@cerebriline/core 4.100.240

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

@@ -0,0 +1,272 @@
+import type { AgentConfig, AgentEvent, AgentHooks, AgentTool, BasicLogger, HookErrorMode, ITelemetryService, ToolApprovalRequest, ToolApprovalResult } from "@cerebriline/shared";
+import { SessionRuntime } from "../../../runtime/orchestration/session-runtime-orchestrator";
+import type { WorkerStruggleSupervisor } from "../../../runtime/safety/worker-struggle";
+import type { DelegatedAgentCheck } from "./agent-check";
+import type { AgentNodePlacement } from "./agent-node-placement";
+import type { AgentSlotGate, AgentSlotGateRegistry } from "./agent-slot-gate";
+import { type RealizedSpawnSampling, type SpawnSamplingDraw } from "./spawn-sampling";
+type AgentExtension = NonNullable<AgentConfig["extensions"]>[number];
+export type DelegatedAgentConnectionConfig = Pick<AgentConfig, "providerId" | "modelId" | "apiKey" | "baseUrl" | "headers" | "onAuthError" | "providerConfig" | "knownModels" | "thinking" | "reasoningEffort" | "thinkingBudgetTokens" | "maxTokensPerTurn" | "maxToolResultChars" | "staleReadRewrites" | "temperature">;
+export interface DelegatedAgentRuntimeConfig extends DelegatedAgentConnectionConfig {
+    cwd?: string;
+    providerId: string;
+    clinePlatform?: string;
+    clineIdeName?: string;
+    maxIterations?: number;
+    /**
+     * Loop-detection and mistake-budget tuning for this agent's own runtime.
+     *
+     * Until now a delegated agent ran on whatever `execution` the lead's runtime
+     * config carried, which for a headless swarm worker is nothing worker-shaped:
+     * the exact-repeat loop tracker and the default mistake budget never catch a
+     * worker grinding on slightly-varying probes to the token cap. Carrying it
+     * here lets a spawn path hand a worker a tighter, worker-calibrated budget --
+     * see `worker-struggle.ts` -- without touching the shared runtime config.
+     */
+    execution?: AgentConfig["execution"];
+    /**
+     * What the server appends to reasoning it cut at the thinking budget, when
+     * the session knows it: how an agent's struggle supervisor tells a turn
+     * that ran out its budget. Without it the supervisor reads the generic
+     * admission in the reasoning's tail (`worker-struggle.ts`).
+     */
+    thinkingBudgetMessage?: string;
+    hooks?: AgentHooks;
+    extensions?: AgentExtension[];
+    logger?: BasicLogger;
+    telemetry?: ITelemetryService;
+    workspaceMetadata?: string;
+    /**
+     * Holds delegated agents to the number of requests their endpoint serves.
+     *
+     * Carried here because it is the one thing every spawn path already shares:
+     * the team runtime, the lead's `spawn_agent`, and a sub-agent spawning its
+     * own all read this provider, so one gate covers them without any of them
+     * knowing about the others. Omitted means no gate -- see
+     * `createAgentSlotGate` for when that is the right answer.
+     */
+    slotGate?: AgentSlotGate;
+    /**
+     * The same bound, held per endpoint, for the path that does not all run on
+     * this provider.
+     *
+     * `slotGate` above covers `spawn_agent`, whose sub-agents are free-form and
+     * always on this connection. A *configured* agent is not: its file may name
+     * a `providerId` or a `profile`, so several in one turn can be spread over a
+     * local server and a cloud one. Gating those together would queue an
+     * Anthropic agent behind a one-slot Ollama; not gating them at all -- which
+     * is what happened until now -- lets four agents pointed at that same Ollama
+     * be spawned four-wide, which is what the gate exists to prevent.
+     */
+    slotGates?: AgentSlotGateRegistry;
+    /**
+     * Where a delegated agent runs, when the profile configures agent nodes.
+     *
+     * A node is a whole agents configuration, so the node decides the agent's
+     * connection and has to be chosen BEFORE the agent is built. A spawn path
+     * that has this takes a node, builds the agent on that node's config
+     * provider, runs inside the node's own gate, and gives the node back --
+     * see `agent-node-placement.ts`. Absent is every session that names no
+     * node: the single delegated connection, and `slotGate` above.
+     */
+    nodePlacement?: AgentNodePlacement;
+    /**
+     * Priority 0 (PLANS §9g): this configuration is the lead's own opencoti
+     * connection, and a pooled agent built from it attaches as a sub-pool of
+     * the lead's session -- this id -- rather than of an owner opened for the
+     * swarm. Set only on the priority-0 node's provider; see
+     * `agent-node-placement.ts`. Absent everywhere else, which is every agent
+     * before this setting.
+     */
+    polykvLeadOwner?: string;
+    /**
+     * Stable end-user identity inherited from the parent session so
+     * delegated-agent telemetry (Langfuse `userId`) groups with the user.
+     */
+    distinctId?: string;
+    /**
+     * Root core session id inherited from the parent session so
+     * delegated-agent telemetry (Langfuse `sessionId`) groups with it.
+     */
+    sessionId?: string;
+    /**
+     * Builds this agent's context pipeline -- compaction and the thinking cap.
+     *
+     * A factory rather than the pipeline itself because compaction carries
+     * state: the lead's is bound to the session's sidecar, and every delegated
+     * agent needs one keyed to its own transcript. Called once per agent in
+     * {@link buildDelegatedAgentConfig}.
+     *
+     * Absent means this agent compacts never. That was the behaviour until now,
+     * and it is how a sub-agent reached 1.87x its model's context window across
+     * 34 consecutive requests with nothing in the transcript to say so.
+     */
+    createPrepareTurn?: (agent?: DelegatedPrepareTurnTarget) => AgentConfig["prepareTurn"];
+    /** The pipeline's other half; stateless, so shared rather than built. */
+    condenseDiscardedReasoning?: AgentConfig["condenseDiscardedReasoning"];
+}
+/**
+ * Whose compaction a delegated agent's pipeline is.
+ *
+ * The agent's own: its connection and its engine session. Built from the
+ * lead's instead -- as it was -- a sub-agent on an opencoti node summarised
+ * itself with the lead's model, measured its trigger against the lead's
+ * request counts, and read pool pressure in the lead's name.
+ */
+export interface DelegatedPrepareTurnTarget {
+    providerId: string;
+    modelId: string;
+    providerConfig: NonNullable<AgentConfig["providerConfig"]>;
+    engineSessionId?: string;
+}
+export interface DelegatedAgentConfigProvider {
+    getRuntimeConfig(): DelegatedAgentRuntimeConfig;
+    /**
+     * Hand this provider the session's node placement.
+     *
+     * A setter because the placement needs this provider to build from -- each
+     * node's connection is the session's with the node's fields over it -- so
+     * the two cannot both be constructed first. Optional on the interface for
+     * the hand-built providers a couple of hosts fall back to.
+     */
+    setNodePlacement?(placement: AgentNodePlacement): void;
+    getConnectionConfig(): DelegatedAgentConnectionConfig;
+    updateConnectionDefaults(overrides: Partial<DelegatedAgentConnectionConfig>): void;
+    /**
+     * The part of a session connection push the agents take: the fields
+     * their own connection names are left out. For an agent built earlier
+     * that the push reaches directly -- a live teammate -- so it keeps its own
+     * server as a new spawn would.
+     */
+    acceptedConnectionUpdates?(overrides: Partial<DelegatedAgentConnectionConfig>): Partial<DelegatedAgentConnectionConfig>;
+}
+export type DelegatedAgentKind = "subagent" | "teammate";
+export interface BuildDelegatedAgentConfigOptions {
+    kind: DelegatedAgentKind;
+    prompt: string;
+    tools: AgentTool[];
+    configProvider: DelegatedAgentConfigProvider;
+    parentAgentId?: string;
+    maxIterations?: number;
+    /**
+     * Per-build override of the runtime's loop-detection and mistake budget.
+     * Falls back to {@link DelegatedAgentRuntimeConfig.execution}. The swarm path
+     * uses it to hand each worker a tighter budget than the shared runtime.
+     */
+    execution?: AgentConfig["execution"];
+    abortSignal?: AbortSignal;
+    onEvent?: (event: AgentEvent) => void;
+    hookErrorMode?: HookErrorMode;
+    toolPolicies?: AgentConfig["toolPolicies"];
+    requestToolApproval?: (request: ToolApprovalRequest) => Promise<ToolApprovalResult> | ToolApprovalResult;
+    role?: string;
+    cwd?: string;
+    /**
+     * Hooks for this run alone, on top of the session's.
+     *
+     * The session's hooks belong to the session and are shared by every
+     * delegated run it starts. A background delegation needs one of its own --
+     * the barrier that holds it while the user has it paused -- and that barrier
+     * belongs to that run and no other.
+     */
+    hooks?: AgentHooks;
+    /**
+     * Something to say to this agent at its next turn boundary, if anything.
+     *
+     * The runtime asks at the one point in the loop with no tool call open, so
+     * what is handed back arrives inside the turn rather than as an invitation
+     * to go and fetch it. The session's own model has had this since steering
+     * existed; a delegated agent could not be reached at all, which was fine
+     * while nothing else was running beside one and is not fine now that the
+     * escalation's base model watches the expert and may need to stop it.
+     */
+    consumePendingUserMessage?: AgentConfig["consumePendingUserMessage"];
+    /**
+     * The engine session this agent runs in -- its own, never the lead's.
+     * See `AgentConfig.engineSessionId`.
+     */
+    engineSessionId?: string;
+    /** Attach to a shared PolyKV pool tree; see `AgentConfig.polykvWorker`. */
+    polykvWorker?: AgentConfig["polykvWorker"];
+    /**
+     * Shared turns at the head of the conversation that compaction must keep
+     * verbatim. See `subagent-layout.ts`.
+     */
+    pinnedHead?: readonly string[];
+    /**
+     * Watches a headless worker for a grind and stops it, per worker.
+     *
+     * The lead has a struggle layer; a delegated worker had none, and on the
+     * 75-agent swarm a third of them ground to the token cap without ever
+     * reporting. Passed here rather than composed in each spawn path because this
+     * builder is the one funnel both `spawn_agent` and the swarm pass through:
+     * wiring it once reaches both. When present it wraps this agent's tools so the
+     * one nudge lands on a result, folds every event into the supervisor, and ORs
+     * its stop into the agent's abort signal. See `worker-struggle.ts`. The
+     * supervisor is stateful and per-agent -- a caller that builds two agents
+     * gives each its own.
+     */
+    struggle?: WorkerStruggleSupervisor;
+    /**
+     * How this agent waits out a turn the server dropped or refused. Defaults
+     * to waiting on its own connection's server with no limit (see
+     * `turn-fault-recovery.ts`); a spawn path that placed the agent passes one
+     * that knows the node and whether the engine has admitted it.
+     */
+    recoverTurnFault?: AgentConfig["recoverTurnFault"];
+    /**
+     * The sampler the spawning call asked for: `temperature` and `seed`.
+     *
+     * A build option rather than a connection field, and applied after the
+     * connection is read, so that nothing which moves a connection -- the
+     * session's `updateConnectionDefaults`, a profile, a node's placement --
+     * can move it. Absent leaves the connection's sampler exactly as it was.
+     * See `spawn-sampling.ts`.
+     *
+     * Already drawn (`drawSpawnSampling`): a random seed is a number here, and
+     * a random temperature is a position in its range, made concrete against
+     * this build's connection -- the model's own temperature is only known
+     * once the node, and so the model, is.
+     */
+    sampling?: SpawnSamplingDraw;
+    /**
+     * Told what this build's sampler came to: the values applied, what a
+     * random one was drawn around, or why one was not applied. Called on every
+     * build with a sampler, so a re-placement reports its own.
+     */
+    onSampling?: (realized: RealizedSpawnSampling) => void;
+    /**
+     * The lead's check on this agent (`agent-check.ts`), judged at each of its
+     * completion attempts. Wired into the runtime's completion boundary -- the
+     * hook the change protocol's approved check uses -- so a failing check
+     * keeps the agent in the same run, within its iteration budget.
+     */
+    check?: DelegatedAgentCheck;
+}
+/**
+ * @param pinned Connection fields the session must not push over.
+ *
+ * Delegated agents normally track the session: the host pushes a model switch
+ * or a refreshed key through `updateConnectionDefaults` and the agents follow,
+ * which is what makes them agents *of* this session. When the agents have been
+ * given a connection of their own, that same push would silently move them back
+ * onto the lead's model — so the fields the override supplied are held, and
+ * everything else still gets through.
+ */
+export declare function createDelegatedAgentConfigProvider(initialConfig: DelegatedAgentRuntimeConfig, pinned?: readonly (keyof DelegatedAgentConnectionConfig)[]): DelegatedAgentConfigProvider;
+/**
+ * The worker spec with its owner, when the agent was placed on priority 0.
+ *
+ * Decided here, the one funnel every spawn path builds through, rather than at
+ * each of the three spawn sites: which node took the agent is a property of
+ * the configuration it was built from, and a site that forgot to ask would put
+ * a priority-0 agent in an owner the swarm opened -- quietly correct, and not
+ * what the setting says.
+ */
+export declare function withPolykvLeadOwner(worker: AgentConfig["polykvWorker"], owner: string | undefined): AgentConfig["polykvWorker"];
+export declare function buildDelegatedAgentConfig(options: BuildDelegatedAgentConfigOptions): AgentConfig & {
+    role?: string;
+};
+export declare function createDelegatedAgent(options: BuildDelegatedAgentConfigOptions): SessionRuntime;
+export { type AgentCheck, type AgentOracleResult, createDelegatedAgentCheck, type DelegatedAgentCheck, describeAgentCheck, readAgentCheck, } from "./agent-check";
+export { type AwaitingLeadEvent, type AwaitingLeadView, createDelegatedAgentLifetime, type DelegatedAgentLifetime, type DelegatedRunOutcome, type DelegatedStopReason, listAwaitingLead, onAwaitingLead, RESUME_AGENT_TOOL_NAME, type ResumeSuspendedResult, resumeSuspended, runDelegatedWithCap, stopSuspended, } from "./agent-iteration-cap";

