@bermudi/pi-delegate 0.1.12 → 0.1.14

package/manual.ts

@@ -120,6 +120,8 @@ export function getSubagentManualMarkdown(
     "",
     "Each task entry may also carry an optional `id` — a caller-provided per-dispatch correlation key. Duplicate `id` values in the same call are rejected; when omitted, tasks are identified by array index, agent, and prompt.",
     "",
+    "Vocabulary, since 'agent' does double duty elsewhere: a **task** is one job; an **agent** is a named profile — a saved bundle of system prompt, tools, workspace, and model policy — that a task references by `agent` name; a **subagent** is the live session that executes one task. Agents are templates, not processes; nothing runs until a task dispatches.",
+    "",
     "Subagents cannot call `delegate` recursively. Their tool activity runs at `cwd`, while Pi stores the runtime session transcript in its own session directory outside that `cwd`.",
     "",
     "## Touched Files (best-effort)",
@@ -142,7 +144,7 @@ export function getSubagentManualMarkdown(
     "",
     agentList,
     "",
-    "Custom agents are defined either inline in a task (using `systemPrompt`, `tools`, and `thinking`) or persisted as Markdown files in `.pi/agents/*.md` (project-local), `~/.pi/agent/agents/` (global), and `.claude/agents/` (interchange with Claude Code). Markdown agents are examples of custom agents — the parent model can shape the subagent it needs on each call. Each Markdown file is an agent with YAML frontmatter:",
+    "Custom agents are profiles, defined either inline in a task (using `systemPrompt`, `tools`, and `thinking`) or persisted as Markdown files in `.pi/agents/*.md` (project-local), `~/.pi/agent/agents/` (global), and `.claude/agents/` (interchange with Claude Code). Inline definitions let the parent model shape the subagent it needs on each call. Each Markdown file is one profile with YAML frontmatter:",
     "",
     "```markdown",
     "---",
@@ -165,26 +167,26 @@ export function getSubagentManualMarkdown(
     "## Session Reuse",
     "",
     "When `sessionId` is set, the subagent is kept alive in a pool for the duration of the pi session.",
-    "Subsequent calls with the same `sessionId` continue the conversation — the agent remembers prior context.",
+    "Subsequent calls with the same `sessionId` continue the conversation — the session retains prior context.",
     "",
     "```ts",
     "// First call — creates and runs an inline custom agent",
     'delegate({ tasks: [{ prompt: "Investigate the auth module", systemPrompt: "You are a focused investigator. Map files and dependencies.", tools: ["read", "grep", "find", "ls"], sessionId: "auth-research" }] })',
     "",
-    "// Second call — continues the same agent",
+    "// Second call — continues the same subagent",
     'delegate({ tasks: [{ prompt: "Now check the tests for that module", sessionId: "auth-research" }] })',
     "",
     "// Clean up when done",
     'delegate({ tasks: [{ sessionId: "auth-research", sessionAction: "close" }] })',
     "```",
     "",
-    'Pooled agents remain live until `sessionAction: "close"` or parent Pi session shutdown.',
+    'Pooled sessions remain live until `sessionAction: "close"` or parent Pi session shutdown.',
     "",
     "## Resuming Previous Sessions",
     "",
     "Use `resumeFrom` to continue a failed or interrupted subagent from where it left off.",
     "Pass the exact absolute path to the session `.jsonl` file copied from delegate retry output. Do not invent placeholder values or use it as a ticket ID; async resume is supported.",
-    "The agent gets the full conversation history and the new `prompt` continues naturally.",
+    "The subagent gets the full conversation history and the new `prompt` continues naturally.",
     "",
     "```ts",
     "// Copy this exact path from the failed delegate result; do not invent it.",
@@ -193,7 +195,7 @@ export function getSubagentManualMarkdown(
     "  resumeFrom: exactRetrySessionFile }] })",
     "```",
     "",
-    "Combine with `sessionId` to resume AND pool the agent for further multi-turn use:",
+    "Combine with `sessionId` to resume AND pool the subagent for further multi-turn use:",
     "",
     "```ts",
     'delegate({ tasks: [{ prompt: "Continue the investigation",',
@@ -238,6 +240,7 @@ export function getSubagentManualMarkdown(
     "- `*` means read/write/edit/bash, not every tool. `grep`, `find`, and `ls` are valid explicit tools and are the `ro` preset.",
     '- `tasks` is an array. The tool recovers common stringified calls for compatibility, but canonical calls use `{ tasks: [{ prompt: "..." }] }`.',
     '- Use `agent: "default"` for the parent\'s live model/thinking/native tools/base prompt. Built-ins are `default`, `scout`, `coder`, and `reviewer`; omitting `agent` creates an ad-hoc task.',
+    "- Omit `thinking` for named agents unless the user asks or the task clearly needs escalation — task-level `thinking` overrides every configured tier (`agentOverrides`, `agentOverridesByParentModel`, Markdown frontmatter, `:level` model suffix), so a casual value silently defeats the configured budget. Ad-hoc tasks default to the parent's thinking.",
     "- An ad-hoc task with no `tools` uses `*`; a named custom task uses its profile; a profile with no tools uses `*`.",
     "- Subagents inherit all skills discovered in their `cwd` (via AgentSession's resource loader). Per-task skill filtering is not supported — curate the cwd's skill set instead.",
     `- Sync \`delegate\` runs at most ${getMaxConcurrent()} tasks at once (the rest queue, not fail). Use \`async: true\` to move work to the background.`,
@@ -248,6 +251,6 @@ export function getSubagentManualMarkdown(
     "Tunables live in `~/.pi/agent/delegate.json` (user scope, global — no project-level config): `maxConcurrent` (sync ceiling), `maxAsyncTickets` (background ticket cap), `stallTimeoutMs` (inactivity watchdog; default 900000, 0 disables), per-model/per-provider concurrency limits, legacy custom-agent model overrides (`agent`), and agent model/thinking/tools overrides — `agentOverrides` and `agentOverridesByParentModel` (exact `provider/model-id` key of the parent model; wins over `agentOverrides` on match). Config edits apply from the next delegate call.",
     "The inactivity watchdog requests cooperative `AgentSession.abort()` cancellation and waits for the subagent to become idle; it is not a hard wall-clock execution deadline.",
     "",
-    `Output bounding: subagent outputs longer than ${OUTPUT_SPILL_THRESHOLD_CHARS} characters are spilled to a temp file, and only the last ${OUTPUT_SPILL_TAIL_CHARS} characters stay in the LLM-facing result. Adjust with \`output.spillThresholdChars\` and \`output.spillTailChars\`. Spill files are written to the system temp directory with owner-only permissions; the full output is always available in the expanded TUI view and the spilled file.`,
+    `Output bounding: subagent outputs longer than ${OUTPUT_SPILL_THRESHOLD_CHARS} characters are spilled to a temp file, and only the last ${OUTPUT_SPILL_TAIL_CHARS} characters stay in the LLM-facing result. Adjust with \`output.spillThresholdChars\` and \`output.spillTailChars\`. Spill files are written to the system temp directory with owner-only permissions and follow OS temp lifecycle; full output remains in the expanded TUI view.`,
   ].join("\n");
 }

package/model.ts

@@ -76,5 +76,10 @@ export function findAvailableAlternative(
   // Prefer a different provider (avoid returning the same broken model).
   return registry
     .getAvailable()
-    .find((m) => m.id === model.id && m.provider !== model.provider);
+    .find(
+      (m) =>
+        m.id === model.id &&
+        m.provider !== model.provider &&
+        registry.hasConfiguredAuth(m),
+    );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bermudi/pi-delegate",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "Delegate tool for the Pi coding agent.",
   "keywords": [
     "pi-package"
@@ -23,14 +23,14 @@
     ]
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "^0.80.9",
-    "@earendil-works/pi-ai": "^0.80.9",
-    "@earendil-works/pi-coding-agent": "^0.80.9",
-    "@earendil-works/pi-tui": "^0.80.9",
+    "@earendil-works/pi-agent-core": "^0.84.2",
+    "@earendil-works/pi-ai": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@earendil-works/pi-tui": "^0.84.2",
     "@marcfargas/pi-test-harness": "^0.6.1",
-    "esbuild": "^0.27.0",
-    "prettier": "^3.8.4",
-    "typescript": "^5.9.0"
+    "esbuild": "^0.28.2",
+    "prettier": "^3.9.6",
+    "typescript": "^5.9.3"
   },
   "patchedDependencies": {
     "@marcfargas/pi-test-harness@0.6.1": "patches/@marcfargas%2Fpi-test-harness@0.6.1.patch"
@@ -40,9 +40,13 @@
     "test": "bun test",
     "typecheck": "tsc --noEmit",
     "build": "esbuild delegate.ts --bundle --platform=neutral --packages=external --format=esm --banner:js=\"// @ts-nocheck\" --outfile=.build/delegate.bundle.ts",
-    "format": "prettier --write \"**/*.ts\""
+    "format": "prettier --write \"**/*.ts\"",
+    "format:check": "prettier --check \"**/*.ts\""
   },
   "dependencies": {
     "@sinclair/typebox": "0.34.52"
+  },
+  "overrides": {
+    "brace-expansion": "5.0.9"
   }
 }

package/pool.ts

@@ -128,6 +128,21 @@ function waitForActiveSessionLocks(): Promise<void> {
   return Promise.all(locks).then(() => undefined);
 }
 
+function deepFreeze<T>(value: T, seen = new WeakSet<object>()): T {
+  if (typeof value !== "object" || value === null || seen.has(value)) {
+    return value;
+  }
+  seen.add(value);
+  const record = value as Record<PropertyKey, unknown>;
+  for (const key of Reflect.ownKeys(value)) deepFreeze(record[key], seen);
+  return Object.freeze(value);
+}
+
+/** Defensive value copy for the capability configuration crossing the pool seam. */
+function cloneFrozenConfig(config: FrozenConfig): FrozenConfig {
+  return deepFreeze(structuredClone(config));
+}
+
 // ── Read + validate ───────────────────────────────────────────────────────
 
 /** Look up a pooled session and validate a reuse request against its frozen
@@ -248,7 +263,7 @@ export function commit(sessionId: string, payload: CommitPayload): boolean {
     session: payload.session,
     sessionManager: payload.sessionManager,
     sessionFile: payload.sessionFile,
-    config: payload.frozen,
+    config: cloneFrozenConfig(payload.frozen),
     lastUsed: now(),
     createdAt: now(),
     totalTokens: payload.tokens,
@@ -271,17 +286,33 @@ export function recordUse(sessionId: string, tokens: number): boolean {
   return true;
 }
 
+/** Remove an exact live session from reuse without aborting or disposing it.
+ * Lifecycle uses this only after runner reports quiescence abandonment: any
+ * ordinary pool close would race provider/extension work that may still be
+ * running. The caller retains the detached session until its background safety
+ * promise resolves. */
+export function _quarantinePooledAgentWithoutDisposal(
+  sessionId: string,
+  expectedSession: AgentSession,
+): boolean {
+  const existing = agentPool.get(sessionId);
+  if (!existing || existing.session !== expectedSession) return false;
+  agentPool.delete(sessionId);
+  return true;
+}
+
 // ── Read-only defaults (for task-resolution) ──────────────────────────────
 
 /** Frozen config for a pooled session, or undefined if not pooled. Lock-free —
- *  safe because the frozen config is write-only at insert and never mutated
- *  thereafter (only stats mutate, via commit, and those do not touch the
- *  returned object). Used by resolveTasks to default {systemPrompt, model,
- *  thinking, tools} for a task that supplies only a sessionId. */
+ *  safe because the stored config is a deeply frozen defensive copy. Callers
+ *  receive another frozen copy so values crossing the pool seam cannot mutate
+ *  its capability contract. Used by resolveTasks to default {systemPrompt,
+ *  model, thinking, tools} for a task that supplies only a sessionId. */
 export function configFor(
   sessionId: string,
 ): Readonly<FrozenConfig> | undefined {
-  return agentPool.get(sessionId)?.config;
+  const config = agentPool.get(sessionId)?.config;
+  return config ? cloneFrozenConfig(config) : undefined;
 }
 
 // ── Lock primitive (D1) ───────────────────────────────────────────────────

package/quiescence.ts

@@ -47,9 +47,11 @@
  * Once cancellation has been requested the session is supposed to be tearing
  * down, so the wait is bounded by `cancelledUnwindBudgetMs`. Without a bound,
  * an extension that keeps launching continuations keeps resetting progress and
- * the barrier never returns — hanging the delegate task forever, which is
- * strictly worse than reporting a cancelled task whose session may still be
- * active. On expiry the barrier logs and returns `"abandoned"`.
+ * the barrier never returns — hanging the delegate task forever. On expiry the
+ * barrier logs and returns `"abandoned"`. Runner then transfers a private
+ * quarantine marker and an unbounded background termination promise to
+ * lifecycle; lifecycle must detach the session and defer disposal/workspace
+ * cleanup until that promise confirms quiescence.
  */
 
 /** Why the runner asked the session to stop. */
@@ -91,8 +93,8 @@ export const DEFAULT_QUIESCENCE_TIMINGS: QuiescenceTimings = {
 /**
  * `"quiescent"` — the session went idle and stayed quiet; ownership may be
  * returned to the caller. `"abandoned"` — the cancelled-unwind budget expired
- * while work was still starting; the caller regains ownership of a session
- * that may still be active.
+ * while work was still starting; the caller must quarantine the session because
+ * it may still be active.
  */
 export type QuiescenceOutcome = "quiescent" | "abandoned";
 
@@ -104,6 +106,9 @@ export type QuiescenceBarrierOptions = {
   cancel: (source: CancellationSource) => void;
   timings?: Partial<QuiescenceTimings>;
   now?: () => number;
+  /** Do not let liveness probes keep Node alive. Used only by the unbounded
+   * quarantine recovery monitor; foreground barriers retain ordinary timers. */
+  unrefTimers?: boolean;
   /** Overridable for tests; defaults to a `console.error` trace. */
   onAbandon?: (info: {
     source: CancellationSource;
@@ -161,7 +166,12 @@ export function createQuiescenceBarrier(
   };
 
   const sleep = (ms: number) =>
-    new Promise<void>((resolve) => setTimeout(resolve, ms));
+    new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, ms);
+      if (options.unrefTimers && typeof timer.unref === "function") {
+        timer.unref();
+      }
+    });
   const nextEventLoopTurn = () =>
     new Promise<void>((resolve) => setImmediate(resolve));
 
@@ -178,6 +188,9 @@ export function createQuiescenceBarrier(
         resolve();
       };
       const probe = setTimeout(finish, probeMs);
+      if (options.unrefTimers && typeof probe.unref === "function") {
+        probe.unref();
+      }
       if (generation !== sampled) {
         finish();
         return;