Skip to content
Knapsack0.4.0
API reference

files-read

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/knapsack/files-read";

Exports

Section titled “Exports”
Kind Export Description
constant maximumReadBytes Maximum UTF-8 byte length of a Files text page.
constant maximumImageBytes Maximum byte length of an image the read tool returns; a host refuses an image it cannot bring within it.
constant imageSniffBytes Bytes needed at the start of a file to recognise a supported image.
constant pathSchema Nonempty file path bounded to 4,096 characters, without null bytes.
constant readInputSchema Canonical bounded Files read request and result, shared with display consumers.
constant readImageMimeType The image types a Files read can return.
constant readImageOutputSchema Whole png, jpeg, gif or webp file, at most maximumImageBytes, as base64.
constant readTextOutputSchema Bounded text page, continuation offset and optional hosted file identity.
constant readImageCaptionSchema What guest code and MCP callers see: an image never travels as base64 in the value. It is pushed through the execution’s image collector and the value is only this caption.
constant readGuestOutputSchema Text page or image caption returned to guest code.
constant readOutputSchema A bounded text page or a whole image; images are only read from offset 0.
function sniffImageMimeType() Identify png, jpeg, gif or webp by their full magic bytes; undefined means not a supported image.
function imageTooLargeMessage() Message for an image above a host’s read cap, shared by every Files host.
function boundedTextSchema() Validate text against a minimum character length and the Files UTF-8 byte limit.
function imageReadResult() Build the image read result for a recognised image’s complete bytes.

maximumReadBytesconstant

Section titled “maximumReadBytes”
Signature
const maximumReadBytes: number;

Maximum UTF-8 byte length of a Files text page.

maximumImageBytesconstant

Section titled “maximumImageBytes”
Signature
const maximumImageBytes: number;

Maximum byte length of an image the read tool returns; a host refuses an image it cannot bring within it.

imageSniffBytesconstant

Section titled “imageSniffBytes”
Signature
const imageSniffBytes: 12 = 12;

Bytes needed at the start of a file to recognise a supported image.

pathSchemaconstant

Section titled “pathSchema”
Signature
const pathSchema: ZodLazy<ZodString>;

Nonempty file path bounded to 4,096 characters, without null bytes.

readInputSchemaconstant

Section titled “readInputSchema”
Signature
const readInputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodLazy<ZodString>;
      offset: ZodDefault<ZodNumber>;
      limit: ZodDefault<ZodNumber>;
    },
    $strict
  >
>;

Canonical bounded Files read request and result, shared with display consumers.

readImageMimeTypeconstant

Section titled “readImageMimeType”
Signature
const readImageMimeType: ZodEnum<{
  image/png: "image/png";
  image/jpeg: "image/jpeg";
  image/gif: "image/gif";
  image/webp: "image/webp";
}>;

The image types a Files read can return.

readImageOutputSchemaconstant

Section titled “readImageOutputSchema”
Signature
const readImageOutputSchema: ZodLazy<ZodObject<{
  path: ZodLazy<ZodString>;
  image: ZodObject<{
     mimeType: ZodEnum<{
        image/png: "image/png";
        image/jpeg: "image/jpeg";
        image/gif: "image/gif";
        image/webp: "image/webp";
     }>;
     data: ZodBase64;
     bytes: ZodNumber;
  }, $strict>;
  file: ZodExactOptional<ZodLazy<ZodObject<{
     computerId: ZodString;
     path: ZodLazy<ZodString>;
  }, $strict>>>;
}, $strict>>;

Whole png, jpeg, gif or webp file, at most maximumImageBytes, as base64.

readTextOutputSchemaconstant

Section titled “readTextOutputSchema”
Signature
const readTextOutputSchema: ZodLazy<
  ZodObject<
    {
      path: ZodLazy<ZodString>;
      content: ZodString;
      offset: ZodNumber;
      nextOffset: ZodNullable<ZodNumber>;
      truncated: ZodBoolean;
      file: ZodExactOptional<
        ZodLazy<
          ZodObject<
            {
              computerId: ZodString;
              path: ZodLazy<ZodString>;
            },
            $strict
          >
        >
      >;
    },
    $strict
  >
>;

Bounded text page, continuation offset and optional hosted file identity.

readImageCaptionSchemaconstant

