@bermudi/pi-delegate 0.1.0

package/manual.ts

@@ -0,0 +1,184 @@
+import {
+  DEFAULT_TOOLS,
+  OUTPUT_SPILL_THRESHOLD_CHARS,
+  OUTPUT_SPILL_TAIL_CHARS,
+} from "./constants.ts";
+import { getMaxAsyncTickets, getMaxConcurrent } from "./config.ts";
+import type { TSchema } from "@sinclair/typebox";
+import { delegateArgumentsSchema, delegateTaskSchema } from "./schema.ts";
+import type { AgentConfig } from "./types.ts";
+
+function schemaType(schema: TSchema): string {
+  if (Array.isArray(schema.enum)) {
+    return schema.enum.map((value) => JSON.stringify(value)).join(" | ");
+  }
+  if (schema.type === "array") return `${schemaType(schema.items)}[]`;
+  return typeof schema.type === "string" ? schema.type : "unknown";
+}
+
+function markdownCell(value: string): string {
+  return value.replaceAll("|", "\\|").replaceAll("\n", " ");
+}
+
+function schemaTable(properties: Record<string, TSchema>): string {
+  const rows = Object.entries(properties).map(([name, schema]) => {
+    const type = markdownCell(schemaType(schema));
+    const defaultValue =
+      "default" in schema ? JSON.stringify(schema.default) : "—";
+    const description = markdownCell(schema.description ?? "");
+    return `| \`${name}\` | \`${type}\` | \`${defaultValue}\` | ${description} |`;
+  });
+  return [
+    "| Field | Type | Default | Description |",
+    "| --- | --- | --- | --- |",
+    ...rows,
+  ].join("\n");
+}
+
+/** Render the current schema and discovered agents as model-facing help. */
+export function getSubagentManualMarkdown(
+  agents: Map<string, AgentConfig>,
+): string {
+  const entries = [...agents];
+  const agentList = entries.length
+    ? entries
+        .map(([n, a]) => {
+          const model = a.model ? ` (model: ${a.model})` : "";
+          const thinking =
+            a.thinking !== "off" ? ` [thinking: ${a.thinking}]` : "";
+          const tools =
+            a.tools.length !== DEFAULT_TOOLS.length ||
+            a.tools.some((t, i) => t !== DEFAULT_TOOLS[i])
+              ? ` tools: ${a.tools.join(", ")}`
+              : "";
+          const scope =
+            a.scope === "project"
+              ? " [project]"
+              : a.scope === "global"
+                ? " [global]"
+                : a.scope === "claude"
+                  ? " [claude]"
+                  : "";
+          return `- **${n}**${model}${thinking}${tools}${scope}: ${a.description}`;
+        })
+        .join("\n")
+    : "_(none defined)_";
+
+  return [
+    "# Delegate Tool Manual",
+    "",
+    "**Why you're seeing this:** no tasks were provided, so the tool returned help instead of dispatching. Nothing is broken. To dispatch subagents, put task fields inside `tasks: [{ ... }]`.",
+    "",
+    "```ts",
+    'delegate({ tasks: [{ prompt: "Investigate the auth module" }] })',
+    "```",
+    "",
+    "Delegate subagents to execute tasks in parallel. Each subagent gets an independent context, system prompt, model, tools, and thinking level. Custom agents can be defined inline in a task or persisted as Markdown files.",
+    "",
+    "## Available Custom Agents",
+    "",
+    agentList,
+    "",
+    "Custom agents are defined either inline in a task (using `systemPrompt`, `tools`, and `thinking`) or persisted as Markdown files in `.pi/agents/*.md` (project-local), `~/.pi/agent/agents/` (global), and `.claude/agents/` (interchange with Claude Code). Markdown agents are examples of custom agents — the parent model can shape the subagent it needs on each call. Each Markdown file is an agent with YAML frontmatter:",
+    "",
+    "```markdown",
+    "---",
+    "name: my-agent",
+    "description: What it does",
+    "thinking: low                     # off/minimal/low/medium/high/xhigh/max",
+    "tools: *                          # * = full agent. ro = read-only. Omit to inherit *.",
+    "---",
+    "You are a helpful agent...",
+    "```",
+    "",
+    "## Task Fields",
+    "",
+    schemaTable(delegateTaskSchema.properties),
+    "",
+    "## Top-level Fields",
+    "",
+    schemaTable(delegateArgumentsSchema.properties),
+    "",
+    "## Session Reuse",
+    "",
+    "When `sessionId` is set, the subagent is kept alive in a pool for the duration of the pi session.",
+    "Subsequent calls with the same `sessionId` continue the conversation — the agent remembers prior context.",
+    "",
+    "```ts",
+    "// First call — creates and runs an inline custom agent",
+    'delegate({ tasks: [{ prompt: "Investigate the auth module", systemPrompt: "You are a focused investigator. Map files and dependencies.", tools: ["read", "grep", "find", "ls"], sessionId: "auth-research" }] })',
+    "",
+    "// Second call — continues the same agent",
+    'delegate({ tasks: [{ prompt: "Now check the tests for that module", sessionId: "auth-research" }] })',
+    "",
+    "// Clean up when done",
+    'delegate({ tasks: [{ sessionId: "auth-research", action: "close" }] })',
+    "```",
+    "",
+    'Pooled agents remain live until `action: "close"` or parent Pi session shutdown.',
+    "",
+    "## Resuming Previous Sessions",
+    "",
+    "Use `resumeFrom` to continue a failed or interrupted subagent from where it left off.",
+    "Pass the exact absolute path to the session `.jsonl` file copied from delegate retry output. Do not invent placeholder values or use it as a ticket ID; async resume is supported.",
+    "The agent gets the full conversation history and the new `prompt` continues naturally.",
+    "",
+    "```ts",
+    "// Copy this exact path from the failed delegate result; do not invent it.",
+    "const exactRetrySessionFile = failedTaskResult.sessionFile;",
+    'delegate({ tasks: [{ prompt: "Continue testing — the server is already running on :3000",',
+    "  resumeFrom: exactRetrySessionFile }] })",
+    "```",
+    "",
+    "Combine with `sessionId` to resume AND pool the agent for further multi-turn use:",
+    "",
+    "```ts",
+    'delegate({ tasks: [{ prompt: "Continue the investigation",',
+    "  resumeFrom: exactRetrySessionFile,",
+    '  sessionId: "my-resumed-agent" }] })',
+    "```",
+    "",
+    "## Resuming on a Different Model",
+    "",
+    "A failed subagent's conversation can be resumed on a **different model** — useful when the original model hit an account usage limit, quota, or auth error (delegate tags these `model_error` and won't waste same-model retries on them). `createAgentSession` honors an explicit `model` over the session's stored model, so the resumed subagent keeps its full conversation history but runs the next turn on the model you name:",
+    "",
+    "```ts",
+    'delegate({ tasks: [{ prompt: "continue",',
+    "  resumeFrom: exactRetrySessionFile,",
+    '  model: "anthropic/claude-sonnet-4" }] })',
+    "```",
+    "",
+    "Pick a model you have auth for (the parent session's provider list). The failed result's retry hint names this exact shape when `failureKind` is `model_error`.",
+    "",
+    "## Async Mode",
+    "",
+    "Set `async: true` to run tasks in the background. The top-level `action` controls the ticket:",
+    "",
+    "```ts",
+    'delegate({ async: true, tasks: [{ prompt: "Investigate auth", systemPrompt: "You are a focused investigator.", tools: ["read", "grep", "find", "ls"] }] })',
+    "```",
+    "",
+    '- `delegate({ action: "poll" })` \u2014 list all tickets',
+    '- `delegate({ action: "poll", ticket: "abc123" })` \u2014 check one ticket',
+    '- `delegate({ action: "wait", ticket: "abc123", timeoutMs: 600000 })` \u2014 block until finished or timeout',
+    '- `delegate({ action: "cancel", ticket: "abc123" })` \u2014 preview activity and partial effects before cancelling',
+    '- `delegate({ action: "cancel", ticket: "abc123", force: true })` \u2014 abort after review',
+    "",
+    `See the field tables above for the full semantics. Max ${getMaxAsyncTickets()} concurrent async tickets.`,
+    "",
+    "## Gotchas",
+    "",
+    "- `*` 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: "..." }] }`.',
+    "- An ad-hoc task with no `tools` uses `*`; a named 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.",
+    `- Sync \`delegate\` runs at most ${getMaxConcurrent()} tasks at once (the rest queue, not fail). Use \`async: true\` to move work to the background.`,
+    "",
+    "## Config",
+    "",
+    "Tunables live in `~/.pi/agent/delegate.json`: `maxConcurrent` (sync ceiling), `maxAsyncTickets` (background ticket cap), `stallTimeoutMs` (inactivity watchdog; default 900000, 0 disables), per-model/per-provider concurrency limits, and per-agent model overrides.",
+    "The inactivity watchdog requests cooperative `AgentSession.abort()` cancellation and waits for the subagent to become idle; it is not a hard wall-clock execution deadline.",
+    "",
+    `Output bounding: subagent outputs longer than ${OUTPUT_SPILL_THRESHOLD_CHARS} characters are spilled to a temp file, and only the last ${OUTPUT_SPILL_TAIL_CHARS} characters stay in the LLM-facing result. Adjust with \`output.spillThresholdChars\` and \`output.spillTailChars\`. Spill files are written to the system temp directory with owner-only permissions; the full output is always available in the expanded TUI view and the spilled file.`,
+  ].join("\n");
+}

