@cerebriline/core 4.100.240

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

@@ -0,0 +1,211 @@
+import { type PolykvReleaseResult } from "@cerebriline/llms";
+import { type AgentEvent, type TeamAgentActivity } from "@cerebriline/shared";
+import { type CompactionCause } from "../../context/compaction-cause";
+import type { RealizedSpawnSampling } from "./spawn-sampling";
+/**
+ * What a delegated agent is doing, reported on the tool call that started it.
+ *
+ * A sub-agent's own events are deliberately kept out of the main chat -- one
+ * agent's internals are already a conversation, and three at once is a flood.
+ * The consequence was that nothing about a running sub-agent reached the user
+ * at all: the UI reads `latestToolCall` off the spawn tool's progress, and no
+ * spawn path had ever emitted any, so the field was declared, parsed, rendered
+ * and always empty.
+ *
+ * Measured on pandorum 2026-09-22: three configured agents ran for between 80
+ * and 148 seconds each, and for all of it the only thing on screen was the
+ * lead's last tool call. Whether an agent was working, queued behind the
+ * endpoint, or dead was not answerable without the extension log.
+ *
+ * This closes over one spawn call, so no identity has to be reconstructed --
+ * the events it is given are its own agent's, and the update lands on its own
+ * tool call.
+ */
+export interface SubagentProgress {
+    /** Feed every event the delegated agent emits. */
+    observe(event: AgentEvent): void;
+}
+/** How much of an agent's latest output the UI is given. */
+export declare const SUBAGENT_OUTPUT_TAIL_CHARS = 400;
+/**
+ * How often output progress is reported, at most.
+ *
+ * Deltas arrive per token; fifty agents reporting each one would be thousands
+ * of chat updates a second for a tail nobody reads that fast.
+ */
+export declare const SUBAGENT_OUTPUT_REPORT_MS = 2000;
+/**
+ * The agent is waiting for a node: every node that could take it is full.
+ *
+ * Without this the UI had no way to tell a queued agent from a working one --
+ * every agent was shown running from the moment it was spawned, so a fan-out
+ * of seventy-five on nodes that take three looked like seventy-five at work.
+ */
+export declare function reportSubagentQueued(emitUpdate: ((update: unknown) => void) | undefined): void;
+/**
+ * The agent has a node and starts now. Sent at placement, not at the end: the
+ * node is what explains a slow agent while it is slow.
+ */
+export declare function reportSubagentPlaced(emitUpdate: ((update: unknown) => void) | undefined, placed: {
+    nodeId?: string;
+    nodeLabel?: string;
+} | undefined): void;
+/**
+ * Which model the agent runs on, sent when its attempt is built -- right after
+ * placement, next to `queued: false`. The row named the model only from the
+ * final result, so while an agent ran (the part where a slow or wrong model is
+ * worth knowing about) nothing said which one it was. Re-sent per attempt: a
+ * re-placement can land it on a node with a different model.
+ */
+export declare function reportSubagentModel(emitUpdate: ((update: unknown) => void) | undefined, model: {
+    providerId?: string;
+    modelId?: string;
+    /** The connection's model catalog, for the model's context window. */
+    knownModels?: Record<string, {
+        contextWindow?: number;
+    } | undefined>;
+    /** The iteration cap this attempt runs under, for the lead's status. */
+    maxIterations?: number;
+}): void;
+/**
+ * The sampler the agent was built with -- its realized seed and temperature,
+ * and when they were drawn, what around -- sent per build beside the model.
+ * A swarm experiment needs each agent's values to reproduce it, and the row
+ * (persisted with the task) is where they are kept. A requested value that
+ * could not be applied is also an info line on the row, never a warning.
+ */
+export declare function reportSubagentSampling(emitUpdate: ((update: unknown) => void) | undefined, sampling: RealizedSpawnSampling | undefined): void;
+/**
+ * The agent has ended: its row finishes now, with its result, and not when the
+ * whole call does.
+ *
+ * A batch or a swarm closed every row at the call's end, so an agent that was
+ * done sat on a "running" row, its output showing, until the slowest one
+ * finished -- sixteen rows running on 2026-09-24 while the server processed
+ * one. `report` is the member's own entry of the call's `results`, and an
+ * `error` on it is what marks the row failed.
+ */
+export declare function reportSubagentFinished(emitUpdate: ((update: unknown) => void) | undefined, report: object): void;
+/**
+ * What an agent's engine release said, for the log: a close that failed, an
+ * id the engine held no session under -- for an agent that sent requests,
+ * ours and the engine's have diverged -- and a session left to the idle TTL
+ * because the server has no close route. A clean release says nothing.
+ */
+export declare function logEngineRelease(log: ((line: string) => void) | undefined, released: PolykvReleaseResult | undefined, prefix: string): void;
+/**
+ * Between a restarted attempt and the next: the row says so, and the engine
+ * session the abandoned attempt held goes back -- after a server restart it is
+ * still booked there, and the new attempt would be charged to it.
+ */
+export declare function restarted(emitUpdate: ((update: unknown) => void) | undefined, engineSessionId: string | undefined): Promise<void>;
+/**
+ * The lead requeued the agent: it stopped at a boundary and goes back to the
+ * placement queue with its transcript. The row says so, and the engine
+ * session it held goes back -- it may be placed on another node.
+ */
+export declare function requeued(emitUpdate: ((update: unknown) => void) | undefined, engineSessionId: string | undefined, reason?: string): Promise<void>;
+/**
+ * Keep an agent's row honest while its requests wait for room on the engine.
+ *
+ * A PolyKV worker whose window is full is held inside the opencoti vendor's
+ * fetch, re-asking until another agent finishes. Nothing there can reach the
+ * agent's row, so it went on saying "running": 75 rows running on 2026-09-24
+ * while the server processed 27. The vendor reports each change under the
+ * agent's engine session; this turns it into the same `queued` the placement
+ * queue sends, with the reason as the row's output line.
+ *
+ * Returns the unsubscribe; call it when the agent is done, not between
+ * re-placements -- the listener belongs to the delegation.
+ */
+export declare function watchPolykvRoom(engineSessionId: string | undefined, emitUpdate: ((update: unknown) => void) | undefined, 
+/**
+ * Where a warning also goes, beside the row: a lost priority-0 sub-pool
+ * is a full prefill nobody sees on a row that has scrolled away.
+ */
+logger?: {
+    log?: (message: string, metadata?: {
+        severity?: "warn";
+    }) => void;
+}, 
+/** Told when a wait starts, with its reason: for the lead's report. */
+onWaiting?: (reason: string | undefined) => void): () => void;
+/**
+ * What every delegating tool tells the model about launching many agents.
+ *
+ * Measured on pandorum 2026-09-23 (sx4bp): asked for 75 reports, the lead
+ * spent its planning turn arguing with itself -- "that's 75 tool calls which
+ * is a LOT", "I'll do this in waves", "can I really make 75 tool calls at
+ * once?" -- five reversals before it launched them all together, which was
+ * right all along: placement queues what does not fit. Nothing in any
+ * description said so, so the model reasoned as if every call it made
+ * started a process on the spot.
+ */
+export declare const DELEGATION_PACING_NOTE = "Launching many is safe: the harness paces them. Each agent starts when a node has room for it and waits in a queue until then, so asking for more than can run at once overloads nothing -- it only means some start later. A call that waits returns when every agent in it has finished, and your next message is sent only after that -- so ask for the whole job at once: one `spawn_agent` call whose `agents` list holds every agent (a configured agent by `type`, several of one kind with `count`), or every call in the same message.";
+/**
+ * What an agent is doing right now, for the lead's `agents_status`: the
+ * stretch it is in, not its last event. A compaction or a condensation is a
+ * model call of its own that streams nothing the agent's row shows, and on a
+ * PolyKV node throughput drops to zero while it runs -- the lead read those
+ * silences as stuck agents and cancelled them (swarm 2026-09-27).
+ */
+export type AgentPhase = "requesting" | "server_queued" | "prefill" | "generating" | "thinking" | "writing" | "writing_tool_call" | "tool" | "compacting" | "condensing_thinking" | "recovering" | "waiting_room";
+/** The update that carries it: `{ phase: { name, detail? } }`. */
+export interface AgentPhaseUpdate {
+    name: AgentPhase;
+    detail?: string;
+}
+/** The phase a notice starts or ends, or `undefined` for one that says none. */
+export declare function phaseOfNotice(event: AgentEvent): AgentPhaseUpdate | "ended" | undefined;
+/** One finished compaction, as the agent's row reports it. */
+export interface SubagentCompaction {
+    cause: CompactionCause;
+    tokensBefore?: number;
+    tokensAfter?: number;
+}
+/**
+ * A compaction that has finished, read off the status notice the compaction
+ * pipeline emits (`phase: "completed"`). The `started` notice and a skipped
+ * one are not compactions. `cause` refines the kind where the pipeline knew
+ * more -- an automatic compaction the server's KV pressure caused -- and a
+ * notice from before that field existed falls back to the kind.
+ */
+export declare function readCompactionNotice(event: AgentEvent): SubagentCompaction | undefined;
+/**
+ * A compaction observer that logs one info line per completed compaction:
+ * the agent, the cause, and its tokens before and after. The row shows the
+ * count; the log is what is left to analyse after a run (swarm 0926).
+ */
+export declare function compactionLogger(name: string, logger: {
+    log?: (message: string) => void;
+} | undefined): ((compaction: SubagentCompaction) => void) | undefined;
+export declare function createSubagentProgress(emitUpdate: ((update: unknown) => void) | undefined, forward?: (event: AgentEvent) => void, now?: () => number, options?: {
+    /** Told of each completed compaction, row or no row. */
+    onCompaction?: (compaction: SubagentCompaction) => void;
+    /**
+     * The agent's `subagentCancellation` id: its whole current step is
+     * kept under it for the row's Inspect view.
+     */
+    outputId?: string;
+}): SubagentProgress;
+/**
+ * A running count of what an agent does -- tool calls and compactions -- for a
+ * holder that has no tool call to report on: a teammate, which outlives any
+ * one call. Built on the same observer every `spawn_agent` row is counted by,
+ * so the two can never count differently.
+ *
+ * `base` is where it starts: a restored teammate carries on from the count it
+ * was saved with. `observe` says whether the count moved, so a caller can
+ * report only on a change -- a teammate's every streamed token is an event.
+ */
+export interface ActivityCounter {
+    observe(event: AgentEvent): boolean;
+    snapshot(): TeamAgentActivity;
+}
+/**
+ * Whether a finished tool call failed: an error, or a result that says so.
+ * The file and command tools report a refusal as `success: false` in their
+ * output rather than as an error.
+ */
+export declare function toolFailed(error: unknown, output: unknown): boolean;
+export declare function createActivityCounter(base?: TeamAgentActivity): ActivityCounter;

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

