@bermudi/pi-delegate 0.1.1 → 0.1.3

package/tickets.ts

@@ -11,22 +11,31 @@ import {
   fmtDuration,
   fmtTokens,
   formatCompletedTask,
+  formatTaskId,
   shortenPath,
   trunc,
   getActivityAge,
   formatActivityLabel,
   taskMetaBase,
   relativeTouchedSummary,
+  findTouchedOverlaps,
+  formatTouchedOverlapWarning,
 } from "./format.ts";
+import { isCrossLeafTicket } from "./leaf.ts";
 import { renderOutputForPoll } from "./spill.ts";
 import { scheduleDeadline } from "./timer.ts";
+import { aggregateTaskResults, emptyUsage } from "./usage.ts";
+import { recordCall } from "./telemetry.ts";
 import type {
   AsyncTicket,
   DelegateDetails,
+  ResolvedTask,
   TaskResult,
   TicketWaiter,
 } from "./types.ts";
 
+const PENDING_RESULT_ERROR = "PENDING — result not available";
+
 const busyTicketIdsBySession = new Map<string, Set<string>>();
 const busySessionsByTicket = new Map<string, Set<string>>();
 
@@ -117,6 +126,30 @@ export function cancelTicketForShutdown(ticket: AsyncTicket): void {
   ticket.completedAt = Date.now();
   syncTicketBusyIndex(ticket);
   settleTicketWaiters(ticket);
+  if (ticket.callRecord) {
+    const { totalTokens, totalCost } = aggregateTaskResults(ticket.results);
+    recordCall(
+      {
+        ...ticket.callRecord,
+        status: "cancelled",
+        wall_ms: ticket.completedAt - (ticket.callStartedAt ?? ticket.created),
+        total_tokens: totalTokens,
+        total_cost: totalCost,
+      },
+      ticket.telemetryGeneration,
+    );
+  }
+}
+
+/** Request cooperative cancellation of a live ticket: abort the workers and
+ *  move to "cancelling" so they settle and report what actually ran. Unlike
+ *  `cancelTicketForShutdown` this leaves the ticket deliverable — the runtime
+ *  is still alive, so the final "cancelled" result still reaches the user. */
+export function requestTicketCancel(ticket: AsyncTicket): void {
+  if (ticket.status !== "running") return;
+  ticket.controller.abort();
+  ticket.status = "cancelling";
+  syncTicketBusyIndex(ticket);
 }
 
 /** Check if any running async ticket holds a given sessionId.
@@ -187,13 +220,23 @@ export function formatCompletedTicket(
     const r = ticket.results[i];
     const t = ticket.resolved[i]!;
     if (!r) {
-      parts.push(`=== ${t.agentName}: ${trunc(t.prompt || "", 80)} ===`);
+      parts.push(
+        `=== ${t.agentName}${formatTaskId(t.id)}: ${trunc(t.prompt || "", 80)} ===`,
+      );
       parts.push(`[${pendingLabelFor(i)}]`);
       continue;
     }
     parts.push(...formatCompletedTask(t, r));
   }
 
+  const completedResults = ticket.results.filter(
+    (r): r is TaskResult => r !== undefined && "touchedFiles" in r,
+  );
+  const overlapWarning = formatTouchedOverlapWarning(
+    findTouchedOverlaps(completedResults),
+  );
+  if (overlapWarning) parts.push("", overlapWarning);
+
   if (ticket.status === "cancelled") {
     parts.push(
       "",
@@ -206,7 +249,11 @@ export function formatCompletedTicket(
     details: {
       tasks: ticket.tasks,
       results: [...ticket.results].map(
-        (r, index) => r ?? { error: pendingLabelFor(index) },
+        (r, index) =>
+          r ?? {
+            ...pendingResultPlaceholder(ticket.resolved[index]),
+            error: pendingLabelFor(index),
+          },
       ),
       progress: [...ticket.progress],
       parentModel: ticket.parentModelId,
@@ -214,22 +261,49 @@ export function formatCompletedTicket(
       // the human sees which ticket they polled, even in the rich tree path.
       ticketId: ticket.id,
       status: ticket.status,
+      overlapWarning: overlapWarning || undefined,
     },
   };
 }
 
 // ── Waiter helpers ─────────────────────────────────────────────────────────
 
+function pendingResultPlaceholder(task: ResolvedTask | undefined): TaskResult {
+  return {
+    id: task?.id,
+    agent: task?.agentName ?? "unknown",
+    output: "",
+    durationMs: 0,
+    tokens: 0,
+    usage: emptyUsage(),
+    touchedFiles: [],
+    attributedFiles: [],
+    // Machine-visible and human-readable marker so structured consumers do not
+    // mistake a pending placeholder for a successful result.
+    error: PENDING_RESULT_ERROR,
+  };
+}
+
 function buildWaitDetails(ticket: AsyncTicket): DelegateDetails {
+  const completedResults = ticket.results.filter(
+    (r): r is TaskResult => r !== undefined && "touchedFiles" in r,
+  );
+  const overlapWarning = formatTouchedOverlapWarning(
+    findTouchedOverlaps(completedResults),
+  );
+  const results: TaskResult[] = [];
+  for (let i = 0; i < ticket.resolved.length; i++) {
+    const r = ticket.results[i];
+    results.push(r ?? pendingResultPlaceholder(ticket.resolved[i]));
+  }
   return {
     tasks: ticket.tasks,
-    results: ticket.results.map(
-      (r) => r ?? { error: "PENDING — result not available" },
-    ),
+    results,
     progress: [...ticket.progress],
     parentModel: ticket.parentModelId,
     ticketId: ticket.id,
     status: ticket.status,
+    overlapWarning: overlapWarning || undefined,
   };
 }
 
@@ -251,9 +325,13 @@ function buildWaitRunningUpdate(
   if (failed > 0) parts.push(`${failed} failed`);
   if (pending > 0) parts.push(`${pending} queued`);
 
+  const details = buildWaitDetails(ticket);
+  const text =
+    parts.join(" · ") +
+    (details.overlapWarning ? `\n\n${details.overlapWarning}` : "");
   return {
-    content: [{ type: "text", text: parts.join(" · ") }],
-    details: buildWaitDetails(ticket),
+    content: [{ type: "text", text }],
+    details,
   };
 }
 
@@ -261,28 +339,38 @@ function buildWaitTimeoutResult(
   ticket: AsyncTicket,
   timeoutMs: number,
 ): AgentToolResult<DelegateDetails> {
+  // A timeout must not be an information cliff. Reuse the same rich snapshot
+  // as poll so the caller can see activity and consume any completed outputs
+  // without making a second tool call.
+  const snapshot = handlePoll({ ticket: ticket.id }, {} as ExtensionContext);
+  const snapshotText = snapshot.content
+    .filter((item) => item.type === "text")
+    .map((item) => item.text)
+    .join("\n");
+  const base = `Ticket ${ticket.id} still ${ticket.status} after ${fmtDuration(timeoutMs)} · wait timed out (ticket continues in background)`;
+  const guidance =
+    "If you need the final result in this turn, call wait once with timeoutMs omitted; do not poll after a timeout. Otherwise stop calling ticket controls and let the final result auto-deliver.";
   return {
     content: [
       {
         type: "text",
-        text: `Ticket ${ticket.id} still ${ticket.status} after ${fmtDuration(timeoutMs)} · wait timed out (ticket continues in background)`,
+        text: `${base}\n\n${snapshotText}\n\n${guidance}`,
       },
     ],
-    details: buildWaitDetails(ticket),
+    details: snapshot.details,
   };
 }
 
 function buildWaitAbortResult(
   ticket: AsyncTicket,
 ): AgentToolResult<DelegateDetails> {
+  const details = buildWaitDetails(ticket);
+  const base = `Wait for ticket ${ticket.id} aborted · ticket continues ${ticket.status} in the background`;
+  const text =
+    base + (details.overlapWarning ? `\n\n${details.overlapWarning}` : "");
   return {
-    content: [
-      {
-        type: "text",
-        text: `Wait for ticket ${ticket.id} aborted · ticket continues ${ticket.status} in the background`,
-      },
-    ],
-    details: buildWaitDetails(ticket),
+    content: [{ type: "text", text }],
+    details,
   };
 }
 
@@ -366,23 +454,57 @@ export function notifyWaiters(ticket: AsyncTicket): void {
       continue;
     }
     active.push(w);
-    if (w.onUpdate) w.onUpdate(buildWaitRunningUpdate(ticket));
+    if (w.onUpdate) {
+      try {
+        w.onUpdate(buildWaitRunningUpdate(ticket));
+      } catch (error) {
+        // Progress delivery is an observer boundary. A host callback must not
+        // be able to fail the worker that reported the update or reject the
+        // wait promise; keep the waiter attached for the terminal result and
+        // leave the failure visible for diagnosis.
+        console.error(
+          `[delegate] wait progress callback for ticket '${ticket.id}' threw; continuing`,
+          error,
+        );
+      }
+    }
   }
   ticket.waiters = active.length ? active : undefined;
 }
 
+/** Prefix for a result whose spawn leaf is no longer the active one. The model
+ *  would otherwise read a foreign branch's work as current-turn context. */
+const CROSS_LEAF_NOTICE =
+  "NOTE: this async delegate ticket was spawned on a different branch of the " +
+  "session tree; the conversation has since navigated elsewhere (/tree). These " +
+  "results may not relate to the current line of work — verify relevance before " +
+  "acting on them.";
+
+/** How a completed ticket was handed back. `deferred` means the result was
+ *  queued without waking the agent because the session navigated away from
+ *  the spawn leaf; callers surface that to the human (see status.ts). */
+export type TicketDelivery = "none" | "waiters" | "steer" | "deferred";
+
 /** Push results into parent session via sendMessage when background ticket completes.
  *  If there are active blocking waiters, resolve them directly and suppress the
- *  automatic follow-up so completion is delivered exactly once. */
+ *  automatic follow-up so completion is delivered exactly once.
+ *
+ *  Delivery mode depends on leaf affinity (see leaf.ts). Same leaf: `steer` +
+ *  `triggerTurn`, the agent picks the result up immediately. Different leaf:
+ *  `nextTurn`, which explicitly "does not interrupt or trigger anything" — the
+ *  result waits for the human's next prompt instead of waking the agent on a
+ *  branch the task was never part of. The ticket stays pollable either way. */
 export function deliverTicketResults(
   pi: ExtensionAPI,
   ticket: AsyncTicket,
-): void {
-  if (!ticket.completedAt) return;
+): TicketDelivery {
+  if (!ticket.completedAt) return "none";
 
   // Resolve active blocking waiters directly. Stale/aborted waiters are
   // cleaned but not resolved here (their abort handlers already returned).
-  if (settleTicketWaiters(ticket)) return;
+  // A waiter is a tool call on the live leaf by construction, so leaf
+  // affinity does not apply to it.
+  if (settleTicketWaiters(ticket)) return "waiters";
 
   const formatted = formatCompletedTicket(ticket);
   const text = formatted.content
@@ -393,10 +515,12 @@ export function deliverTicketResults(
     .map((c) => c.text)
     .join("\n");
 
+  const crossLeaf = isCrossLeafTicket(ticket);
+
   pi.sendMessage(
     {
       customType: "async_delegate_result",
-      content: text,
+      content: crossLeaf ? `${CROSS_LEAF_NOTICE}\n\n${text}` : text,
       display: true,
       details: {
         ...formatted.details,
@@ -404,11 +528,11 @@ export function deliverTicketResults(
         status: ticket.status,
       },
     },
-    {
-      deliverAs: "steer",
-      triggerTurn: true,
-    },
+    crossLeaf
+      ? { deliverAs: "nextTurn" }
+      : { deliverAs: "steer", triggerTurn: true },
   );
+  return crossLeaf ? "deferred" : "steer";
 }
 
 /** Return a snapshot of one async ticket or the complete ticket roster. */
@@ -434,7 +558,7 @@ export function handlePoll(
               "No async tickets.",
               "",
               "To spawn a subagent: delegate({ tasks: [{ agent, prompt }] }).",
-              "For the full manual and agent list, call delegate({ tasks: [] }) with no top-level `action`.",
+              "For the full manual and agent list, call delegate({ tasks: [] }) with no top-level `ticketAction`.",
             ].join("\n"),
           },
         ],
