@esso0428/pi-subagents 0.17.6 → 0.17.8

package/dist/structured-output.d.ts

@@ -0,0 +1,62 @@
+/**
+ * structured-output.ts — the synthetic tool behind `agent(prompt, { schema })`.
+ *
+ * A workflow script that passes a `schema` wants an *object* back, not prose it
+ * has to parse. Claude Code does this by giving the child a `StructuredOutput`
+ * tool whose input schema is the caller's schema, so the provider fills the
+ * fields, and returning the validated payload as the agent's result.
+ *
+ * We do the same, with one gap named up front: Claude Code *forces* the call,
+ * and we cannot. `toolChoice` exists in pi-ai's provider layer but is not
+ * plumbed through `AgentSession`, so an extension has no way to require a
+ * particular tool. What we have instead is three softer pressures —
+ *
+ *   1. `constrainedSampling`, so providers that support it hold the payload to
+ *      the schema at sampling time;
+ *   2. the tool's description, snippet and guideline, which say the answer must
+ *      come through this call;
+ *   3. validation here, answering a bad payload with `isError` so the model
+ *      sees what was wrong and calls again inside the same run.
+ *
+ * — and, when all three fail, one more prompt from `runAgent`. See
+ * {@link structuredRetryPrompt}.
+ *
+ * The name matches Claude Code's exactly, so a ported prompt that mentions
+ * `StructuredOutput` is still telling the truth.
+ */
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { CompiledSchema } from "./workflow/json-schema.js";
+/**
+ * Deliberately NOT added to `SUBAGENT_TOOL_NAMES`: that list becomes
+ * `EXCLUDED_TOOL_NAMES`, which is exactly the denial this tool has to avoid.
+ * Nor to `BUILTIN_TOOL_NAMES` — it is ours to inject, never a name a user may
+ * ask for in an agent's `tools:` frontmatter.
+ */
+export declare const STRUCTURED_OUTPUT_TOOL_NAME = "StructuredOutput";
+/** What the child produced, filled in as the tool is called. */
+export interface StructuredCapture {
+    /** The last payload that validated, canonicalised. Absent until one does. */
+    json?: string;
+    /** Why the most recent attempt was rejected, for the retry prompt. */
+    lastError?: string;
+    /** Whether the tool was called at all — "never tried" reads differently. */
+    called: boolean;
+}
+export declare function createStructuredCapture(): StructuredCapture;
+/**
+ * Build the tool for one child.
+ *
+ * `capture` is the box the caller reads afterwards. It is passed in rather than
+ * returned so `runAgent` owns its lifetime and can consult it on every exit
+ * path, including the ones where the tool was never reached.
+ */
+export declare function createStructuredOutputTool(compiled: CompiledSchema, capture: StructuredCapture): ToolDefinition;
+/**
+ * The one extra prompt sent when a run ended with nothing captured.
+ *
+ * Distinguishes "never called it" from "called it wrongly" — the two need
+ * different corrections, and telling a model it got the shape wrong when it
+ * never answered at all sends it looking for a mistake it did not make.
+ */
+export declare function structuredRetryPrompt(capture: StructuredCapture): string;
+//# sourceMappingURL=structured-output.d.ts.map

package/dist/structured-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-output.d.ts","sourceRoot":"","sources":["../src/structured-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAClF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,qBAAqB,CAAC;AAE9D,gEAAgE;AAChE,MAAM,WAAW,iBAAiB;IAChC,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,uBAAuB,IAAI,iBAAiB,CAE3D;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,iBAAiB,GACzB,cAAc,CAqDhB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAKxE"}

package/dist/structured-output.js