Section titled “readImageCaptionSchema”
Signature
const readImageCaptionSchema: ZodLazy<ZodObject<{
  path: ZodLazy<ZodString>;
  image: ZodObject<{
     ref: ZodString;
     mimeType: ZodEnum<{
        image/png: "image/png";
        image/jpeg: "image/jpeg";
        image/gif: "image/gif";
        image/webp: "image/webp";
     }>;
     bytes: ZodNumber;
  }, $strict>;
}, $strict>>;

What guest code and MCP callers see: an image never travels as base64 in the value. It is pushed through the execution’s image collector and the value is only this caption.

readGuestOutputSchemaconstant

Section titled “readGuestOutputSchema”
Signature
const readGuestOutputSchema: ZodLazy<ZodUnion<readonly [ZodLazy<ZodObject<{
  path: ZodLazy<ZodString>;
  content: ZodString;
  offset: ZodNumber;
  nextOffset: ZodNullable<ZodNumber>;
  truncated: ZodBoolean;
  file: ZodExactOptional<ZodLazy<ZodObject<{
     computerId: ZodString;
     path: ZodLazy<...>;
  }, $strict>>>;
}, $strict>>, ZodLazy<ZodObject<{
  path: ZodLazy<ZodString>;
  image: ZodObject<{
     ref: ZodString;
     mimeType: ZodEnum<{
        image/png: "image/png";
        image/jpeg: "image/jpeg";
        image/gif: "image/gif";
        image/webp: "image/webp";
     }>;
     bytes: ZodNumber;
  }, $strict>;
}, $strict>>]>>;

Text page or image caption returned to guest code.

readOutputSchemaconstant

Section titled “readOutputSchema”
Signature
const readOutputSchema: ZodLazy<ZodUnion<readonly [ZodLazy<ZodObject<{
  path: ZodLazy<ZodString>;
  content: ZodString;
  offset: ZodNumber;
  nextOffset: ZodNullable<ZodNumber>;
  truncated: ZodBoolean;
  file: ZodExactOptional<ZodLazy<ZodObject<{
     computerId: ZodString;
     path: ZodLazy<...>;
  }, $strict>>>;
}, $strict>>, ZodLazy<ZodObject<{
  path: ZodLazy<ZodString>;
  image: ZodObject<{
     mimeType: ZodEnum<{
        image/png: "image/png";
        image/jpeg: "image/jpeg";
        image/gif: "image/gif";
        image/webp: "image/webp";
     }>;
     data: ZodBase64;
     bytes: ZodNumber;
  }, $strict>;
  file: ZodExactOptional<ZodLazy<ZodObject<{
     computerId: ZodString;
     path: ZodLazy<...>;
  }, $strict>>>;
}, $strict>>]>>;

A bounded text page or a whole image; images are only read from offset 0.

sniffImageMimeType()function

Section titled “sniffImageMimeType()”
Signature
function sniffImageMimeType(head): string | undefined;

Identify png, jpeg, gif or webp by their full magic bytes; undefined means not a supported image.

Parameters

Section titled “Parameters”
Parameter Type
head Uint8Array

Returns

Section titled “Returns”

string | undefined

imageTooLargeMessage()function

Section titled “imageTooLargeMessage()”
Signature
function imageTooLargeMessage(path, size, limit): string;

Message for an image above a host’s read cap, shared by every Files host.

Parameters

Section titled “Parameters”
Parameter Type
path string
size number
limit number

Returns

Section titled “Returns”

string

boundedTextSchema()function

Section titled “boundedTextSchema()”
Signature
function boundedTextSchema(minimumLength?): ZodString;

Validate text against a minimum character length and the Files UTF-8 byte limit.

Parameters

Section titled “Parameters”
Parameter Type Default value
minimumLength number 0

Returns

Section titled “Returns”

ZodString

imageReadResult()function

Section titled “imageReadResult()”
Signature
function imageReadResult(path, mimeType, bytes): object;

Build the image read result for a recognised image’s complete bytes.

Parameters

Section titled “Parameters”
Parameter Type
path string
mimeType string
bytes Uint8Array

Returns

Section titled “Returns”

object

Name Type Default value
path string pathSchema
image object -
image.mimeType "image/png" | "image/jpeg" | "image/gif" | "image/webp" readImageMimeType
image.data string -
image.bytes number -
file? object -
file.computerId string -
file.path string -