@ian-pascoe/pi-codemode 0.4.0 → 0.5.0

package/README.md

@@ -154,14 +154,19 @@ parent kills the worker before it can reply.
 
 ## Transcript and Observer UI
 
-The CodeMode Transcript gives all four tools semantic collapsed and expanded
-rendering. Collapsed rows prioritize Cell lifecycle, a short Session ID, Cell
+The CodeMode Transcript gives all five tools semantic collapsed and expanded
+rendering. Session rows prioritize Cell lifecycle, a short Session ID, Cell
 Ordinal, returned-value shape, Console-call count, nested-tool count, and elapsed
 time. Expanded rows show the full Session ID, explicit call arguments,
 TypeScript source, bounded Console output before structured returned data or the
 error, and bounded nested-tool names, outcomes, and durations. Nested arguments
 and raw nested outputs are never copied into the presentation.
 
+Search rows show the query, result range, and next offset without exposing raw
+JSON. Expanding a search shows each exact tool name, display group, highlighted
+TypeScript declaration, and any declaration-size failure. Search declarations
+are bounded only in the Transcript; the model-facing result remains unchanged.
+
 Status always uses a symbol and text together:
 
 ```text
@@ -228,18 +233,50 @@ termination, or process failure destroys that session's heap.
 
 ## Registered tools
 
-The `codemode_execute` description contains generated TypeScript declarations
-for the currently exposed registered tools. Guest calls resolve to:
+The `codemode_execute` description contains a token-bounded catalogue of
+complete generated TypeScript declarations for currently exposed registered
+tools. It marks the catalogue `COMPLETE` or `PARTIAL`; a partial catalogue keeps
+the remaining declarations available through:
 
 ```ts
