@ymy88/pi-subagents 0.0.0-stage → 0.24.0

package/dist/agent-record-entry.d.ts

@@ -0,0 +1,96 @@
+/**
+ * agent-record-entry.ts — what a finished top-level agent leaves behind in the session.
+ *
+ * The live record is evicted about ten minutes after the agent finishes, read or
+ * not, and is gone after a reload or a restart. Its completion notification
+ * carries only a preview of the result and points at `get_subagent_result` for
+ * the rest, so that pointer has to outlive the record: the final record is
+ * appended to the session as this entry, and `get_subagent_result` falls back
+ * to it.
+ *
+ * It is also what lets `Agent({ resume })` reopen an evicted agent: the entry
+ * names the session file the conversation lives in, so the id the model holds
+ * still leads somewhere after eviction, a reload or a restart.
+ */
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentRecord, SubagentType } from "./types.js";
+/** `customType` of the session entry a finished top-level agent appends. */
+export declare const AGENT_RECORD_ENTRY_TYPE = "subagents:record";
+/** The persisted snapshot of a finished agent. */
+export interface AgentRecordEntryData {
+    id: string;
+    type: AgentRecord["type"];
+    description: string;
+    status: AgentRecord["status"];
+    result?: string;
+    error?: string;
+    startedAt: number;
+    completedAt?: number;
+    /**
+     * The agent's persisted pi session, when it has one — what a resume reopens.
+     * Absent for an in-memory session (`rememberAgents` off, or
+     * `persist_session: false`), which leaves nothing to come back to.
+     */
+    sessionFile?: string;
+    /** Names to give back to the reopened agent, as the `@handle` path does. */
+    handle?: string;
+    alias?: string;
+    /** Set when the agent's work lived in a worktree that is now gone — see {@link worktreeLost}. */
+    worktreeLost?: boolean;
+}
+/**
+ * Whether the agent ran in a worktree that held its work and has since been
+ * removed. Settling always removes the worktree, committing any changes to a
+ * branch first, so only a clean one (`hasChanges: false`) leaves nothing
+ * behind; a run that failed before cleanup reported nothing and counts as lost.
+ * Claude Code draws the same line: it resumes an isolated agent outside its
+ * worktree only when the worktree was removed clean, and never builds a fresh
+ * one on resume.
+ */
+export declare function worktreeLost(record: Pick<AgentRecord, "worktree" | "worktreeResult">): boolean;
+/** Snapshot a finished record for {@link AGENT_RECORD_ENTRY_TYPE}. */
+export declare function agentRecordEntryData(record: AgentRecord): AgentRecordEntryData;
+/**
+ * The latest persisted record of `id` on the current branch. A resumed agent
+ * appends a new entry on each finish, so the last one wins; an entry on an
+ * abandoned branch is not this conversation's.
+ *
+ * When `matchHandle` is set, the handle and alias match too, case-insensitively
+ * like `@handle`, and only if no entry's id is `id`. Resume leaves it off: it
+ * reopens whatever this returns, and a handle would reopen a saved session
+ * while that agent's live record still exists.
+ */
+export declare function findAgentRecordEntry(ctx: ExtensionContext, id: string, matchHandle?: boolean): AgentRecordEntryData | undefined;
+/**
+ * Whether an evicted agent's saved conversation can be reopened, and the
+ * agent type to reopen it under. Shared by `@handle`, `Agent({ resume })` and
+ * a workflow's `resume`, so all three refuse the same cases in the same words;
+ * `reason` completes "Could not resume X —" and "cannot be resumed —".
+ *
+ * The file is checked here rather than left to SessionManager.open: that runs
+ * inside runAgent, whose rejection lands on the record as an agent error, not
+ * as a refusal. A `/new` in another pi window or a manual delete makes the
+ * conversation unrecoverable (Claude Code's `not_reachable`); `gone` marks
+ * that, and the no-file case, as refusals that can never clear.
+ *
+ * The Agent tool deliberately falls back to general-purpose for a type it
+ * cannot resolve (#183), which covers a deleted file AND a merely disabled
+ * one. A resume must not inherit that: reopening this conversation under a
+ * different agent's prompt and tools is not continuing it, and the new record
+ * would re-tombstone under the substitute, so the handle would never find its
+ * way back. `@handle` and the Agent tool reload the agent files first.
+ *
+ * `worktreeLost` refuses for good, as Claude Code does ("its worktree no
+ * longer exists"): the conversation's edits were made in a directory that is
+ * gone, and reopening it in the parent's checkout or a fresh worktree would
+ * continue that work somewhere it never happened.
+ */
+export declare function reopenTarget(type: string, sessionFile: string | undefined, worktreeLost?: boolean): {
+    ok: true;
+    type: SubagentType;
+    sessionFile: string;
+} | {
+    ok: false;
+    reason: string;
+    gone: boolean;
+};

