@namzu/sdk 39.0.0 → 40.0.0

package/dist/tools/builtins/read-file.js

@@ -3,10 +3,22 @@ import { extname } from 'node:path';
 import { z } from 'zod';
 import { defineTool } from '../defineTool.js';
 import { resolveWithinAnyReal, toolRoots } from '../paths.js';
+import { fingerprintContent } from './content-fingerprint.js';
+import { renderNumberedRead } from './read-render.js';
 const inputSchema = z.object({
     path: z.string().describe('Path to the file to read (absolute or relative)'),
+    // A two-element ARRAY, not a `z.tuple`, and the distinction is the whole
+    // reason this comment exists. Both members carry the identical constraint,
+    // so the tuple bought nothing — and it rendered as the draft-07 tuple
+    // `items: [a, b]`, which a wire that validates against JSON Schema 2020-12
+    // refuses outright. It was the only tuple in the first-party tool surface,
+    // and it took down every other tool in the same request with it. The
+    // spelling below means the same thing to the model (`[10, 40]` either way)
+    // and to the parser, and reads identically in both dialects. See
+    // `registry/tool/portable.ts`.
     readRange: z
-        .tuple([z.coerce.number().int().min(1), z.coerce.number().int().min(1)])
+        .array(z.coerce.number().int().min(1))
+        .length(2)
         .optional()
         .describe('Optional 1-indexed inclusive line range, e.g. [10, 40]. When provided it takes precedence over offset/limit.'),
     offset: z.coerce
@@ -53,22 +65,15 @@ export const ReadFileTool = defineTool({
                 };
             }
             const content = buffer.toString('utf-8');
-            const lines = content.split('\n');
-            const { start, end } = resolveReadWindow(input, lines.length);
-            const selectedLines = lines.slice(start, end);
-            const numberedLines = selectedLines.map((line, i) => `${start + i + 1}\t${line}`).join('\n');
-            // The WHOLE body, not the selected window: a later edit is checked
-            // against the file, and a partial read must not fingerprint a
-            // fragment as if it were the file.
-            context.fileReadTracker?.recordRead(input.path, content);
-            const partial = selectedLines.length < lines.length;
+            const rendered = renderNumberedRead(content, input);
+            recordObservedRead(context, input.path, content, rendered);
             return {
                 success: true,
-                output: numberedLines + partialViewNotice(start, selectedLines.length, lines.length),
+                output: rendered.output,
                 data: {
-                    totalLines: lines.length,
-                    returnedLines: selectedLines.length,
-                    truncated: partial,
+                    totalLines: rendered.totalLines,
+                    returnedLines: rendered.returnedLines,
+                    truncated: rendered.partial,
                     path: input.path,
                     sandboxed: true,
                 },
@@ -88,24 +93,45 @@ export const ReadFileTool = defineTool({
             };
         }
         const content = buffer.toString('utf-8');
-        const lines = content.split('\n');
-        const { start, end } = resolveReadWindow(input, lines.length);
-        const selectedLines = lines.slice(start, end);
-        const numberedLines = selectedLines.map((line, i) => `${start + i + 1}\t${line}`).join('\n');
-        context.fileReadTracker?.recordRead(filePath, content);
-        const isPartial = selectedLines.length < lines.length;
+        const rendered = renderNumberedRead(content, input);
+        recordObservedRead(context, filePath, content, rendered);
         return {
             success: true,
-            output: numberedLines + partialViewNotice(start, selectedLines.length, lines.length),
+            output: rendered.output,
             data: {
-                totalLines: lines.length,
-                returnedLines: selectedLines.length,
-                truncated: isPartial,
+                totalLines: rendered.totalLines,
+                returnedLines: rendered.returnedLines,
+                truncated: rendered.partial,
                 path: filePath,
             },
         };
     },
 });
