@cerebriline/core 4.100.240

package/dist/extensions/tools/team/spawn-swarm-tool.d.ts

@@ -0,0 +1,330 @@
+/**
+ * `spawn_swarm` — several agents on one shared prefix, reporting digests.
+ *
+ * `spawn_agent` delegates one task to one sub-agent that starts from a system
+ * prompt and re-prefills the whole of it. A swarm is the other shape: N agents
+ * that all need what the lead already knows, which on opencoti can be given to
+ * them for free. The lead's live context is snapshotted into a KV pool with
+ * `from_session` — no tokens cross the wire, the engine takes the prefix from
+ * the slot's own token history — and every worker attaches to it. The workers
+ * share a prefix instead of each paying for it.
+ *
+ * Four things about that are load-bearing, in the order they bite:
+ *
+ * 1. **The snapshot's timing.** The host prompt cache saves and clears idle
+ *    slots the moment any new task launches, so the snapshot has to be taken at
+ *    the end of the lead's turn, before any other task starts. Taken late it
+ *    captures a slot that has already been cleared.
+ * 2. **A failed snapshot holds the pooling, not the round.** Running the
+ *    workers against a bad pool means each pays a full prefill and shares
+ *    nothing, which is slower than not fanning out at all — so on failure they
+ *    run unpooled and the result says so.
+ * 3. **Every pool is released, on every path.** Unpin then release, in a
+ *    `finally`. The engine's 60-second ephemeral sweep is the crash net, not
+ *    the plan, and a pin left on an abandoned subtree blocks reclaim forever.
+ * 4. **A worker that breaks the contract is still represented.** The reducer
+ *    cannot tell "nothing to report" from "lost", so a worker that threw, or
+ *    that spent its whole budget thinking and returned empty content, appears
+ *    in the digest with what it did say. Its transcript goes when the pool
+ *    does; whatever is not in the digest is gone.
+ *
+ * "As many agents as possible" needs no parser. The model reads the phrase and
+ * passes `count: "max"`, and the runtime resolves it against what the engine
+ * says it will take right now — which is the same `/capacity` answer the
+ * admission gate draws from, and is bounded there for the reason named in
+ * `agent-admission.ts`.
+ */
+import { type AgentResult, type AgentTool } from "@cerebriline/shared";
+import { z } from "zod";
+import { type WorkDigest } from "../../context/work-digest";
+import { type AgentCheck, type AgentOracleResult } from "./agent-check";
+import type { DelegatedStopReason } from "./agent-iteration-cap";
+import type { HandedRevision } from "./delegated-sandboxes";
+import { type RealizedSpawnSampling, type SpawnSampling } from "./spawn-sampling";
+import { type SubagentCancellationRegistration } from "./subagent-cancellation";
+export declare const SpawnSwarmInputSchema: z.ZodObject<{
+    systemPrompt: z.ZodString;
+    task: z.ZodOptional<z.ZodString>;
+    tasks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        task: z.ZodString;
+        systemPrompt: z.ZodOptional<z.ZodString>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        temperature: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"random">]>>;
+        seed: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"random">]>>;
+        temperature_range: z.ZodOptional<z.ZodNumber>;
+        check: z.ZodOptional<z.ZodObject<{
+            command: z.ZodString;
+            expect: z.ZodString;
+            must: z.ZodOptional<z.ZodEnum<{
+                match: "match";
+                not_match: "not_match";
+            }>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    count: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"max">]>>;
+    temperature: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"random">]>>;
+    seed: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"random">]>>;
+    temperature_range: z.ZodOptional<z.ZodNumber>;
+    check: z.ZodOptional<z.ZodObject<{
+        command: z.ZodString;
+        expect: z.ZodString;
+        must: z.ZodOptional<z.ZodEnum<{
+            match: "match";
+            not_match: "not_match";
+        }>>;
+    }, z.core.$strip>>;
+    wait: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SpawnSwarmInput = z.infer<typeof SpawnSwarmInputSchema>;
+export interface SpawnSwarmOutput {
+    /** The merged report. The only thing that survives the round. */
+    digest: string;
+    /** How many workers actually ran. */
+    workers: number;
+    /** Whether they shared the lead's prefix, or each paid for their own. */
+    pooled: boolean;
+    /**
+     * What the round cost, summed over the workers that reported it.
+     *
+     * Carried out because nothing downstream can recover it: the workers'
+     * transcripts are discarded when their pool is released, so a swarm that
+     * kept this to itself would spend N runs' worth of tokens that are counted
+     * nowhere the task header can see. `spawn_agent` reports its own for the
+     * same reason. A worker that threw contributes nothing, having returned no
+     * result to read a count from -- the number is what was reported, not an
+     * estimate of what was spent.
+     */
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        cachedInputTokens?: number;
+    };
+    /**
+     * One report per requested worker, in the order they were asked for.
+     *
+     * What the host puts on each worker's row. Without it every row of a
+     * 75-worker round sat at "0 tools called · 0 tokens" for the whole round,
+     * and a worker that failed -- or never started -- said so nowhere.
+     */
+    results?: SwarmMemberReport[];
+    /** The round this call opened, for `agents_status` and `retry_failed`. */
+    round?: string;
+    /** Every worker's id and how it ended, one line of facts each. */
+    agents?: Array<{
+        id: string;
+        name: string;
+        state?: string;
+        stop?: string;
+        facts?: string;
+    }>;
+    /** Set when the round runs in the background and this is its receipt. */
+    background?: true;
+    note?: string;
+}
+/** How one worker ended, for its row. */
+export interface SwarmMemberReport {
+    name: string;
+    text?: string;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    /** Why it failed, or why it never ran. Absent means it finished. */
+    error?: string;
+    model?: {
+        provider: string;
+        id: string;
+    };
+    nodeId?: string;
+    nodeLabel?: string;
+    /** The seed and temperature it ran with, as drawn, when the call set any. */
+    sampling?: RealizedSpawnSampling;
+    /** Its id in the round, and how it ended there. */
+    id?: string;
+    /** Its state in the round: `awaiting_lead` while it waits at its cap. */
+    state?: string;
+    /** The round's stop reason (`iteration_cap` when the cap ended it). */
+    stopReason?: DelegatedStopReason | string;
+    finishReason?: string;
+    /** Iterations used, and its cap where there is one. */
+    iterations?: number;
+    maxIterations?: number;
+    /** Its own id, for `resume_agent` and the status tool. */
+    agentId?: string;
+    /** The lead's check, when one was set. */
+    oracle?: AgentOracleResult;
+}
+/** A worker's result, with where it ran when the runner knows. */
+export type SwarmWorkerResult = AgentResult & {
+    placed?: {
+        nodeId: string;
+        nodeLabel?: string;
+    };
+    /** What its sampler came to, when the call set one. */
+    sampling?: RealizedSpawnSampling;
+    /**
+     * The revisions its changes were handed back to the lead as, when it ran on
+     * a private workspace. Present -- even empty -- means it did; the runner
+     * sets the same field on the error a failed worker throws.
+     */
+    handback?: readonly HandedRevision[];
+    /** Its cap, and what the cap and the check made of its run. */
+    maxIterations?: number;
+    stopReason?: DelegatedStopReason;
+    state?: "awaiting_lead";
+    agentId?: string;
+    oracle?: AgentOracleResult;
+};
+/** An ephemeral pool holding a snapshot of the lead's live context. */
+export interface SwarmPoolSnapshot {
+    poolId: string;
+    /** Unpin then release. Called on every path, success and failure. */
+    release(): Promise<void>;
+}
+export interface SwarmPoolSource {
+    /**
+     * Snapshot the lead's live context into an ephemeral pool.
+     *
+     * `undefined` when the engine would not, which runs the round unpooled
+     * rather than failing it.
+     */
+    snapshot(): Promise<SwarmPoolSnapshot | undefined>;
+    /**
+     * How many workers the engine will take right now, or `undefined` when it
+     * will not say.
+     *
+     * An **opening hint only**, where {@link admit} exists. It is a
+     * point-in-time status, and the question a growing round needs answered is
+     * a different one: not "how many are free" but "may I start one more",
+     * asked again after each spawn.
+     */
+    headroom(): Promise<number | undefined>;
+    /**
+     * May one more worker start right now? **Asks without taking.**
+     *
+     * This is what lets a round grow: the engine's answer bounds it, rather
+     * than a number computed once at launch. Non-consuming on purpose — the
+     * worker this admits goes on to acquire through its own slot gate, so a
+     * probe that took the slot would book every worker twice and halve the
+     * round.
+     *
+     * Absent on a source that cannot be asked, which keeps the round sized
+     * from the hint: no probe is no evidence that one more would be taken.
+     */
+    admit?(): Promise<boolean>;
+}
+export interface SwarmWorkerRequest {
+    name: string;
+    task: string;
+    systemPrompt: string;
+    /** The shared pool, when there is one. */
+    poolId?: string;
+    /** The only tools this worker gets, by name; absent means all of them. */
+    tools?: string[];
+    /**
+     * Progress for this worker's row: placement, tool calls, output. Already
+     * tagged with the worker, so the runner reports as a lone agent would.
+     */
+    emitUpdate?: (update: unknown) => void;
+    /** This worker's own stop, which the lead's cancel also trips. */
+    signal?: AbortSignal;
+    /** Messages the lead's side turn left for it, one per turn boundary. */
+    takeMessage?: () => string | undefined;
+    /**
+     * The sampler the call asked for this worker, when it asked; its seed
+     * already offset by the worker's index. See `spawn-sampling.ts`.
+     */
+    sampling?: SpawnSampling;
+    /** Its iteration cap: the task's, else the swarm's; absent is the default. */
+    maxIterations?: number;
+    /** Its check: the task's, else the swarm's. */
+    check?: AgentCheck;
+    /**
+     * The worker's own controls: read its signal per segment (a requeue ends
+     * a segment), run its placement `continuable` so a requeue carries its
+     * transcript, and `track` the agent it builds.
+     */
+    control?: SubagentCancellationRegistration;
+}
+export interface SpawnSwarmToolConfig {
+    pools: SwarmPoolSource;
+    /** Run one worker to completion. */
+    runWorker: (request: SwarmWorkerRequest) => Promise<SwarmWorkerResult>;
+    /**
+     * Rewrite several digests into one, with a model that knows what the lead
+     * knows because it was forked from the same pool.
+     *
+     * Optional: without it, and whenever it fails, the digests are folded
+     * mechanically instead. That fold is lossless where the model's is not, so
+     * it is a fallback worth having rather than a degraded mode.
+     *
+     * The reducer is an agent with file tools like the workers, so it can hand
+     * changes back too. It reports them through `handedBack`, whether it
+     * returns a digest or not, so the report can name them beside the
+     * workers'.
+     */
+    reduce?: (digests: readonly WorkDigest[], reducer?: {
+        handedBack(name: string, handed: readonly HandedRevision[]): void;
+    }) => Promise<WorkDigest | undefined>;
+    /** Most workers this will ever run, whatever the model or engine says. */
+    maxWorkers?: number;
+    /**
+     * How long the supervisor waits before asking again, when nothing has
+     * finished and the engine last said no.
+     */
+    tickMs?: number;
+    /** Test seam. */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * The lead's session, when the tool is built for one: `retry_failed` and a
+     * restart of a finished worker then run it again from its round.
+     */
+    sessionId?: string;
+}
+/**
+ * A spin guard, and deliberately not a policy.
+ *
+ * It exists only so that an engine answering yes forever cannot run this loop
+ * until something else breaks. It must never be the number that decides how
+ * wide a round gets — that is the engine's answer, and a constant standing in
+ * for it is the limit this was raised to remove. Set at the engine's own
+ * `--max-parallel` ceiling so that reaching it means something has gone wrong
+ * rather than that a swarm was busy.
+ */
+export declare const SWARM_RUNAWAY_MAX = 64;
+/** Opening size when the engine will not say and cannot be probed. */
+export declare const DEFAULT_MAX_SWARM_WORKERS = 8;
+/** How often the supervisor re-asks while work is left. */
+export declare const DEFAULT_SWARM_TICK_MS = 5000;
+/** One sandboxed worker's hand-back. */
+interface SwarmHandback {
+    name: string;
+    handed: readonly HandedRevision[];
+}
+/**
+ * Where the round's work went, for the end of the swarm's report.
+ *
+ * Each worker ran on a private copy of the workspace, so the lead's files are
+ * untouched and every change is a revision in the lead's log. Without this the
+ * lead reads its own copy, sees none of the fixes the digest describes, and
+ * concludes the workers did nothing (the `spawn_agent` note's pandorum
+ * failure, once per worker). Empty when no worker was sandboxed.
+ */
+export declare function swarmHandbackNote(handbacks: readonly SwarmHandback[]): string;
+/**
+ * Worker `index`'s sampler: the swarm's, its seed offset by the index so that
+ * workers on one task do not draw identical samples, under the task's own.
+ */
+export declare function workerSampling(input: Pick<SpawnSwarmInput, "temperature" | "seed" | "temperature_range">, index: number, task?: unknown): SpawnSampling | undefined;
+/**
+ * What the reducer is asked to do.
+ *
+ * It runs attached to the same pool the workers did, so it already knows
+ * everything the lead knows -- which is why the prompt can tell it to be short
+ * rather than complete. "Done as planned" costs a line there and a paragraph
+ * anywhere else.
+ */
+export declare const SWARM_REDUCER_PROMPT = "You are merging the reports of several agents that worked in parallel on one task, and you already hold the context they were given \u2014 so do not restate it.\n\nWrite ONE report in the same form they used, as a fenced json block with any of these keys: goal, done, in_progress, ruled_out, key_facts, next, notes.\n\nRules:\n- Keep every specific: paths, symbols, error text, commands, numbers. A detail you drop has to be rediscovered.\n- Where two agents found the same thing, say it once.\n- Where they disagree, say so and say who found what. Do not pick a winner.\n- An agent that reported an error or nothing must still appear, in notes, by name.\n- Do not add findings none of them reported.";
+export declare function createSpawnSwarmTool(config: SpawnSwarmToolConfig): AgentTool<SpawnSwarmInput, SpawnSwarmOutput>;
+export {};

