@cerebriline/core 4.100.240

package/dist/extensions/tools/team/agent-sandbox-executors.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Set up a delegated agent's private sandbox and the executor options that bind
+ * every one of its file tools to the overlay.
+ *
+ * A delegated agent must not reuse the lead's executors: its file tools have to
+ * resolve through the agent's overlay, and its shell has to run rooted at the
+ * native launcher. `createBuiltinTools` builds its file executors from
+ * `executorOptions`, so setting `overlay` there is what makes read, editor,
+ * apply_patch, grep, sed and awk overlay-backed in one place — no per-executor
+ * wiring to forget, and none of the lead's disk-backed overrides slipping
+ * through to re-point a tool at the real workspace.
+ *
+ * The shell is the escape-prone part. It is bound to the launcher through
+ * `bash.wrapSpawn`, and where the platform has no launcher there is no wrapper —
+ * so `commandsEnabled` is false and the caller passes `enableBash: false`. An
+ * un-wrapped command runs against the real workspace, so "no launcher" always
+ * means "no run_commands", never "run it unsandboxed".
+ */
+import { type AgentSandbox, type SandboxBinaries } from "../../../runtime/sandbox/agent-sandbox";
+import type { DefaultExecutorsOptions } from "../executors";
+/**
+ * The host's per-session capability to sandbox delegated agents. Supplied only
+ * when isolation is turned on and the workspace/storage are known; absent means
+ * delegated agents run exactly as before, sharing the lead's executors.
+ *
+ * The host owns the two things core cannot know: where the agent's overlay may
+ * be written (persistent storage, never tmpfs), and where the native launcher
+ * binaries live (shipped in the extension). `binaries` absent — or not built for
+ * this platform — yields file isolation without a shell.
+ */
+export interface DelegatedSandboxProvider {
+    /** The lead's workspace, read-only to every delegated agent. */
+    workspaceRoot: string;
+    /** The native command-sandbox binaries, when present for this platform. */
+    binaries?: SandboxBinaries;
+    /**
+     * Confine every agent's commands to its workspace copy and a temp folder.
+     * On unless `false` (the host's `subagentSandboxConfine`).
+     */
+    confine?: boolean;
+    /**
+     * A private overlay directory for the agent behind this spawning tool call.
+     * Distinct per call, and in persistent storage — copy-ups can be large, and
+     * tmpfs would lose them and pressure RAM.
+     */
+    overlayRootFor(toolCallId: string): string;
+}
+export interface DelegatedSandboxOptions {
+    /** The lead's workspace, read-only to the agent. */
+    workspaceRoot: string;
+    /** This agent's private overlay directory, in persistent host storage. */
+    overlayRoot: string;
+    /**
+     * The native command-sandbox binaries. Absent — or present but not built for
+     * this platform — means the agent gets file isolation but no shell.
+     */
+    binaries?: SandboxBinaries;
+    /** Confine the agent's commands to the workspace and temp; on unless `false`. */
+    confine?: boolean;
+    /**
+     * Executor tuning to carry over from the lead (timeouts, limits, shell). The
+     * overlay and the shell wrapper are set on top and win over anything here.
+     */
+    base?: DefaultExecutorsOptions;
+}
+export interface DelegatedSandboxSetup {
+    /** The sandbox, for the hand-back to the lead and for disposal. */
+    sandbox: AgentSandbox;
+    /** Pass straight to `createBuiltinTools({ executorOptions })`. */
+    executorOptions: DefaultExecutorsOptions;
+    /**
+     * Whether the agent has a shell. When false the caller passes
+     * `enableBash: false` so `run_commands` is left off the agent's tool list.
+     */
+    commandsEnabled: boolean;
+}
+export declare function setUpDelegatedSandbox(options: DelegatedSandboxOptions): Promise<DelegatedSandboxSetup>;
+/** {@link setUpDelegatedSandbox} for a caller that cannot await. */
+export declare function setUpDelegatedSandboxSync(options: DelegatedSandboxOptions): DelegatedSandboxSetup;

package/dist/extensions/tools/team/agent-slot-gate.d.ts

