@bermudi/pi-delegate 0.1.7 → 0.1.9

package/README.md

@@ -38,6 +38,19 @@ Parent extension/MCP tools are not copied, and project instructions are rebuilt
 for the task's `cwd`. Omit `agent` when you want an ad-hoc task using delegate's
 normal inline defaults instead.
 
+The other built-ins are:
+
+- `scout` — read-only investigation with `read`, `grep`, `find`, and `ls`.
+- `coder` — implementation and verification with `read`, `write`, `edit`, and
+  `bash` in the shared workspace.
+- `reviewer` — review with `read` and `bash`, using a disposable scratch copy by
+  default. Set `workspace: "shared"` when a reviewer needs a persistent
+  `sessionId`.
+
+Fresh built-ins inherit the parent's exact model object and thinking level.
+Task-level overrides win; settings can provide unconditional overrides or exact
+parent-model overrides under `delegate.agentOverridesByParentModel`.
+
 ### Disposable scratch workspace
 
 For review, tests, or other commands whose project changes should be thrown
@@ -136,7 +149,7 @@ over an installed extension.
   rare override. Markdown agents are examples of custom agents.
 - **Named agent** / **Markdown agent** — A reusable custom agent persisted as a
   Markdown file in `.pi/agents/*.md` or `~/.pi/agent/agents/*.md`. The frontmatter
-  defines its name, description, model, tools, thinking level, and skills; the
+  defines its name, description, model, tools, and thinking level; the
   Markdown body is its system prompt.
 - **Ad-hoc subagent** — A subagent created from inline task fields instead of a
   named Markdown agent profile. In current output this is labeled `ad-hoc`.

package/agents.ts

@@ -7,8 +7,13 @@ import type {
 } from "@earendil-works/pi-agent-core";
 import { parseFrontmatter as parsePiFrontmatter } from "@earendil-works/pi-coding-agent";
 import {
+  BUILTIN_AGENT_NAMES,
+  CODER_AGENT_NAME,
   DEFAULT_AGENT_NAME,
   DEFAULT_TOOLS,
+  READONLY_TOOLS,
+  REVIEWER_AGENT_NAME,
+  SCOUT_AGENT_NAME,
   VALID_THINKING,
 } from "./constants.ts";
 import { resolveToolGroups } from "./tools.ts";
@@ -110,6 +115,50 @@ export function parseFrontmatter(
 
 // ── Agent Discovery ───────────────────────────────────────────────────────
 
+/** Built-in profiles are always available and cannot vary with Markdown files. */
+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.",
+    tools: DEFAULT_TOOLS,
+    systemPrompt: "",
+    builtin: true,
+    workspace: "shared",
+  },
+  [SCOUT_AGENT_NAME]: {
+    name: SCOUT_AGENT_NAME,
+    description: "Investigate without modifying the source project.",
+    tools: READONLY_TOOLS,
+    systemPrompt:
+      "Explore the codebase to answer the assigned question. Do not modify files. Trace relevant code, tests, documentation, and history when useful. Return concise findings with concrete paths, symbols, and any uncertainty. Prefer evidence over speculation.",
+    builtin: true,
+    workspace: "shared",
+  },
+  [CODER_AGENT_NAME]: {
+    name: CODER_AGENT_NAME,
+    description: "Implement and verify changes in the shared source tree.",
+    tools: DEFAULT_TOOLS,
+    systemPrompt:
+      "Implement the assigned change. Read the existing code and project instructions first. Prefer the smallest maintainable solution that follows existing conventions. Surface failures clearly. Run focused tests or checks and report what changed, what passed, and any remaining risk.",
+    builtin: true,
+    workspace: "shared",
+  },
+  [REVIEWER_AGENT_NAME]: {
+    name: REVIEWER_AGENT_NAME,
+    description: "Inspect the current snapshot and report actionable findings.",
+    tools: ["read", "bash"],
+    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",
+  },
+};
+
+export function isBuiltinAgentName(name: string): boolean {
+  return (BUILTIN_AGENT_NAMES as readonly string[]).includes(name);
+}
+
 /** Find the nearest ancestor containing project-scoped agent files. */
 export function findProjectRoot(cwd: string): string | null {
   let dir = cwd;
@@ -330,7 +379,9 @@ export function discoverAgents(cwd: string): Map<string, AgentConfig> {
     scope: "claude",
   });
 
