@bermudi/pi-delegate 0.1.1 → 0.1.3

package/schema.ts

@@ -18,10 +18,23 @@ function StringEnum<const T extends readonly string[]>(
   });
 }
 
+const TASK_ID_PATTERN = "^[A-Za-z0-9._-]{1,64}$";
+const TASK_ID_RE = new RegExp(TASK_ID_PATTERN);
+
 export const delegateTaskSchema = Type.Object({
+  id: Type.Optional(
+    Type.String({
+      pattern: TASK_ID_PATTERN,
+      minLength: 1,
+      maxLength: 64,
+      description:
+        "Optional task correlation key; 1-64 chars; A-Z a-z 0-9 . _ - only; duplicate ids rejected. Omit for index.",
+    }),
+  ),
   prompt: Type.Optional(
     Type.String({
-      description: "Task prompt; omit only for close, list, or resumeFrom.",
+      description:
+        "Self-contained task prompt; fresh context cannot see this chat. Omit only for close, list, or resumeFrom.",
     }),
   ),
   agent: Type.Optional(
@@ -37,13 +50,14 @@ export const delegateTaskSchema = Type.Object({
   ),
   systemPrompt: Type.Optional(
     Type.String({
-      description: "Base system prompt; AgentSession adds project resources.",
+      description:
+        "Base system prompt; project resources from the task cwd are added automatically.",
     }),
   ),
   context: Type.Optional(
     StringEnum(["fresh", "with-parent-transcript"], {
       description:
-        "fresh omits parent transcript; with-parent-transcript copies it (token-expensive).",
+        "fresh omits this chat; with-parent-transcript copies it (token-expensive).",
       default: "fresh",
     }),
   ),
@@ -55,7 +69,7 @@ export const delegateTaskSchema = Type.Object({
   tools: Type.Optional(
     Type.Array(Type.String(), {
       description:
-        "`default`=parent natives; ad-hoc=*; *=read/write/edit/bash (mutating); ro=read/grep/find/ls (read-only).",
+        "Names/presets: *=read/write/edit/bash (mutating); ro=read/grep/find/ls (read-only). Ad-hoc defaults to *.",
     }),
   ),
   thinking: Type.Optional(
@@ -70,7 +84,7 @@ export const delegateTaskSchema = Type.Object({
         "Live pool key for multi-turn reuse; omit for one-shot tasks.",
     }),
   ),
-  action: Type.Optional(
+  sessionAction: Type.Optional(
     StringEnum(["prompt", "close", "list"], {
       description:
         "Session action; close needs sessionId; list shows active pooled sessions.",
@@ -83,12 +97,20 @@ export const delegateTaskSchema = Type.Object({
         "Exact absolute .jsonl session path from retry output; never a ticket ID.",
     }),
   ),
+  deadlineMs: Type.Optional(
+    Type.Number({
+      description:
+        "Wall-clock budget (ms) from run start after queueing. Cooperative abort; side effects remain. Omit disables.",
+    }),
+  ),
 });
 
-// Single source of truth for registration, generated help, and the
-// DelegateArguments/TaskDef projections in types.ts.
+// Single source of truth for registration and generated help. The exported
+// argument types in types.ts project this canonical schema and add deprecated
+// `action` aliases as a type-only compatibility overlay; providers never see
+// those legacy fields in this schema.
 export const delegateArgumentsSchema = Type.Object({
-  action: Type.Optional(
+  ticketAction: Type.Optional(
     StringEnum(["poll", "cancel", "wait"], {
       description:
         "Ticket control: poll=snapshot; wait=block until settled; cancel=abort. Prefer wait; never cancel for time.",
@@ -109,7 +131,7 @@ export const delegateArgumentsSchema = Type.Object({
   force: Type.Optional(
     Type.Boolean({
       description:
-        "True cancels after preview; completed writes/commands remain.",
+        "With cancel: false previews active work; true confirms abort. Completed writes/commands remain.",
       default: false,
     }),
   ),
@@ -117,14 +139,14 @@ export const delegateArgumentsSchema = Type.Object({
     Type.Number({
       minimum: 0,
       description:
-        "Bounds wait (ms); omit to block until settled. Timeout never cancels the ticket.",
+        "Bounds wait (ms); omit to block until settled. Timeout returns a snapshot; do not poll afterward.",
     }),
   ),
   tasks: Type.Optional(
     Type.Array(delegateTaskSchema, {
       minItems: 0,
       description:
-        "Fields in entries; tasks run concurrently; separate dependent/shared-file work. []=help.",
+        "Tasks share the real filesystem and run concurrently; separate dependent/shared-file work. []=full manual.",
     }),
   ),
 });
@@ -132,6 +154,7 @@ export const delegateArgumentsSchema = Type.Object({
 /** Fields that belong to a task entry. Models sometimes place these at the
  * top level of the arguments; the shim folds them back into a single task. */
 const TASK_FIELD_NAMES = [
+  "id",
   "prompt",
   "agent",
   "cwd",
@@ -141,7 +164,9 @@ const TASK_FIELD_NAMES = [
   "tools",
   "thinking",
   "sessionId",
+  "sessionAction",
   "resumeFrom",
+  "deadlineMs",
 ] as const;
 
 /** Every field a task entry may carry. Anything else is a model mistake —
@@ -149,37 +174,81 @@ const TASK_FIELD_NAMES = [
  * corrective message instead of being silently ignored (observed in the
  * wild: a task-level `async: true` the caller believed had backgrounded
  * the work while the call in fact ran synchronously). */
-const VALID_TASK_KEYS = new Set<string>([...TASK_FIELD_NAMES, "action"]);
+const VALID_TASK_KEYS = new Set<string>([...TASK_FIELD_NAMES, "sessionAction"]);
+
+/** Top-level ticket actions the legacy `action` field may map to. */
+const TICKET_ACTIONS = new Set(["poll", "cancel", "wait"]);
+
+/** Session actions that are valid at the task level. A flat `action` at the
+ * top level may also fold into a wrapped task's `sessionAction`. */
+const TASK_ACTIONS = new Set(["prompt", "close", "list"]);
+
+/** Every value the legacy `action` field can carry before it is normalized to
+ * `ticketAction` or `sessionAction`. */
+const LEGACY_ACTIONS = new Set([...TICKET_ACTIONS, ...TASK_ACTIONS]);
 
 /** Validate the three operation modes after compatibility reshaping. */
 export function validateDelegateOperation(
   params: DelegateArguments,
 ): string | undefined {
+  const rawParams = params as Record<string, unknown>;
   const tasks = params.tasks ?? [];
-  const isTicketControl = params.action !== undefined;
+
+  const hasLegacyAction = typeof rawParams.action === "string";
+  const hasTicketAction = params.ticketAction !== undefined;
+
+  if (hasLegacyAction) {
+    if (!LEGACY_ACTIONS.has(rawParams.action as string)) {
+      return `unknown action '${rawParams.action}'; valid ticket actions are poll/cancel/wait, valid session actions are prompt/close/list.`;
+    }
+    if (hasTicketAction) {
+      return "ambiguous: supply only ticketAction (or only legacy action), not both.";
+    }
+    if (TASK_ACTIONS.has(rawParams.action as string) && tasks.length > 0) {
+      return `legacy top-level action '${rawParams.action}' cannot be combined with an explicit tasks array; move it into the task's sessionAction or remove tasks.`;
+    }
+  }
+
+  const ticketAction: string | undefined =
+    params.ticketAction ??
+    (hasLegacyAction && TICKET_ACTIONS.has(rawParams.action as string)
+      ? (rawParams.action as string)
+      : undefined);
+
+  const isTicketControl = ticketAction !== undefined;
 
   if (isTicketControl) {
-    if (params.tasks !== undefined || params.async === true) {
-      return "ticket control cannot include tasks or async; call it separately.";
+    const topLevelTaskIntentFields = [...TASK_FIELD_NAMES, "tasks"] as const;
+    const taskIntentFields = topLevelTaskIntentFields.filter(
+      (field) => rawParams[field] !== undefined,
+    );
+    if (taskIntentFields.length) {
+      return `ticket control cannot be combined with task-intent field(s) ${taskIntentFields
+        .map((field) => `'${field}'`)
+        .join(", ")}; call it separately.`;
+    }
+    if (params.async === true) {
+      return "ticket control cannot include async; call it separately.";
     }
-    if (params.action !== "poll" && !params.ticket) {
-      return `action '${params.action}' requires ticket.`;
+    if (ticketAction !== "poll" && !params.ticket) {
+      return `ticketAction '${ticketAction}' requires ticket.`;
     }
-    if (params.action !== "cancel" && params.force === true) {
-      return "force is valid only with action 'cancel'.";
+    if (ticketAction !== "cancel" && params.force === true) {
+      return "force is valid only with ticketAction 'cancel'.";
     }
-    if (params.action !== "wait" && params.timeoutMs !== undefined) {
-      return "timeoutMs is valid only with action 'wait'.";
+    if (ticketAction !== "wait" && params.timeoutMs !== undefined) {
+      return "timeoutMs is valid only with ticketAction 'wait'.";
     }
     return undefined;
   }
 
   if (params.ticket !== undefined) {
-    return "ticket requires action 'poll', 'cancel', or 'wait'.";
+    return "ticket requires ticketAction 'poll', 'cancel', or 'wait'.";
   }
-  if (params.force === true) return "force is valid only with action 'cancel'.";
+  if (params.force === true)
+    return "force is valid only with ticketAction 'cancel'.";
   if (params.timeoutMs !== undefined) {
-    return "timeoutMs is valid only with action 'wait'.";
+    return "timeoutMs is valid only with ticketAction 'wait'.";
   }
   if (!tasks.length) {
     return params.async === true
@@ -187,10 +256,48 @@ export function validateDelegateOperation(
       : undefined; // Intentional help request.
   }
 
+  // Reject mixed shapes: flat task fields at the top level alongside a
+  // nonempty tasks array. The normalize shim only wraps flat fields when
+  // there is no tasks array, so a mixed call silently lets tasks win —
+  // a model mistake that should fail loudly.
+  if (tasks.length > 0) {
+    const flatTaskFields = [
+      ...new Set([...TASK_FIELD_NAMES, "sessionAction", "action"]),
+    ].filter((field) => rawParams[field] !== undefined);
+    if (flatTaskFields.length) {
+      return `cannot mix top-level task field(s) ${flatTaskFields
+        .map((field) => `'${field}'`)
+        .join(
+          ", ",
+        )} with an explicit tasks array; move them into a task entry or remove tasks.`;
+    }
+  }
+
   for (const [index, task] of tasks.entries()) {
-    const unknownKeys = Object.keys(task).filter(
-      (key) => !VALID_TASK_KEYS.has(key),
-    );
+    const rawTask = task as Record<string, unknown>;
+    const hasLegacyTaskAction = typeof rawTask.action === "string";
+    const hasSessionAction = task.sessionAction !== undefined;
+
+    if (hasLegacyTaskAction) {
+      if (!TASK_ACTIONS.has(rawTask.action as string)) {
+        return `task ${index + 1}: unknown action '${rawTask.action}'; valid session actions are prompt/close/list.`;
+      }
+      if (hasSessionAction) {
+        return `task ${index + 1}: ambiguous: supply only sessionAction (or only legacy action), not both.`;
+      }
+    }
+
+    const sessionAction: string | undefined =
+      task.sessionAction ??
+      (hasLegacyTaskAction && TASK_ACTIONS.has(rawTask.action as string)
+        ? (rawTask.action as string)
+        : undefined);
+
+    const unknownKeys = Object.keys(rawTask).filter((key) => {
+      if (VALID_TASK_KEYS.has(key)) return false;
+      if (key === "action" && sessionAction !== undefined) return false;
+      return true;
+    });
     if (unknownKeys.length) {
       const asyncHint = unknownKeys.includes("async")
         ? " 'async' is a top-level flag; move it out of the task entry."
@@ -202,21 +309,35 @@ export function validateDelegateOperation(
         `Valid task fields: ${[...VALID_TASK_KEYS].join(", ")}.`
       );
     }
-    if (task.action === "close") {
+    if (rawTask.id !== undefined) {
+      if (typeof rawTask.id !== "string" || !TASK_ID_RE.test(rawTask.id)) {
+        return `task ${index + 1}: id must be 1-64 characters using only A-Z, a-z, 0-9, '.', '_', or '-'.`;
+      }
+    }
+    if (typeof rawTask.deadlineMs === "number" && !(rawTask.deadlineMs > 0)) {
+      return `task ${index + 1}: deadlineMs must be a positive number of milliseconds.`;
+    }
+    if (sessionAction === "close") {
       if (!task.sessionId) {
-        return `task ${index + 1}: action 'close' requires sessionId.`;
+        return `task ${index + 1}: sessionAction 'close' requires sessionId.`;
       }
-      const extras = Object.keys(task).filter(
-        (key) => key !== "action" && key !== "sessionId",
+      const extras = Object.keys(rawTask).filter(
+        (key) =>
+          key !== "sessionAction" &&
+          key !== "sessionId" &&
+          key !== "action" &&
+          key !== "id",
       );
       if (extras.length) {
-        return `task ${index + 1}: action 'close' accepts only action and sessionId.`;
+        return `task ${index + 1}: sessionAction 'close' accepts only sessionAction and sessionId.`;
       }
     }
-    if (task.action === "list") {
-      const extras = Object.keys(task).filter((key) => key !== "action");
+    if (sessionAction === "list") {
+      const extras = Object.keys(rawTask).filter(
+        (key) => key !== "sessionAction" && key !== "action" && key !== "id",
+      );
       if (extras.length) {
-        return `task ${index + 1}: action 'list' accepts only action.`;
+        return `task ${index + 1}: sessionAction 'list' accepts only sessionAction.`;
       }
     }
   }
@@ -224,11 +345,6 @@ export function validateDelegateOperation(
   return undefined;
 }
 
-/** Actions that are only valid at task level. The top-level `action` is
- * ticket-scoped (poll/cancel/wait), so a flat close/list/prompt belongs to
- * the wrapped task. */
-const TASK_ACTIONS = new Set(["prompt", "close", "list"]);
-
 function parseStringifiedArray(value: string): unknown[] | undefined {
   try {
     const parsed: unknown = JSON.parse(value);
@@ -256,9 +372,13 @@ function normalizeToolsField(value: string): unknown {
  * - task fields (`prompt`, `systemPrompt`, `tools`, ...) placed at the top
  *   level instead of inside a `tasks` entry — wrapped into a single task;
  * - `tools` as a JSON string (or bare token) inside a task entry;
- * - `agent: ""` inside a task entry — treated as omitted (ad-hoc).
- * Skipped when a ticket action is in play. All other invalid input is left
- * for normal schema validation to reject loudly.
+ * - `agent: ""` inside a task entry — treated as omitted (ad-hoc);
+ * - legacy `action` folded into `ticketAction` (top level) or `sessionAction`
+ *   (per task) for runtime compatibility.
+ * Skipped when a ticket action is in play. Conflicts between the legacy
+ * `action` field and its canonical replacement are left for
+ * `validateDelegateOperation` to report. All other invalid input is left for
+ * normal schema validation to reject loudly.
  *
  * Silent by design: these rewrites are lossless re-shaping, so unlike the
  * model-suffix warning in task-resolution (which fires because thinking
@@ -275,11 +395,26 @@ export function normalizeDelegateArguments(args: unknown): DelegateArguments {
     if (parsed) record.tasks = parsed;
   }
 
+  // Legacy top-level `action` (ticket verb) → canonical `ticketAction`.
+  // If both are present, leave the conflict for validateDelegateOperation.
+  if (
+    typeof record.action === "string" &&
+    ["poll", "cancel", "wait"].includes(record.action)
+  ) {
+    if (record.ticketAction === undefined) {
+      record.ticketAction = record.action;
+      delete record.action;
+    }
+  }
+
   // Flat task fields at the top level → wrap into a single task. Only fires
   // when there is no usable tasks array and no ticket action (`ticket`,
   // poll/cancel/wait) — those calls are legitimately taskless.
   const hasTasks = Array.isArray(record.tasks) && record.tasks.length > 0;
   const isTicketAction =
+    record.ticketAction === "poll" ||
+    record.ticketAction === "cancel" ||
+    record.ticketAction === "wait" ||
     record.action === "poll" ||
     record.action === "cancel" ||
     record.action === "wait";
@@ -291,28 +426,50 @@ export function normalizeDelegateArguments(args: unknown): DelegateArguments {
         delete record[key];
       }
     }
+    // Canonical `sessionAction` at the top level folds into the wrapped task.
+    if (typeof record.sessionAction === "string") {
+      if (task.sessionAction === undefined) {
+        task.sessionAction = record.sessionAction;
+      }
+      delete record.sessionAction;
+    }
+    // Legacy top-level session `action` folds into the wrapped task's
+    // `sessionAction`. A conflict with an explicit `sessionAction` is left
+    // for validateDelegateOperation to report.
     if (typeof record.action === "string" && TASK_ACTIONS.has(record.action)) {
-      task.action = record.action;
+      if (task.sessionAction === undefined) {
+        task.sessionAction = record.action;
+      } else {
+        task.action = record.action;
+      }
       delete record.action;
     }
     if (Object.keys(task).length > 0) record.tasks = [task];
   }
 
   // Per-entry recovery: stringified (or bare-token) `tools` → real arrays,
-  // and `agent: ""` → omitted (models emit an empty string to mean "ad-hoc";
-  // without this it only works by truthiness accident downstream).
+  // `agent: ""` → omitted, and legacy `action` → `sessionAction`.
   if (Array.isArray(record.tasks)) {
     record.tasks = record.tasks.map((entry: unknown) => {
       if (!entry || typeof entry !== "object") return entry;
       const e = entry as Record<string, unknown>;
       const rawTools = e.tools;
       const fixAgent = e.agent === "";
-      if (typeof rawTools !== "string" && !fixAgent) return entry;
+      const needsActionNorm =
+        typeof e.action === "string" &&
+        TASK_ACTIONS.has(e.action) &&
+        e.sessionAction === undefined;
+      if (typeof rawTools !== "string" && !fixAgent && !needsActionNorm)
+        return entry;
       const out = { ...e };
       if (typeof rawTools === "string") {
         out.tools = normalizeToolsField(rawTools);
       }
       if (fixAgent) delete out.agent;
+      if (needsActionNorm) {
+        out.sessionAction = out.action;
+        delete out.action;
+      }
       return out;
     });
   }

package/status.ts

@@ -13,7 +13,12 @@
  *    active ticket — the moment a user is most likely to assume everything
  *    is done and close the session.
  * 3. A confirm guard on the session-replacement paths pi lets extensions
- *    cancel (`session_before_switch`, `session_before_fork`).
+ *    cancel (`session_before_switch`, `session_before_fork`), plus a distinct
+ *    prompt for `/tree` navigation, which re-targets results rather than
+ *    killing them (see `guardTreeNavigation`).
+ * 4. A notification when a ticket completes after the session navigated away
+ *    from its spawn leaf: delivery is downgraded to non-waking, so without
+ *    this the human gets no signal that the ticket finished at all.
  *
  * Quit (Ctrl+C×2 / Ctrl+D / /quit) and /reload CANNOT be intercepted from an
  * extension — `session_shutdown` is advisory, not cancellable. The footer
@@ -21,7 +26,7 @@
  * there.
  */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { ticketRegistry } from "./tickets.ts";
+import { requestTicketCancel, ticketRegistry } from "./tickets.ts";
 import type { AsyncTicket } from "./types.ts";
 
 const STATUS_KEY = "delegate";
@@ -178,6 +183,67 @@ export async function guardSessionReplacement(
   return proceed ? undefined : { cancel: true };
 }
 
+/** `/tree` navigation is not a session replacement: the runtime survives and
+ *  the subagents keep running, but the eventual result no longer belongs to
+ *  the branch the user is on. Offer the three honest outcomes instead of the
+ *  destructive switch/fork confirm. Dismissal keeps the user where they are —
+ *  the conservative choice, since navigating is what creates the hazard.
+ *
+ *  This guard is UX, not the correctness mechanism: navigation that never
+ *  reaches it (dismissed dialog, headless ctx, `ctx.navigateTree` from another
+ *  extension) is still handled at delivery time via leaf affinity. */
+export async function guardTreeNavigation(
+  ctx: ExtensionContext,
+): Promise<{ cancel: true } | undefined> {
+  lastCtx = ctx;
+  const summary = activeTicketSummary();
+  if (!summary.tickets.length || !ctx.hasUI) return undefined;
+
+  const ids = summary.tickets.map((t) => t.id).join(", ");
+  const hold = "Navigate — hold results (poll to read them)";
+  const cancel = "Navigate — cancel the background subagents";
+  const stay = "Stay on this branch";
+  let choice: string | undefined;
+  try {
+    choice = await ctx.ui.select(
+      `${plural(summary.activeSubagents, "background subagent")} (${ids}) still running — ` +
+        "navigating means their results arrive on a different branch",
+      [hold, cancel, stay],
+    );
+  } catch {
+    // pi does not surface handler rejections, so a throwing dialog (stale ctx,
+    // TUI failure) would become an unhandled rejection. Let the navigation
+    // through rather than trapping the user: leaf affinity at delivery time is
+    // the correctness mechanism, not this prompt.
+    return undefined;
+  }
+
+  if (choice === hold) return undefined;
+  if (choice === cancel) {
+    for (const ticket of summary.tickets) requestTicketCancel(ticket);
+    syncDelegateStatus(ctx);
+    return undefined;
+  }
+  return { cancel: true };
+}
+
+/** Tell the human a ticket landed on a branch they had left. Delivery used
+ *  `nextTurn` (no wake-up), so this notification and the pollable ticket are
+ *  the only signals that the work finished. */
+export function notifyCrossLeafDelivery(ticket: AsyncTicket): void {
+  if (!lastCtx) return;
+  try {
+    lastCtx.ui.notify(
+      `Ticket ${ticket.id} finished (${ticket.status}) on a branch you navigated away from — ` +
+        `results are held for your next message; read them with delegate poll.`,
+      "warning",
+    );
+  } catch {
+    lastCtx = undefined;
+    lastStatusText = undefined;
+  }
+}
+
 /** One-line description of live work for shutdown traces. */
 export function describeActiveTickets(
   summary: ActiveTicketSummary = activeTicketSummary(),