@@ -0,0 +1,186 @@
+import type { AgentAdmissionController } from "./agent-admission";
+/**
+ * Holds delegated agents to the number of requests their endpoint will serve.
+ *
+ * A local server queues a request that finds no free slot rather than refusing
+ * it, and says nothing while it does. Spawning four sub-agents against a
+ * one-slot Ollama does not run four agents: it runs one and leaves three
+ * waiting, and the run reads as slow rather than blocked. The team runtime
+ * already had a concurrency bound of its own (`maxConcurrentRuns`), so this
+ * exists for the other path -- `spawn_agent`, which the agent loop can issue
+ * several of in a single iteration, each running its sub-agent to completion
+ * inline with nothing between them and the server.
+ *
+ * Deliberately a queue and not a refusal. The waiting has to happen somewhere;
+ * doing it here means it happens once, in order, and can be said out loud,
+ * rather than inside a provider's socket where nothing can see it.
+ */
+export interface AgentSlotGate {
+    /**
+     * Runs `task` when a slot is free. Slots are released on throw too.
+     *
+     * `admitted` is the task's to call on the agent's first output
+     * (`isAdmissionEvent`). Where the engine decides admission, that call is
+     * what lets the next agent start; a task that ends without calling it
+     * releases its turn to try all the same.
+     */
+    run<T>(task: (admitted: () => void) => Promise<T>): Promise<T>;
+    /** How many are running now. For diagnostics; never a scheduling input. */
+    active(): number;
+    /**
+     * Whether one more would be admitted right now, without taking anything.
+     *
+     * For a caller deciding whether to launch, where the launch itself will go
+     * through {@link run} and do the real acquiring — a consuming probe here
+     * would book every worker twice. `true` where there is no admission
+     * control to ask, which is the same reading the rest of this file takes: a
+     * question that cannot be asked has not been answered no.
+     */
+    canAdmitMore(): Promise<boolean>;
+}
+export interface AgentSlotGateOptions {
+    /**
+     * Whether this endpoint's engine admits agents itself (opencoti or xOllama
+     * with PolyKV pools). Asked on each start of an uncapped gate; where it
+     * answers yes, one agent at a time waits for admission (see `run`).
+     * Absent or no: every agent starts at once.
+     */
+    paced?: () => Promise<boolean>;
+}
+/**
+ * @param limit Most agents at once, or `undefined` for no gate of ours.
+ * @param admission The engine's own answer, where there is one.
+ *
+ * `undefined` is not "unlimited": it is the caller saying something else is
+ * deciding -- opencoti with PolyKV on, where admission control answers against
+ * measured KV headroom and counting slots here would refuse work the server
+ * would have taken.
+ *
+ * `admission` is that something else, made explicit. The two bounds measure
+ * different things and both apply: the slot count is what the endpoint will
+ * *serve* at once, the engine's answer is what the pool's KV will *hold*, and
+ * an agent starts only once both say yes. Asking before the spawn rather than
+ * absorbing the refusal after it is the better half of the same fix -- a
+ * request that is going to be refused is a request worth not sending.
+ */
+export declare function createAgentSlotGate(limit: number | undefined, admission?: AgentAdmissionController, options?: AgentSlotGateOptions): AgentSlotGate;
+/**
+ * Whether an endpoint with this bound can run a delegated agent *beside* the
+ * agent that asked for one.
+ *
+ * The gate above makes one-slot delegation safe; it does not make it useful. A
+ * spawned agent on a one-slot server runs after its parent's request rather
+ * than alongside it, so nothing finishes sooner and the model has spent a turn
+ * arranging it. Measured on a live transaction: the model sent
+ * `team_spawn_teammate`, the call was refused on its arguments, the model
+ * answered with `team_cleanup` and went back to editing -- three turns spent
+ * on a capability the endpoint never had.
+ *
+ * So the tools are not offered at all when the count says one. A tool a model
+ * can see is a tool it will try, and one that cannot help it is a distraction
+ * priced in turns.
+ *
+ * `undefined` is not one: it means no host resolved a count, and a host that
+ * has not been taught to ask keeps the behaviour it had. `0` is not one
+ * either -- that is the host saying admission control decides, which is
+ * opencoti with PolyKV, where agents share a KV pool and the server paces
+ * them.
+ */
+/**
+ * Whether two delegated agents can actually run beside one another.
+ *
+ * The question the tools are offered on. It used to be asked of the session's
+ * one endpoint alone, which was right while there was only one place a
+ * delegated agent could go. Agent nodes made that false: two nodes serving one
+ * request each serve two at once, and reading only the session's count withheld
+ * `spawn_agent` and the team tools from exactly the configuration that exists
+ * to run them in parallel. Measured on a live run — two nodes configured, the
+ * tools absent, and the model falling back to `create_agent`, which writes an
+ * agent definition file and runs nothing.
+ */
+export declare function delegationCanRunInParallel(input: {
+    maxConcurrentAgents: number | undefined;
+    nodes?: ReadonlyArray<{
+        capacity: number;
+    }>;
+}): boolean;
+/**
+ * Whether the configured nodes together have room for more than one agent.
+ *
+ * `0` is a node that is off and contributes nothing; `Infinity` is an endpoint
+ * that decides its own admission and settles the question on its own. Anything
+ * else adds up.
+ */
+export declare function agentNodesAllowParallelDelegation(nodes: ReadonlyArray<{
+    capacity: number;
+}> | undefined): boolean;
+/** Whether one endpoint on its own serves more than one request at a time. */
+export declare function slotsAllowParallelDelegation(maxConcurrentAgents: number | undefined): boolean;
+/**
+ * The endpoint two agents share, or do not.
+ *
+ * Provider and base URL together, because a provider id alone says nothing
+ * about which server: two profiles both naming `ollama` may point at a machine
+ * each. Lower-cased, and the trailing slash dropped, so a base URL that differs
+ * only in those is one endpoint rather than two.
+ */
+export declare function agentEndpointKey(connection: {
+    providerId?: string;
+    baseUrl?: string;
+}): string;
+/**
+ * Host-supplied bounds, keyed the way the gates are keyed.
+ *
+ * The host names connections; only this file knows that a trailing slash and a
+ * capital letter do not make a second server. First entry wins, so a caller may
+ * put the specific answers first -- a profile carries its own count, and the
+ * shared provider entry answers for every profile that does not.
+ */
+export declare function agentSlotLimitsByEndpoint(entries: ReadonlyArray<{
+    providerId?: string;
+    baseUrl?: string;
+    limit: number;
+}> | undefined): Record<string, number> | undefined;
+/**
+ * A gate per endpoint, from one bound.
+ *
+ * The single gate above was written when every delegated agent ran on the
+ * session's connection, and its own comment says so -- "they all read this
+ * provider". That stopped being true when a configured agent gained
+ * `providerId`, and again when it gained `profile:`. Agents on a cloud
+ * provider and agents on a local one would otherwise contend for the same
+ * slots, so a one-slot Ollama serialises work that was never going near it.
+ *
+ * The bound is applied per endpoint rather than shared because that is what it
+ * measures: how many requests *that server* will serve at once. Which also
+ * means one number cannot answer for all of them: an agent whose profile names
+ * a four-slot server was held to the lead's one, and the three slots it was
+ * entitled to went unused while its siblings queued. So the host may hand over
+ * a bound per endpoint as well, and the session's stays the answer for every
+ * endpoint it did not name -- conservative in the right direction, since it
+ * never over-subscribes a server it knows nothing about.
+ */
+export interface AgentSlotGateRegistry {
+    /** The gate for one endpoint, created on first use and kept. */
+    for(key: string): AgentSlotGate;
+    /** The bound this endpoint's gate was built with. Diagnostics only. */
+    limitFor(key: string): number | undefined;
+    /** How many are running across every endpoint. Diagnostics only. */
+    active(): number;
+}
+/**
+ * @param limit The bound for an endpoint the host said nothing about.
+ * @param limits A bound per {@link agentEndpointKey}, from the host.
+ * @param admissionFor The engine's own answer for an endpoint that has one.
+ *
+ * `limits` is consulted before `limit`, and `0` in it is honoured rather than
+ * treated as absent: zero is the host saying admission control decides for that
+ * endpoint, which is a different statement from having no answer for it.
+ *
+ * `admissionFor` is asked once per endpoint, when that endpoint's gate is
+ * first built, and returning `undefined` is the ordinary case -- only opencoti
+ * with a pool has anything to ask. It is keyed by endpoint for the same reason
+ * the bound is: a pool belongs to one server, and an agent whose profile points
+ * at another must not be held against it.
+ */
+export declare function createAgentSlotGateRegistry(limit: number | undefined, limits?: Readonly<Record<string, number>>, admissionFor?: (key: string) => AgentAdmissionController | undefined, pacedFor?: (key: string) => AgentSlotGateOptions["paced"]): AgentSlotGateRegistry;