@@ -0,0 +1,113 @@
+/**
+ * structured-output.ts — the synthetic tool behind `agent(prompt, { schema })`.
+ *
+ * A workflow script that passes a `schema` wants an *object* back, not prose it
+ * has to parse. Claude Code does this by giving the child a `StructuredOutput`
+ * tool whose input schema is the caller's schema, so the provider fills the
+ * fields, and returning the validated payload as the agent's result.
+ *
+ * We do the same, with one gap named up front: Claude Code *forces* the call,
+ * and we cannot. `toolChoice` exists in pi-ai's provider layer but is not
+ * plumbed through `AgentSession`, so an extension has no way to require a
+ * particular tool. What we have instead is three softer pressures —
+ *
+ *   1. `constrainedSampling`, so providers that support it hold the payload to
+ *      the schema at sampling time;
+ *   2. the tool's description, snippet and guideline, which say the answer must
+ *      come through this call;
+ *   3. validation here, answering a bad payload with `isError` so the model
+ *      sees what was wrong and calls again inside the same run.
+ *
+ * — and, when all three fail, one more prompt from `runAgent`. See
+ * {@link structuredRetryPrompt}.
+ *
+ * The name matches Claude Code's exactly, so a ported prompt that mentions
+ * `StructuredOutput` is still telling the truth.
+ */
+import { defineTool } from "@earendil-works/pi-coding-agent";
+/**
+ * Deliberately NOT added to `SUBAGENT_TOOL_NAMES`: that list becomes
+ * `EXCLUDED_TOOL_NAMES`, which is exactly the denial this tool has to avoid.
+ * Nor to `BUILTIN_TOOL_NAMES` — it is ours to inject, never a name a user may
+ * ask for in an agent's `tools:` frontmatter.
+ */
+export const STRUCTURED_OUTPUT_TOOL_NAME = "StructuredOutput";
+export function createStructuredCapture() {
+    return { called: false };
+}
+/**
+ * Build the tool for one child.
+ *
+ * `capture` is the box the caller reads afterwards. It is passed in rather than
+ * returned so `runAgent` owns its lifetime and can consult it on every exit
+ * path, including the ones where the tool was never reached.
+ */
+export function createStructuredOutputTool(compiled, capture) {
+    return defineTool({
+        name: STRUCTURED_OUTPUT_TOOL_NAME,
+        label: "Structured Output",
+        description: "Report your final answer. Call this exactly once, with the complete result, and put everything the "
+            + "caller needs inside the arguments — text written outside this call is discarded. If a call is "
+            + "rejected for not matching the schema, fix the reported fields and call it again.",
+        promptSnippet: "Report your final answer as structured data",
+        promptGuidelines: [
+            "Your final answer MUST be reported by calling StructuredOutput. Prose outside that call is discarded.",
+        ],
+        // The caller's schema *is* the tool's input schema, verbatim — that is what
+        // makes the provider fill the fields. pi types this as TypeBox's `TSchema`,
+        // which v1 defines as an open interface, so a plain JSON Schema satisfies
+        // it without a cast at runtime or a conversion at author time.
+        parameters: compiled.schema,
+        // "prefer", not "require": a provider that cannot constrain sampling should
+        // fall through to validation-and-retry rather than fail the call outright.
+        constrainedSampling: { type: "json_schema", strict: "prefer" },
+        // Models occasionally send the whole payload as one JSON string instead of
+        // an object. Recovering that costs nothing and saves a whole retry.
+        prepareArguments: (args) => {
+            if (typeof args !== "string")
+                return args;
+            try {
+                return JSON.parse(args);
+            }
+            catch {
+                return args;
+            }
+        },
+        execute: async (_toolCallId, params) => {
+            capture.called = true;
+            const verdict = compiled.check(params);
+            if (verdict !== true) {
+                capture.lastError = verdict;
+                // `isError` puts the reason in front of the model as a tool result, so
+                // it can correct itself inside this same run. This is where most
+                // mismatches are resolved; the prompt-level retry is the backstop.
+                return {
+                    content: [{
+                            type: "text",
+                            text: `StructuredOutput did not match the required schema:\n${verdict}\nCall it again with a corrected value.`,
+                        }],
+                    isError: true,
+                    details: {},
+                };
+            }
+            // Last valid call wins: a model that calls twice meant the second one.
+            capture.json = JSON.stringify(params);
+            capture.lastError = undefined;
+            return { content: [{ type: "text", text: "Recorded." }], details: {} };
+        },
+    });
+}
+/**
+ * The one extra prompt sent when a run ended with nothing captured.
+ *
+ * Distinguishes "never called it" from "called it wrongly" — the two need
+ * different corrections, and telling a model it got the shape wrong when it
+ * never answered at all sends it looking for a mistake it did not make.
+ */
+export function structuredRetryPrompt(capture) {
+    const reason = capture.called && capture.lastError !== undefined
+        ? `Your last ${STRUCTURED_OUTPUT_TOOL_NAME} call did not match the required schema: ${capture.lastError}`
+        : `You did not call ${STRUCTURED_OUTPUT_TOOL_NAME}, so your answer was not recorded.`;
+    return `${reason}\n\nCall ${STRUCTURED_OUTPUT_TOOL_NAME} now with your complete final answer. Do not reply with prose.`;
+}
+//# sourceMappingURL=structured-output.js.map

