xcoder-jarvis-agent 0.0.0-stage → 1.3.0

package/dist/jarvis/react-loop.js

@@ -0,0 +1,160 @@
+import { BudgetExceeded } from "./budget.js";
+import { parseDecision, ReactParseError } from "./decision.js";
+import { wrapObservation } from "./prompt/assemble.js";
+/**
+ * The ReAct loop, owned in-package (design §2.4, tradeoff T1).
+ *
+ * The shared `GenesisReActOrchestrator` in xcoder-dna could not be reused: its
+ * tool registry is internal and non-injectable, which would mean shipping an
+ * agent whose tool surface we do not control. Six invariants hold here, each
+ * covered by a test:
+ *  1. iterations never exceed `maxIterations` (clamped to 8 by the caller);
+ *  2. every reply is parsed before any side effect occurs;
+ *  3. a tool not in the registry allowlist is refused in code and fed back as
+ *     an error observation — it is never dispatched;
+ *  4. `isKilled()` is checked before each LLM call and each dispatch;
+ *  5. budget exhaustion yields `budget_exceeded` with no partial answer;
+ *  6. the kill-switch AbortSignal is passed to the tool context.
+ */
+export const MAX_ITERATIONS = 8;
+const CORRECTIVE_NUDGE = "Your previous reply could not be used: it was not a single JSON object " +
+    "matching the required shape. Reply again with exactly one JSON object and " +
+    "no other text. Do not explain, and do not repeat the rejected text.";
+function transcriptWith(transcript, role, content) {
+    return [...transcript, { role, content }];
+}
+/**
+ * Execute one parsed action. The allowlist is enforced by `registry.get()`,
+ * which returns undefined for anything not registered AND allowed — so an
+ * off-list name cannot reach `execute()` at all.
+ */
+async function dispatch(input, decision) {
+    const descriptor = input.registry.get(decision.tool);
+    if (!descriptor) {
+        return {
+            dispatched: false,
+            observation: {
+                ok: false,
+                summary: `refused: tool '${decision.tool}' is not in this run's allowlist (${input.registry
+                    .allowlist()
+                    .join(", ")})`,
+                bytes: 0,
+                truncated: false,
+            },
+        };
+    }
+    const parsedArgs = descriptor.argsSchema.safeParse(decision.args);
+    if (!parsedArgs.success) {
+        const issue = parsedArgs.error.issues[0];
+        return {
+            dispatched: false,
+            observation: {
+                ok: false,
+                summary: `refused: arguments for '${decision.tool}' did not match its schema (${issue?.path.join(".") || "(root)"}: ${issue?.message ?? "invalid"})`,
+                bytes: 0,
+                truncated: false,
+            },
+        };
+    }
+    try {
+        const observation = await descriptor.execute(parsedArgs.data, input.toolContext);
+        return { dispatched: true, observation };
+    }
+    catch {
+        return {
+            dispatched: true,
+            observation: {
+                ok: false,
+                summary: `tool '${decision.tool}' failed while executing`,
+                bytes: 0,
+                truncated: false,
+            },
+        };
+    }
+}
+export async function runReactLoop(i) {
+    const maxIterations = Math.min(MAX_ITERATIONS, Math.max(1, i.maxIterations));
+    let transcript = [{ role: "user", content: i.task }];
+    let iterations = 0;
+    let consecutiveParseFailures = 0;
+    while (iterations < maxIterations) {
+        // (4) kill switch, before the LLM call.
+        if (i.isKilled()) {
+            return { outcome: "aborted", iterations, transcript, error: "kill switch tripped" };
+        }
+        // (5) budget, before spending anything.
+        try {
+            i.budget.check();
+        }
+        catch (err) {
+            if (err instanceof BudgetExceeded) {
+                return { outcome: "budget_exceeded", iterations, transcript, error: err.message };
+            }
+            throw err;
+        }
+        let reply;
+        try {
+            reply = await i.client.complete(i.systemPrompt.system, transcript);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message.slice(0, 300) : "model call failed";
+            return { outcome: "error", iterations, transcript, error: message };
+        }
+        iterations += 1;
+        try {
+            i.budget.chargeUsage(reply.usage);
+            i.budget.countIteration();
+        }
+        catch (err) {
+            if (err instanceof BudgetExceeded) {
+                return { outcome: "budget_exceeded", iterations, transcript, error: err.message };
+            }
+            throw err;
+        }
+        // (2) parse BEFORE any side effect.
+        let decision;
+        try {
+            decision = parseDecision(reply.text);
+            consecutiveParseFailures = 0;
+        }
+        catch (err) {
+            consecutiveParseFailures += 1;
+            const detail = err instanceof ReactParseError ? err.message : "unparseable reply";
+            if (consecutiveParseFailures >= 2) {
+                return {
+                    outcome: "error",
+                    iterations,
+                    transcript,
+                    error: `model reply could not be parsed twice (${detail})`,
+                };
+            }
+            // Observed as data, never as trusted instruction.
+            transcript = transcriptWith(transcriptWith(transcript, "assistant", "[reply rejected: not a valid decision object]"), "user", CORRECTIVE_NUDGE);
+            continue;
+        }
+        transcript = transcriptWith(transcript, "assistant", reply.text);
+        if (decision.kind === "final") {
+            return {
+                outcome: "answered",
+                answer: decision.answer,
+                iterations,
+                transcript,
+            };
+        }
+        // (4) kill switch again, before dispatching a tool.
+        if (i.isKilled()) {
+            return { outcome: "aborted", iterations, transcript, error: "kill switch tripped" };
+        }
+        // (3) allowlist + args schema, enforced in code.
+        const { observation, dispatched } = await dispatch(i, decision);
+        if (dispatched)
+            i.onToolUsed?.(decision.tool, observation);
+        transcript = transcriptWith(transcript, "user", wrapObservation(decision.tool, observation.summary));
+    }
+    return {
+        outcome: "iteration_limit",
+        iterations,
+        transcript,
+        error: `reached the ${maxIterations}-iteration limit without a final answer`,
+    };
+}