@@ -0,0 +1,3 @@
+import type { DelegatedAgentRuntimeConfig } from "./delegated-agent";
+export declare function buildTeammateSystemPrompt(prompt: string, config: DelegatedAgentRuntimeConfig): string;
+export declare function buildSubAgentSystemPrompt(prompt: string, config: DelegatedAgentRuntimeConfig): string;

package/dist/extensions/tools/team/team-state-dates.d.ts

@@ -0,0 +1,10 @@
+import type { TeamRuntimeState } from "@cerebriline/shared";
+/**
+ * A team's state as it was saved, with its dates made dates again.
+ *
+ * The one reviver every reader of a saved team goes through: the SQLite
+ * store, the file store, the session's team file and the team tools. There
+ * were four copies, and a field added to one (B-10's `lastProgressAt`) had to
+ * be found and added to the other three by hand.
+ */
+export declare function reviveTeamStateDates(state: TeamRuntimeState): TeamRuntimeState;

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

@@ -0,0 +1,56 @@
+import { type AgentTool, type TeamTeammateSpec } from "@cerebriline/shared";
+import { type DelegatedAgentConfigProvider, type DelegatedAgentRuntimeConfig } from "./delegated-agent";
+import type { AgentTeamsRuntime } from "./multi-agent";
+export type TeamTeammateRuntimeConfig = DelegatedAgentRuntimeConfig;
+export interface CreateAgentTeamsToolsOptions {
+    runtime: AgentTeamsRuntime;
+    requesterId: string;
+    teammateConfigProvider: DelegatedAgentConfigProvider;
+    /**
+     * The builtin tools for one teammate, by its id: a sandboxing host opens the
+     * teammate's private workspace here and binds the tools to it.
+     */
+    createBaseTools?: (agentId: string) => AgentTool[];
+    allowSpawn?: boolean;
+    includeSpawnTool?: boolean;
+    includeManagementTools?: boolean;
+    onLeadToolsUnlocked?: (tools: AgentTool[]) => void;
+    /**
+     * The tools are a teammate's: {@link TEAMMATE_TEAM_TOOL_NAMES} only, and
+     * its `team_task` works the board without adding to it.
+     */
+    teammate?: boolean;
+}
+export interface BootstrapAgentTeamsOptions {
+    runtime: AgentTeamsRuntime;
+    teammateConfigProvider: DelegatedAgentConfigProvider;
+    /**
+     * The builtin tools for one teammate, by its id: a sandboxing host opens the
+     * teammate's private workspace here and binds the tools to it.
+     */
+    createBaseTools?: (agentId: string) => AgentTool[];
+    leadAgentId?: string;
+    restoredTeammates?: TeamTeammateSpec[];
+    restoredFromPersistence?: boolean;
+    includeLeadSpawnTool?: boolean;
+    includeLeadManagementTools?: boolean;
+    onLeadToolsUnlocked?: (tools: AgentTool[]) => void;
+}
+export interface BootstrapAgentTeamsResult {
+    tools: AgentTool[];
+    restoredFromPersistence: boolean;
+    restoredTeammates: string[];
+}
+export declare const TEAM_TOOL_NAMES: readonly ["team_spawn_teammate", "team_shutdown_teammate", "team_status", "team_task", "team_run_task", "team_cancel_run", "team_list_runs", "team_await_runs", "team_send_message", "team_broadcast", "team_read_mailbox", "team_mission_log", "team_cleanup", "team_create_outcome", "team_attach_outcome_fragment", "team_review_outcome_fragment", "team_finalize_outcome", "team_list_outcomes"];
+/**
+ * A teammate's team tools: the board, the mailbox, the mission log. The rest
+ * are the lead's. With them a teammate cancelled the lead's runs, finalized
+ * its outcomes, routed tasks to other teammates out of the lead's sight, and
+ * -- two teammates each awaiting "all runs" -- deadlocked (audit G-6, B-8).
+ * Their schemas were also a third of every teammate request's team tools.
+ */
+export declare const TEAMMATE_TEAM_TOOL_NAMES: ReadonlySet<string>;
+export declare function bootstrapAgentTeams(options: BootstrapAgentTeamsOptions): BootstrapAgentTeamsResult;
+export declare function createAgentTeamsTools(options: CreateAgentTeamsToolsOptions): AgentTool[];
+export { reviveTeamStateDates } from "./team-state-dates";
+export declare function sanitizeTeamName(name: string): string;