package/dist/extensions/tools/team/delegated-sandboxes.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The private workspaces of every delegated agent in one session.
+ *
+ * Every path that runs an agent on the lead's behalf -- `spawn_agent`, swarm
+ * workers, configured agents (`subagent_<name>`), and teammates -- opens one
+ * here, keyed by whatever identifies that agent's run, and closes it when the
+ * agent is done. In between the agent's file tools resolve through its overlay
+ * and its shell (when it has one) is rooted at the native launcher, so nothing
+ * it does touches the lead's tree. What it changed comes back to the lead as
+ * revisions in the lead's own revision log, attributed to the agent and never
+ * written to disk.
+ *
+ * One object for all four paths so the rules cannot drift between them:
+ *
+ * - **The shell.** `run_commands` is offered only when the sandbox has a
+ *   launcher for this platform AND the user allowed agent commands. Either
+ *   missing and it is withheld -- an un-launched command runs against the real
+ *   workspace, which is the escape the sandbox exists to prevent.
+ * - **The hand-back.** Each changed file is seeded with the lead's current
+ *   on-disk version, then recorded as the agent's revision. A long-lived agent
+ *   (a teammate) hands back more than once, so each hand-back carries only
+ *   what changed since the last one.
+ * - **Disposal.** Idempotent, and it hands back first: an agent that failed,
+ *   was cancelled or was shut down still leaves its work where the lead can
+ *   find it.
+ */
+import type { RevisionLog } from "../../../runtime/atomic/file-revisions";
+import type { AgentSandbox } from "../../../runtime/sandbox/agent-sandbox";
+import type { DefaultExecutorsOptions } from "../executors";
+import { type DelegatedSandboxProvider } from "./agent-sandbox-executors";
+/** One file an agent handed back, and the revision it became. */
+export interface HandedRevision {
+    /** Workspace-relative path, forward-slashed. */
+    rel: string;
+    /** The revision number in the lead's log. */
+    index: number;
+    kind: string;
+}
+/** An agent's open workspace: what its toolset is built from. */
+export interface DelegatedWorkspace {
+    readonly sandbox: AgentSandbox;
+    /** Pass to `createBuiltinTools({ executorOptions })`. */
+    readonly executorOptions: DefaultExecutorsOptions;
+    /**
+     * Whether the agent gets `run_commands`: a launcher covers this platform and
+     * the user allowed agent commands. False means build it with
+     * `enableBash: false`, whatever the mode preset or routing rules say.
+     */
+    readonly allowCommands: boolean;
+}
+export interface DelegatedSandboxes {
+    /** The lead's workspace, read-only to every agent. */
+    readonly workspaceRoot: string;
+    /** Open a workspace for `key`. A key already open is closed first. */
+    open(key: string): Promise<DelegatedWorkspace>;
+    /** {@link open} for a caller that cannot await (a teammate's toolset). */
+    openSync(key: string): DelegatedWorkspace;
+    has(key: string): boolean;
+    /** The open workspace for `key`, if any: what the agent's check runs in. */
+    get(key: string): DelegatedWorkspace | undefined;
+    /**
+     * Fold what the agent changed since its last hand-back into the lead's
+     * revision log, attributed to `agentName`. The workspace stays open.
+     */
+    handBack(key: string, agentName: string): Promise<HandedRevision[]>;
+    /**
+     * Hand back anything outstanding, then dispose the overlay. A key that is
+     * not open is a no-op returning nothing, so every exit path may call it.
+     */
+    close(key: string, agentName: string): Promise<HandedRevision[]>;
+    /** Close every open workspace -- the session is ending. */
+    closeAll(): Promise<void>;
+}
+export interface CreateDelegatedSandboxesOptions {
+    provider: DelegatedSandboxProvider;
+    /** The "Agents can run commands" toggle. */
+    commandsEnabled: boolean;
+    /** The lead's revision log, read when a hand-back runs. */
+    revisionLog: () => RevisionLog | undefined;
+}
+export declare function createDelegatedSandboxes(options: CreateDelegatedSandboxesOptions): DelegatedSandboxes;
+/**
+ * The launcher an agent's commands run under, when it may run any: the same
+ * `wrapSpawn` its `run_commands` was built with. `undefined` -- no workspace,
+ * no launcher on this platform, or agent commands turned off -- means nothing
+ * may be run for the agent at all; never run it on the host instead.
+ */
+export declare function commandLauncherOf(workspace: DelegatedWorkspace | undefined): NonNullable<DelegatedWorkspace["executorOptions"]["bash"]>["wrapSpawn"];
+/**
+ * The launcher and root an agent's check runs under, from its open workspace
+ * (keyed as it was opened); `undefined` when it may run no command.
+ */
+export declare function commandSandboxOf(sandboxes: DelegatedSandboxes | undefined, key: string | undefined): {
+    wrapSpawn: NonNullable<ReturnType<typeof commandLauncherOf>>;
+    cwd: string;
+} | undefined;
+/**
+ * What an agent that was stopped before answering had got to, from its own
+ * transcript: its latest message, and what it called.
+ *
+ * A stopped agent reported only that it gave no answer, while an agent of the
+ * same round that ran into its cap wrote a full report -- and the stopped
+ * one's transcript held findings as good (pandorum h0o2o, 2026-09-28: the lead
+ * stopped 18 of 25 and got 18 disclaimers). A last turn to write one is not
+ * the answer: most were stopped *because* the server kept refusing them, and
+ * a final turn would be refused the same way. So this reads what is already
+ * there.
+ */
+export declare function partialFindings(messages: readonly unknown[]): string;
+/**
+ * The note that tells the lead where an agent's work went, to append to the
+ * agent's answer. Without it the lead reads or runs its own on-disk copy --
+ * unchanged, because the agent worked on a private overlay -- sees no fix, and
+ * calls the agent a liar (pandorum 2026-09-24).
+ *
+ * `text` is the agent's answer before the note, read to tell whether it gave
+ * one: an empty answer is the tell that the run ended without the agent saying
+ * what it did, and the usual cause is a final turn that produced no text and no
+ * *readable* tool call -- a tool call emitted inside the reasoning channel is
+ * swallowed, so the loop sees "no more tool calls" and finishes as "completed".
+ * The lead must not read that silence as success, and if the agent handed
+ * changes back it must be told they are unvetted (pandorum 2026-09-24, agent
+ * "fix-manic-miner").
+ */
+export declare function handbackNote(text: string, finishReason: string | undefined, agentName: string, handed: readonly HandedRevision[]): string;