package/dist/jarvis/telemetry/provenance.d.ts

@@ -0,0 +1,54 @@
+export type JarvisOutcome = "answered" | "iteration_limit" | "budget_exceeded" | "aborted" | "error";
+export interface ProvenanceRecord {
+    v: 1;
+    runId: string;
+    ts: string;
+    agent: string;
+    version: string;
+    workspaceId: string;
+    userId: string;
+    session: string;
+    policyVersion: string;
+    policySha256: string;
+    skills: Array<{
+        name: string;
+        sha256: string;
+    }>;
+    skippedSkills: Array<{
+        name: string;
+        reason: string;
+    }>;
+    toolAllowlist: readonly string[];
+    toolsUsed: Array<{
+        name: string;
+        ok: boolean;
+        bytes: number;
+    }>;
+    iterations: number;
+    outcome: JarvisOutcome;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    memoryWrites: number;
+    redactions: number;
+    error?: string;
+}
+export declare const RETENTION_DAYS = 90;
+/**
+ * Audit record for one run (CORE-08, PRM-10, AI-12).
+ *
+ * The schema itself is the privacy control: it has no field that can hold
+ * prompt text, model replies, file contents, tokens or keys. What is recorded
+ * is identifiers, hashes and counts — enough to reconstruct which prompt and
+ * which policy produced which outcome, without retaining user data.
+ *
+ * The error string is the one free-text field; it is redacted and capped
+ * before it is written.
+ */
+export declare function writeProvenance(dir: string, r: ProvenanceRecord): Promise<string>;
+/**
+ * Delete run logs older than the retention window. Best-effort and never
+ * throws: pruning is housekeeping, and a failed prune must not fail a run.
+ */
+export declare function pruneProvenance(dir: string, now?: Date): Promise<number>;

package/dist/jarvis/telemetry/provenance.js

