@namzu/sdk 2.0.0 → 3.0.0

package/dist/telemetry/metrics.js

@@ -0,0 +1,160 @@
+import { metrics } from '@opentelemetry/api';
+import { GENAI, NAMZU } from '../constants/telemetry/index.js';
+/**
+ * The runtime's metric instruments.
+ *
+ * Metrics lived in the telemetry package as a bag a host constructed for
+ * itself — and nothing in the workspace ever constructed one, so the
+ * runtime emitted spans and not a single measurement. Defining them beside
+ * the code that records them is what stops that recurring: an instrument
+ * with no call site is visible here, where a bag with no owner was not.
+ *
+ * Every instrument is resolved LAZILY. Binding eagerly meant that a bag
+ * built before `registerTelemetry()` captured the no-op meter and threw
+ * every write away for the rest of its life — silently, and forever, from
+ * one line of call-order. Ordering is not something a caller should have
+ * to get right to be measured at all.
+ */
+let cached;
+function build(meter) {
+    return {
+        // ONE counter for every token, split by `gen_ai.token.type`. It was
+        // two counters under two names, the second of them invented — so a
+        // dashboard aggregating the conventional name got input tokens only
+        // and under-reported usage by roughly half, with nothing to suggest
+        // the other half existed.
+        tokens: meter.createCounter('gen_ai.client.token.usage', {
+            description: 'Tokens used, by type',
+            unit: '{token}',
+        }),
+        toolCalls: meter.createCounter('gen_ai.tool.call.count', {
+            description: 'Tool calls executed',
+            unit: '{call}',
+        }),
+        runDuration: meter.createHistogram('namzu.run.duration', {
+            description: 'Agent run duration',
+            unit: 's',
+        }),
+        llmDuration: meter.createHistogram('gen_ai.client.operation.duration', {
+            description: 'Model request duration',
+            unit: 's',
+        }),
+        // namzu streams, so perceived latency is dominated by how long the
+        // user waits for the FIRST token, not by how long the whole request
+        // takes. The request histogram above cannot tell a fast-first-token
+        // long generation from a stalled one, and no host could recover the
+        // distinction from namzu's data in any form.
+        timeToFirstToken: meter.createHistogram('gen_ai.client.time_to_first_token', {
+            description: 'Time from request start to the first content delta',
+            unit: 's',
+        }),
+        // The wall clock was measured since the first version of the executor
+        // and emitted per call on `tool_completed`, so a p95 was computable
+        // from events — but there was no instrument, with the value already
+        // in scope one frame above the call site.
+        toolDuration: meter.createHistogram('gen_ai.tool.call.duration', {
+            description: 'Tool execution duration',
+            unit: 's',
+        }),
+    };
+}
+/**
+ * Resolve instruments against the meter that is live *now*.
+ *
+ * Cached against the meter identity rather than unconditionally: rebuilding
+ * on every call would allocate on a hot path, and never rebuilding is the
+ * bug this replaces. When `registerTelemetry()` swaps the global provider
+ * the meter changes, the cache misses once, and everything after that is
+ * recorded through the real one.
+ */
+function instruments() {
+    const meter = metrics.getMeter('namzu');
+    if (cached?.meter === meter)
+        return cached.instruments;
+    const built = build(meter);
+    cached = { meter, instruments: built };
+    return built;
+}
+/** Drop the cache. Tests that swap the global provider need this. */
+export function resetRuntimeMetrics() {
+    cached = undefined;
+}
+/**
+ * Record what a turn cost, split by token type.
+ *
+ * Cache reads and writes are recorded as their own types rather than
+ * folded into `input`. They bill differently — a read is a fraction of the
+ * input rate and a write is a premium on it — so a total that hides them
+ * cannot explain a bill, which is the main thing anyone asks a token
+ * metric.
+ */
+export function recordTokenUsage(model, usage) {
+    const { tokens } = instruments();
+    if (usage.promptTokens > 0) {
+        tokens.add(usage.promptTokens, {
+            [GENAI.REQUEST_MODEL]: model,
+            [GENAI.TOKEN_TYPE]: 'input',
+        });
+    }
+    if (usage.completionTokens > 0) {
+        tokens.add(usage.completionTokens, {
+            [GENAI.REQUEST_MODEL]: model,
+            [GENAI.TOKEN_TYPE]: 'output',
+        });
+    }
+    if (usage.cachedTokens !== undefined && usage.cachedTokens > 0) {
+        tokens.add(usage.cachedTokens, {
+            [GENAI.REQUEST_MODEL]: model,
+            [GENAI.TOKEN_TYPE]: 'cache_read',
+        });
+    }
+    if (usage.cacheWriteTokens !== undefined && usage.cacheWriteTokens > 0) {
+        tokens.add(usage.cacheWriteTokens, {
+            [GENAI.REQUEST_MODEL]: model,
+            [GENAI.TOKEN_TYPE]: 'cache_write',
+        });
+    }
+}
+/**
+ * Record a tool call.
+ *
+ * `errorType` carries WHY a call failed rather than only that it did. A
+ * flat success rate cannot separate a tool that is broken from one whose
+ * input the model keeps getting wrong, and those need different fixes.
+ */
+export function recordToolCall(toolName, success, errorType, durationMs) {
+    const attributes = {
+        [GENAI.TOOL_NAME]: toolName,
+        [NAMZU.TOOL_SUCCESS]: success,
+        ...(errorType !== undefined ? { [NAMZU.TOOL_ERROR]: errorType } : {}),
+    };
+    const { toolCalls, toolDuration } = instruments();
+    toolCalls.add(1, attributes);
+    // Same attributes as the count, so "which tool is slow" and "which tool
+    // fails" are answerable from one query rather than two that cannot be
+    // joined.
+    if (durationMs !== undefined)
+        toolDuration.record(durationMs / 1000, attributes);
+}
+/**
+ * Record how long the first content delta took to arrive.
+ *
+ * Recorded at the first delta rather than at the end of the request,
+ * because the two are not the same measurement and only this one tracks
+ * what a person waiting actually experiences.
+ */
+export function recordTimeToFirstToken(model, durationMs) {
+    instruments().timeToFirstToken.record(durationMs / 1000, { [GENAI.REQUEST_MODEL]: model });
+}
+/** Record how long a whole run took, keyed by how it settled. */
+export function recordRunDuration(status, durationMs) {
+    instruments().runDuration.record(durationMs / 1000, { [NAMZU.RUN_STATUS]: status });
+}
+/** Record how long one model request took. */
+export function recordModelDuration(model, durationMs, errorType) {
+    instruments().llmDuration.record(durationMs / 1000, {
+        [GENAI.REQUEST_MODEL]: model,
+        ...(errorType !== undefined ? { [NAMZU.TOOL_ERROR]: errorType } : {}),
+    });
+}
+//# sourceMappingURL=metrics.js.map