@@ -467,9 +591,9 @@ export function handlePoll(
       // Copy-pasteable controls for running/cancelling tickets — a human can grab these
       // straight out of the TUI without retyping the ticket id.
       if (t.status === "running" || t.status === "cancelling") {
-        line += `\n     poll:   delegate({ action: "poll", ticket: "${t.id}" })`;
+        line += `\n     poll:   delegate({ ticketAction: "poll", ticket: "${t.id}" })`;
         if (t.status === "running") {
-          line += `\n     cancel: delegate({ action: "cancel", ticket: "${t.id}", force: true })`;
+          line += `\n     cancel: delegate({ ticketAction: "cancel", ticket: "${t.id}", force: true })`;
         }
       }
       return line;
@@ -537,9 +661,9 @@ export function handlePoll(
         if (r.touchedFiles.length > 0) {
           const t = ticket.resolved[i]!;
           const touched = relativeTouchedSummary(r.touchedFiles, t.cwd);
-          if (touched) meta.push(`touched: ${touched}`);
+          if (touched) meta.push(`touched (best-effort): ${touched}`);
         }
-        lines.push(`✓ ${r.agent} · ${meta.join(" · ")}`);
+        lines.push(`✓ ${r.agent}${formatTaskId(r.id)} · ${meta.join(" · ")}`);
         if (r.output && r.output !== "(no output)") {
           lines.push(renderOutputForPoll(r.output));
         }
@@ -549,10 +673,12 @@ export function handlePoll(
         if (r.touchedFiles.length > 0) {
           const t = ticket.resolved[i]!;
           const touched = relativeTouchedSummary(r.touchedFiles, t.cwd);
-          if (touched) meta.push(`touched: ${touched}`);
+          if (touched) meta.push(`touched (best-effort): ${touched}`);
         }
         const errorText = r.error ?? "unknown error";
-        lines.push(`✗ ${r.agent} · ${errorText} · ${meta.join(" · ")}`);
+        lines.push(
+          `✗ ${r.agent}${formatTaskId(r.id)} · ${errorText} · ${meta.join(" · ")}`,
+        );
         if (r.sessionFile)
           lines.push(`  session: ${shortenPath(r.sessionFile)}`);
         if (r.output && r.output !== "(no output)")
@@ -565,12 +691,19 @@ export function handlePoll(
         if (p.tokens > 0) parts.push(`${fmtTokens(p.tokens)} tokens`);
         const age = getActivityAge(p.lastActivityAt);
         if (age) parts.push(age);
-        lines.push(`⏳ ${p.agent} · ${parts.join(" · ")}`);
+        lines.push(`⏳ ${p.agent}${formatTaskId(p.id)} · ${parts.join(" · ")}`);
       } else {
-        lines.push(`○ ${p.agent} · waiting…`);
+        lines.push(`○ ${p.agent}${formatTaskId(p.id)} · waiting…`);
       }
     }
 
+    const completedForOverlap = completedResults.filter(
+      (r): r is TaskResult => r !== undefined,
+    );
+    const overlapWarning = formatTouchedOverlapWarning(
+      findTouchedOverlaps(completedForOverlap),
+    );
+
     const headerStatus =
       ticket.status === "cancelling" ? "CANCELLING" : "RUNNING";
     const headerParts: string[] = [
@@ -586,24 +719,22 @@ export function handlePoll(
     const header = headerParts.join(" · ");
     const guidance =
       ticket.status === "cancelling"
-        ? "Cancellation requested. Active subagents are aborting and returning partial results; poll again for the final status."
+        ? "Cancellation requested. Active subagents are aborting and returning partial results. Wait without timeoutMs for final status; do not repeatedly poll."
         : settledCount === totalCount
           ? ""
-          : settledCount > 0
-            ? "Tasks are progressing. Do other work while remaining tasks finish — results will be delivered automatically when all complete."
-            : "Tasks are still running. Do other work while you wait — polling again immediately will not speed them up. Results are delivered automatically when all tasks complete.";
+          : "If you need the final result in this turn, call wait once with timeoutMs omitted. Otherwise stop calling ticket controls and let the final result auto-deliver after this turn; repeated polling will not speed it up.";
 
     return {
       content: [
         {
           type: "text",
-          text: `${header}\n${lines.join("\n")}${guidance ? `\n\n${guidance}` : ""}`,
+          text: `${header}\n${lines.join("\n")}${guidance ? `\n\n${guidance}` : ""}${overlapWarning ? `\n\n${overlapWarning}` : ""}`,
         },
       ],
       details: {
         tasks: ticket.tasks,
         results: completedResults.map(
-          (r) => r ?? { error: "PENDING — result not available" },
+          (r, i) => r ?? pendingResultPlaceholder(ticket.resolved[i]),
         ),
         progress: [...ticket.progress],
         parentModel: ticket.parentModelId,
@@ -611,6 +742,7 @@ export function handlePoll(
         // (friction #2). The LLM-facing content still names the ticket id too.
         ticketId: ticket.id,
         status: ticket.status,
+        overlapWarning: overlapWarning || undefined,
       },
     };
   }
@@ -633,9 +765,9 @@ function buildCancelPreview(ticket: AsyncTicket): string {
   for (let i = 0; i < ticket.progress.length; i++) {
     const p = ticket.progress[i]!;
     if (p.status === "done") {
-      lines.push(`✓ ${p.agent} · completed`);
+      lines.push(`✓ ${p.agent}${formatTaskId(p.id)} · completed`);
     } else if (p.status === "failed") {
-      lines.push(`✗ ${p.agent} · ${p.error ?? "failed"}`);
+      lines.push(`✗ ${p.agent}${formatTaskId(p.id)} · ${p.error ?? "failed"}`);
     } else if (p.status === "running") {
       const parts: string[] = [formatActivityLabel(p)];
       if (p.toolUses > 0)
@@ -643,16 +775,16 @@ function buildCancelPreview(ticket: AsyncTicket): string {
       if (p.tokens > 0) parts.push(`${fmtTokens(p.tokens)} tokens`);
       const age = getActivityAge(p.lastActivityAt);
       if (age) parts.push(age);
-      lines.push(`⏳ ${p.agent} · ${parts.join(" · ")}`);
+      lines.push(`⏳ ${p.agent}${formatTaskId(p.id)} · ${parts.join(" · ")}`);
     } else {
-      lines.push(`○ ${p.agent} · waiting…`);
+      lines.push(`○ ${p.agent}${formatTaskId(p.id)} · waiting…`);
     }
   }
 
   lines.push(
     "",
     "WARNING: Cancelling now will abort active subagents. Files already written or shell commands already executed are NOT rolled back.",
-    `To proceed, call delegate({ action: "cancel", ticket: "${ticket.id}", force: true }).`,
+    `To proceed, call delegate({ ticketAction: "cancel", ticket: "${ticket.id}", force: true }).`,
   );
   return lines.join("\n");
 }
@@ -668,7 +800,7 @@ export function handleCancel(params: {
   if (!ticketId) {
     return {
       content: [
-        { type: "text", text: "action='cancel' requires a ticket ID." },
+        { type: "text", text: "ticketAction='cancel' requires a ticket ID." },
       ],
       details: { tasks: [], results: [], progress: [] },
     };
@@ -692,29 +824,30 @@ export function handleCancel(params: {
     };
   }
   if (!params.force) {
+    const details = buildWaitDetails(ticket);
+    const text =
+      buildCancelPreview(ticket) +
+      (details.overlapWarning ? `\n\n${details.overlapWarning}` : "");
     return {
-      content: [{ type: "text", text: buildCancelPreview(ticket) }],
-      details: buildWaitDetails(ticket),
+      content: [{ type: "text", text }],
+      details,
     };
   }
-  ticket.controller.abort();
-  ticket.status = "cancelling";
-  syncTicketBusyIndex(ticket);
+  requestTicketCancel(ticket);
+  const details = buildWaitDetails(ticket);
+  const base = `Ticket '${ticketId}' is cancelling; workers are settling. Poll for final status.`;
+  const text =
+    base + (details.overlapWarning ? `\n\n${details.overlapWarning}` : "");
   return {
-    content: [
-      {
-        type: "text",
-        text: `Ticket '${ticketId}' is cancelling; workers are settling. Poll for final status.`,
-      },
-    ],
-    details: buildWaitDetails(ticket),
+    content: [{ type: "text", text }],
+    details,
   };
 }
 
 /** Block until a ticket reaches a terminal state or `timeoutMs` expires.
  *  Progress is streamed through `onUpdate` without consuming model turns.
  *  Parent-tool abort or timeout detaches the waiter and leaves the ticket
- *  running; cancellation remains explicit (`action: "cancel"`). */
+ *  running; cancellation remains explicit (`ticketAction: "cancel"`). */
 export function handleWait(
   params: { ticket?: string; timeoutMs?: number },
   signal: AbortSignal | undefined,
@@ -727,7 +860,9 @@ export function handleWait(
   const ticketId = params.ticket;
   if (!ticketId) {
     return Promise.resolve({
-      content: [{ type: "text", text: "action='wait' requires a ticket ID." }],
+      content: [
+        { type: "text", text: "ticketAction='wait' requires a ticket ID." },
+      ],
       details: {
         tasks: [],
         results: [],

package/tools.ts

@@ -12,20 +12,22 @@ import { DEFAULT_TOOLS, READONLY_TOOLS } from "./constants.ts";
 
 /** Shorthand → concrete tool list. `*` = full agent (bash subsumes search);
  *  `ro` = read-only scout (search without shell). */
-const TOOL_GROUPS: Record<string, string[]> = {
-  "*": DEFAULT_TOOLS,
-  ro: READONLY_TOOLS,
-};
+const TOOL_GROUPS: Record<string, string[]> = Object.create(null) as Record<
+  string,
+  string[]
+>;
+TOOL_GROUPS["*"] = DEFAULT_TOOLS;
+TOOL_GROUPS.ro = READONLY_TOOLS;
 
-export const TOOL_FACTORIES: Record<string, (cwd: string) => AgentTool<any>> = {
-  read: createReadTool,
-  write: createWriteTool,
-  edit: createEditTool,
-  bash: createBashTool,
-  grep: createGrepTool,
-  find: createFindTool,
-  ls: createLsTool,
-};
+export const TOOL_FACTORIES: Record<string, (cwd: string) => AgentTool<any>> =
+  Object.create(null) as Record<string, (cwd: string) => AgentTool<any>>;
+TOOL_FACTORIES.read = createReadTool;
+TOOL_FACTORIES.write = createWriteTool;
+TOOL_FACTORIES.edit = createEditTool;
+TOOL_FACTORIES.bash = createBashTool;
+TOOL_FACTORIES.grep = createGrepTool;
+TOOL_FACTORIES.find = createFindTool;
+TOOL_FACTORIES.ls = createLsTool;
 
 /** Expand tool-group shorthands (`*`, `ro`) into concrete tool lists.
  *  Unknown names pass through unchanged for the caller to validate.
@@ -33,8 +35,7 @@ export const TOOL_FACTORIES: Record<string, (cwd: string) => AgentTool<any>> = {
 export function resolveToolGroups(tools: string[]): string[] {
   const resolved: string[] = [];
   for (const t of tools) {
-    const group = TOOL_GROUPS[t];
-    if (group) resolved.push(...group);
+    if (Object.hasOwn(TOOL_GROUPS, t)) resolved.push(...TOOL_GROUPS[t]);
     else resolved.push(t);
   }
   return [...new Set(resolved)];