package/dist/extensions/tools/team/delegated-tools.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The tools a delegated agent gets, on every path that starts one:
+ * `spawn_agent`, a configured `subagent_*` tool, and a swarm worker.
+ *
+ * Two things differ from the lead's set, both measured on pandorum
+ * 2026-09-24 (yglnz):
+ *
+ * - **A question goes to the lead, not the user.** An agent's `ask_question`
+ *   reached the user directly, and the whole round -- the lead included, since
+ *   it waits inside its delegation call -- sat for 1,141 s until they answered
+ *   a question about a tool, from an agent they could not place. Here the
+ *   agent's `ask_question` ends its run and its question is its report: the
+ *   lead reads it with the others' and decides whether to answer, run the
+ *   agent again, or ask the user itself.
+ * - **The host's stateless tools come along.** Delegated agents got core's
+ *   builtins only, so `check_file` -- which their instructions name -- was an
+ *   `unavailable tool` twice, and the question above was the agent asking how
+ *   to check braces without it. The ones shared are those that hold nothing
+ *   per session and start nothing: not the terminal, which would give every
+ *   agent of a round of 75 its own VS Code terminal, and not the browser,
+ *   which is one Chrome.
+ */
+import type { AgentTool } from "@cerebriline/shared";
+/** Host tools a delegated agent is given as well as its builtins. */
+export declare const DELEGATED_HOST_TOOLS: ReadonlySet<string>;
+export declare const ASK_LEAD_TOOL_NAME = "ask_question";
+/** How an agent's question reads in the report the lead receives. */
+export declare function formatQuestionForLead(question: string, options: readonly string[]): string;
+/**
+ * `ask_question` for a delegated agent: the same name and input, so an agent
+ * file that tells it to ask still works, but the call ends the agent's run and
+ * the question becomes what it reports to the lead.
+ */
+export declare function createAskLeadTool(): AgentTool;
+/**
+ * A delegated agent's tools from its builtins and the host's tools.
+ *
+ * A host tool replaces a builtin of the same name, as it does for the lead.
+ */
+export declare function delegatedAgentTools(builtins: readonly AgentTool[], hostTools: readonly AgentTool[] | undefined): AgentTool[];

