@anchrd/colab-sdk 0.1.16 → 0.1.18

package/dist/card-kinds/card-kinds.d.ts

@@ -21,6 +21,7 @@ export declare const CardKindIcon: z.ZodEnum<{
     message: "message";
     user: "user";
     package: "package";
+    target: "target";
     search: "search";
     flag: "flag";
     route: "route";
@@ -28,7 +29,6 @@ export declare const CardKindIcon: z.ZodEnum<{
     "square-check": "square-check";
     "file-text": "file-text";
     bulb: "bulb";
-    target: "target";
     calendar: "calendar";
     star: "star";
     bolt: "bolt";
@@ -68,6 +68,7 @@ export declare const CardKindInput: z.ZodObject<{
         message: "message";
         user: "user";
         package: "package";
+        target: "target";
         search: "search";
         flag: "flag";
         route: "route";
@@ -75,7 +76,6 @@ export declare const CardKindInput: z.ZodObject<{
         "square-check": "square-check";
         "file-text": "file-text";
         bulb: "bulb";
-        target: "target";
         calendar: "calendar";
         star: "star";
         bolt: "bolt";
@@ -113,6 +113,7 @@ export declare const CardKindsInput: z.ZodArray<z.ZodObject<{
         message: "message";
         user: "user";
         package: "package";
+        target: "target";
         search: "search";
         flag: "flag";
         route: "route";
@@ -120,7 +121,6 @@ export declare const CardKindsInput: z.ZodArray<z.ZodObject<{
         "square-check": "square-check";
         "file-text": "file-text";
         bulb: "bulb";
-        target: "target";
         calendar: "calendar";
         star: "star";
         bolt: "bolt";
@@ -183,6 +183,7 @@ export declare const CardKind: z.ZodObject<{
         message: "message";
         user: "user";
         package: "package";
+        target: "target";
         search: "search";
         flag: "flag";
         route: "route";
@@ -190,7 +191,6 @@ export declare const CardKind: z.ZodObject<{
         "square-check": "square-check";
         "file-text": "file-text";
         bulb: "bulb";
-        target: "target";
         calendar: "calendar";
         star: "star";
         bolt: "bolt";
@@ -228,6 +228,7 @@ export declare const TaskKind: z.ZodObject<{
         message: "message";
         user: "user";
         package: "package";
+        target: "target";
         search: "search";
         flag: "flag";
         route: "route";
@@ -235,7 +236,6 @@ export declare const TaskKind: z.ZodObject<{
         "square-check": "square-check";
         "file-text": "file-text";
         bulb: "bulb";
-        target: "target";
         calendar: "calendar";
         star: "star";
         bolt: "bolt";

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,3 +76,15 @@ 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>;
+export type Warning = z.infer<typeof Warning>;

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,23 +10,165 @@ 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"]),
             message: z.string(),
         }),
     ]),
 });
+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", "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/grammar/grammar.d.ts

@@ -39,6 +39,11 @@ export declare const verbs: readonly ["invite", "resend", "disable", "enable", "
 export type Package = (typeof packages)[number];
 export type Resource = keyof typeof resources;
 export type Action = (typeof actions)[number] | (typeof verbs)[number];
+export type ActionAnnotations = {
+    readOnlyHint: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+};
 export type ToolName = {
     package: Package;
     resources: readonly Resource[];
@@ -60,4 +65,5 @@ export declare function parseToolName(name: string): ToolName;
 export declare function toolRoute(name: string): Route;
 export declare function toolPermission(name: string): string;
 export declare function toolEvent(name: string): string;
+export declare function toolAnnotations(name: string): ActionAnnotations | undefined;
 export declare function toolSchemaName(name: string): string;