@ian-pascoe/pi-codemode 0.1.0 → 0.3.0

package/README.md

@@ -62,11 +62,44 @@ codemode_cancel({ sessionId: string });
 Stops the session process and frees its capacity. The cancel call succeeds;
 subsequent polling returns the retained `cancellation` failure.
 
-All three tools return:
+### `codemode_sessions`
 
 ```ts
+codemode_sessions({});
+```
+
+Lists every live Session, with idle Sessions first in least-recently-used order,
+then running Sessions in least-recently-used order. Listing does not refresh
+Session recency.
+
+```ts
+type CodeModeSessionsResult = {
+  result: "success";
+  sessions: Array<{
+    sessionId: string;
+    state: "idle" | "running";
+    cellCount: number;
+    lastActivityAtMs: number;
+  }>;
+};
+```
+
+The execute, result, and cancel tools return:
+
+```ts
+type CodeModeConsoleEntry = {
+  method: "log" | "info" | "warn" | "error" | "debug";
+  text: string;
+};
+
 type CodeModeResult =
-  | { result: "success"; sessionId: string; data?: JsonValue }
+  | {
+      result: "success";
+      sessionId: string;
+      data?: JsonValue;
+      reclaimedSessionId?: string;
+      console?: CodeModeConsoleEntry[];
+    }
   | { result: "pending"; sessionId: string }
   | {
       result: "failed";
@@ -76,6 +109,7 @@ type CodeModeResult =
           | "unknown"
           | "busy"
           | "capacity"
+          | "eviction"
           | "script"
           | "serialization"
           | "timeout"
@@ -84,6 +118,7 @@ type CodeModeResult =
           | "runtime";
         message: string;
       };
+      console?: CodeModeConsoleEntry[];
     };
 ```
 
@@ -91,29 +126,57 @@ type CodeModeResult =
 result text returned to the model. Pi retains additional bounded Presentation
 Snapshots in tool-result details for Transcript replay and the TUI.
 
+Cells may call `console.log`, `console.info`, `console.warn`, `console.error`,
+and `console.debug`. One call creates one ordered entry without a trailing
+newline, while embedded newlines remain intact:
+
+```ts
+console.log("answer:", 42);
+return 42;
+```
+
+```json
+{
+  "result": "success",
+  "sessionId": "...",
+  "data": 42,
+  "console": [{ "method": "log", "text": "answer: 42" }]
+}
+```
+
+Formatting matches the pinned Deno Console for format tokens, primitives,
+spacing, and multiline inspection. Getters, coercion hooks, and custom
+inspectors do not run; CodeMode uses safe inspection instead when that differs
+from Deno. Console output arrives only with terminal results. Ordinary script,
+serialization, and worker-reported runtime failures retain prior calls. A
+timeout, cancellation, termination, or process death may omit them because the
+parent kills the worker before it can reply.
+
 ## Transcript and Observer UI
 
-The CodeMode Transcript gives all three tools semantic collapsed and expanded
+The CodeMode Transcript gives all four tools semantic collapsed and expanded
 rendering. Collapsed rows prioritize Cell lifecycle, a short Session ID, Cell
-Ordinal, returned-value shape, nested-tool count, and elapsed time. Expanded
-rows show the full Session ID, explicit call arguments, TypeScript source,
-structured returned data or error, and bounded nested-tool names, outcomes, and
-durations. Nested arguments and raw nested outputs are never copied into the
-presentation.
+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.
 
 Status always uses a symbol and text together:
 
 ```text
 ◉ running   ○ idle   ✓ completed
-× failed    ■ cancelled   ! timed out
+× failed    ■ cancelled   ■ reclaimed   ! timed out
 ```
 
 Awaited Cells publish a presentation update immediately and once per second.
-Source display is limited to 200 lines or 50 KB. Returned-data display uses
-Pi's 2,000-line/50-KB limit; complete oversized data is written to a private
-Result Spill while the model-facing result remains unchanged. Result Spill
-files last for the live Pi session. Replayed history falls back to its retained
-bounded data when a prior spill is no longer available.
+Collapsed calls show one highlighted line inline or the first eight highlighted
+lines of a multi-line Cell. Expanded calls show the complete TypeScript source.
+Returned-data display uses Pi's 2,000-line/50-KB limit; complete oversized data
+is written to a private Result Spill while the model-facing result remains
+unchanged. Result Spill files last for the live Pi session. Replayed history
+falls back to its retained bounded data when a prior spill is no longer
+available.
 
 In TUI mode, the read-only CodeMode Observer UI appears above the editor during
 Cell activity. It shows up to eight running, idle, or recently terminal
