@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/tools/workspace/mutator.js

@@ -26,11 +26,17 @@
  * The landing is hardened beyond the lexical resolver: missing parent
  * directories are created only inside the write prefix, the deepest existing
  * ancestor is realpath-checked against the realpath'd prefix (a symlinked
- * ancestor cannot re-aim the write), and the final open uses `O_NOFOLLOW`
- * (a symlinked final component is refused, never followed).
+ * ancestor cannot re-aim the write), and a symlinked final component is
+ * refused, never followed.
+ *
+ * The landing is atomic: the bytes go to a temporary file in the target's
+ * directory, and a rename puts that file over the target. A reader of the
+ * target sees the old file or the new file whole, never a part of one, and a
+ * process that dies mid-write leaves the target as it was.
  */
+import { createHash } from "node:crypto";
 import { constants } from "node:fs";
-import { lstat, mkdir, open, realpath } from "node:fs/promises";
+import { lstat, mkdir, open, realpath, rename, unlink } from "node:fs/promises";
 import { basename, dirname, join as joinPath, relative as relativePath, resolve as resolvePath, sep } from "node:path";
 import { createNoopLogger } from "../../lib/console-logger.js";
 import { computeSha256 } from "../../lib/fs-helpers.js";
@@ -38,6 +44,13 @@ import { tryFs, tryFsWrite } from "../../lib/fs-result.js";
 import { unwrapOrThrow } from "../../lib/result.js";
 import { bindSessionEmit } from "../../provenance/seam.js";
 import { resolveForWrite } from "../../workspace/paths.js";
+/**
+ * Agent-visible name of the tool driving a confined write. Rides the write args
+ * so a successful write is attributed to the invoking tool in provenance
+ * (`inflexa:tool` in the signed document) — the seam records the write without
+ * inspecting its caller.
+ */
+export const MUTATE_TOOL_NAMES = ["write_file", "edit_file", "knowledge_template", "execute_command"];
 /**
  * Land `bytes` at `absolute`, hardened against a symlink re-aiming the write.
  * `absolute` is already lexically confined under `prefix` by the resolver;
@@ -53,14 +66,14 @@ import { resolveForWrite } from "../../workspace/paths.js";
  *      the created directory and refuse when it lands outside the prefix — a
  *      symlink raced into a missing segment between the ancestor check and the
  *      recursive mkdir would re-aim the tail of the path.
- *   4. Refuse a symlinked final component (lstat), then open with
- *      `O_NOFOLLOW` so a symlink raced in after the check still cannot be
- *      followed.
+ *   4. Refuse a symlinked final component (lstat), then stage the bytes in a
+ *      temporary file beside it and rename that file over it. The rename
+ *      replaces a symlink raced in after the check, and never follows it.
  *
  * Refusals are data; a genuine I/O failure throws (the loop's dispatch catch
- * maps it to an error tool result).
+ * maps it to an error tool result). A throw removes the temporary file.
  */