+/**
+ * Put this read on the observation ledger.
+ *
+ * Always the WHOLE body, not the selected window: a later edit is checked
+ * against the file, and a partial read must not fingerprint a fragment as if it
+ * were the file.
+ *
+ * A read that returned the file whole additionally witnesses itself, so the
+ * derived work context can reference the body without the model reading it
+ * again. The witness is the fingerprint of the RENDERING — this call's own
+ * `output`, byte for byte — because the rendering is what the receipt carries,
+ * and the body is in front of the model only while the receipt is still exactly
+ * that. A read whose window left any of the file out witnesses nothing: it
+ * shows a fragment, and the fingerprint of the file cannot say which one.
+ */
+function recordObservedRead(context, key, content, rendered) {
+    const tracker = context.fileReadTracker;
+    if (!tracker)
+        return;
+    if (!rendered.partial && tracker.recordFullRead && context.toolUseId) {
+        tracker.recordFullRead(key, content, context.toolUseId, fingerprintContent(rendered.output));
+        return;
+    }
+    tracker.recordRead(key, content);
+}
 function describeStructuredBinaryRead(path, buffer) {
     const ext = extname(path).toLowerCase();
     if (ext === '.docx')
@@ -130,45 +156,4 @@ function buildStructuredBinaryGuidance(path, format, extractor) {
         'If extraction fails, report the exact filename and extraction error instead of claiming the attachment is unavailable.',
     ].join('\n');
 }
-/**
- * Lines returned when the caller specifies no window.
- *
- * Chosen to cover the overwhelming majority of source files whole while
- * bounding the pathological case.
- */
-const DEFAULT_READ_LINES = 2000;
-/**
- * Tell the model, explicitly, when it is looking at a window rather than
- * the file.
- *
- * Without this a truncated read is indistinguishable from a short file, and
- * the agent reasons about a fragment as if it were the whole thing — the
- * most expensive silent failure a read tool can have. The notice names the
- * exact next call rather than describing it.
- */
-function partialViewNotice(start, returned, total) {
-    if (returned >= total)
-        return '';
-    const shownTo = start + returned;
-    return [
-        '',
-        '',
-        `[PARTIAL view — lines ${start + 1}-${shownTo} of ${total}.`,
-        `Continue with read({ offset: ${shownTo}, limit: N }), or narrow with grep.]`,
-    ].join('\n');
-}
-function resolveReadWindow(input, totalLines) {
-    if (input.readRange) {
-        const [first, last] = input.readRange;
-        const start = Math.max(0, first - 1);
-        const end = Math.min(totalLines, Math.max(start, last));
-        return { start, end };
-    }
-    const start = Math.max(0, input.offset ?? 0);
-    // A bare `read({ path })` used to return the entire file, so a 2 MB
-    // lockfile became ~500k tokens in one tool_result. Default to a window
-    // and say so in the output; the model asks for more when it needs it.
-    const end = input.limit ? start + input.limit : Math.min(totalLines, start + DEFAULT_READ_LINES);
-    return { start, end };
-}
 //# sourceMappingURL=read-file.js.map

package/dist/tools/builtins/read-file.js.map

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

package/dist/tools/builtins/read-render.d.ts