package/dist/extensions/tools/team/agent-status.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `agents_status`: what the lead's agents are doing, and why.
+ *
+ * Read-only, and offered in every mode the lead can be in -- its own turn
+ * beside a background round, the side turn while a blocking round runs, and
+ * an escalation's expert (spec B, rulings 3 and 6). Three shapes:
+ *
+ * - no arguments: a summary -- per round, how many agents are in each state
+ *   and for how long the round has run; per node, what it runs, whether it
+ *   answers, how full it is, its admission policy and recent refusals, and
+ *   the retry policy in words;
+ * - `round_id`: one line per agent of that round;
+ * - `agent_id` (or several): an agent in detail -- its state and the reason
+ *   for it, node, model, window, tokens, speed, iterations against its cap,
+ *   compactions by cause, sampler, the oracle's verdict, the tail of its
+ *   output and of its activity, and its errors with their class.
+ *
+ * Bounded: never a transcript, and never more than {@link STATUS_MAX_CHARS}.
+ * Everything it says comes from what is already known -- the round records,
+ * the placement queue, and the last `/kv` read the compaction trigger made.
+ * It never asks a server anything.
+ */
+import { type AgentTool, type TeamMemberSnapshot, type TeamRunRecord } from "@cerebriline/shared";
+import { type AgentRounds, type AgentRunState, type RoundAgentRecord, type RoundRecord } from "./agent-rounds";
+import type { DelegatedAgentConfigProvider } from "./delegated-agent";
+export declare const AGENTS_STATUS_TOOL_NAME = "agents_status";
+/** The most a status answer may take. */
+export declare const STATUS_MAX_CHARS = 12000;
+/**
+ * How the harness treats infrastructure trouble, in words, for the lead:
+ * it must not try to route around a node itself (ruling 1).
+ */
+export declare const RETRY_POLICY_TEXT: string;
+/** A teammate, as the team runtime reports it. */
+export interface TeammateStatusSource {
+    members: TeamMemberSnapshot[];
+    runs: TeamRunRecord[];
+}
+export interface AgentsStatusOptions {
+    sessionId: string;
+    /** The session's delegated connection: its nodes, or its single endpoint. */
+    configProvider?: () => DelegatedAgentConfigProvider | undefined;
+    /** The team, when the session has teammates. */
+    teammates?: () => TeammateStatusSource | undefined;
+    now?: () => number;
+}
+export declare function formatDuration(ms: number): string;
+/**
+ * What the status knows beyond one record: where each node is and what its
+ * compaction threshold is, the order of the placement queue, and how fast
+ * agents have been finishing. Built once per call.
+ */
+export interface StatusContext {
+    /** By node id ("" for the session's single connection). */
+    nodes: Map<string, {
+        baseUrl?: string;
+        threshold: number;
+        polykv: boolean;
+    }>;
+    /** Agent id -> its place in the placement queue, 1-based, and the length. */
+    queue: Map<string, number>;
+    queueLength: number;
+    /** Agents of this session that ended in the last five minutes. */
+    finishedRecently: number;
+}
+/** Build the context once per status call. */
+export declare function buildStatusContext(rounds: AgentRounds, provider: DelegatedAgentConfigProvider | undefined, now: number): StatusContext;
+/** Why an agent is where it is, in words (ruling 6). */
+export declare function describeReason(agent: RoundAgentRecord, state: AgentRunState, now: number): string;
+/** The nodes block of the summary. */
+export declare function describeNodes(provider: DelegatedAgentConfigProvider | undefined, now: number): string[];
+/** The whole summary: rounds, nodes, retry policy, teammates. */
+export declare function describeSummary(rounds: AgentRounds, options: Omit<AgentsStatusOptions, "sessionId">): string;
+/** One line per agent of a round. */
+export declare function describeRound(round: RoundRecord, now: number, ctx?: StatusContext): string;
+/** One agent in full: everything ruling 6 and spec B ask for, bounded. */
+export declare function describeAgent(round: RoundRecord, agent: RoundAgentRecord, now: number, ctx?: StatusContext): string;
+export declare function renderAgentsStatus(input: {
+    agent_id?: string;
+    agent_ids?: string[];
+    round_id?: string;
+}, options: AgentsStatusOptions): string;
+export declare const AGENTS_STATUS_DESCRIPTION: string;
+export declare function createAgentsStatusTool(options: AgentsStatusOptions): AgentTool;

