@namzu/sdk 31.1.0 → 33.0.0

package/dist/store/attachment/index.js

@@ -1,3 +1,6 @@
+/** One minute is long enough for remote stores without letting a run wedge forever. */
+export const DEFAULT_ATTACHMENT_RESOLVE_TIMEOUT_MS = 60_000;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
 /** A reference nothing could resolve. */
 export class AttachmentNotFoundError extends Error {
     details;
@@ -25,6 +28,15 @@ export class AttachmentMediaTypeMismatchError extends Error {
         this.details = details;
     }
 }
+/** A store did not settle the materialization phase within its declared bound. */
+export class AttachmentResolutionTimeoutError extends Error {
+    details;
+    constructor(details) {
+        super(`Stored attachment resolution timed out after ${details.timeoutMs}ms.`);
+        this.name = 'AttachmentResolutionTimeoutError';
+        this.details = details;
+    }
+}
 export const isStoredAttachment = (attachment) => attachment.type === 'stored';
 /**
  * Turn a stored attachment into an inline one, or refuse.
@@ -36,10 +48,14 @@ export const isStoredAttachment = (attachment) => attachment.type === 'stored';
  * branches returns the message unchanged.
  */
 export async function resolveAttachment(attachment, store, options = {}) {
-    const { signal } = options;
-    signal?.throwIfAborted();
+    options.signal?.throwIfAborted();
+    const timeoutMs = resolveAttachmentTimeoutMs(options.timeoutMs);
     if (!isStoredAttachment(attachment))
         return attachment;
+    return await withAttachmentDeadline(options.signal, timeoutMs, async (signal) => resolveAttachmentWithSignal(attachment, store, signal));
+}
+async function resolveAttachmentWithSignal(attachment, store, signal) {
+    signal?.throwIfAborted();
     if (!store)
         throw new NoAttachmentStoreError({ ref: attachment.ref });
     const bytes = await awaitStoreRead(signal, () => signal ? store.get(attachment.ref, { signal }) : store.get(attachment.ref));
@@ -81,6 +97,7 @@ export async function resolveAttachment(attachment, store, options = {}) {
  */
 export async function resolveAttachments(messages, store, options = {}) {
     options.signal?.throwIfAborted();
+    const timeoutMs = resolveAttachmentTimeoutMs(options.timeoutMs);
     // `Message` rather than a structural constraint: only some members of
     // the union carry `attachments`, and a structural bound over a union
     // like that is not assignable in either direction. Naming the real type
@@ -88,15 +105,45 @@ export async function resolveAttachments(messages, store, options = {}) {
     const has = (message) => message.attachments;
     if (!messages.some((m) => has(m)?.some(isStoredAttachment)))
         return messages;
-    return await Promise.all(messages.map(async (message) => {
+    return await withAttachmentDeadline(options.signal, timeoutMs, async (signal) => Promise.all(messages.map(async (message) => {
         const attachments = has(message);
         if (!attachments?.some(isStoredAttachment))
             return message;
         return {
             ...message,
-            attachments: await Promise.all(attachments.map((attachment) => resolveAttachment(attachment, store, options))),
+            attachments: await Promise.all(attachments.map((attachment) => isStoredAttachment(attachment)
+                ? resolveAttachmentWithSignal(attachment, store, signal)
+                : attachment)),
         };
-    }));
+    })));
+}
+function resolveAttachmentTimeoutMs(value) {
+    const resolved = value ?? DEFAULT_ATTACHMENT_RESOLVE_TIMEOUT_MS;
+    if (!Number.isInteger(resolved) || resolved < 0 || resolved > MAX_TIMER_DELAY_MS) {
+        throw new RangeError(`attachmentResolveTimeoutMs must be an integer from 0 to ${MAX_TIMER_DELAY_MS}; received ${String(resolved)}`);
+    }
+    return resolved;
+}
+/**
+ * Own one timer for the whole parallel materialization phase.
+ *
+ * The caller's signal is an input, never the controller we abort. Whichever
+ * cause wins is latched by `AbortSignal.any`, and every store wait races that
+ * fused signal independently through `awaitStoreRead` below.
+ */
+async function withAttachmentDeadline(upstream, timeoutMs, start) {
+    upstream?.throwIfAborted();
+    if (timeoutMs === 0)
+        return await start(upstream);
+    const timeout = new AbortController();
+    const signal = upstream ? AbortSignal.any([upstream, timeout.signal]) : timeout.signal;
+    const timer = setTimeout(() => timeout.abort(new AttachmentResolutionTimeoutError({ timeoutMs })), timeoutMs);
+    try {
+        return await start(signal);
+    }
+    finally {
+        clearTimeout(timer);
+    }
 }
 /**
  * Await a host store without handing it ownership of run cancellation.

package/dist/store/attachment/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/store/attachment/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/store/attachment/index.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtins/computer-use.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"computer-use.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/computer-use.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAGX,eAAe,EAEf,MAAM,mCAAmC,CAAA;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,2BAA2B,CAAA;AAG3E,eAAO,MAAM,sBAAsB,EAAG,cAAuB,CAAA;AAa7D,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAmBhB,CAAA;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAkFtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,cAAc,CAAC,WAAW,CAAC,CAwBxF"}
+{"version":3,"file":"computer-use.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/computer-use.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAGX,eAAe,EAGf,MAAM,mCAAmC,CAAA;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAc,MAAM,2BAA2B,CAAA;AAG3E,eAAO,MAAM,sBAAsB,EAAG,cAAuB,CAAA;AAa7D,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAmBhB,CAAA;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAA;AAqHtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,GAAG,cAAc,CAAC,WAAW,CAAC,CA+BxF"}

package/dist/tools/builtins/computer-use.js

@@ -110,6 +110,35 @@ function resultToToolResult(result) {
             return { success: true, output: 'ok' };
     }
 }
+function isOutcomeUnknown(value, action) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (candidate.code === 'computer_use_outcome_unknown' &&
+        candidate.action === action &&
+        candidate.outcome === 'unknown' &&
+        candidate.retrySafety === 'unsafe' &&
+        typeof candidate.timedOut === 'boolean' &&
+        typeof candidate.exitCode === 'number' &&
+        Number.isInteger(candidate.exitCode) &&
+        typeof candidate.message === 'string' &&
+        candidate.message.length > 0);
+}
+function unknownOutcomeToToolResult(error) {
+    return {
+        success: false,
+        output: '',
+        error: error.message,
+        data: {
+            code: error.code,
+            action: error.action,
+            outcome: error.outcome,
+            retrySafety: error.retrySafety,
+            timedOut: error.timedOut,
+            exitCode: error.exitCode,
+        },
+    };
+}
 /**
  * Factory: given a ComputerUseHost (provided by the consumer — e.g.
  * @namzu/computer-use's SubprocessComputerUseHost), returns a ToolDefinition
@@ -149,8 +178,16 @@ export function createComputerUseTool(host) {
                     error: `computer_use: action "${input.type}" requires capability "${required}" which is not available on this host (displayServer=${host.capabilities.displayServer}).`,
                 };
             }
-            const result = await host.execute(input);
-            return resultToToolResult(result);
+            try {
+                const result = await host.execute(input);
+                return resultToToolResult(result);
+            }
+            catch (error) {
+                if (isOutcomeUnknown(error, input.type)) {
+                    return unknownOutcomeToToolResult(error);
+                }
+                throw error;
+            }
         },
     });
 }

package/dist/tools/builtins/computer-use.js.map

@@ -1 +1 @@
-{"version":3,"file":"computer-use.js","sourceRoot":"","sources":["../../../src/tools/builtins/computer-use.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"computer-use.js","sourceRoot":"","sources":["../../../src/tools/builtins/computer-use.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtins/lsp.d.ts

@@ -2,8 +2,8 @@ import type { CodeNavigationProvider } from '../../types/code-navigation/index.j
 export declare const LSP_TOOL_NAME = "lsp";
 export declare const LspTool: import("../../types/tool/index.js").ToolDefinition<{
     path: string;
-    operation: "hover" | "definition" | "references";
     line: number;
+    operation: "hover" | "definition" | "references";
     character: number;
 } | {
     query: string;

package/dist/tools/builtins/run-code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-code.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/run-code.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAA;AA0CxE,eAAO,MAAM,kBAAkB,aAAa,CAAA;AAE5C,MAAM,WAAW,kBAAkB;IAClC,gDAAgD;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAA;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAChC;AAKD,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,kBAAuB;;;GAiGhE"}
+{"version":3,"file":"run-code.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/run-code.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uCAAuC,CAAA;AA0CxE,eAAO,MAAM,kBAAkB,aAAa,CAAA;AAE5C,MAAM,WAAW,kBAAkB;IAClC,gDAAgD;IAChD,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAA;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAChC;AAKD,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,kBAAuB;;;GAyGhE"}

package/dist/tools/builtins/run-code.js

@@ -10,12 +10,12 @@ import { defineTool } from '../defineTool.js';
  * loop cannot reach further than the twenty calls could have.
  *
  * **The program's reach is the RUN's reach, and nothing wider.** Every
- * capability it can call is a tool already in this run's registry, already
- * narrowed by the turn's `allowedTools`, already subject to the same
- * dispatch that a model-issued call goes through — the permission gate, the
- * approval policy, the audit record. There is no second path: the runtime
- * hands the host a name and an input, and the host does exactly what it
- * would have done for a `tool_use` block.
+ * capability it can call is a tool already in this run's registry and
+ * narrowed by the turn's `allowedTools`. The host dispatch records every
+ * child in the run and applies the run's operator authorization gate. An
+ * explicit allow proceeds; a denial or an undecided child fails closed and
+ * leaves a durable refusal, because an already-executing parent cannot open
+ * a second durable human-review turn on the program's behalf.
  *
  * Opt-in, and not in the default builtin set. A run that does not need
  * model-authored control flow should not have a way to execute
@@ -72,20 +72,24 @@ export function buildRunCodeTool(options = {}) {
                 timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
                 maxOutputBytes: options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT,
                 ...(context.abortSignal ? { signal: context.abortSignal } : {}),
-                onHostCall: async (request) => {
-                    // Through the SAME registry, with the SAME context. Not a
-                    // parallel dispatch path: a second path is a second place
-                    // for the permission gate to be forgotten, and the one that
-                    // forgot it would be the one a model reached through a
-                    // program.
+                onHostCall: async (request, operation) => {
+                    // Through the run-owned nested dispatch: registry narrowing,
+                    // operator authorization, audit/event lineage and invocation
+                    // cancellation remain host-owned rather than worker-owned.
                     try {
-                        const toolResult = await dispatch(request.name, request.input);
+                        const toolResult = await dispatch(request.name, request.input, {
+                            signal: operation.signal,
+                            runtimeToolCallId: operation.runtimeToolCallId,
+                        });
                         return toolResult.success
                             ? { ok: true, value: toolResult.output }
                             : { ok: false, error: toolResult.error ?? 'the tool failed' };
                     }
                     catch (err) {
-                        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+                        return {
+                            ok: false,
+                            error: err instanceof Error ? err.message : String(err),
+                        };
                     }
                 },
             });
@@ -113,10 +117,14 @@ export function buildRunCodeTool(options = {}) {
                         // printed its progress and then hung has told the model
                         // where it got to, and discarding that leaves the model
                         // retrying from the start.
-                        error: `The program ran longer than ${options.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms and was stopped.`,
+                        error: `The program ran longer than ${options.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms and its worker was stopped. Admitted host calls were asked to cancel; an uncooperative one may still be running.`,
                     };
                 case 'cancelled':
-                    return { success: false, output: body, error: 'The program was cancelled.' };
+                    return {
+                        success: false,
+                        output: body,
+                        error: 'The program was cancelled.',
+                    };
                 default:
                     return { success: false, output: body, error: result.outcome.error };
             }

package/dist/tools/builtins/run-code.js.map

@@ -1 +1 @@
-{"version":3,"file":"run-code.js","sourceRoot":"","sources":["../../../src/tools/builtins/run-code.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAGvB,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAA;AAC1E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,IAAI,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACR,0MAA0M,CAC1M;IACF,KAAK,EAAE,CAAC;SACN,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;SACjB,QAAQ,CACR,0HAA0H,CAC1H;CACF,CAAC,CAAA;AAIF,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAA;AAS5C,MAAM,kBAAkB,GAAG,MAAM,CAAA;AACjC,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,CAAA;AAEpC,MAAM,UAAU,gBAAgB,CAAC,UAA8B,EAAE;IAChE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,IAAI,iBAAiB,EAAE,CAAA;IAE1D,OAAO,UAAU,CAAC;QACjB,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACV,uNAAuN;QACxN,WAAW;QACX,QAAQ,EAAE,QAAQ;QAClB,WAAW,EAAE,EAAE;QACf,oEAAoE;QACpE,oEAAoE;QACpE,qEAAqE;QACrE,oEAAoE;QACpE,6BAA6B;QAC7B,QAAQ,EAAE,KAAK;QACf,WAAW,EAAE,IAAI;QACjB,eAAe,EAAE,KAAK;QAEtB,KAAK,CAAC,OAAO,CAAC,KAAmB,EAAE,OAAO;YACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,YAAY,CAAA;YACrC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACf,OAAO;oBACN,OAAO,EAAE,KAAK;oBACd,MAAM,EAAE,EAAE;oBACV,KAAK,EAAE,gFAAgF;iBACvF,CAAA;YACF,CAAC;YAED,+DAA+D;YAC/D,gEAAgE;YAChE,mEAAmE;YACnE,gEAAgE;YAChE,MAAM,UAAU,GAAG,OAAO,CAAC,YAAY,CAAA;YACvC,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CACjC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAC/D,CAAA;YACD,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;YAErE,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;gBAChC,MAAM,EAAE,KAAK,CAAC,IAAI;gBAClB,YAAY,EAAE,OAAO;gBACrB,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,kBAAkB;gBAClD,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,kBAAkB;gBAC5D,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/D,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;oBAC7B,0DAA0D;oBAC1D,0DAA0D;oBAC1D,4DAA4D;oBAC5D,uDAAuD;oBACvD,WAAW;oBACX,IAAI,CAAC;wBACJ,MAAM,UAAU,GAAG,MAAM,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,CAAA;wBAC9D,OAAO,UAAU,CAAC,OAAO;4BACxB,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,CAAC,MAAM,EAAE;4BACxC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,IAAI,iBAAiB,EAAE,CAAA;oBAC/D,CAAC;oBAAC,OAAO,GAAG,EAAE,CAAC;wBACd,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAA;oBAC9E,CAAC;gBACF,CAAC;aACD,CAAC,CAAA;YAEF,MAAM,KAAK,GAAG;gBACb,OAAO,CAAC,MAAM,GAAG,CAAC;oBACjB,CAAC,CAAC,6CAA6C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,4BAA4B,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,iBAAiB,GAAG;oBAC3I,CAAC,CAAC,EAAE;gBACL,MAAM,CAAC,eAAe;oBACrB,CAAC,CAAC,mEAAmE;oBACrE,CAAC,CAAC,EAAE;aACL,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;YAEjB,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAEjE,QAAQ,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;gBAC/B,KAAK,WAAW;oBACf,OAAO;wBACN,OAAO,EAAE,IAAI;wBACb,MAAM,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,cAAc,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,WAAW,EAAE;wBACtG,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,CAAC,eAAe,EAAE;qBAChE,CAAA;gBACF,KAAK,WAAW;oBACf,OAAO;wBACN,OAAO,EAAE,KAAK;wBACd,MAAM,EAAE,IAAI;wBACZ,2DAA2D;wBAC3D,wDAAwD;wBACxD,wDAAwD;wBACxD,2BAA2B;wBAC3B,KAAK,EAAE,+BAA+B,OAAO,CAAC,SAAS,IAAI,kBAAkB,qBAAqB;qBAClG,CAAA;gBACF,KAAK,WAAW;oBACf,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,4BAA4B,EAAE,CAAA;gBAC7E;oBACC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;YACtE,CAAC;QACF,CAAC;KACD,CAAC,CAAA;AACH,CAAC"}
+{"version":3,"file":"run-code.js","sourceRoot":"","sources":["../../../src/tools/builtins/run-code.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtins/skill.d.ts

@@ -9,6 +9,7 @@
 export declare function parseAllowedTools(declared: string | undefined): readonly string[] | undefined;
 export declare const SKILL_TOOL_NAME = "skill";
 export declare const SkillTool: import("../../public-types.js").ToolDefinition<{
-    name: string;
+    name?: string | undefined;
+    cursor?: string | undefined;
 }>;
 //# sourceMappingURL=skill.d.ts.map

package/dist/tools/builtins/skill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/skill.ts"],"names":[],"mappings":"AA8BA;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAW7F;AAED,eAAO,MAAM,eAAe,UAAU,CAAA;AAEtC,eAAO,MAAM,SAAS;;EAgFpB,CAAA"}
+{"version":3,"file":"skill.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/skill.ts"],"names":[],"mappings":"AAyOA;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAW7F;AAED,eAAO,MAAM,eAAe,UAAU,CAAA;AAEtC,eAAO,MAAM,SAAS;;;EAmMpB,CAAA"}

package/dist/tools/builtins/skill.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { z } from 'zod';
 import { isInvocableBy, skillInvocation } from '../../types/skills/index.js';
 import { defineTool } from '../defineTool.js';
@@ -20,8 +21,151 @@ const inputSchema = z.object({
     name: z
         .string()
         .min(1)
-        .describe('The skill to load, exactly as listed in the available-skills manifest.'),
+        .optional()
+        .describe('The skill to load, exactly as listed in the available-skills manifest. Omit it to list model-invocable skills.'),
+    cursor: z
+        .string()
+        .max(160)
+        .optional()
+        .describe('Opaque continuation cursor returned by an earlier call in the same mode.'),
 });
+const CURSOR_PATTERN = /^v1\.([1-9][0-9]*)\.([A-Za-z0-9_-]{43})$/;
+const LIST_CURSOR_PATTERN = /^v1\.list\.(0|[1-9][0-9]*)\.([01])\.([A-Za-z0-9_-]{43})$/;
+const MAX_SKILLS_PER_PAGE = 20;
+const OVERSIZED_CATALOG_WARNING = 'Some skills were omitted because their metadata is too large for this response budget.';
+function snapshotDigest(snapshot) {
+    return createHash('sha256')
+        .update(JSON.stringify({
+        version: 1,
+        name: snapshot.name,
+        body: snapshot.body,
+        allowedTools: snapshot.allowedTools ?? null,
+        invocation: snapshot.invocation,
+    }))
+        .digest('base64url');
+}
+function cursorFor(offset, digest) {
+    return `v1.${offset}.${digest}`;
+}
+function parseCursor(cursor) {
+    const match = CURSOR_PATTERN.exec(cursor);
+    if (!match)
+        return undefined;
+    const offset = Number(match[1]);
+    if (!Number.isSafeInteger(offset))
+        return undefined;
+    return { offset, digest: match[2] ?? '' };
+}
+function listCursorFor(offset, warned, digest) {
+    return `v1.list.${offset}.${warned ? 1 : 0}.${digest}`;
+}
+function parseListCursor(cursor) {
+    const match = LIST_CURSOR_PATTERN.exec(cursor);
+    if (!match)
+        return undefined;
+    const offset = Number(match[1]);
+    if (!Number.isSafeInteger(offset))
+        return undefined;
+    return { offset, warned: match[2] === '1', digest: match[3] ?? '' };
+}
+function activeOutputCap(maxChars) {
+    return maxChars !== undefined && maxChars > 0 ? maxChars : undefined;
+}
+function listDigest(skills, maxChars) {
+    return createHash('sha256')
+        .update(JSON.stringify({ version: 1, kind: 'list', maxChars: maxChars ?? null, skills }))
+        .digest('base64url');
+}
+function serializeListPage(page) {
+    return JSON.stringify(page);
+}
+function fitsListBudget(page, maxChars) {
+    return maxChars === undefined || serializeListPage(page).length <= maxChars;
+}
+function pageSkillCatalog(input) {
+    const { skills, digest, start, warningAlreadyShown, maxChars } = input;
+    const retained = [];
+    let omitted = false;
+    let hasRetainedLater = false;
+    // Work backwards so the final retained entry is tested without a cursor.
+    // A last entry that fits by itself must not be dropped merely because an
+    // earlier page will need a continuation token to reach it.
+    for (let index = skills.length - 1; index >= start; index -= 1) {
+        const skill = skills[index];
+        if (!skill)
+            continue;
+        const nextCursor = hasRetainedLater ? listCursorFor(index + 1, true, digest) : null;
+        if (fitsListBudget({ skills: [skill], warnings: [], nextCursor }, maxChars)) {
+            retained.push({ index, skill });
+            hasRetainedLater = true;
+        }
+        else {
+            omitted = true;
+        }
+    }
+    retained.reverse();
+    const warning = omitted && !warningAlreadyShown ? [OVERSIZED_CATALOG_WARNING] : [];
+    let count = Math.min(MAX_SKILLS_PER_PAGE, retained.length);
+    while (count > 0) {
+        const selected = retained.slice(0, count);
+        const last = selected.at(-1);
+        const hasMore = count < retained.length;
+        const page = {
+            skills: selected.map((entry) => entry.skill),
+            warnings: warning,
+            nextCursor: hasMore && last
+                ? listCursorFor(last.index + 1, warningAlreadyShown || warning.length > 0, digest)
+                : null,
+        };
+        if (fitsListBudget(page, maxChars))
+            return page;
+        count -= 1;
+    }
+    if (warning.length > 0) {
+        const page = {
+            skills: [],
+            warnings: warning,
+            nextCursor: retained.length > 0 ? listCursorFor(start, true, digest) : null,
+        };
+        if (fitsListBudget(page, maxChars))
+            return page;
+    }
+    const empty = { skills: [], warnings: [], nextCursor: null };
+    return retained.length === 0 && fitsListBudget(empty, maxChars) ? empty : undefined;
+}
+function isCodePointBoundary(text, index) {
+    if (index <= 0 || index >= text.length)
+        return true;
+    const before = text.charCodeAt(index - 1);
+    const after = text.charCodeAt(index);
+    return !(before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff);
+}
+function boundaryAtOrBefore(text, index) {
+    const bounded = Math.max(0, Math.min(text.length, index));
+    return isCodePointBoundary(text, bounded) ? bounded : bounded - 1;
+}
+function continuationNotice(name, cursor) {
+    return `\n\n[More skill instructions remain. Call skill again with name "${name}" and cursor "${cursor}" before acting.]`;
+}
+function pageSkillBody(input) {
+    const { snapshot, digest, start, notice, maxChars } = input;
+    const remaining = `${snapshot.body.slice(start)}${notice}`;
+    if (maxChars === undefined || maxChars <= 0 || remaining.length <= maxChars) {
+        return { output: remaining };
+    }
+    // Estimate once, then remove exactly the overflow until the page fits.
+    // The cursor grows only at powers of ten, so this converges in a handful
+    // of steps without allocating an index for every character in a large file.
+    let end = boundaryAtOrBefore(snapshot.body, Math.min(snapshot.body.length - 1, start + maxChars));
+    while (end > start) {
+        const nextCursor = cursorFor(end, digest);
+        const output = `${snapshot.body.slice(start, end)}${continuationNotice(snapshot.name, nextCursor)}${notice}`;
+        if (output.length <= maxChars)
+            return { output, nextCursor };
+        end = boundaryAtOrBefore(snapshot.body, end - Math.max(1, output.length - maxChars));
+    }
+    return undefined;
+}
 /**
  * `allowed-tools` as a list.
  *
@@ -46,7 +190,7 @@ export function parseAllowedTools(declared) {
 export const SKILL_TOOL_NAME = 'skill';
 export const SkillTool = defineTool({
     name: SKILL_TOOL_NAME,
-    description: 'Loads the full instructions for a skill listed in the available-skills manifest. Call this before doing work the skill describes; the manifest carries only names and descriptions.',
+    description: 'Lists model-invocable skills when called without a name, or loads one skill by its exact listed name. Long lists and bodies return an opaque continuation cursor; keep calling in the same mode with that cursor until no continuation remains. The manifest carries only names and descriptions.',
     inputSchema,
     category: 'analysis',
     permissions: [],
@@ -64,6 +208,64 @@ export const SkillTool = defineTool({
                 error: 'This run has no skills registry, so there is nothing to load. Proceed without the skill.',
             };
         }
+        if (input.name === undefined) {
+            if (!context.skills.catalog) {
+                return {
+                    success: false,
+                    output: '',
+                    error: 'This skills registry cannot enumerate model-safe metadata. Use a skill name from the available-skills manifest.',
+                };
+            }
+            const skills = (await context.skills.catalog())
+                .filter((entry) => entry.invocation === undefined ||
+                entry.invocation === 'model' ||
+                entry.invocation === 'both')
+                .map((entry) => ({
+                name: entry.registeredName,
+                description: entry.description,
+                location: entry.location,
+                ...(entry.allowedTools === undefined ? {} : { allowedTools: entry.allowedTools }),
+            }));
+            const maxChars = activeOutputCap(context.maxToolOutputChars);
+            const digest = listDigest(skills, maxChars);
+            let start = 0;
+            let warningAlreadyShown = false;
+            if (input.cursor !== undefined) {
+                const parsed = parseListCursor(input.cursor);
+                if (!parsed || parsed.digest !== digest || parsed.offset >= skills.length) {
+                    return {
+                        success: false,
+                        output: '',
+                        error: 'The skill-list continuation cursor is stale or invalid. Call skill again without a cursor to read the current catalog.',
+                    };
+                }
+                start = parsed.offset;
+                warningAlreadyShown = parsed.warned;
+            }
+            const page = pageSkillCatalog({
+                skills,
+                digest,
+                start,
+                warningAlreadyShown,
+                maxChars,
+            });
+            if (!page) {
+                return {
+                    success: false,
+                    output: '',
+                    error: 'The model-visible tool-output budget is too small to list skill metadata safely. Increase maxToolOutputChars and retry.',
+                };
+            }
+            return {
+                success: true,
+                output: serializeListPage(page),
+                data: {
+                    kind: 'list',
+                    count: page.skills.length,
+                    ...(page.nextCursor === null ? {} : { nextCursor: page.nextCursor }),
+                },
+            };
+        }
         // The registry answers with a load RESULT, not a skill — the shape
         // mirrors the implementation rather than an adapter, so there is
         // nothing between them to drift.
@@ -80,6 +282,7 @@ export const SkillTool = defineTool({
             };
         }
         const skill = loaded.skill;
+        const invocation = skillInvocation(skill);
         if (!isInvocableBy(skill, 'model')) {
             // Reachable even though the manifest omits it: the model can name
             // anything, and a check that only filtered the listing would be a
@@ -92,6 +295,49 @@ export const SkillTool = defineTool({
             };
         }
         const allowed = parseAllowedTools(skill.metadata.allowedTools);
+        const snapshot = {
+            name: input.name,
+            body: skill.body ?? '(this skill has no body)',
+            allowedTools: allowed,
+            invocation,
+        };
+        const digest = snapshotDigest(snapshot);
+        let start = 0;
+        if (input.cursor !== undefined) {
+            const parsed = parseCursor(input.cursor);
+            if (!parsed ||
+                parsed.digest !== digest ||
+                parsed.offset >= snapshot.body.length ||
+                !isCodePointBoundary(snapshot.body, parsed.offset)) {
+                return {
+                    success: false,
+                    output: '',
+                    error: `The continuation cursor for "${input.name}" is stale or invalid. Call skill again without a cursor to read the current instructions.`,
+                };
+            }
+            start = parsed.offset;
+        }
+        const notice = allowed === undefined
+            ? ''
+            : `\n\n[While following this skill, restrict yourself to: ${allowed.length > 0 ? allowed.join(', ') : '(no tools)'}. This takes effect from your next turn.]`;
+        const page = pageSkillBody({
+            snapshot,
+            digest,
+            start,
+            notice,
+            maxChars: context.maxToolOutputChars,
+        });
+        if (!page) {
+            return {
+                success: false,
+                output: '',
+                error: `The model-visible tool-output budget is too small to read "${input.name}" safely. Increase maxToolOutputChars and retry.`,
+            };
+        }
+        // Cursor and policy validation must finish before this mutation. A
+        // continuation is bound to the body AND its effective authorization
+        // metadata, so an edit to allowed-tools or invocation cannot widen the
+        // next batch under an old cursor.
         if (allowed !== undefined) {
             // Adopted, not merely announced. The notice below tells the model
             // what happened; this is what makes it true whether or not the
@@ -104,15 +350,13 @@ export const SkillTool = defineTool({
             // advice.
             context.adoptSkillScope?.({ skill: skill.metadata.name, allowedTools: allowed });
         }
-        const notice = allowed === undefined
-            ? ''
-            : `\n\n[While following this skill, restrict yourself to: ${allowed.length > 0 ? allowed.join(', ') : '(no tools)'}. This takes effect from your next turn.]`;
         return {
             success: true,
-            output: `${skill.body ?? '(this skill has no body)'}${notice}`,
+            output: page.output,
             data: {
                 skill: skill.metadata.name,
                 ...(allowed === undefined ? {} : { allowedTools: allowed }),
+                ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
             },
         };
     },