@@ -0,0 +1,56 @@
+/**
+ * How `read` turns a file's body into the text the model sees.
+ *
+ * Pulled out of the tool for the reason `edit-apply` was: a second caller —
+ * the resume seed, deciding whether a `read` receipt in history shows exactly
+ * the body it already believes the file had — has to produce byte-for-byte
+ * what the tool produced, and a parallel implementation of the numbering or
+ * the window arithmetic would silently stop agreeing with it.
+ *
+ * Pure by construction: no filesystem access, no `ToolContext`.
+ */
+/**
+ * Lines returned when the caller specifies no window.
+ *
+ * Chosen to cover the overwhelming majority of source files whole while
+ * bounding the pathological case.
+ */
+export declare const DEFAULT_READ_LINES = 2000;
+/** The window fields of `read`'s input; the path plays no part in rendering. */
+export interface ReadWindowRequest {
+    /**
+     * `[start, end]`, 1-indexed inclusive.
+     *
+     * Typed as a number array rather than a pair because the tool's schema
+     * pins the length at two with `.length(2)` instead of a `z.tuple` — a
+     * tuple renders as draft-07 `items: [a, b]`, which a 2020-12 wire refuses.
+     * The parse still rejects any other length, so a caller reaching here has
+     * two numbers; `resolveReadWindow` reads them defensively anyway, because
+     * this interface is also implemented by hand elsewhere in the kernel.
+     */
+    readonly readRange?: readonly number[];
+    readonly offset?: number;
+    readonly limit?: number;
+}
+export interface RenderedRead {
+    /** Exactly what `read` returns as its output for this body and window. */
+    readonly output: string;
+    readonly totalLines: number;
+    readonly returnedLines: number;
+    /** Whether the window left any of the file out, which is what adds the notice. */
+    readonly partial: boolean;
+}
+/**
+ * Render `content` the way `read` renders it.
+ *
+ * The numbering is what makes this reversible enough to compare against: every
+ * line goes out behind its own `${n}\t`, so two different bodies cannot render
+ * to one string, and the partial-view notice below — whose lines carry no such
+ * prefix — cannot be mistaken for part of a body.
+ */
+export declare function renderNumberedRead(content: string, input: ReadWindowRequest): RenderedRead;
+export declare function resolveReadWindow(input: ReadWindowRequest, totalLines: number): {
+    start: number;
+    end: number;
+};
+//# sourceMappingURL=read-render.d.ts.map

package/dist/tools/builtins/read-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-render.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/read-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAA;AAEtC,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IACjC;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,YAAY;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,YAAY,CAW1F;AAsBD,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,iBAAiB,EACxB,UAAU,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAahC"}

package/dist/tools/builtins/read-render.js

@@ -0,0 +1,73 @@
+/**
+ * How `read` turns a file's body into the text the model sees.
+ *
+ * Pulled out of the tool for the reason `edit-apply` was: a second caller —
+ * the resume seed, deciding whether a `read` receipt in history shows exactly
+ * the body it already believes the file had — has to produce byte-for-byte
+ * what the tool produced, and a parallel implementation of the numbering or
+ * the window arithmetic would silently stop agreeing with it.
+ *
+ * Pure by construction: no filesystem access, no `ToolContext`.
+ */
+/**
+ * Lines returned when the caller specifies no window.
+ *
+ * Chosen to cover the overwhelming majority of source files whole while
+ * bounding the pathological case.
+ */
+export const DEFAULT_READ_LINES = 2000;
+/**
+ * Render `content` the way `read` renders it.
+ *
+ * The numbering is what makes this reversible enough to compare against: every
+ * line goes out behind its own `${n}\t`, so two different bodies cannot render
+ * to one string, and the partial-view notice below — whose lines carry no such
+ * prefix — cannot be mistaken for part of a body.
+ */
+export function renderNumberedRead(content, input) {
+    const lines = content.split('\n');
+    const { start, end } = resolveReadWindow(input, lines.length);
+    const selected = lines.slice(start, end);
+    const numbered = selected.map((line, i) => `${start + i + 1}\t${line}`).join('\n');
+    return {
+        output: numbered + partialViewNotice(start, selected.length, lines.length),
+        totalLines: lines.length,
+        returnedLines: selected.length,
+        partial: selected.length < lines.length,
+    };
+}
+/**
+ * Tell the model, explicitly, when it is looking at a window rather than
+ * the file.
+ *
+ * Without this a truncated read is indistinguishable from a short file, and
+ * the agent reasons about a fragment as if it were the whole thing — the
+ * most expensive silent failure a read tool can have. The notice names the
+ * exact next call rather than describing it.
+ */
+function partialViewNotice(start, returned, total) {
+    if (returned >= total)
+        return '';
+    const shownTo = start + returned;
+    return [
+        '',
+        '',
+        `[PARTIAL view — lines ${start + 1}-${shownTo} of ${total}.`,
+        `Continue with read({ offset: ${shownTo}, limit: N }), or narrow with grep.]`,
+    ].join('\n');
+}
+export function resolveReadWindow(input, totalLines) {
+    const [first, last] = input.readRange ?? [];
+    if (first !== undefined && last !== undefined) {
+        const start = Math.max(0, first - 1);
+        const end = Math.min(totalLines, Math.max(start, last));
+        return { start, end };
+    }
+    const start = Math.max(0, input.offset ?? 0);
+    // A bare `read({ path })` used to return the entire file, so a 2 MB
+    // lockfile became ~500k tokens in one tool_result. Default to a window
+    // and say so in the output; the model asks for more when it needs it.
+    const end = input.limit ? start + input.limit : Math.min(totalLines, start + DEFAULT_READ_LINES);
+    return { start, end };
+}
+//# sourceMappingURL=read-render.js.map

