@bermudi/pi-delegate 0.1.9 → 0.1.11

package/tickets.ts

@@ -9,21 +9,21 @@ import type {
 import { ASYNC_TICKET_TTL_MS } from "./constants.ts";
 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 {
+  emptyTicketPollResult,
+  formatCancelPreview,
+  formatLiveTicketPoll,
+  missingTicketPollResult,
+  rosterTicketPollResult,
+} from "./ticket-format.ts";
 import { aggregateTaskResults, emptyUsage } from "./usage.ts";
 import { recordCall } from "./telemetry.ts";
 import type {
@@ -115,6 +115,39 @@ export function sweepTickets(): void {
   }
 }
 
+/** Options for `settleTicket`. */
+export interface SettleTicketOptions {
+  status: "done" | "failed" | "cancelled";
+  /** Recorded on the ticket (unexpected worker failure); omitted leaves any
+   *  existing error untouched. */
+  error?: string;
+}
+
+/**
+ * Transition an active ticket to a terminal state. Single owner of the
+ * terminal transition — status, completion timestamp, error, and the
+ * busy-session index — so the normal-completion, unexpected-error, and
+ * shutdown paths cannot drift apart. Result delivery is deliberately outside
+ * this transition: a host `sendMessage()` failure must not undo or re-enter
+ * worker settlement. Settling is idempotent: `completedAt` is the settle
+ * marker, and a second settle attempt is a loud no-op.
+ */
+export function settleTicket(
+  ticket: AsyncTicket,
+  opts: SettleTicketOptions,
+): void {
+  if (ticket.completedAt) {
+    console.error(
+      `[delegate] ticket '${ticket.id}' already settled as '${ticket.status}'; ignoring settle as '${opts.status}'`,
+    );
+    return;
+  }
+  ticket.status = opts.status;
+  if (opts.error !== undefined) ticket.error = opts.error;
+  ticket.completedAt = Date.now();
+  syncTicketBusyIndex(ticket);
+}
+
 /**
  * Finalize an active ticket during host shutdown and resolve any blocking
  * waiters. This intentionally does not send a follow-up: the host is exiting.
@@ -122,17 +155,16 @@ export function sweepTickets(): void {
 export function cancelTicketForShutdown(ticket: AsyncTicket): void {
   if (ticket.status !== "running" && ticket.status !== "cancelling") return;
   ticket.controller.abort();
-  ticket.status = "cancelled";
-  ticket.completedAt = Date.now();
-  syncTicketBusyIndex(ticket);
+  settleTicket(ticket, { status: "cancelled" });
   settleTicketWaiters(ticket);
   if (ticket.callRecord) {
+    const completedAt = ticket.completedAt ?? Date.now();
     const { totalTokens, totalCost } = aggregateTaskResults(ticket.results);
     recordCall(
       {
         ...ticket.callRecord,
         status: "cancelled",
-        wall_ms: ticket.completedAt - (ticket.callStartedAt ?? ticket.created),
+        wall_ms: completedAt - (ticket.callStartedAt ?? ticket.created),
         total_tokens: totalTokens,
         total_cost: totalCost,
       },
@@ -168,9 +200,9 @@ export function isSessionBusy(sessionId: string): string | null {
  * is also "failed".
  *
  * Callers are expected to have already handled "cancelled" / "cancelling"
- * (set by handleCancel) before invoking this; those paths set `ticket.status`
- * directly and skip this function via the `if (ticket.status === "running")`
- * guard in execute().
+ * (set by handleCancel / cancelTicketForShutdown) before invoking this;
+ * dispatchAsync's completion path routes both through `settleTicket`, which
+ * only calls this for a still-"running" ticket.
  */
 export function resolveFinalTicketStatus(
   ticket: AsyncTicket,
@@ -517,21 +549,31 @@ export function deliverTicketResults(
 
   const crossLeaf = isCrossLeafTicket(ticket);
 
-  pi.sendMessage(
-    {
-      customType: "async_delegate_result",
-      content: crossLeaf ? `${CROSS_LEAF_NOTICE}\n\n${text}` : text,
-      display: true,
-      details: {
-        ...formatted.details,
-        ticketId: ticket.id,
-        status: ticket.status,
+  try {
+    pi.sendMessage(
+      {
+        customType: "async_delegate_result",
+        content: crossLeaf ? `${CROSS_LEAF_NOTICE}\n\n${text}` : text,
+        display: true,
+        details: {
+          ...formatted.details,
+          ticketId: ticket.id,
+          status: ticket.status,
+        },
       },
-    },
-    crossLeaf
-      ? { deliverAs: "nextTurn" }
-      : { deliverAs: "steer", triggerTurn: true },
-  );
+      crossLeaf
+        ? { deliverAs: "nextTurn" }
+        : { deliverAs: "steer", triggerTurn: true },
+    );
+  } catch (error) {
+    // Delivery is an observer boundary. The terminal ticket remains pollable
+    // even when the host cannot accept an unsolicited follow-up.
+    console.error(
+      `[delegate] failed to deliver results for ticket '${ticket.id}'; it remains pollable`,
+      error,
+    );
+    return "none";
+  }
   return crossLeaf ? "deferred" : "steer";
 }
 
@@ -545,195 +587,23 @@ export function handlePoll(
 
   // Only use top-level ticket param — per-task prompt is NOT a ticket ID
   const ticketId = params.ticket;
-
-  // No ticket specified — list all
   if (!ticketId) {
     const tickets = [...ticketRegistry.values()];
-    if (!tickets.length) {
-      return {
-        content: [
-          {
-            type: "text",
-            text: [
-              "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 `ticketAction`.",
-            ].join("\n"),
-          },
-        ],
-        details: {
-          tasks: [],
-          results: [],
-          progress: [],
-          parentModel: parentModelId,
-        },
-      };
-    }
-    const lines = tickets.map((t) => {
-      const icon =
-        t.status === "running" || t.status === "cancelling"
-          ? "⏳"
-          : t.status === "done"
-            ? "✓"
-            : "✗";
-      const done = t.progress.filter((p) => p.status === "done").length;
-      const age = fmtDuration(Date.now() - t.created);
-      // Agent roster — compact, deduplicated (a ticket may run the same agent
-      // several times). Helps a human tell tickets apart at a glance.
-      const agentSet = [
-        ...new Set(t.progress.map((p) => p.agent).filter(Boolean)),
-      ];
-      const agents = agentSet.length
-        ? ` · ${agentSet.slice(0, 3).join(", ")}${agentSet.length > 3 ? ` +${agentSet.length - 3}` : ""}`
-        : "";
-      let line = `${icon} ${t.id}${agents} · ${done}/${t.progress.length} tasks · ${t.status} · ${age}`;
-      // 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({ ticketAction: "poll", ticket: "${t.id}" })`;
-        if (t.status === "running") {
-          line += `\n     cancel: delegate({ ticketAction: "cancel", ticket: "${t.id}", force: true })`;
-        }
-      }
-      return line;
-    });
-    return {
-      content: [{ type: "text", text: `Async tickets:\n${lines.join("\n")}` }],
-      details: {
-        tasks: [],
-        results: [],
-        progress: [],
-        parentModel: parentModelId,
-      },
-    };
+    return tickets.length
+      ? rosterTicketPollResult(tickets, parentModelId)
+      : emptyTicketPollResult(parentModelId);
   }
 
-  // Specific ticket
   const ticket = ticketRegistry.get(ticketId);
-  if (!ticket) {
-    return {
-      content: [
-        {
-          type: "text",
-          text: `Ticket '${ticketId}' not found. It may have expired or never existed.`,
-        },
-      ],
-      details: {
-        tasks: [],
-        results: [],
-        progress: [],
-        parentModel: parentModelId,
-      },
-    };
-  }
+  if (!ticket) return missingTicketPollResult(ticketId, parentModelId);
 
   if (ticket.status === "running" || ticket.status === "cancelling") {
-    const failedCount = ticket.progress.filter(
-      (p) => p.status === "failed",
-    ).length;
-    // Settled = done + failed. Used for the "all finished" guidance check.
-    const settledCount = ticket.progress.filter(
-      (p) => p.status === "done" || p.status === "failed",
-    ).length;
-    const totalCount = ticket.progress.length;
-    const runningCount = ticket.progress.filter(
-      (p) => p.status === "running",
-    ).length;
-    const pendingCount = ticket.progress.filter(
-      (p) => p.status === "pending",
-    ).length;
-    const totalTools = ticket.progress.reduce((sum, p) => sum + p.toolUses, 0);
-    const totalTokens = ticket.progress.reduce((sum, p) => sum + p.tokens, 0);
-    const lines: string[] = [];
-    // Index-aligned sparse array — same shape as ticket.results, so consumers
-    // can correlate results[i] with progress[i] and tasks[i].
-    const completedResults: (TaskResult | undefined)[] = new Array(
-      ticket.progress.length,
-    ).fill(undefined);
-
-    for (let i = 0; i < ticket.progress.length; i++) {
-      const p = ticket.progress[i]!;
-      const r = ticket.results[i];
-
-      if (p.status === "done" && r) {
-        const meta = taskMetaBase(r);
-        if (r.touchedFiles.length > 0) {
-          const t = ticket.resolved[i]!;
-          const touched = relativeTouchedSummary(r.touchedFiles, t.cwd);
-          if (touched) meta.push(`touched (best-effort): ${touched}`);
-        }
-        lines.push(`✓ ${r.agent}${formatTaskId(r.id)} · ${meta.join(" · ")}`);
-        if (r.output && r.output !== "(no output)") {
-          lines.push(renderOutputForPoll(r.output));
-        }
-        completedResults[i] = r;
-      } else if (p.status === "failed" && r) {
-        const meta = taskMetaBase(r);
-        if (r.touchedFiles.length > 0) {
-          const t = ticket.resolved[i]!;
-          const touched = relativeTouchedSummary(r.touchedFiles, t.cwd);
-          if (touched) meta.push(`touched (best-effort): ${touched}`);
-        }
-        const errorText = r.error ?? "unknown error";
-        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)")
-          lines.push(renderOutputForPoll(r.output));
-        completedResults[i] = r;
-      } else if (p.status === "running") {
-        const parts: string[] = [formatActivityLabel(p)];
-        if (p.toolUses > 0)
-          parts.push(`${p.toolUses} tool${p.toolUses === 1 ? "" : "s"}`);
-        if (p.tokens > 0) parts.push(`${fmtTokens(p.tokens)} tokens`);
-        const age = getActivityAge(p.lastActivityAt);
-        if (age) parts.push(age);
-        lines.push(`⏳ ${p.agent}${formatTaskId(p.id)} · ${parts.join(" · ")}`);
-      } else {
-        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[] = [
-      `Ticket ${ticket.id}: ${headerStatus}`,
-      `${settledCount}/${totalCount} finalized`,
-    ];
-    if (runningCount > 0) headerParts.push(`${runningCount} active`);
-    if (pendingCount > 0) headerParts.push(`${pendingCount} queued`);
-    if (failedCount > 0) headerParts.push(`${failedCount} failed`);
-    headerParts.push(`${totalTools} tool${totalTools === 1 ? "" : "s"}`);
-    headerParts.push(`${fmtTokens(totalTokens)} tokens`);
-    headerParts.push(`(${fmtDuration(Date.now() - ticket.created)})`);
-    const header = headerParts.join(" · ");
-    const guidance =
-      ticket.status === "cancelling"
-        ? "Cancellation requested. Active subagents are aborting and returning partial results. Wait without timeoutMs for final status; do not repeatedly poll."
-        : settledCount === totalCount
-          ? ""
-          : "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.";
-
+    const snapshot = formatLiveTicketPoll(ticket);
     return {
-      content: [
-        {
-          type: "text",
-          text: `${header}\n${lines.join("\n")}${guidance ? `\n\n${guidance}` : ""}${overlapWarning ? `\n\n${overlapWarning}` : ""}`,
-        },
-      ],
+      content: [{ type: "text", text: snapshot.text }],
       details: {
         tasks: ticket.tasks,
-        results: completedResults.map(
+        results: snapshot.completedResults.map(
           (r, i) => r ?? pendingResultPlaceholder(ticket.resolved[i]),
         ),
         progress: [...ticket.progress],
@@ -742,53 +612,14 @@ export function handlePoll(
         // (friction #2). The LLM-facing content still names the ticket id too.
         ticketId: ticket.id,
         status: ticket.status,
-        overlapWarning: overlapWarning || undefined,
+        overlapWarning: snapshot.overlapWarning || undefined,
       },
     };
   }
 
-  // Done / Failed / Cancelled — full results
   return formatCompletedTicket(ticket);
 }
 
-function buildCancelPreview(ticket: AsyncTicket): string {
-  const finalized = ticket.progress.filter(
-    (p) => p.status === "done" || p.status === "failed",
-  ).length;
-  const running = ticket.progress.filter((p) => p.status === "running").length;
-  const pending = ticket.progress.filter((p) => p.status === "pending").length;
-  const lines: string[] = [
-    `Ticket ${ticket.id}: cancellation preview`,
-    `${finalized}/${ticket.progress.length} finalized · ${running} active · ${pending} queued`,
-  ];
-
-  for (let i = 0; i < ticket.progress.length; i++) {
-    const p = ticket.progress[i]!;
-    if (p.status === "done") {
-      lines.push(`✓ ${p.agent}${formatTaskId(p.id)} · completed`);
-    } else if (p.status === "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)
-        parts.push(`${p.toolUses} tool${p.toolUses === 1 ? "" : "s"}`);
-      if (p.tokens > 0) parts.push(`${fmtTokens(p.tokens)} tokens`);
-      const age = getActivityAge(p.lastActivityAt);
-      if (age) parts.push(age);
-      lines.push(`⏳ ${p.agent}${formatTaskId(p.id)} · ${parts.join(" · ")}`);
-    } else {
-      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({ ticketAction: "cancel", ticket: "${ticket.id}", force: true }).`,
-  );
-  return lines.join("\n");
-}
-
 /** Preview or request cancellation of a running async ticket. */
 export function handleCancel(params: {
   ticket?: string;
@@ -826,7 +657,7 @@ export function handleCancel(params: {
   if (!params.force) {
     const details = buildWaitDetails(ticket);
     const text =
-      buildCancelPreview(ticket) +
+      formatCancelPreview(ticket) +
       (details.overlapWarning ? `\n\n${details.overlapWarning}` : "");
     return {
       content: [{ type: "text", text }],

package/tools.ts

@@ -29,6 +29,18 @@ TOOL_FACTORIES.grep = createGrepTool;
 TOOL_FACTORIES.find = createFindTool;
 TOOL_FACTORIES.ls = createLsTool;
 
+/** Tools supplied by the allowlisted provider extension rather than Pi core. */
+const PROVIDER_TOOLS: Readonly<Record<string, readonly string[]>> = {
+  "openai-codex": ["web_search"],
+};
+
+export function availableToolNames(modelProvider?: string): string[] {
+  return [
+    ...Object.keys(TOOL_FACTORIES),
+    ...(modelProvider ? (PROVIDER_TOOLS[modelProvider] ?? []) : []),
+  ];
+}
+
 /** Expand tool-group shorthands (`*`, `ro`) into concrete tool lists.
  *  Unknown names pass through unchanged for the caller to validate.
  *  Returns a deduped list. */

package/trusted-paths.ts

@@ -0,0 +1,71 @@
+/**
+ * Path containment primitives for the subagent trust boundary.
+ *
+ * These decide whether a resolved package directory is allowed to become
+ * executable subagent code, so they compare **canonical** paths: a symlink
+ * whose target escapes an install root must not be able to launder itself
+ * through a lexically-innocent path.
+ */
+import { realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+/**
+ * Resolve a path through symlinks, or `undefined` if the path cannot be
+ * canonicalized.
+ *
+ * A path that cannot be resolved to a real filesystem target is never accepted
+ * as trusted: returning `undefined` lets callers fail closed rather than
+ * falling back to lexical resolution, which a symlink whose target escapes an
+ * install root could launder itself through.
+ */
+export function canonicalPath(candidate: string): string | undefined {
+  try {
+    return realpathSync(candidate);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Whether `candidate` is `directory` itself or lies beneath it, after symlink
+ * resolution. Returns `false` when either path cannot be canonicalized. */
+export function isPathWithinDirectory(
+  directory: string | undefined,
+  candidate: string | undefined,
+): boolean {
+  if (directory === undefined || candidate === undefined) return false;
+  const canonicalDirectory = canonicalPath(directory);
+  const canonicalCandidate = canonicalPath(candidate);
+  if (canonicalDirectory === undefined || canonicalCandidate === undefined) {
+    return false;
+  }
+  const relativePath = relative(canonicalDirectory, canonicalCandidate);
+  return (
+    relativePath === "" ||
+    (relativePath !== ".." &&
+      !relativePath.startsWith(`..${sep}`) &&
+      !isAbsolute(relativePath))
+  );
+}
+
+/**
+ * Whether `candidate` is `directory` itself or lies beneath it, using lexical
+ * resolution only (no symlink resolution).
+ *
+ * Use this for containment checks on paths that are already trusted or that
+ * need not exist on disk (e.g. classifying load failures by root). For the
+ * subagent trust boundary, use `isPathWithinDirectory` instead — a symlink
+ * whose target escapes an install root must not launder itself through a
+ * lexical check.
+ */
+export function isPathWithinDirectoryLexical(
+  directory: string,
+  candidate: string,
+): boolean {
+  const relativePath = relative(resolve(directory), resolve(candidate));
+  return (
+    relativePath === "" ||
+    (relativePath !== ".." &&
+      !relativePath.startsWith(`..${sep}`) &&
+      !isAbsolute(relativePath))
+  );
+}

package/types.ts

@@ -23,20 +23,26 @@ export interface AgentConfig {
   thinking?: ThinkingLevel;
   tools: string[];
   systemPrompt: string;
-  /** Built-in profiles are immutable and cannot be shadowed by Markdown. */
+  /** Built-in profiles can be overridden by a same-named Markdown file. */
   builtin?: boolean;
   /** Default workspace for a built-in profile. Custom agents use shared. */
   workspace?: WorkspaceMode;
   /** Origin of the profile. `claude` denotes imported .claude/agents files. */
   scope?: "project" | "global" | "claude";
+  /** Whether `tools` was explicitly set in the Markdown frontmatter (vs inherited default). */
+  explicitTools?: boolean;
+  /** Whether `model` was explicitly set in the Markdown frontmatter. */
+  explicitModel?: boolean;
+  /** Whether `thinking` was explicitly set in the Markdown frontmatter. */
+  explicitThinking?: boolean;
+  /** Denylist applied to a built-in `default` override with no explicit allowlist – materialized against parentNativeTools at resolution. */
+  deniedTools?: string[];
 }
 
 // ── Tool parameter types — derived from the TypeBox schema ────────────────
 // `delegateArgumentsSchema` in schema.ts is the canonical provider-visible
-// shape. The public types add deprecated `action` aliases so existing TypeScript
-// callers remain source-compatible without advertising the overloaded fields to
-// models. The import is type-only, so the schema.ts ↔ types.ts cycle is erased
-// at compile time.
+// shape; these types are its `Static<>` projections. The import is type-only,
+// so the schema.ts ↔ types.ts cycle is erased at compile time.
 
 type CanonicalDelegateArguments = Static<typeof delegateArgumentsSchema>;
 type CanonicalTaskDef = NonNullable<
@@ -52,19 +58,9 @@ export type SessionAction = NonNullable<CanonicalTaskDef["sessionAction"]>;
 /** Filesystem mode: shared source tree or an ephemeral CoW scratch copy. */
 export type WorkspaceMode = NonNullable<CanonicalTaskDef["workspace"]>;
 
-export type TaskDef = CanonicalTaskDef & {
-  /** @deprecated Use `sessionAction` instead. Runtime normalization still accepts this alias. */
-  action?: SessionAction;
-};
+export type TaskDef = CanonicalTaskDef;
 
-export type DelegateArguments = Omit<CanonicalDelegateArguments, "tasks"> & {
-  /** @deprecated Use `ticketAction` instead. Runtime normalization still accepts this alias. */
-  action?: TicketAction;
-  tasks?: TaskDef[];
-};
-
-/** @deprecated Use `TicketAction` instead. */
-export type DelegateAction = TicketAction;
+export type DelegateArguments = CanonicalDelegateArguments;
 
 // ── Async Ticket Types ─────────────────────────────────────────────────────