-async function landBytes(prefix, absolute, bytes) {
+async function landBytes(prefix, absolute, bytes, stagingKey, beforeRename) {
     unwrapOrThrow(await tryFsWrite("mutator.mkdirPrefix", () => mkdir(prefix, { recursive: true }), { path: prefix }));
     const realPrefix = unwrapOrThrow(await tryFs("mutator.realpathPrefix", () => realpath(prefix), { path: prefix }));
     // Deepest existing ancestor of the target. The walk stops at the prefix,
@@ -85,8 +98,8 @@ async function landBytes(prefix, absolute, bytes) {
         // a symlink raced into a missing segment after the ancestor check would
         // re-aim the tail. The canonical path of the created directory exposes
         // it; a directory that vanished before the check is hostile too. The
-        // open below uses the canonical path, so the write never traverses the
-        // raced segment again.
+        // staging below uses the canonical path, so the write never traverses
+        // the raced segment again.
         const realTarget = unwrapOrThrow(await tryFs("mutator.realpathTarget", () => realpath(targetDir), { path: targetDir, onAbsent: () => null }));
         if (realTarget === null)
             return "symlink_denied";
@@ -98,24 +111,54 @@ async function landBytes(prefix, absolute, bytes) {
     const finalStat = unwrapOrThrow(await tryFs("mutator.lstatFinal", () => lstat(finalPath), { path: finalPath, onAbsent: () => null }));
     if (finalStat !== null && finalStat.isSymbolicLink())
         return "symlink_denied";
-    // `O_NOFOLLOW` backstops the lstat refusal: a symlink raced in between the
-    // two calls fails the open (`ELOOP`) instead of being followed.
-    const handle = unwrapOrThrow(await tryFsWrite("mutator.open", () => open(finalPath, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW), {
-        path: finalPath,
-    }));
+    const stagingPath = joinPath(landingDir, stagingNameFor(stagingKey, finalPath));
+    let landed = false;
     try {
-        unwrapOrThrow(await tryFsWrite("mutator.writeBytes", () => handle.writeFile(bytes), { path: finalPath }));
+        await stageBytes(stagingPath, bytes, finalStat?.isFile() === true ? finalStat.mode : undefined);
+        if (beforeRename !== undefined)
+            await beforeRename();
+        unwrapOrThrow(await tryFsWrite("mutator.rename", () => rename(stagingPath, finalPath), { path: finalPath }));
+        landed = true;
     }
     finally {
-        unwrapOrThrow(await tryFsWrite("mutator.close", () => handle.close(), { path: finalPath }));
+        if (!landed)
+            await tryFsWrite("mutator.removeStaging", () => unlink(stagingPath), { path: stagingPath }).unwrapOr(undefined);
     }
     return "ok";
 }
+/**
+ * The name of the temporary file of one write. A rerun of the same call writes
+ * the same name, thus it replaces a file that a dead process left behind.
+ */
+function stagingNameFor(stagingKey, finalPath) {
+    return `.${createHash("sha256").update(`${stagingKey}\0${finalPath}`).digest("hex").slice(0, 32)}.tmp`;
+}
+/**
+ * Write `bytes` to the temporary file. The file takes the permission bits of
+ * the file that it replaces, thus an edit keeps, for example, the execute bit
+ * of a script.
+ */
+async function stageBytes(stagingPath, bytes, replacedMode) {
+    // `O_NOFOLLOW` refuses a symlink planted at the staging name (`ELOOP`).
+    const handle = unwrapOrThrow(await tryFsWrite("mutator.openStaging", () => open(stagingPath, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW), {
+        path: stagingPath,
+    }));
+    try {
+        unwrapOrThrow(await tryFsWrite("mutator.writeBytes", () => handle.writeFile(bytes), { path: stagingPath }));
+        if (replacedMode !== undefined) {
+            unwrapOrThrow(await tryFsWrite("mutator.chmodStaging", () => handle.chmod(replacedMode & 0o7777), { path: stagingPath }));
+        }
+    }
+    finally {
+        unwrapOrThrow(await tryFsWrite("mutator.close", () => handle.close(), { path: stagingPath }));
+    }
+}
 /**
  * The shared write gauntlet both realizations run: resolve + confine
  * (`resolveForWrite`), then the hardened landing. A refusal comes back as data;
  * an ok carries what the caller's provenance record needs — the
- * analysis-relative path and the exact bytes that landed.
+ * analysis-relative path and the exact bytes that landed. `beforeLand` gets
+ * the same ok while the bytes wait in the temporary file.
  */
 async function confinedWrite(args) {
     const scoped = resolveForWrite({
@@ -135,37 +178,44 @@ async function confinedWrite(args) {
     const agentPath = `/${args.analysisId}/${relative}`;
     const bytes = Buffer.from(args.content, "utf8");
     const prefix = resolvePath(args.workingDir);
-    const landed = await landBytes(prefix, scoped.absolute, bytes);
+    const confined = { status: "ok", relative, agentPath, bytes };
+    const { beforeLand } = args;
+    const landed = await landBytes(prefix, scoped.absolute, bytes, args.invocationId, beforeLand === undefined ? undefined : () => beforeLand(confined));
     if (landed !== "ok")
         return { status: landed };
-    return { status: "ok", relative, agentPath, bytes };
+    return confined;
 }
 export function createWorkspaceMutator(deps) {
     return {
-        async writeFile({ path, content, toolName, invocationId }) {
+        async writeFile({ path, content, toolName, invocationId, beforeLand }) {
+            const landedWrite = (landed) => {
+                // `invocationId` is replay-stable: the model turn that minted the tool
+                // call is a durably cached step, so a re-execution replays the same id.
+                // That is what lets the bridge key a DETERMINISTIC call-activity
+                // identifier on it — a wall-clock stamp here would be re-minted per
+                // replay and must never reach an identifier or a formal PROV position.
+                const record = {
+                    analysisId: deps.analysisId,
+                    path: landed.relative,
+                    hash: computeSha256(landed.bytes),
+                    size: landed.bytes.length,
+                    toolName,
+                    invocationId,
+                };
+                return { status: "ok", path: landed.agentPath, bytesWritten: landed.bytes.length, record };
+            };
             const landed = await confinedWrite({
                 workspaceRoot: deps.workspaceRoot,
                 analysisId: deps.analysisId,
                 workingDir: deps.workingDir,
                 path,
                 content,
+                invocationId,
+                beforeLand: beforeLand === undefined ? undefined : (staged) => beforeLand(landedWrite(staged)),
             });
             if (landed.status !== "ok")
                 return { status: landed.status, path };
-            // `invocationId` is replay-stable: the model turn that minted the tool
-            // call is a durably cached step, so a re-execution replays the same id.
-            // That is what lets the bridge key a DETERMINISTIC call-activity
-            // identifier on it — a wall-clock stamp here would be re-minted per
-            // replay and must never reach an identifier or a formal PROV position.
-            const record = {
-                analysisId: deps.analysisId,
-                path: landed.relative,
-                hash: computeSha256(landed.bytes),
-                size: landed.bytes.length,
-                toolName,
-                invocationId,
-            };
-            return { status: "ok", path: landed.agentPath, bytesWritten: landed.bytes.length, record };
+            return landedWrite(landed);
         },
         recordWrite(record) {
             deps.lineageCollector?.recordFileToolWrite({
@@ -195,12 +245,21 @@ export function createSessionWorkspaceMutator(deps) {
     const logger = (deps.logger ?? createNoopLogger()).named("workspace-mutator");
     const observe = bindSessionEmit(deps.provenance, logger);
     return {
-        async writeFile({ path, content, toolName, invocationId, session }) {
-            // Only an analysis scope has a workspace tree; under any other
-            // scope there is nothing in scope to write.
+        async writeFile({ path, content, toolName, invocationId, session, beforeLand }) {
             const scope = session.scope;
-            if (scope.kind !== "analysis")
-                return { status: "out_of_scope", path };
+            const landedWrite = (landed) => {
+                const record = {
+                    analysisId: scope.analysisId,
+                    path: landed.relative,
+                    hash: computeSha256(landed.bytes),
+                    size: landed.bytes.length,
+                    toolName,
+                    invocationId,
+                };
+                if (scope.threadId !== undefined)
+                    record.threadId = scope.threadId;
+                return { status: "ok", path: landed.agentPath, bytesWritten: landed.bytes.length, record };
+            };
             // Rejects on an unknown analysis — the loop's dispatch catch maps
             // it to an error tool result, like any unexpected host failure.
             const workspaceRoot = await deps.resolveWorkspaceRoot(scope.analysisId);
@@ -210,31 +269,26 @@ export function createSessionWorkspaceMutator(deps) {
                 workingDir: workspaceRoot,
                 path,
                 content,
+                invocationId,
+                beforeLand: beforeLand === undefined ? undefined : (staged) => beforeLand(landedWrite(staged)),
             });
             if (landed.status !== "ok")
                 return { status: landed.status, path };
-            const record = {
-                analysisId: scope.analysisId,
-                ...(scope.threadId !== undefined ? { threadId: scope.threadId } : {}),
-                path: landed.relative,
-                hash: computeSha256(landed.bytes),
-                size: landed.bytes.length,
-                toolName,
-                invocationId,
-            };
-            return { status: "ok", path: landed.agentPath, bytesWritten: landed.bytes.length, record };
+            return landedWrite(landed);
         },
         recordWrite(record) {
-            observe({
+            const event = {
                 type: "write-file",
                 analysisId: record.analysisId,
-                ...(record.threadId !== undefined ? { threadId: record.threadId } : {}),
                 path: record.path,
                 hash: record.hash,
                 size: record.size,
                 tool: record.toolName,
                 invocationId: record.invocationId,
-            });
+            };
+            if (record.threadId !== undefined)
+                event.threadId = record.threadId;
+            observe(event);
         },
     };
 }

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

@@ -7,6 +7,8 @@
  * oversize read is `truncated`. Only unexpected I/O errors throw; the loop
  * wraps them as `is_error`.
  */
+import { z } from "zod";
+import { type Tool } from "../define-tool.js";
 import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
 type ReadFileOutput = {
     status: "invalid_input";
@@ -36,9 +38,10 @@ type ReadFileOutput = {
     mode: "head" | "tail" | "full";
     totalSize?: number;
 };
-export declare function createReadFileTool(fs: WorkspaceFilesystem, workingDir?: string): import("../define-tool.js").Tool<{
-    path: string;
-    headLines?: number | undefined;
-    tailLines?: number | undefined;
-}, ReadFileOutput>;
+declare const ReadFileInputSchema: z.ZodObject<{
+    path: z.ZodString;
+    headLines: z.ZodOptional<z.ZodNumber>;
+    tailLines: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export declare function createReadFileTool(fs: WorkspaceFilesystem, workingDir?: string): Tool<z.infer<typeof ReadFileInputSchema>, ReadFileOutput>;
 export {};

package/dist/tools/workspace/result-bounds.d.ts

@@ -17,13 +17,13 @@
 import type { ExecResult } from "../../sandbox/types.js";
 /** Per-stream cap: the maximum of a kept tool output, thus the host gets each stream that the store can keep. */
 export declare const EXEC_STREAM_BYTE_CAP: number;
-export interface BoundedStream {
+export type BoundedStream = {
     readonly content: string;
     readonly truncated: boolean;
     readonly totalLength: number;
     readonly returnedBytes: number;
-}
-export interface BoundedExecResult {
+};
+export type BoundedExecResult = {
     readonly execId: string;
     readonly exitCode: number | null;
     readonly stdout: string;
@@ -34,10 +34,10 @@ export interface BoundedExecResult {
     readonly stderrTotalLength: number;
     readonly durationMs: number | null;
     readonly timedOut: boolean;
-    readonly syntheticFailure?: {
+    syntheticFailure?: {
         readonly reason: string;
     };
-}
+};
 /**
  * Bound an `ExecResult`'s streams while keeping its shape.
  *

package/dist/tools/workspace/result-bounds.js

@@ -94,7 +94,7 @@ export function capExecStreams(result, cap = EXEC_STREAM_BYTE_CAP) {
 export function boundExecResult(result, cap = EXEC_STREAM_BYTE_CAP) {
     const outStream = boundStream(result.stdout, cap);
     const errStream = boundStream(result.stderr, cap);
-    return {
+    const bounded = {
         execId: result.execId,
         exitCode: result.exitCode,
         stdout: outStream.content,
@@ -105,6 +105,8 @@ export function boundExecResult(result, cap = EXEC_STREAM_BYTE_CAP) {
         stderrTotalLength: result.stderrTotalBytes ?? errStream.totalLength,
         durationMs: result.durationMs,
         timedOut: result.timedOut,
-        ...(result.syntheticFailure ? { syntheticFailure: result.syntheticFailure } : {}),
     };
+    if (result.syntheticFailure)
+        bounded.syntheticFailure = result.syntheticFailure;
+    return bounded;
 }

package/dist/tools/workspace/run-exec.d.ts

@@ -10,7 +10,7 @@
 import type { SandboxClient } from "../../sandbox/client.js";
 import type { ExecResult, SandboxRef } from "../../sandbox/types.js";
 import type { EmitFn } from "../define-tool.js";
-export interface RunExecArgs {
+export type RunExecArgs = {
     readonly sandboxClient: SandboxClient;
     readonly sandbox: SandboxRef;
     readonly command: readonly string[];
@@ -19,5 +19,5 @@ export interface RunExecArgs {
     readonly timeoutSeconds?: number;
     readonly deadlineMs: number;
     readonly emit: EmitFn;
-}
+};
 export declare function runSandboxExec(args: RunExecArgs): Promise<ExecResult>;

package/dist/tools/workspace/run-exec.js

@@ -10,8 +10,8 @@
 export function runSandboxExec(args) {
     return args.sandboxClient.exec(args.sandbox, {
         command: args.command,
-        ...(args.cwd === undefined ? {} : { cwd: args.cwd }),
-        ...(args.env === undefined ? {} : { env: args.env }),
-        ...(args.timeoutSeconds === undefined ? {} : { timeoutSeconds: args.timeoutSeconds }),
+        cwd: args.cwd,
+        env: args.env,
+        timeoutSeconds: args.timeoutSeconds,
     }, (event) => args.emit({ type: "data-sandbox-event", data: { event } }), args.deadlineMs);
 }

package/dist/tools/workspace/scan-inputs.d.ts

@@ -11,17 +11,19 @@
  * prefix-sufficient header readout run in-process over the workspace read seam; only a
  * footer-indexed container reaches into the sandbox (see `input-scan/enrich.ts`).
  */
+import { z } from "zod";
 import type { SandboxClient } from "../../sandbox/client.js";
 import type { SandboxRef } from "../../sandbox/types.js";
 import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
-export interface ScanInputsDeps {
+import { type Tool } from "../define-tool.js";
+export type ScanInputsDeps = {
     readonly workspaceFs: WorkspaceFilesystem;
     readonly analysisId: string;
     /** Omit to skip the container readouts; the prefix readouts run regardless. */
     readonly sandboxClient?: SandboxClient;
     readonly sandbox?: SandboxRef;
     readonly deadlineMs: () => number;
-}
+};
 type ScanInputsOutput = {
     readonly path: string;
     readonly fileCount: number;
@@ -29,7 +31,8 @@ type ScanInputsOutput = {
     /** The rendered manifest — bounded whatever the subtree's size. */
     readonly manifest: string;
 };
-export declare function createScanInputsTool(deps: ScanInputsDeps): import("../define-tool.js").Tool<{
-    path: string;
-}, ScanInputsOutput>;
+declare const ScanInputsInputSchema: z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strip>;
+export declare function createScanInputsTool(deps: ScanInputsDeps): Tool<z.infer<typeof ScanInputsInputSchema>, ScanInputsOutput>;
 export {};

package/dist/tools/workspace/scan-inputs.js

@@ -15,7 +15,20 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { enrichShapes } from "../../input-scan/enrich.js";
 import { renderInputScanManifest, scanInputTree } from "../../input-scan/scan.js";
+/** The path without its leading and trailing slashes. */
+function stripEdgeSlashes(value) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && value.charAt(start) === "/")
+        start++;
+    while (end > start && value.charAt(end - 1) === "/")
+        end--;
+    return value.slice(start, end);
+}
 import { defineTool } from "../define-tool.js";
+const ScanInputsInputSchema = z.object({
+    path: z.string().min(1).describe("Directory to scan, relative to the analysis root (e.g. 'data/inputs' or 'data/inputs/vcf')."),
+});
 export function createScanInputsTool(deps) {
     return defineTool({
         id: "scan_inputs",
@@ -29,22 +42,21 @@ export function createScanInputsTool(deps) {
             "Your briefing already carries a scan of the whole input tree; call this to look at a subtree more closely, " +
             "or to check a grouping you are unsure about. " +
             "It reports observations only: which files are one KIND of data, and what a varying position MEANS, are yours to decide.",
-        inputSchema: z.object({
-            path: z.string().min(1).describe("Directory to scan, relative to the analysis root (e.g. 'data/inputs' or 'data/inputs/vcf')."),
-        }),
+        inputSchema: ScanInputsInputSchema,
         describeCall: ({ path }) => path,
         execute: async ({ path }, ctx) => {
             const scan = await scanInputTree({
                 session: ctx.session,
                 fs: deps.workspaceFs,
-                root: path.replace(/^\/+/, "").replace(/\/+$/, ""),
+                root: stripEdgeSlashes(path),
                 signal: ctx.signal,
             });
             const shapes = await enrichShapes({
                 shapes: scan.manifest.shapes,
                 session: ctx.session,
                 fs: deps.workspaceFs,
-                ...(deps.sandboxClient && deps.sandbox ? { sandboxClient: deps.sandboxClient, sandbox: deps.sandbox } : {}),
+                sandboxClient: deps.sandboxClient,
+                sandbox: deps.sandbox,
                 mountRoot: `/${deps.analysisId}`,
                 deadlineMs: deps.deadlineMs(),
                 emit: ctx.emit,

package/dist/tools/workspace/show-file.d.ts

@@ -21,11 +21,11 @@ type ShowFileOutput = {
     id: string;
 };
 export declare const showFileTool: import("../define-tool.js").Tool<{
+    title?: string | undefined;
     files: {
         path: string;
         caption?: string | undefined;
     }[];
-    title?: string | undefined;
 }, ShowFileOutput>;
 /** Exposed for tests. */
 export declare const __testing: {

package/dist/tools/workspace/show-file.js

@@ -12,6 +12,7 @@
  * live emit and the reconstruct-on-read path produce byte-identical cards.
  */
 import { ok } from "neverthrow";
+import { presentFirst } from "../../lib/present.js";
 import { z } from "zod";
 import { buildFileReferenceCardData, deriveRunId, fileGroupHash, MAX_FILES } from "../../memory/card-builders.js";
 import { defineTool } from "../define-tool.js";
@@ -42,7 +43,7 @@ export const showFileTool = defineTool({
         "(markdown image syntax pointing at a workspace file does NOT render — this tool is the only way to show one).",
     inputSchema: ShowFileInputSchema,
     // `.min(1)` on `files` makes index 0 total after the parse.
-    describeCall: ({ files }) => (files.length === 1 ? files[0].path : `${files.length} files`),
+    describeCall: ({ files }) => (files.length === 1 ? presentFirst(files, "the shown file").path : `${files.length} files`),
     execute: async (input, ctx) => {
         const card = buildFileReferenceCardData(input);
         // A malformed/traversal path yields no card — an expected outcome the model can self-correct

package/dist/tools/workspace/show-plan.d.ts

@@ -8,7 +8,9 @@
  * Dependency-bearing: the database `Pool` is captured by the factory
  * (see the harness-durable-runtime spec). The analysis id is read from the request-scoped `Session`.
  */
-import type { Pool } from "pg";
+import { z } from "zod";
+import type { PlanRowQuerier } from "../../state/plans.js";
+import { type Tool } from "../define-tool.js";
 type ShowPlanOutput = {
     shown: false;
     reason: "plan_not_found";
@@ -16,8 +18,9 @@ type ShowPlanOutput = {
     shown: true;
     id: string;
 };
-export declare function createShowPlanTool(pool: Pool): import("../define-tool.js").Tool<{
-    planId: string;
-    title?: string | undefined;
-}, ShowPlanOutput>;
+declare const ShowPlanInputSchema: z.ZodObject<{
+    planId: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare function createShowPlanTool(pool: PlanRowQuerier): Tool<z.infer<typeof ShowPlanInputSchema>, ShowPlanOutput>;
 export {};

package/dist/tools/workspace/show-plan.js

@@ -13,8 +13,15 @@ import { z } from "zod";
 import { buildPlanCardData } from "../../memory/card-builders.js";
 import { scopeResource } from "../../auth/types.js";
 import { unwrapOrThrow } from "../../lib/result.js";
+import { PLAN_ID_RE } from "../../contracts/schemas/chat-parts.js";
 import { defineTool } from "../define-tool.js";
-const PLAN_ID_REGEX = /^pln-[a-f0-9]{8}$/;
+const ShowPlanInputSchema = z.object({
+    planId: z
+        .string()
+        .regex(PLAN_ID_RE, "planId must match pln-<8hex>")
+        .describe("Plan ID (`pln-<8hex>`) from `generate_plan` (newly created) or `inspect_run` (each run carries the planId it ran)"),
+    title: z.string().optional().describe("Optional card heading; defaults to the plan's own title"),
+});
 export function createShowPlanTool(pool) {
     return defineTool({
         id: "show_plan",
@@ -25,13 +32,7 @@ export function createShowPlanTool(pool) {
             "NOT for a plan you are drafting in conversation (that is `generate_plan`), NOT for other synthesized content " +
             "(`show_user`), NOT for analysis files (`show_file`). Never re-type a plan's steps into a `show_user` markdown " +
             "card — that renders a second, divergent copy of the same plan.",
-        inputSchema: z.object({
-            planId: z
-                .string()
-                .regex(PLAN_ID_REGEX, "planId must match pln-<8hex>")
-                .describe("Plan ID (`pln-<8hex>`) from `generate_plan` (newly created) or `inspect_run` (each run carries the planId it ran)"),
-            title: z.string().optional().describe("Optional card heading; defaults to the plan's own title"),
-        }),
+        inputSchema: ShowPlanInputSchema,
         describeCall: ({ planId }) => planId,
         execute: async ({ planId, title }, ctx) => {
             const resourceId = scopeResource(ctx.session.scope).resourceId;

package/dist/tools/workspace/workspace-search.d.ts

@@ -10,8 +10,10 @@
  * rows by cosine similarity. "Nothing indexed yet" (the index table does not
  * exist) is an expected outcome — an empty result list, not an error.
  */
-import type { Pool } from "pg";
+import type { QueryConfig } from "pg";
+import { z } from "zod";
 import type { EmbeddingProvider } from "../../providers/types.js";
+import { type Tool } from "../define-tool.js";
 /**
  * The workspace path a hit addresses, or `undefined` for a pattern entry. Resolved here,
  * once, across every index era — group/dimension/kind entries and previous-era entity
@@ -20,15 +22,41 @@ import type { EmbeddingProvider } from "../../providers/types.js";
  * segment. The consumer branches on presence, nothing else.
  */
 export declare function fileTargetOf(id: string, metadata: unknown): string | undefined;
-export declare function createWorkspaceSearchTool(pool: Pool, embedding: EmbeddingProvider): import("../define-tool.js").Tool<{
-    query: string;
-    limit: number;
-    type?: "output" | "input" | "summary" | "synthesis" | "input-group" | "input-dimension" | "input-kind" | undefined;
-}, {
-    results: {
-        metadata: unknown;
-        path?: string | undefined;
-        id: string;
-        score: number;
-    }[];
-}>;
+/** One search-hit row, as the pgvector SELECT returns it. */
+type SearchHitRow = {
+    id: string;
+    score: number;
+    metadata: unknown;
+};
+/** One ranked entry the tool returns: the row plus the workspace path it addresses. */
+type WorkspaceSearchHit = {
+    id: string;
+    score: number;
+    path: string | undefined;
+    metadata: unknown;
+};
+type WorkspaceSearchOutput = {
+    results: WorkspaceSearchHit[];
+};
+declare const WorkspaceSearchInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    type: z.ZodOptional<z.ZodEnum<{
+        input: "input";
+        "input-dimension": "input-dimension";
+        "input-group": "input-group";
+        "input-kind": "input-kind";
+        output: "output";
+        summary: "summary";
+        synthesis: "synthesis";
+    }>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/** What the workspace search reads of the pool: its one row-reading query. A real `Pool` satisfies it. */
+export type WorkspaceSearchQuerier = {
+    query(queryTextOrConfig: string | QueryConfig, values?: unknown[]): Promise<{
+        rows: SearchHitRow[];
+        rowCount: number | null;
+    }>;
+};
+export declare function createWorkspaceSearchTool(pool: WorkspaceSearchQuerier, embedding: EmbeddingProvider): Tool<z.infer<typeof WorkspaceSearchInputSchema>, WorkspaceSearchOutput>;
+export {};