package/dist/tools/builtins/read-render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-render.js","sourceRoot":"","sources":["../../../src/tools/builtins/read-render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAA;AA4BtC;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,KAAwB;IAC3E,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACjC,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,iBAAiB,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;IAC7D,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;IACxC,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,KAAK,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAClF,OAAO;QACN,MAAM,EAAE,QAAQ,GAAG,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;QAC1E,UAAU,EAAE,KAAK,CAAC,MAAM;QACxB,aAAa,EAAE,QAAQ,CAAC,MAAM;QAC9B,OAAO,EAAE,QAAQ,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM;KACvC,CAAA;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,iBAAiB,CAAC,KAAa,EAAE,QAAgB,EAAE,KAAa;IACxE,IAAI,QAAQ,IAAI,KAAK;QAAE,OAAO,EAAE,CAAA;IAChC,MAAM,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAA;IAChC,OAAO;QACN,EAAE;QACF,EAAE;QACF,yBAAyB,KAAK,GAAG,CAAC,IAAI,OAAO,OAAO,KAAK,GAAG;QAC5D,gCAAgC,OAAO,sCAAsC;KAC7E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACb,CAAC;AAED,MAAM,UAAU,iBAAiB,CAChC,KAAwB,EACxB,UAAkB;IAElB,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,KAAK,CAAC,SAAS,IAAI,EAAE,CAAA;IAC3C,IAAI,KAAK,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAA;QACvD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;IACtB,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,CAAA;IAC5C,oEAAoE;IACpE,uEAAuE;IACvE,sEAAsE;IACtE,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,GAAG,kBAAkB,CAAC,CAAA;IAChG,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAA;AACtB,CAAC"}

package/dist/tools/builtins/wait-for-job-bounds.d.ts