package/dist/extensions/tools/team/agent-trouble.d.ts

@@ -0,0 +1,91 @@
+import { type TurnFaultWait } from "./turn-fault-recovery";
+/** Continuous waiting after which the lead is told about an agent. */
+export declare const LEAD_NUDGE_AFTER_MS: number;
+/**
+ * Continuous waiting after which an agent counts as having no node to run on,
+ * and the lead is asked to decide instead of waiting on.
+ */
+export declare const NO_NODE_AFTER_MS: number;
+/**
+ * How long the first overdue agent waits for others to join its report.
+ *
+ * A round of agents on one node goes wrong together: 75 agents crossing the
+ * line within a minute of each other are one report, not 75 side turns.
+ */
+export declare const LEAD_NUDGE_BATCH_MS = 30000;
+/**
+ * How a nudge waits for the lead: `awaiting` for the agents-waiting-on-you
+ * notice (one replaces another), and a `refresh` that rewrites it as it is
+ * read, or drops it once it no longer applies.
+ */
+export interface LeadNudgeOptions {
+    noteKind?: "awaiting" | "queued";
+    refresh?: () => string | undefined;
+    /**
+     * Nothing in it asks the lead to decide anything, so it does not end a
+     * wait on the agents: it is read with whatever ends that wait next. In
+     * wlafh r3 three "queued, not broken: wait for them" notes each ended an
+     * `await_agents` that the lead could only call again.
+     */
+    quiet?: boolean;
+}
+/** Per-session listener: whoever can put a message in front of the lead. */
+type LeadNudgeListener = (text: string, options?: LeadNudgeOptions) => void;
+/**
+ * Receive the nudges for a session's lead. One listener per session: the
+ * host that owns the lead. Returns the unsubscribe.
+ */
+export declare function onLeadNudge(sessionId: string, listener: LeadNudgeListener): () => void;
+/** Whether a host is listening for this session's lead: a side turn or a queue. */
+export declare function leadCanBeReached(sessionId: string): boolean;
+/** Put a message in front of the lead. `false` when no host is listening. */
+export declare function sendLeadNudge(sessionId: string, text: string, options?: LeadNudgeOptions): boolean;
+interface TroubleRecord {
+    name: string;
+    /** Start of the current stretch of waiting. */
+    since: number;
+    kind: TurnFaultWait["kind"];
+    where: string;
+    detail: string;
+    /** Refusals in the current stretch. */
+    refusals: number;
+    /** Told the lead already; never twice for one agent. */
+    nudged: boolean;
+    /** Told the lead it has had no node for hours; never twice either. */
+    escalated: boolean;
+}
+/** One agent's line in the lead's report. */
+export declare function describeTrouble(record: Pick<TroubleRecord, "name" | "since" | "kind" | "where" | "detail" | "refusals">, now: number): string;
+/** The whole report, as the lead reads it. */
+export declare function describeLeadNudge(records: ReadonlyArray<Pick<TroubleRecord, "name" | "since" | "kind" | "where" | "detail" | "refusals">>, now: number): string;
+/** The second report: these agents have had nowhere to run for hours. */
+export declare function describeNoNodeNudge(records: ReadonlyArray<Pick<TroubleRecord, "name" | "since" | "kind" | "where" | "detail" | "refusals">>, now: number, afterMs?: number): string;
+/** A wait the engine's fetch reported (`onPolykvRoomWait`), as a trouble. */
+export declare function roomWaitTrouble(reason: string | undefined): TurnFaultWait;
+export interface AgentTroubleWatch {
+    /** The agent is waiting on this; starts or continues a stretch. */
+    waiting(state: TurnFaultWait): void;
+    /** The engine produced something for the agent: the stretch is over. */
+    progressed(): void;
+    /** The agent ended. */
+    dispose(): void;
+}
+export interface AgentTroubleWatchOptions {
+    /** The lead's session; absent means nobody to tell, and nothing is kept. */
+    sessionId?: string;
+    /** The agent's name, as the round and `stop_agents` call it. */
+    name: string;
+    /** Seams for tests. */
+    now?: () => number;
+    nudgeAfterMs?: number;
+    noNodeAfterMs?: number;
+    batchMs?: number;
+    /** Where the report goes; defaults to the session's lead listener. */
+    send?: (sessionId: string, text: string, options?: LeadNudgeOptions) => boolean;
+    /** For when no lead could be reached: the log still says it. */
+    logger?: {
+        log: (message: string) => void;
+    };
+}
+export declare function createAgentTroubleWatch(options: AgentTroubleWatchOptions): AgentTroubleWatch;
+export {};