package/dist/telemetry/metrics.js.map

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

package/dist/test-setup.d.ts

@@ -11,9 +11,9 @@
  * `ToolRegistry.execute`'s zod-validation and thrown-error branches,
  * `ConnectorToolRouter.getTools`' per-instance error catch, the
  * AgentBus listener-throw handler, and every connector's `connect()`
- * info log. GitHub Actions annotates any `[ERROR]` stderr line as a
- * workflow error; silencing the root logger during tests keeps the CI
- * log clean.
+ * info log. CI annotates any `[ERROR]` stderr line as a workflow
+ * error; silencing the root logger during tests keeps the CI log
+ * clean.
  *
  * This is test-only configuration. It runs before every test file and
  * does not affect consumers.

package/dist/test-setup.js

@@ -11,9 +11,9 @@
  * `ToolRegistry.execute`'s zod-validation and thrown-error branches,
  * `ConnectorToolRouter.getTools`' per-instance error catch, the
  * AgentBus listener-throw handler, and every connector's `connect()`
- * info log. GitHub Actions annotates any `[ERROR]` stderr line as a
- * workflow error; silencing the root logger during tests keeps the CI
- * log clean.
+ * info log. CI annotates any `[ERROR]` stderr line as a workflow
+ * error; silencing the root logger during tests keeps the CI log
+ * clean.
  *
  * This is test-only configuration. It runs before every test file and
  * does not affect consumers.