@@ -0,0 +1,67 @@
+import type { BackgroundJobRegistryRef } from '../../types/tool/index.js';
+/**
+ * Waiting on a background job, bounded by two different questions — the
+ * shell-job counterpart to `waitForTaskWithBounds`
+ * (`../coordinator/wait-with-idle-bound.ts`), which this mirrors.
+ *
+ * A delegated agent task reports its own progress through
+ * `TaskScheduler.onTaskProgress`. A shell job has no such channel: the only
+ * signal it ever produces is bytes on stdout/stderr. So where the task
+ * version resets its idle clock on a progress EVENT, this one resets it on
+ * OBSERVED OUTPUT GROWTH — read on every tick, compared against the last
+ * tick's offset. A tick that finds nothing new is not progress; treating it
+ * as progress would make the idle bound unable to fire for a wedged job at
+ * all, which is the exact failure this exists to catch.
+ *
+ *  - the **run bound** counts elapsed time and is never refreshed. It
+ *    exists for a job that stays busy forever (a server, a stuck build).
+ *  - the **idle bound** counts time since output last grew, and resets
+ *    whenever it does. It exists for a job that stopped producing anything
+ *    without exiting.
+ *
+ * Neither bound cancels the job. A wait that ran out is a statement about
+ * the WAITER, not the work — the job keeps running, and its output is still
+ * there to read with `job` or a later `wait_for_job` call.
+ */
+export interface JobWaitOptions {
+    /** Elapsed-time ceiling, never refreshed. */
+    readonly runMs: number;
+    /**
+     * Time-without-new-output ceiling, refreshed whenever `read` returns
+     * more than it did last tick. Omit to bound by the run clock alone.
+     */
+    readonly idleMs?: number;
+    /** Resume from here rather than the start of what the job has retained. */
+    readonly fromOffset?: number;
+    /** Stop preempts a wait that has not resolved yet; the job is untouched. */
+    readonly signal?: AbortSignal;
+}
+interface JobWaitProgress {
+    readonly output: string;
+    readonly nextOffset: number;
+    readonly droppedBytes: number;
+}
+export type JobWaitOutcome = ({
+    readonly kind: 'exited';
+    readonly status: string;
+    readonly exitCode?: number;
+} & JobWaitProgress) | ({
+    readonly kind: 'timeout';
+    /** Which clock ran out. */
+    readonly cause: 'idle' | 'run';
+    readonly elapsedMs: number;
+} & JobWaitProgress);
+/**
+ * Await a job under both bounds, accumulating its output as it goes.
+ *
+ * Returns the output gathered so far either way: a completed wait has all
+ * of it, and a timed-out one has everything read up to the moment it gave
+ * up, so the caller never has to throw away a partial answer.
+ */
+export declare function waitForJobWithBounds(jobs: Pick<BackgroundJobRegistryRef, 'read' | 'waitForExit'>, id: string, options: JobWaitOptions, now?: () => number): Promise<JobWaitOutcome>;
+/** What to tell the model, in the words that fit what actually happened. */
+export declare function describeJobWaitTimeout(id: string, outcome: Extract<JobWaitOutcome, {
+    kind: 'timeout';
+}>): string;
+export {};
+//# sourceMappingURL=wait-for-job-bounds.d.ts.map

package/dist/tools/builtins/wait-for-job-bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-for-job-bounds.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/wait-for-job-bounds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAA;AAEzE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,cAAc;IAC9B,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC7B;AAED,UAAU,eAAe;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,MAAM,cAAc,GACvB,CAAC;IACD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CACzB,GAAG,eAAe,CAAC,GACpB,CAAC;IACD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAA;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CACzB,GAAG,eAAe,CAAC,CAAA;AAYvB;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACzC,IAAI,EAAE,IAAI,CAAC,wBAAwB,EAAE,MAAM,GAAG,aAAa,CAAC,EAC5D,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,cAAc,EACvB,GAAG,GAAE,MAAM,MAAiB,GAC1B,OAAO,CAAC,cAAc,CAAC,CAoFzB;AAED,4EAA4E;AAC5E,wBAAgB,sBAAsB,CACrC,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,CAAC,cAAc,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,GACnD,MAAM,CAOR"}

package/dist/tools/builtins/wait-for-job-bounds.js