@@ -204,12 +267,18 @@ 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 three `codemode_*` tools are always direct-only.
+or activate direct access. The four `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.
 
-`maxSessions` defaults to 8 and counts only live Deno processes. Up to 64 recent
-worker-free terminal or failed-admission records remain pollable.
+`maxSessions` defaults to 8 and counts only live Deno processes. When capacity
+is full, a new Session gracefully stops the least-recently-used idle Session
+before starting; its Notebook Bindings are discarded, the new success reports
+`reclaimedSessionId`, and polling the old ID returns `eviction`. Running Sessions
+are never reclaimed, so admission still returns `capacity` when every process is
+busy. Executing or polling refreshes recency; listing and Observer rendering do
+not. Up to 64 recent worker-free terminal or failed-admission records remain
+pollable.
 
 ## Isolation and limits
 
@@ -219,13 +288,16 @@ generated helper source out of ordinary source locations. Every operating-system
 permission class is denied: filesystem read/write, network, environment, system
 information, subprocesses, FFI, and remote imports.
 
-Guest code receives ECMAScript built-ins, a read-only `tools` object, and only a
-frozen `Deno.version` identity. Raw process and standard-stream access,
-`console`, `Worker`, timers, filesystem/network APIs, and module loading are
-withheld. The parent watchdog terminates the subprocess for timeout or an
-infinite loop. Deno/V8 bounds each Session to a 128 MiB old-space heap and a
-1 MiB stack. Protocol inputs, tool results, and Cell results remain JSON-only
-and limited to 8 MiB of UTF-8.
+Guest code receives ECMAScript built-ins, a read-only `tools` object, a frozen
+five-method Console facade, and only a frozen `Deno.version` identity. Raw
+process and standard-stream access, `Worker`, timers, filesystem/network APIs,
+and module loading are withheld. Console calls never write to worker streams and
+do not include output from registered Pi tool handlers. The parent watchdog
+terminates the subprocess for timeout or an infinite loop. Deno/V8 bounds each
+Session to a 128 MiB old-space heap and a 1 MiB stack. Protocol inputs, tool
+results, returned data, and Console entries share one 8 MiB UTF-8 worker-message
+limit. An oversized response becomes the bounded `serialization` failure and
+may omit its Console entries.
 
 Registered Pi tools still execute in Pi's parent process with their normal
 permissions and lifecycle hooks. Cancellation aborts them through Pi's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-codemode",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "private": false,
   "description": "Process-isolated persistent TypeScript tool composition for Pi",
   "keywords": [
@@ -32,10 +32,6 @@
     "access": "public",
     "provenance": true
   },
-  "scripts": {
-    "test": "vitest run --config ../../vitest.config.ts --root .",
-    "typecheck": "tsc --noEmit -p tsconfig.json"
-  },
   "dependencies": {
     "deno": "2.9.5",
     "minimatch": "^10.2.5",
@@ -55,5 +51,9 @@
     "extensions": [
       "./src/index.ts"
     ]
+  },
+  "scripts": {
+    "test": "vitest run --config ../../vitest.config.ts --root .",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
   }
-}
+}

package/src/codemode-console-output.ts

@@ -0,0 +1,11 @@
+/** Console methods captured from a CodeMode Cell in call order. */
+export const CODEMODE_CONSOLE_METHODS = ["log", "info", "warn", "error", "debug"] as const;
+
+/** One supported CodeMode Cell Console method. */
+export type CodeModeConsoleMethod = (typeof CODEMODE_CONSOLE_METHODS)[number];
+
+/** One captured CodeMode Cell Console call without a synthetic trailing newline. */
+export type CodeModeConsoleEntry = {
+  readonly method: CodeModeConsoleMethod;
+  readonly text: string;
+};

package/src/codemode-observer-ui.ts

@@ -12,6 +12,11 @@ import type {
   CodeModeObserverSnapshot,
   CodeModeUnexpectedFailure,
 } from "./codemode-session-coordinator.js";
+import {
+  boundedCodeModeElapsedMs,
+  formatCodeModeDuration,
+  shortestUniqueCodeModeSessionPrefix,
+} from "./codemode-session-coordinator.js";
 
 const CODEMODE_OBSERVER_UI_KEY = "codemode-observer";
 const CODEMODE_OBSERVER_ROW_LIMIT = 8;
@@ -72,7 +77,7 @@ export type CodeModeObserverRow = {
   /** Idle Session summary retained only during relevant Observer activity. */
   | { readonly state: "idle"; readonly cellCount: number }
   | {
-      readonly state: "failed" | "cancelled" | "timed_out";
+      readonly state: "failed" | "cancelled" | "reclaimed" | "timed_out";
       /** Most recent one-based Cell Ordinal, or Session Cell count when no final Cell exists. */
       readonly cellOrdinal: number;
     }
@@ -102,6 +107,7 @@ const CODEMODE_OBSERVER_STATE_PRESENTATION = {
   idle: { symbol: "○", label: "idle", color: "muted" },
   failed: { symbol: "×", label: "failed", color: "error" },
   cancelled: { symbol: "■", label: "cancelled", color: "warning" },
+  reclaimed: { symbol: "■", label: "reclaimed", color: "warning" },
   timed_out: { symbol: "!", label: "timed out", color: "error" },
 } satisfies Record<CodeModeObserverState, CodeModeObserverStatePresentation>;
 
@@ -130,33 +136,21 @@ function shortestUniqueCodeModeSessionPrefixes(
     const safe = sanitizeCodeModeObserverText(session.sessionId);
     return safe.length === 0 ? "unknown" : safe;
   });
-  return identifiers.map((identifier, index) => {
-    let length = Math.min(8, identifier.length);
-    while (
-      length < identifier.length &&
-      identifiers.some(
-        (candidate, candidateIndex) =>
-          candidateIndex !== index && candidate.startsWith(identifier.slice(0, length)),
-      )
-    ) {
-      length += 1;
-    }
-    return identifier.slice(0, length);
-  });
-}
-
-function boundedElapsedMilliseconds(nowMs: number, startedAtMs: number): number {
-  const elapsed = Math.round(nowMs - startedAtMs);
-  if (!Number.isFinite(elapsed)) return 0;
-  return Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, elapsed));
+  return identifiers.map((identifier, index) =>
+    shortestUniqueCodeModeSessionPrefix(
+      identifier,
+      identifiers.filter((_candidate, candidateIndex) => candidateIndex !== index),
+    ),
+  );
 }
 
 function codeModeTerminalObserverState(
   session: CodeModeObservedSession,
-): Extract<CodeModeObserverState, "failed" | "cancelled" | "timed_out"> {
+): Extract<CodeModeObserverState, "failed" | "cancelled" | "reclaimed" | "timed_out"> {
   if (session.terminal_error_code === "cancellation" || session.last_cell?.state === "cancelled") {
     return "cancelled";
   }
+  if (session.terminal_error_code === "eviction") return "reclaimed";
   if (session.terminal_error_code === "timeout" || session.last_cell?.state === "timed_out") {
     return "timed_out";
   }
@@ -180,7 +174,7 @@ function projectCodeModeObserverRow(
       sessionPrefix,
       state: "running",
       cellOrdinal: session.current_cell.ordinal,
-      elapsedMs: boundedElapsedMilliseconds(nowMs, session.current_cell.started_at_ms),
+      elapsedMs: boundedCodeModeElapsedMs(session.current_cell.started_at_ms, nowMs),
       activeToolNames,
       activeToolCount: Math.max(session.current_cell.active_tool_count, activeToolNames.length),
     };
@@ -230,13 +224,6 @@ export function buildCodeModeObserverView(
   };
 }
 
-function formatCodeModeObserverDuration(elapsedMs: number): string {
-  if (elapsedMs < 1_000) return `${elapsedMs}ms`;
-  if (elapsedMs < 60_000) return `${(elapsedMs / 1_000).toFixed(1)}s`;
-  const seconds = Math.floor(elapsedMs / 1_000);
-  return `${Math.floor(seconds / 60)}m ${String(seconds % 60).padStart(2, "0")}s`;
-}
-
 function formatCodeModeObserverToolActivity(
   row: Extract<CodeModeObserverRow, { state: "running" }>,
 ): string | undefined {
@@ -254,10 +241,6 @@ function codeModeObserverRowDetail(row: CodeModeObserverRow): string {
     : `Cell ${row.cellOrdinal}`;
 }
 
-function joinCodeModeObserverRow(parts: readonly string[], separator: string): string {
-  return parts.join(separator);
-}
-
 function renderCodeModeObserverRow(
   row: CodeModeObserverRow,
   width: number,
@@ -268,9 +251,7 @@ function renderCodeModeObserverRow(
   const status = theme.fg(presentation.color, presentation.label);
   const detail = theme.fg("muted", codeModeObserverRowDetail(row));
   const duration =
-    row.state === "running"
-      ? theme.fg("muted", formatCodeModeObserverDuration(row.elapsedMs))
-      : undefined;
+    row.state === "running" ? theme.fg("muted", formatCodeModeDuration(row.elapsedMs)) : undefined;
   const toolActivity =
     row.state === "running" ? formatCodeModeObserverToolActivity(row) : undefined;
   const themedToolActivity =
@@ -283,13 +264,13 @@ function renderCodeModeObserverRow(
     [identity, status],
   ].map((parts) => parts.filter((part): part is string => part !== undefined));
   for (const parts of candidates) {
-    const line = joinCodeModeObserverRow(parts, separator);
+    const line = parts.join(separator);
     if (visibleWidth(line) <= width) return line;
   }
 
   const compactSeparator = theme.fg("dim", CODEMODE_OBSERVER_COMPACT_SEPARATOR_TEXT);
   const compactIdentity = `${theme.fg(presentation.color, presentation.symbol)} ${theme.bold(row.sessionPrefix)}`;
-  const compact = joinCodeModeObserverRow([compactIdentity, status], compactSeparator);
+  const compact = [compactIdentity, status].join(compactSeparator);
   if (visibleWidth(compact) <= width) return compact;
   return truncateToWidth(compact, width, CODEMODE_OBSERVER_ELLIPSIS);
 }