package/dist/extensions/tools/team/subagent-cancellation.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Stopping one sub-agent without stopping the session.
+ *
+ * A delegated agent used to run on the parent's abort signal alone, so the
+ * only way to stop a runaway one was to cancel the whole task -- losing the
+ * lead's context and every sibling agent that was working correctly. A fan-out
+ * of five where one grinds is the case: four reports are already written, and
+ * the only control on screen cancels all of them.
+ *
+ * So each spawned agent gets a signal of its own, and it is registered here
+ * while it runs. The registry is the process's, keyed by session and tool
+ * call: the id is what the chat row is already keyed by, so a row can name the
+ * agent it is showing without inventing an identity for it.
+ *
+ * Deliberately plain. It holds only live runs -- registration is released in
+ * the spawn tool's `finally`, on every path -- so nothing here outlives the
+ * agent it refers to, and a stop for an agent that has already finished is a
+ * no-op rather than an error.
+ */
+/** Who stopped an agent, for the reason its report gives. */
+export type SubagentStopActor = "user" | "lead";
+/** What a requeue carries into the agent's next placement. */
+export interface SubagentRequeueOptions {
+    /** Why the lead moved it, in its words or one of the named reasons. */
+    reason?: string;
+    /** The node to place it anywhere but, when another has room. */
+    avoidNodeId?: string;
+}
+/**
+ * An agent's run that was stopped at a boundary to be placed again: its
+ * transcript, and where not to put it.
+ */
+export interface SubagentRequeueCarry {
+    messages: readonly unknown[];
+    reason?: string;
+    avoidNodeId?: string;
+    /**
+     * A graceful stop: the next segment is one report turn on this
+     * transcript, and the agent ends on it. Who asked, for its report.
+     */
+    wrapUp?: SubagentStopActor;
+}
+/** The live control state of one agent, for the lead's status tool. */
+export interface SubagentControlState {
+    label: string;
+    /** A graceful stop was asked for: it is finishing its step, then reports. */
+    wrapUpPending: boolean;
+    /** A requeue was asked for and has not yet happened. */
+    requeuePending: boolean;
+    /** Waiting on infrastructure right now (a refusal, a server gone). */
+    waitingInfra: boolean;
+}
+export interface SubagentCancellation {
+    /**
+     * Stop this agent. `false` when nothing by that id is running. `by` says
+     * who, for its report: the row's stop is the user's, `stop_agents` the
+     * lead's.
+     */
+    cancel(id: string, by?: SubagentStopActor): boolean;
+    /**
+     * Abandon this agent's current attempt and start it again from its task,
+     * in the same place in the round. `false` when nothing by that id is
+     * running.
+     *
+     * The case it is for: an agent stuck on a stream the server dropped (a
+     * restart under it), or one looping in its output. Stop was the only
+     * control, and a stopped agent is a lost task -- the lead gets "stopped"
+     * and the round is short one report.
+     */
+    restart(id: string, options?: {
+        instructions?: string;
+    }): boolean;
+    /**
+     * Stop this agent at its next turn boundary -- or at once, if it is only
+     * waiting on infrastructure -- and put it back in the placement queue with
+     * its transcript: it continues, it does not start over. `false` when
+     * nothing by that id is running.
+     */
+    requeue(id: string, options?: SubagentRequeueOptions): boolean;
+    /**
+     * Stop this agent gracefully: at its next turn boundary -- or at once, if
+     * it is only waiting on infrastructure -- it is given one turn, with no
+     * tools, to report what it has, and it ends on that report. `false` when
+     * nothing by that id is running, or it runs outside a segment that could
+     * take the report turn; stop it with `cancel` then.
+     *
+     * Slow by nature: the step it is in finishes first, and on a slow node or
+     * a looping model that can take minutes. `cancel` still ends it at once.
+     */
+    wrapUp(id: string, by?: SubagentStopActor): boolean;
+    /** A graceful stop has been asked for this agent and not yet ended it. */
+    wrappingUp(id: string): boolean;
+    /** What a live agent's controls are doing, or undefined when not running. */
+    inspect(id: string): SubagentControlState | undefined;
+    /**
+     * Who stopped the agent last registered under `id`, if anyone did. Kept
+     * past its release, so a report written after the run can say.
+     */
+    stoppedBy(id: string): SubagentStopActor | undefined;
+    /**
+     * Leave a message for this agent, read at its next turn boundary. `false`
+     * when nothing by that id is running.
+     *
+     * How the lead's side turn reaches the round it is waiting on: a message
+     * from the user while the lead sat inside its delegation call was queued
+     * for a turn the lead would not take until every agent had finished.
+     */
+    message(id: string, text: string): boolean;
+    /**
+     * Compact this agent's context before its next model request, as a manual
+     * compaction: its KV cells are given back without stopping it. `false`
+     * when nothing by that id is running or it has not started a model yet.
+     */
+    compact(id: string): boolean;
+    /** The agents running for this session, with the names they were given. */
+    runningIn(sessionId: string | undefined): Array<{
+        id: string;
+        label: string;
+    }>;
+    /** Ids of the agents running right now. For tests and diagnostics. */
+    running(): string[];
+}
+/** The agent a segment runs: its transcript, and -- a `SessionRuntime` -- a compaction on request. */
+export interface TrackedAgent {
+    getMessages(): readonly unknown[];
+    requestCompaction?(): void;
+}
+export interface SubagentCancellationRegistration {
+    /** What it is registered under: its row's id and the controls'. */
+    readonly id: string | undefined;
+    /**
+     * The signal to run under: the current attempt's, once `restartable` has
+     * started one. Read it when the agent is built, not once up front, or a
+     * restarted attempt runs on the signal of the one it replaced.
+     */
+    readonly signal: AbortSignal | undefined;
+    /**
+     * Run `run`, and run it again for as long as an attempt ends because it was
+     * restarted. `onRestart` goes between attempts: whatever the abandoned one
+     * held -- its engine session -- is given back there.
+     */
+    restartable<T>(run: () => Promise<T>, onRestart?: () => void | Promise<void>): Promise<T>;
+    /**
+     * Run `run` for as long as it ends because the agent was requeued: each
+     * time with the transcript the requeued segment left, so the agent carries
+     * on where it stopped. `onRequeue` goes between segments -- the engine
+     * session the stopped one held is given back there. Nested inside
+     * {@link restartable}: a restart still starts from the task.
+     */
+    continuable<T>(run: (carry: SubagentRequeueCarry | undefined) => Promise<T>, onRequeue?: (carry: SubagentRequeueCarry) => void | Promise<void>): Promise<T>;
+    /** The agent the current segment runs, so a requeue can take its transcript. */
+    track(agent: TrackedAgent): void;
+    /** Waiting on infrastructure, or not: a requeue then stops it at once. */
+    setWaitingInfra(waiting: boolean): void;
+    /**
+     * Requeue this agent, as the lead's `requeue_agent` would: the harness's
+     * own move off a node that refused it. `false` when it cannot be moved.
+     */
+    requeue(options?: SubagentRequeueOptions): boolean;
+    /** What the lead added to the task when it last restarted this agent. */
+    readonly instructions: string | undefined;
+    /** The next message left for this agent, for its `consumePendingUserMessage`. */
+    takeMessage: () => string | undefined;
+    release: () => void;
+}
+/**
+ * How a running sub-agent is named from outside.
+ *
+ * Session first, because a tool call id comes from the model and is only
+ * unique within the conversation that produced it -- two windows on two tasks
+ * can mint the same one, and stopping the wrong window's agent would be the
+ * worst possible bug in a stop button.
+ */
+export declare function subagentCancelId(sessionId: string | undefined, toolCallId: string | undefined): string | undefined;
+/**
+ * A signal for one sub-agent, aborted by its own stop or by the parent's.
+ *
+ * Returns the signal to run under and a release to call when the run ends,
+ * however it ends. `undefined` id means the caller could not name this agent
+ * -- no tool call id -- in which case it simply runs on the parent's signal as
+ * it always did, rather than being registered under a name nothing can send.
+ */
+export declare function registerSubagentCancellation(id: string | undefined, parent: AbortSignal | undefined, label?: string): SubagentCancellationRegistration;
+/** Its task, with what the lead added when it restarted it. */
+export declare function withRevisedInstructions(task: string, instructions: string | undefined): string;
+export declare const subagentCancellation: SubagentCancellation;
+/** Test seam: no run outlives its `finally`, so this is only for isolation. */
+export declare function __resetSubagentCancellations(): void;