@@ -0,0 +1,108 @@
+/**
+ * How often the bounds are checked, and how often output is drained.
+ *
+ * Coarse on purpose, same reasoning as the task version's own interval:
+ * both bounds are measured in minutes, so a second of latency noticing
+ * either one is irrelevant, and this is an internal timer, not a model
+ * turn — it costs nothing external no matter how often it fires.
+ */
+const POLL_INTERVAL_MS = 1_000;
+/**
+ * Await a job under both bounds, accumulating its output as it goes.
+ *
+ * Returns the output gathered so far either way: a completed wait has all
+ * of it, and a timed-out one has everything read up to the moment it gave
+ * up, so the caller never has to throw away a partial answer.
+ */
+export async function waitForJobWithBounds(jobs, id, options, now = Date.now) {
+    if (!jobs.waitForExit) {
+        throw new Error('This background job registry cannot wait for a job to exit.');
+    }
+    const waitForExit = jobs.waitForExit.bind(jobs);
+    const startedAt = now();
+    let lastProgressAt = startedAt;
+    let cursor = options.fromOffset ?? 0;
+    let output = '';
+    let droppedBytes = 0;
+    let settled = false;
+    /** Read whatever is new since `cursor`, and count it as progress if it is. */
+    const drain = () => {
+        const chunk = jobs.read(id, { fromOffset: cursor });
+        if (chunk.droppedBytes > 0)
+            droppedBytes += chunk.droppedBytes;
+        if (chunk.nextOffset > cursor)
+            lastProgressAt = now();
+        cursor = chunk.nextOffset;
+        if (chunk.chunk)
+            output += chunk.chunk;
+    };
+    try {
+        const exited = waitForExit(id, { signal: options.signal }).then((job) => {
+            // One last read: the job can exit between ticks, and the bytes
+            // it wrote in its final moment are exactly the ones a caller
+            // most wants — the error, the summary line, the exit trace.
+            drain();
+            return {
+                kind: 'exited',
+                status: job.status,
+                ...(job.exitCode === undefined ? {} : { exitCode: job.exitCode }),
+                output,
+                nextOffset: cursor,
+                droppedBytes,
+            };
+        });
+        const expiry = new Promise((resolve) => {
+            // Polled rather than scheduled, for the same reason the task
+            // version is: the idle deadline MOVES on every byte of new
+            // output, and a timer armed for it would have to be cleared and
+            // rearmed on every tick that mattered.
+            const tick = setInterval(() => {
+                if (settled)
+                    return;
+                drain();
+                const elapsed = now() - startedAt;
+                if (elapsed >= options.runMs) {
+                    clearInterval(tick);
+                    resolve({
+                        kind: 'timeout',
+                        cause: 'run',
+                        elapsedMs: elapsed,
+                        output,
+                        nextOffset: cursor,
+                        droppedBytes,
+                    });
+                    return;
+                }
+                if (options.idleMs !== undefined) {
+                    const quietFor = now() - lastProgressAt;
+                    if (quietFor >= options.idleMs) {
+                        clearInterval(tick);
+                        resolve({
+                            kind: 'timeout',
+                            cause: 'idle',
+                            elapsedMs: elapsed,
+                            output,
+                            nextOffset: cursor,
+                            droppedBytes,
+                        });
+                    }
+                }
+            }, POLL_INTERVAL_MS);
+            tick.unref?.();
+        });
+        return await Promise.race([exited, expiry]);
+    }
+    finally {
+        settled = true;
+    }
+}
+/** What to tell the model, in the words that fit what actually happened. */
+export function describeJobWaitTimeout(id, outcome) {
+    const seconds = Math.round(outcome.elapsedMs / 1000);
+    const resume = `call wait_for_job again, or job read with from_offset ${outcome.nextOffset}, to see what it does next`;
+    if (outcome.cause === 'idle') {
+        return `Job ${id} went quiet: no new output for a while, after ${seconds}s. It has not been stopped and may still be working — ${resume}.`;
+    }
+    return `Job ${id} has been running for ${seconds}s without finishing. It has not been stopped — ${resume}.`;
+}
+//# sourceMappingURL=wait-for-job-bounds.js.map

package/dist/tools/builtins/wait-for-job-bounds.js.map

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

package/dist/tools/builtins/wait-for-job.d.ts

@@ -0,0 +1,6 @@
+export declare const WaitForJobTool: import("../../public-types.js").ToolDefinition<{
+    id: string;
+    timeout_ms?: number | undefined;
+    idle_timeout_ms?: number | undefined;
+}>;
+//# sourceMappingURL=wait-for-job.d.ts.map

package/dist/tools/builtins/wait-for-job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-for-job.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/wait-for-job.ts"],"names":[],"mappings":"AA2DA,eAAO,MAAM,cAAc;;;;EA4HzB,CAAA"}