-  const agents = new Map<string, AgentConfig>();
+  const agents = new Map<string, AgentConfig>(
+    Object.entries(BUILTIN_AGENT_CONFIGS),
+  );
   const loadDir = (
     { dir, scope }: { dir: string; scope: AgentConfig["scope"] },
     loader: (fp: string) => AgentConfig | null,
@@ -345,9 +396,9 @@ export function discoverAgents(cwd: string): Map<string, AgentConfig> {
       if (!e.name.endsWith(".md") || e.name.endsWith(".chain.md")) continue;
       const filePath = path.join(dir, e.name);
       const cfg = loader(filePath);
-      if (cfg?.name === DEFAULT_AGENT_NAME) {
+      if (cfg && isBuiltinAgentName(cfg.name)) {
         console.warn(
-          `[delegate] ignoring agent profile '${DEFAULT_AGENT_NAME}' from ${filePath}: the name is reserved for the built-in parent-mirroring profile.`,
+          `[delegate] ignoring agent profile '${cfg.name}' from ${filePath}: the name is reserved for a built-in delegate profile.`,
         );
         continue;
       }

package/config.ts

@@ -129,10 +129,17 @@ function normalizeProviderExtensions(
 // Provider-scoped opt-in extension map for subagents. Keep this aligned with
 // the currently shipped codex remote-compaction integration. `delegate.json`
 // `providerExtensions` replaces a provider's entries (it does not append); an
-// empty array is ignored so the default persists.
-const DEFAULT_PROVIDER_EXTENSIONS: Record<string, readonly string[]> = {
-  "openai-codex": ["git:github.com/bermudi/manaflow-pi-codex"],
-};
+// empty array is ignored so the default persists. Provenance is classification
+// by config presence: every source the user lists is required and fails
+// closed when missing, unverifiable, or broken — including an exact re-listing
+// of a shipped default. Shipped defaults (providers the user never mentioned)
+// are best-effort: they degrade silently to extension-free subagents on Pi's
+// native compaction, because absence of an optional integration is not a
+// warning condition — that is Pi's normal operation.
+const DEFAULT_PROVIDER_EXTENSIONS: Record<string, readonly string[]> =
+  Object.assign(Object.create(null) as Record<string, readonly string[]>, {
+    "openai-codex": ["npm:@bermudi/pi-codex"],
+  });
 
 function resolveProviderExtensions(
   raw: unknown,
@@ -155,7 +162,7 @@ const DEFAULT_DELEGATE_CONFIG: DelegateConfig = {
     wholeTaskMaxRetries: 3,
     wholeTaskBaseDelayMs: 1_000,
   },
-  providerExtensions: DEFAULT_PROVIDER_EXTENSIONS,
+  providerExtensions: {},
   telemetry: {
     enabled: true,
   },
@@ -174,7 +181,15 @@ let __delegateConfig: DelegateConfig = {
 };
 let stallTimeoutOverrideForTesting: number | undefined;
 
-/** Read delegate config from disk. Returns defaults if file missing or corrupt. */
+/** Read delegate config from disk. Returns defaults if file missing or corrupt.
+ *
+ *  The returned `providerExtensions` is the *user-only* view — exactly what the
+ *  file said, defaults excluded. `getSubagentProviderExtensionMap()` is the
+ *  merged (defaults + user) view, and
+ *  `getSubagentProviderExtensionSourcesForProvider()` is the provenance-tagged
+ *  view. Keeping the raw user map here is what lets the sources getter
+ *  distinguish "the user listed this" from "this is a shipped default" by
+ *  config presence rather than string identity. */
 export function loadDelegateConfig(): DelegateConfig {
   try {
     const raw = fs.readFileSync(DELEGATE_CONFIG_PATH, "utf-8");
@@ -191,7 +206,9 @@ export function loadDelegateConfig(): DelegateConfig {
         ...(parsed.concurrency ?? {}),
       },
       retry: { ...DEFAULT_DELEGATE_CONFIG.retry, ...(parsed.retry ?? {}) },
-      providerExtensions: resolveProviderExtensions(parsed.providerExtensions),
+      providerExtensions: normalizeProviderExtensions(
+        parsed.providerExtensions,
+      ),
       telemetry: normalizeTelemetryConfig(parsed.telemetry),
       output: { ...DEFAULT_DELEGATE_CONFIG.output, ...(parsed.output ?? {}) },
     } as DelegateConfig;
@@ -255,7 +272,7 @@ export function _setDelegateConfigForTesting(
       ...DEFAULT_DELEGATE_CONFIG.retry,
       ...(config.retry ?? {}),
     },
-    providerExtensions: resolveProviderExtensions(config.providerExtensions),
+    providerExtensions: normalizeProviderExtensions(config.providerExtensions),
     telemetry: normalizeTelemetryConfig(config.telemetry),
     output: {
       ...DEFAULT_DELEGATE_CONFIG.output,
@@ -266,7 +283,11 @@ export function _setDelegateConfigForTesting(
 }
 
 /**
- * Get the configured provider-scoped extension allowlist for subagents.
+ * Get the configured provider-scoped extension allowlist for subagents:
+ * the merged view (shipped defaults + user config, user entries replacing a
+ * provider's defaults). The stored `config.providerExtensions` itself is the
+ * user-only view; the merge happens here so provenance survives until a
+ * consumer asks for it (`getSubagentProviderExtensionSourcesForProvider`).
  * Explicit configs are normalized here too, so callers using the injected
  * config form get the same case-insensitive and replace-per-provider
  * semantics as the file-backed singleton.
@@ -295,6 +316,60 @@ export function getSubagentProviderExtensionsForProvider(
     : [];
 }
 
+/** A provider-extension source together with how it entered the config. */
+export interface ProviderExtensionSource {
+  /** The normalized source string, as the package manager consumes it. */
+  readonly source: string;
+  /**
+   * Whether the user configured this source themselves (required) or it is a
+   * shipped default for a provider the user never mentioned (best-effort).
+   * Required sources fail closed when missing, unverifiable, or broken;
+   * best-effort defaults degrade silently to extension-free subagents on
+   * Pi's native compaction.
+   */
+  readonly required: boolean;
+}
+
+/**
+ * Get the provenance-tagged extension sources for a provider's subagents.
+ * Classification is by config presence, never by string identity: everything
+ * the user lists in `providerExtensions` is `required: true` — including an
+ * exact re-listing of a shipped default, because typing it into the config
+ * expresses intent. Providers the user never configured fall back to the
+ * shipped defaults, tagged `required: false` (best-effort).
+ */
+export function getSubagentProviderExtensionSourcesForProvider(
+  provider: string | undefined,
+  config: DelegateConfig = __delegateConfig,
+): readonly ProviderExtensionSource[] {
+  const normalized = provider?.trim().toLowerCase();
+  if (!normalized) return [];
+  // Normalize the injected config map so an unnormalized key like " Custom-Provider "
+  // is handled, matching getSubagentProviderExtensionMap / getSubagentProviderExtensionsForProvider.
+  const rawUserMap = config.providerExtensions;
+  const userMap = rawUserMap
+    ? normalizeProviderExtensions(rawUserMap)
+    : (Object.create(null) as Record<string, readonly string[]>);
+  if (Object.prototype.hasOwnProperty.call(userMap, normalized)) {
+    return (userMap[normalized] ?? []).map((source) => ({
+      source,
+      required: true,
+    }));
+  }
+  if (
+    !Object.prototype.hasOwnProperty.call(
+      DEFAULT_PROVIDER_EXTENSIONS,
+      normalized,
+    )
+  ) {
+    return [];
+  }
+  return (DEFAULT_PROVIDER_EXTENSIONS[normalized] ?? []).map((source) => ({
+    source,
+    required: false,
+  }));
+}
+
 // ── Config Getters ───────────────────────────────────────────────────────
 
 /**

package/constants.ts

@@ -1,6 +1,23 @@
 /** Reserved built-in profile that mirrors the live parent configuration. */
 export const DEFAULT_AGENT_NAME = "default";
 
+/** Reserved built-in profile for read-only investigation. */
+export const SCOUT_AGENT_NAME = "scout";
+
+/** Reserved built-in profile for shared-workspace implementation work. */
+export const CODER_AGENT_NAME = "coder";
+
+/** Reserved built-in profile for isolated review work. */
+export const REVIEWER_AGENT_NAME = "reviewer";
+
+/** All names reserved by delegate's built-in profiles. */
+export const BUILTIN_AGENT_NAMES = [
+  DEFAULT_AGENT_NAME,
+  SCOUT_AGENT_NAME,
+  CODER_AGENT_NAME,
+  REVIEWER_AGENT_NAME,
+] as const;
+
 /** Full-capability agent set. Inline-task default and the `*` shorthand.
  *  Bash subsumes search, so the dedicated grep/find/ls tools are excluded. */
 export const DEFAULT_TOOLS = ["read", "write", "edit", "bash"];

package/delegate.ts

@@ -24,6 +24,10 @@ export type { DelegateConfig } from "./config.ts";
 
 export {
   DEFAULT_AGENT_NAME,
+  SCOUT_AGENT_NAME,
+  CODER_AGENT_NAME,
+  REVIEWER_AGENT_NAME,
+  BUILTIN_AGENT_NAMES,
   DEFAULT_TOOLS,
   READONLY_TOOLS,
   MAX_CONCURRENCY,
@@ -123,6 +127,8 @@ export {
   loadAgentFile,
   loadClaudeAgentFile,
   discoverAgents,
+  BUILTIN_AGENT_CONFIGS,
+  isBuiltinAgentName,
   buildSubagentSystemPrompt,
   DEFAULT_SUBAGENT_SYSTEM_PROMPT,
 } from "./agents.ts";
@@ -133,7 +139,12 @@ export {
   resolveModelRequest,
   findAvailableAlternative,
 } from "./model.ts";
-export { readDelegateSettingsFile, loadDelegateSettings } from "./settings.ts";
+export {
+  readDelegateSettingsFile,
+  loadDelegateSettings,
+  clearDelegateSettingsCache,
+} from "./settings.ts";
+export type { AgentOverride } from "./settings.ts";
 export { resolveCwd, extractOutput, extractUsage } from "./utils.ts";
 export {
   decideSpill,

package/dispatch.ts

@@ -24,6 +24,7 @@ import {
 import { validateDelegateOperation } from "./schema.ts";
 import { notifyCrossLeafDelivery, syncDelegateStatus } from "./status.ts";
 import { validateTasks, resolveTasks } from "./task-resolution.ts";
+import { clearDelegateSettingsCache } from "./settings.ts";
 import type { CallSpan } from "./telemetry.ts";
 import type {
   AgentConfig,
@@ -146,6 +147,9 @@ export interface DelegateDispatchInput {
 export async function dispatchDelegate(
   input: DelegateDispatchInput,
 ): Promise<DelegateToolResult> {
+  // Settings are user-editable. Clear once at the dispatch boundary so every
+  // task in this batch observes one consistent settings snapshot.
+  clearDelegateSettingsCache();
   const {
     pi,
     params,

package/extension.ts

@@ -18,7 +18,10 @@ import {
 } from "./dispatch.ts";
 import { renderDelegateCall, renderDelegateResult } from "./render-result.ts";
 import { hostCompatError } from "./host-compat.ts";
-import { invalidateHostDepsCache } from "./host.ts";
+import {
+  invalidateHostDepsCache,
+  registerProviderExtensionNotifier,
+} from "./host.ts";
 import { recordTreeNavigation, resetLeafTracking } from "./leaf.ts";
 import { closeAllPooledAgents } from "./pool.ts";
 import {
@@ -122,6 +125,12 @@ export default function delegateExtension(pi: ExtensionAPI): void {
     prepareArguments: normalizeDelegateArguments,
 
     async execute(_id, params: DelegateArguments, signal, onUpdate, ctx) {
+      // Prime the UI notice for best-effort provider extensions that load for
+      // subagents (host.ts consumes it where the fact is discovered). Every
+      // execute re-primes so a stale ctx never sticks.
+      registerProviderExtensionNotifier((message) =>
+        ctx.ui.notify(message, "info"),
+      );
       const parentModelId = ctx.model?.id;
       const tasks = params.tasks ?? [];
       const parentSessionFile = (
@@ -347,6 +356,7 @@ export default function delegateExtension(pi: ExtensionAPI): void {
       // captured pi) to touch. The cancelled completion path still writes one
       // final aggregate after late task results arrive, but never delivers UI.
       clearDelegateStatusContext();
+      registerProviderExtensionNotifier(undefined);
       // A replacement session starts on its own leaf; stale tracking would make
       // every ticket look cross-leaf (or, worse, look same-leaf by accident).
       resetLeafTracking();