@pi-ohm/subagents 0.6.4-dev.22169815567.1.cdde4e8 → 0.6.4-dev.22170486101.1.c0abdac

package/README.md

@@ -96,6 +96,76 @@ Nested interactive-shell outputs are sanitized to strip runtime metadata lines (
 
 For unknown tasks/expired tasks, error categorization is explicit: `error_category: "not_found"`.
 
+## Operator cookbook
+
+### 1) Sync vs async recommendation matrix
+
+| scenario                                        | recommended mode                         | why                                                     |
+| ----------------------------------------------- | ---------------------------------------- | ------------------------------------------------------- |
+| quick lookup, single task, result needed now    | `start` (default sync)                   | simplest UX; one call, one terminal result              |
+| long-running analysis where caller can continue | `start async:true` + `wait/status` later | avoids blocking; keeps task lifecycle explicit          |
+| fan-out independent tasks                       | `start tasks[] parallel:true`            | deterministic ordered aggregation + bounded concurrency |
+| follow-up on active task                        | `send`                                   | preserves task history + follow-up prompts              |
+| stop background task                            | `cancel`                                 | explicit terminal transition + abort propagation        |
+
+Default policy: use sync first; opt into async only when needed.
+
+### 2) Backend tradeoff matrix
+
+| backend                       | strengths                                                                    | tradeoffs                                        | when to pick                               |
+| ----------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------ |
+| `interactive-shell` (default) | mature nested CLI behavior; straightforward rollback                         | text-capture based transcript fidelity           | safe baseline/default                      |
+| `interactive-sdk` (opt-in)    | structured tool/assistant events, event-derived rows, better inline fidelity | newer path; needs smoke/ops confidence           | pre-prod validation + richer observability |
+| `none`                        | deterministic scaffold output                                                | no real execution                                | testing/demo/debug wiring only             |
+| `custom-plugin`               | reserved hook                                                                | not implemented (`unsupported_subagent_backend`) | none currently                             |
+
+Fallback policy:
+
+- enable `OHM_SUBAGENTS_SDK_FALLBACK_TO_CLI=true` to downgrade only recoverable SDK bootstrap failures (`task_backend_execution_failed`) from SDK -> CLI path.
+
+### 3) Recommended smoke matrix
+
+```bash
+# default backend visibility
+printf '/ohm-subagents\n' | pi -e ./packages/subagents/extension.ts
+
+# explicit sdk backend visibility
+mkdir -p /tmp/pi-ohm-sdk-smoke
+cat >/tmp/pi-ohm-sdk-smoke/ohm.json <<'EOF'
+{ "subagentBackend": "interactive-sdk" }
+EOF
+printf '/ohm-subagents\n' | PI_CONFIG_DIR=/tmp/pi-ohm-sdk-smoke pi -e ./packages/subagents/extension.ts
+```
+
+Task lifecycle smoke checklist:
+
+1. sync single `start`
+2. async single `start async:true` + `status` + `wait`
+3. `cancel` running task
+4. batch partial acceptance (`tasks[]` mixed validity)
+5. timeout path (`wait timeout_ms`)
+6. follow-up `send` on running task
+
+### 4) Troubleshooting quick map
+
+| symptom                                 | likely cause                                                   | check/fix                                                                      |
+| --------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| output looks scaffolded/echoed          | backend is `none`                                              | set `subagentBackend` to `interactive-shell` or `interactive-sdk`              |
+| sdk selected but execution drops to cli | fallback env enabled and sdk hit recoverable bootstrap failure | inspect `OHM_SUBAGENTS_SDK_FALLBACK_TO_CLI`; disable to keep hard sdk failures |
+| `task_wait_timeout`                     | task still non-terminal at timeout                             | increase `timeout_ms`, poll with `status`, or reduce batch size                |
+| `task_wait_aborted`                     | caller signal cancelled wait                                   | retry wait with active signal                                                  |
+| `task_expired` on old IDs               | retention/capacity eviction                                    | increase retention/cap env knobs; treat task IDs as ephemeral                  |
+| too many inline progress updates        | high-frequency non-terminal emissions                          | increase `OHM_SUBAGENTS_ONUPDATE_THROTTLE_MS`                                  |
+
+### 5) Guardrail env knobs
+
+- `OHM_SUBAGENTS_TASK_RETENTION_MS` — terminal task retention window
+- `OHM_SUBAGENTS_TASK_MAX_EVENTS` — per-task structured event cap
+- `OHM_SUBAGENTS_TASK_MAX_ENTRIES` — in-memory task registry cap
+- `OHM_SUBAGENTS_TASK_MAX_EXPIRED_ENTRIES` — expired-task reason cache cap
+- `OHM_SUBAGENTS_ONUPDATE_THROTTLE_MS` — non-terminal onUpdate emission throttle
+- `OHM_SUBAGENTS_OUTPUT_MAX_CHARS` — terminal output payload cap
+
 ### Output truncation policy
 
 Task output returned in tool payloads is capped to prevent oversized context injection.
@@ -160,7 +230,15 @@ Persistence details:
 
 - default snapshot path: `${PI_CONFIG_DIR|PI_CODING_AGENT_DIR|PI_AGENT_DIR|~/.pi/agent}/ohm.subagents.tasks.json`
 - retention window is configurable via `OHM_SUBAGENTS_TASK_RETENTION_MS` (positive integer ms)
+- per-task structured event timeline cap is configurable via `OHM_SUBAGENTS_TASK_MAX_EVENTS`
+  (default `120`)
+- in-memory task registry capacity is configurable via `OHM_SUBAGENTS_TASK_MAX_ENTRIES`
+  (default `200`); oldest terminal tasks are evicted first once cap is exceeded
+- expired-task reason cache is configurable via `OHM_SUBAGENTS_TASK_MAX_EXPIRED_ENTRIES`
+  (default `500`)
 - corrupt snapshot files are auto-recovered to `*.corrupt-<epoch>` and runtime falls back to empty state
+- inline `onUpdate` emission is throttled via `OHM_SUBAGENTS_ONUPDATE_THROTTLE_MS`
+  (default `120ms`) with duplicate-frame suppression to avoid async wait/update spam
 
 ## Migration notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-ohm/subagents",
-  "version": "0.6.4-dev.22169815567.1.cdde4e8",
+  "version": "0.6.4-dev.22170486101.1.c0abdac",
   "homepage": "https://github.com/pi-ohm/pi-ohm/tree/dev/packages/subagents#readme",
   "repository": {
     "type": "git",
@@ -20,8 +20,8 @@
   },
   "dependencies": {
     "@mariozechner/pi-coding-agent": "catalog:pi",
-    "@pi-ohm/config": "0.6.4-dev.22169815567.1.cdde4e8",
-    "@pi-ohm/tui": "0.6.4-dev.22169815567.1.cdde4e8",
+    "@pi-ohm/config": "0.6.4-dev.22170486101.1.c0abdac",
+    "@pi-ohm/tui": "0.6.4-dev.22170486101.1.c0abdac",
     "better-result": "catalog:",
     "zod": "catalog:"
   },

package/src/runtime/tasks.test.ts

@@ -615,6 +615,46 @@ defineTest("retention policy expires terminal tasks with explicit error reason",
   assert.match(String(lookup?.errorMessage), /retention policy/);
 });
 