package/dist/extensions/tools/team/teammates-off.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Teammates are a setting, off by default, and a session can outlive a change
+ * to it: one that used teammates can be reopened after they were switched off.
+ *
+ * Nothing is restored then -- the team store is not opened and no `team_*`
+ * tool is offered, so the transcript's earlier team calls stay history -- and
+ * that is correct, but it is also invisible. This names it once, so a user
+ * reading the log after "where did my teammates go" finds the answer.
+ */
+export declare const TEAMMATES_OFF_RESTORE_NOTE = "[Agents] This session used teammates, but Teammates is off in settings: the team tools are not offered and its teammates are not restored. Turn Teammates on to bring them back.";
+/** Whether a transcript holds a call to any `team_*` tool. */
+export declare function historyUsedTeammates(messages: readonly {
+    content?: unknown;
+}[] | undefined): boolean;

package/dist/extensions/tools/team/token-split.d.ts

@@ -0,0 +1,28 @@
+/**
+ * An input count split into what the provider had cached and what it read
+ * fresh. `input` stays the whole prompt, every turn summed: an agent that
+ * sends a 30k prefix twenty times shows 600k, nearly all of it cached, and
+ * without the split that read as 600k of work (lead report, swarm wlafh).
+ *
+ * A gateway's input count holds the cached part; a provider that reports the
+ * cache apart (more cached than sent) gets it added. `cached` and `fresh` are
+ * absent when the provider reported no cache figure.
+ */
+export declare function splitInputTokens(input: number, cached: number | undefined): {
+    input: number;
+    cached?: number;
+    fresh?: number;
+};
+/** Usage as an agent's result states it to the lead. */
+export interface MemberUsage {
+    inputTokens: number;
+    outputTokens: number;
+    /** Of `inputTokens`, what the provider served from its cache. */
+    cachedInputTokens?: number;
+}
+/** A runtime's usage as the lead is told it, the cached part of the input named. */
+export declare function memberUsage(usage: {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+} | undefined): MemberUsage;

