@namzu/sdk 0.6.0 → 1.1.0

package/dist/tools/builtins/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/builtins/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAA;AAC/F,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAGjF,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,wEAAwE;AACxE,qEAAqE;AAErE,MAAM,UAAU,eAAe;IAC9B,OAAO;QACN,YAAY;QACZ,aAAa;QACb,QAAQ;QACR,QAAQ;QACR,QAAQ;QACR,QAAQ;QACR,MAAM;QACN,eAAe;KACf,CAAA;AACF,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/tools/builtins/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAA;AAChC,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAA;AAC/F,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAGjF,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAC/C,wEAAwE;AACxE,sEAAsE;AACtE,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,qEAAqE;AACrE,wEAAwE;AACxE,0EAA0E;AAC1E,2EAA2E;AAC3E,sEAAsE;AACtE,0EAA0E;AAE1E,MAAM,UAAU,eAAe;IAC9B,OAAO,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,iBAAiB,EAAE,aAAa,CAAC,CAAA;AAChG,CAAC"}

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

@@ -1,6 +1,7 @@
 export declare const ReadFileTool: import("../../public-types.js").ToolDefinition<{
     path: string;
     limit?: number | undefined;
+    readRange?: [number, number] | undefined;
     offset?: number | undefined;
 }>;
 //# sourceMappingURL=read-file.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"read-file.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/read-file.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,YAAY;;;;EAwDvB,CAAA"}
+{"version":3,"file":"read-file.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/read-file.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,YAAY;;;;;EAkFvB,CAAA"}

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

