pi-famulus 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-famulus",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Subagents, monitoring, and auto-backgrounding bash for pi",
   "type": "module",
   "license": "MIT",
@@ -15,10 +15,10 @@
   "files": ["src", "bin", "README.md"],
   "bin": { "pi-famulus": "./bin/pi-famulus.js" },
   "optionalDependencies": {
-    "pi-famulus-linux-x64": "0.1.0",
-    "pi-famulus-linux-arm64": "0.1.0",
-    "pi-famulus-darwin-x64": "0.1.0",
-    "pi-famulus-darwin-arm64": "0.1.0"
+    "pi-famulus-linux-x64": "0.1.2",
+    "pi-famulus-linux-arm64": "0.1.2",
+    "pi-famulus-darwin-x64": "0.1.2",
+    "pi-famulus-darwin-arm64": "0.1.2"
   },
   "pi": {
     "extensions": ["./src/index.ts"]
@@ -27,18 +27,17 @@
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },
-  "dependencies": {
-    "typebox": "^1.3.7"
-  },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.87.1",
-    "@earendil-works/pi-tui": "^0.87.1",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "^1.0.0",
     "@types/node": "^24.0.0",
+    "typebox": "1.3.27",
     "typescript": "7.0.2",
     "vitest": "^3.0.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*",
     "@earendil-works/pi-tui": "*"
   },
   "peerDependenciesMeta": {

package/src/bash-override.ts

@@ -17,7 +17,7 @@ import { randomUUID } from "node:crypto";
 import { writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { Type } from "typebox";
+import { Type, type Static } from "typebox";
 import type {
   AgentToolResult,
   BashToolDetails,
@@ -62,6 +62,46 @@ const bashParameters = Type.Object({
 
 type BashParams = { command: string; timeout?: number; run_in_background?: boolean };
 
+/**
+ * Mirrors the built-in bash outputSchema (pi ≥0.99) so codemode scripts calling
+ * `bash()` resolve to the same structured shape the built-in tool returns.
+ * pi does not export `bashOutputSchema`, so keep this in sync with BashToolOutput.
+ */
+const bashOutputSchema = Type.Object({
+  output: Type.String(),
+  truncated: Type.Boolean(),
+  full_output_path: Type.Optional(Type.String()),
+  exit_code: Type.Number(),
+  wall_time_seconds: Type.Number(),
+});
+type BashToolOutput = Static<typeof bashOutputSchema>;
+
+/** Same cap as the built-in structured output (1 MiB). */
+const STRUCTURED_OUTPUT_MAX_BYTES = 1024 * 1024;
+
+/** Full-output slice for structuredContent, keeping the tail like the built-in. */
+function structuredOutput(fullText: string): { output: string; truncated: boolean } {
+  if (Buffer.byteLength(fullText, "utf8") <= STRUCTURED_OUTPUT_MAX_BYTES) {
+    return { output: fullText, truncated: false };
+  }
+  // Keep the largest tail that fits the cap without materializing the whole
+  // output as a second buffer: search a UTF-16 index near the end (each code
+  // unit encodes to at least one byte, so the tail starts within `cap` units
+  // of the end) and only encode that slice.
+  let lo = Math.max(0, fullText.length - STRUCTURED_OUTPUT_MAX_BYTES);
+  let hi = fullText.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (Buffer.byteLength(fullText.slice(mid), "utf8") <= STRUCTURED_OUTPUT_MAX_BYTES) hi = mid;
+    else lo = mid + 1;
+  }
+  return { output: fullText.slice(lo), truncated: true };
+}
+
+function wallSeconds(startedAtMs: number, endedAtMs: number): number {
+  return Math.round((endedAtMs - startedAtMs) / 100) / 10;
+}
+
 /** Details shape returned by this override; superset of BashToolDetails. */
 export interface FamulusBashDetails extends BashToolDetails {
   backgrounded?: boolean;
@@ -130,6 +170,7 @@ async function executeLocal(
   clock: Clock,
 ): Promise<AgentToolResult<FamulusBashDetails | undefined>> {
   const timeoutMs = resolveTimeoutMs(params.timeout);
+  const startedAtMs = clock.now();
   const shell = process.env.SHELL && process.env.SHELL.length > 0 ? process.env.SHELL : "/bin/bash";
 
   const output = await new Promise<{ text: string; exitCode: number | null; signal: string | null; timedOut: boolean; aborted: boolean }>(
@@ -216,11 +257,26 @@ async function executeLocal(
   if (output.timedOut && params.timeout !== undefined) {
     throw new Error(appendStatus(text, timedOutStatus(params.timeout)));
   }
-  if (output.exitCode !== 0 && output.exitCode !== null) {
-    throw new Error(appendStatus(text, `Command exited with code ${output.exitCode}`));
-  }
   if (output.exitCode === null) throw new Error(appendStatus(text, killedBy(output.signal)));
-  return { content: [{ type: "text", text }], details };
+  const { output: structuredText, truncated: structuredTruncated } = structuredOutput(output.text);
+  const structuredContent: BashToolOutput = {
+    output: structuredText,
+    truncated: structuredTruncated,
+    ...(details?.fullOutputPath ? { full_output_path: details.fullOutputPath } : {}),
+    exit_code: output.exitCode,
+    wall_time_seconds: wallSeconds(startedAtMs, clock.now()),
+  };
+  if (output.exitCode !== 0) {
+    // Mirror the built-in bash tool: non-zero exits resolve to an isError
+    // result carrying structuredContent instead of rejecting.
+    return {
+      content: [{ type: "text", text: appendStatus(text, `Command exited with code ${output.exitCode}`) }],
+      details,
+      structuredContent,
+      isError: true,
+    };
+  }
+  return { content: [{ type: "text", text }], details, structuredContent };
 }
 
 // ---------------------------------------------------------------------------
@@ -245,6 +301,7 @@ export function createBashOverride(
       "Long-running bash commands are moved to the background automatically; do not poll or sleep to wait for them. End your turn (a reply with no tool call) and resume from the task wake when it arrives.",
     ],
     parameters: bashParameters,
+    outputSchema: bashOutputSchema,
     renderResult(result, { expanded }, theme, context) {
       const details = result.details as FamulusBashDetails | undefined;
       if (details?.backgrounded && details.task_id) {
@@ -291,6 +348,7 @@ export function createBashOverride(
       }
 
       const timeoutMs = resolveTimeoutMs(input.timeout);
+      const startedAtMs = (deps.clock ?? realClock).now();
       let start;
       try {
         start = await client.start({
@@ -358,15 +416,37 @@ export function createBashOverride(
       const collected = await collectOutput(client, start.task_id);
       const { text, details } = formatFinishedOutput(collected, outputPath);
       const exitCode = waitResult.exit_code ?? null;
-      if (exitCode !== 0 && exitCode !== null) {
-        throw new Error(appendStatus(text, `Command exited with code ${exitCode}`));
-      }
       // No exit code: killed (timeout, stop, crash), unless the manager
       // finished it as completed with its runner status unobservable.
       if (exitCode === null && collected.status !== "completed") {
         throw new Error(appendStatus(text, await killedStatus(client, start.task_id, input.timeout)));
       }
-      return { content: [{ type: "text", text }], details };
+      if (exitCode === null) {
+        // Completed but the exit code was unobservable: no honest
+        // structured shape (exit_code is required, and a sentinel like -1
+        // would misclassify success as failure), so omit structuredContent
+        // and let codemode scripts fall back to the text content.
+        return { content: [{ type: "text", text }], details };
+      }
+      const { output: structuredText, truncated: structuredTruncated } = structuredOutput(collected.text);
+      const structuredContent: BashToolOutput = {
+        output: structuredText,
+        truncated: structuredTruncated || collected.windowed,
+        full_output_path: outputPath,
+        exit_code: exitCode,
+        wall_time_seconds: wallSeconds(startedAtMs, (deps.clock ?? realClock).now()),
+      };
+      if (exitCode !== 0) {
+        // Mirror the built-in bash tool: non-zero exits resolve to an isError
+        // result carrying structuredContent instead of rejecting.
+        return {
+          content: [{ type: "text", text: appendStatus(text, `Command exited with code ${exitCode}`) }],
+          details,
+          structuredContent,
+          isError: true,
+        };
+      }
+      return { content: [{ type: "text", text }], details, structuredContent };
     },
   };
 }

package/src/manager-client.ts

@@ -16,7 +16,7 @@ import { famulusPaths } from "./config";
 import { realClock, type Clock, type ClockTimer } from "./clock";
 
 const MAX_FRAME_BYTES = 4 * 1024 * 1024; // 4 MiB (§3.3)
-const EXTENSION_VERSION = "0.1.0";
+const EXTENSION_VERSION = "0.1.2";
 // 3: speaks in-place upgrade (resends on reconnect, start keys).
 const PROTOCOL = 3;
 const HELLO_TIMEOUT_MS = 5000;

package/src/subagent/fleet-widget.ts

@@ -9,7 +9,7 @@
  * Driven by WorkIndex changes. Does not poll the manager.
  */
 import { realClock, type Clock, type ClockTimer } from "../clock";
-import { formatAge, type WorkIndex, type WorkItem } from "../work-index";
+import { formatAge, nextAgeBoundary, type WorkIndex, type WorkItem } from "../work-index";
 import { truncateToWidth } from "../tui/pi-tui-load";
 
 export const FLEET_WIDGET_KEY = "pi-famulus-fleet";
@@ -72,6 +72,7 @@ export class FleetWidget {
   private tui: FleetTui | null = null;
   private unsubscribe: (() => void) | null = null;
   private ageTimer: ClockTimer | null = null;
+  private ageTimerIsTimeout = false;
   private readonly clock: Clock;
 
   constructor(deps: FleetStatusDeps) {
@@ -93,10 +94,11 @@ export class FleetWidget {
     const counts = this.deps.index.counts();
     const activeAgents = items.filter((item) => item.kind === "agent" && isActive(item));
     const total = counts.workers + counts.subagents + counts.monitors;
-    if (activeAgents.length > 0 && !this.ageTimer) {
-      this.ageTimer = this.clock.setInterval(() => this.tui?.requestRender(), 5000);
-      this.clock.unref?.(this.ageTimer);
-    } else if (activeAgents.length === 0) {
+    // Always reschedule: an item added while a timeout is pending may have
+    // an earlier boundary, and a removed item must not tick for stale state.
+    if (activeAgents.length > 0) {
+      this.startAgeTicker();
+    } else {
       this.clearAgeTimer();
     }
     if (total === 0) {
@@ -109,6 +111,11 @@ export class FleetWidget {
         (tui, theme) => {
           this.tui = tui;
           this.widgetRegistered = true;
+          // The ticker refuses to schedule while no component is mounted
+          // (refresh may have run before the host invoked the factory).
+          if (!this.ageTimer && this.deps.index.list(this.clock.now()).some((item) => item.kind === "agent" && isActive(item))) {
+            this.scheduleNextAgeTick();
+          }
           return {
             render: (width) => this.renderLine(width, theme),
             invalidate: () => {},
@@ -136,10 +143,43 @@ export class FleetWidget {
     if (ui) this.clearWidget(ui);
   }
 
+  /**
+   * Tick exactly when a displayed age changes. formatAge rounds
+   * (now - startedAt) to the nearest second, so each live item's visible
+   * value flips on half-second boundaries relative to its own startedAt —
+   * a global phase would be early/late for items started off the second.
+   * Schedule the earliest pending flip and re-evaluate after every tick.
+   */
+  private startAgeTicker(): void {
+    this.clearAgeTimer();
+    this.scheduleNextAgeTick();
+  }
+
+  private scheduleNextAgeTick(): void {
+    const now = this.clock.now();
+    const items = this.deps.index.list(now).filter((item) => item.kind === "agent" && isActive(item));
+    if (items.length === 0 || !this.tui) return;
+    let next = Infinity;
+    for (const item of items) {
+      next = Math.min(next, nextAgeBoundary(now, item.startedAt));
+    }
+    this.ageTimerIsTimeout = true;
+    this.ageTimer = this.clock.setTimeout(() => {
+      this.ageTimer = null;
+      this.ageTimerIsTimeout = false;
+      this.tui?.requestRender();
+      // Phases and the active set may have changed; schedule the next flip.
+      this.scheduleNextAgeTick();
+    }, next - now);
+    this.clock.unref?.(this.ageTimer);
+  }
+
   private clearAgeTimer(): void {
     if (!this.ageTimer) return;
-    this.clock.clearInterval(this.ageTimer);
+    if (this.ageTimerIsTimeout) this.clock.clearTimeout(this.ageTimer);
+    else this.clock.clearInterval(this.ageTimer);
     this.ageTimer = null;
+    this.ageTimerIsTimeout = false;
   }
 
   private clearWidget(ui: FleetUi): void {

package/src/subagent/pi-runtime.ts

@@ -161,9 +161,11 @@ function wrapSession(
   return {
     ...(extras.warning !== undefined ? { warning: extras.warning } : {}),
     ...(extras.resolvedModel !== undefined ? { resolvedModel: extras.resolvedModel } : {}),
-    prompt: (text) => session.prompt(text),
-    steer: (text) => session.steer(text),
-    followUp: (text) => session.followUp(text),
+    // pi ≥0.99 returns QueuedInputDisposition ("handled" | "queued") from
+    // input methods; the adapter contract stays Promise<void>.
+    prompt: async (text) => { await session.prompt(text); },
+    steer: async (text) => { await session.steer(text); },
+    followUp: async (text) => { await session.followUp(text); },
     abort: () => session.abort(),
     waitForIdle: () => session.waitForIdle(),
     getLastAssistantText: () => session.getLastAssistantText(),

package/src/tui/tasks-command.ts

@@ -10,13 +10,12 @@ import type { ManagerClient, TaskRecord } from "../manager-client";
 import { taskOutputPath } from "../config";
 import { formatConversation } from "../subagent/conversation";
 import type { SubagentRegistry } from "../subagent/registry";
-import { formatAge, type WorkIndex, type WorkItem } from "../work-index";
+import { formatAge, nextAgeBoundary, type WorkIndex, type WorkItem } from "../work-index";
 import { notifyPlainFallback, showScrollDetail } from "./scroll-detail-view";
 import { readTaskFileTailCached, stderrPathFor } from "./task-output-paths";
 import { fitLines, loadPiTui, truncateToWidth } from "./pi-tui-load";
 import { statusGlyph } from "./tool-component";
 
-const AGE_TICK_MS = 1000;
 
 function isLive(item: WorkItem): boolean {
   return item.status === "pending" || item.status === "running";
@@ -261,9 +260,36 @@ async function showTaskList(
       let loadingAll = false;
       let confirmId: string | undefined;
       let hint = "";
-      const unsub = subscribe(() => tui.requestRender());
-      const ageTimer = clock.setInterval(() => tui.requestRender(), AGE_TICK_MS);
-      clock.unref?.(ageTimer);
+      // formatAge rounds (now - startedAt) to the nearest second, so each
+      // live row's visible age flips on half-second boundaries relative to
+      // its own startedAt. Schedule the earliest pending flip and
+      // re-evaluate after every tick and every index change.
+      let ageTimer: unknown = null;
+      const clearAgeTimer = () => {
+        if (ageTimer === null) return;
+        clock.clearTimeout(ageTimer);
+        ageTimer = null;
+      };
+      const scheduleAgeTick = () => {
+        clearAgeTimer();
+        const now = clock.now();
+        let next = Infinity;
+        for (const item of visibleItems()) {
+          if (!isLive(item)) continue;
+          next = Math.min(next, nextAgeBoundary(now, item.startedAt));
+        }
+        if (!Number.isFinite(next)) return;
+        ageTimer = clock.setTimeout(() => {
+          ageTimer = null;
+          tui.requestRender();
+          scheduleAgeTick();
+        }, next - now);
+        clock.unref?.(ageTimer);
+      };
+      const unsub = subscribe(() => {
+        tui.requestRender();
+        scheduleAgeTick();
+      });
       const border = new DynamicBorder((text) => theme.fg("border", text));
       const pageSize = () => Math.max(1, (tui.terminal?.rows ?? 24) - 8);
       const matches = (data: string, id: "tui.select.up" | "tui.select.down" | "tui.select.confirm" | "tui.select.cancel") => {
@@ -273,6 +299,7 @@ async function showTaskList(
         scope === "all" ? mergeItems(getItems(), allItems) : getItems(),
         filter,
       );
+      scheduleAgeTick();
       const choose = (id: string | undefined) => {
         selectedId = id;
         hint = "";
@@ -394,7 +421,10 @@ async function showTaskList(
             tui.requestRender();
           }
         },
-        dispose() { clock.clearInterval(ageTimer); unsub(); },
+        dispose() {
+          clearAgeTimer();
+          unsub();
+        },
       };
     },
     // Bottom sheet over the editor, where the user typed /tasks; the list is

package/src/work-index.ts

@@ -180,3 +180,19 @@ export function formatAge(startedAt: number, endedAt: number | undefined, now: n
   if (ms < 3_600_000) return `${Math.floor(ms / 60_000)}m${Math.round((ms % 60_000) / 1000)}s`;
   return `${Math.floor(ms / 3_600_000)}h${Math.floor((ms % 3_600_000) / 60_000)}m`;
 }
+
+/**
+ * Next time the age displayed by {@link formatAge} for an item started at
+ * `startedAt` changes, given at most one render per second.
+ *
+ * Below 1s formatAge shows raw milliseconds, so a sub-second item's first
+ * scheduled update is the transition to "1s" at the 1s mark. At 1s and above
+ * the value rounds to the nearest second and flips on half-second boundaries
+ * relative to `startedAt`.
+ */
+export function nextAgeBoundary(now: number, startedAt: number): number {
+  const age = now - startedAt;
+  if (age < 1000) return now + (1000 - age);
+  const offset = age % 1000;
+  return now + (offset < 500 ? 500 - offset : 1500 - offset);
+}