package/dist/structured-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-output.js","sourceRoot":"","sources":["../src/structured-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,UAAU,EAAuB,MAAM,iCAAiC,CAAC;AAGlF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,kBAAkB,CAAC;AAY9D,MAAM,UAAU,uBAAuB;IACrC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CACxC,QAAwB,EACxB,OAA0B;IAE1B,OAAO,UAAU,CAAC;QAChB,IAAI,EAAE,2BAA2B;QACjC,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EACT,qGAAqG;cACnG,gGAAgG;cAChG,kFAAkF;QACtF,aAAa,EAAE,6CAA6C;QAC5D,gBAAgB,EAAE;YAChB,uGAAuG;SACxG;QACD,4EAA4E;QAC5E,4EAA4E;QAC5E,0EAA0E;QAC1E,+DAA+D;QAC/D,UAAU,EAAE,QAAQ,CAAC,MAAe;QACpC,4EAA4E;QAC5E,2EAA2E;QAC3E,mBAAmB,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE;QAC9D,2EAA2E;QAC3E,oEAAoE;QACpE,gBAAgB,EAAE,CAAC,IAAa,EAAE,EAAE;YAClC,IAAI,OAAO,IAAI,KAAK,QAAQ;gBAAE,OAAO,IAAa,CAAC;YACnD,IAAI,CAAC;gBACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAU,CAAC;YACnC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO,IAAa,CAAC;YACvB,CAAC;QACH,CAAC;QACD,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE;YACrC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;YACtB,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACvC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC;gBAC5B,uEAAuE;gBACvE,iEAAiE;gBACjE,mEAAmE;gBACnE,OAAO;oBACL,OAAO,EAAE,CAAC;4BACR,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,wDAAwD,OAAO,yCAAyC;yBAC/G,CAAC;oBACF,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE,EAAE;iBACZ,CAAC;YACJ,CAAC;YACD,uEAAuE;YACvE,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YACtC,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;YAC9B,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;QACzE,CAAC;KACF,CAAmB,CAAC;AACvB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA0B;IAC9D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS;QAC9D,CAAC,CAAC,aAAa,2BAA2B,4CAA4C,OAAO,CAAC,SAAS,EAAE;QACzG,CAAC,CAAC,oBAAoB,2BAA2B,oCAAoC,CAAC;IACxF,OAAO,GAAG,MAAM,YAAY,2BAA2B,gEAAgE,CAAC;AAC1H,CAAC"}

package/dist/types.d.ts

@@ -11,12 +11,25 @@ export type SubagentType = string;
 export declare const DEFAULT_AGENT_NAMES: readonly ["general-purpose", "Explore", "Plan"];
 /** Memory scope for persistent agent memory. */
 export type MemoryScope = "user" | "project" | "local";
