@bermudi/pi-delegate 0.1.15 → 0.1.17

package/agents.ts

@@ -120,7 +120,7 @@ export const BUILTIN_AGENT_CONFIGS: Readonly<Record<string, AgentConfig>> = {
   [DEFAULT_AGENT_NAME]: {
     name: DEFAULT_AGENT_NAME,
     description:
-      "Mirror the live parent model, thinking level, native tools, and base prompt.",
+      "General-purpose subagent mirroring the live parent model, thinking level, native tools, and base prompt. Prefer it for general work; pick a specialist only when its role, tool limits, or scratch workspace genuinely fit.",
     tools: DEFAULT_TOOLS,
     systemPrompt: "",
     builtin: true,
@@ -151,7 +151,7 @@ export const BUILTIN_AGENT_CONFIGS: Readonly<Record<string, AgentConfig>> = {
     systemPrompt:
       "Review the current snapshot for correctness, regressions, security problems, and missing tests. Do not modify the source project. Run focused checks when useful. Report actionable findings ordered by severity, with concrete paths and locations. If there are no material findings, say so plainly; do not invent issues or merely summarize the implementation.",
     builtin: true,
-    workspace: "scratch",
+    workspace: "shared",
   },
 };
 

package/constants.ts

@@ -59,3 +59,13 @@ export const VALID_THINKING_LEVELS = [
  *  `Set<VALID_THINKING_LEVELS[number]>`) so the `.has(string)` call sites in
  *  task-resolution.ts and agents.ts stay ergonomic under strict typing. */
 export const VALID_THINKING: Set<string> = new Set(VALID_THINKING_LEVELS);
+
+/** Session-control actions: RPC against the session pool, not work. Callers
+ *  spell them at the TOP level (`sessionAction`, one action per call — #32).
+ *  This predicate remains the one shared spelling of the control set for the
+ *  session-mode intent check and validator in schema.ts and the pipeline
+ *  guards over internally bridged tasks (task-resolution.ts). Per-action
+ *  behavior lives at the branch sites (e.g. lifecycle applySessionAction). */
+export function isSessionControlAction(action: unknown): boolean {
+  return action === "close" || action === "list";
+}

package/delegate.ts

@@ -3,6 +3,7 @@ export { default } from "./extension.ts";
 export type {
   AgentConfig,
   SessionAction,
+  DispatchableTask,
   WorkspaceMode,
   TicketAction,
   DelegateArguments,

package/dispatch.ts

@@ -48,6 +48,7 @@ import type {
   DelegateToolResult,
   ParentAgentDefaults,
   ResolvedTask,
+  DispatchableTask,
   TaskDef,
   TaskProgress,
   TaskResult,
@@ -58,7 +59,7 @@ const UNSAFE_SHARED_WRITES_WARNING =
   "UNSAFE SHARED WRITES ENABLED: shared-write admission is bypassed. Delegate provides no isolation or rollback.";
 
 interface ActiveSyncDispatch {
-  tasks: TaskDef[];
+  tasks: DispatchableTask[];
   resolved: ResolvedTask[];
 }
 
@@ -157,7 +158,7 @@ export function makeFireUpdater(
 export interface AsyncDispatchInput {
   pi: ExtensionAPI;
   ctx: DelegateToolCtx;
-  tasks: TaskDef[];
+  tasks: DispatchableTask[];
   resolved: ResolvedTask[];
   progress: TaskProgress[];
   parentModelId: string | undefined;
@@ -169,7 +170,7 @@ export interface AsyncDispatchInput {
 /** Inputs needed by the sync (blocking) dispatch path. */
 export interface SyncDispatchInput {
   ctx: DelegateToolCtx;
-  tasks: TaskDef[];
+  tasks: DispatchableTask[];
   resolved: ResolvedTask[];
   progress: TaskProgress[];
   parentModelId: string | undefined;
@@ -193,7 +194,7 @@ export interface DelegateDispatchInput {
   callSpan?: CallSpan;
 }
 
-function taskReference(task: TaskDef, index: number): string {
+function taskReference(task: DispatchableTask, index: number): string {
   return `Task ${index + 1}${task.id ? `#${task.id}` : ""}`;
 }
 
@@ -207,7 +208,7 @@ function asAdmissionWriter(task: ResolvedTask): ResolvedTask {
 }
 
 function sharedWriteRejection(
-  tasks: TaskDef[],
+  tasks: DispatchableTask[],
   parentModelId: string | undefined,
   conflicts: SharedWriteConflict[],
   references: readonly string[] = tasks.map(taskReference),
@@ -236,7 +237,7 @@ function sharedWriteRejection(
 }
 
 function sharedWriteSafetyFailure(
-  tasks: TaskDef[],
+  tasks: DispatchableTask[],
   parentModelId: string | undefined,
   error: unknown,
 ): DelegateToolResult {
@@ -289,13 +290,26 @@ export async function dispatchDelegate(
     return validationError;
   }
 
-  const resolved = resolveTasks(
+  const resolveResult = resolveTasks(
     tasks,
     ctx,
     agents,
     parentDefaults,
     dispatchConfig,
   );
+  if (resolveResult.error !== undefined) {
+    callSpan?.finish({
+      status: "failed",
+      totalTokens: 0,
+      totalCost: 0,
+      wallMs: Date.now() - callSpan.startedAt,
+    });
+    return {
+      content: [{ type: "text", text: resolveResult.error }],
+      details: { tasks, results: [], progress: [], parentModel: parentModelId },
+    };
+  }
+  const resolved = resolveResult.tasks;
   if (params.async && resolved.some((task) => task.workspace === "isolated")) {
     callSpan?.finish({
       status: "failed",

package/extension.ts

@@ -44,7 +44,11 @@ import {
   prepareTelemetryForSession,
   sealTelemetryWrites,
 } from "./telemetry.ts";
-import type { DelegateArguments, DelegateDetails } from "./types.ts";
+import type {
+  DelegateArguments,
+  DelegateDetails,
+  DispatchableTask,
+} from "./types.ts";
 
 const DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS = 10_000;
 let shutdownDrainTimeoutMs = DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS;
@@ -52,6 +56,21 @@ let shutdownDrainTimeoutMs = DEFAULT_SHUTDOWN_DRAIN_TIMEOUT_MS;
 type ShutdownDrainResult =
   { drained: true; failures: unknown[] } | { drained: false; failures: [] };
 
+/** Bridge the promoted top-level session RPC (`sessionAction` + `sessionId`)
+ * to the internal single-entry batch the runner executes. Internal only — the
+ * public task schema has no `sessionAction`; validation guarantees close
+ * carries a sessionId by this point. `list` never carries a sessionId: it does
+ * not target a specific session, and attaching one would make validateTasks
+ * run busy/quarantine checks that can fail the list call. */
+function bridgeSessionControlTask(params: DelegateArguments): DispatchableTask {
+  return {
+    ...(params.sessionAction === "close" && params.sessionId
+      ? { sessionId: params.sessionId }
+      : {}),
+    sessionAction: params.sessionAction,
+  };
+}
+
 /** Wait for shutdown workers without allowing a stuck provider/tool to hold
  * Pi's reload or exit hostage. The allSettled promise is intentionally left
  * attached after timeout so a late rejection cannot become unhandled. */
@@ -160,6 +179,11 @@ export default function delegateExtension(pi: ExtensionAPI): void {
       let mode: string;
       if (params.ticketAction) {
         mode = params.ticketAction;
+      } else if (params.sessionAction) {
+        // Session RPC is its own mode, not a task shape — label it before the
+        // tasks-based branches so close/list spans stop misreporting as
+        // "sync" with a zero task count.
+        mode = "session";
       } else if (tasks.length === 0) {
         mode = "manual";
       } else if (params.async) {
@@ -173,6 +197,7 @@ export default function delegateExtension(pi: ExtensionAPI): void {
         mode,
         taskCount,
         parentSessionFile,
+        parentCwd: ctx.cwd,
       });
 
       function failCall(): void {
@@ -246,6 +271,35 @@ export default function delegateExtension(pi: ExtensionAPI): void {
       // silently swap the agent roster.
       const agents = discoverAgents(ctx.cwd);
 
+      // ── Session RPC (top-level sessionAction, #32 promotion) ─────────
+      // Session control is no longer spelled as a task, but it still runs
+      // through the one runner: bridge it to an internal single-entry batch so
+      // busy-index validation, per-session locking (lifecycle's literal
+      // per-action branches), progress rows, and result formatting all keep
+      // their existing behavior. Never async — validation rejects that.
+      // Must precede the help short-circuit: session RPC carries no tasks and
+      // must not be mistaken for an empty help request.
+      if (params.sessionAction) {
+        invalidateHostDepsCache();
+        // Keep the footer-status pipeline in step exactly as a normal
+        // dispatch would (deduped no-op when nothing is running).
+        syncDelegateStatus(ctx);
+        return await dispatchDelegate({
+          pi,
+          params: { ...params, tasks: [bridgeSessionControlTask(params)] },
+          ctx,
+          agents,
+          parentModelId,
+          parentDefaults: {
+            thinking: pi.getThinkingLevel(),
+            tools: pi.getActiveTools(),
+          },
+          signal,
+          onUpdate,
+          callSpan,
+        });
+      }
+
       // ── Help mode ─────────────────────────────────────────────────
       if (!tasks.length) {
         succeedCall();

package/lifecycle.ts

@@ -142,9 +142,18 @@ function scratchSetupFailureResult(
   if (signalAborted) {
     message = "Aborted";
     failureKind = "cancelled";
-  } else if (error instanceof ScratchDeadlineError) {
-    message = formatDeadlineExceededError(task.deadlineMs ?? 0);
-    failureKind = "deadline_exceeded";
+  } else {
+    if (error instanceof ScratchDeadlineError) {
+      message = formatDeadlineExceededError(task.deadlineMs ?? 0);
+      failureKind = "deadline_exceeded";
+    }
+    // Every non-aborted setup failure names its remedy in one place, so the
+    // paths (platform guard, pre-check, reflink, worktree, deadline) cannot
+    // drift. The symlink message already carries remedy text naming
+    // workspace "shared" — skip the append there to avoid saying it twice.
+    if (!message.includes('workspace "shared"')) {
+      message = `${message} — to retry without scratch containment, use workspace: "shared".`;
+    }
   }
   return {
     ...failTask(task, message, undefined, failureKind),
@@ -433,9 +442,10 @@ function recordTaskOutcome(
  *  that model, so same-model retry is pointless. Distinguished from a bare
  *  transient 429 (per-minute rate limit) by the *account-level* wording:
  *  "usage limit", "quota", "upgrade for higher limits", "exceeded your
- *  … quota", or an auth/credential failure (401/403 with word boundaries so a
- *  port like 4019 doesn't false-positive). The parent should resume with a
- *  different `model` (see `resumeFrom` + `model`). */
+ *  … quota", an auth/credential failure (401/403 with word boundaries so a
+ *  port like 4019 doesn't false-positive), or an invalidated OAuth token
+ *  ("invalid"/"invalidated" anywhere alongside "oauth token"). The parent
+ *  should resume with a different `model` (see `resumeFrom` + `model`). */
 export function isModelAttributableError(error: string | undefined): boolean {
   if (!error) return false;
   const e = error.toLowerCase();
@@ -454,6 +464,7 @@ export function isModelAttributableError(error: string | undefined): boolean {
     e.includes("authentication") ||
     e.includes("invalid api key") ||
     (e.includes("api key") && e.includes("invalid")) ||
+    (e.includes("oauth token") && e.includes("invalid")) ||
     /\b401\b/.test(e) ||
     /\b403\b/.test(e)
   );

package/manual.ts

@@ -138,6 +138,8 @@ export function getSubagentManualMarkdown(
     "",
     ...builtinLines,
     "",
+    "Prefer `default` for general work: it is the only built-in guaranteed to run the parent's exact model and thinking. `scout`/`coder`/`reviewer` apply any configured delegate.json tiers (`agentOverrides`, `agentOverridesByParentModel`) and may run a different model or thinking level than the parent. `scout` is read-only, and `reviewer` runs in a disposable scratch workspace — its writes are discarded by design. Choose a specialist for its role, not its name.",
+    "",
     "Fresh built-ins inherit the parent's exact model object and thinking level. A same-named Markdown file can override any built-in (first definition wins); an explicit `model` or `thinking` in that file replaces parent inheritance. Task-level `model`/`thinking`/`tools` always win. For `scout`/`coder`/`reviewer`, delegate.json overrides (`agentOverrides`, `agentOverridesByParentModel`) win over the Markdown file; `default` ignores overrides and uses only an explicit Markdown `model`/`thinking` when present. A prompt-only Markdown override keeps the built-in's tools and workspace, so `scout` stays read-only and `reviewer` stays scratch unless the file explicitly changes them. Parent extension/MCP tools are not copied. Parent-global `AGENTS.md` instructions are also excluded. Project-local context and skills are rebuilt for the task's `cwd`; per-task fields remain explicit overrides.",
     "",
     "## Available Custom Agents",
@@ -177,10 +179,10 @@ export function getSubagentManualMarkdown(
     'delegate({ tasks: [{ prompt: "Now check the tests for that module", sessionId: "auth-research" }] })',
     "",
     "// Clean up when done",
-    'delegate({ tasks: [{ sessionId: "auth-research", sessionAction: "close" }] })',
+    'delegate({ sessionAction: "close", sessionId: "auth-research" })',
     "```",
     "",
-    'Pooled sessions remain live until `sessionAction: "close"` or parent Pi session shutdown.',
+    'Pooled sessions remain live until a top-level `sessionAction: "close"` or parent Pi session shutdown.',
     "",
     "## Resuming Previous Sessions",
     "",
@@ -239,7 +241,7 @@ export function getSubagentManualMarkdown(
     '- Shared writers that overlap tasks in the same call or a running sync/async dispatch are rejected. Unknown tools count as mutating. Run them sequentially, use `workspace: "isolated"` for Git-backed ordered reconciliation, or use `workspace: "scratch"` when changes may be discarded.',
     "- `*` means read/write/edit/bash, not every tool. `grep`, `find`, and `ls` are valid explicit tools and are the `ro` preset.",
     '- `tasks` is an array. The tool recovers common stringified calls for compatibility, but canonical calls use `{ tasks: [{ prompt: "..." }] }`.',
-    '- Use `agent: "default"` for the parent\'s live model/thinking/native tools/base prompt. Built-ins are `default`, `scout`, `coder`, and `reviewer`; omitting `agent` creates an ad-hoc task.',
+    '- Prefer `agent: "default"` — the parent\'s live model/thinking/native tools/base prompt — for general tasks. Pick `scout`/`coder`/`reviewer` only when the role, tool limits, or scratch workspace fit; they follow delegate.json tiers and may not run the parent model. Omitting `agent` creates an ad-hoc task (parent model, full tools).',
     "- Omit `thinking` for named agents unless the user asks or the task clearly needs escalation — task-level `thinking` overrides every configured tier (`agentOverrides`, `agentOverridesByParentModel`, Markdown frontmatter, `:level` model suffix), so a casual value silently defeats the configured budget. Ad-hoc tasks default to the parent's thinking.",
     "- An ad-hoc task with no `tools` uses `*`; a named custom task uses its profile; a profile with no tools uses `*`.",
     "- Subagents inherit all skills discovered in their `cwd` (via AgentSession's resource loader). Per-task skill filtering is not supported — curate the cwd's skill set instead.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bermudi/pi-delegate",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Delegate tool for the Pi coding agent.",
   "keywords": [
     "pi-package"

package/render-branches.ts

@@ -470,7 +470,8 @@ export function renderFinalBranch(ctx: BranchCtx, h: RenderHelpers): void {
       );
     }
 
-    // Warnings (e.g. unknown tools ignored) — muted line under the task.
+    // Warnings (e.g. scratch-workspace notices, ignored model suffix) — muted
+    // line under the task.
     pushWarnings(p, ind);
 
     // Tool activities: compact summary only in expanded mode, terminal tasks only.