package/dist/extensions/tools/team/turn-fault-recovery.d.ts

@@ -0,0 +1,71 @@
+import { type TurnFaultRecovery } from "@cerebriline/shared";
+/** First wait after a refusal; doubles with each one in a row. */
+export declare const REFUSAL_BACKOFF_FIRST_MS = 2000;
+/**
+ * Longest wait between refused attempts: the one guard against a tight loop,
+ * and short enough that a pool that frees up is used within a minute.
+ */
+export declare const REFUSAL_BACKOFF_MAX_MS = 60000;
+/** Wait before the `attempt`th retry of a refusal (1-based). */
+export declare function refusalBackoffMs(attempt: number): number;
+/** What a waiting agent is waiting on. */
+export interface TurnFaultWait {
+    kind: "transport" | "refusal";
+    /** The node or server. */
+    where: string;
+    /** The refusal's text, or why the server is gone. */
+    detail: string;
+}
+export interface TurnFaultRecoveryOptions {
+    /** The agent, as its row and the log name it. */
+    label: string;
+    /** Where it runs, for the waiting line: a node label, or undefined. */
+    where?: () => string | undefined;
+    /** The server's base URL, for the health probe. Absent: back off only. */
+    baseUrl?: () => string | undefined;
+    headers?: () => Record<string, string> | undefined;
+    /** The agent's own stop, on top of the run's. */
+    signal?: AbortSignal;
+    /** The agent's row. */
+    emitUpdate?: (update: unknown) => void;
+    logger?: {
+        log: (message: string) => void;
+    };
+    /**
+     * Placed agents only: whether the engine has admitted this agent. Before
+     * it has, the fault goes back to the spawn queue, which can re-place it.
+     */
+    isAdmitted?: () => boolean;
+    /** A transport fault was seen: take the node out of rotation for a while. */
+    onTransportFault?: () => void;
+    /**
+     * A refused turn, on an admitted agent: move it to another node with room
+     * instead of waiting here. `true` when it is being moved; `false` when no
+     * other node has room (or the agent cannot be moved), and it waits.
+     *
+     * User ruling 2026-09-28: an agent the engine keeps refusing is moved,
+     * by priority, to a node that is free. Before this only `requeue_agent`
+     * moved an admitted agent, and the lead in h0o2o did it 21 times by hand.
+     */
+    relocate?: (reason: string) => boolean;
+    /**
+     * Told on every wait, and again on each health probe that finds the server
+     * still gone: what the agent is waiting on. For whoever tracks how long an
+     * agent has been stuck.
+     */
+    onWaiting?: (state: TurnFaultWait) => void;
+    /** Seams for tests. */
+    fetch?: typeof fetch;
+    sleep?: (ms: number, signal?: AbortSignal | null) => Promise<void>;
+    probe?: (root: string) => Promise<boolean>;
+}
+/**
+ * The server answered and failed the whole decode batch the turn was in:
+ * opencoti's "Invalid input batch." or its speculative sub-batch throw. The
+ * node is up and serving; calling it unreachable made the lead stop agents
+ * on a working node (swarm 0926).
+ */
+export declare const FAILED_BATCH_REASON = "it failed the batch this turn was in";
+/** Why the server went away, in the words the row uses. */
+export declare function transportFaultReason(message: string): string;
+export declare function createTurnFaultRecovery(options: TurnFaultRecoveryOptions): TurnFaultRecovery;