-/** Isolation mode for agent execution. */
-export type IsolationMode = "worktree";
+/**
+ * Isolation mode for agent execution.
+ *
+ * `"off"` exists for the caller's benefit, not the runtime's: models that fill
+ * every optional parameter had no legal way to decline a single-value
+ * `isolation` field and kept spawning worktrees they had just reasoned their
+ * way out of (#231, #184). It is an input spelling only —
+ * `resolveAgentInvocationConfig` collapses it to `undefined`, so nothing
+ * downstream sees a value other than `"worktree"`. In an agent file it is a
+ * genuine veto, since agent config outranks tool-call params.
+ */
+export type IsolationMode = "worktree" | "off";
 /** Unified agent configuration — used for both default and user-defined agents. */
 export interface AgentConfig {
     name: string;
+    /** UI name. `display_name` wins; Claude Code's `name` is accepted as a fallback. */
     displayName?: string;
+    /** Claude Code-compatible name color (named color or #RRGGBB). */
+    color?: string;
     description: string;
     builtinToolNames?: string[];
     /** Raw `ext:` selector entries from the `tools:` CSV, e.g. ["ext:foo", "ext:bar/x"].
@@ -40,6 +53,11 @@ export interface AgentConfig {
     outputTranscript?: boolean;
     /** Optional session directory used when persistSession is true. Omitted = pi's normal session location. */
     sessionDir?: string;
+    /**
+     * Nested delegation, off by default: undefined = no nested tools;
+     * "all" = any enabled agent; string[] = only those agent types.
+     */
+    allowedSubagents?: "all" | string[];
     systemPrompt: string;
     promptMode: "replace" | "append";
     /** Default for spawn: fork parent conversation. undefined = caller decides. */
@@ -50,7 +68,10 @@ export interface AgentConfig {
     isolated?: boolean;
     /** Persistent memory scope — agents with memory get a persistent directory and MEMORY.md */
     memory?: MemoryScope;
-    /** Isolation mode — "worktree" runs the agent in a temporary git worktree */
+    /**
+     * Isolation mode — "worktree" runs the agent in a temporary git worktree,
+     * "off" refuses one even when the caller asks (frontmatter outranks params).
+     */
     isolation?: IsolationMode;
     /** true = this is an embedded default agent (informational) */
     isDefault?: boolean;
@@ -58,6 +79,8 @@ export interface AgentConfig {
     enabled?: boolean;
     /** Where this agent was loaded from */
     source?: "default" | "project" | "global";
+    /** Path of the .md it was loaded from. Unset for embedded defaults. */
+    sourcePath?: string;
 }
 export type JoinMode = 'async' | 'group' | 'smart';
 /**
@@ -68,9 +91,75 @@ export type JoinMode = 'async' | 'group' | 'smart';
  * - `off`: hide the widget entirely.
  */
 export type WidgetMode = 'all' | 'background' | 'off';
+/**
+ * How much of the conversation viewer's transcript is rendered as Markdown.
+ * - `off`: every line wraps as literal text, as it did before the mode existed.
+ * - `assistant`: assistant text renders as Markdown; tool results stay verbatim
+ *   and dim. The default, because assistant text *is* Markdown by contract
+ *   while a tool result is arbitrary bytes — a Markdown pass over a log or a
+ *   diff eats `#` from shell comments, swallows a `---` line into a setext
+ *   heading, re-fences indented output and redraws `| a | b |` as a table.
+ *   (Ordered-list renumbering is the one such rewrite actively suppressed —
+ *   see `MARKDOWN_OPTIONS` — because it silently changes data, not layout.)
+ * - `all`: tool results render as Markdown too, for tools that genuinely emit
+ *   it (#210's `ctx_execute`), accepting the rewrites above on ones that don't.
+ */
+export type ViewerMarkdownMode = 'off' | 'assistant' | 'all';
+/**
+ * How `@handle message` starts an agent that is not already running.
+ * - `model`: inject Claude Code's `agent_mention` reminder and let the main
+ *   model spawn it with the `Agent` tool, which is what Claude Code does.
+ * - `direct`: spawn it here, immediately, with the typed message as its prompt
+ *   and no main-model turn spent.
+ * - `off`: `@` means only "attach a file" again.
+ *
+ * Messaging a running agent and resuming a finished one are direct in every
+ * mode — Claude Code only differs from us on the *new* invocation.
+ */
+export type AgentMentionMode = 'model' | 'direct' | 'off';
+/**
+ * What survives a record's eviction so `@handle` keeps working. The live record
+ * is discarded after ~10 minutes, but the pi session it wrote is still on disk,
+ * and this is the little that is needed to find and describe it again.
+ */
+export interface AgentTombstone {
+    handle: string;
+    alias?: string;
+    id: string;
+    type: SubagentType;
+    description: string;
+    /** Always set — a record with no session file is never tombstoned. */
+    sessionFile: string;
+    completedAt: number;
+}
+/**
+ * What `@handle` resolved to: an agent still in memory, or the remains of one
+ * whose conversation can be reopened from disk.
+ */
+export type MentionResolution = {
+    kind: "live";
+    record: AgentRecord;
+} | {
+    kind: "tombstone";
+    entry: AgentTombstone;
+};
 export interface AgentRecord {
     id: string;
     type: SubagentType;
+    /**
+     * Typeable name for the `@handle message` prompt mention, derived from the
+     * agent type and numbered when siblings collide (`explore`, `explore-2`).
+     * Top-level agents only — nested children are hidden from every top-level
+     * surface, so nothing can address them.
+     */
+    handle?: string;
+    /**
+     * A second, memorable handle from the spawner's `name` (`@auth-audit`), drawn
+     * from the same namespace as `handle` so the two can never collide. Purely
+     * additive: `handle` is assigned regardless, so a named agent stays reachable
+     * by its type and `@explore` never comes to mean "start another one".
+     */
+    alias?: string;
     description: string;
     status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
     result?: string;
@@ -81,6 +170,22 @@ export interface AgentRecord {
     session?: AgentSession;
     abortController?: AbortController;
     promise?: Promise<string>;
+    /**
+     * A caller is awaiting this agent inline (`spawnAndWait`) — what
+     * `maxConcurrentForeground` bounds. Distinct from `isBackground === false`,
+     * which says only that the agent has an inline result surface: a detached
+     * cross-extension RPC spawn is foreground by that measure and yet blocks
+     * nobody, so it takes no slot.
+     */
+    blocking?: boolean;
+    /**
+     * Present only while the record is "queued": resolves when it leaves the
+     * queue, started or aborted. `spawnAndWait` waits on this because a queued
+     * record has no `promise` yet. Always resolves, never rejects — a rejection
+     * would escape into the caller's tool `execute` and take down pi's whole
+     * Promise.all tool batch.
+     */
+    startGate?: Promise<void>;
     groupId?: string;
     joinMode?: JoinMode;
     /** Set when result was already consumed via get_subagent_result — suppresses completion notification. */
@@ -107,8 +212,17 @@ export interface AgentRecord {
     historyFile?: string;
     /** Project-relative durable transcript path persisted in the parent session. */
     transcriptPath?: string;
-    /** Cleanup function for the output file stream subscription. */
+    /**
+     * The agent's pi session file, when it was persisted (`persist_session`, or
+     * the `rememberAgents` default). Captured so a mention can reopen the
+     * conversation after the record itself has been evicted; undefined for an
+     * in-memory session, which leaves nothing to reopen.
+     */
+    sessionFile?: string;
+    /** Cleanup function for the optional `.output` stream subscription. */
     outputCleanup?: () => void;
+    /** Cleanup function for the mandatory durable `.pi-subagents` history stream. */
+    historyCleanup?: () => void;
     /**
      * Lifetime usage breakdown, accumulated via `message_end` events. Survives
      * compaction. Total = input + output + cacheWrite (cacheRead deliberately
@@ -130,15 +244,61 @@ export interface AgentRecord {
     isBackground?: boolean;
     /** Resolved spawn params, captured for UI display. Fixed at spawn time. */
     invocation?: AgentInvocation;
+    /** Nesting depth: top-level subagent = 1. */
+    depth?: number;
+    /**
+     * The validated `StructuredOutput` payload, as canonical JSON.
+     *
+     * Set only when the spawn asked for a schema. Separate from `result` because
+     * `result` is prose for a reader — previewed in the widget, written to the
+     * transcript, and appended to with the worktree branch note — and JSON that
+     * has been appended to no longer parses.
+     */
+    structuredJson?: string;
+    /** Whether the child needed the extra structured-output prompt. */
+    structuredRetried?: boolean;
+    /** Parent agent ID for ownership-scoped nested controls. */
+    parentAgentId?: string;
+    /**
+     * The workflow run that owns this child, when a workflow spawned it.
+     *
+     * Owned the same way a nested child is owned by its parent: filtered out of
+     * every top-level surface, and outside the `maxConcurrent` pool. See
+     * `isTopLevelAgent`.
+     */
+    workflowId?: string;
+    /** Effective inherited nesting cap for this branch. */
+    maxSubagentDepth?: number;
+    /**
+     * Session id of the root (main) session this branch descends from. Nested
+     * spawns inherit it so their transcripts file under the same session
+     * directory as their ancestors' instead of the child session's own id.
+     */
+    rootSessionId?: string;
 }
+/**
+ * What a session reports as its level: pi's `ThinkingLevel` plus the `"off"` a
+ * model with thinking disabled reports. Display-only — spawning still takes a
+ * `ThinkingLevel`, so this widening cannot leak into an invocation.
+ */
+export type EffectiveThinkingLevel = ThinkingLevel | "off";
 export interface AgentInvocation {
-    /** Short display name, e.g. "haiku" — only set when different from parent. */
+    /** Short display name for tight rows, e.g. "haiku 4.5". Always set once known. */
     modelName?: string;
-    /** Effective model captured from the child session, including inherited models. */
-    effectiveModelName?: string;
-    /** Requested/ effective thinking level. */
-    effectiveThinking?: AgentSession["thinkingLevel"];
-    thinking?: ThinkingLevel;
+    /** Canonical `provider/id`, for surfaces with room to disambiguate providers. */
+    modelId?: string;
+    /** The level actually in effect, once a session exists to report one. */
+    thinking?: EffectiveThinkingLevel;
+    /**
+     * What the caller asked for, kept only when they did not get it — pi clamped
+     * the level to the model's capabilities, or an agent file's frontmatter
+     * outranked the parameter (#182). The snapshot exists to answer "did the spawn
+     * honor my instructions?" (#62), which it cannot do if the request is lost, so
+     * neither `requested*` field is overwritten once set.
+     */
+    requestedThinking?: EffectiveThinkingLevel;
+    /** The caller's `model` parameter, as written, when an agent file's pin won. */
+    requestedModel?: string;
     maxTurns?: number;
     isolated?: boolean;
     inheritContext?: boolean;
@@ -154,6 +314,12 @@ export interface NotificationDetails {
     turnCount: number;
     maxTurns?: number;
     totalTokens: number;
+    /**
+     * Estimated cost in USD, from pi's per-message `usage.cost.total`. Always
+     * populated (0 when the model has no pricing); the renderer decides whether
+     * to show it, per the `showCost` setting.
+     */
+    totalCost?: number;
     durationMs: number;
     outputFile?: string;
     error?: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/ui/agent-mention.d.ts

@@ -0,0 +1,83 @@
+/**
+ * agent-mention.ts — what `@` can address, and the suggestions pi renders for it.
+ *
+ * A subagent is addressable whether or not it is currently running: a live
+ * record is messaged or resumed, an evicted one whose session is still on disk
+ * is reopened, and an agent *type* with no instance at all is started. That is
+ * the point of the handle — `@explore` means the Explore agent, not "the
+ * Explore process that happens to exist right now" — so the roster below unions
+ * all three, and the dispatcher and the popup read the same list.
+ *
+ * Rows are per *agent*, not per handle. An agent given a `name` holds two names
+ * (its alias and its type-derived handle) and both resolve, but it lists once,
+ * under the alias, with its type moved into the description so the row still
+ * says what it is.
+ *
+ * pi's `CombinedAutocompleteProvider` already owns `@`, where it means "attach a
+ * file". Extensions can wrap it (`ctx.ui.addAutocompleteProvider`), so this
+ * provider adds the `@` tokens that name an agent and delegates everything else
+ * — including all of `applyCompletion`, whose `@`-branch already inserts
+ * `item.value` plus a trailing space, which is exactly what a handle needs.
+ *
+ * Matching mirrors Claude Code: case-insensitive prefix, not fuzzy. What it does
+ * NOT mirror is Claude Code dropping files whenever an agent matches. Here `@` is
+ * pi's file picker first, and the handles are additive, so a token matching both
+ * lists both — agents first. Suppressing on any match sounds narrow and is not:
+ * an empty token prefix-matches every handle, so a bare `@` — the gesture people
+ * use to browse files — would offer no files at all, and a single letter
+ * beginning any handle would do the same.
+ *
+ * Both halves ship under ONE `prefix`, which is sound because wherever BOTH sides
+ * produce rows they measured the same span. pi's `extractAtPrefix` takes the
+ * token after the last of `{space, tab, ", ', =}` and keeps it only if it starts
+ * with `@`; `MENTION_TRIGGER` matches `@[\w-]*` at the cursor, after start-of-line
+ * or `[\s。、？！]`. Where those two disagree, exactly one side answers and there
+ * is nothing to merge: `@src/index.ts` and `@"my file` are pi's alone (no handle
+ * matches), `=@ex` is pi's alone (`=` is a delimiter to pi, not a boundary to us),
+ * and `。@ex` is ours alone (the reverse). A merged response therefore never
+ * carries a prefix from one side and an item from the other.
+ *
+ * Offering never-started types is a deliberate step beyond Claude Code, whose
+ * registry holds only live tasks, so an agent you had not launched yet was
+ * unaddressable.
+ */
+import type { AutocompleteProvider } from "@earendil-works/pi-tui";
+import type { AgentManager } from "../agent-manager.js";
+import type { AgentRecord, AgentTombstone } from "../types.js";
+/**
+ * One thing `@` can address, and what sending to it will do. `typeLabel` is the
+ * agent's `display_name`, resolved by the caller: this module stays independent
+ * of the type registry, but the popup must agree with FleetView and the widget,
+ * which both render the label rather than the raw type.
+ */
+export type MentionTarget = {
+    kind: "record";
+    handle: string;
+    record: AgentRecord;
+    typeLabel: string;
+} | {
+    kind: "tombstone";
+    handle: string;
+    entry: AgentTombstone;
+    typeLabel: string;
+} | {
+    kind: "type";
+    handle: string;
+    type: string;
+    description: string;
+};
+/** The registry facts the roster needs, so it stays independent of agent-types. */
+export type TypeInfo = {
+    name: string;
+    description: string;
+};
+/**
+ * Everything `@` can reach, in the order the popup lists it: steerable agents
+ * first, then the other live ones earliest-launched, then agent types with no
+ * live instance. A type whose handle a record already holds is omitted — that
+ * name addresses the existing agent, which is what makes `@explore` mean
+ * "message the one that's running" and only otherwise "start one".
+ */
+export declare function mentionRoster(manager: AgentManager, types: readonly TypeInfo[], displayNameOf?: (type: string) => string): MentionTarget[];
+export declare function createMentionProvider(current: AutocompleteProvider, roster: () => MentionTarget[], isEnabled: () => boolean): AutocompleteProvider;
+//# sourceMappingURL=agent-mention.d.ts.map

package/dist/ui/agent-mention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-mention.d.ts","sourceRoot":"","sources":["../../src/ui/agent-mention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAoB,oBAAoB,EAA2B,MAAM,wBAAwB,CAAC;AAC9G,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC1E;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/E;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,mFAAmF;AACnF,MAAM,MAAM,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,YAAY,EACrB,KAAK,EAAE,SAAS,QAAQ,EAAE,EAG1B,aAAa,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAqB,GACrD,aAAa,EAAE,CAsCjB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,oBAAoB,EAC7B,MAAM,EAAE,MAAM,aAAa,EAAE,EAC7B,SAAS,EAAE,MAAM,OAAO,GACvB,oBAAoB,CA0DtB"}