package/dist/test-support/paths.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Test-only path helpers.
+ *
+ * `node:path.join` produces platform-native separators, which is correct —
+ * the SDK should hand the OS the paths the OS expects. Assertions written
+ * as POSIX string literals therefore fail on Windows even though the code
+ * is right, which used to leave three suites permanently red for every
+ * Windows contributor. Compare path *structure* instead of separator style.
+ */
+/** Normalize a path's separators so an assertion can be written once. */
+export declare function posix(p: string | undefined): string;
+/** True when running on Windows, for the few cases that cannot be normalized away. */
+export declare const IS_WINDOWS: boolean;
+//# sourceMappingURL=paths.d.ts.map

package/dist/test-support/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/test-support/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,yEAAyE;AACzE,wBAAgB,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEnD;AAED,sFAAsF;AACtF,eAAO,MAAM,UAAU,SAA+B,CAAA"}

package/dist/test-support/paths.js

@@ -0,0 +1,16 @@
+/**
+ * Test-only path helpers.
+ *
+ * `node:path.join` produces platform-native separators, which is correct —
+ * the SDK should hand the OS the paths the OS expects. Assertions written
+ * as POSIX string literals therefore fail on Windows even though the code
+ * is right, which used to leave three suites permanently red for every
+ * Windows contributor. Compare path *structure* instead of separator style.
+ */
+/** Normalize a path's separators so an assertion can be written once. */
+export function posix(p) {
+    return (p ?? '').replaceAll('\\', '/');
+}
+/** True when running on Windows, for the few cases that cannot be normalized away. */
+export const IS_WINDOWS = process.platform === 'win32';
+//# sourceMappingURL=paths.js.map

package/dist/test-support/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/test-support/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,yEAAyE;AACzE,MAAM,UAAU,KAAK,CAAC,CAAqB;IAC1C,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;AACvC,CAAC;AAED,sFAAsF;AACtF,MAAM,CAAC,MAAM,UAAU,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAA"}

package/dist/tools/__tests__/path-containment.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=path-containment.test.d.ts.map

package/dist/tools/__tests__/path-containment.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-containment.test.d.ts","sourceRoot":"","sources":["../../../src/tools/__tests__/path-containment.test.ts"],"names":[],"mappings":""}

package/dist/tools/__tests__/path-containment.test.js