package/dist/extensions/tools/team/delegation-call-hooks.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Hooks a caller attaches to one delegated run, carried on the tool context.
+ *
+ * A configured agent is reached through a tool, and a tool's only channel to
+ * its implementation is the input and the context. The input belongs to the
+ * model -- it is in the schema the model writes against -- so hooks that exist
+ * for one call and one call only travel on `context.metadata`, which the host
+ * already uses to say `delegatedByUser`.
+ *
+ * A function through a metadata bag is not pretty. The alternative is a
+ * registry threaded through `createConfiguredAgentTools` at session build time,
+ * which would mean the tool factory knowing about background runs, and a
+ * background run is a thing a user starts long after the tools were built.
+ * Reading and writing it live in this one file so the two ends cannot drift.
+ */
+import type { AgentHooks } from "@cerebriline/shared";
+export declare function withDelegationHooks(metadata: Record<string, unknown> | undefined, hooks: AgentHooks | undefined): Record<string, unknown> | undefined;
+export declare function readDelegationHooks(metadata: Record<string, unknown> | undefined): AgentHooks | undefined;
+/**
+ * How a run hands its caller the way to give its engine session back.
+ *
+ * A background delegation the user paused holds its engine session -- on an
+ * opencoti node a whole booked window -- for as long as the pause lasts. The
+ * session id is made inside the agent's tool, so the tool binds its release
+ * here and the caller calls it on pause. The next request after the resume
+ * books the session again.
+ */
+export type DelegationEngineSessionBinder = (release: () => Promise<unknown>) => void;
+export declare function withDelegationEngineSession(metadata: Record<string, unknown> | undefined, bind: DelegationEngineSessionBinder | undefined): Record<string, unknown> | undefined;
+export declare function readDelegationEngineSession(metadata: Record<string, unknown> | undefined): DelegationEngineSessionBinder | undefined;