package/dist/agent-record-entry.js

@@ -0,0 +1,121 @@
+/**
+ * agent-record-entry.ts — what a finished top-level agent leaves behind in the session.
+ *
+ * The live record is evicted about ten minutes after the agent finishes, read or
+ * not, and is gone after a reload or a restart. Its completion notification
+ * carries only a preview of the result and points at `get_subagent_result` for
+ * the rest, so that pointer has to outlive the record: the final record is
+ * appended to the session as this entry, and `get_subagent_result` falls back
+ * to it.
+ *
+ * It is also what lets `Agent({ resume })` reopen an evicted agent: the entry
+ * names the session file the conversation lives in, so the id the model holds
+ * still leads somewhere after eviction, a reload or a restart.
+ */
+import { existsSync } from "node:fs";
+import { resolveSpawnType } from "./agent-types.js";
+/** `customType` of the session entry a finished top-level agent appends. */
+export const AGENT_RECORD_ENTRY_TYPE = "subagents:record";
+/**
+ * Whether the agent ran in a worktree that held its work and has since been
+ * removed. Settling always removes the worktree, committing any changes to a
+ * branch first, so only a clean one (`hasChanges: false`) leaves nothing
+ * behind; a run that failed before cleanup reported nothing and counts as lost.
+ * Claude Code draws the same line: it resumes an isolated agent outside its
+ * worktree only when the worktree was removed clean, and never builds a fresh
+ * one on resume.
+ */
+export function worktreeLost(record) {
+    return record.worktree !== undefined && record.worktreeResult?.hasChanges !== false;
+}
+/** Snapshot a finished record for {@link AGENT_RECORD_ENTRY_TYPE}. */
+export function agentRecordEntryData(record) {
+    return {
+        id: record.id,
+        type: record.type,
+        description: record.description,
+        status: record.status,
+        result: record.result,
+        error: record.error,
+        startedAt: record.startedAt,
+        completedAt: record.completedAt,
+        sessionFile: record.sessionFile,
+        handle: record.handle,
+        alias: record.alias,
+        worktreeLost: worktreeLost(record) || undefined,
+    };
+}
+function isAgentRecordEntryData(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const { id, type, status, startedAt } = data;
+    return typeof id === "string" && typeof type === "string" && typeof status === "string" && typeof startedAt === "number";
+}
+/**
+ * The latest persisted record of `id` on the current branch. A resumed agent
+ * appends a new entry on each finish, so the last one wins; an entry on an
+ * abandoned branch is not this conversation's.
+ *
+ * When `matchHandle` is set, the handle and alias match too, case-insensitively
+ * like `@handle`, and only if no entry's id is `id`. Resume leaves it off: it
+ * reopens whatever this returns, and a handle would reopen a saved session
+ * while that agent's live record still exists.
+ */
+export function findAgentRecordEntry(ctx, id, matchHandle = false) {
+    const entries = ctx.sessionManager.getBranch();
+    const wanted = id.toLowerCase();
+    let named;
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        if (entry.type !== "custom" || entry.customType !== AGENT_RECORD_ENTRY_TYPE)
+            continue;
+        if (!isAgentRecordEntryData(entry.data))
+            continue;
+        if (entry.data.id === id)
+            return entry.data;
+        if (matchHandle &&
+            named === undefined &&
+            (entry.data.handle?.toLowerCase() === wanted || entry.data.alias?.toLowerCase() === wanted)) {
+            named = entry.data;
+        }
+    }
+    return named;
+}
+/**
+ * Whether an evicted agent's saved conversation can be reopened, and the
+ * agent type to reopen it under. Shared by `@handle`, `Agent({ resume })` and
+ * a workflow's `resume`, so all three refuse the same cases in the same words;
+ * `reason` completes "Could not resume X —" and "cannot be resumed —".
+ *
+ * The file is checked here rather than left to SessionManager.open: that runs
+ * inside runAgent, whose rejection lands on the record as an agent error, not
+ * as a refusal. A `/new` in another pi window or a manual delete makes the
+ * conversation unrecoverable (Claude Code's `not_reachable`); `gone` marks
+ * that, and the no-file case, as refusals that can never clear.
+ *
+ * The Agent tool deliberately falls back to general-purpose for a type it
+ * cannot resolve (#183), which covers a deleted file AND a merely disabled
+ * one. A resume must not inherit that: reopening this conversation under a
+ * different agent's prompt and tools is not continuing it, and the new record
+ * would re-tombstone under the substitute, so the handle would never find its
+ * way back. `@handle` and the Agent tool reload the agent files first.
+ *
+ * `worktreeLost` refuses for good, as Claude Code does ("its worktree no
+ * longer exists"): the conversation's edits were made in a directory that is
+ * gone, and reopening it in the parent's checkout or a fresh worktree would
+ * continue that work somewhere it never happened.
+ */
+export function reopenTarget(type, sessionFile, worktreeLost) {
+    if (sessionFile === undefined) {
+        return { ok: false, reason: "its conversation was not saved (`rememberAgents` or `persist_session` was off)", gone: true };
+    }
+    if (!existsSync(sessionFile))
+        return { ok: false, reason: "its session is gone", gone: true };
+    if (worktreeLost)
+        return { ok: false, reason: "its worktree no longer exists", gone: true };
+    const dispatch = resolveSpawnType(type);
+    if (!dispatch.ok || dispatch.fellBackFrom !== undefined) {
+        return { ok: false, reason: `the ${type} agent is no longer available`, gone: false };
+    }
+    return { ok: true, type: dispatch.type, sessionFile };
+}