package/dist/extensions/tools/team/subagent-layout.d.ts

@@ -0,0 +1,90 @@
+/**
+ * How a sub-agent's first request is laid out, and what it shares.
+ *
+ * Two layouts, chosen by where the agent runs.
+ *
+ * **On a PolyKV node** the request is built for deduplication, one shared layer
+ * per turn, in the order the engine's pool tree nests them:
+ *
+ *   system  the sub-agent base prompt           -- identical for every agent
+ *   user    the knowledge, with files inlined   -- identical for every agent given it
+ *   user    the instructions of the agent's role -- identical for every agent of it
+ *   user    the task                            -- the agent's own
+ *
+ * Each of the first three is a pool the engine holds once for the whole swarm
+ * (`polykv-swarm.ts`). The file is read here, once, and inlined: an agent that
+ * is only told the path reads it with its own tool, and every agent then holds
+ * a private copy -- measured, 51 agents each carrying the same 15,191-byte read
+ * result in their own suffix.
+ *
+ * **Everywhere else** there is nothing to dedupe against, so nothing changes
+ * for the model: the instructions are the system prompt and the knowledge
+ * rides at the top of the one task message -- with files named, not inlined,
+ * because the agent has the tools to read what it needs and a copy it may not
+ * need is context it pays for on every turn.
+ */
+/** What several agents are given in common. */
+export interface SubagentKnowledge {
+    /** Workspace files every agent given this knowledge works from. */
+    files?: string[];
+    /** Shared notes: findings, constraints, context. */
+    text?: string;
+}
+/**
+ * The system prompt of every pooled sub-agent.
+ *
+ * Fixed on purpose: it is the root of the pool tree, and a prompt that varied
+ * per agent would share nothing below it. What makes agents different goes in
+ * the instructions turn.
+ */
+export declare const SUBAGENT_BASE_PROMPT: string;
+/** Files larger than this are named rather than inlined. */
+export declare const SUBAGENT_INLINE_FILE_MAX_CHARS = 200000;
+export interface SubagentLayout {
+    /** The agent's system prompt. */
+    systemPrompt: string;
+    /** The agent's own task turn. */
+    task: string;
+    /**
+     * The shared turns at the head of the conversation, verbatim, before the
+     * task.
+     *
+     * Compaction must leave them exactly where they are: they are the pool the
+     * agent's every request attaches to, and a head rewritten by a summary
+     * matches nothing and shares nothing for the rest of the run.
+     */
+    pinnedHead: string[];
+    /** How many turns after the system turn are shared layers. */
+    layers: number;
+}
+export declare function buildSubagentLayout(options: {
+    /** The agent's role, as the lead wrote it. */
+    instructions: string;
+    task: string;
+    knowledge?: SubagentKnowledge;
+    /** Whether the agent runs on a PolyKV node. */
+    pooled: boolean;
+    cwd?: string;
+}): Promise<SubagentLayout>;
+type PrepareTurn<I, R> = (input: I) => Promise<R | undefined>;
+/**
+ * Keep the shared head out of compaction's reach.
+ *
+ * The turns are taken off the front before the pipeline sees the conversation
+ * and put back in front of whatever it returns, unchanged. Compaction then
+ * summarises only the agent's own work -- which is also the only part of the
+ * conversation that grows -- and every request after it still opens with the
+ * exact tokens of the pool.
+ *
+ * A conversation that does not start with the pinned turns is passed through
+ * untouched: something upstream already changed the head, and guessing where
+ * it went would be worse than leaving the pipeline to see the whole thing.
+ */
+export declare function pinConversationHead<I extends {
+    messages: readonly unknown[];
+    apiMessages?: readonly unknown[];
+    pinnedHead?: readonly unknown[];
+}, R extends {
+    messages: readonly unknown[];
+}>(prepare: PrepareTurn<I, R> | undefined, pinned: readonly string[]): PrepareTurn<I, R> | undefined;
+export {};