package/dist/extensions/tools/team/engine-evictions.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Every session the engine evicted, as this process saw it.
+ *
+ * opencoti's partial eviction (patch 0233) drops the largest live sequence
+ * when the KV cannot fit another token, to keep the rest of the batch alive.
+ * Ruled after swarm 0926 on b108 (11 agents holding 20-31k of 64k ended on
+ * it): no session is ever evicted. An eviction is a critical failure and a
+ * bug in the engine, never an operating mode -- so the agent is retried like
+ * a refusal, and every eviction is counted here, where the lead's status
+ * (`agents_status`) and the round report read it, and reported at WARN by the
+ * agent loop.
+ *
+ * Also delivered live on the agent's row: every update the turn-fault
+ * recovery emits for an eviction carries `evicted`, that agent's count so
+ * far, for whoever keeps per-agent state from the row stream.
+ */
+/** One eviction. */
+export interface EngineEviction {
+    /** `Date.now()` when the agent was told. */
+    at: number;
+    /** The agent, as its row and the log name it. */
+    label: string;
+    /** The node or server that evicted it. */
+    where?: string;
+    /** The evicted session, when the loop knew it. */
+    sessionId?: string;
+    /** What the session held at the least: its last completed request. */
+    tokensHeld?: number;
+    /** The engine's text. */
+    message: string;
+}
+export declare function recordEngineEviction(eviction: EngineEviction): void;
+/** Every eviction since the process started. */
+export declare function engineEvictionCount(): number;
+/** The evictions kept, oldest first; optionally only those since `since`. */
+export declare function engineEvictions(since?: number): EngineEviction[];
+/** Test seam. */
+export declare function resetEngineEvictions(): void;