+defineTest("capacity policy evicts oldest terminal tasks when maxTasks is exceeded", () => {
+  let now = 1000;
+  const store = createInMemoryTaskRuntimeStore({
+    now: () => now,
+    retentionMs: 60_000,
+    maxTasks: 2,
+  });
+
+  for (const taskId of ["task_1", "task_2", "task_3"]) {
+    const created = store.createTask({
+      taskId,
+      subagent: finderSubagent,
+      description: `Task ${taskId}`,
+      prompt: `Prompt ${taskId}`,
+      backend: "scaffold",
+      invocation: "task-routed",
+    });
+    assert.equal(Result.isOk(created), true);
+
+    now += 5;
+    const running = store.markRunning(taskId, `Running ${taskId}`);
+    assert.equal(Result.isOk(running), true);
+
+    now += 5;
+    const succeeded = store.markSucceeded(taskId, `Done ${taskId}`, `Output ${taskId}`);
+    assert.equal(Result.isOk(succeeded), true);
+  }
+
+  const remainingIds = store
+    .listTasks()
+    .map((snapshot) => snapshot.id)
+    .sort();
+  assert.deepEqual(remainingIds, ["task_2", "task_3"]);
+
+  const evicted = store.getTasks(["task_1"])[0];
+  assert.equal(evicted?.found, false);
+  assert.equal(evicted?.errorCode, "task_expired");
+  assert.match(String(evicted?.errorMessage), /capacity policy/);
+});
+
 defineTest("corrupt persistence snapshot falls back to empty store and records diagnostics", () => {
   withTempDir((dir) => {
     const filePath = join(dir, "tasks.json");

package/src/runtime/tasks.ts

@@ -19,6 +19,8 @@ export interface TaskRuntimeObservability {
 const TASK_PERSISTENCE_SCHEMA_VERSION = 1;
 const DEFAULT_RETENTION_MS = 1000 * 60 * 60 * 24;
 const DEFAULT_MAX_EVENTS_PER_TASK = 120;
+const DEFAULT_MAX_TASKS = 200;
+const DEFAULT_MAX_EXPIRED_TASKS = 500;
 
 export interface TaskRuntimeSnapshot {
   readonly id: string;
@@ -748,6 +750,8 @@ export interface InMemoryTaskRuntimeStoreOptions {
   readonly retentionMs?: number;
   readonly persistence?: TaskRuntimePersistence;
   readonly maxEventsPerTask?: number;
+  readonly maxTasks?: number;
+  readonly maxExpiredTasks?: number;
 }
 
 class InMemoryTaskRuntimeStore implements TaskRuntimeStore {
@@ -758,6 +762,8 @@ class InMemoryTaskRuntimeStore implements TaskRuntimeStore {
   private readonly retentionMs: number;
   private readonly persistence: TaskRuntimePersistence | undefined;
   private readonly maxEventsPerTask: number;
+  private readonly maxTasks: number;
+  private readonly maxExpiredTasks: number;
 
   constructor(options: InMemoryTaskRuntimeStoreOptions = {}) {
     this.now = options.now ?? (() => Date.now());
@@ -770,6 +776,12 @@ class InMemoryTaskRuntimeStore implements TaskRuntimeStore {
       options.maxEventsPerTask !== undefined && options.maxEventsPerTask > 0
         ? options.maxEventsPerTask
         : DEFAULT_MAX_EVENTS_PER_TASK;
+    this.maxTasks =
+      options.maxTasks !== undefined && options.maxTasks > 0 ? options.maxTasks : DEFAULT_MAX_TASKS;
+    this.maxExpiredTasks =
+      options.maxExpiredTasks !== undefined && options.maxExpiredTasks > 0
+        ? options.maxExpiredTasks
+        : DEFAULT_MAX_EXPIRED_TASKS;
 
     this.hydrateFromPersistence();
     this.pruneExpiredTerminalTasks();
@@ -789,6 +801,8 @@ class InMemoryTaskRuntimeStore implements TaskRuntimeStore {
       );
     }
 
+    this.expiredTasks.delete(input.taskId);
+
     const now = this.now();
     const initialRecord: TaskRecord = {
       id: input.taskId,
@@ -816,6 +830,7 @@ class InMemoryTaskRuntimeStore implements TaskRuntimeStore {
     };
 
     this.tasks.set(input.taskId, entry);
+    this.pruneTaskCapacity();
     this.persistCurrentState();
     return Result.ok(toTaskRuntimeSnapshot(entry));
   }
@@ -1259,6 +1274,12 @@ class InMemoryTaskRuntimeStore implements TaskRuntimeStore {
       this.tasks.set(validatedRecord.value.id, hydrated);
     }
 
+    const sizeBeforeCapacityPrune = this.tasks.size;
+    this.pruneTaskCapacity();
+    if (this.tasks.size !== sizeBeforeCapacityPrune) {
+      changed = true;
+    }
+
     if (changed) {
       this.persistCurrentState();
     }
@@ -1276,7 +1297,7 @@ class InMemoryTaskRuntimeStore implements TaskRuntimeStore {
       if (ageMs < this.retentionMs) continue;
 
       this.tasks.delete(taskId);
-      this.expiredTasks.set(
+      this.rememberExpiredTask(
         taskId,
         `Task id '${taskId}' expired by retention policy after ${this.retentionMs}ms`,
       );
@@ -1288,6 +1309,39 @@ class InMemoryTaskRuntimeStore implements TaskRuntimeStore {
     }
   }
 
+  private rememberExpiredTask(taskId: string, reason: string): void {
+    this.expiredTasks.delete(taskId);
+    this.expiredTasks.set(taskId, reason);
+
+    while (this.expiredTasks.size > this.maxExpiredTasks) {
+      const oldest = this.expiredTasks.keys().next();
+      if (oldest.done) return;
+      this.expiredTasks.delete(oldest.value);
+    }
+  }
+
+  private pruneTaskCapacity(): void {
+    if (this.tasks.size <= this.maxTasks) return;
+
+    const evictable = [...this.tasks.entries()]
+      .filter(([, entry]) => isTerminalState(entry.record.state))
+      .sort((left, right) => {
+        const leftEnded = left[1].record.endedAtEpochMs ?? left[1].record.updatedAtEpochMs;
+        const rightEnded = right[1].record.endedAtEpochMs ?? right[1].record.updatedAtEpochMs;
+        return leftEnded - rightEnded;
+      });
+
+    for (const [taskId] of evictable) {
+      if (this.tasks.size <= this.maxTasks) return;
+
+      this.tasks.delete(taskId);
+      this.rememberExpiredTask(
+        taskId,
+        `Task id '${taskId}' evicted by capacity policy after reaching max ${this.maxTasks} tasks`,
+      );
+    }
+  }
+
   private persistCurrentState(): void {
     if (!this.persistence) return;
 

package/src/tools/task.test.ts

@@ -1083,6 +1083,61 @@ defineTest("runTaskToolMvp wait exposes aborted outcome contract", async () => {
   await Promise.resolve();
 });
 
+defineTest("runTaskToolMvp throttles duplicate wait progress updates", async () => {
+  const previousThrottle = process.env.OHM_SUBAGENTS_ONUPDATE_THROTTLE_MS;
+  process.env.OHM_SUBAGENTS_ONUPDATE_THROTTLE_MS = "1000";
+
+  try {
+    const backend = new DeferredBackend();
+    const deps = makeDeps({ backend });
+
+    const started = await runTask({
+      params: {
+        op: "start",
+        async: true,
+        subagent_type: "finder",
+        description: "Throttle wait progress",
+        prompt: "keep running",
+      },
+      cwd: "/tmp/project",
+      signal: undefined,
+      onUpdate: undefined,
+      deps,
+    });
+
+    assert.equal(started.details.status, "running");
+
+    const updates: string[] = [];
+    const waited = await runTask({
+      params: {
+        op: "wait",
+        ids: ["task_test_0001"],
+        timeout_ms: 260,
+      },
+      cwd: "/tmp/project",
+      signal: undefined,
+      onUpdate: (partial) => {
+        updates.push(JSON.stringify(partial.details));
+      },
+      deps,
+    });
+
+    assert.equal(waited.details.error_code, "task_wait_timeout");
+    assert.equal(updates.length, 2);
+    assert.notEqual(updates[0], updates[1]);
+
+    backend.resolveSuccess(0, "Finder: Throttle wait progress", "done output");
+    await Promise.resolve();
+    await Promise.resolve();
+  } finally {
+    if (previousThrottle === undefined) {
+      delete process.env.OHM_SUBAGENTS_ONUPDATE_THROTTLE_MS;
+    } else {
+      process.env.OHM_SUBAGENTS_ONUPDATE_THROTTLE_MS = previousThrottle;
+    }
+  }
+});
+
 defineTest("runTaskToolMvp status/wait include terminal outputs for async tasks", async () => {
   const backend = new DeferredBackend();
   const deps = makeDeps({ backend });

package/src/tools/task.ts

@@ -175,6 +175,28 @@ function resolveCollapsedResultPreviewVisualLines(): number {
   return 12;
 }
 
+function resolveTaskRetentionMs(): number | undefined {
+  return parsePositiveIntegerEnv("OHM_SUBAGENTS_TASK_RETENTION_MS");
+}
+
+function resolveTaskMaxEventsPerTask(): number | undefined {
+  return parsePositiveIntegerEnv("OHM_SUBAGENTS_TASK_MAX_EVENTS");
+}
+
+function resolveTaskMaxEntries(): number | undefined {
+  return parsePositiveIntegerEnv("OHM_SUBAGENTS_TASK_MAX_ENTRIES");
+}
+
+function resolveTaskMaxExpiredEntries(): number | undefined {
+  return parsePositiveIntegerEnv("OHM_SUBAGENTS_TASK_MAX_EXPIRED_ENTRIES");
+}
+
+function resolveOnUpdateThrottleMs(): number {
+  const fromEnv = parsePositiveIntegerEnv("OHM_SUBAGENTS_ONUPDATE_THROTTLE_MS");
+  if (fromEnv !== undefined) return fromEnv;
+  return 120;
+}
+
 function resolveDefaultTaskPersistencePath(): string {
   const baseDir =
     process.env.PI_CONFIG_DIR ??
@@ -187,7 +209,10 @@ function resolveDefaultTaskPersistencePath(): string {
 
 const DEFAULT_TASK_STORE = createInMemoryTaskRuntimeStore({
   persistence: createJsonTaskRuntimePersistence(resolveDefaultTaskPersistencePath()),
-  retentionMs: parsePositiveIntegerEnv("OHM_SUBAGENTS_TASK_RETENTION_MS"),
+  retentionMs: resolveTaskRetentionMs(),
+  maxEventsPerTask: resolveTaskMaxEventsPerTask(),
+  maxTasks: resolveTaskMaxEntries(),
+  maxExpiredTasks: resolveTaskMaxExpiredEntries(),
 });
 
 let taskSequence = 0;
@@ -1541,8 +1566,58 @@ interface RunTaskToolInput {
 type TaskToolUiHandle = NonNullable<RunTaskToolInput["ui"]>;
 const liveUiBySurface = new WeakMap<TaskToolUiHandle, TaskLiveUiCoordinator>();
 const liveUiHeartbeatBySurface = new WeakMap<TaskToolUiHandle, ReturnType<typeof setInterval>>();
+const onUpdateLastEmissionByCallback = new WeakMap<
+  AgentToolUpdateCallback<TaskToolResultDetails>,
+  {
+    readonly atEpochMs: number;
+    readonly signature: string;
+  }
+>();
 const LIVE_UI_HEARTBEAT_MS = 120;
 
+function isThrottleBypassUpdate(details: TaskToolResultDetails): boolean {
+  if (
+    details.status === "succeeded" ||
+    details.status === "failed" ||
+    details.status === "cancelled"
+  ) {
+    return true;
+  }
+
+  if (details.op === "wait") {
+    if (details.done === true) return true;
+    if (details.wait_status === "timeout" || details.wait_status === "aborted") return true;
+  }
+
+  return false;
+}
+
+function shouldEmitOnUpdate(
+  callback: AgentToolUpdateCallback<TaskToolResultDetails>,
+  details: TaskToolResultDetails,
+): boolean {
+  const nextSignature = JSON.stringify(details);
+  const nowEpochMs = Date.now();
+  const previous = onUpdateLastEmissionByCallback.get(callback);
+
+  if (previous && previous.signature === nextSignature) {
+    return false;
+  }
+
+  const bypassThrottle = isThrottleBypassUpdate(details);
+  const throttleMs = resolveOnUpdateThrottleMs();
+
+  if (!bypassThrottle && previous && nowEpochMs - previous.atEpochMs < throttleMs) {
+    return false;
+  }
+
+  onUpdateLastEmissionByCallback.set(callback, {
+    atEpochMs: nowEpochMs,
+    signature: nextSignature,
+  });
+  return true;
+}
+
 function getTaskLiveUiCoordinator(ui: TaskToolUiHandle): TaskLiveUiCoordinator {
   const existing = liveUiBySurface.get(ui);
   if (existing) return existing;
@@ -1614,6 +1689,10 @@ function emitTaskRuntimeUpdate(input: {
     return;
   }
 
+  if (!shouldEmitOnUpdate(input.onUpdate, input.details)) {
+    return;
+  }
+
   {
     const runtimeText =
       presentation.widgetLines.length > 0