@anchrd/colab-sdk 0.1.17 → 0.1.19

package/dist/documents/documents.d.ts

@@ -8,6 +8,8 @@ export declare const DocumentCreateInput: z.ZodObject<{
 export type DocumentCreateInput = z.infer<typeof DocumentCreateInput>;
 export declare const DocumentGetInput: z.ZodObject<{
     documentId: z.ZodTemplateLiteral<`node_${string}`>;
+    cursor: z.ZodOptional<z.ZodString>;
+    known: z.ZodOptional<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>;
 }, z.core.$strict>;
 export type DocumentGetInput = z.infer<typeof DocumentGetInput>;
 export declare const DocumentUpdateInput: z.ZodObject<{
@@ -49,13 +51,68 @@ export declare const DocumentDetail: z.ZodObject<{
     appHandle: z.ZodNullable<z.ZodString>;
     rev: z.ZodNumber;
     archivedAt: z.ZodNullable<z.ZodISODateTime>;
-    instructions: z.ZodOptional<z.ZodObject<{
+    instructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         chain: z.ZodArray<z.ZodObject<{
             path: z.ZodString;
             status: z.ZodNullable<z.ZodString>;
             markdown: z.ZodString;
         }, z.core.$strip>>;
         hint: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
+        digest: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        digest: z.ZodString;
+        known: z.ZodLiteral<true>;
+    }, z.core.$strip>]>>;
 }, z.core.$strip>;
 export type DocumentDetail = z.infer<typeof DocumentDetail>;
+export declare const DocumentExcerpt: z.ZodObject<{
+    secret: z.ZodOptional<z.ZodLiteral<true>>;
+    locked: z.ZodOptional<z.ZodBoolean>;
+    documentId: z.ZodTemplateLiteral<`node_${string}`>;
+    name: z.ZodString;
+    hidden: z.ZodBoolean;
+    parentId: z.ZodNullable<z.ZodTemplateLiteral<`node_${string}`>>;
+    path: z.ZodObject<{
+        section: z.ZodEnum<{
+            users: "users";
+            own: "own";
+            shared: "shared";
+        }>;
+        items: z.ZodArray<z.ZodObject<{
+            nodeId: z.ZodTemplateLiteral<`node_${string}`>;
+            name: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    content: z.ZodString;
+    version: z.ZodNullable<z.ZodNumber>;
+    savedAt: z.ZodNullable<z.ZodISODateTime>;
+    savedBy: z.ZodNullable<z.ZodObject<{
+        userId: z.ZodString;
+        name: z.ZodNullable<z.ZodString>;
+        kind: z.ZodNullable<z.ZodEnum<{
+            machine: "machine";
+            human: "human";
+        }>>;
+    }, z.core.$strip>>;
+    appHandle: z.ZodNullable<z.ZodString>;
+    archivedAt: z.ZodNullable<z.ZodISODateTime>;
+    instructions: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+        chain: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            status: z.ZodNullable<z.ZodString>;
+            markdown: z.ZodString;
+        }, z.core.$strip>>;
+        hint: z.ZodOptional<z.ZodString>;
+        digest: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        digest: z.ZodString;
+        known: z.ZodLiteral<true>;
+    }, z.core.$strip>]>>;
+    excerpt: z.ZodObject<{
+        offset: z.ZodNumber;
+        length: z.ZodNumber;
+        nextCursor: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    rev: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type DocumentExcerpt = z.infer<typeof DocumentExcerpt>;

package/dist/documents/documents.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { Instructions } from "../instructions/instructions.js";
+import { ExcerptCursor, TextExcerpt } from "../excerpt/excerpt.js";
+import { InstructionsRead, Known } from "../instructions/instructions.js";
 import { NodeId, NodePath, NodePerson, SecretFields } from "../nodes/nodes.js";
 import { IdempotencyKey, Rev } from "../primitives/primitives.js";
 // Documents (#39, Nodes › Dokument, E36, E59): the inputs of `intelligence_document_create`, `_get`
@@ -22,7 +23,11 @@ export const DocumentCreateInput = z.strictObject({
     content: Content,
     idempotencyKey: IdempotencyKey,
 });
-export const DocumentGetInput = z.strictObject({ documentId: DocumentId });
+export const DocumentGetInput = z.strictObject({
+    documentId: DocumentId,
+    cursor: ExcerptCursor.optional(),
+    known: Known.optional(),
+});
 export const DocumentUpdateInput = z.strictObject({
     documentId: DocumentId,
     content: Content,
@@ -52,8 +57,17 @@ export const DocumentDetail = z.object({
     // The state the next save sends (E70).
     rev: z.number().int(),
     archivedAt: z.iso.datetime().nullable(),
-    // Over MCP only, the INSTRUCTIONS of the document's folder (#39).
-    instructions: Instructions.optional(),
+    // Over MCP only, the INSTRUCTIONS of the document's folder (#39); not again with a cursor (#674),
+    // the reference when known (E123, #677).
+    instructions: InstructionsRead.optional(),
     // A secret document (#357): `content` is empty while it is `locked` for this caller.
     ...SecretFields,
 });
+// One excerpt of a document over MCP whose text is above `excerptChars` (E127, #674): `content` is
+// this part, `excerpt` where it stands and the cursor of the next. ⚠️ `rev` comes with the last
+// excerpt only: a save sends the whole text, and a `rev` beside a part of it would let a save of
+// that part cut the rest away without a conflict.
+export const DocumentExcerpt = DocumentDetail.extend({
+    excerpt: TextExcerpt,
+    rev: z.number().int().optional(),
+});

package/dist/error/error.d.ts

@@ -11,18 +11,60 @@ export type ErrorCode = z.infer<typeof ErrorCode>;
 export declare const ErrorIssue: z.ZodObject<{
     path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
     message: z.ZodString;
+    expected: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strict>;
 export type ErrorIssue = z.infer<typeof ErrorIssue>;
+export declare const ErrorCurrent: z.ZodObject<{
+    taskId: z.ZodOptional<z.ZodTemplateLiteral<`node_${string}`>>;
+    boardId: z.ZodOptional<z.ZodTemplateLiteral<`node_${string}`>>;
+    documentId: z.ZodOptional<z.ZodTemplateLiteral<`node_${string}`>>;
+    tableId: z.ZodOptional<z.ZodTemplateLiteral<`node_${string}`>>;
+    fileId: z.ZodOptional<z.ZodTemplateLiteral<`node_${string}`>>;
+    gadgetId: z.ZodOptional<z.ZodTemplateLiteral<`node_${string}`>>;
+    nodeId: z.ZodOptional<z.ZodTemplateLiteral<`node_${string}`>>;
+    machineId: z.ZodOptional<z.ZodTemplateLiteral<`user_${string}`>>;
+    rev: z.ZodNumber;
+    savedBy: z.ZodOptional<z.ZodObject<{
+        userId: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strict>>;
+    savedAt: z.ZodISODateTime;
+    values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export type ErrorCurrent = z.infer<typeof ErrorCurrent>;
 export declare const ErrorResponse: z.ZodObject<{
     error: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        code: z.ZodEnum<{
-            invalid: "invalid";
-            conflict: "conflict";
-        }>;
+        code: z.ZodLiteral<"invalid">;
+        message: z.ZodString;
+        issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+            message: z.ZodString;
+            expected: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>, z.ZodObject<{
+        code: z.ZodLiteral<"conflict">;
         message: z.ZodString;
         issues: z.ZodOptional<z.ZodArray<z.ZodObject<{
             path: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
             message: z.ZodString;
+            expected: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strict>>>;
+        current: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            taskId: z.ZodOptional<z.ZodTemplateLiteral<`node_${string}`>>;
+            boardId: z.ZodOptional<z.ZodTemplateLiteral<`node_${string}`>>;
+            documentId: z.ZodOptional<z.ZodTemplateLiteral<`node_${string}`>>;
+            tableId: z.ZodOptional<z.ZodTemplateLiteral<`node_${string}`>>;
+            fileId: z.ZodOptional<z.ZodTemplateLiteral<`node_${string}`>>;
+            gadgetId: z.ZodOptional<z.ZodTemplateLiteral<`node_${string}`>>;
+            nodeId: z.ZodOptional<z.ZodTemplateLiteral<`node_${string}`>>;
+            machineId: z.ZodOptional<z.ZodTemplateLiteral<`user_${string}`>>;
+            rev: z.ZodNumber;
+            savedBy: z.ZodOptional<z.ZodObject<{
+                userId: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strict>>;
+            savedAt: z.ZodISODateTime;
+            values: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strict>>>;
     }, z.core.$strict>, z.ZodObject<{
         code: z.ZodEnum<{
@@ -34,9 +76,14 @@ export declare const ErrorResponse: z.ZodObject<{
     }, z.core.$strict>], "code">;
 }, z.core.$strict>;
 export type ErrorResponse = z.infer<typeof ErrorResponse>;
+export declare function invalidInput(schema: z.ZodType, error: z.ZodError): ErrorResponse;
 export declare const Warning: z.ZodObject<{
     code: z.ZodEnum<{
         followup_failed: "followup_failed";
+        test_failed: "test_failed";
+        mail_failed: "mail_failed";
+        unused: "unused";
+        too_long: "too_long";
     }>;
     message: z.ZodString;
 }, z.core.$strip>;

package/dist/error/error.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { idSchema } from "../ids/ids.js";
 // The one error shape of API and MCP (E68, E70). Missing rights answer `not_found`, never a code of
 // their own: a caller must not learn that something exists which it may not see.
 export const errorCodes = [
@@ -9,19 +10,50 @@ export const errorCodes = [
     "unavailable",
 ];
 export const ErrorCode = z.enum(errorCodes);
-// One entry per rejected field: where, and a sentence why.
+// One entry per rejected field: where, and a sentence why. `expected` only where the tool's schema
+// refused the input (#678): the form that field takes, the JSON Schema `tools/list` shows for it,
+// derived from the schema and never written by hand, so the AI's next try needs no guess.
 export const ErrorIssue = z.strictObject({
     path: z.array(z.union([z.string(), z.number()])),
     message: z.string(),
+    expected: z.record(z.string(), z.unknown()).optional(),
+});
+const NodeRef = idSchema("node");
+// What stands now where a save met a newer one (E128, #678), one entry per stale node: its `rev`,
+// who saved it last (the author of its current version; absent for a kind without versions) and
+// when, and under `values` today's value of exactly each field the call wanted to change, under the
+// field's name in the call. Never a document's text: there the answer is to read it again. The id
+// under its resource's name, as in `changed`; an Operator's under `machineId` (E135, #739). Nothing
+// is merged and nothing overwritten (E70).
+export const ErrorCurrent = z.strictObject({
+    taskId: NodeRef.optional(),
+    boardId: NodeRef.optional(),
+    documentId: NodeRef.optional(),
+    tableId: NodeRef.optional(),
+    fileId: NodeRef.optional(),
+    gadgetId: NodeRef.optional(),
+    nodeId: NodeRef.optional(),
+    machineId: idSchema("user").optional(),
+    rev: z.number().int(),
+    savedBy: z.strictObject({ userId: z.string(), name: z.string() }).optional(),
+    savedAt: z.iso.datetime(),
+    values: z.record(z.string(), z.unknown()).optional(),
 });
 // `issues` exists only next to `invalid` and `conflict` (a change of many entries names each stale
-// one, #630, #625); on every other code a strict object rejects it.
+// one, #630, #625), `current` only next to `conflict` (E128); on every other code a strict object
+// rejects them.
 export const ErrorResponse = z.strictObject({
     error: z.discriminatedUnion("code", [
         z.strictObject({
-            code: z.enum(["invalid", "conflict"]),
+            code: z.literal("invalid"),
+            message: z.string(),
+            issues: z.array(ErrorIssue).optional(),
+        }),
+        z.strictObject({
+            code: z.literal("conflict"),
             message: z.string(),
             issues: z.array(ErrorIssue).optional(),
+            current: z.array(ErrorCurrent).optional(),
         }),
         z.strictObject({
             code: ErrorCode.exclude(["invalid", "conflict"]),
@@ -29,11 +61,114 @@ export const ErrorResponse = z.strictObject({
         }),
     ]),
 });
-// What a write answers beside its result when it went through and something stands out (E126): a
-// hint for the AI, never a refusal; a fixed code and a sentence. #623 brings the first code, #672
-// takes the field to every write over `/mcp` and adds its own.
-// - `followup_failed`: the change is saved, and a step after the save failed and was reported.
+const isSchema = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+// A `$ref` of the converter (`#`, `#/definitions/…`, `#/$defs/…`), resolved against the root.
+function resolved(node, root) {
+    const ref = node.$ref;
+    if (typeof ref !== "string" || !ref.startsWith("#"))
+        return node;
+    let found = root;
+    for (const part of ref.slice(1).split("/").filter(Boolean)) {
+        found = isSchema(found) ? found[part.replaceAll("~1", "/").replaceAll("~0", "~")] : undefined;
+    }
+    return isSchema(found) ? found : node;
+}
+// The alternatives a value may take at this place: a nullable or optional field is an `anyOf`.
+function branches(node, root) {
+    const own = resolved(node, root);
+    const alternatives = [own.anyOf, own.oneOf, own.allOf].find(Array.isArray);
+    if (!alternatives)
+        return [own];
+    return alternatives.filter(isSchema).flatMap((branch) => branches(branch, root));
+}
+function child(node, part, root) {
+    for (const branch of branches(node, root)) {
+        if (typeof part === "number") {
+            if (Array.isArray(branch.items) && isSchema(branch.items[part]))
+                return branch.items[part];
+            if (isSchema(branch.items))
+                return branch.items;
+            if (Array.isArray(branch.prefixItems) && isSchema(branch.prefixItems[part])) {
+                return branch.prefixItems[part];
+            }
+            continue;
+        }
+        if (isSchema(branch.properties) && isSchema(branch.properties[part])) {
+            return branch.properties[part];
+        }
+        if (isSchema(branch.additionalProperties))
+            return branch.additionalProperties;
+    }
+    return undefined;
+}
+// The JSON Schema at a path of the input, as `tools/list` shows it (#678).
+function schemaAt(root, path) {
+    let node = root;
+    for (const part of path) {
+        node = node && child(node, part, root);
+    }
+    if (!node)
+        return undefined;
+    const { $schema: _schema, ...shown } = resolved(node, root);
+    return shown;
+}
+// The fields an object at this place takes, to name beside a key it does not know.
+function fieldsAt(root, path) {
+    const node = schemaAt(root, path);
+    if (!node)
+        return [];
+    return [
+        ...new Set(branches(node, root).flatMap((branch) => isSchema(branch.properties) ? Object.keys(branch.properties) : [])),
+    ];
+}
+// The options `@modelcontextprotocol/sdk` converts a tool's input with for `tools/list`.
+function jsonSchemaOf(schema) {
+    try {
+        return z.toJSONSchema(schema, { target: "draft-7", io: "input" });
+    }
+    catch {
+        return null;
+    }
+}
+const dotted = (path) => path.length === 0 ? "its top level" : path.map(String).join(".");
+// `invalid` for an input its tool's schema refused (#678), at `/api` and `/mcp` alike: each issue
+// with the field's path, Zod's sentence and the form the field expects; a key the schema does not
+// know names the fields that are there instead.
+export function invalidInput(schema, error) {
+    const root = jsonSchemaOf(schema);
+    const issues = error.issues.map((issue) => {
+        const path = issue.path.map((part) => (typeof part === "symbol" ? String(part) : part));
+        if (issue.code === "unrecognized_keys") {
+            const fields = root ? fieldsAt(root, path) : [];
+            return {
+                path,
+                message: fields.length > 0
+                    ? `${issue.message}; the fields here are ${fields.join(", ")}.`
+                    : issue.message,
+            };
+        }
+        const expected = root ? schemaAt(root, path) : undefined;
+        return { path, message: issue.message, ...(expected && { expected }) };
+    });
+    const places = [...new Set(issues.map((issue) => dotted(issue.path)))];
+    return {
+        error: {
+            code: "invalid",
+            message: `The input does not match the schema at ${places.join(", ")}: issues name what each expects. Nothing was done.`,
+            issues,
+        },
+    };
+}
+// What a write answers beside what it changed when it went through and something stands out (E126,
+// `Written`): a hint for the AI, never a refusal; a fixed code and a sentence.
+// - `followup_failed`: the change is saved, and a step after the save failed and was reported
+//   (#623, #725); the answer holds only what the save itself knows.
+// - `test_failed`: a credential or a connection was changed and then failed its test, with the
+//   provider's sentence (#743); the change stands.
+// - `mail_failed`: the mail of an invitation was not accepted (#743); the invitation stands.
+// - `unused`: a credential that no Operator uses yet (#676).
+// - `too_long`: an INSTRUCTIONS was saved with more words than an AI follows reliably (E67, #675).
 export const Warning = z.object({
-    code: z.enum(["followup_failed"]),
+    code: z.enum(["followup_failed", "test_failed", "mail_failed", "unused", "too_long"]),
     message: z.string(),
 });

package/dist/events/events.d.ts

@@ -13,6 +13,11 @@ export declare const ActorKind: z.ZodEnum<{
     human: "human";
 }>;
 export type ActorKind = z.infer<typeof ActorKind>;
+export declare const EventSource: z.ZodEnum<{
+    mcp: "mcp";
+    api: "api";
+}>;
+export type EventSource = z.infer<typeof EventSource>;
 export declare const EventListInput: z.ZodObject<{
     actorId: z.ZodOptional<z.ZodUnion<readonly [z.ZodTemplateLiteral<`user_${string}`>, z.ZodTemplateLiteral<`service_${string}`>]>>;
     actorKind: z.ZodOptional<z.ZodEnum<{
@@ -62,7 +67,12 @@ export declare const Event: z.ZodObject<{
             human: "human";
         }>>;
         image: z.ZodNullable<z.ZodString>;
+        appHandle: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>>;
+    source: z.ZodNullable<z.ZodEnum<{
+        mcp: "mcp";
+        api: "api";
+    }>>;
     failed: z.ZodBoolean;
     code: z.ZodNullable<z.ZodString>;
     ip: z.ZodNullable<z.ZodString>;
@@ -93,7 +103,12 @@ export declare const EventList: z.ZodObject<{
                 human: "human";
             }>>;
             image: z.ZodNullable<z.ZodString>;
+            appHandle: z.ZodNullable<z.ZodString>;
         }, z.core.$strip>>;
+        source: z.ZodNullable<z.ZodEnum<{
+            mcp: "mcp";
+            api: "api";
+        }>>;
         failed: z.ZodBoolean;
         code: z.ZodNullable<z.ZodString>;
         ip: z.ZodNullable<z.ZodString>;

package/dist/events/events.js

@@ -13,6 +13,8 @@ export const EventKind = z.enum(["change", "signin", "app", "connector"]);
 // Who did it: a person or a machine, or an outside service that declared its own interfaces under
 // `/auth/service` (#178).
 export const ActorKind = z.enum([...UserKind.options, "service"]);
+// The doors of `ToolSource`, as a row of the protocol stores them (#738).
+export const EventSource = z.enum(["api", "mcp"]);
 export const EventListInput = z.strictObject({
     // Who did it: a user, or a service for what it declared itself (#178).
     actorId: z.union([UserId, ServiceId]).optional(),
@@ -51,14 +53,22 @@ export const Event = z.object({
     // `access.directory.resolve` gives it: null for a machine, a service and a person without one
     // (#140). ⚠️ `userId` also carries a `service_…` id when `kind` is `service` (#178): the field
     // keeps its name so the answer's shape stays as the UI reads it.
+    // `appHandle` is the app a person's AI came through over `/mcp` (#738, E134), by its registered
+    // name like a chat's sender (E49), the stored client id where `access` no longer knows the client;
+    // null from the UI, for a machine's own token and for every row from before.
     actor: z
         .object({
         userId: z.string(),
         name: z.string().nullable(),
         kind: ActorKind.nullable(),
         image: z.string().nullable(),
+        appHandle: z.string().nullable(),
     })
         .nullable(),
+    // The door the event came through (#738, E134): `api` for `/api` and `/auth` (the UI, a sign-in, a
+    // service's own door), `mcp` for `/mcp`; null for what Colab does itself in a job and for every row
+    // from before.
+    source: EventSource.nullable(),
     failed: z.boolean(),
     // The refusal's code, only next to `failed`.
     code: z.string().nullable(),

package/dist/excerpt/excerpt.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export declare const excerptChars = 20000;
+export declare const ExcerptCursor: z.ZodString;
+export declare const TextExcerpt: z.ZodObject<{
+    offset: z.ZodNumber;
+    length: z.ZodNumber;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type TextExcerpt = z.infer<typeof TextExcerpt>;
+export declare const RowsExcerpt: z.ZodObject<{
+    firstRow: z.ZodNumber;
+    lastRow: z.ZodNumber;
+    rowCount: z.ZodNumber;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type RowsExcerpt = z.infer<typeof RowsExcerpt>;

package/dist/excerpt/excerpt.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+// Large texts over `/mcp` (E127, #674): the text of a document, a file or a table comes in excerpts of
+// at most `excerptChars` characters, each with where it stands in the whole and a `cursor` for the
+// next one, until everything is read. A text that fits comes whole, without `excerpt`. Nothing is cut
+// at the end of an answer: a result cut off in the middle of its JSON is useless. Claude Code warns at
+// 10,000 tokens of tool output and puts a text over 50,000 characters into a file the AI must read
+// again; 20,000 characters are about 5,000 tokens.
+export const excerptChars = 20_000;
+// One cursor for every kind: the next excerpt of the same text, refused once the node has changed.
+export const ExcerptCursor = z
+    .string()
+    .min(1)
+    .max(500)
+    .describe("The nextCursor of the previous excerpt, unchanged, for the next part of the same text. If the node was saved in between, the answer is conflict: read it again without cursor.");
+// Where an excerpt of a document's Markdown or a file's text stands, in characters.
+export const TextExcerpt = z.object({
+    // The characters of the whole text before this excerpt.
+    offset: z.number().int(),
+    // The characters of the whole text.
+    length: z.number().int(),
+    // Null with the last excerpt.
+    nextCursor: z.string().nullable(),
+});
+// Where an excerpt of a table stands: whole rows, never a row cut in two; the CSV's header line comes
+// with the first excerpt only, so the excerpts joined are the table's CSV.
+export const RowsExcerpt = z.object({
+    // The positions of the first and the last row in this excerpt, 1 for the first data row.
+    firstRow: z.number().int(),
+    lastRow: z.number().int(),
+    // The data rows of the whole table.
+    rowCount: z.number().int(),
+    nextCursor: z.string().nullable(),
+});

package/dist/files/files.d.ts

@@ -27,6 +27,7 @@ export declare const FileUpdateInput: z.ZodObject<{
 export type FileUpdateInput = z.infer<typeof FileUpdateInput>;
 export declare const FileGetInput: z.ZodObject<{
     fileId: z.ZodTemplateLiteral<`node_${string}`>;
+    cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type FileGetInput = z.infer<typeof FileGetInput>;
 export declare const UploadTicket: z.ZodObject<{
@@ -71,6 +72,11 @@ export declare const FileDetail: z.ZodObject<{
         reading: "reading";
         none: "none";
     }>;
+    excerpt: z.ZodOptional<z.ZodObject<{
+        offset: z.ZodNumber;
+        length: z.ZodNumber;
+        nextCursor: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
     contentUrl: z.ZodURL;
     sourceUrl: z.ZodOptional<z.ZodString>;
     fetchedAt: z.ZodOptional<z.ZodISODateTime>;

package/dist/files/files.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { ExcerptCursor, TextExcerpt } from "../excerpt/excerpt.js";
 import { idSchema } from "../ids/ids.js";
 import { NodeId } from "../nodes/nodes.js";
 import { IdempotencyKey, Rev } from "../primitives/primitives.js";
@@ -142,7 +143,7 @@ export const FileUpdateInput = z.strictObject({
     size: Size,
     rev: Rev,
 });
-export const FileGetInput = z.strictObject({ fileId: FileId });
+export const FileGetInput = z.strictObject({ fileId: FileId, cursor: ExcerptCursor.optional() });
 // What `_create` and `_update` answer: the door, the ticket and the whole command. ⚠️ `ticket` is a
 // credential, and it is in this answer on purpose: it opens ONE upload for ONE person for fifteen
 // minutes. It appears nowhere else, never in an error and never in a log.
@@ -173,8 +174,11 @@ export const FileDetail = z.object({
     // The node's revision, to send with the next `_update`.
     rev: z.number().int(),
     // The text read from the current version for search and AI; null unless `textState` is `done`.
+    // Over MCP a text above `excerptChars` comes in excerpts (E127, #674): then this is one of them.
     text: z.string().nullable(),
     textState: FileTextState,
+    // Over MCP only, when the text comes in excerpts: where this one stands, and the cursor of the next.
+    excerpt: TextExcerpt.optional(),
     // Where the bytes are read, with a session or a token and the right to read the file.
     contentUrl: z.url(),
     // Only on a version Colab fetched from an address (#556): the address asked for and when.

package/dist/instructions/instructions.d.ts

@@ -17,3 +17,39 @@ export declare const Instructions: z.ZodObject<{
     hint: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type Instructions = z.infer<typeof Instructions>;
+export declare const Digest: z.ZodString;
+export type Digest = z.infer<typeof Digest>;
+export declare const maxKnown = 100;
+export declare const Known: z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>;
+export declare const KnownText: z.ZodObject<{
+    digest: z.ZodString;
+    known: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export type KnownText = z.infer<typeof KnownText>;
+export declare function isKnownText(value: object): value is KnownText;
+export declare const InstructionText: z.ZodObject<{
+    digest: z.ZodString;
+    markdown: z.ZodString;
+}, z.core.$strip>;
+export type InstructionText = z.infer<typeof InstructionText>;
+export declare const InstructionRead: z.ZodNullable<z.ZodUnion<readonly [z.ZodObject<{
+    digest: z.ZodString;
+    markdown: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    digest: z.ZodString;
+    known: z.ZodLiteral<true>;
+}, z.core.$strip>]>>;
+export type InstructionRead = z.infer<typeof InstructionRead>;
+export declare const InstructionsRead: z.ZodUnion<readonly [z.ZodObject<{
+    chain: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        status: z.ZodNullable<z.ZodString>;
+        markdown: z.ZodString;
+    }, z.core.$strip>>;
+    hint: z.ZodOptional<z.ZodString>;
+    digest: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    digest: z.ZodString;
+    known: z.ZodLiteral<true>;
+}, z.core.$strip>]>;
+export type InstructionsRead = z.infer<typeof InstructionsRead>;

package/dist/instructions/instructions.js

@@ -33,3 +33,32 @@ export const Instructions = z.object({
     // Only when the whole chain holds more than 3,000 words (E67): one English sentence.
     hint: z.string().optional(),
 });
+// E123 (#677): a board's instruction and the INSTRUCTIONS come along over MCP only when the AI does
+// not hold them in this version yet. Their version is `digest`: the first 16 hex characters of the
+// SHA-256 of what the answer would carry, so it names the text as the caller gets it. The same
+// text has the same digest wherever it stands; a changed text, status or path, or another cut of a
+// machine's part, has a new one. ⚠️ Colab keeps nothing of what an AI got, because a client may
+// compact its context or start anew: the AI sends what it holds under `known`, and without it every
+// text comes whole. The system message of an Operator's run (E111) asks without `known`.
+export const Digest = z
+    .string()
+    .regex(/^[0-9a-f]{16}$/)
+    .describe("The digest of an instruction or of INSTRUCTIONS, as an earlier read named it.");
+// The most digests one read takes: one per board and folder an AI works in, with room to spare.
+export const maxKnown = 100;
+// Over REST one comma-separated value (`?known=…,…`): a query string carries text. No lower bound:
+// an empty list holds nothing and means the same as leaving it out.
+export const Known = z
+    .preprocess((value) => (typeof value === "string" ? value.split(",") : value), z.array(Digest).max(maxKnown))
+    .describe("The digests of the instruction and INSTRUCTIONS whose text you still hold from an earlier read, as that read named them under digest. Where one still matches, the answer carries only { digest, known: true } in place of the text; a changed text comes whole with its new digest. Leave out what is no longer in your context. Leaving it out gives every text whole.");
+// What stands in place of the text when the caller sent its digest under `known`.
+export const KnownText = z.object({ digest: Digest, known: z.literal(true) });
+export function isKnownText(value) {
+    return "known" in value;
+}
+// A board's instruction over MCP (E87, #354): its Markdown with its digest.
+export const InstructionText = z.object({ digest: Digest, markdown: z.string() });
+// The instruction as a read over MCP answers it: the text, the reference, or null without one.
+export const InstructionRead = z.union([InstructionText, KnownText]).nullable();
+// The chain as a read over MCP answers it: whole with its digest, or the reference.
+export const InstructionsRead = z.union([Instructions.extend({ digest: Digest }), KnownText]);