@marcoscale98/pi-extensible-workflows 5.14.1-fork.1 → 5.19.1-fork.1

package/CHANGELOG.md

@@ -1,6 +1,141 @@
 # Changelog
 ## Unreleased
 
+## [5.19.1] - 2026-10-05
+
+### New capabilities
+
+- Trajectory shows workflow script `shell()` and `tools.<name>()` calls: CALLS and the `script` Gantt lane share status and colours, with phase and timing. Tool arguments and results are not recorded in call state or shown in Trajectory (including live state and HTML exports/shares); tool errors keep only the code. The replay journal retains tool results unchanged. Shell calls keep inputs and output, with environment override names, not values. Calls are recorded without a count cap; tool metadata writes are best-effort, and journaled calls without finish timing show completed with unknown duration.
+
+## [5.19.0] - 2026-10-02
+
+### Breaking changes
+
+- `tools` is a reserved workflow global: registering a workflow function named `tools` fails with `GLOBAL_COLLISION`. Rename the function.
+
+### New capabilities
+
+- Workflow and subagent tools declare an `outputSchema` and return `structuredContent`, so Pi `codemode` scripts receive objects instead of JSON text. For example, `await tools.workflow_status({ runId })` resolves to `{ runId, workflowName, state, agents, ... }`. A completed foreground `workflow`, `workflow_retry`, or `workflow_resume` call resolves with the full `value`, even when the model sees only a result descriptor. Inside workflow agents, the child agent tools `agent` and `get_subagent_result` do the same, and Herdr-bridged tools keep their `outputSchema`.
+- Workflow scripts call the launching session's tools directly as `await tools.<name>(args)`, through Pi's `ctx.executeTool()`, with the names and results of Pi `codemode`. Permission handlers apply, results are journaled for resume and retry, the live workflow item shows calls in flight, and an unknown tool fails the launch with `UNKNOWN_TOOL`. Failed calls reject with the new `TOOL_FAILED` code.
+- `workflow_status`, `workflow_catalog`, and `subagents_inspect` carry the `readOnlyHint` tool annotation, so permission extensions that read annotations can skip confirming them.
+
+### Internal
+
+- Build and test against Pi 1.0.0. `@piewf/cli` bundles Pi 1.0.0.
+
+## [5.18.0] - 2026-09-30
+
+### Breaking changes
+
+- `pi-extensible-workflows` and `@piewf/herdr` require Pi 0.99.0 or later; their `@earendil-works/pi-coding-agent` peer dependency is now `>=0.99.0`. `@piewf/cli` bundles Pi 0.99.1.
+
+### New capabilities
+
+- Global model aliases appear in `/model` and `--model` as virtual models named `workflow/<alias>`, for example `workflow/cheap-model`. The alias target is read from settings on every request, and workflow agents and subagents that inherit the session model run on that target. The thinking level selected in `/model` replaces the one in the alias. Project and extension-provided aliases are not listed, and new aliases need `/reload`.
+- Workflow agents and standalone subagents load Pi's built-in `codemode`, `tool-search`, and `mcp` extensions, so they can reach the MCP servers from `mcp.json` through `codemode` or `tool_search`. `-builtin:<name>` in Pi settings still disables them. Workflow extension selectors name them `builtin:codemode`, `builtin:tool-search`, and `builtin:mcp`; a selector list that starts with `!*` needs `builtin:*` or those names to keep them.
+- The global `codemodeTools` workflow setting limits which workflow and subagent tools Pi `codemode` scripts may call: `"all"` (default), `"read-only"` (`workflow_status`, `workflow_catalog`, and `subagents_inspect`), or `"none"`. The model still calls every tool directly. Changes apply after `/reload`.
+- The agent tool ceiling includes the parent session's tools that only codemode scripts call or `tool_search` loads, such as MCP tools with the default exposure. Role and call tool selectors still restrict them.
+
+### Fixes
+
+- Prompt inspection in `piewf doctor` and role inspection renders the system prompt again on Pi 0.99, including changes made by `before_agent_start` handlers.
+- An agent that asks for a model of Pi's built-in `llama.cpp` provider fails with an error that explains why: Pi does not expose that extension to extension sessions. Declare the server as a provider in `models.json` instead.
+
+### Internal
+
+- Build and test against Pi 0.99.1. Package verification ignores three `brace-expansion` advisories that come from the `npm-shrinkwrap.json` of `@earendil-works/pi-coding-agent@0.99.1`.
+
+## [5.17.2] - 2026-09-28
+
+### Breaking changes
+
+- `subagents_inspect({})` lists only the runs of the current Pi session, matching `/subagents` and Trajectory. Pass `scope: "all"` to list every stored run as before. Lookup by `id` still resolves runs from any session ([#305](https://github.com/vekexasia/pi-extensible-workflows/pull/305)).
+
+### New capabilities
+
+- `piewf doctor` inspects a role file before it is installed: a role ending in `.md`, such as `piewf doctor ./roles/reviewer.md`, is read as a file relative to the current working directory, while other values still name an installed role. A missing file reports `ROLE_FILE_NOT_FOUND` ([#303](https://github.com/vekexasia/pi-extensible-workflows/issues/303)).
+
+### Fixes
+
+- `piewf doctor` no longer fails because of roles that another role overrides: it still reports their invalid frontmatter, but checks tools, models, and settings only for the roles that apply. A role tool missing from doctor's headless tool list is now a `ROLE_TOOL_INACTIVE` warning, because doctor cannot see tools that extensions add when a session starts and the runtime skips unavailable role tools. Role inspection and workflow agent sessions now skip the workflow host extensions of every installed copy of the package, so a Pi package installed next to `@piewf/cli` no longer fails with `Global name is already registered: reviewLoop` ([#302](https://github.com/vekexasia/pi-extensible-workflows/issues/302)).
+
+## [5.17.1] - 2026-09-26
+
+### Fixes
+
+- Running workflow agents and standalone subagents show a fixed status glyph before their names and keep the activity spinner visible after `[running]`, even without a current activity label.
+
+### Internal
+
+- Remove duplicated view and trajectory helpers, unused internal code, and tracked generated images. Preserve the public `pi-extensible-workflows/runtime` type exports.
+
+## [5.17.0] - 2026-09-23
+
+### New capabilities
+
+- `/subagents` opens the `/workflow` dashboard layout instead of a picker followed by a `key=value` detail dump. The run list sits beside the selected run's details at 80 columns or wider and drills down from list to details to actions below that, with the same configured and vim key hints and page scrolling. While a run is active, the active runs and the selection refresh every second. Details show the run ID and the shared agent fields in the `/workflow` agent order; the prompt, live system prompt, and result open in the editor, as in `/workflow`, and editor and copy actions leave the action menu open. A running run shows its live activity through the new opt-in `includeActivity` inspection context; `subagents_inspect` still leaves activity out. A retry selects the new run, and a repeated name carries its short ID in the list, as in the `/workflow` picker. Outside the TUI, the picker rows follow the `/workflow` picker: state glyph, name, state, model, cost, and runtime.
+- `/subagents` gains the `/workflow` run actions that apply to standalone runs: `Delete`, `Delete all completed`, and `Delete all failed` (also in the picker outside the TUI), and `Copy run path`. Stop and deletions ask for confirmation. `SubagentManager` gains an optional `delete(request, context)` that removes a settled record and refuses running runs and runs whose worktree cleanup is pending; it is not a model tool.
+- Background subagents appear below the editor in the workflow widget's frame, one row per run with model, tokens, cost, elapsed time, and quiet or stalled warnings, and each leaves a receipt in the transcript when it settles, like a background workflow run.
+- The `subagents_run` result header shows tokens and cost, like the workflow header.
+
+### Fixes
+
+- Declining the Stop confirmation in the `/workflow` dashboard no longer leaves Pi stuck. Pi's confirm dialog replaced the dashboard and then restored the editor, so the `/workflow` command never finished: later messages and extension commands such as `/subagents` queued without running, and the workflow widget stayed hidden. The question now appears inside the dashboard, as in `/subagents`; declining keeps the dashboard open on the action menu.
+- A subagent that settled just before its manager was disposed, for example at session shutdown, no longer stays `running` on disk. Disposal skipped the terminal status write, and a new manager in the same Pi process treated the record as owned by a live process, so it kept showing as running and could not be retried.
+
+## [5.16.3] - 2026-09-23
+
+### Fixes
+
+- A live foreground workflow block taller than the terminal no longer snaps pi's scrollback to the bottom on every update. Past `rows - 10` lines the block turns compact: finished phases collapse to one summary line (done, failed, wall time, tokens, cost) plus their failures, and the current phase lists failed, active, and the three latest settled agents with a count of the rest. `ctrl+o` still shows everything, and a finished block keeps the full list.
+
+## [5.16.2] - 2026-09-23
+
+### New capabilities
+
+- Trajectory highlights workflow scripts, JSON values (tool and workflow arguments, environment, and output), and fenced code in messages with a vendored Prism 1.30.0 build (JavaScript, TypeScript, JSON, bash, diff, Python).
+- Trajectory lists runs by newest completion with active runs on top. Each session shows every active run or subagent and at least three in total; the rest sit behind a "+ N more" toggle that is remembered per browser, and the selected entry always stays visible.
+
+### Fixes
+
+- Pi no longer adopts a Trajectory server that answers on the port without owning the lock, such as an older server whose lock was lost. `/health` now reports the server pid and fingerprint; a mismatching server that reports its pid is replaced, and one without an identity fails the attach with a clear error instead of serving outdated code indefinitely.
+
+## [5.16.1] - 2026-09-23
+
+### Fixes
+
+- Trajectory no longer blanks a live subagent's or agent's events for about a second when its transcript grows between a state poll and the transcript read; the stale reply keeps the cached entries until the newer revision arrives.
+
+## [5.16.0] - 2026-09-23
+
+### Breaking changes
+
+- `extensionSettings.trajectory.themes` is removed; settings files that still set it fail validation. Persisted launch snapshots that carry it still load.
+
+### New capabilities
+
+- Trajectory has a paper-style look in light and dark versions. It follows the system colour scheme, and a sidebar toggle overrides it per browser. On phones it shows one panel at a time, with Runs, Trace, and Details tabs.
+- The Trajectory inspector shows workflow arguments (bounded for large values) (#300) and an Agent details Output tab (#301).
+
+### Performance
+
+- Foreground workflow progress bursts collapse to one update per 100ms, and progress reads `state.json` alone instead of state plus snapshot, so Pi no longer re-renders the whole tool block for every agent event.
+- Trajectory ships tool timing only for the run a browser shows and omits timing it already delivered at the same revision. The gantt patches only changed lanes and merges tool calls that overlap on screen.
+- Trajectory publishers poll every 10s while no browser is attached, and hidden tabs skip rendering.
+
+### Fixes
+
+- A Trajectory browser tab that drops without a WebSocket close frame is released, so viewer counts and pending requests no longer leak.
+- Live Trajectory timing keeps the newest entries within its 64 KB per-agent budget, so a long agent's gantt keeps growing instead of freezing on its first calls.
+- `piewf` `npx` examples use the scoped `@piewf/cli` package.
+
+## [5.15.0] - 2026-09-18
+
+### New capabilities
+
+- Roles are exposed as a standalone `pi-extensible-workflows/roles` subpath (`discoverRoles`, `loadRole`, `resolveRole`) that resolves a role into plain data (model, tools, skills, extensions, prompt, context file scopes, unmatched selectors) without a workflow run; the workflow executor, validation, CLI, and subagents consume the same implementation (#294).
+- `@piewf/cli` adds a `pi-role <role> [pi arguments...]` launcher that resolves a role and starts the regular Pi CLI with the matching model, tools, skills, extensions, and system prompt arguments; remaining arguments are forwarded to Pi (#295).
+
 ## [5.14.1] - 2026-09-17
 
 ### Fixes

package/dist/src/agent-execution.js

@@ -5,9 +5,9 @@ import { basename, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Type } from "@earendil-works/pi-ai";
 import { Compile } from "typebox/compile";
-import { createAgentSession, DefaultPackageManager, DefaultResourceLoader, defineTool, getAgentDir, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, createCodemodeExtension, createMcpExtension, createToolSearchExtension, DefaultPackageManager, DefaultResourceLoader, defineTool, getAgentDir, ModelRuntime, SessionManager, SettingsManager } from "@earendil-works/pi-coding-agent";
 ;
-import { SerialLane, assertModelThinking, byPriorityThenName, deepFreeze, errorText, jsonObject, jsonValue, mergeWorkflowExtensionSettings, object, modelAliasName, modelCapability, resolveModelReference, resourcePatternHasMagic, selectResourcesByLayers, unmatchedResourcePatterns } from "./utils.js";
+import { SerialLane, assertModelThinking, byPriorityThenName, deepFreeze, errorText, jsonObject, jsonValue, mergeWorkflowExtensionSettings, object, physicalModel, resolveModelReference, resourcePatternHasMagic, unmatchedResourcePatterns } from "./utils.js";
 import { SETTLED_AGENT_STATES, WorkflowError, isContextFileScope, zeroAccounting } from "./types.js";
 import { createLiveSessionHandoff } from "./session-handoff.js";
 import { createToolTimingExtension } from "./tool-timing.js";
@@ -15,7 +15,9 @@ import { isEmptyAbortedAssistant, normalizePiMessage, normalizePiSessionEvent, r
 import { createPiRuntimeAgentRunner, isRuntimeAgentProviderError, normalizePiRuntimeError } from "./pi-runtime-runner.js";
 import { defaultWorkflowResultSchema } from "./runtime/workflow-result.js";
 import { validateAgentOptions, validateSchema } from "./validation.js";
-import { canonicalPath } from "./paths.js";
+import { canonicalPath, extensionIdentity } from "./paths.js";
+import { isCorePackageName } from "./package-identity.js";
+import { canonicalExtensionSelector, resolveRole } from "./roles.js";
 const localToolTimingExtension = createToolTimingExtension();
 function parseModel(value, fallback, aliases = {}, knownModels, settingsPath) {
     if (!value)
@@ -26,25 +28,26 @@ function parseModel(value, fallback, aliases = {}, knownModels, settingsPath) {
 function accounting(stats) {
     return { input: stats.tokens.input, output: stats.tokens.output, cacheRead: stats.tokens.cacheRead, cacheWrite: stats.tokens.cacheWrite, cost: stats.cost };
 }
-const extensionDirectory = dirname(fileURLToPath(import.meta.url));
-const workflowPackageRoot = basename(dirname(extensionDirectory)) === "dist" ? resolve(extensionDirectory, "../..") : resolve(extensionDirectory, "..");
-const WORKFLOW_HOST_ENTRIES = new Set([
-    canonicalPath(resolve(workflowPackageRoot, "src/index.ts")),
-    canonicalPath(resolve(workflowPackageRoot, "dist/src/index.js")),
-    canonicalPath(resolve(workflowPackageRoot, "starter/index.ts")),
-    canonicalPath(resolve(workflowPackageRoot, "dist/starter/index.js")),
-    canonicalPath(resolve(workflowPackageRoot, "subagents/index.ts")),
-    canonicalPath(resolve(workflowPackageRoot, "dist/subagents/index.js")),
-]);
-function canonicalExtensionSelector(selector, base = process.cwd()) {
-    const negated = selector.startsWith("!");
-    const body = negated ? selector.slice(1) : selector;
-    if (body === "*" || body === "**" || body.startsWith("**/"))
-        return selector;
-    const resolved = resolve(base, body);
-    if (resourcePatternHasMagic(body))
-        return `${negated ? "!" : ""}${resolved}`;
-    return `${negated ? "!" : ""}${canonicalPath(resolved)}`;
+const WORKFLOW_HOST_ENTRY_PATHS = ["src/index.ts", "dist/src/index.js", "starter/index.ts", "dist/starter/index.js", "subagents/index.ts", "dist/subagents/index.js"];
+function isWorkflowHostEntry(path) {
+    const entryPath = canonicalPath(path);
+    let packageRoot = dirname(entryPath);
+    while (packageRoot !== dirname(packageRoot)) {
+        const packageMetadataPath = join(packageRoot, "package.json");
+        if (existsSync(packageMetadataPath)) {
+            try {
+                const metadata = JSON.parse(readFileSync(packageMetadataPath, "utf8"));
+                if (typeof metadata !== "object" || metadata === null || !("name" in metadata) || !isCorePackageName(metadata.name))
+                    return false;
+                return WORKFLOW_HOST_ENTRY_PATHS.some((entry) => canonicalPath(join(packageRoot, entry)) === entryPath);
+            }
+            catch {
+                return false;
+            }
+        }
+        packageRoot = dirname(packageRoot);
+    }
+    return false;
 }
 const WORKFLOW_DIRECTORY = "pi-extensible-workflows";
 function workflowSystemPromptPath(cwd, agentDir, projectTrusted) {
@@ -80,34 +83,41 @@ function loadPiPackageDirectory() {
         }
     }).catch((error) => ({ error: `could not load @earendil-works/pi-coding-agent package metadata: ${errorText(error)}` }));
 }
-let nativePromptTemplateModule;
-async function loadNativePromptTemplateModule() {
+const nativeCoreModules = new Map();
+/** Pi does not export these core modules, so inspection loads them from the installed package. */
+async function loadNativeCoreModule(file, label) {
     const packageDirectory = await loadPiPackageDirectory();
-    let promptTemplatePath;
+    let modulePath;
     if (packageDirectory.directory) {
-        const candidate = resolve(packageDirectory.directory, "dist/core/prompt-templates.js");
+        const candidate = resolve(packageDirectory.directory, "dist/core", file);
         if (existsSync(candidate))
-            promptTemplatePath = candidate;
+            modulePath = candidate;
     }
-    promptTemplatePath ??= resolve(dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), "core/prompt-templates.js");
+    modulePath ??= resolve(dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))), "core", file);
     const packageDirectoryError = packageDirectory.error ? ` Package directory lookup failed: ${packageDirectory.error}` : "";
-    return nativePromptTemplateModule ??= import(promptTemplatePath).then((module) => module).catch((error) => { throw new Error(`Could not load Pi prompt templates.${packageDirectoryError}`, { cause: error }); });
+    let loaded = nativeCoreModules.get(file);
+    if (!loaded) {
+        loaded = import(modulePath).catch((error) => { throw new Error(`Could not load Pi ${label}.${packageDirectoryError}`, { cause: error }); });
+        nativeCoreModules.set(file, loaded);
+    }
+    return loaded;
 }
 async function expandPromptTemplateForInspection(text, templates) {
-    return (await loadNativePromptTemplateModule()).expandPromptTemplate(text, templates);
+    return (await loadNativeCoreModule("prompt-templates.js", "prompt templates")).expandPromptTemplate(text, templates);
+}
+async function buildSystemPromptForInspection(options) {
+    return (await loadNativeCoreModule("system-prompt.js", "system prompt builder")).buildSystemPrompt(options);
 }
 async function preparePiPrompt(native, text) {
     const session = native;
     const diagnostics = [];
     const runner = session._extensionRunner;
-    const baseSystemPrompt = typeof session._baseSystemPrompt === "string" ? session._baseSystemPrompt : session.systemPrompt ?? "";
+    const baseSystemPrompt = session.systemPrompt ?? "";
     const baseOptions = session._baseSystemPromptOptions;
     const expandSkillCommand = session._expandSkillCommand;
     const templates = session.promptTemplates;
     if (!runner)
         diagnostics.push({ type: "error", message: "Pi prompt inspection seam is unavailable: extension runner is missing", source: "Pi session" });
-    if (typeof session._baseSystemPrompt !== "string")
-        diagnostics.push({ type: "error", message: "Pi prompt inspection seam is unavailable: base system prompt is missing", source: "Pi session" });
     if (baseOptions === undefined)
         diagnostics.push({ type: "error", message: "Pi prompt inspection seam is unavailable: base system prompt options are missing", source: "Pi session" });
     if (typeof expandSkillCommand !== "function")
@@ -138,9 +148,11 @@ async function preparePiPrompt(native, text) {
                 diagnostics.push({ type: "error", message: `Pi prompt template expansion is unavailable: ${errorText(error)}`, source: "Pi session" });
             }
         }
-        const result = !inputHandled && runner && baseOptions !== undefined ? await runner.emitBeforeAgentStart(expandedPrompt, undefined, baseSystemPrompt, baseOptions) : undefined;
+        const result = !inputHandled && runner && baseOptions !== undefined ? await runner.emitBeforeAgentStart(expandedPrompt, undefined, baseOptions) : undefined;
         const prepared = result;
-        return { prompt: text, expandedPrompt, systemPrompt: typeof prepared?.systemPrompt === "string" ? prepared.systemPrompt : baseSystemPrompt, systemPromptOptions: baseOptions, messages: prepared?.messages ?? [], inputHandled, diagnostics };
+        const systemPromptOptions = prepared?.systemPromptOptions ?? baseOptions;
+        const systemPrompt = prepared?.systemPromptOptions === undefined ? baseSystemPrompt : await buildSystemPromptForInspection(prepared.systemPromptOptions);
+        return { prompt: text, expandedPrompt, systemPrompt, systemPromptOptions, messages: prepared?.messages ?? [], inputHandled, diagnostics };
     }
     finally {
         unsubscribe?.();
@@ -184,6 +196,22 @@ export function flushExtensionProviders(resourceLoader, modelRuntime) {
     runtime.pendingNativeProviderRegistrations = [];
     return failures;
 }
+/**
+ * The CLI adds Pi's built-in extensions itself; SDK sessions only get them from these public
+ * factories (docs/sdk.md). As `builtin` entries they obey `-builtin:<name>` settings, and like the
+ * CLI's they are replaceable by an extension that registers the same tools or commands.
+ * NOTE: Pi does not export the built-in llama.cpp extension, so workflow agents cannot use models it
+ * provides. Declare the server as a provider in models.json instead.
+ */
+function builtinExtensions() {
+    return [
+        { name: "codemode", factory: createCodemodeExtension(), replaceable: true, builtin: true },
+        { name: "tool-search", factory: createToolSearchExtension(), replaceable: true, builtin: true },
+        { name: "mcp", factory: createMcpExtension(), replaceable: true, builtin: true },
+    ];
+}
+const BUILTIN_EXTENSION_PREFIX = "builtin:";
+function isLlamaModel(model) { return model.provider === "llama.cpp"; }
 async function createLocalPiSessionHandle(input, sessionStartEvent) {
     const agentDir = input.agentDir ?? getAgentDir();
     const systemPromptSource = workflowSystemPromptPath(input.cwd, agentDir, input.resourcePolicy?.projectTrusted ?? true);
@@ -197,28 +225,33 @@ async function createLocalPiSessionHandle(input, sessionStartEvent) {
     const tools = [...new Set([...input.tools, ...customTools.map(({ name }) => name)])];
     let settingsManager;
     let resourceLoader;
+    const builtins = builtinExtensions();
+    const builtinNames = builtins.flatMap((extension) => typeof extension === "function" ? [] : [extension.name]);
+    const extensionFactories = [...builtins, ...(input.extensionFactories ?? [])];
     const policy = input.resourcePolicy;
     if (policy) {
         settingsManager = SettingsManager.create(input.cwd, agentDir, { projectTrusted: false });
         settingsManager.setProjectTrusted(policy.projectTrusted);
-        const packageManager = new DefaultPackageManager({ cwd: input.cwd, agentDir, settingsManager });
+        const packageManager = new DefaultPackageManager({ cwd: input.cwd, agentDir, settingsManager, builtinExtensions: builtinNames });
         const resolved = await packageManager.resolve();
-        const discoveredExtensions = [...new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => canonicalPath(path)))];
+        const discoveredExtensions = [...new Set(resolved.extensions.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => extensionIdentity(path)))];
         const selectorSources = policy.selectorSources;
-        const extensionLayers = [selectorSources.global.extensions, selectorSources.project.extensions, selectorSources.role?.extensions, selectorSources.call?.extensions];
-        const extensionSelectors = extensionLayers.flatMap((layer) => (layer ?? []).map((original) => ({ original, matching: canonicalExtensionSelector(original, input.cwd) })));
-        const selectedExtensions = selectResourcesByLayers(extensionLayers.map((layer) => layer?.map((selector) => canonicalExtensionSelector(selector, input.cwd))), discoveredExtensions);
-        const extensionPaths = selectedExtensions.filter((path) => !WORKFLOW_HOST_ENTRIES.has(path));
-        const unmatchedExtensions = extensionSelectors.filter(({ matching }) => unmatchedResourcePatterns([matching], discoveredExtensions).length > 0).map(({ original }) => original);
+        const selection = resolveRole(undefined, {
+            cwd: input.cwd,
+            selectorSources,
+            resources: { extensions: discoveredExtensions },
+        });
+        const selectedExtensions = selection.selectedExtensions ?? [];
+        const extensionPaths = selectedExtensions.filter((path) => path.startsWith(BUILTIN_EXTENSION_PREFIX) || !isWorkflowHostEntry(path));
         policy.selectedExtensions = selectedExtensions;
-        policy.unmatchedExtensions = unmatchedExtensions;
+        policy.unmatchedExtensions = selection.unmatchedExtensions ?? [];
         const skillPaths = [...new Set(resolved.skills.filter(({ enabled, metadata }) => enabled && (policy.projectTrusted || metadata.scope !== "project")).map(({ path }) => path))];
         const updateSkillMatches = (skills) => {
             const names = [...new Set(skills.map(({ name }) => name))];
-            const skillLayers = [selectorSources.global.skills, selectorSources.project.skills, selectorSources.role?.skills, selectorSources.call?.skills];
-            const selectedSkills = selectResourcesByLayers(skillLayers, names);
+            const selected = resolveRole(undefined, { cwd: input.cwd, selectorSources, resources: { skills: names } });
+            const selectedSkills = selected.selectedSkills ?? [];
             policy.selectedSkills = selectedSkills;
-            policy.unmatchedSkills = unmatchedResourcePatterns(skillLayers.flatMap((layer) => layer ?? []), names);
+            policy.unmatchedSkills = selected.unmatchedSkills ?? [];
             return new Set(names.filter((name) => !selectedSkills.includes(name)));
         };
         resourceLoader = new DefaultResourceLoader({
@@ -229,7 +262,7 @@ async function createLocalPiSessionHandle(input, sessionStartEvent) {
             additionalExtensionPaths: extensionPaths,
             noSkills: true,
             additionalSkillPaths: [...new Set([...skillPaths, ...(input.additionalSkillPaths ?? [])])],
-            ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}),
+            extensionFactories,
             ...(contextFilesOverride ? { agentsFilesOverride: contextFilesOverride } : {}),
             skillsOverride: (base) => {
                 const disabledSkills = updateSkillMatches(base.skills);
@@ -242,10 +275,10 @@ async function createLocalPiSessionHandle(input, sessionStartEvent) {
     }
     else {
         settingsManager = SettingsManager.create(input.cwd, agentDir, { projectTrusted: true });
-        const packageManager = new DefaultPackageManager({ cwd: input.cwd, agentDir, settingsManager });
+        const packageManager = new DefaultPackageManager({ cwd: input.cwd, agentDir, settingsManager, builtinExtensions: builtinNames });
         const resolved = await packageManager.resolve();
-        const extensionPaths = [...new Set(resolved.extensions.filter(({ enabled }) => enabled).map(({ path }) => canonicalPath(path)).filter((path) => !WORKFLOW_HOST_ENTRIES.has(path)))];
-        resourceLoader = new DefaultResourceLoader({ cwd: input.cwd, agentDir, settingsManager, noExtensions: true, additionalExtensionPaths: extensionPaths, ...(input.additionalSkillPaths?.length ? { additionalSkillPaths: [...input.additionalSkillPaths] } : {}), ...(input.extensionFactories?.length ? { extensionFactories: input.extensionFactories } : {}), ...(contextFilesOverride ? { agentsFilesOverride: contextFilesOverride } : {}), ...systemPromptOptions, ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}) });
+        const extensionPaths = [...new Set(resolved.extensions.filter(({ enabled }) => enabled).map(({ path }) => extensionIdentity(path)).filter((path) => path.startsWith(BUILTIN_EXTENSION_PREFIX) || !isWorkflowHostEntry(path)))];
+        resourceLoader = new DefaultResourceLoader({ cwd: input.cwd, agentDir, settingsManager, noExtensions: true, additionalExtensionPaths: extensionPaths, ...(input.additionalSkillPaths?.length ? { additionalSkillPaths: [...input.additionalSkillPaths] } : {}), extensionFactories, ...(contextFilesOverride ? { agentsFilesOverride: contextFilesOverride } : {}), ...systemPromptOptions, ...(input.systemPromptAppend ? { appendSystemPromptOverride: (base) => [...base, input.systemPromptAppend ?? ""] } : {}) });
         await resourceLoader.reload();
     }
     const providerFailures = flushExtensionProviders(resourceLoader, modelRuntime);
@@ -256,7 +289,7 @@ async function createLocalPiSessionHandle(input, sessionStartEvent) {
         // missing, so the failure travels with the complaint rather than being
         // swallowed — otherwise a misconfigured gateway reads as a typo in a model
         // name.
-        const because = providerFailures.length > 0 ? ` (provider registration failed — ${providerFailures.join("; ")})` : "";
+        const because = providerFailures.length > 0 ? ` (provider registration failed — ${providerFailures.join("; ")})` : isLlamaModel(input.model) ? " (Pi does not expose its built-in llama.cpp provider to extension sessions; declare the llama.cpp server as a provider in models.json and use that model instead)" : "";
         throw new WorkflowError("UNKNOWN_MODEL", `Unknown model: ${input.model.provider}/${input.model.model}${because}`);
     }
     const effectiveSessionStartEvent = input.settings === undefined && sessionStartEvent === undefined ? undefined : { ...(sessionStartEvent ?? { type: "session_start", reason: "startup" }), settings: input.settings ?? Object.freeze({}) };
@@ -285,13 +318,13 @@ async function createLocalPiSessionHandle(input, sessionStartEvent) {
         await shutdown("quit").catch(() => undefined);
         throw error;
     }
-    const resourcePaths = { extensions: resourceLoader.getExtensions().extensions.filter(({ path }) => !path.startsWith("<")).map(({ resolvedPath }) => canonicalPath(resolvedPath)), skills: resourceLoader.getSkills().skills.map(({ filePath }) => canonicalPath(filePath)) };
+    const resourcePaths = { extensions: resourceLoader.getExtensions().extensions.filter(({ path }) => !path.startsWith("<")).map(({ resolvedPath }) => extensionIdentity(resolvedPath)), skills: resourceLoader.getSkills().skills.map(({ filePath }) => canonicalPath(filePath)) };
     const resourceInspection = () => {
         const extensions = resourceLoader.getExtensions();
         const skills = resourceLoader.getSkills();
         const diagnostics = [...extensions.errors.map(({ path, error }) => ({ type: "error", message: error, source: path })), ...skills.diagnostics.map(({ type, path, message }) => ({ type, message, ...(path ? { source: path } : {}) }))];
         const systemSource = systemPromptSource;
-        return { extensions: resourceLoader.getExtensions().extensions.filter(({ path }) => !path.startsWith("<")).map(({ resolvedPath }) => canonicalPath(resolvedPath)), skills: skills.skills.map(({ name }) => name), diagnostics, ...(systemSource ? { systemPromptSource: systemSource } : resourceLoader.getSystemPrompt() !== undefined ? { systemPromptSource: "Pi resource loader" } : {}) };
+        return { extensions: resourceLoader.getExtensions().extensions.filter(({ path }) => !path.startsWith("<")).map(({ resolvedPath }) => extensionIdentity(resolvedPath)), skills: skills.skills.map(({ name }) => name), diagnostics, ...(systemSource ? { systemPromptSource: systemSource } : resourceLoader.getSystemPrompt() !== undefined ? { systemPromptSource: "Pi resource loader" } : {}) };
     };
     const managedSession = Object.assign(session, {
         getLeafId: () => manager.getLeafId(),
@@ -944,7 +977,6 @@ export class WorkflowAgentExecutor {
         const roleDefinition = roleName ? this.root.agentDefinitions?.[roleName] : undefined;
         if (roleName && !roleDefinition)
             throw new WorkflowError("UNKNOWN_AGENT_TYPE", `Unknown agent role: ${roleName}`);
-        const candidateTools = inheritedTools !== undefined ? [...inheritedTools] : [...this.root.tools];
         if (inheritedTools === undefined)
             for (const pattern of roleDefinition?.tools ?? []) {
                 const body = pattern.startsWith("!") ? pattern.slice(1) : pattern;
@@ -956,37 +988,30 @@ export class WorkflowAgentExecutor {
                     }
                 }
             }
-        const selectorLayers = [
-            this.root.resourceSelectors?.tools,
-            roleDefinition?.tools,
-            options.tools,
-        ];
-        for (const pattern of options.tools ?? []) {
-            const body = pattern.startsWith("!") ? pattern.slice(1) : pattern;
-            if (!pattern.startsWith("!") && !resourcePatternHasMagic(pattern) && !candidateTools.includes(body))
-                throw new WorkflowError("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${body}`);
-        }
-        const outsideEffectiveTool = options.effectiveTools?.find((tool) => !candidateTools.includes(tool));
-        if (outsideEffectiveTool)
-            throw new WorkflowError("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${outsideEffectiveTool}`);
-        const requested = options.effectiveTools ?? selectResourcesByLayers(selectorLayers, candidateTools);
-        const forbidden = requested.find((tool) => !this.root.tools.has(tool));
-        if (forbidden)
-            throw new WorkflowError("UNKNOWN_TOOL", `Tool is outside the launching session boundary: ${forbidden}`);
-        const requestedModel = options.model ?? (roleDefinition?.model && roleDefinition.thinking && !roleDefinition.model.includes(":") ? `${roleDefinition.model}:${roleDefinition.thinking}` : roleDefinition?.model);
-        const alias = requestedModel === undefined ? undefined : modelAliasName(requestedModel, this.root.modelAliases ?? {});
-        const blockedAlias = requestedModel?.split(":", 1)[0];
-        if (requestedModel !== undefined && blockedAlias && this.root.blockedAliases?.has(blockedAlias) && !alias) {
-            const target = this.root.blockedAliasTargets?.[blockedAlias];
-            throw new WorkflowError("UNKNOWN_MODEL", `Unknown model alias ${requestedModel}${target ? ` resolved to ${target}` : ""}${this.root.settingsPath ? ` (settings: ${this.root.settingsPath})` : ""}`);
-        }
-        const model = options.modelOverride ?? parseModel(requestedModel, this.root.model, this.root.modelAliases, this.root.knownModels ?? this.root.availableModels, this.root.settingsPath);
-        const availableModels = this.root.knownModels ?? this.root.availableModels ?? new Set([modelCapability(this.root.model)]);
-        if (!availableModels.has(modelCapability(model)))
-            throw new WorkflowError("UNKNOWN_MODEL", `Unknown model${requestedModel ? ` ${requestedModel} resolved to ${modelCapability(model)}` : ""}${this.root.settingsPath ? ` (settings: ${this.root.settingsPath})` : ""}`);
-        const overrideSystemPrompt = roleDefinition?.overrideSystemPrompt === true;
-        const contextFiles = options.contextFiles ?? roleDefinition?.contextFiles;
-        return { model, ...(alias && requestedModel ? { requestedModel } : {}), tools: requested, ...(overrideSystemPrompt ? { systemPrompt: roleDefinition.prompt ?? "" } : {}), systemPromptAppend: overrideSystemPrompt ? "" : roleDefinition?.prompt ?? "", ...(contextFiles === undefined ? {} : { contextFiles: [...contextFiles] }) };
+        const resolved = resolveRole(roleName, {
+            cwd: this.root.cwd,
+            ...(roleDefinition === undefined ? {} : { definition: roleDefinition }),
+            ...(this.root.agentDefinitions === undefined ? {} : { definitions: this.root.agentDefinitions }),
+            ...(this.root.agentDir === undefined ? {} : { agentDir: this.root.agentDir }),
+            selectorSources: { global: this.root.resourceSelectors ?? {}, project: {} },
+            ...(this.root.modelAliases === undefined ? {} : { modelAliases: this.root.modelAliases }),
+            ...(this.root.knownModels === undefined ? {} : { knownModels: this.root.knownModels }),
+            ...(this.root.availableModels === undefined ? {} : { availableModels: this.root.availableModels }),
+            ...(this.root.blockedAliases === undefined ? {} : { blockedAliases: this.root.blockedAliases }),
+            ...(this.root.blockedAliasTargets === undefined ? {} : { blockedAliasTargets: this.root.blockedAliasTargets }),
+            ...(this.root.settingsPath === undefined ? {} : { settingsPath: this.root.settingsPath }),
+            rootModel: this.root.model,
+            rootTools: this.root.tools,
+            ...(inheritedTools === undefined ? {} : { inheritedTools }),
+            ...(options.model === undefined ? {} : { model: options.model }),
+            ...(options.modelOverride === undefined ? {} : { modelOverride: options.modelOverride }),
+            ...(options.tools === undefined ? {} : { tools: options.tools }),
+            ...(options.skills === undefined ? {} : { skills: options.skills }),
+            ...(options.extensions === undefined ? {} : { extensions: options.extensions }),
+            ...(options.contextFiles === undefined ? {} : { contextFiles: options.contextFiles }),
+            ...(options.effectiveTools === undefined ? {} : { effectiveTools: options.effectiveTools }),
+        });
+        return { model: physicalModel(resolved.model ?? this.root.model, this.root.modelAliases, this.root.knownModels, this.root.settingsPath), ...(resolved.requestedModel === undefined ? {} : { requestedModel: resolved.requestedModel }), tools: resolved.tools ?? [], ...(resolved.overrideSystemPrompt ? { systemPrompt: resolved.prompt } : {}), systemPromptAppend: resolved.overrideSystemPrompt ? "" : resolved.prompt, ...(resolved.contextFiles === undefined ? {} : { contextFiles: resolved.contextFiles }) };
     }
     async execute(task, options, signal, customTools = [], setSteer, beforeRetry) {
         const executionSignal = signal ?? this.root.runContext?.signal;
@@ -1454,6 +1479,7 @@ export class FairAgentScheduler {
         const agentTool = defineTool({
             name: "agent", label: "Child Agent", description: "Start a direct child agent",
             parameters: Type.Object({ prompt: Type.String(), label: Type.String(), tools: Type.Optional(Type.Array(Type.String())), skills: Type.Optional(Type.Array(Type.String())), extensions: Type.Optional(Type.Array(Type.String())), model: Type.Optional(Type.String()), role: Type.Optional(Type.String()), contextFiles: Type.Optional(Type.Array(Type.String())), outputSchema: Type.Optional(Type.Record(Type.String(), Type.Unknown())), retries: Type.Optional(Type.Integer({ minimum: 0 })), timeoutMs: Type.Optional(Type.Union([Type.Integer({ minimum: 1 }), Type.Null()])) }, { additionalProperties: true }),
+            outputSchema: Type.Object({ id: Type.String() }),
             execute: async (_id, params) => {
                 if (!isChildAgentToolParams(params))
                     throw new WorkflowError("INVALID_METADATA", "Invalid child agent parameters");
@@ -1466,14 +1492,15 @@ export class FairAgentScheduler {
                 Reflect.deleteProperty(agentOptions, "prompt");
                 const options = { label: params.label, requestedLabel: params.label, cwd: parent.options.cwd, tools, agentOptions, ...(params.skills ? { skills: params.skills } : {}), ...(params.extensions ? { extensions: params.extensions } : {}), ...(params.model ? { model: params.model } : {}), ...(params.role ? { role: params.role } : {}), ...(params.contextFiles ? { contextFiles: params.contextFiles } : {}), ...(outputSchema === undefined ? {} : { schema: outputSchema }), ...(params.retries === undefined ? {} : { retries: params.retries }), ...(params.timeoutMs === undefined ? {} : { timeoutMs: params.timeoutMs }) };
                 const child = this.spawn(parent.runId, params.prompt, options, parentId);
-                return { content: [{ type: "text", text: JSON.stringify({ id: child.id }) }], details: { id: child.id } };
+                return { content: [{ type: "text", text: JSON.stringify({ id: child.id }) }], details: { id: child.id }, structuredContent: { id: child.id } };
             },
         });
         const resultTool = defineTool({
             name: "get_subagent_result", label: "Child Result", description: "Wait for a direct child and return its result once; repeated retrieval fails with AGENT_RESULT_COLLECTED",
             parameters: Type.Object({ id: Type.String() }),
+            outputSchema: Type.Object({ id: Type.String(), ok: Type.Boolean(), value: Type.Optional(Type.Unknown()), error: Type.Optional(Type.Object({ code: Type.String(), message: Type.String() })) }),
             execute: async (_id, params) => { const value = await this.result(parentId, params.id); if (!value.ok && value.error.code === "BUDGET_EXHAUSTED")
-                throw new WorkflowError("BUDGET_EXHAUSTED", value.error.message); return { content: [{ type: "text", text: JSON.stringify(value) }], details: value }; }
+                throw new WorkflowError("BUDGET_EXHAUSTED", value.error.message); return { content: [{ type: "text", text: JSON.stringify(value) }], details: value, structuredContent: value }; }
         });
         const steerTool = defineTool({
             name: "steer_subagent", label: "Steer Child", description: "Steer a running direct child",

package/dist/src/background-widget.d.ts

@@ -22,6 +22,23 @@ export type BackgroundWidgetAPI = Pick<ExtensionAPI, "appendEntry" | "on"> & {
     registerEntryRenderer?: ExtensionAPI["registerEntryRenderer"];
     registerShortcut?: ExtensionAPI["registerShortcut"];
 };
+/**
+ * Repaint interval. Fast enough that the spinner reads as motion rather than a
+ * stutter; the underlying data is only re-read when an event says it changed.
+ */
+export declare const REPAINT_MS = 125;
+/**
+ * How long an agent may go without an event before the widget says so.
+ *
+ * Deliberately shorter than the core's own stall threshold. That one answers
+ * "is this agent dead"; this one answers "should you go and look". An agent
+ * asking a question in its own pane produces exactly this signature — no tool
+ * calls, no events, waiting on a person — and the core cannot see it, since the
+ * pane is a separate process. Three minutes is longer than any single stretch
+ * of thinking and far shorter than the ten minutes it takes to be declared
+ * stalled.
+ */
+export declare const QUIET_MS: number;
 /**
  * Overrides the switch above, for the tests that cover navigation.
  *
@@ -32,6 +49,11 @@ export type BackgroundWidgetAPI = Pick<ExtensionAPI, "appendEntry" | "on"> & {
 export declare const __navigationForTests: {
     enabled: boolean;
 };
+/**
+ * Paints text in a themed colour role. Falls back to the bare text when no
+ * theme is available, so a frame rendered outside the TUI is still legible.
+ */
+export type Paint = (role: Parameters<Theme["fg"]>[0], text: string) => string;
 interface ReceiptAgent {
     id?: string;
     parentId?: string;
@@ -62,8 +84,47 @@ interface Receipt {
     agents: readonly ReceiptAgent[];
     error?: string;
 }
+/** Status mark for a finished-or-running unit of work. */
+export declare function mark(state: string | undefined, now: number, paint: Paint, runState?: string): string;
+export declare function formatElapsed(ms: number): string;
 export declare function formatTokens(tokens: number | undefined): string;
 export declare function formatCost(cost: number | undefined): string;
+interface Row {
+    text: string;
+    /**
+     * Numbers to set against the right-hand rule rather than trailing the name.
+     *
+     * Names are ragged — a phase called `plan` beside one called `refactor-2` —
+     * so numbers that follow them are ragged too, and comparing the cost of one
+     * agent against another means reading across a gap that moves on every row.
+     * Held to the right edge, they form a column.
+     */
+    right?: string;
+    /** 2 = a run header or something needing an answer, 1 = live or failed work, 0 = finished detail. */
+    rank: number;
+    /**
+     * Set on the one row that stands for a whole run.
+     *
+     * Rank alone cannot protect it: a checkpoint needs an answer and so shares
+     * the top rank, and enough of them would spend the budget before a later
+     * run's header is reached. A run missing its header is not a terse run, it
+     * is an invisible one.
+     */
+    header?: boolean;
+    /**
+     * A stable name for a row that can be folded shut, and the key of the row it
+     * hangs from. Together they let the cursor walk a tree rather than a list:
+     * collapsing a phase hides its agents, collapsing a run hides everything
+     * under it, and the choice survives the repaint that follows.
+     */
+    key?: string;
+    parent?: string;
+}
+/**
+ * The box around the live rows, shared with the subagent widget so both sit
+ * under the editor in one style.
+ */
+export declare function drawFrame(title: string, hint: string, body: readonly Pick<Row, "text" | "right">[], width: number, paint: Paint, accent: (text: string) => string, scrollbar?: (index: number) => string | undefined): string[];
 /** The receipt as transcript lines: the widget's tree, one level deeper. */
 export declare function renderReceipt(data: Receipt, expanded: boolean, theme: Theme): string[];
 export interface BackgroundWidgetController {