package/dist/extensions/tools/team/subagent-output.d.ts

@@ -0,0 +1,73 @@
+/**
+ * What a sub-agent is generating, in full, for the one row being inspected.
+ *
+ * The row's own line is a status: "Prefilling 39,050 / 56,042", "Writing
+ * editor call: 8,327 characters", or the last 400 characters of its text. That
+ * says what it is doing and hides how it is doing it -- a model reasoning in
+ * circles, or writing the wrong file, reads the same as one that is fine. The
+ * stream itself was never lost, only not kept.
+ *
+ * So each agent keeps its current step here: everything the model has
+ * generated since its latest request began -- thinking, answer text and the
+ * arguments of the tool calls it writes, in the order they arrive. A step
+ * starts over with the next request, so the call it just wrote stays readable
+ * while the tool runs.
+ *
+ * Nothing is sent anywhere unless someone subscribes: fifty agents streaming
+ * kilobytes each to a webview nobody is reading would cost the chat for
+ * nothing. The registry is the process's, keyed by the same id as
+ * `subagentCancellation`, and an agent's entry goes when its registration is
+ * released.
+ */
+/** What a stretch of the stream is. */
+export type SubagentOutputKind = "reasoning" | "text" | "tool";
+/** One stretch of the stream: consecutive output of one kind. */
+export interface SubagentOutputChunk {
+    kind: SubagentOutputKind;
+    text: string;
+    /** The tool whose arguments these are, for `kind: "tool"`. */
+    toolName?: string;
+    /** Which call, so two calls to the same tool stay two stretches. */
+    toolCallId?: string;
+}
+/** What a subscriber is told, after the snapshot it started from. */
+export type SubagentOutputEvent = 
+/** A new step began: what was shown is the previous step's. */
+{
+    type: "step";
+}
+/** More of the stream. Joins the last chunk when kind and call match. */
+ | {
+    type: "append";
+    chunk: SubagentOutputChunk;
+};
+export type SubagentOutputListener = (event: SubagentOutputEvent) => void;
+/**
+ * How much of a step is kept. An `editor` call carrying a whole file is the
+ * long case; past this the start of the step goes, as a terminal's scrollback
+ * would.
+ */
+export declare const SUBAGENT_OUTPUT_STEP_CHARS: number;
+/** Where one agent's progress writes its stream. */
+export interface SubagentOutputWriter {
+    append(chunk: SubagentOutputChunk): void;
+    /** A new request began: the step so far is over. */
+    step(): void;
+}
+export declare const subagentOutput: {
+    /** The writer for the agent registered under `id`. */
+    writer(id: string): SubagentOutputWriter;
+    /**
+     * Watch an agent's stream: the step so far, then what follows. An agent
+     * that has not written yet -- queued, or prefilling -- starts empty and
+     * fills in when it does. Call the returned function to stop.
+     */
+    subscribe(id: string, listener: SubagentOutputListener): {
+        snapshot: SubagentOutputChunk[];
+        unsubscribe: () => void;
+    };
+    /** The agent ended: its stream goes, unless someone is still looking. */
+    release(id: string): void;
+    /** Ids with an entry. For tests and diagnostics. */
+    ids(): string[];
+};