package/dist/extensions/tools/team/index.d.ts

@@ -0,0 +1,20 @@
+export { type AgentCheck, AgentCheckSchema, type AgentOracleResult, createDelegatedAgentCheck, type DelegatedAgentCheck, describeAgentCheck, readAgentCheck, } from "./agent-check";
+export { AGENT_CONTROLS_NOTE, AGENT_SANDBOX_ROLE_NOTE, AgentControlFields, maxIterationsOf, readMaxIterations, } from "./agent-controls";
+export { type AwaitingLeadEvent, type AwaitingLeadView, createDelegatedAgentLifetime, type DelegatedAgentLifetime, type DelegatedRunOutcome, type DelegatedStopReason, describeAwaitingLead, listAwaitingLead, onAwaitingLead, RESUME_AGENT_TOOL_NAME, type ResumeSuspendedResult, resumeSuspended, runDelegatedWithCap, type SubagentStopOutcome, stopSubagent, stopSuspended, } from "./agent-iteration-cap";
+export { type AgentNodePlacement, type AgentNodeRuntimeConfig, createAgentNodePlacement, type PlacedAgentNode, POLYKV_LEAD_NODE_ID, POLYKV_LEAD_NODE_LABEL, PRIMARY_OVERFLOW_NODE_ID, type SessionAgentNodesInput, sessionAgentNodes, } from "./agent-node-placement";
+export { type AgentNode, capLeadTier, emptyPlacementState, LEAD_PRIORITY, LEAD_SUBPOOL_CAPACITY, type Placement, type PlacementState, placeAgent, } from "./agent-placement";
+export { type AgentPlacementQueue, createAgentPlacementQueue, NODE_COOL_OFF_MS, NoAgentCapacityError, type PlacementLease, } from "./agent-placement-queue";
+export { AGENT_SUMMARY_MAX_CHARS, clearAgentReports, createReadAgentReportTool, READ_AGENT_REPORT_TOOL_NAME, readAgentReport, recordAgentReport, } from "./agent-reports";
+export { type BackgroundDelegationControls, type BackgroundDelegationRegistry, type BackgroundDelegationStatus, type BackgroundDelegationView, createBackgroundDelegationRegistry, type StartBackgroundDelegationInput, startBackgroundDelegation, } from "./background-delegations";
+export { type ConfiguredAgentConfig, type ConfiguredAgentLoadResult, type ConfiguredAgentReadError, loadConfiguredAgentConfigs, parseConfiguredAgentConfig, } from "./configured-agent-config";
+export { type AgentProfileConnection, type AgentProviderConnection, buildConfiguredAgentToolDescriptors, buildConfiguredAgentToolName, type ConfiguredAgentInput, type ConfiguredAgentToolConfig, type ConfiguredAgentToolDescriptor, createConfiguredAgentTools, } from "./configured-agent-tool";
+export { type ConfiguredAgentDelegationResult, type ConfiguredAgentSummary, type DelegateToConfiguredAgentInput, delegateToConfiguredAgent, findConfiguredAgent, listConfiguredAgentSummaries, renderDelegationForTranscript, UnknownConfiguredAgentError, } from "./delegate-to-agent";
+export { type EngineEviction, engineEvictionCount, engineEvictions, recordEngineEviction, resetEngineEvictions, } from "./engine-evictions";
+export { isNodeUnreachable } from "./node-reachability";
+export { buildTeamProgressSummary, toTeamProgressLifecycleEvent, } from "./projections";
+export * from "./runtime";
+export { isSessionAllocationFull, retryWhileSessionFull, } from "./session-window-retry";
+export type { SubAgentEndContext, SubAgentSettledContext, SubAgentStartContext, } from "./spawn-agent-tool";
+export { createSpawnSwarmTool, DEFAULT_MAX_SWARM_WORKERS, type SpawnSwarmInput, SpawnSwarmInputSchema, type SpawnSwarmOutput, type SpawnSwarmToolConfig, SWARM_REDUCER_PROMPT, type SwarmPoolSnapshot, type SwarmPoolSource, type SwarmWorkerRequest, } from "./spawn-swarm-tool";
+export { subagentCancelId, subagentCancellation, } from "./subagent-cancellation";
+export { SUBAGENT_OUTPUT_STEP_CHARS, type SubagentOutputChunk, type SubagentOutputEvent, subagentOutput, } from "./subagent-output";

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