package/model.ts

@@ -0,0 +1,81 @@
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { VALID_THINKING } from "./constants.ts";
+
+export interface ResolvedModelRequest {
+  model: Model<Api> | undefined;
+  /** Pi-style `:<thinking-level>` suffix stripped to make the reference
+   *  resolve. Reported so the caller can warn — it is NOT honored as a
+   *  thinking level; the task's `thinking` field is the only thinking input. */
+  strippedSuffix?: ThinkingLevel;
+}
+
+function resolveModelReference(
+  spec: string,
+  registry: ModelRegistry,
+): Model<Api> | undefined {
+  const idx = spec.indexOf("/");
+  if (idx === -1) {
+    // Bare id — match against available models
+    const match = registry.getAvailable().find((m) => m.id === spec);
+    return match ?? undefined;
+  }
+  return registry.find(spec.slice(0, idx), spec.slice(idx + 1)) ?? undefined;
+}
+
+/** Resolve a model reference, tolerating a Pi-style `:<thinking-level>`
+ * suffix.
+ *
+ * Exact model references win first so provider model IDs containing colons are
+ * preserved. If no exact match exists, a final `:<thinking-level>` suffix is
+ * stripped and the base reference is resolved — models learned this syntax
+ * from Pi's CLI (e.g. `openai-codex/gpt-5.6-luna:max`) and keep emitting it,
+ * so hard-failing the whole call over it is worse than tolerating it. The
+ * suffix is deliberately NOT fed into thinking resolution: a single knob
+ * (the `thinking` field) beats two knobs with a silent precedence rule. */
+export function resolveModelRequest(
+  spec: string | undefined,
+  registry: ModelRegistry,
+  parentModel: Model<Api> | undefined,
+): ResolvedModelRequest {
+  if (!spec) return { model: parentModel };
+
+  const exact = resolveModelReference(spec, registry);
+  if (exact) return { model: exact };
+
+  const colon = spec.lastIndexOf(":");
+  if (colon === -1) return { model: undefined };
+
+  const suffix = spec.slice(colon + 1);
+  if (!VALID_THINKING.has(suffix)) return { model: undefined };
+
+  const model = resolveModelReference(spec.slice(0, colon), registry);
+  return model
+    ? { model, strippedSuffix: suffix as ThinkingLevel }
+    : { model: undefined };
+}
+
+/** Resolve a model spec and return only the selected model instance. */
+export function resolveModel(
+  spec: string | undefined,
+  registry: ModelRegistry,
+  parentModel: Model<Api> | undefined,
+): Model<Api> | undefined {
+  return resolveModelRequest(spec, registry, parentModel).model;
+}
+
+/** Find an available model with the same id as the given model, preferring
+ *  a different provider if the original has no configured auth. */
+export function findAvailableAlternative(
+  model: Model<Api> | undefined,
+  registry: ModelRegistry,
+): Model<Api> | undefined {
+  if (!model) return undefined;
+  if (registry.hasConfiguredAuth(model)) return model;
+  // Look for another model with the same id that DOES have auth.
+  // Prefer a different provider (avoid returning the same broken model).
+  return registry
+    .getAvailable()
+    .find((m) => m.id === model.id && m.provider !== model.provider);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@bermudi/pi-delegate",
+  "version": "0.1.0",
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^0.80.9",
+    "@earendil-works/pi-ai": "^0.80.9",
+    "@earendil-works/pi-coding-agent": "^0.80.9",
+    "@earendil-works/pi-tui": "^0.80.9",
+    "@marcfargas/pi-test-harness": "^0.6.1",
+    "@sinclair/typebox": "^0.34.0",
+    "esbuild": "^0.27.0",
+    "prettier": "^3.8.4",
+    "typescript": "^5.9.0"
+  },
+  "private": false,
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "build": "esbuild delegate.ts --bundle --platform=neutral --packages=external --format=esm --banner:js=\"// @ts-nocheck\" --outfile=delegate.bundle.ts",
+    "format": "prettier --write \"**/*.ts\""
+  },
+  "type": "module",
+  "description": "Delegate tool for the Pi coding agent.",
+  "keywords": [
+    "pi-package"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bermudi/pi-delegate.git"
+  },
+  "files": [
+    "*.ts",
+    "!*.test.ts",
+    "!*.bundle.ts",
+    "README.md",
+    "patches"
+  ],
+  "pi": {
+    "extensions": [
+      "./delegate.ts"
+    ]
+  }
+}

package/parent-context.ts

@@ -0,0 +1,42 @@
+import {
+  buildSessionContext,
+  type SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+
+/** Render the active parent conversation as compact context for a subagent. */
+export function buildParentTranscript(
+  entries: SessionEntry[],
+  leafId: string | null,
+): string | null {
+  try {
+    const ctx = buildSessionContext(entries, leafId);
+    const lines: string[] = [];
+    for (const msg of ctx.messages) {
+      if (msg.role === "user") {
+        const text = extractTextContent(msg.content);
+        if (text) lines.push(`**User:** ${text.trim()}`);
+      } else if (msg.role === "assistant") {
+        const text = extractTextContent(msg.content);
+        if (text) lines.push(`**Assistant:** ${text.trim()}`);
+      }
+    }
+    return lines.join("\n\n") || null;
+  } catch {
+    return null;
+  }
+}
+
+/** Extract only text blocks from a Pi message content value. */
+export function extractTextContent(
+  content: string | Array<{ type: string; text?: string }>,
+): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter(
+      (b): b is { type: "text"; text: string } =>
+        b.type === "text" && typeof b.text === "string",
+    )
+    .map((b) => b.text)
+    .join("");
+}