@bermudi/pi-delegate 0.1.19 → 0.1.20

package/schema.ts

@@ -113,9 +113,9 @@ export const delegateTaskSchema = Type.Object({
 export const delegateArgumentsSchema = Type.Object(
   {
     ticketAction: Type.Optional(
-      StringEnum(["poll", "cancel", "wait"], {
+      StringEnum(["poll", "cancel", "wait", "pause", "resume"], {
         description:
-          "Ticket control: poll=snapshot; wait=block until settled; cancel=abort. Prefer wait; never cancel for time.",
+          "poll=snapshot; wait=await results; pause=stop between turns; resume=continue; cancel=abort. Prefer wait over polling.",
       }),
     ),
     sessionAction: Type.Optional(
@@ -213,7 +213,7 @@ export function validateDelegateOperation(
   const rawParams = params as Record<string, unknown>;
   if ("action" in rawParams) {
     return (
-      "unsupported field 'action'; use 'ticketAction' for poll/cancel/wait " +
+      "unsupported field 'action'; use 'ticketAction' for poll/cancel/wait/pause/resume " +
       "or 'sessionAction' for close/list."
     );
   }
@@ -327,7 +327,7 @@ function validateDispatchOrHelpMode(
   const tasks = params.tasks ?? [];
 
   if (params.ticket !== undefined) {
-    return "ticket requires ticketAction 'poll', 'cancel', or 'wait'.";
+    return "ticket requires ticketAction 'poll', 'cancel', 'wait', 'pause', or 'resume'.";
   }
   if (params.force === true)
     return "force is valid only with ticketAction 'cancel'.";
@@ -415,12 +415,14 @@ function normalizeToolsField(value: string): unknown {
 
 /** True when `record` carries a top-level ticket-control intent that makes a
  * flat task-field wrap illegitimate: an explicit `ticketAction`, or a bare
- * `ticket` id (which only makes sense with poll/cancel/wait). */
+ * `ticket` id (which only makes sense with ticket controls). */
 function hasTicketControlIntent(record: Record<string, unknown>): boolean {
   return (
     record.ticketAction === "poll" ||
     record.ticketAction === "cancel" ||
     record.ticketAction === "wait" ||
+    record.ticketAction === "pause" ||
+    record.ticketAction === "resume" ||
     record.ticket !== undefined
   );
 }

package/status.ts

@@ -62,8 +62,22 @@ function plural(n: number, noun: string): string {
 export function buildStatusText(
   summary: ActiveTicketSummary,
 ): string | undefined {
+  const text = buildStatusSummary(summary);
+  return text === undefined ? undefined : `${text} · /subagents`;
+}
+
+function buildStatusSummary(summary: ActiveTicketSummary): string | undefined {
   const { tickets, activeSubagents } = summary;
   if (tickets.length === 0) return undefined;
+  const held = tickets.filter(
+    (ticket) =>
+      ticket.status === "running" &&
+      ticket.pause &&
+      ticket.pause.state !== "running",
+  );
+  if (held.length) {
+    return `Ⅱ ${held.map((ticket) => `${ticket.id} ${ticket.pause!.state}`).join(" · ")}${tickets.length > held.length ? ` · ${tickets.length - held.length} other ticket(s)` : ""}`;
+  }
   // Wind-down window: tasks have settled but the ticket has not flipped to a
   // terminal status yet. "settling" is more honest than "0 subagents".
   if (activeSubagents === 0) {

package/ticket-format.ts

@@ -50,12 +50,18 @@ export function formatTicketAgentRoster(progress: TaskProgress[]): string {
 
 /**
  * Copy-pasteable poll/cancel controls for a live ticket. Cancelling tickets
- * keep poll (to watch unwind) but drop cancel (already requested).
+ * keep poll (to watch unwind) but drop cancel (already requested). Pause/
+ * resume needs the ticket's pause controller: without one, handlePause
+ * rejects the call, so no snippet is advertised.
  */
 export function formatTicketControlSnippets(ticket: AsyncTicket): string {
   if (ticket.status !== "running" && ticket.status !== "cancelling") return "";
   let snippets = `\n     poll:   delegate({ ticketAction: "poll", ticket: "${ticket.id}" })`;
   if (ticket.status === "running") {
+    if (ticket.pause) {
+      const action = ticket.pause.state !== "running" ? "resume" : "pause";
+      snippets += `\n     ${action}: delegate({ ticketAction: "${action}", ticket: "${ticket.id}" })`;
+    }
     snippets += `\n     cancel: delegate({ ticketAction: "cancel", ticket: "${ticket.id}", force: true })`;
   }
   return snippets;
@@ -71,7 +77,11 @@ export function formatTicketRosterLine(
     (p) => p.status === "done" || p.status === "failed",
   ).length;
   const age = fmtDuration(now - ticket.created);
-  return `${icon} ${ticket.id}${formatTicketAgentRoster(ticket.progress)} · ${finalized}/${ticket.progress.length} finalized · ${ticket.status} · ${age}${formatTicketControlSnippets(ticket)}`;
+  const state =
+    ticket.status === "running"
+      ? (ticket.pause?.state ?? ticket.status)
+      : ticket.status;
+  return `${icon} ${ticket.id}${formatTicketAgentRoster(ticket.progress)} · ${finalized}/${ticket.progress.length} finalized · ${state} · ${age}${formatTicketControlSnippets(ticket)}`;
 }
 
 /** Full roster listing when poll is called without a ticket id. */
@@ -88,6 +98,8 @@ export function missingTicketPollText(ticketId: string): string {
 
 /** Running-task line shared by poll snapshots and cancel previews. */
 export function formatInFlightTaskLine(p: TaskProgress): string {
+  if (p.paused)
+    return `Ⅱ ${p.agent}${resumeMarker(p)}${formatTaskId(p.id)} · paused between turns`;
   const parts: string[] = [formatActivityLabel(p)];
   if (p.toolUses > 0)
     parts.push(`${p.toolUses} tool${p.toolUses === 1 ? "" : "s"}`);
@@ -183,7 +195,10 @@ export function formatLiveTicketHeader(
   ).length;
   const totalCount = ticket.progress.length;
   const runningCount = ticket.progress.filter(
-    (p) => p.status === "running",
+    (p) => p.status === "running" && !p.paused,
+  ).length;
+  const pausedCount = ticket.progress.filter(
+    (p) => p.status === "running" && p.paused,
   ).length;
   const pendingCount = ticket.progress.filter(
     (p) => p.status === "pending",
@@ -191,12 +206,15 @@ export function formatLiveTicketHeader(
   const totalTools = ticket.progress.reduce((sum, p) => sum + p.toolUses, 0);
   const totalTokens = ticket.progress.reduce((sum, p) => sum + p.tokens, 0);
   const headerStatus =
-    ticket.status === "cancelling" ? "CANCELLING" : "RUNNING";
+    ticket.status === "cancelling"
+      ? "CANCELLING"
+      : (ticket.pause?.state ?? "running").toUpperCase();
   const headerParts: string[] = [
     `Ticket ${ticket.id}: ${headerStatus}`,
     `${settledCount}/${totalCount} finalized`,
   ];
   if (runningCount > 0) headerParts.push(`${runningCount} active`);
+  if (pausedCount > 0) headerParts.push(`${pausedCount} paused`);
   if (pendingCount > 0) headerParts.push(`${pendingCount} queued`);
   if (failedCount > 0) headerParts.push(`${failedCount} failed`);
   headerParts.push(`${totalTools} tool${totalTools === 1 ? "" : "s"}`);
@@ -209,6 +227,9 @@ export function liveTicketGuidance(ticket: AsyncTicket): string {
   if (ticket.status === "cancelling") {
     return "Cancellation requested. Active subagents are aborting and returning partial results. Wait without timeoutMs for final status; do not repeatedly poll.";
   }
+  if (ticket.pause && ticket.pause.state !== "running") {
+    return `Pause requested: current turns may finish, then further turns and queued tasks stay blocked. Resume with delegate({ ticketAction: "resume", ticket: "${ticket.id}" }). Wait does not resume a paused ticket.`;
+  }
   const settledCount = ticket.progress.filter(
     (p) => p.status === "done" || p.status === "failed",
   ).length;

package/tickets.ts

@@ -100,6 +100,7 @@ function buildWaitDetails(ticket: AsyncTicket): DelegateDetails {
     parentModel: ticket.parentModelId,
     ticketId: ticket.id,
     status: ticket.status,
+    pauseState: ticket.status === "running" ? ticket.pause?.state : undefined,
     elapsedMs: (ticket.completedAt ?? Date.now()) - ticket.created,
     overlapWarning: overlapWarning || undefined,
     dispatchWarning: ticket.dispatchWarning,
@@ -112,6 +113,7 @@ function appendDispatchWarnings(
   details: DelegateDetails,
 ): string {
   const warnings = [
+    details.serializedNotice,
     details.dispatchWarning ? `WARNING: ${details.dispatchWarning}` : undefined,
     details.overlapWarning,
   ].filter((warning): warning is string => warning !== undefined);
@@ -124,15 +126,21 @@ function buildWaitRunningUpdate(
   const total = ticket.progress.length;
   const done = ticket.progress.filter((p) => p.status === "done").length;
   const failed = ticket.progress.filter((p) => p.status === "failed").length;
-  const running = ticket.progress.filter((p) => p.status === "running").length;
+  const running = ticket.progress.filter(
+    (p) => p.status === "running" && !p.paused,
+  ).length;
+  const paused = ticket.progress.filter(
+    (p) => p.status === "running" && p.paused,
+  ).length;
   const pending = ticket.progress.filter((p) => p.status === "pending").length;
   const finalized = done + failed;
 
   const parts: string[] = [
-    `Waiting for ticket ${ticket.id}: ${ticket.status.toUpperCase()}`,
+    `Waiting for ticket ${ticket.id}: ${(ticket.status === "running" ? (ticket.pause?.state ?? ticket.status) : ticket.status).toUpperCase()}`,
   ];
   parts.push(`${finalized}/${total} finalized`);
   if (running > 0) parts.push(`${running} active`);
+  if (paused > 0) parts.push(`${paused} paused`);
   if (failed > 0) parts.push(`${failed} failed`);
   if (pending > 0) parts.push(`${pending} queued`);
 
@@ -603,6 +611,8 @@ export class TicketRegistry extends Map<string, AsyncTicket> {
           // (friction #2). The LLM-facing content still names the ticket id too.
           ticketId: ticket.id,
           status: ticket.status,
+          pauseState:
+            ticket.status === "running" ? ticket.pause?.state : undefined,
           elapsedMs: Date.now() - ticket.created,
           overlapWarning: snapshot.overlapWarning || undefined,
           dispatchWarning: ticket.dispatchWarning,
@@ -614,6 +624,41 @@ export class TicketRegistry extends Map<string, AsyncTicket> {
     return this.formatCompletedTicket(ticket);
   }
 
+  /** Preview or request cancellation of a running async ticket. */
+  handlePause(params: {
+    ticket?: string;
+    ticketAction: "pause" | "resume";
+  }): AgentToolResult<DelegateDetails> {
+    const ticket = params.ticket ? this.get(params.ticket) : undefined;
+    if (!ticket || ticket.status !== "running" || !ticket.pause) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: !ticket
+              ? `Ticket '${params.ticket ?? ""}' not found.`
+              : `Cannot ${params.ticketAction} ticket '${ticket.id}': ${ticket.status === "running" ? "pause control unavailable" : `already ${ticket.status}`}.`,
+          },
+        ],
+        details: { tasks: [], results: [], progress: [] },
+      };
+    }
+    ticket.pause[params.ticketAction]();
+    console.info(
+      `[delegate] ticket '${ticket.id}' ${params.ticketAction} requested: ${ticket.pause.state}`,
+    );
+    const details = buildWaitDetails(ticket);
+    const text = `Ticket ${ticket.id}: ${ticket.pause.state.toUpperCase()}. ${
+      params.ticketAction === "pause"
+        ? "Current turns may finish; no subsequent turn or queued task starts while paused. Resume this ticket to continue. Existing background processes are not frozen; wall-clock deadlines still apply."
+        : "Continuing the same live sessions."
+    }`;
+    return {
+      content: [{ type: "text", text: appendDispatchWarnings(text, details) }],
+      details,
+    };
+  }
+
   /** Preview or request cancellation of a running async ticket. */
   handleCancel(params: {
     ticket?: string;
@@ -881,6 +926,13 @@ export function handleCancel(params: {
   return ticketRegistry.handleCancel(params);
 }
 
+export function handlePause(params: {
+  ticket?: string;
+  ticketAction: "pause" | "resume";
+}): AgentToolResult<DelegateDetails> {
+  return ticketRegistry.handlePause(params);
+}
+
 export function handleWait(
   params: { ticket?: string; timeoutMs?: number },
   signal: AbortSignal | undefined,

package/types.ts

@@ -84,6 +84,8 @@ export interface TicketWaiter {
 }
 
 export interface AsyncTicket {
+  /** Orthogonal to lifecycle status: paused tickets remain live reservations. */
+  pause?: import("./pause.ts").PauseController;
   id: string;
   created: number;
   completedAt?: number;
@@ -253,6 +255,12 @@ export type TaskFailureKind =
   "cancelled" | "stalled" | "model_error" | "deadline_exceeded";
 
 export interface TaskProgress {
+  /** Bounded assistant-text tail for the live browser; no private thinking. */
+  assistantPreview?: string;
+  activity?: string;
+  /** Index of the same-call writer this task must follow. */
+  waitingFor?: number;
+  paused?: boolean;
   id?: string;
   index: number;
   agent: string;
@@ -278,6 +286,7 @@ export interface TaskProgress {
 }
 
 export interface DelegateDetails {
+  pauseState?: import("./pause.ts").PauseState;
   tasks: TaskDef[];
   results: (TaskResult | { error: string })[];
   progress: TaskProgress[];
@@ -300,6 +309,8 @@ export interface DelegateDetails {
 }
 
 export interface TaskResult {
+  /** Batch-local ordered-writer group; never suppress incomplete evidence. */
+  serializedGroup?: number;
   id?: string;
   agent: string;
   /** Short tag (via `formatResumeTag`) of the transcript this task continued
@@ -426,6 +437,8 @@ export interface AgentRunConfig {
 }
 
 export interface AgentProgressUpdate {
+  assistantPreview?: string;
+  activity?: string;
   tokens: number;
   toolUses: number;
   durationMs: number;
@@ -436,6 +449,7 @@ export interface AgentProgressUpdate {
 }
 
 export interface TaskRunEnv {
+  pause?: import("./pause.ts").PauseController;
   /** Abort signal — parent's for sync, ticket's for async. May be undefined when no parent signal is available. */
   signal: AbortSignal | undefined;
   modelRegistry: ModelRegistry;