@bermudi/pi-delegate 0.1.18 → 0.1.20

package/lifecycle.ts

@@ -14,8 +14,7 @@ import type {
   TaskRunEnv,
   ToolActivity,
 } from "./types.ts";
-import * as pool from "./pool.ts";
-import { isSessionBusy } from "./tickets.ts";
+import { getDefaultDelegateRuntime, type DelegateRuntime } from "./runtime.ts";
 import {
   createSubagentSessionManager,
   persistSessionHeader,
@@ -50,10 +49,6 @@ let runAgentSessionForTesting: RunAgentSession = runAgentSession;
 type CreateScratchWorkspace = typeof createScratchWorkspace;
 let createScratchWorkspaceForTesting: CreateScratchWorkspace =
   createScratchWorkspace;
-type DetachQuarantinedPooledSession =
-  typeof pool._quarantinePooledAgentWithoutDisposal;
-let detachQuarantinedPooledSessionForTesting: DetachQuarantinedPooledSession =
-  pool._quarantinePooledAgentWithoutDisposal;
 
 export function _setRunAgentSessionForTesting(
   override: RunAgentSession | undefined,
@@ -70,10 +65,11 @@ export function _setCreateScratchWorkspaceForTesting(
 
 /** @internal Simulate a pooled-detachment invariant failure in lifecycle tests. */
 export function _setQuarantinePooledSessionDetachForTesting(
-  override: DetachQuarantinedPooledSession | undefined,
+  override:
+    ((sessionId: string, expectedSession: AgentSession) => boolean) | undefined,
+  runtime: DelegateRuntime = getDefaultDelegateRuntime(),
 ): void {
-  detachQuarantinedPooledSessionForTesting =
-    override ?? pool._quarantinePooledAgentWithoutDisposal;
+  runtime.pool._setQuarantinePooledAgentWithoutDisposalForTesting(override);
 }
 
 /**
@@ -242,14 +238,16 @@ function disposeSession(session: AgentSession, description: string): void {
 /** Detach an abandoned session from every owner immediately, then dispose it
  * only after runner's background termination monitor proves quiescence. */
 function quarantineAcquiredSession(
+  env: TaskRunEnv,
   task: ResolvedTask,
   acquired: AcquiredSession,
   quarantine: SessionQuarantine,
 ): void {
   let mayDisposeAfterSafety = acquired.lifecycleOwnsSession;
   if (!acquired.lifecycleOwnsSession) {
+    const runtime = env.runtime!;
     const detached = task.sessionId
-      ? detachQuarantinedPooledSessionForTesting(
+      ? runtime.pool.quarantinePooledAgentWithoutDisposal(
           task.sessionId,
           acquired.session,
         )
@@ -363,6 +361,8 @@ export function updateProgressFromRun(
     u.durationMs,
   );
   p.lastActivityAt = u.lastActivityAt;
+  p.assistantPreview = u.assistantPreview;
+  p.activity = u.activity;
   p.activities = mergeToolActivities(p.activities, u.activities);
   p.failureKind = u.failureKind;
 }
@@ -617,11 +617,12 @@ type AcquireResult = AcquiredSession | { error: TaskResult };
  * checkout is pure (no lastUsed bump); lastUsed is bumped by commit().
  */
 function checkoutPooledSession(
+  env: TaskRunEnv,
   task: ResolvedTask,
   p: TaskProgress,
 ): AcquireResult | undefined {
   if (!task.sessionId) return undefined;
-  const co = pool.checkout(task.sessionId, {
+  const co = env.runtime!.pool.checkout(task.sessionId, {
     cwd: task.cwd,
     thinking: task.thinking,
     tools: task.tools,
@@ -762,7 +763,7 @@ async function acquireAgentSession(
   p: TaskProgress,
 ): Promise<AcquireResult> {
   if (task.sessionId) {
-    const pooled = checkoutPooledSession(task, p);
+    const pooled = checkoutPooledSession(env, task, p);
     if (pooled) return pooled;
   }
   if (task.resumeFrom) return resumeFromSessionFile(env, task, task.resumeFrom);
@@ -813,6 +814,10 @@ export async function runResolvedTask(
   p: TaskProgress,
   taskIndex: number,
 ): Promise<TaskResult> {
+  // Ensure every lifecycle call operates on an explicit runtime. Older callers
+  // (and some test fixtures) do not inject one, so the default runtime is the
+  // backward-compatible fallback.
+  env.runtime ??= getDefaultDelegateRuntime();
   return withResumeTranscriptLock(task.resumeFrom, async (transcript) => {
     let executionTask = task;
     if (task.resumeFrom) {
@@ -879,8 +884,9 @@ export async function runResolvedTask(
       return runResolvedTaskUnlocked(env, executionTask, p, taskIndex);
     };
 
+    const runtime = env.runtime!;
     return executionTask.sessionId
-      ? pool.withSessionLock(executionTask.sessionId, runLocked)
+      ? runtime.pool.withSessionLock(executionTask.sessionId, runLocked)
       : runLocked();
   });
 }
@@ -1198,7 +1204,10 @@ async function applySessionAction(
     // The per-session lock for action-based operations is already held by the
     // outer runResolvedTask() wrapper. Use the internal close helper to avoid a
     // reentrant deadlock on the same key.
-    const closed = await pool._closePooledAgentWithoutLock(task.sessionId);
+    const runtime = env.runtime!;
+    const closed = await runtime.pool.closePooledAgentWithoutLock(
+      task.sessionId,
+    );
     return finishTask(
       env,
       p,
@@ -1213,12 +1222,13 @@ async function applySessionAction(
   }
 
   if (task.sessionAction === "list") {
+    const runtime = env.runtime!;
     return finishTask(
       env,
       p,
       completeSessionAction(
         task,
-        `Active sessions:\n${pool.listPooledAgents().join("\n")}`,
+        `Active sessions:\n${runtime.pool.listPooledAgents().join("\n")}`,
         Date.now() - env.delegateStartedAt,
       ),
     );
@@ -1231,7 +1241,7 @@ function busySessionConflict(
   task: ResolvedTask,
 ): TaskResult | undefined {
   if (!task.sessionId) return undefined;
-  const busyTicketId = isSessionBusy(task.sessionId);
+  const busyTicketId = env.runtime!.tickets.isSessionBusy(task.sessionId);
   if (busyTicketId && busyTicketId !== env.ticketId) {
     return failTask(
       task,
@@ -1303,6 +1313,7 @@ function noteAttemptProgress(
 
 /** Commit, record, or evict a pooled session after one prompt attempt. */
 async function settlePooledAttempt(
+  env: TaskRunEnv,
   task: ResolvedTask,
   acquired: AcquiredSession,
   r: {
@@ -1313,6 +1324,7 @@ async function settlePooledAttempt(
   },
   sessionReleased: boolean,
 ): Promise<boolean> {
+  const runtime = env.runtime!;
   if (!task.sessionId) return sessionReleased;
   if (acquired.lifecycleOwnsSession) {
     // Pool misses (including resumeFrom) transfer ownership only on
@@ -1323,7 +1335,7 @@ async function settlePooledAttempt(
       r.failureKind !== "stalled" &&
       r.failureKind !== "deadline_exceeded"
     ) {
-      const committed = pool.commit(task.sessionId, {
+      const committed = runtime.pool.commit(task.sessionId, {
         session: acquired.session,
         sessionManager: acquired.sessionManager,
         sessionFile: acquired.sessionFile,
@@ -1353,7 +1365,7 @@ async function settlePooledAttempt(
   ) {
     try {
       return (
-        (await pool._closePooledAgentWithoutLock(task.sessionId)) ||
+        (await runtime.pool.closePooledAgentWithoutLock(task.sessionId)) ||
         sessionReleased
       );
     } catch (error) {
@@ -1371,7 +1383,7 @@ async function settlePooledAttempt(
   if (r.failureKind !== "deadline_exceeded") {
     // Pool hits stay owned by the pool, and non-stalled, non-aborted
     // completions (including failed attempts) must still count usage.
-    pool.recordUse(task.sessionId, r.tokens);
+    runtime.pool.recordUse(task.sessionId, r.tokens);
   }
   // Pre-prompt deadline (prompted === false): the pooled session was
   // checked out but never used. Leave it in the pool with no usage
@@ -1536,6 +1548,7 @@ async function runTaskAttempt(
       timing.taskStartedAt,
       timing.deadlineAt,
       env.config,
+      env.pause ? { controller: env.pause, index: p.index } : undefined,
     );
 
     accounting.cumulativeTokens += r.tokens;
@@ -1558,12 +1571,13 @@ async function runTaskAttempt(
         );
 
     if (quarantine) {
-      quarantineAcquiredSession(task, acquired, quarantine);
+      quarantineAcquiredSession(env, task, acquired, quarantine);
       // Neither lifecycle nor pool owns it now. The deferred safety callback is
       // the sole owner and finally below must not dispose it early.
       sessionReleased = true;
     } else {
       sessionReleased = await settlePooledAttempt(
+        env,
         task,
         acquired,
         r,

package/manual.ts

@@ -110,11 +110,11 @@ export function getSubagentManualMarkdown(
     'delegate({ tasks: [{ agent: "default", prompt: "Investigate the auth module" }] })',
     "```",
     "",
-    'Delegate subagents to execute tasks in parallel. Each subagent gets an independent conversation. A batch with multiple write-capable tasks in one shared tree is rejected before dispatch; run them sequentially, use synchronous one-shot `workspace: "isolated"` for Git-backed ordered reconciliation, or use disposable scratch workspaces.',
+    "Delegate subagents to execute tasks in parallel. Each subagent gets an independent conversation. Start with a built-in agent and its defaults: set only `agent` and `prompt`. Overlapping shared writers in one call run in task order.",
     "",
     "The three handles have different lifetimes:",
     "",
-    "- **ticket** — controls one async batch with `poll`, `wait`, or `cancel`.",
+    "- **ticket** — controls one async batch with `poll`, `wait`, `pause`, `resume`, or `cancel`.",
     "- **sessionId** — a caller-chosen key for a live multi-turn worker, retained until close or parent shutdown.",
     "- **resumeFrom** — an absolute `.jsonl` transcript path used to recover an interrupted worker.",
     "",
@@ -138,9 +138,12 @@ export function getSubagentManualMarkdown(
     "",
     ...builtinLines,
     "",
-    "Prefer `default` for general work: it is the only built-in guaranteed to run the parent's exact model and thinking. `scout`/`coder`/`reviewer` apply any configured delegate.json tiers (`agentOverrides`, `agentOverridesByParentModel`) and may run a different model or thinking level than the parent. `scout` is read-only, and `reviewer` runs in a disposable scratch workspace — its writes are discarded by design. Choose a specialist for its role, not its name.",
+    "Start with a built-in and its configured defaults. Set only `agent` and `prompt`; omit `model`, `thinking`, `tools`, and `workspace` unless the user requests an override or a concrete task requirement makes the built-in default unsuitable.",
+    "A scout needs no scratch copy with its read-only defaults. Adding `bash` makes it write-capable regardless of its name; an explicit scratch copy can then be appropriate for disposable shell-based investigation.",
     "",
-    "Fresh built-ins inherit the parent's exact model object and thinking level. A same-named Markdown file can override any built-in (first definition wins); an explicit `model` or `thinking` in that file replaces parent inheritance. Task-level `model`/`thinking`/`tools` always win. For `scout`/`coder`/`reviewer`, delegate.json overrides (`agentOverrides`, `agentOverridesByParentModel`) win over the Markdown file; `default` ignores overrides and uses only an explicit Markdown `model`/`thinking` when present. A prompt-only Markdown override keeps the built-in's tools and workspace, so `scout` stays read-only and `reviewer` stays scratch unless the file explicitly changes them. Parent extension/MCP tools are not copied. Parent-global `AGENTS.md` instructions are also excluded. Project-local context and skills are rebuilt for the task's `cwd`; per-task fields remain explicit overrides.",
+    "Prefer `default` for general work: it is the only built-in guaranteed to run the parent's exact model and thinking. `scout`/`coder`/`reviewer` apply any configured delegate.json tiers (`agentOverrides`, `agentOverridesByParentModel`) and may run a different model or thinking level than the parent. `scout` is read-only; `coder` and `reviewer` use the shared workspace unless overridden. Choose a specialist for its role, not its name.",
+    "",
+    "Fresh built-ins inherit the parent's exact model object and thinking level. A same-named Markdown file can override any built-in (first definition wins); an explicit `model` or `thinking` in that file replaces parent inheritance. Task-level `model`/`thinking`/`tools` always win. For `scout`/`coder`/`reviewer`, delegate.json overrides (`agentOverrides`, `agentOverridesByParentModel`) win over the Markdown file; `default` ignores overrides and uses only an explicit Markdown `model`/`thinking` when present. A prompt-only Markdown override keeps the built-in's tools and workspace, so `scout` stays read-only and `reviewer` stays shared unless the file explicitly changes them. Parent extension/MCP tools are not copied. Parent-global `AGENTS.md` instructions are also excluded. Project-local context and skills are rebuilt for the task's `cwd`; per-task fields remain explicit overrides.",
     "",
     "## Available Custom Agents",
     "",
@@ -166,6 +169,12 @@ export function getSubagentManualMarkdown(
     "",
     schemaTable(delegateArgumentsSchema.properties),
     "",
+    "## Pause and Resume",
+    "",
+    'Use `delegate({ ticketAction: "pause", ticket: "<id>" })` to pause an async batch, and `ticketAction: "resume"` to continue its same live sessions. These controls return a snapshot immediately.',
+    "Pause finishes each current model response and its tool calls, then blocks before the next model request. Not-yet-started tasks stay queued. `pausing` means an operation is still finishing; `paused` means all remaining work has reached a checkpoint. A task that finishes naturally need not pause.",
+    "The inactivity watchdog is suspended at a paused turn boundary, but explicit wall-clock `deadlineMs` budgets continue. Wait does not resume. Cancel and shutdown still abort paused work. Live sessions, concurrency slots, workspace reservations, and scratch/isolated workspaces remain held; pause does not survive Pi exit or reload. Isolated preparation/application already in progress finishes before pausing; background processes are not frozen and files may be unfinished.",
+    "",
     "## Session Reuse",
     "",
     "When `sessionId` is set, the subagent is kept alive in a pool for the duration of the pi session.",
@@ -227,6 +236,8 @@ export function getSubagentManualMarkdown(
     "",
     '- `delegate({ ticketAction: "poll" })` \u2014 list all tickets',
     '- `delegate({ ticketAction: "poll", ticket: "abc123" })` \u2014 take one progress snapshot',
+    '- `delegate({ ticketAction: "pause", ticket: "abc123" })` \u2014 pause between turns, not after the entire task',
+    '- `delegate({ ticketAction: "resume", ticket: "abc123" })` \u2014 continue the same live sessions',
     '- `delegate({ ticketAction: "wait", ticket: "abc123" })` \u2014 block until finished; omit `timeoutMs` when the result is needed this turn',
     '- `delegate({ ticketAction: "wait", ticket: "abc123", timeoutMs: 600000 })` \u2014 bounded wait; timeout includes the latest snapshot, so do not poll afterward',
     '- `delegate({ ticketAction: "cancel", ticket: "abc123" })` \u2014 preview activity and partial effects before cancelling',
@@ -234,16 +245,18 @@ export function getSubagentManualMarkdown(
     "",
     `See the field tables above for the full semantics. Max ${getMaxAsyncTickets()} concurrent async tickets.`,
     "Async results arrive as follow-up messages, so Pi cannot fold their usage into the parent session total; displayed task usage remains informational.",
+    'Isolation supports sync or async one-shot `workspace: "isolated"` tasks. In async mode it prepares Git worktrees after returning the ticket, runs one-shot workers, then reconciles successful proposals in task order before settling. Cancellation never applies unfinished work; a completed proposal cancelled before source application is retained as a private ref and full patch.',
     "",
     "## Gotchas",
     "",
     "- Dispatch validation is batch-wide and runs before spawning: one invalid task rejects the call without starting its siblings.",
-    '- Shared writers that overlap tasks in the same call or a running sync/async dispatch are rejected. Unknown tools count as mutating. Run them sequentially, use `workspace: "isolated"` for Git-backed ordered reconciliation, or use `workspace: "scratch"` when changes may be discarded.',
+    "- Shared writers overlapping within one call are serialized in task order (reported in the result); overlap with a running sync/async dispatch is rejected, so wait for it to finish. Unknown tools count as mutating.",
     "- `*` 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: "..." }] }`.',
-    '- Prefer `agent: "default"` — the parent\'s live model/thinking/native tools/base prompt — for general tasks. Pick `scout`/`coder`/`reviewer` only when the role, tool limits, or scratch workspace fit; they follow delegate.json tiers and may not run the parent model. Omitting `agent` creates an ad-hoc task (parent model, full tools).',
-    "- 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 `*`.",
+    "- Use a built-in agent first: `default` for general work, `scout` for read-only investigation, `coder` for implementation, and `reviewer` for review. Omitting `agent` creates a custom inline task rather than selecting a default.",
+    "- Omit `model`, `thinking`, `tools`, and `workspace` for built-ins unless the user requests an override or the built-in default cannot satisfy a concrete requirement. These task fields replace configured policy.",
+    "- In particular, setting `thinking` overrides the agent's configured thinking budget. A casual effort value silently defeats that budget; leave it unset rather than estimating effort for every task.",
+    "- An inline 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.`,
     "- `deadlineMs` is a per-task wall-clock budget measured from when the task starts running (after queuing). It requests cooperative abort and is not a hard kill; completed writes/commands remain. Omission disables the deadline.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bermudi/pi-delegate",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Delegate tool for the Pi coding agent.",
   "keywords": [
     "pi-package"
@@ -28,6 +28,7 @@
     "@earendil-works/pi-coding-agent": "^0.84.2",
     "@earendil-works/pi-tui": "^0.84.2",
     "@marcfargas/pi-test-harness": "^0.6.1",
+    "@types/bun": "^1.4.0",
     "esbuild": "^0.28.2",
     "prettier": "^3.9.6",
     "typescript": "^5.9.3"

package/parent-context.ts

@@ -6,7 +6,7 @@ import {
 /** Render the active parent conversation as compact context for a subagent. */
 export function buildParentTranscript(
   entries: SessionEntry[],
-  leafId: string | null,
+  leafId: string | null | undefined,
 ): string | null {
   try {
     const ctx = buildSessionContext(entries, leafId);

package/pause.ts

@@ -0,0 +1,81 @@
+/** Cooperative, in-memory ticket pause. Active operations finish; participants
+ * park at a checkpoint before starting their next operation. This neither
+ * freezes child processes nor releases workspace reservations/concurrency. */
+export type PauseState = "running" | "pausing" | "paused";
+
+export class PauseController {
+  private requested = false;
+  private readonly active = new Set<number>();
+  private readonly parked = new Set<number>();
+  private readonly wake = new Set<() => void>();
+
+  constructor(private readonly onChange: () => void = () => {}) {}
+
+  get state(): PauseState {
+    if (!this.requested) return "running";
+    return [...this.active].every((index) => this.parked.has(index))
+      ? "paused"
+      : "pausing";
+  }
+
+  isParked(index: number): boolean {
+    return this.requested && this.parked.has(index);
+  }
+
+  private publish(): void {
+    try {
+      this.onChange();
+    } catch (error) {
+      console.error("[delegate] pause state notification failed", error);
+    }
+  }
+
+  pause(): void {
+    if (this.requested) return;
+    this.requested = true;
+    this.publish();
+  }
+
+  resume(): void {
+    if (!this.requested) return;
+    this.requested = false;
+    for (const wake of this.wake) wake();
+    this.publish();
+  }
+
+  enter(index: number): void {
+    this.active.add(index);
+    this.publish();
+  }
+
+  leave(index: number): void {
+    this.active.delete(index);
+    this.parked.delete(index);
+    this.publish();
+  }
+
+  /** Abort unblocks the checkpoint without clearing another task's pause.
+   * Callers still observe their signal and take their normal cancellation path. */
+  async checkpoint(index: number, signal?: AbortSignal): Promise<void> {
+    if (!this.requested || signal?.aborted) return;
+    this.parked.add(index);
+    this.publish();
+    try {
+      while (this.requested && !signal?.aborted) {
+        await new Promise<void>((resolve) => {
+          const wake = () => {
+            this.wake.delete(wake);
+            signal?.removeEventListener("abort", wake);
+            resolve();
+          };
+          this.wake.add(wake);
+          signal?.addEventListener("abort", wake, { once: true });
+          if (signal?.aborted) wake();
+        });
+      }
+    } finally {
+      this.parked.delete(index);
+      this.publish();
+    }
+  }
+}