-type PiToolResult = {
+const page = await tools.codemode_search({
+  query: "intent or exact registered name",
+  group: "optional display group",
+  limit: 10,
+  offset: 0,
+});
+```
+
+Search returns stable pages with `items`, `total`, `hasMore`, and `nextOffset`.
+Each item contains its exact flat `name`, display-only `group`, bounded
+`description`, and complete `declaration`. A pathological declaration above the
+search response bound instead has an explicit `declarationError`, without
+stalling pagination. Call a discovered tool with `tools[item.name](input)`;
+every exposed name remains callable even when its declaration is omitted from
+the inline catalogue.
+
+`codemode_search` is also a direct Pi tool, so declarations can be discovered
+before starting a Cell. Direct search reads the current exposure catalogue;
+in-Cell search reads the Cell's frozen exposure snapshot. Both expose only
+CodeMode-callable tools and use the same search implementation.
+
+Ordinary guest tool calls resolve to:
+
+```ts
+type PiToolResult<Output = unknown> = {
   content: Array<
     { type: "text"; text: string } | { type: "image"; data: string; mimeType: string }
   >;
-  details?: unknown;
+  details?: Output;
 };
 ```
 
+Each declaration derives its input from `parameters` and its `details` type
+from the registered definition's optional `outputSchema`. Source-gated fallback
+schemas cover Pi's built-in tools and `@howaboua/pi-codex-conversion` 3.0.23;
+tool-provided schemas take precedence. Other missing or unsupported output
+schemas remain `unknown`.
+
 Ordinary tool failures reject with a catchable `CodeModeToolError`. A Pi result
 that requests termination stops the complete CodeMode Session and cannot be
 caught by guest code.
@@ -268,7 +305,8 @@ last match wins. Project `tools` replaces the global array, while project
 
 An unmatched active tool defaults to `direct-and-codemode`; an unmatched
 inactive tool remains unavailable. An explicit rule may expose an inactive tool
-or activate direct access. The four `codemode_*` tools are always direct-only.
+or activate direct access. The five registered `codemode_*` tools are always
+direct-only.
 Pi's global allowed/excluded registry remains authoritative. Invalid fields or
 patterns disable CodeMode for that session without changing Pi's active tools.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-codemode",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Process-isolated persistent TypeScript tool composition for Pi",
   "keywords": [
@@ -35,16 +35,26 @@
   },
   "dependencies": {
     "deno": "2.9.5",
-    "minimatch": "^10.2.5",
-    "typescript": "6.0.3"
+    "minimatch": "^10.2.6",
+    "runtime-typescript": "npm:typescript@6.0.3",
+    "typescript": "^7.0.2"
+  },
+  "devDependencies": {
+    "@howaboua/pi-codex-conversion": "3.0.23"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
+    "@howaboua/pi-codex-conversion": "3.0.23",
     "typebox": "*"
   },
+  "peerDependenciesMeta": {
+    "@howaboua/pi-codex-conversion": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=22.19.0"
   },

package/src/codemode-cell-transform.ts

@@ -1,4 +1,4 @@
-import ts from "typescript";
+import ts from "runtime-typescript";
 
 /** Successful pure transform output consumed only by the worker-owned Notebook runtime. */
 export type TransformedCodeModeCell = {

package/src/codemode-known-output-schemas.ts

@@ -0,0 +1,222 @@
+import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+import { Type, type TSchema } from "typebox";
+import type { CodeModeToolSchema } from "./codemode-tool-catalog.js";
+
+const ClosedObject = { additionalProperties: false } as const;
+const OptionalUndefinedString = Type.Optional(Type.Union([Type.String(), Type.Undefined()]));
+const OptionalUndefinedNumber = Type.Optional(Type.Union([Type.Number(), Type.Undefined()]));
+
+const TruncationResultSchema = Type.Object(
+  {
+    content: Type.String(),
+    truncated: Type.Boolean(),
+    truncatedBy: Type.Union([Type.Literal("lines"), Type.Literal("bytes"), Type.Null()]),
+    totalLines: Type.Number(),
+    totalBytes: Type.Number(),
+    outputLines: Type.Number(),
+    outputBytes: Type.Number(),
+    lastLinePartial: Type.Boolean(),
+    firstLineExceedsLimit: Type.Boolean(),
+    maxLines: Type.Number(),
+    maxBytes: Type.Number(),
+  },
+  ClosedObject,
+);
+const ShellOutputSchema = Type.Object(
+  {
+    truncation: Type.Optional(TruncationResultSchema),
+    fullOutputPath: Type.Optional(Type.String()),
+  },
+  ClosedObject,
+);
+const ReadOutputSchema = Type.Object(
+  { truncation: Type.Optional(TruncationResultSchema) },
+  ClosedObject,
+);
+const EditOutputSchema = Type.Object(
+  {
+    diff: Type.String(),
+    patch: Type.String(),
+    firstChangedLine: Type.Optional(Type.Number()),
+  },
+  ClosedObject,
+);
+const GrepOutputSchema = Type.Object(
+  {
+    truncation: Type.Optional(TruncationResultSchema),
+    matchLimitReached: Type.Optional(Type.Number()),
+    linesTruncated: Type.Optional(Type.Boolean()),
+  },
+  ClosedObject,
+);
+const FindOutputSchema = Type.Object(
+  {
+    truncation: Type.Optional(TruncationResultSchema),
+    resultLimitReached: Type.Optional(Type.Number()),
+  },
+  ClosedObject,
+);
+const LsOutputSchema = Type.Object(
+  {
+    truncation: Type.Optional(TruncationResultSchema),
+    entryLimitReached: Type.Optional(Type.Number()),
+  },
+  ClosedObject,
+);
+
+const ExecutePatchResultSchema = Type.Object(
+  {
+    changedFiles: Type.Array(Type.String()),
+    createdFiles: Type.Array(Type.String()),
+    deletedFiles: Type.Array(Type.String()),
+    movedFiles: Type.Array(Type.String()),
+    fuzz: Type.Number(),
+  },
+  ClosedObject,
+);
+const ApplyPatchOutputSchema = Type.Union([
+  Type.Object({ status: Type.Literal("success"), result: ExecutePatchResultSchema }, ClosedObject),
+  Type.Object(
+    {
+      status: Type.Literal("partial_failure"),
+      result: ExecutePatchResultSchema,
+      failedTargets: Type.Optional(Type.Union([Type.Array(Type.String()), Type.Undefined()])),
+    },
+    ClosedObject,
+  ),
+]);
+const UnifiedExecOutputSchema = Type.Object(
+  {
+    chunk_id: Type.String(),
+    wall_time_seconds: Type.Number(),
+    output: Type.String(),
+    exit_code: OptionalUndefinedNumber,
+    session_id: OptionalUndefinedNumber,
+    original_token_count: OptionalUndefinedNumber,
+  },
+  ClosedObject,
+);
+const ImagegenOutputSchema = Type.Object(
+  {
+    path: Type.String(),
+    latest_path: Type.String(),
+    images: Type.Array(
+      Type.Object(
+        {
+          path: Type.String(),
+          absolute_path: Type.String(),
+          latest_path: Type.Optional(Type.String()),
+          latest_absolute_path: Type.Optional(Type.String()),
+        },
+        ClosedObject,
+      ),
+    ),
+    background: OptionalUndefinedString,
+    quality: OptionalUndefinedString,
+    size: OptionalUndefinedString,
+  },
+  ClosedObject,
+);
+// oxlint-disable-next-line anti-slop/no-unsafe-dictionary-type -- SAFETY: pi-codex-conversion intentionally exposes provider-defined web_run fields alongside these known text fields.
+type CodexWebRunPayload = Record<string, unknown> & {
+  encrypted_output?: string | undefined;
+  output_text?: string | undefined;
+  output?: string | undefined;
+  text?: string | undefined;
+};
+const WebRunPayloadSchema = Type.Unsafe<CodexWebRunPayload>(
+  Type.Object(
+    {
+      encrypted_output: OptionalUndefinedString,
+      output_text: OptionalUndefinedString,
+      output: OptionalUndefinedString,
+      text: OptionalUndefinedString,
+    },
+    { additionalProperties: true },
+  ),
+);
+const WebRunOutputSchema = Type.Object({ webRun: WebRunPayloadSchema }, ClosedObject);
+const ViewImageContentSchema = Type.Object(
+  {
+    type: Type.Literal("image"),
+    data: Type.String(),
+    mimeType: Type.String(),
+    detail: Type.Union([Type.Literal("high"), Type.Literal("original")]),
+  },
+  ClosedObject,
+);
+const ViewImageOutputSchema = Type.Union([
+  Type.Object({ viewImage: Type.Literal(true) }, ClosedObject),
+  Type.Object(
+    {
+      viewImageDescription: Type.Object(
+        {
+          image: ViewImageContentSchema,
+          path: Type.String(),
+          description: Type.String(),
+        },
+        ClosedObject,
+      ),
+    },
+    ClosedObject,
+  ),
+]);
+
+/** Source-gated fallback output schemas for Pi and pi-codex-conversion tool details. */
+export const CodeModeKnownOutputSchemas = {
+  builtin: {
+    bash: ShellOutputSchema,
+    powershell: ShellOutputSchema,
+    read: ReadOutputSchema,
+    edit: EditOutputSchema,
+    write: Type.Undefined(),
+    grep: GrepOutputSchema,
+    find: FindOutputSchema,
+    ls: LsOutputSchema,
+  },
+  codexConversion: {
+    apply_patch: ApplyPatchOutputSchema,
+    exec_command: UnifiedExecOutputSchema,
+    write_stdin: UnifiedExecOutputSchema,
+    view_image: ViewImageOutputSchema,
+    web_run: WebRunOutputSchema,
+    imagegen: ImagegenOutputSchema,
+  },
+} as const satisfies {
+  readonly builtin: Readonly<Record<string, TSchema>>;
+  readonly codexConversion: Readonly<Record<string, TSchema>>;
+};
+
+const CODEX_CONVERSION_SOURCE = "npm:@howaboua/pi-codex-conversion";
+
+function schemaByName(
+  schemas: Readonly<Record<string, TSchema>>,
+  name: string,
+): TSchema | undefined {
+  return schemas[name];
+}
+
+function isCodexConversionSource(sourceInfo: ToolInfo["sourceInfo"]): boolean {
+  return (
+    sourceInfo.origin === "package" &&
+    (sourceInfo.source === CODEX_CONVERSION_SOURCE ||
+      sourceInfo.source.startsWith(`${CODEX_CONVERSION_SOURCE}@`))
+  );
+}
+
+/** Returns a known output schema only when both the registered tool name and owner match. */
+export function resolveKnownToolOutputSchema(
+  tool: Pick<ToolInfo, "name" | "sourceInfo">,
+): CodeModeToolSchema | undefined {
+  if (
+    tool.sourceInfo.source === "builtin" &&
+    tool.sourceInfo.path === `<builtin:${tool.name}>` &&
+    tool.sourceInfo.scope === "temporary" &&
+    tool.sourceInfo.origin === "top-level"
+  ) {
+    return schemaByName(CodeModeKnownOutputSchemas.builtin, tool.name);
+  }
+  return isCodexConversionSource(tool.sourceInfo)
+    ? schemaByName(CodeModeKnownOutputSchemas.codexConversion, tool.name)
+    : undefined;
+}

package/src/codemode-session-coordinator.ts

@@ -7,7 +7,9 @@ import { CodeModeWorkerProcess } from "./codemode-deno-process.js";
 import { formatCodeModePresentationData } from "./codemode-presentation-output.js";
 import type { CodeModeRuntime, CodeModeTimerHandle } from "./codemode-runtime.js";
 import type { CodeModeResultSpillWriter } from "./codemode-session-files.js";
+import type { CodeModeToolSearchEntry } from "./codemode-tool-catalog.js";
 import {
+  CODEMODE_SEARCH_TOOL_NAME,
   createCodeModeFailure,
   createCodeModePending,
   createCodeModeSuccess,
@@ -123,6 +125,10 @@ export type CodeModeNestedToolBatch = {
   readonly sessionId: string;
   readonly batchId: string;
   readonly calls: readonly CodeModeNestedToolCall[];
+  /** Exact guest-callable name snapshot installed for this Cell. */
+  readonly exposedToolNames: readonly string[];
+  /** Immutable searchable declaration snapshot installed with this Cell's names. */
+  readonly searchEntries: readonly CodeModeToolSearchEntry[];
   readonly signal: AbortSignal;
   readonly onUpdate?: (update: CodeModeNestedToolUpdate) => void;
 };
@@ -159,7 +165,11 @@ export type CodeModeSessionOperationResult = {
 /** Construction capabilities and limits for one CodeMode Session coordinator. */
 export type CodeModeSessionCoordinatorOptions = {
   readonly maxSessions: number;
-  readonly getToolNames: () => readonly string[];
+  /** Captures guest-callable names and searchable declarations atomically for each Cell. */
+  readonly getToolSnapshot: () => {
+    readonly names: readonly string[];
+    readonly searchEntries: readonly CodeModeToolSearchEntry[];
+  };
   readonly executeToolBatch: ExecuteCodeModeNestedToolBatch;
   /** Private Result Spill storage for complete oversized presentation data. */
   readonly resultSpillWriter: CodeModeResultSpillWriter;
@@ -198,6 +208,8 @@ type ActiveCodeModeCell = {
   readonly resolveCompletion: (result: CodeModeResult) => void;
   readonly metadata: CodeModeMetadataAccumulator;
   readonly nestedTools: CodeModePresentationSnapshot["nested_tools"];
+  exposedToolNames: readonly string[];
+  searchEntries: readonly CodeModeToolSearchEntry[];
   activeToolNames: readonly string[];
   activeToolCount: number;
   failedNestedToolCount: number;
@@ -739,6 +751,8 @@ export class CodeModeSessionCoordinator {
       resolveCompletion: completion.resolve,
       metadata: emptyMetadataAccumulator(),
       nestedTools: [],
+      exposedToolNames: [],
+      searchEntries: [],
       activeToolNames: [],
       activeToolCount: 0,
       failedNestedToolCount: 0,
@@ -789,7 +803,13 @@ export class CodeModeSessionCoordinator {
       }, input.timeoutMs + CODEMODE_WATCHDOG_GRACE_MS);
     }
     try {
-      const toolNames = [...new Set(this.options.getToolNames())];
+      const toolSnapshot = this.options.getToolSnapshot();
+      const toolNames = [...new Set(toolSnapshot.names)];
+      cell.exposedToolNames = toolNames;
+      const exposedNames = new Set(toolNames);
+      cell.searchEntries = toolSnapshot.searchEntries.filter((entry) =>
+        exposedNames.has(entry.name),
+      );
       const requestBase = {
         version: 1,
         type: "execute",
@@ -900,9 +920,12 @@ export class CodeModeSessionCoordinator {
     cell: ActiveCodeModeCell,
     response: Extract<CodeModeWorkerResponse, { readonly type: "tool-batch" }>,
   ): Promise<void> {
-    cell.activeToolNames = [...new Set(response.calls.map((call) => call.toolName))];
-    cell.activeToolCount = response.calls.length;
-    cell.nestedToolCount += response.calls.length;
+    const piToolCalls = response.calls.filter(
+      (call) => call.toolName !== CODEMODE_SEARCH_TOOL_NAME,
+    );
+    cell.activeToolNames = [...new Set(piToolCalls.map((call) => call.toolName))];
+    cell.activeToolCount = piToolCalls.length;
+    cell.nestedToolCount += piToolCalls.length;
     record.lastActivityAtMs = this.runtime.now();
     this.publishObserverSnapshot();
 
@@ -927,6 +950,8 @@ export class CodeModeSessionCoordinator {
         sessionId: record.sessionId,
         batchId: response.batchId,
         calls: parsedCalls,
+        exposedToolNames: cell.exposedToolNames,
+        searchEntries: cell.searchEntries,
         signal: cell.abortController.signal,
       } as const;
       const onUpdate = (_update: CodeModeNestedToolUpdate): void => {
@@ -951,7 +976,7 @@ export class CodeModeSessionCoordinator {
       };
     }
     if (!this.isCurrentCell(record, cell)) return;
-    this.recordNestedToolPresentation(cell, response.calls, batchResult);
+    this.recordNestedToolPresentation(cell, piToolCalls, batchResult);
     cell.activeToolNames = [];
     cell.activeToolCount = 0;
     record.lastActivityAtMs = this.runtime.now();