@@ -0,0 +1,133 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { GlobTool } from '../builtins/glob.js';
+import { GrepTool } from '../builtins/grep.js';
+import { LsTool } from '../builtins/ls.js';
+import { matchesGlob } from '../glob-match.js';
+import { resolveWithin } from '../paths.js';
+/**
+ * The containment rule existed — in one private function inside the local
+ * sandbox provider — and the filesystem tools never reached it. They
+ * resolved a caller-supplied path against the working directory bare, so
+ * `path: "../../.."` landed wherever that pointed and the tool read it
+ * happily.
+ *
+ * That holds with no sandbox configured at all, which is the common case,
+ * so the escape needed no misconfiguration to reach: a model that asks for
+ * a parent directory gets one. And `grep` returns file CONTENT, so what
+ * escaped was not a listing.
+ */
+let root;
+let outside;
+beforeEach(() => {
+    const base = mkdtempSync(join(tmpdir(), 'namzu-containment-'));
+    root = join(base, 'workspace');
+    outside = join(base, 'secrets');
+    mkdirSync(root, { recursive: true });
+    mkdirSync(outside, { recursive: true });
+    writeFileSync(join(root, 'inside.ts'), 'const inside = true\n');
+    writeFileSync(join(outside, 'credentials.txt'), 'SECRET_TOKEN=hunter2\n');
+});
+afterEach(() => {
+    rmSync(resolve(root, '..'), { recursive: true, force: true });
+});
+const context = () => ({
+    workingDirectory: root,
+    env: {},
+    abortSignal: new AbortController().signal,
+});
+describe('resolveWithin', () => {
+    it('accepts a path inside the root', () => {
+        expect(resolveWithin('/work', 'src/a.ts')).toBe(resolve('/work/src/a.ts'));
+    });
+    it('treats an absent path as the root itself', () => {
+        expect(resolveWithin('/work', undefined)).toBe(resolve('/work'));
+    });
+    it('refuses a climb out', () => {
+        expect(() => resolveWithin('/work', '../../..')).toThrow(/escapes the working directory/);
+    });
+    it('refuses an absolute path elsewhere', () => {
+        expect(() => resolveWithin('/work', '/etc/passwd')).toThrow(/escapes the working directory/);
+    });
+    it('refuses a sibling that merely shares a prefix', () => {
+        // A `startsWith` test would call this inside, which is the whole
+        // reason the check uses `relative`.
+        expect(() => resolveWithin('/work', '../work-backup')).toThrow(/escapes/);
+    });
+    it('allows a climb that lands back inside', () => {
+        expect(resolveWithin('/work', 'src/../lib/a.ts')).toBe(resolve('/work/lib/a.ts'));
+    });
+});
+describe('glob', () => {
+    it('refuses a path that climbs out', async () => {
+        const result = await GlobTool.execute({ pattern: '*.txt', path: '../secrets' }, context());
+        // A refusal reaches the model as a failed tool result rather than a
+        // throw, so it can read WHY and correct itself.
+        expect(result.success).toBe(false);
+        expect(result.error).toMatch(/escapes the working directory/);
+    });
+    it('refuses an escape hidden in the pattern', async () => {
+        // The base directory lifted out of a pattern is caller-supplied too.
+        const result = await GlobTool.execute({ pattern: '../secrets/**/*.txt' }, context());
+        expect(result.success).toBe(false);
+        expect(result.error).toMatch(/escapes the working directory/);
+    });
+    it('still finds what is inside', async () => {
+        const result = await GlobTool.execute({ pattern: '**/*.ts' }, context());
+        expect(result.success).toBe(true);
+        expect(result.output).toContain('inside.ts');
+    });
+});
+describe('grep', () => {
+    it('refuses a path that climbs out', async () => {
+        const result = await GrepTool.execute({
+            pattern: 'SECRET',
+            path: '../secrets',
+            case_sensitive: true,
+            context_lines: 0,
+            max_results: 10,
+        }, context());
+        expect(result.success).toBe(false);
+        expect(result.error).toMatch(/escapes the working directory/);
+        expect(JSON.stringify(result)).not.toContain('hunter2');
+    });
+    it('never returns content from outside the working directory', async () => {
+        const result = await GrepTool.execute({ pattern: 'SECRET', case_sensitive: true, context_lines: 0, max_results: 50 }, context());
+        // grep returns file CONTENT, so an escape here reads rather than lists.
+        expect(result.output).not.toContain('hunter2');
+    });
+    it('still finds what is inside', async () => {
+        const result = await GrepTool.execute({ pattern: 'inside', case_sensitive: true, context_lines: 0, max_results: 50 }, context());
+        expect(result.output).toContain('inside.ts');
+    });
+});
+describe('ls', () => {
+    it('refuses a path that climbs out', async () => {
+        const result = await LsTool.execute({ path: '../secrets' }, context());
+        expect(result.success).toBe(false);
+        expect(result.error).toMatch(/escapes the working directory/);
+    });
+});
+describe('glob matching', () => {
+    it.each([
+        ['**/*.ts', 'src/a.ts', true],
+        ['**/*.ts', 'a.ts', true],
+        ['*.ts', 'a.ts', true],
+        ['*.ts', 'src/a.ts', false],
+        ['src/*.ts', 'src/a.ts', true],
+        ['src/*.ts', 'src/deep/a.ts', false],
+        ['**/*.ts', 'a.tsx', false],
+        ['a?.ts', 'ab.ts', true],
+        ['a?.ts', 'abc.ts', false],
+    ])('%s vs %s', (pattern, path, expected) => {
+        expect(matchesGlob(path, pattern)).toBe(expected);
+    });
+    it('treats regex punctuation in a pattern as literal', () => {
+        // A pattern is not a regex; `a.b` must not match `axb`.
+        expect(matchesGlob('a.b.ts', 'a.b.ts')).toBe(true);
+        expect(matchesGlob('axb.ts', 'a.b.ts')).toBe(false);
+    });
+});
+//# sourceMappingURL=path-containment.test.js.map