package/dist/agent-runner.d.ts

@@ -0,0 +1,310 @@
+/**
+ * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
+ */
+import type { Model } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, DefaultResourceLoader, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type NestedAgentManager } from "./nested-tools.js";
+import type { SubagentType, ThinkingLevel } from "./types.js";
+import type { LifetimeUsage } from "./usage.js";
+import type { CompiledSchema } from "./workflow/json-schema.js";
+/**
+ * Tool names registered by THIS extension. Single source of truth so the
+ * registration sites (index.ts) and the subagent exclusion list below can't
+ * drift apart. These are our own tools, not pi built-ins, so they can't be
+ * derived from pi — but they only need defining once.
+ */
+export declare const SUBAGENT_TOOL_NAMES: {
+    readonly AGENT: "Agent";
+    readonly WORKFLOW: "SubagentWorkflow";
+    readonly GET_RESULT: "get_subagent_result";
+    readonly STEER: "steer_subagent";
+};
+/**
+ * Canonical name of an extension for `extensions: [...]` allowlist matching.
+ * Lowercased — extension names match case-insensitively so `extensions: [Mcp]`
+ * resolves the same as `[mcp]`. Tool names within `ext:foo/bar` are not affected.
+ * Directory extensions (`foo/index.ts`) resolve to the parent directory name;
+ * single-file extensions to the basename minus `.ts`/`.js`.
+ */
+export declare function extensionCanonicalName(extPath: string): string;
+/**
+ * All names an extension answers to for allowlist matching (lowercased): its
+ * path-derived {@link extensionCanonicalName} plus, when a pi package manifest
+ * declares this entry, that package's unscoped short name (`@scope/foo` → `foo`).
+ * #143: an extension installed via `pi.extensions: ["./src/index.ts"]` would
+ * otherwise only ever match as `src` (the source directory), never by its
+ * package name. The path-derived name is preserved, so it keeps matching too.
+ */
+export declare function extensionCanonicalNames(extPath: string): string[];
+/**
+ * Classify `extensions: string[]` frontmatter entries for the loader-level filter.
+ *
+ * An entry is a PATH iff it contains a path separator or starts with `~`; otherwise
+ * it is a NAME. `"*"` sets the wildcard flag (keep all default-discovered extensions).
+ *
+ * Path entries are resolved (`~` expanded, made absolute against `cwd`) into `paths`
+ * — and their canonical name is also added to `names`. The loader override matches
+ * everything by canonical name, so path-loaded extensions are matched via their name
+ * rather than their post-staging `Extension.path`.
+ */
+export declare function parseExtensionsSpec(entries: string[], cwd: string): {
+    names: Set<string>;
+    paths: string[];
+    wildcard: boolean;
+};
+/**
+ * Parse raw `ext:` selector strings (from the `tools:` CSV) into the set of
+ * extension names to keep loaded and a per-extension tool-narrowing map.
+ *
+ * `ext:foo` → `extNames` has `foo`, no narrowing entry (all of foo's tools).
+ * `ext:foo/bar` → `extNames` has `foo`, `narrowing.foo` has `bar` (only `bar`).
+ * A name lands in `narrowing` only when a `/tool` form is seen, so a bare
+ * `ext:foo` alongside `ext:foo/bar` leaves narrowing in effect (narrowing wins).
+ * The split is on the first `/`; extension canonical names never contain `/`.
+ */
+export declare function parseExtSelectors(entries: string[]): {
+    extNames: Set<string>;
+    narrowing: Map<string, Set<string>>;
+};
+/**
+ * Keep a subagent's tool scope correct as extensions register tools over time.
+ *
+ * Extensions may call `registerTool` long after load — pi-mcp from `session_start`,
+ * context-mode from `before_agent_start` — so scope has to be re-derived rather than
+ * snapshotted. `registerTool` writes into the very `extension.tools` maps this reads,
+ * so `inScope()` sees late arrivals on the next call.
+ *
+ * Two enforcement points, because neither covers the whole picture:
+ *
+ *   - `turn_end` re-narrows the ACTIVE set. pi emits `turn_end` immediately before
+ *     `prepareNextTurn` re-snapshots `agent.state.tools`, and session listeners run
+ *     synchronously, so the narrow lands in time for turns 2..N.
+ *   - `beforeToolCall` blocks out-of-scope calls. Turn 1 cannot be narrowed at all:
+ *     `before_agent_start` fires INSIDE `prompt()` and may widen the tool set, but
+ *     `createContextSnapshot()` freezes that turn's tools immediately after — there
+ *     is no hook in between. A call-time check is the only correct guard there.
+ *
+ * Both are installed on the session and deliberately NOT unsubscribed: they must
+ * outlive the `runAgent` call so resumed/steered turns stay scoped. pi's `dispose()`
+ * clears `_eventListeners`, so they die with the session rather than leaking.
+ *
+ * Only meaningful when extensions are loaded — under `noExtensions`/`isolated` the
+ * static `allowedToolNames` allowlist already gates the registry itself.
+ */
+export declare function installExtensionToolScope(session: AgentSession, ctx: {
+    loader: DefaultResourceLoader;
+    toolNames: string[];
+    disallowedSet: Set<string> | undefined;
+    extNames: Set<string>;
+    narrowing: Map<string, Set<string>>;
+    /** Bare `mcp__` entries from `tools:`; undefined leaves MCP tools to the rules above. */
+    mcpToolPatterns: string[] | undefined;
+    /**
+     * Injected `customTools` to keep active regardless of the built-in list.
+     *
+     * Two kinds arrive here and they are blocked for different reasons: opt-in
+     * nested-delegation tools share EXCLUDED_TOOL_NAMES' names, and
+     * StructuredOutput is simply not a built-in, so neither survives a `keep`
+     * seeded from `toolNames`.
+     */
+    readmitToolNames: Set<string>;
+    /** Receives the scope check the child's nested-call gate extension applies. */
+    nestedCallGate: NestedCallGate;
+}): void;
+/** Set once the child's tool scope is installed; until then the gate admits everything. */
+type NestedCallGate = {
+    allows?: (name: string) => boolean;
+};
+/** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
+export declare function normalizeMaxTurns(n: number | undefined): number | undefined;
+/** Get the default max turns value. undefined = unlimited. */
+export declare function getDefaultMaxTurns(): number | undefined;
+/** Set the default max turns value. undefined or 0 = unlimited, otherwise minimum 1. */
+export declare function setDefaultMaxTurns(n: number | undefined): void;
+/**
+ * The turn limit a run of `type` will actually enforce: an explicit value if the
+ * caller supplied one, else the agent's own `max_turns`, else the project
+ * default. `undefined` = unlimited.
+ *
+ * Exported because the widget's turn counter (`↻3≤20`) has to predict this
+ * before the run starts, and a second copy of the expression would drift from
+ * the one below that enforces it.
+ */
+export declare function resolveEffectiveMaxTurns(type: string, explicit?: number): number | undefined;
+/** Whether subagent sessions are persisted by default. */
+export declare function getRememberAgents(): boolean;
+/** Set whether subagent sessions are persisted by default. */
+export declare function setRememberAgents(b: boolean): void;
+/** Get the grace turns value. */
+export declare function getGraceTurns(): number;
+/** Set the grace turns value (minimum 1). */
+export declare function setGraceTurns(n: number): void;
+/**
+ * Try to find the right model for an agent type.
+ * Priority: explicit option > config.model > parent model.
+ */
+export declare function resolveDefaultModel(parentModel: Model<any> | undefined, registry: {
+    find(provider: string, modelId: string): Model<any> | undefined;
+    getAvailable?(): Model<any>[];
+}, configModel?: string): Model<any> | undefined;
+/** Info about a tool event in the subagent. */
+export interface ToolActivity {
+    type: "start" | "end";
+    toolName: string;
+}
+export interface RunOptions {
+    /** ExtensionAPI instance — used for pi.exec() instead of execSync. */
+    pi: ExtensionAPI;
+    /** Manager-assigned id; suffixes session name to disambiguate parallel spawns (e.g. `Explore#a1b2c3d4`). */
+    agentId?: string;
+    model?: Model<any>;
+    maxTurns?: number;
+    signal?: AbortSignal;
+    /** Applies only when the agent file leaves `isolated:` unset — frontmatter is authoritative. */
+    isolated?: boolean;
+    inheritContext?: boolean;
+    thinkingLevel?: ThinkingLevel;
+    /**
+     * Reopen this pi session file rather than starting an empty conversation.
+     * `createAgentSession` seeds itself from whatever its SessionManager holds,
+     * so pointing it at an existing file rehydrates that agent's history and the
+     * prompt continues it. Everything else — tools, model, system prompt, turn
+     * caps — is still resolved from the agent type, so the continuation runs
+     * under the type's *current* definition, not the one the original run used.
+     */
+    resumeSessionFile?: string;
+    /**
+     * True when another agent spawned this one. Only top-level agents get a
+     * handle, so only they can be reopened by name — which is the whole reason
+     * `rememberAgents` persists a session at all. A nested run's transcript would
+     * be unreachable by anything, so it stays in memory unless its own
+     * frontmatter asks otherwise.
+     */
+    nested?: boolean;
+    /**
+     * True when a workflow run spawned this agent. Its final text is the value
+     * `agent()` resolves to rather than a report a person reads, and the prompt
+     * says so — but only when `structuredOutput` is unset, since that child
+     * already has a `StructuredOutput` tool to answer through and two competing
+     * "this is how you return your answer" instructions is worse than one.
+     */
+    workflow?: boolean;
+    /** Override working directory (e.g. for worktree isolation). */
+    cwd?: string;
+    /**
+     * Directory the worktree copy was created from. Set only when `cwd` points
+     * into a worktree — the prompt then tells the agent to stay in the copy
+     * instead of following the inherited parent prompt back to the main tree.
+     */
+    worktreeBase?: string;
+    /**
+     * Where .pi config is discovered (project extensions, skills, pi settings,
+     * agent memory). Default: same as the working directory. The manager sets
+     * this to the parent session's cwd when `SpawnOptions.cwd` points the
+     * working directory elsewhere — the agent works *there* but carries the
+     * parent project's config (the target's `.pi` extensions never execute).
+     *
+     * WARNING for future callers: if you pass `cwd` pointing at a directory the
+     * user didn't open, you almost certainly must pass `configCwd` too —
+     * omitting it makes the target's `.pi` extensions execute in this process.
+     * (Worktree isolation is the one intentional exception: its copy IS the
+     * parent's repo, so config resolving inside it is correct.)
+     */
+    configCwd?: string;
+    /** Called on tool start/end with activity info. */
+    onToolActivity?: (activity: ToolActivity) => void;
+    /** Called on streaming text deltas from the assistant response. */
+    onTextDelta?: (delta: string, fullText: string) => void;
+    onSessionCreated?: (session: AgentSession) => void;
+    /** Called at the end of each agentic turn with the cumulative count. */
+    onTurnEnd?: (turnCount: number) => void;
+    /**
+     * Called once per assistant message_end with that message's usage delta.
+     * Lets callers maintain a lifetime accumulator that survives compaction
+     * (which replaces session.state.messages and resets stats-derived sums).
+     *
+     * `cost` is pi's own `usage.cost.total` for that message — priced from the
+     * model's rates, so it is 0 (not missing) for a model pi has no pricing for.
+     * We never price anything ourselves; every dollar figure this extension shows
+     * or reports traces back to this field.
+     */
+    onAssistantUsage?: (usage: LifetimeUsage) => void;
+    /**
+     * Called when the session successfully compacts. `tokensBefore` is upstream's
+     * pre-compaction context size estimate. Aborted compactions don't fire.
+     */
+    onCompaction?: (info: {
+        reason: "manual" | "threshold" | "overflow";
+        tokensBefore: number;
+    }) => void;
+    /**
+     * Make this child report through a `StructuredOutput` tool built from this
+     * schema, and put the validated payload on {@link RunResult.structuredJson}.
+     *
+     * Already compiled by the caller, so a schema this runtime cannot validate
+     * fails at the call that wrote it rather than inside the child.
+     */
+    structuredOutput?: CompiledSchema;
+    /** Runtime bridge for opt-in child-safe nested delegation. */
+    nestedRuntime?: {
+        manager: NestedAgentManager;
+        parentAgentId: string;
+        depth: number;
+        maxSubagentDepth?: number;
+    };
+}
+export interface RunResult {
+    responseText: string;
+    session: AgentSession;
+    /** True if the agent was hard-aborted (max_turns + grace exceeded). */
+    aborted: boolean;
+    /** True if the agent was steered to wrap up (hit soft turn limit) but finished in time. */
+    steered: boolean;
+    /**
+     * A failure message for the run's FINAL assistant turn, when that turn failed:
+     * a provider error (stopReason "error"), or a "length" stop that produced no
+     * text (a silent max-token death). pi resolves an exhausted-retries failure
+     * normally instead of rejecting, so without this the manager would report such
+     * a run as completed — with an empty result, or worse, an earlier turn's text
+     * presented as the answer (#144). Undefined for a clean stop, or a "length"
+     * stop that produced text (a legitimate truncated answer).
+     */
+    failure?: string;
+    /**
+     * The validated `StructuredOutput` payload as canonical JSON, when the caller
+     * asked for a schema and the child produced one.
+     *
+     * Deliberately not folded into {@link responseText}: `record.result` picks up
+     * a worktree branch note on the way out, which would leave the caller with
+     * unparseable JSON, and merging the two would make "produced structured
+     * output" indistinguishable from "happened to answer in JSON".
+     */
+    structuredJson?: string;
+    /** Whether the extra structured-output prompt had to be sent. */
+    structuredRetried?: boolean;
+}
+export declare function runAgent(ctx: ExtensionContext, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult>;
+/**
+ * Send a new prompt to an existing session (resume). A fresh run of the same
+ * agent: the turn limit is resolved as `runAgent` resolves it — an explicit
+ * `maxTurns`, else the agent type's own `max_turns`, else the project default
+ * — and counted from this prompt (#368).
+ */
+export declare function resumeAgent(session: AgentSession, prompt: string, options: Pick<RunOptions, "maxTurns" | "onTurnEnd" | "onToolActivity" | "onAssistantUsage" | "onCompaction" | "signal"> & {
+    /** The agent's type, for its own `max_turns`. */
+    type: SubagentType;
+}): Promise<{
+    text: string;
+    failure?: string;
+} & Pick<RunResult, "aborted" | "steered">>;
+/**
+ * Send a steering message to a running subagent.
+ * The message will interrupt the agent after its current tool execution.
+ */
+export declare function steerAgent(session: AgentSession, message: string): Promise<void>;
+/**
+ * Get the subagent's conversation messages as formatted text.
+ */
+export declare function getAgentConversation(session: AgentSession): string;
+export {};