@@ -0,0 +1,92 @@
+/**
+ * The lead's controls over its delegated agents (spec C).
+ *
+ * - `requeue_agent`: stop an agent at its next boundary and put it back in
+ *   the placement queue with its transcript. The harness picks the node; a
+ *   reason of `slow` or `malfunction` sends it anywhere but where it was.
+ * - `restart_agent`: start it over from its task, in its place in the round,
+ *   with its check, its sampler (a random seed drawn again) and its cap.
+ * - `resume_agent`: carry on an agent held at its iteration cap.
+ * - `retry_failed`: run a round's failed and cancelled agents again from the
+ *   tasks they were given.
+ * - `message_agents` / `stop_agents`: what the side turn could already do,
+ *   now from the lead's own turn too, by id or by name.
+ *
+ * Every control takes an agent's id (`r3-2`) or its name, and every one works
+ * for every delegated path that opens a round -- `spawn_agent` single and
+ * batch, configured agents, swarm workers -- because they all go through the
+ * round registry and the stop registry. A teammate is not a round, but its
+ * running task is in the stop registry under the teammate's name: stop,
+ * restart, message and requeue reach it there.
+ *
+ * None of these routes an agent by hand. Infrastructure trouble is the
+ * harness's to retry (ruling 1); these are for an agent whose *work* the lead
+ * wants handled differently.
+ */
+import type { AgentTool } from "@cerebriline/shared";
+import { RESUME_AGENT_TOOL_NAME } from "./agent-iteration-cap";
+import { type AgentRounds, type RoundAgentRecord, type RoundRecord } from "./agent-rounds";
+export declare const REQUEUE_AGENT_TOOL_NAME = "requeue_agent";
+export declare const RESTART_AGENT_TOOL_NAME = "restart_agent";
+export { RESUME_AGENT_TOOL_NAME };
+export declare const RETRY_FAILED_TOOL_NAME = "retry_failed";
+export declare const MESSAGE_AGENTS_TOOL_NAME = "message_agents";
+export declare const STOP_AGENTS_TOOL_NAME = "stop_agents";
+export declare const AWAIT_AGENTS_TOOL_NAME = "await_agents";
+export declare const COMPACT_AGENTS_TOOL_NAME = "compact_agents";
+/**
+ * The tools that act on agents, as opposed to looking at them. An
+ * escalation's expert gets none of them (spec: status only).
+ */
+export declare const LEAD_CONTROL_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * The controls that reach a teammate's running task. The rest act on rounds,
+ * which a team alone never opens.
+ */
+export declare const TEAMMATE_CONTROL_TOOL_NAMES: ReadonlySet<string>;
+/** An agent the lead named, resolved. */
+export interface ResolvedAgent {
+    ref: string;
+    round?: RoundRecord;
+    agent?: RoundAgentRecord;
+    /** Its live control, while it runs. */
+    cancelId?: string;
+    label: string;
+}
+/**
+ * Resolve an agent by id or name: a round's agent first, then any agent
+ * running for the session under that name (a path with no round).
+ */
+export declare function resolveAgent(sessionId: string, ref: string, rounds?: AgentRounds): ResolvedAgent | undefined;
+/**
+ * The agents a message or a stop goes to: those named (by id or name), or
+ * every agent running for the session.
+ */
+export declare function resolveTargets(sessionId: string, refs: readonly string[] | undefined): {
+    targets: ResolvedAgent[];
+    unknown: string[];
+};
+export declare const REQUEUE_AGENT_DESCRIPTION = "Stop an agent at its next turn boundary and put it back in the placement queue, keeping its transcript: it continues where it was, it does not start over. The harness picks the node -- you cannot, and never need to: waits on a server are already retried on their own. `reason` is for you and the log; `slow` or `malfunction` also sends it anywhere but its current node when another has room. Use it for an agent crawling on an overloaded node or behaving oddly there; use restart_agent when its work itself went wrong.";
+export declare const RESTART_AGENT_DESCRIPTION = "Start an agent over from its original task, discarding its transcript and its workspace changes. It keeps its place in the round, its check, its sampler (a random seed is drawn again) and its iteration cap. `instructions` are added to its task as revised instructions -- say what to do differently. Works on a running agent and on one that has finished, failed or been stopped; a finished agent's new report reaches you when it ends.";
+export declare const RESUME_AGENT_DESCRIPTION = "Continue agents that are waiting for you (awaiting_lead): stopped at their iteration cap, by the loop guard for repeating the same call, or by the struggle supervisor for grinding on after being told to commit a SUMMARY. Each carries on from where it stopped, with its transcript and its changes. One call takes several: `agent_ids`, or leave it out for every agent waiting on you. `extra_iterations` defaults to the cap each was spawned with (60 -> 120 -> 180). `instructions` are added as they resume -- for a looping agent, say what to do instead of the call it repeated; for a struggling one, what to settle for. To take the work as it is instead, stop_agents; to start over, restart_agent.";
+export declare const RETRY_FAILED_DESCRIPTION = "Run a round's failed and cancelled agents again, each from the task it was originally given (and any revised instructions from a restart), with the same check, sampler and cap. `agent_ids` limits it to some of them. The round reports again when they finish. Infrastructure trouble never fails an agent -- it is retried on its own -- so what this reruns failed on its task: consider restart_agent with instructions for one that will fail the same way again.";
+export declare const MESSAGE_AGENTS_DESCRIPTION = "Leave a message for running agents. Each reads it at its next turn, between tool calls, and carries on with it in mind. Use it to pass on a change of plan, a constraint, or an answer.";
+export declare const STOP_AGENTS_DESCRIPTION = "Stop agents. A last resort: its task ends unfinished, and is lost unless you run it again. Slowness and a full server are not reasons to stop one: the harness paces agents and retries refusals, the PolyKV server frees KV cells on its own, and while an agent compacts its throughput drops to zero for minutes -- that is progress, not a hang (agents_status shows each agent's phase). To free KV cells, compact_agents; to move an agent off a slow node, requeue_agent; to change its course, message_agents. The rest of its round carries on. By default the stop is graceful: the agent finishes the step it is in, then gets one turn with no tools to report what it changed, found and verified, and where it stopped -- its report reaches you as its result, marked as partial work, and its file changes are kept. That takes as long as its step plus one reply, minutes on a slow node or a looping model. `immediate: true` ends it at once, with its file changes and no report -- also the way to end one already stopping gracefully. An agent waiting on you (at its cap, looping, struggling) is ended where it stopped, after the same report turn unless `immediate`.";
+export declare const COMPACT_AGENTS_DESCRIPTION = "Compact running agents' context, giving their KV cells back without stopping them -- what to do instead of stop_agents when a PolyKV node is short of cells. Each compacts before its next model request: a summary call during which its throughput is zero, often for minutes, and after which it carries on with a summary in place of its detailed history. Rarely needed: agents compact on their own when their node's KV pressure reaches its threshold (0.85 unless configured), and the server frees cells itself. Use it only on agents holding a large share of a node's cells while the node's pressure is near its threshold -- agents_status shows both. An agent already compacting, or waiting on you, is left as it is.";
+export interface LeadAgentToolsOptions {
+    sessionId: string;
+    /** What each tool did, in words: the side turn reports it to the lead. */
+    onAction?: (line: string) => void;
+}
+/** requeue_agent, restart_agent, resume_agent, retry_failed. */
+export declare function createLeadAgentControlTools(options: LeadAgentToolsOptions): AgentTool[];
+/** message_agents and stop_agents, by id or name, from any turn of the lead. */
+export declare function createLeadAgentMessagingTools(options: LeadAgentToolsOptions): AgentTool[];
+export declare const AWAIT_AGENTS_DESCRIPTION = "Wait for rounds running in the background to finish, and get their reports. With no arguments it waits for every round still running; `round_id` (or `round_ids`) waits for those. You need it only when you have nothing else to do until the agents are done: a background round's report is delivered to you on its own when it ends. A message for you -- from the user, or the agent system's report of a stuck agent -- ends the wait: this call returns, you read the message, and you can wait again.";
+/**
+ * Wait for background rounds, as a call that waited would have: their
+ * reports come back as this call's result, and not as a notice as well.
+ */
+export declare function createAwaitAgentsTool(options: LeadAgentToolsOptions): AgentTool;
+/** Everything the lead has over its agents, for its own turn. */
+export declare function createLeadAgentTools(options: LeadAgentToolsOptions): AgentTool[];