package/dist/tools/__tests__/path-containment.test.js.map

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

package/dist/tools/__tests__/posix-path.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=posix-path.test.d.ts.map

package/dist/tools/__tests__/posix-path.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"posix-path.test.d.ts","sourceRoot":"","sources":["../../../src/tools/__tests__/posix-path.test.ts"],"names":[],"mappings":""}

package/dist/tools/__tests__/posix-path.test.js

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { joinPosix, relativePosix, resolveWithinPosix } from '../posix-path.js';
+/**
+ * A sandbox is a POSIX filesystem whatever the host runs, so resolving its
+ * paths with the host's path module rewrites them whenever the two
+ * disagree — on a Windows host `resolve('/workspace')` becomes
+ * `C:\workspace`, and a container path stops being a container path. The
+ * tool then hands the model a string its own sandbox cannot open.
+ *
+ * Found while testing the sandboxed search: the fake sandbox returned
+ * nothing at all, because the paths it was asked for had been rewritten
+ * into host shape on the way through.
+ */
+describe('joinPosix', () => {
+    it('joins and keeps the leading slash', () => {
+        expect(joinPosix('/work', 'src', 'a.ts')).toBe('/work/src/a.ts');
+    });
+    it('normalises . and ..', () => {
+        expect(joinPosix('/work', 'src/../lib/a.ts')).toBe('/work/lib/a.ts');
+    });
+    it('collapses repeated separators', () => {
+        expect(joinPosix('/work//', '/src//a.ts')).toBe('/work/src/a.ts');
+    });
+    it('leaves a relative base relative', () => {
+        expect(joinPosix('work', 'a.ts')).toBe('work/a.ts');
+    });
+    it('never produces a host-shaped path', () => {
+        // The whole point: this must not become `C:\work\a.ts` anywhere.
+        expect(joinPosix('/work', 'a.ts')).not.toContain('\\');
+    });
+});
+describe('relativePosix', () => {
+    it('strips a shared prefix', () => {
+        expect(relativePosix('/work', '/work/src/a.ts')).toBe('src/a.ts');
+    });
+    it('returns empty for the root itself', () => {
+        expect(relativePosix('/work', '/work')).toBe('');
+    });
+    it('climbs out when it has to', () => {
+        expect(relativePosix('/work/src', '/work/lib/a.ts')).toBe('../lib/a.ts');
+    });
+    it('does not treat a prefix-sharing sibling as inside', () => {
+        expect(relativePosix('/work', '/work-backup/a.ts').startsWith('..')).toBe(true);
+    });
+});
+describe('resolveWithinPosix', () => {
+    it('accepts a path inside the root', () => {
+        expect(resolveWithinPosix('/work', 'src/a.ts')).toBe('/work/src/a.ts');
+    });
+    it('treats an absent path as the root', () => {
+        expect(resolveWithinPosix('/work', undefined)).toBe('/work');
+    });
+    it('refuses a climb out', () => {
+        expect(() => resolveWithinPosix('/work', '../../etc')).toThrow(/escapes the working directory/);
+    });
+    it('refuses a prefix-sharing sibling', () => {
+        expect(() => resolveWithinPosix('/work', '../work-backup')).toThrow(/escapes/);
+    });
+    it('takes an absolute candidate as sandbox-absolute', () => {
+        expect(resolveWithinPosix('/work', '/work/src')).toBe('/work/src');
+        expect(() => resolveWithinPosix('/work', '/etc/passwd')).toThrow(/escapes/);
+    });
+    it('allows a climb that lands back inside', () => {
+        expect(resolveWithinPosix('/work', 'src/../lib')).toBe('/work/lib');
+    });
+});
+//# sourceMappingURL=posix-path.test.js.map