@@ -0,0 +1,56 @@
+// xcoder:version 1 | xcoder:task task-f1b5f6 | xcoder:updated 2026-11-05T02:47:00.711Z | xcoder:subtask code-st-53c7b5
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { redact, writeFilePrivate } from "../util/text.js";
+export const RETENTION_DAYS = 90;
+/**
+ * Audit record for one run (CORE-08, PRM-10, AI-12).
+ *
+ * The schema itself is the privacy control: it has no field that can hold
+ * prompt text, model replies, file contents, tokens or keys. What is recorded
+ * is identifiers, hashes and counts — enough to reconstruct which prompt and
+ * which policy produced which outcome, without retaining user data.
+ *
+ * The error string is the one free-text field; it is redacted and capped
+ * before it is written.
+ */
+export async function writeProvenance(dir, r) {
+    const record = {
+        ...r,
+        error: r.error === undefined ? undefined : redact(r.error).text.slice(0, 500),
+    };
+    const file = path.join(dir, `${r.runId}.jsonl`);
+    await writeFilePrivate(file, JSON.stringify(record) + "\n");
+    return file;
+}
+/**
+ * Delete run logs older than the retention window. Best-effort and never
+ * throws: pruning is housekeeping, and a failed prune must not fail a run.
+ */
+export async function pruneProvenance(dir, now = new Date()) {
+    const cutoff = now.getTime() - RETENTION_DAYS * 24 * 60 * 60 * 1000;
+    let removed = 0;
+    let entries;
+    try {
+        entries = await fsp.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    for (const e of entries) {
+        if (!e.isFile() || !e.name.endsWith(".jsonl"))
+            continue;
+        const full = path.join(dir, e.name);
+        try {
+            const st = await fsp.stat(full);
+            if (st.mtimeMs < cutoff) {
+                await fsp.unlink(full);
+                removed += 1;
+            }
+        }
+        catch {
+            /* skip unreadable entries */
+        }
+    }
+    return removed;
+}

package/dist/jarvis/test-helpers.d.ts

@@ -0,0 +1,14 @@
+import { MemoryStore } from "./memory/store.js";
+import { assembleSystemPrompt, type AssembledPrompt } from "./prompt/assemble.js";
+import { type ToolDescriptor, type ToolObservation } from "./tools/registry.js";
+import type { LlmCompleter, ReactLoopInput } from "./react-loop.js";
+/** Shared fixtures for the jarvis test suite. Not part of the public barrel. */
+export declare const TEST_WORKSPACE: string;
+export declare function promptFor(overrides?: Partial<Parameters<typeof assembleSystemPrompt>[0]>): AssembledPrompt;
+export declare function makeMemory(rootDir?: string): MemoryStore;
+export declare function stubClient(reply: () => string): LlmCompleter;
+/** A tool with a real zod args schema, so schema validation is genuinely exercised. */
+export declare function fakeTool(name: string, execute: () => Promise<ToolObservation>): ToolDescriptor<Record<string, unknown>>;
+export declare function baseInput(overrides?: Partial<ReactLoopInput>): ReactLoopInput;
+export declare function finalReply(answer: string): string;
+export declare function actionReply(tool: string, args?: Record<string, unknown>): string;

package/dist/jarvis/test-helpers.js

@@ -0,0 +1,69 @@
+// xcoder:version 1 | xcoder:task task-f1b5f6 | xcoder:updated 2026-11-05T02:48:23.033Z | xcoder:subtask code-st-53c7b5
+import { z } from "zod";
+import { RunBudget } from "./budget.js";
+import { MemoryStore } from "./memory/store.js";
+import { assembleSystemPrompt } from "./prompt/assemble.js";
+import { ALLOWED_TOOLS, createToolRegistry } from "./tools/registry.js";
+import { alwaysDeny } from "./util/confirm.js";
+/** Shared fixtures for the jarvis test suite. Not part of the public barrel. */
+export const TEST_WORKSPACE = process.cwd();
+export function promptFor(overrides = {}) {
+    return assembleSystemPrompt({
+        agentName: "jarvis-agent",
+        directive: "test task",
+        skills: [],
+        window: [],
+        toolAllowlist: [...ALLOWED_TOOLS],
+        toolManifest: "- read_file: read",
+        now: new Date("2026-01-01T00:00:00Z"),
+        ...overrides,
+    });
+}
+export function makeMemory(rootDir = "/tmp/jarvis-test") {
+    return new MemoryStore({ rootDir, scope: { workspaceId: "ws-test", userId: "u-test" } });
+}
+export function stubClient(reply) {
+    return {
+        complete: async () => ({ text: reply(), usage: { inputTokens: 10, outputTokens: 5 } }),
+    };
+}
+/** A tool with a real zod args schema, so schema validation is genuinely exercised. */
+export function fakeTool(name, execute) {
+    return {
+        name,
+        description: `fake ${name}`,
+        risk: "read",
+        argsSchema: z.object({}).passthrough().transform((v) => v),
+        execute: () => execute(),
+    };
+}
+export function baseInput(overrides = {}) {
+    return {
+        task: "do something",
+        systemPrompt: promptFor(),
+        client: stubClient(() => JSON.stringify({ kind: "final", thought: "t", answer: "done" })),
+        registry: createToolRegistry({ tools: [] }),
+        toolContext: {
+            workspaceRoot: TEST_WORKSPACE,
+            memory: makeMemory(),
+            session: "s1",
+            confirm: alwaysDeny,
+            limits: { maxReadBytes: 1024, maxResults: 10 },
+        },
+        maxIterations: 8,
+        budget: new RunBudget({
+            maxIterations: 8,
+            maxInputTokens: 1_000_000,
+            maxOutputTokens: 1_000_000,
+            maxWallMs: 60_000,
+        }),
+        isKilled: () => false,
+        ...overrides,
+    };
+}
+export function finalReply(answer) {
+    return JSON.stringify({ kind: "final", thought: "t", answer });
+}
+export function actionReply(tool, args = {}) {
+    return JSON.stringify({ kind: "action", thought: "t", tool, args });
+}

package/dist/jarvis/tools/fs-tools.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { ToolDescriptor } from "./registry.js";
+export declare function isSecretPath(p: string): boolean;
+/** Convert a glob to a RegExp: `*`, `**`, `?`, `{a,b}` only. */
+export declare function globToRegExp(pattern: string): RegExp;
+declare const ReadFileArgs: z.ZodObject<{
+    path: z.ZodString;
+    maxBytes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const readFileTool: ToolDescriptor<z.infer<typeof ReadFileArgs>>;
+declare const GlobArgs: z.ZodObject<{
+    pattern: z.ZodString;
+    maxResults: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const globTool: ToolDescriptor<z.infer<typeof GlobArgs>>;
+declare const GrepArgs: z.ZodObject<{
+    pattern: z.ZodString;
+    pathGlob: z.ZodOptional<z.ZodString>;
+    maxResults: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const grepTool: ToolDescriptor<z.infer<typeof GrepArgs>>;
+declare const SearchArgs: z.ZodObject<{
+    query: z.ZodString;
+    maxResults: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const searchWorkspaceTool: ToolDescriptor<z.infer<typeof SearchArgs>>;
+export declare const FS_TOOLS: readonly ToolDescriptor<any>[];
+export {};

package/dist/jarvis/tools/fs-tools.js

@@ -0,0 +1,292 @@
+// xcoder:version 1 | xcoder:task task-f1b5f6 | xcoder:updated 2026-11-05T02:46:50.359Z | xcoder:subtask code-st-53c7b5
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { byteLength, normalizeUntrusted, readBounded, redact, resolveInsideRoot, truncate, } from "../util/text.js";
+/**
+ * Read-only filesystem tools (design §2.6).
+ *
+ * Every one of these is confined to the workspace and bounded in both output
+ * size and result count. None of them can write, delete, spawn a process or
+ * reach the network — those capabilities simply do not exist in this module,
+ * so no prompt text can conjure them (PRM-04, LLM08).
+ */
+/** Paths whose contents must never enter the model context (PRM-03, LLM06). */
+const SECRET_PATH_PATTERNS = [
+    /(^|[\\/])\.env(\.[^.\\/]+)?$/i,
+    /(^|[\\/])\.npmrc$/i,
+    /(^|[\\/])\.netrc$/i,
+    /(^|[\\/])id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/i,
+    /(^|[\\/])[^\\/]*\.(pem|key|p12|pfx|jks)$/i,
+    /(^|[\\/])\.ssh([\\/]|$)/i,
+    /(^|[\\/])\.aws([\\/]|$)/i,
+    /(^|[\\/])\.docker[\\/]config\.json$/i,
+    /(^|[\\/])credentials(\.json)?$/i,
+];
+export function isSecretPath(p) {
+    return SECRET_PATH_PATTERNS.some((re) => re.test(p));
+}
+/** Directories never worth walking, and expensive if we did. */
+const SKIP_DIRS = new Set([
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "coverage",
+    ".next",
+    ".turbo",
+    ".venv",
+]);
+function aborted(ctx) {
+    if (ctx.signal?.aborted) {
+        return { ok: false, summary: "aborted by kill switch", bytes: 0, truncated: false };
+    }
+    return undefined;
+}
+/** Convert a glob to a RegExp: `*`, `**`, `?`, `{a,b}` only. */
+export function globToRegExp(pattern) {
+    let out = "";
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === "*") {
+            if (pattern[i + 1] === "*") {
+                out += ".*";
+                i += 2;
+                if (pattern[i] === "/")
+                    i += 1;
+                continue;
+            }
+            out += "[^/]*";
+            i += 1;
+            continue;
+        }
+        if (ch === "?") {
+            out += "[^/]";
+            i += 1;
+            continue;
+        }
+        if (ch === "{") {
+            const close = pattern.indexOf("}", i);
+            if (close !== -1) {
+                const alts = pattern
+                    .slice(i + 1, close)
+                    .split(",")
+                    .map((a) => a.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+                out += `(?:${alts.join("|")})`;
+                i = close + 1;
+                continue;
+            }
+        }
+        out += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        i += 1;
+    }
+    return new RegExp(`^${out}$`);
+}
+async function walk(root, maxFiles) {
+    const out = [];
+    const stack = [root];
+    while (stack.length > 0 && out.length < maxFiles) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = await fsp.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (out.length >= maxFiles)
+                break;
+            const full = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                if (SKIP_DIRS.has(e.name))
+                    continue;
+                stack.push(full);
+            }
+            else if (e.isFile() && !isSecretPath(full)) {
+                out.push(full);
+            }
+        }
+    }
+    return out;
+}
+const ReadFileArgs = z.object({
+    path: z.string().min(1).max(1_000),
+    maxBytes: z.number().int().positive().max(1_048_576).optional(),
+});
+export const readFileTool = {
+    name: "read_file",
+    description: "Read a UTF-8 text file inside the workspace. Args: { path }. Secret-bearing paths (dotenv, keys, ssh, npmrc, credentials) are refused.",
+    risk: "read",
+    argsSchema: ReadFileArgs,
+    async execute(args, ctx) {
+        const stopped = aborted(ctx);
+        if (stopped)
+            return stopped;
+        if (isSecretPath(args.path)) {
+            return {
+                ok: false,
+                summary: `refused: ${args.path} is on the secret-path denylist`,
+                bytes: 0,
+                truncated: false,
+            };
+        }
+        const resolved = await resolveInsideRoot(ctx.workspaceRoot, args.path);
+        if (!resolved.ok) {
+            return { ok: false, summary: `refused: ${resolved.reason}`, bytes: 0, truncated: false };
+        }
+        if (isSecretPath(resolved.path)) {
+            return {
+                ok: false,
+                summary: "refused: resolved path is on the secret-path denylist",
+                bytes: 0,
+                truncated: false,
+            };
+        }
+        const cap = Math.min(args.maxBytes ?? ctx.limits.maxReadBytes, ctx.limits.maxReadBytes);
+        const read = await readBounded(resolved.path, cap);
+        if (!read.ok) {
+            return { ok: false, summary: `refused: ${read.reason}`, bytes: 0, truncated: false };
+        }
+        const cleaned = redact(normalizeUntrusted(read.text)).text;
+        const trimmed = truncate(cleaned, 20_000);
+        return {
+            ok: true,
+            summary: trimmed.text,
+            bytes: read.bytes,
+            truncated: read.truncated || trimmed.truncated,
+            data: { path: args.path, bytes: read.bytes },
+        };
+    },
+};
+const GlobArgs = z.object({
+    pattern: z.string().min(1).max(200),
+    maxResults: z.number().int().positive().max(200).optional(),
+});
+export const globTool = {
+    name: "glob",
+    description: "List workspace file paths matching a glob. Supports *, **, ? and {a,b} only. Args: { pattern, maxResults? }.",
+    risk: "read",
+    argsSchema: GlobArgs,
+    async execute(args, ctx) {
+        const stopped = aborted(ctx);
+        if (stopped)
+            return stopped;
+        const limit = Math.min(args.maxResults ?? 100, ctx.limits.maxResults);
+        const re = globToRegExp(args.pattern);
+        const files = await walk(ctx.workspaceRoot, 20_000);
+        const matches = [];
+        for (const f of files) {
+            const rel = path.relative(ctx.workspaceRoot, f).split(path.sep).join("/");
+            if (re.test(rel) || re.test(path.basename(rel))) {
+                matches.push(rel);
+                if (matches.length >= limit)
+                    break;
+            }
+        }
+        return {
+            ok: true,
+            summary: matches.length > 0 ? matches.join("\n") : "no files matched",
+            bytes: byteLength(matches.join("\n")),
+            truncated: matches.length >= limit,
+            data: { count: matches.length },
+        };
+    },
+};
+const GrepArgs = z.object({
+    pattern: z.string().min(1).max(200),
+    pathGlob: z.string().min(1).max(200).optional(),
+    maxResults: z.number().int().positive().max(500).optional(),
+});
+export const grepTool = {
+    name: "grep",
+    description: "Search workspace file contents for a regular expression. Binary files are skipped. Args: { pattern, pathGlob?, maxResults? }.",
+    risk: "read",
+    argsSchema: GrepArgs,
+    async execute(args, ctx) {
+        const stopped = aborted(ctx);
+        if (stopped)
+            return stopped;
+        let re;
+        try {
+            re = new RegExp(args.pattern, "i");
+        }
+        catch {
+            return { ok: false, summary: "refused: pattern is not a valid regex", bytes: 0, truncated: false };
+        }
+        const limit = Math.min(args.maxResults ?? 100, ctx.limits.maxResults);
+        const pathFilter = args.pathGlob ? globToRegExp(args.pathGlob) : undefined;
+        const files = await walk(ctx.workspaceRoot, 20_000);
+        const hits = [];
+        for (const file of files) {
+            if (ctx.signal?.aborted)
+                break;
+            if (hits.length >= limit)
+                break;
+            const rel = path.relative(ctx.workspaceRoot, file).split(path.sep).join("/");
+            if (pathFilter && !pathFilter.test(rel) && !pathFilter.test(path.basename(rel)))
+                continue;
+            const read = await readBounded(file, 256_000);
+            if (!read.ok)
+                continue;
+            if (read.text.includes("\u0000"))
+                continue; // binary
+            const lines = read.text.split(/\r?\n/);
+            for (let i = 0; i < lines.length; i += 1) {
+                if (!re.test(lines[i]))
+                    continue;
+                hits.push(`${rel}:${i + 1}: ${redact(lines[i]).text.slice(0, 300)}`);
+                if (hits.length >= limit)
+                    break;
+            }
+        }
+        return {
+            ok: true,
+            summary: hits.length > 0 ? hits.join("\n") : "no matches",
+            bytes: byteLength(hits.join("\n")),
+            truncated: hits.length >= limit,
+            data: { count: hits.length },
+        };
+    },
+};
+const SearchArgs = z.object({
+    query: z.string().min(1).max(200),
+    maxResults: z.number().int().positive().max(200).optional(),
+});
+export const searchWorkspaceTool = {
+    name: "search_workspace",
+    description: "Search workspace file PATHS for a substring (cheap path index lookup, not content). Args: { query, maxResults? }.",
+    risk: "read",
+    argsSchema: SearchArgs,
+    async execute(args, ctx) {
+        const stopped = aborted(ctx);
+        if (stopped)
+            return stopped;
+        const limit = Math.min(args.maxResults ?? 100, ctx.limits.maxResults);
+        const needle = args.query.toLowerCase();
+        const files = await walk(ctx.workspaceRoot, 20_000);
+        const matches = [];
+        for (const f of files) {
+            const rel = path.relative(ctx.workspaceRoot, f).split(path.sep).join("/");
+            if (rel.toLowerCase().includes(needle)) {
+                matches.push(rel);
+                if (matches.length >= limit)
+                    break;
+            }
+        }
+        return {
+            ok: true,
+            summary: matches.length > 0 ? matches.join("\n") : "no paths matched",
+            bytes: byteLength(matches.join("\n")),
+            truncated: matches.length >= limit,
+            data: { count: matches.length },
+        };
+    },
+};
+export const FS_TOOLS = [
+    readFileTool,
+    globTool,
+    grepTool,
+    searchWorkspaceTool,
+];