@bermudi/pi-delegate 0.1.18 → 0.1.19

package/render-branches.ts

@@ -523,7 +523,8 @@ export function renderFinalBranch(ctx: BranchCtx, h: RenderHelpers): void {
       const integration = r.integration;
       const tone =
         integration.status === "applied_unverified" ||
-        integration.status === "no_changes"
+        integration.status === "no_changes" ||
+        integration.status === "retained"
           ? "warning"
           : "error";
       lines.push(

package/render-result.ts

@@ -213,6 +213,12 @@ export function renderDelegateResult(
       lines.push(truncLine(theme.fg("warning", `⚠ ${warning}`), w), "");
     }
   }
+  if (details?.serializedNotice) {
+    const notice = sanitizeTerminalLine(details.serializedNotice);
+    if (notice) {
+      lines.push(truncLine(theme.fg("dim", `⏳ ${notice}`), w), "");
+    }
+  }
   if (details?.overlapWarning) {
     const warning = sanitizeTerminalLine(details.overlapWarning);
     if (warning) {

package/runtime.ts

@@ -0,0 +1,36 @@
+import { SessionPool, defaultSessionPool } from "./pool.ts";
+import { TicketRegistry, ticketRegistry } from "./tickets.ts";
+
+/**
+ * Injectable runtime context for one delegate extension lifetime.
+ *
+ * A runtime bundles a {@link SessionPool} and a {@link TicketRegistry} so
+ * tests and nested callers can create fully isolated dispatch/lifecycle
+ * environments without touching the module-level default pool or ticket
+ * registry. Production Pi uses the single default runtime returned by
+ * {@link getDefaultDelegateRuntime}; the public barrel still exposes the
+ * familiar checkout/commit/ticket wrapper functions for compatibility.
+ */
+export interface DelegateRuntime {
+  pool: SessionPool;
+  tickets: TicketRegistry;
+}
+
+/** Create a fresh, isolated runtime with its own pool and ticket registry. */
+export function createDelegateRuntime(): DelegateRuntime {
+  return {
+    pool: new SessionPool(),
+    tickets: new TicketRegistry(),
+  };
+}
+
+const defaultRuntime: DelegateRuntime = {
+  pool: defaultSessionPool,
+  tickets: ticketRegistry,
+};
+
+/** The runtime used by the one-argument Pi extension entry point and the
+ *  default-runtime compatibility wrappers exported from the barrel. */
+export function getDefaultDelegateRuntime(): DelegateRuntime {
+  return defaultRuntime;
+}

package/schema.ts

@@ -42,7 +42,7 @@ export const delegateTaskSchema = Type.Object({
   agent: Type.Optional(
     Type.String({
       description:
-        "default mirrors the parent's tools; scout/coder/reviewer specialists. Ad-hoc tasks get * tools even when the parent is narrower.",
+        "Use built-ins first: default=general; scout/coder/reviewer specialize. Omit only for inline; it gets * even if parent is narrower.",
     }),
   ),
   cwd: Type.Optional(
@@ -65,19 +65,20 @@ export const delegateTaskSchema = Type.Object({
   ),
   model: Type.Optional(
     Type.String({
-      description: "Model override; omit to inherit parent.",
+      description:
+        "Override only if requested or required; else keep its default.",
     }),
   ),
   tools: Type.Optional(
     Type.Array(Type.String(), {
       description:
-        "Names/presets: *=read/write/edit/bash (mutating); ro=read/grep/find/ls (read-only). Ad-hoc defaults to *.",
+        "Override only if requested or required. *=read/write/edit/bash; ro=read/grep/find/ls (read-only).",
     }),
   ),
   thinking: Type.Optional(
     StringEnum(VALID_THINKING_LEVELS, {
       description:
-        "off/minimal/low/medium/high/xhigh/max. Omit for agents — it overrides delegate.json tiers; default inherits.",
+        "off/minimal/low/medium/high/xhigh/max. Omit by default: overrides the agent's configured thinking budget.",
     }),
   ),
   sessionId: Type.Optional(
@@ -101,7 +102,7 @@ export const delegateTaskSchema = Type.Object({
   workspace: Type.Optional(
     StringEnum(["shared", "scratch", "isolated"], {
       description:
-        "shared edits source; scratch discards; isolated orders Git worktree proposals; none confine access.",
+        "shared/scratch/isolated. Override if requested or required. scratch discards; isolated reconciles Git; not a security boundary.",
     }),
   ),
 });
@@ -159,7 +160,7 @@ export const delegateArgumentsSchema = Type.Object(
       Type.Array(delegateTaskSchema, {
         minItems: 0,
         description:
-          "Tasks run concurrently; shared workspaces share files. scratch uses a disposable CoW copy. []=full manual.",
+          "Use built-in defaults first. Tasks run concurrently; overlapping shared writers run in task order. []=manual.",
       }),
     ),
   },
@@ -286,9 +287,21 @@ function validateTicketMode(params: DelegateArguments): string | undefined {
     [...TASK_FIELD_NAMES, "tasks", "sessionAction"] as const
   ).filter((field) => rawParams[field] !== undefined);
   if (incompatibleFields.length) {
-    return `ticket control cannot be combined with field(s) ${incompatibleFields
+    const base = `ticket control cannot be combined with field(s) ${incompatibleFields
       .map((field) => `'${field}'`)
       .join(", ")}; call it separately.`;
+    // Kitchen-sink callers attach default-shaped ticket control to a real
+    // dispatch and then repeat the identical rejected call (observed in the
+    // wild: glm-5.3 sent `ticketAction:"wait"` + tasks + empty ticket six
+    // times in a row). With tasks present and no ticket id, address the
+    // likely intent — dispatch already blocks; async creates the tickets
+    // that ticketAction manages — instead of restating the field rule.
+    const wantsDispatch =
+      Array.isArray(params.tasks) && params.tasks.length > 0 && !params.ticket;
+    if (wantsDispatch) {
+      return `${base} Dispatched tasks run to completion before returning — omit ticketAction entirely; only async:true produces a ticket to wait on.`;
+    }
+    return base;
   }
   if (params.async === true) {
     return "ticket control cannot include async; call it separately.";
@@ -327,10 +340,6 @@ function validateDispatchOrHelpMode(
       : undefined; // Intentional help request.
   }
 
-  if (params.async && tasks.some((task) => task.workspace === "isolated")) {
-    return 'workspace "isolated" is synchronous; remove async.';
-  }
-
   // 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 —
@@ -450,7 +459,7 @@ function wrapFlatTaskFields(record: Record<string, unknown>): void {
 }
 
 /** Per-entry recovery for one task: stringified (or bare-token) `tools` → a
- * real array, and `agent: ""` → omitted (ad-hoc). Other malformed input is
+ * real array, and `agent: ""` → omitted (inline). Other malformed input is
  * left for schema validation to reject loudly. */
 function normalizeTaskEntry(entry: unknown): unknown {
   if (!entry || typeof entry !== "object") return entry;
@@ -476,7 +485,7 @@ function normalizeTaskEntry(entry: unknown): unknown {
  *   unless ticket- or session-control intent makes the call legitimately
  *   taskless (see `hasTicketControlIntent` / `hasSessionControlIntent`);
  * - `tools` as a JSON string (or bare token) inside a task entry;
- * - `agent: ""` inside a task entry — treated as omitted (ad-hoc);
+ * - `agent: ""` inside a task entry — treated as omitted (inline);
  * All other invalid input is left for normal schema validation to reject
  * loudly.
  *

package/status.ts

@@ -26,7 +26,7 @@
  * there.
  */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { requestTicketCancel, ticketRegistry } from "./tickets.ts";
+import { getDefaultDelegateRuntime, type DelegateRuntime } from "./runtime.ts";
 import type { AsyncTicket } from "./types.ts";
 
 const STATUS_KEY = "delegate";
@@ -39,10 +39,12 @@ export interface ActiveTicketSummary {
 }
 
 /** Snapshot the live background work from the ticket registry. */
-export function activeTicketSummary(): ActiveTicketSummary {
+export function activeTicketSummary(
+  runtime: DelegateRuntime = getDefaultDelegateRuntime(),
+): ActiveTicketSummary {
   const tickets: AsyncTicket[] = [];
   let activeSubagents = 0;
-  for (const ticket of ticketRegistry.values()) {
+  for (const ticket of runtime.tickets.values()) {
     if (ticket.status !== "running" && ticket.status !== "cancelling") continue;
     tickets.push(ticket);
     activeSubagents += ticket.progress.filter(
@@ -88,10 +90,13 @@ const settledWarnedTicketIds = new Set<string>();
  *  Called on every ticket lifecycle mutation (create, progress, complete,
  *  cancel); event-driven only — no timers, so the text never goes stale
  *  (counts are the only content). */
-export function syncDelegateStatus(ctx?: ExtensionContext): void {
+export function syncDelegateStatus(
+  ctx?: ExtensionContext,
+  runtime?: DelegateRuntime,
+): void {
   if (ctx) lastCtx = ctx;
 
-  const summary = activeTicketSummary();
+  const summary = activeTicketSummary(runtime);
   const text = buildStatusText(summary);
 
   if (settledWarnedTicketIds.size) {
@@ -127,9 +132,12 @@ export function clearDelegateStatusContext(): void {
 /** Warn once per ticket at the first agent_settled with that ticket active —
  *  the "looks idle but isn't" moment. The persistent footer status carries
  *  the information from then on, so later settles stay quiet. */
-export function notifyActiveTicketsOnSettled(ctx: ExtensionContext): void {
+export function notifyActiveTicketsOnSettled(
+  ctx: ExtensionContext,
+  runtime?: DelegateRuntime,
+): void {
   lastCtx = ctx;
-  const summary = activeTicketSummary();
+  const summary = activeTicketSummary(runtime);
   const fresh = summary.tickets.filter(
     (t) => !settledWarnedTicketIds.has(t.id),
   );
@@ -167,9 +175,10 @@ export function notifyActiveTicketsOnSettled(ctx: ExtensionContext): void {
 export async function guardSessionReplacement(
   ctx: ExtensionContext,
   action: "switch" | "fork",
+  runtime?: DelegateRuntime,
 ): Promise<{ cancel: true } | undefined> {
   lastCtx = ctx;
-  const summary = activeTicketSummary();
+  const summary = activeTicketSummary(runtime);
   if (!summary.tickets.length || !ctx.hasUI) return undefined;
 
   const ids = summary.tickets.map((t) => t.id).join(", ");
@@ -194,9 +203,11 @@ export async function guardSessionReplacement(
  *  extension) is still handled at delivery time via leaf affinity. */
 export async function guardTreeNavigation(
   ctx: ExtensionContext,
+  runtime?: DelegateRuntime,
 ): Promise<{ cancel: true } | undefined> {
   lastCtx = ctx;
-  const summary = activeTicketSummary();
+  const rt = runtime ?? getDefaultDelegateRuntime();
+  const summary = activeTicketSummary(rt);
   if (!summary.tickets.length || !ctx.hasUI) return undefined;
 
   const ids = summary.tickets.map((t) => t.id).join(", ");
@@ -220,8 +231,10 @@ export async function guardTreeNavigation(
 
   if (choice === hold) return undefined;
   if (choice === cancel) {
-    for (const ticket of summary.tickets) requestTicketCancel(ticket);
-    syncDelegateStatus(ctx);
+    for (const ticket of summary.tickets) {
+      rt.tickets.requestTicketCancel(ticket);
+    }
+    syncDelegateStatus(ctx, rt);
     return undefined;
   }
   return { cancel: true };

package/task-resolution.ts

@@ -12,8 +12,7 @@ import {
   availableToolNames,
   resolveToolGroups,
 } from "./tools.ts";
-import { configFor } from "./pool.ts";
-import { isSessionBusy } from "./tickets.ts";
+import { getDefaultDelegateRuntime, type DelegateRuntime } from "./runtime.ts";
 import {
   isResumeFromQuarantined,
   isSessionIdQuarantined,
@@ -115,6 +114,7 @@ export function validateTasks(
   tasks: DispatchableTask[],
   agents: Map<string, AgentConfig>,
   parentModelId: string | undefined,
+  runtime: DelegateRuntime = getDefaultDelegateRuntime(),
 ): DelegateToolResult | null {
   const unknown: string[] = [];
   for (const task of tasks) {
@@ -203,7 +203,7 @@ export function validateTasks(
   // Disallow sessionIds already claimed by a running async ticket.
   const busyConflicts: string[] = [];
   for (const sid of sessionIds) {
-    const owner = isSessionBusy(sid);
+    const owner = runtime.tickets.isSessionBusy(sid);
     if (owner) busyConflicts.push(`${sid} (ticket ${owner})`);
   }
   if (busyConflicts.length) {
@@ -247,6 +247,7 @@ export function resolveTasks(
   agents: Map<string, AgentConfig>,
   parentDefaults: ParentAgentDefaults,
   dispatchConfig: DelegateConfig = getDelegateConfigSnapshot(),
+  runtime: DelegateRuntime = getDefaultDelegateRuntime(),
 ): ResolveTasksResult {
   // Build parent transcript lazily — only computed once if any task uses with-parent-transcript
   let parentTranscript: string | null = null;
@@ -302,10 +303,12 @@ export function resolveTasks(
         : undefined;
 
     // Build system prompt. Explicit task prompts and named agent prompts
-    // win; ad-hoc subagents inherit the parent's base prompt when Pi exposes
+    // win; inline subagents inherit the parent's base prompt when Pi exposes
     // it. The assembled parent project-context section was stripped above;
     // the child ResourceLoader supplies context for this task's cwd.
-    const pooledConfig = t.sessionId ? configFor(t.sessionId) : undefined;
+    const pooledConfig = t.sessionId
+      ? runtime.pool.configFor(t.sessionId)
+      : undefined;
     const isPoolHit = pooledConfig !== undefined;
     const parentNativeTools = parentDefaults.tools.filter((name) =>
       Object.hasOwn(TOOL_FACTORIES, name),
@@ -625,12 +628,12 @@ export function resolveTasks(
       // display code treats "" and absent alike (`t.prompt || …`).
       prompt: prompt ?? "",
       // Keep the built-in selector visible in progress/results. Omitted-agent
-      // inline tasks retain the established `ad-hoc` label and config namespace
-      // — except resumes: a continued transcript is not a fresh ad-hoc spawn,
-      // so it carries the resumed-transcript identity instead.
+      // tasks use the `inline` label and config namespace — except resumes: a
+      // continued transcript is not a fresh inline spawn, so it carries the
+      // resumed-transcript identity instead.
       agentName:
         agent?.name ??
-        (resumeFromDisplay ? `resume:${resumeFromDisplay}` : "ad-hoc"),
+        (resumeFromDisplay ? `resume:${resumeFromDisplay}` : "inline"),
       resumeFromDisplay,
       warnings,
       reuseIntent: {

package/test-harness.ts

@@ -0,0 +1,81 @@
+import {
+  createTestSession,
+  type TestSession,
+  type TestSessionOptions,
+} from "@marcfargas/pi-test-harness";
+import type {
+  AgentSession,
+  AgentToolResult,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+import type { DelegateDetails, TaskResult } from "./types.ts";
+import { resolve } from "node:path";
+
+export const DELEGATE_EXTENSION = resolve(import.meta.dirname, "./delegate.ts");
+
+export { type TestSession };
+
+export function createDelegateTestSession(
+  options: TestSessionOptions = {},
+): Promise<TestSession> {
+  return createTestSession({
+    ...options,
+    extensions: [...(options.extensions ?? []), DELEGATE_EXTENSION],
+  });
+}
+
+export interface TestToolDefinition {
+  name: string;
+  label: string;
+  description: string;
+  promptSnippet?: string;
+  promptGuidelines?: string[];
+  parameters: unknown;
+  prepareArguments?: (args: unknown) => unknown;
+  execute(...args: unknown[]): Promise<AgentToolResult<DelegateDetails>>;
+  renderCall: (...args: unknown[]) => Component;
+  renderResult: (...args: unknown[]) => Component;
+}
+
+export function getToolDef(ts: TestSession, name: string): TestToolDefinition {
+  const tool = (ts.session as AgentSession).extensionRunner.getToolDefinition(
+    name,
+  );
+  if (!tool) throw new Error(`${name} tool not found`);
+  return tool as unknown as TestToolDefinition;
+}
+
+export function getDelegateTool(ts: TestSession): TestToolDefinition {
+  return getToolDef(ts, "delegate");
+}
+
+export function getExecContext(ts: TestSession): ExtensionContext {
+  return (ts.session as AgentSession).extensionRunner.createContext();
+}
+
+export function firstText(result: { content: readonly unknown[] }): string {
+  const content = result.content[0];
+  if (
+    !content ||
+    typeof content !== "object" ||
+    !("type" in content) ||
+    content.type !== "text" ||
+    !("text" in content) ||
+    typeof content.text !== "string"
+  ) {
+    throw new Error("Expected first tool result content item to be text");
+  }
+  return content.text;
+}
+
+export function taskResultAt(
+  results: readonly (TaskResult | { error: string })[],
+  index: number,
+): TaskResult {
+  const result = results[index];
+  if (!result || !("agent" in result)) {
+    throw new Error(`Expected task result at index ${index}`);
+  }
+  return result;
+}

package/ticket-format.ts

@@ -246,15 +246,16 @@ export function formatLiveTicketPoll(
     findTouchedOverlaps(completedForOverlap),
   );
   const guidance = liveTicketGuidance(ticket);
+  const serializedNotice = ticket.serializedNotice ?? "";
   const dispatchWarning = ticket.dispatchWarning
     ? `WARNING: ${ticket.dispatchWarning}`
     : "";
   return {
     text: `${formatLiveTicketHeader(ticket, now)}\n${lines.join("\n")}${
       guidance ? `\n\n${guidance}` : ""
-    }${dispatchWarning ? `\n\n${dispatchWarning}` : ""}${
-      overlapWarning ? `\n\n${overlapWarning}` : ""
-    }`,
+    }${serializedNotice ? `\n\n${serializedNotice}` : ""}${
+      dispatchWarning ? `\n\n${dispatchWarning}` : ""
+    }${overlapWarning ? `\n\n${overlapWarning}` : ""}`,
     completedResults,
     overlapWarning,
   };