package/dist/tools/__tests__/posix-path.test.js.map

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

package/dist/tools/__tests__/sandboxed-search.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sandboxed-search.test.d.ts.map

package/dist/tools/__tests__/sandboxed-search.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandboxed-search.test.d.ts","sourceRoot":"","sources":["../../../src/tools/__tests__/sandboxed-search.test.ts"],"names":[],"mappings":""}

package/dist/tools/__tests__/sandboxed-search.test.js

@@ -0,0 +1,114 @@
+import { describe, expect, it, vi } from 'vitest';
+import { GlobTool } from '../builtins/glob.js';
+import { GrepTool } from '../builtins/grep.js';
+/**
+ * Both tools reached `node:fs` directly and referenced `context.sandbox`
+ * nowhere, so with a container backend wired in the sandbox was not a read
+ * boundary at all — every sibling builtin already remembered the branch.
+ *
+ * The paths they returned were host-relative too, while `read` resolves
+ * what it is handed INSIDE the sandbox, so every search-to-read handoff
+ * either failed or opened a different file. The two roots genuinely
+ * diverge: the executor passes `workingDirectory` unchanged alongside the
+ * sandbox and never re-points it at `sandbox.rootDir`.
+ */
+const SANDBOX_ROOT = '/sandbox/workspace';
+const HOST_ROOT = '/host/elsewhere';
+function fakeSandbox(files) {
+    const reads = [];
+    return {
+        id: 'sbx_test',
+        rootDir: SANDBOX_ROOT,
+        reads,
+        exec: vi.fn(),
+        writeFile: vi.fn(),
+        readFile: vi.fn(async (path) => {
+            reads.push(path);
+            const key = path.startsWith(SANDBOX_ROOT) ? path.slice(SANDBOX_ROOT.length + 1) : path;
+            const content = files[key.split('\\').join('/')];
+            if (content === undefined)
+                throw new Error(`no such file: ${path}`);
+            return Buffer.from(content, 'utf-8');
+        }),
+        listFiles: vi.fn(async () => Object.keys(files).map((path) => ({ path, size: files[path]?.length ?? 0 }))),
+        destroy: vi.fn(),
+        status: vi.fn(),
+    };
+}
+const context = (sandbox) => ({
+    // Deliberately different from the sandbox root: the executor passes
+    // the host working directory through unchanged, so a tool that
+    // reads this one is reading the wrong filesystem.
+    workingDirectory: HOST_ROOT,
+    sandbox,
+    env: {},
+    abortSignal: new AbortController().signal,
+});
+describe('glob inside a sandbox', () => {
+    it('enumerates through the sandbox, not the host', async () => {
+        const sandbox = fakeSandbox({ 'src/a.ts': 'a', 'src/b.js': 'b' });
+        const result = await GlobTool.execute({ pattern: '**/*.ts' }, context(sandbox));
+        expect(sandbox.listFiles).toHaveBeenCalled();
+        expect(result.output).toContain('src/a.ts');
+        expect(result.output).not.toContain('b.js');
+    });
+    it('returns paths the sandbox-side reader can actually open', async () => {
+        const sandbox = fakeSandbox({ 'src/a.ts': 'a' });
+        const result = await GlobTool.execute({ pattern: '**/*.ts' }, context(sandbox));
+        // A host-relative path here is a string `read` resolves somewhere
+        // else, so the handoff between the two tools has to agree on a
+        // coordinate system.
+        expect(result.output).not.toContain(HOST_ROOT);
+        expect(result.output.trim()).toBe('./src/a.ts');
+    });
+    it('says it searched the sandbox', async () => {
+        const sandbox = fakeSandbox({ 'a.ts': 'a' });
+        const result = await GlobTool.execute({ pattern: '**/*.ts' }, context(sandbox));
+        expect(result.data.sandboxed).toBe(true);
+    });
+    it('refuses a path that climbs out of the sandbox root', async () => {
+        const sandbox = fakeSandbox({ 'a.ts': 'a' });
+        const result = await GlobTool.execute({ pattern: '*.ts', path: '../../etc' }, context(sandbox));
+        expect(result.success).toBe(false);
+        expect(result.error).toMatch(/escapes the working directory/);
+    });
+});
+describe('grep inside a sandbox', () => {
+    const args = (extra = {}) => ({
+        pattern: 'needle',
+        case_sensitive: true,
+        context_lines: 0,
+        max_results: 50,
+        ...extra,
+    });
+    it('reads through the sandbox, not the host', async () => {
+        const sandbox = fakeSandbox({ 'src/a.ts': 'a needle here\n' });
+        const result = await GrepTool.execute(args(), context(sandbox));
+        expect(sandbox.readFile).toHaveBeenCalled();
+        // Asserted on the MATCH line, not on the word. The no-matches
+        // message quotes the pattern back, so checking for "needle" alone
+        // passed on a search that found nothing — which is exactly what this
+        // test existed to catch.
+        expect(result.output).toContain('a needle here');
+        expect(result.output).toContain('Found 1 match');
+    });
+    it('reports paths relative to the sandbox root', async () => {
+        const sandbox = fakeSandbox({ 'src/a.ts': 'a needle here\n' });
+        const result = await GrepTool.execute(args(), context(sandbox));
+        expect(result.output).toContain('./src/a.ts');
+        expect(result.output).not.toContain(HOST_ROOT);
+    });
+    it('honours the include filter through the sandbox listing', async () => {
+        const sandbox = fakeSandbox({ 'a.ts': 'needle\n', 'b.md': 'needle\n' });
+        const result = await GrepTool.execute(args({ include: '*.ts' }), context(sandbox));
+        expect(result.output).toContain('a.ts');
+        expect(result.output).not.toContain('b.md');
+    });
+    it('refuses a path that climbs out of the sandbox root', async () => {
+        const sandbox = fakeSandbox({ 'a.ts': 'needle\n' });
+        const result = await GrepTool.execute(args({ path: '../../etc' }), context(sandbox));
+        expect(result.success).toBe(false);
+        expect(result.error).toMatch(/escapes the working directory/);
+    });
+});
+//# sourceMappingURL=sandboxed-search.test.js.map