@@ -1,9 +1,13 @@
 import { readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { extname, resolve } from 'node:path';
 import { z } from 'zod';
 import { defineTool } from '../defineTool.js';
 const inputSchema = z.object({
     path: z.string().describe('Path to the file to read (absolute or relative)'),
+    readRange: z
+        .tuple([z.coerce.number().int().min(1), z.coerce.number().int().min(1)])
+        .optional()
+        .describe('Optional 1-indexed inclusive line range, e.g. [10, 40]. When provided it takes precedence over offset/limit.'),
     offset: z.coerce
         .number()
         .int()
@@ -13,8 +17,8 @@ const inputSchema = z.object({
     limit: z.coerce.number().optional().describe('Maximum number of lines to read'),
 });
 export const ReadFileTool = defineTool({
-    name: 'read_file',
-    description: 'Reads a file and returns its contents with line numbers. Supports offset and limit parameters for large files.',
+    name: 'read',
+    description: 'Reads a file and returns its contents with line numbers. Supports readRange ([start,end], 1-indexed inclusive) or offset/limit for large files.',
     inputSchema,
     category: 'filesystem',
     permissions: ['file_read'],
@@ -25,12 +29,24 @@ export const ReadFileTool = defineTool({
         // Sandbox-aware: route through sandbox.readFile() when available
         if (context.sandbox) {
             const buffer = await context.sandbox.readFile(input.path);
+            const binaryGuidance = describeStructuredBinaryRead(input.path, buffer);
+            if (binaryGuidance) {
+                return {
+                    success: false,
+                    output: binaryGuidance,
+                    data: {
+                        path: input.path,
+                        sandboxed: true,
+                        binary: true,
+                    },
+                };
+            }
             const content = buffer.toString('utf-8');
             const lines = content.split('\n');
-            const start = Math.max(0, input.offset ?? 0);
-            const end = input.limit ? start + input.limit : lines.length;
+            const { start, end } = resolveReadWindow(input, lines.length);
             const selectedLines = lines.slice(start, end);
-            const numberedLines = selectedLines.map((line, i) => `${start + i}\t${line}`).join('\n');
+            const numberedLines = selectedLines.map((line, i) => `${start + i + 1}\t${line}`).join('\n');
+            context.fileReadTracker?.recordRead(input.path);
             return {
                 success: true,
                 output: numberedLines,
@@ -43,12 +59,24 @@ export const ReadFileTool = defineTool({
             };
         }
         const filePath = resolve(context.workingDirectory, input.path);
-        const content = await readFile(filePath, 'utf-8');
+        const buffer = await readFile(filePath);
+        const binaryGuidance = describeStructuredBinaryRead(filePath, buffer);
+        if (binaryGuidance) {
+            return {
+                success: false,
+                output: binaryGuidance,
+                data: {
+                    path: filePath,
+                    binary: true,
+                },
+            };
+        }
+        const content = buffer.toString('utf-8');
         const lines = content.split('\n');
-        const start = Math.max(0, input.offset ?? 0);
-        const end = input.limit ? start + input.limit : lines.length;
+        const { start, end } = resolveReadWindow(input, lines.length);
         const selectedLines = lines.slice(start, end);
-        const numberedLines = selectedLines.map((line, i) => `${start + i}\t${line}`).join('\n');
+        const numberedLines = selectedLines.map((line, i) => `${start + i + 1}\t${line}`).join('\n');
+        context.fileReadTracker?.recordRead(filePath);
         return {
             success: true,
             output: numberedLines,
@@ -60,4 +88,39 @@ export const ReadFileTool = defineTool({
         };
     },
 });
+function describeStructuredBinaryRead(path, buffer) {
+    const ext = extname(path).toLowerCase();
+    if (ext === '.docx')
+        return buildStructuredBinaryGuidance(path, 'DOCX', 'python-docx');
+    if (ext === '.pptx')
+        return buildStructuredBinaryGuidance(path, 'PPTX', 'python-pptx');
+    if (ext === '.xlsx')
+        return buildStructuredBinaryGuidance(path, 'XLSX', 'openpyxl');
+    if (ext === '.pdf' || startsWithPdfHeader(buffer)) {
+        return buildStructuredBinaryGuidance(path, 'PDF', 'pdftotext or PyMuPDF');
+    }
+    return null;
+}
+function startsWithPdfHeader(buffer) {
+    return buffer.length >= 4 && buffer.subarray(0, 4).toString('utf8') === '%PDF';
+}
+function buildStructuredBinaryGuidance(path, format, extractor) {
+    return [
+        `The file "${path}" is a ${format} document package, not UTF-8 text.`,
+        'Do not use the read/cat tools as evidence for this raw file.',
+        `Extract its text with shell/Python tooling already available in the sandbox (${extractor}), write the extracted text or summary under scratch, then read that text file.`,
+        'If extraction fails, report the exact filename and extraction error instead of claiming the attachment is unavailable.',
+    ].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);
+    const end = input.limit ? start + input.limit : totalLines;
+    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/search-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-tools.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/search-tools.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,eAAe;;EA2C1B,CAAA"}
+{"version":3,"file":"search-tools.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/search-tools.ts"],"names":[],"mappings":"AAmBA,eAAO,MAAM,eAAe;;EAkE1B,CAAA"}

package/dist/tools/builtins/search-tools.js

@@ -1,8 +1,18 @@
 import { z } from 'zod';
+import { toolDiscoveryHint } from '../../registry/tool/execute.js';
 import { defineTool } from '../defineTool.js';
 const inputSchema = z.object({
     query: z.string().describe('Tool name or capability keyword to search for'),
 });
+// Activate only the best-ranked matches. Top-5 is the literature's sweet
+// spot (retrieval at k=5 matches oracle toolsets) and bounds how much
+// schema weight a single search can add to every subsequent iteration —
+// each activation also busts the prompt-cache prefix once.
+const ACTIVATION_TOP_K = 5;
+// Near-misses are reported name+hint WITHOUT activating, so a retrieval
+// miss becomes one cheap re-query instead of a dead end (the fixed-top-k
+// hard-tail failure mode: the right tool ranked 6th-10th).
+const NEAR_MISS_LIMIT = 5;
 export const SearchToolsTool = defineTool({
     name: 'search_tools',
     description: 'Search and load available tools by name or capability. ' +
@@ -21,21 +31,39 @@ export const SearchToolsTool = defineTool({
                 error: 'Tool registry not available in this context.',
             };
         }
-        const matches = context.toolRegistry.searchDeferred(input.query);
-        if (matches.length === 0) {
+        const allowed = context.allowedTools && context.allowedTools.length > 0 ? new Set(context.allowedTools) : null;
+        // `searchDeferred` returns a ranked list (score-descending), so slicing
+        // the head is a true top-k activation, not an arbitrary subset.
+        const ranked = context.toolRegistry
+            .searchDeferred(input.query)
+            .filter((tool) => !allowed || allowed.has(tool.name));
+        if (ranked.length === 0) {
             return {
                 success: true,
                 output: `No deferred tools matching "${input.query}". All matching tools are already active.`,
             };
         }
-        context.toolRegistry.activate(matches.map((t) => t.name));
-        const descriptions = matches.map((t) => `- ${t.name}: ${t.description}`).join('\n');
+        const activated = ranked.slice(0, ACTIVATION_TOP_K);
+        const nearMisses = ranked.slice(ACTIVATION_TOP_K, ACTIVATION_TOP_K + NEAR_MISS_LIMIT);
+        context.toolRegistry.activate(activated.map((t) => t.name));
+        const descriptions = activated.map((t) => `- ${t.name}: ${t.description}`).join('\n');
+        const sections = [`Activated ${activated.length} tool(s):\n${descriptions}`];
+        if (nearMisses.length > 0) {
+            const hints = nearMisses
+                .map((t) => {
+                const hint = toolDiscoveryHint(t.description);
+                return hint.length > 0 ? `- ${t.name}: ${hint}` : `- ${t.name}`;
+            })
+                .join('\n');
+            sections.push(`Also matched but NOT loaded (search again with a more specific query, e.g. the tool name, to load one of these):\n${hints}`);
+        }
         return {
             success: true,
-            output: `Activated ${matches.length} tool(s):\n${descriptions}`,
+            output: sections.join('\n\n'),
             data: {
-                activated: matches.map((t) => t.name),
-                count: matches.length,
+                activated: activated.map((t) => t.name),
+                count: activated.length,
+                nearMisses: nearMisses.map((t) => t.name),
             },
         };
     },

package/dist/tools/builtins/search-tools.js.map

@@ -1 +1 @@
-{"version":3,"file":"search-tools.js","sourceRoot":"","sources":["../../../src/tools/builtins/search-tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;CAC3E,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAC;IACzC,IAAI,EAAE,cAAc;IACpB,WAAW,EACV,yDAAyD;QACzD,qFAAqF;IACtF,WAAW;IACX,QAAQ,EAAE,UAAU;IACpB,WAAW,EAAE,EAAE;IACf,QAAQ,EAAE,IAAI;IACd,WAAW,EAAE,KAAK;IAClB,eAAe,EAAE,IAAI;IAErB,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO;QAC3B,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC;YAC3B,OAAO;gBACN,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,EAAE;gBACV,KAAK,EAAE,8CAA8C;aACrD,CAAA;QACF,CAAC;QAED,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QAEhE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO;gBACN,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,+BAA+B,KAAK,CAAC,KAAK,2CAA2C;aAC7F,CAAA;QACF,CAAC;QAED,OAAO,CAAC,YAAY,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;QAEzD,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAEnF,OAAO;YACN,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,aAAa,OAAO,CAAC,MAAM,cAAc,YAAY,EAAE;YAC/D,IAAI,EAAE;gBACL,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;gBACrC,KAAK,EAAE,OAAO,CAAC,MAAM;aACrB;SACD,CAAA;IACF,CAAC;CACD,CAAC,CAAA"}
+{"version":3,"file":"search-tools.js","sourceRoot":"","sources":["../../../src/tools/builtins/search-tools.ts"],"names":[],"mappings":"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"}

package/dist/tools/builtins/verify-outputs.d.ts

@@ -0,0 +1,5 @@
+export declare const VerifyOutputsTool: import("../../types/tool/index.js").ToolDefinition<{
+    paths: string[];
+    min_bytes?: number | undefined;
+}>;
+//# sourceMappingURL=verify-outputs.d.ts.map

package/dist/tools/builtins/verify-outputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-outputs.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/verify-outputs.ts"],"names":[],"mappings":"AA6BA,eAAO,MAAM,iBAAiB;;;EAyC5B,CAAA"}

package/dist/tools/builtins/verify-outputs.js

@@ -0,0 +1,103 @@
+import { stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { defineTool } from '../defineTool.js';
+const inputSchema = z.object({
+    paths: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe('Expected output file paths to verify. Each path is checked for existence and size.'),
+    min_bytes: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe('Minimum acceptable file size in bytes. A file under this size counts as missing. Default: 1 (any non-empty file passes).'),
+});
+export const VerifyOutputsTool = defineTool({
+    name: 'verify_outputs',
+    description: "Verify that a set of expected output files actually exist on disk and are non-empty. Use this BEFORE declaring multi-worker work done — pass every expected output path the workers were supposed to produce. Returns a per-path report (exists, size_bytes, ok) plus an overall pass/fail summary. If any path fails, spawn a fresh `create_task` on the responsible specialist with a brief that names the missing path and the prior worker's output location — do NOT paper over a missing file in prose.",
+    inputSchema,
+    category: 'filesystem',
+    permissions: ['file_read'],
+    readOnly: true,
+    destructive: false,
+    concurrencySafe: true,
+    async execute(input, context) {
+        const minBytes = input.min_bytes ?? 1;
+        const results = await Promise.all(input.paths.map((path) => verifyOne({ path, minBytes, context })));
+        const passed = results.filter((r) => r.ok).length;
+        const failed = results.filter((r) => !r.ok);
+        const summary = {
+            total: results.length,
+            passed,
+            failed: failed.length,
+            min_bytes: minBytes,
+        };
+        const lines = results.map((r) => r.ok
+            ? `- OK   ${r.path}${typeof r.size_bytes === 'number' ? ` (${r.size_bytes}B)` : ''}`
+            : `- FAIL ${r.path} — ${r.error ?? (r.exists ? `size ${r.size_bytes ?? 0}B < min ${minBytes}B` : 'missing')}`);
+        const header = `Verify outputs: ${passed}/${results.length} passed (min ${minBytes}B)`;
+        return {
+            success: failed.length === 0,
+            output: [header, '', ...lines].join('\n'),
+            error: failed.length > 0
+                ? `${failed.length} of ${results.length} expected outputs failed verification`
+                : undefined,
+            data: { results, summary },
+        };
+    },
+});
+async function verifyOne(input) {
+    const { path, minBytes, context } = input;
+    if (context.sandbox) {
+        try {
+            const buffer = await context.sandbox.readFile(path);
+            const size = buffer.byteLength;
+            return {
+                path,
+                exists: true,
+                size_bytes: size,
+                ok: size >= minBytes,
+            };
+        }
+        catch (err) {
+            return {
+                path,
+                exists: false,
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    const filePath = resolve(context.workingDirectory, path);
+    try {
+        const info = await stat(filePath);
+        if (!info.isFile()) {
+            return {
+                path,
+                exists: true,
+                ok: false,
+                error: 'not a regular file',
+            };
+        }
+        return {
+            path,
+            exists: true,
+            size_bytes: info.size,
+            ok: info.size >= minBytes,
+        };
+    }
+    catch (err) {
+        const code = err?.code;
+        if (code === 'ENOENT')
+            return { path, exists: false, ok: false };
+        return {
+            path,
+            exists: false,
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+//# sourceMappingURL=verify-outputs.js.map

package/dist/tools/builtins/verify-outputs.js.map

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

package/dist/tools/builtins/write-file.d.ts

@@ -1,5 +1,6 @@
-export declare const WriteFileTool: import("../../public-types.js").ToolDefinition<{
+export declare const WriteFileTool: import("../../types/tool/index.js").ToolDefinition<{
     path: string;
-    content: string;
+    content?: string | undefined;
+    newStr?: string | undefined;
 }>;
 //# sourceMappingURL=write-file.d.ts.map

package/dist/tools/builtins/write-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"write-file.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/write-file.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,aAAa;;;EAiCxB,CAAA"}
+{"version":3,"file":"write-file.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/write-file.ts"],"names":[],"mappings":"AAiCA,eAAO,MAAM,aAAa;;;;EA+CxB,CAAA"}

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

@@ -1,14 +1,28 @@
-import { mkdir, writeFile } from 'node:fs/promises';
+import { access, mkdir, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { z } from 'zod';
 import { defineTool } from '../defineTool.js';
-const inputSchema = z.object({
-    path: z.string().describe('Path to the file to write'),
-    content: z.string().describe('Content to write to the file'),
+const inputSchema = z
+    .object({
+    path: z
+        .string()
+        .min(1)
+        .describe('Relative path to the file to write (e.g. "outputs/report.md"). Required. Must be a non-empty string.'),
+    content: z
+        .string()
+        .optional()
+        .describe('Full file body to write. Required (use "" only for an intentionally empty file). The file is fully overwritten — pass the COMPLETE intended content for this bounded chunk, not a diff. Self-budget content under 12000 characters before calling; if the intended body is longer, write a smaller opening section here, then use `edit` with insertLine: "end" to extend the file section by section. Do NOT try to chain multiple `write` calls, since each one overwrites the previous.'),
+    newStr: z
+        .string()
+        .optional()
+        .describe('Alias for content. Useful for hosts that expose create/write operations as newStr. Self-budget this payload under 12000 characters before calling.'),
+})
+    .refine((value) => typeof value.content === 'string' || typeof value.newStr === 'string', {
+    message: 'Either content or newStr is required.',
 });
 export const WriteFileTool = defineTool({
-    name: 'write_file',
-    description: 'Writes content to a file. Creates the file if it does not exist, overwrites if it does. Creates intermediate directories as needed.',
+    name: 'write',
+    description: 'Writes a file to the local filesystem. Overwrites the existing file at the path if there is one.\n\n- If the file already exists, you must use the `read` tool on it first in this conversation, or this call will fail.\n- Prefer the `edit` tool for modifying existing files — it only sends the diff and preserves the rest of the file byte-for-byte.\n- Use `write` to create a new file or to perform a deliberate full rewrite of a file you have already read.\n- Self-budget content/newStr under 12000 characters before emitting the tool call. For long content, write a smaller opening section, then use `edit` with insertLine: "end" to extend the file section by section. Do not chain multiple `write` calls — each one overwrites the previous.',
     inputSchema,
     category: 'filesystem',
     permissions: ['file_write'],
@@ -16,23 +30,69 @@ export const WriteFileTool = defineTool({
     destructive: true,
     concurrencySafe: false,
     async execute(input, context) {
+        const content = input.content ?? input.newStr ?? '';
         // Sandbox-aware: route through sandbox.writeFile() when available
         if (context.sandbox) {
-            await context.sandbox.writeFile(input.path, input.content);
+            const sandboxExists = await sandboxFileExists(context, input.path);
+            if (sandboxExists) {
+                const guard = enforceReadBeforeOverwrite(context, input.path);
+                if (guard)
+                    return guard;
+            }
+            await context.sandbox.writeFile(input.path, content);
+            context.fileReadTracker?.recordRead(input.path);
             return {
                 success: true,
-                output: `File written successfully: ${input.path} (${input.content.length} chars) [sandboxed]`,
-                data: { path: input.path, size: input.content.length, sandboxed: true },
+                output: `File written successfully: ${input.path} (${content.length} chars) [sandboxed]`,
+                data: { path: input.path, size: content.length, sandboxed: true },
             };
         }
         const filePath = resolve(context.workingDirectory, input.path);
+        const localExists = await pathExists(filePath);
+        if (localExists) {
+            const guard = enforceReadBeforeOverwrite(context, filePath);
+            if (guard)
+                return guard;
+        }
         await mkdir(dirname(filePath), { recursive: true });
-        await writeFile(filePath, input.content, 'utf-8');
+        await writeFile(filePath, content, 'utf-8');
+        context.fileReadTracker?.recordRead(filePath);
         return {
             success: true,
-            output: `File written successfully: ${filePath} (${input.content.length} chars)`,
-            data: { path: filePath, size: input.content.length },
+            output: `File written successfully: ${filePath} (${content.length} chars)`,
+            data: { path: filePath, size: content.length },
         };
     },
 });
+function enforceReadBeforeOverwrite(context, key) {
+    if (!context.fileReadTracker)
+        return null;
+    if (context.fileReadTracker.hasRead(key))
+        return null;
+    return {
+        success: false,
+        output: '',
+        error: `${key} already exists. Use the \`read\` tool on it first in this conversation, then call \`write\` again — or prefer \`edit\` for a targeted change.`,
+    };
+}
+async function pathExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function sandboxFileExists(context, path) {
+    if (!context.sandbox)
+        return false;
+    try {
+        await context.sandbox.readFile(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 //# sourceMappingURL=write-file.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"write-file.js","sourceRoot":"","sources":["../../../src/tools/builtins/write-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACnD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;IACtD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;CAC5D,CAAC,CAAA;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;IACvC,IAAI,EAAE,YAAY;IAClB,WAAW,EACV,qIAAqI;IACtI,WAAW;IACX,QAAQ,EAAE,YAAY;IACtB,WAAW,EAAE,CAAC,YAAY,CAAC;IAC3B,QAAQ,EAAE,KAAK;IACf,WAAW,EAAE,IAAI;IACjB,eAAe,EAAE,KAAK;IAEtB,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO;QAC3B,kEAAkE;QAClE,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAA;YAC1D,OAAO;gBACN,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,8BAA8B,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,CAAC,MAAM,qBAAqB;gBAC9F,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE;aACvE,CAAA;QACF,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,gBAAgB,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QAE9D,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACnD,MAAM,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QAEjD,OAAO;YACN,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,8BAA8B,QAAQ,KAAK,KAAK,CAAC,OAAO,CAAC,MAAM,SAAS;YAChF,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE;SACpD,CAAA;IACF,CAAC;CACD,CAAC,CAAA"}
+{"version":3,"file":"write-file.js","sourceRoot":"","sources":["../../../src/tools/builtins/write-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAC3D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAE7C,MAAM,WAAW,GAAG,CAAC;KACnB,MAAM,CAAC;IACP,IAAI,EAAE,CAAC;SACL,MAAM,EAAE;SACR,GAAG,CAAC,CAAC,CAAC;SACN,QAAQ,CACR,sGAAsG,CACtG;IACF,OAAO,EAAE,CAAC;SACR,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACR,4dAA4d,CAC5d;IACF,MAAM,EAAE,CAAC;SACP,MAAM,EAAE;SACR,QAAQ,EAAE;SACV,QAAQ,CACR,oJAAoJ,CACpJ;CACF,CAAC;KACD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE;IACzF,OAAO,EAAE,uCAAuC;CAChD,CAAC,CAAA;AAIH,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;IACvC,IAAI,EAAE,OAAO;IACb,WAAW,EACV,suBAAsuB;IACvuB,WAAW;IACX,QAAQ,EAAE,YAAY;IACtB,WAAW,EAAE,CAAC,YAAY,CAAC;IAC3B,QAAQ,EAAE,KAAK;IACf,WAAW,EAAE,IAAI;IACjB,eAAe,EAAE,KAAK;IAEtB,KAAK,CAAC,OAAO,CAAC,KAAiB,EAAE,OAAO;QACvC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,MAAM,IAAI,EAAE,CAAA;QACnD,kEAAkE;QAClE,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACrB,MAAM,aAAa,GAAG,MAAM,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;YAClE,IAAI,aAAa,EAAE,CAAC;gBACnB,MAAM,KAAK,GAAG,0BAA0B,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;gBAC7D,IAAI,KAAK;oBAAE,OAAO,KAAK,CAAA;YACxB,CAAC;YACD,MAAM,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;YACpD,OAAO,CAAC,eAAe,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YAC/C,OAAO;gBACN,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,8BAA8B,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,MAAM,qBAAqB;gBACxF,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE;aACjE,CAAA;QACF,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,gBAAgB,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;QAE9D,MAAM,WAAW,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,CAAA;QAC9C,IAAI,WAAW,EAAE,CAAC;YACjB,MAAM,KAAK,GAAG,0BAA0B,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;YAC3D,IAAI,KAAK;gBAAE,OAAO,KAAK,CAAA;QACxB,CAAC;QAED,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QACnD,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;QAC3C,OAAO,CAAC,eAAe,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAA;QAE7C,OAAO;YACN,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,8BAA8B,QAAQ,KAAK,OAAO,CAAC,MAAM,SAAS;YAC1E,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,MAAM,EAAE;SAC9C,CAAA;IACF,CAAC;CACD,CAAC,CAAA;AAEF,SAAS,0BAA0B,CAClC,OAAoB,EACpB,GAAW;IAEX,IAAI,CAAC,OAAO,CAAC,eAAe;QAAE,OAAO,IAAI,CAAA;IACzC,IAAI,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IACrD,OAAO;QACN,OAAO,EAAE,KAAK;QACd,MAAM,EAAE,EAAE;QACV,KAAK,EAAE,GAAG,GAAG,gJAAgJ;KAC7J,CAAA;AACF,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,QAAgB;IACzC,IAAI,CAAC;QACJ,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAA;QACtB,OAAO,IAAI,CAAA;IACZ,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAA;IACb,CAAC;AACF,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,OAAoB,EAAE,IAAY;IAClE,IAAI,CAAC,OAAO,CAAC,OAAO;QAAE,OAAO,KAAK,CAAA;IAClC,IAAI,CAAC;QACJ,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;QACpC,OAAO,IAAI,CAAA;IACZ,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAA;IACb,CAAC;AACF,CAAC"}

package/dist/tools/coordinator/__tests__/agent.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Behavioural contract for `buildAgentTool`:
+ *
+ * - Reports `success: true` only when BOTH the gateway task state and
+ *   the underlying `BaseAgentResult.status` say completed.
+ * - Reports `success: false` and surfaces `lastError` when either
+ *   layer disagrees — the canonical bug Codex caught was that a
+ *   failed subagent could be reported as successful when the gateway
+ *   forwarded `state: 'completed'` from a manager that did not
+ *   propagate the run's `status: 'failed'`.
+ * - Returns the subagent's `result` string as the tool output on
+ *   success.
+ */
+export {};
+//# sourceMappingURL=agent.test.d.ts.map

package/dist/tools/coordinator/__tests__/agent.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.test.d.ts","sourceRoot":"","sources":["../../../../src/tools/coordinator/__tests__/agent.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}