package/dist/extensions/tools/team/background-delegations.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Delegations the user started and then went back to work.
+ *
+ * `delegateToConfiguredAgent` runs an agent and returns its answer, which is
+ * the right shape for "run the QA agent on this and tell me". It is the wrong
+ * shape for the reason people ask for it: the lead is blocked for as long as
+ * the delegated run takes, and pressing stop on the lead takes the delegation
+ * down with it. A run the user asked for should outlive the turn they asked in.
+ *
+ * So a background run is held here rather than on the turn. The registry owns
+ * the three things such a run needs and a promise does not have: a way to be
+ * paused, a way to be stopped, and a status somebody can render.
+ *
+ * Deliberately ignorant of how an agent runs. It is handed a `run` function and
+ * gives it back the controls; the caller wires those into whatever it is
+ * running. That keeps the delegation path -- provider resolution, the endpoint
+ * slot gate, the per-agent tool filtering -- exactly the one the synchronous
+ * path already uses, instead of a second copy of it that drifts.
+ */
+import type { AgentHooks } from "@cerebriline/shared";
+import { type ConfiguredAgentDelegationResult, type DelegateToConfiguredAgentInput } from "./delegate-to-agent";
+export type BackgroundDelegationStatus = "running" | "paused" | "completed" | "failed"
+/** The user stopped it. Not a failure, and not to be reported as one. */
+ | "stopped";
+export interface BackgroundDelegationView {
+    id: string;
+    agentName: string;
+    prompt: string;
+    status: BackgroundDelegationStatus;
+    startedAt: number;
+    endedAt?: number;
+    /** The last thing worth putting on a one-line row. */
+    activity?: string;
+    /** Turns taken so far, so a row can show progress and not just elapsed time. */
+    iterations?: number;
+    result?: ConfiguredAgentDelegationResult;
+    error?: string;
+}
+export interface BackgroundDelegationControls {
+    runId: string;
+    /** Aborted when the user stops the run. */
+    signal: AbortSignal;
+    /**
+     * Hooks that suspend the run while it is paused.
+     *
+     * The barrier is in `beforeModel`, which the runtime awaits before every
+     * request, so a paused run stops between requests and never mid-stream.
+     * Pausing does not cancel the request already in flight -- that would throw
+     * away work the user has paid for and asked to keep.
+     */
+    hooks: AgentHooks;
+    /**
+     * Where the run hands over the release of its engine session. A pause
+     * calls it -- a paused run must not hold a booked window for as long as
+     * the user leaves it -- and the resume waits for that close to land, so
+     * the next request books afresh rather than racing it.
+     */
+    bindEngineSession: (release: () => Promise<unknown>) => void;
+}
+export interface StartBackgroundDelegationInput {
+    agentName: string;
+    prompt: string;
+    run: (controls: BackgroundDelegationControls) => Promise<ConfiguredAgentDelegationResult>;
+    /**
+     * Called once when the run has finished, failed or been stopped.
+     *
+     * This is where a host delivers the answer back into the conversation. It
+     * runs outside the lead's turn by definition, so it must not assume there is
+     * one.
+     */
+    onSettled?: (view: BackgroundDelegationView) => void;
+}
+export interface BackgroundDelegationRegistry {
+    /** Starts the run and returns immediately. */
+    start(input: StartBackgroundDelegationInput): BackgroundDelegationView;
+    list(): BackgroundDelegationView[];
+    get(id: string): BackgroundDelegationView | undefined;
+    /** @returns whether there was a running run to pause. */
+    pause(id: string): boolean;
+    /** @returns whether there was a paused run to resume. */
+    resume(id: string): boolean;
+    /** @returns whether there was a live run to stop. */
+    stop(id: string): boolean;
+    /** Records what the run is doing, for the panel. */
+    note(id: string, activity: string): void;
+    /** Every change, for a panel that redraws. Returns an unsubscribe. */
+    subscribe(listener: (runs: BackgroundDelegationView[]) => void): () => void;
+    /** Stops everything. For a host tearing the session down for good. */
+    stopAll(): void;
+}
+export declare function createBackgroundDelegationRegistry(options?: {
+    now?: () => number;
+    newId?: () => string;
+}): BackgroundDelegationRegistry;
+/**
+ * Start a configured agent in the background, on the same path the foreground
+ * one runs down.
+ *
+ * The agent name is checked here rather than inside the run, so a typo is an
+ * error at the prompt where it was typed instead of a background run that
+ * appears in the panel and immediately fails. Every other failure belongs to
+ * the run and is reported there.
+ */
+export declare function startBackgroundDelegation(registry: BackgroundDelegationRegistry, input: Omit<DelegateToConfiguredAgentInput, "signal" | "hooks" | "bindEngineSession"> & {
+    onSettled?: (view: BackgroundDelegationView) => void;
+}): BackgroundDelegationView;