package/dist/tools/__tests__/sandboxed-search.test.js.map

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

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

@@ -104,12 +104,22 @@ describe('createComputerUseTool', () => {
         expect(result.error).toContain('cursorPosition');
         expect(calls).toHaveLength(0);
     });
-    it('returns base64 PNG output for screenshot', async () => {
+    it('returns the screenshot as an image BLOCK, not as base64 text', async () => {
         const { host } = makeHost();
         const tool = createComputerUseTool(host);
         const result = await tool.execute({ type: 'screenshot' }, makeContext());
         expect(result.success).toBe(true);
-        expect(Buffer.from(result.output, 'base64').slice(0, 4)).toEqual(Buffer.from([0x89, 0x50, 0x4e, 0x47]));
+        // `output` used to BE the base64 payload, so the model received
+        // hundreds of thousands of tokens of undecodable characters and
+        // could not see the screen at all. It is now a short description.
+        expect(result.output).toContain('1920x1080');
+        expect(result.output.length).toBeLessThan(200);
+        const blocks = result.content;
+        expect(Array.isArray(blocks)).toBe(true);
+        const image = blocks[0];
+        expect(image?.type).toBe('image');
+        expect(image?.mediaType).toBe('image/png');
+        expect(Buffer.from(image?.data ?? '', 'base64').subarray(0, 4)).toEqual(Buffer.from([0x89, 0x50, 0x4e, 0x47]));
         expect(result.data).toMatchObject({
             mimeType: 'image/png',
             width: 1920,