@cerebriline/core 4.100.240

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

@@ -0,0 +1,450 @@
+/**
+ * Reusable spawn_agent tool for delegating tasks to sub-agents.
+ */
+import { type AgentConfig, type AgentEvent, type AgentHooks, type AgentResult, type AgentTool, type AgentToolContext, type BasicLogger, type HookErrorMode, type ITelemetryService, type ToolApprovalRequest, type ToolApprovalResult, type ToolPolicy } from "@cerebriline/shared";
+import { z } from "zod";
+import type { OracleSpawnWrapper } from "../../../runtime/atomic/oracle";
+import { type AgentCheck, type AgentOracleResult } from "./agent-check";
+import { type DelegatedRunOutcome, type DelegatedStopReason } from "./agent-iteration-cap";
+import { type AgentFacts, type RoundHandle } from "./agent-rounds";
+import { type SpawnBatchReport } from "./batch-report";
+import type { ConfiguredAgentConfig } from "./configured-agent-config";
+import { type DelegatedAgentConfigProvider } from "./delegated-agent";
+import { type RealizedSpawnSampling } from "./spawn-sampling";
+import { withRevisedInstructions } from "./subagent-cancellation";
+import { type MemberUsage } from "./token-split";
+/** The tool a model calls to hand a self-contained piece of work to a subagent. */
+export declare const SPAWN_AGENT_TOOL_NAME = "spawn_agent";
+type AgentExtension = NonNullable<AgentConfig["extensions"]>[number];
+type AgentFinishReason = AgentResult["finishReason"];
+export declare const SpawnAgentInputSchema: z.ZodObject<{
+    wait: z.ZodOptional<z.ZodBoolean>;
+    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>>;
+    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>;
+    knowledge: z.ZodOptional<z.ZodObject<{
+        files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        text: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    instructions: z.ZodOptional<z.ZodString>;
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    task: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Several agents in one call.
+ *
+ * What the model reaches for first: asked for 75 reports in the sx4bp run
+ * (pandorum, 2026-09-23), the lead planned "a swarm", found only a one-agent
+ * tool, and spent its turn deciding whether 75 calls was too many before
+ * writing all 75 -- each repeating the same `knowledge` and `instructions`.
+ * A list states the shared parts once and is one call.
+ */
+export declare const SpawnAgentMemberSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    task: z.ZodString;
+    instructions: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
+    count: z.ZodOptional<z.ZodNumber>;
+    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>;
+/** Most agents one entry's `count` may ask for. */
+export declare const MAX_AGENTS_PER_ENTRY = 100;
+/**
+ * One entry per agent, with each `count` spelled out.
+ *
+ * Copies are named `<name>-<n>` so their rows and reports tell them apart.
+ * The host expands the same way (`spawnBatchMembers`), which is what keeps a
+ * row keyed `<call>#<index>` on the agent it shows.
+ *
+ * An entry's `seed` is offset by the copy's index -- seed 7 with count 3 is
+ * 7, 8 and 9 -- so that copies running one task do not draw identical samples.
+ * Its `temperature` is the same for every copy.
+ */
+export declare function expandAgentCounts(agents: readonly SpawnAgentMember[]): SpawnAgentMember[];
+export declare const SpawnAgentBatchInputSchema: z.ZodObject<{
+    wait: z.ZodOptional<z.ZodBoolean>;
+    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>>;
+    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>;
+    knowledge: z.ZodOptional<z.ZodObject<{
+        files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        text: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    instructions: z.ZodOptional<z.ZodString>;
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    task: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    agents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        task: z.ZodString;
+        instructions: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodString>;
+        count: z.ZodOptional<z.ZodNumber>;
+        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>>>;
+}, z.core.$strip>;
+/** Only offered when the session can run swarms. */
+export declare const SpawnAgentSwarmInputSchema: z.ZodObject<{
+    wait: z.ZodOptional<z.ZodBoolean>;
+    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>>;
+    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>;
+    knowledge: z.ZodOptional<z.ZodObject<{
+        files: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        text: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    instructions: z.ZodOptional<z.ZodString>;
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    task: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    agents: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        task: z.ZodString;
+        instructions: z.ZodOptional<z.ZodString>;
+        type: z.ZodOptional<z.ZodString>;
+        count: z.ZodOptional<z.ZodNumber>;
+        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>>>;
+    merge: z.ZodOptional<z.ZodBoolean>;
+    count: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"max">]>>;
+}, z.core.$strip>;
+export type SpawnAgentMember = z.infer<typeof SpawnAgentMemberSchema>;
+export type SpawnAgentInput = z.infer<typeof SpawnAgentInputSchema> & {
+    agents?: SpawnAgentMember[];
+    merge?: boolean;
+    count?: number | "max";
+    /**
+     * What the harness changed about the call while reading it, for the lead:
+     * agents renamed apart, a field that does nothing here. Not part of the
+     * schema -- set by `checkMembers`, reported with the call's result.
+     */
+    setupNotes?: string[];
+};
+/** One agent of a batch, as reported back. */
+export interface SpawnAgentMemberOutput extends Partial<SpawnAgentOutput> {
+    name: string;
+    /** Set when this agent failed; its siblings' reports are unaffected. */
+    error?: string;
+    /** Times the engine evicted it (an engine bug each time), when it did. */
+    evicted?: number;
+}
+/**
+ * An `agents` call's result: an aggregate, an index of every agent, and as
+ * many reports as fit -- the rest named, to read with `read_agent_report`.
+ * See `batch-report.ts`.
+ */
+export type SpawnAgentBatchOutput = SpawnBatchReport;
+export interface SpawnAgentOutput {
+    text: string;
+    iterations: number;
+    finishReason: AgentFinishReason;
+    usage: MemberUsage;
+    /**
+     * Which model actually spent those tokens.
+     *
+     * Not always the session's: agents can be given a connection of their own,
+     * and a configured agent may name a provider per file. Without this the
+     * host can only add a sub-agent's tokens to the lead's total, which is the
+     * difference between free local tokens and billed ones going unrecorded.
+     */
+    model?: {
+        id: string;
+        provider: string;
+    };
+    /**
+     * Which agent node this agent was placed on, when the session has any.
+     *
+     * The model and the node are different facts and both are worth showing:
+     * two nodes can carry the same model on two endpoints, and the reason a
+     * fan-out is slow is usually which node took the work rather than which
+     * model did it. Absent on a session with no nodes, where there is only
+     * one place an agent can run and naming it says nothing.
+     */
+    nodeId?: string;
+    /** What the settings panel calls that node: `Node1`, `Node2`. */
+    nodeLabel?: string;
+    /**
+     * The sampler the call asked for, when it asked: what this agent ran with
+     * over its model's own -- a random seed or temperature as drawn, with what
+     * it was drawn around. Absent means the model's own throughout.
+     */
+    sampling?: RealizedSpawnSampling;
+    /** The agent's own id: what `resume_agent` and the status tool name it by. */
+    agentId?: string;
+    /** Its cap: the first one plus every raise. Absent is no cap. */
+    maxIterations?: number;
+    /** Set when the iteration cap is what ended it (the lead stopped it there). */
+    stopReason?: DelegatedStopReason;
+    /**
+     * `awaiting_lead`: it is at its cap, waiting, work kept -- continue it with
+     * `resume_agent`. Only when nothing could ask the lead during the round.
+     */
+    state?: "awaiting_lead";
+    /** The lead's check, when one was set: pass, fail or not run. */
+    oracle?: AgentOracleResult;
+    /**
+     * Its place in the round and how it ended (section F): id, state, stop
+     * reason, iterations against its cap, tokens, compactions, check, sampler
+     * and node. Set on the result the lead is handed.
+     */
+    agent?: AgentFacts;
+}
+export interface SubAgentStartContext {
+    subAgentId: string;
+    conversationId: string;
+    parentAgentId: string;
+    input: SpawnAgentInput;
+    /**
+     * The spawning tool call. Unique per spawned agent (batch spawns suffix the
+     * index), and known before the agent's own id exists, so it is the key a
+     * per-agent sandbox is registered under and later handed back by. Optional
+     * because a tool context need not carry one; sandboxing is skipped when it
+     * does not.
+     */
+    toolCallId?: string;
+}
+export interface SubAgentEndContext {
+    subAgentId: string;
+    conversationId: string;
+    parentAgentId: string;
+    input: SpawnAgentInput;
+    /** The spawning tool call; see {@link SubAgentStartContext.toolCallId}. */
+    toolCallId?: string;
+    result?: SpawnAgentOutput;
+    agentResult?: AgentResult;
+    error?: Error;
+}
+/** How a delegation that has ended is identified to its last observer. */
+export interface SubAgentSettledContext {
+    /** The spawning tool call; see {@link SubAgentStartContext.toolCallId}. */
+    toolCallId?: string;
+    /** The agent's name, as the lead gave it or as its file names it. */
+    name: string;
+}
+export interface SpawnAgentToolConfig {
+    configProvider: DelegatedAgentConfigProvider;
+    /**
+     * Whether the session also offers the `team_*` tools. Only then does the
+     * description point at them: with Teammates off (the default) a sentence
+     * sending the model to tools it was not given is a call that fails.
+     */
+    teammates?: boolean;
+    defaultMaxIterations?: number;
+    subAgentTools?: AgentTool[];
+    createSubAgentTools?: (input: SpawnAgentInput, context: AgentToolContext) => AgentTool[] | Promise<AgentTool[]>;
+    onSubAgentEvent?: (event: AgentEvent) => void;
+    /**
+     * Lifecycle hooks forwarded to spawned sub-agent runs.
+     */
+    hooks?: AgentHooks;
+    /**
+     * Extension list forwarded to spawned sub-agent runs.
+     */
+    extensions?: AgentExtension[];
+    /**
+     * Error handling mode for forwarded lifecycle hooks.
+     */
+    hookErrorMode?: HookErrorMode;
+    /**
+     * Called after a sub-agent instance is created and before it starts running.
+     * Errors are ignored so lifecycle observers cannot break task execution.
+     */
+    onSubAgentStart?: (context: SubAgentStartContext) => void | Promise<void>;
+    /**
+     * Called once a sub-agent run finishes (success or error).
+     * Errors are ignored so lifecycle observers cannot break task execution.
+     */
+    onSubAgentEnd?: (context: SubAgentEndContext) => void | Promise<void>;
+    /**
+     * Called once the spawn is over, however it ended -- including the paths
+     * {@link onSubAgentEnd} never sees, where the agent failed or was stopped
+     * before it started. Whatever `createSubAgentTools` opened for this call
+     * (its private workspace) is released here, so nothing outlives the call.
+     * Errors are ignored.
+     */
+    onSubAgentSettled?: (context: SubAgentSettledContext) => void | Promise<void>;
+    /**
+     * Optional per-tool policy for spawned sub-agents.
+     */
+    toolPolicies?: Record<string, ToolPolicy>;
+    /**
+     * Optional approval callback for spawned sub-agent tool calls.
+     */
+    requestToolApproval?: (request: ToolApprovalRequest) => Promise<ToolApprovalResult> | ToolApprovalResult;
+    /**
+     * Optional logger forwarded to spawned sub-agent runs.
+     */
+    logger?: BasicLogger;
+    telemetry?: ITelemetryService;
+    /**
+     * The configured agents an `agents[].type` may name, keyed by
+     * {@link configuredAgentKey}. Each runs through its own tool, so its role,
+     * model and placement are exactly what a direct `subagent_<name>` call
+     * would give it.
+     */
+    configuredAgents?: () => ReadonlyMap<string, AgentTool>;
+    /** The same agents' definitions, keyed alike: what a swarm worker needs. */
+    configuredAgentConfigs?: () => ReadonlyMap<string, ConfiguredAgentConfig>;
+    /**
+     * The session's swarm, when it can run one. Present means `merge` and
+     * `count` are offered and routed to it, and `spawn_swarm` is not
+     * registered on its own.
+     */
+    swarm?: AgentTool;
+    /**
+     * The launcher an agent's commands run under, keyed by its spawning tool
+     * call: where its `check` is run. `undefined` -- or no resolver -- is no
+     * command sandbox, and the check is reported as not run.
+     */
+    commandSandboxFor?: (toolCallId: string | undefined) => {
+        wrapSpawn: OracleSpawnWrapper;
+        cwd: string;
+    } | undefined;
+    /**
+     * The lead's session, when the tool is built for one: its rounds can then
+     * run an agent again from their record (`retry_failed`) without the call
+     * that first ran it.
+     */
+    sessionId?: string;
+}
+/** The key a configured agent is looked up by: `JS-Syntactic`, `js_syntactic` and `subagent_js_syntactic` are one agent. */
+export declare function configuredAgentKey(name: string): string;
+export declare function describeSpawnAgent(swarm: boolean, teammates?: boolean): string;
+/**
+ * `agents` as the list it was meant to be, or a refusal that says how to send it.
+ *
+ * Measured on pandorum 2026-09-23 (5rybo): qwen sent `agents` as text, twice,
+ * and the text was the list followed by the rest of the call --
+ * `[{...}, ...], "merge": true`. That is not JSON on its own, it went through
+ * as a string, and the batch failed with `a.map is not a function`, which
+ * told the model nothing it could act on. It gave up on the list and fanned
+ * one task out fifteen times instead.
+ *
+ * Two readings are taken, each the only one its text has: the list as JSON
+ * text, and the list with the fields written after it, read as the object
+ * they close. A field that bled in fills only what the call left unset.
+ * Anything else is refused by name, never run.
+ */
+export declare function readAgentsField(input: SpawnAgentInput): SpawnAgentInput;
+/**
+ * The swarm tool's input, from a `merge` call.
+ *
+ * An entry naming a configured agent in `type` becomes a worker with that
+ * agent's role and tool list, on the swarm's nodes and snapshot. Dropped
+ * before, so asked for "15 code-verifiers as a swarm" the round ran fifteen
+ * generic workers under the lead's shared instructions.
+ */
+export declare function toSwarmInput(input: SpawnAgentInput, configs?: ReadonlyMap<string, ConfiguredAgentConfig>): Record<string, unknown>;
+/**
+ * `check`, and `max_iterations` only where the harness itself stored one,
+ * read and passed on only when set.
+ *
+ * A model's `max_iterations` is ignored, not refused: the field is no longer
+ * offered (see `AgentControlFields`), and a lead that still sends it from an
+ * older transcript should not lose the call over it.
+ */
+export declare function controlFields(input: unknown, options?: {
+    storedCap?: boolean;
+}): {
+    max_iterations?: number;
+    check?: AgentCheck;
+};
+/** What a session hands its spawn tool beyond the connection. */
+export type SpawnToolOptions = Pick<SpawnAgentToolConfig, "swarm" | "configuredAgents" | "configuredAgentConfigs" | "teammates">;
+/**
+ * Create a spawn_agent tool that can run a delegated task with a focused sub-agent.
+ */
+export declare function createSpawnAgentTool(config: SpawnAgentToolConfig): AgentTool<SpawnAgentInput, SpawnAgentOutput | SpawnAgentBatchOutput | SpawnBackgroundAck>;
+/**
+ * An agent's cap and check as its round stored them, for a rerun. The cap
+ * is the one it was given, not one the lead raised later: a rerun starts
+ * over.
+ */
+export declare function storedControls(agent: {
+    maxIterations?: number;
+    check?: unknown;
+}): {
+    max_iterations?: number;
+    check?: AgentCheck;
+};
+/**
+ * What a call that runs in the background returns at once: where its agents
+ * are, and how their report will reach the lead.
+ */
+export interface SpawnBackgroundAck {
+    background: true;
+    round: string;
+    agents: Array<{
+        id: string;
+        name: string;
+    }>;
+    note: string;
+}
+export declare function backgroundAck(handle: RoundHandle): SpawnBackgroundAck;
+/**
+ * What a blocking call returns when a message for the lead arrives first: the
+ * round is detached and goes on in the background.
+ */
+export declare function wokenAck(handle: RoundHandle): SpawnBackgroundAck;
+/** What an agent moved to another node is told when it carries on. */
+export declare function requeueNote(reason: string | undefined): string;
+export { withRevisedInstructions };
+/** The report fields the cap and the check add, only where they say something. */
+export declare function controlReport(agentId: string | undefined, outcome: DelegatedRunOutcome | undefined): Pick<SpawnAgentOutput, "agentId" | "maxIterations" | "stopReason" | "state" | "oracle">;
+/** What the lead reads under an agent returned while it waits at its cap. */
+export declare function awaitingLeadNote(name: string, agentId: string | undefined, outcome: DelegatedRunOutcome): string;

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

@@ -0,0 +1,188 @@
+/**
+ * A sampler the lead chose for the agents it spawns: `temperature` and `seed`.
+ *
+ * Both are optional, and absent is not a default. An agent spawned without
+ * them runs on its connection's sampler exactly as before -- nothing here
+ * writes a value the lead did not pass, because a local model's validated
+ * sampler lives in its Modelfile and a client that invents one silently
+ * replaces it.
+ *
+ * What the lead passes is applied last, in {@link buildDelegatedAgentConfig},
+ * over whatever connection the agent was built on. That is the one point
+ * after every other source has had its say -- the session's pushes through
+ * `updateConnectionDefaults`, a profile, a node's connection (the priority-0
+ * node clears `temperature` so the lead's own applies) -- so none of them can
+ * move a value the lead asked for.
+ *
+ * Either may also be `"random"`, for a swarm experiment that wants its agents
+ * to sample differently and wants to know afterwards how:
+ *
+ * - `seed: "random"` gives each agent its own independent seed.
+ * - `temperature: "random"` gives each agent a draw from its model's own
+ *   temperature +/- `temperature_range` percent (2 when not given, so a model
+ *   at 1 draws 0.98 to 1.02). The model's own is read, never guessed (see
+ *   {@link modelTemperatureOf}); when nothing states it the agent keeps the
+ *   model's sampler and the row says so.
+ * - A numeric `temperature` with a `temperature_range` is randomized around
+ *   that number; `temperature_range` alone around the model's own.
+ * - The range is the user's to widen, and only so far: a request over
+ *   {@link MAX_TEMPERATURE_RANGE_PERCENT} is held to it and the row says so.
+ *   A lead once judged 2% "effectively no variation", asked for 60 on its own
+ *   and ran an agent at 0.595 on a model validated at 1.
+ *
+ * The lead's request is drawn once per agent ({@link drawSpawnSampling}) --
+ * so a re-placement keeps the draw -- and realized at build, where the
+ * connection and so the model's own temperature are known
+ * ({@link realizeSpawnSampling}). What each agent really ran with goes to its
+ * row, its result and, for a teammate, its persisted spec.
+ */
+import type { AgentConfig } from "@cerebriline/shared";
+import { z } from "zod";
+/** The keyword that asks for a per-agent random value. */
+export declare const SPAWN_RANDOM: "random";
+/** Percent a random temperature may move either way when no range is given. */
+export declare const DEFAULT_TEMPERATURE_RANGE_PERCENT = 2;
+/** The widest a random temperature may move either way, whatever is asked. */
+export declare const MAX_TEMPERATURE_RANGE_PERCENT = 10;
+/** Seeds drawn for `seed: "random"` are in [0, this). Fits a signed int32. */
+export declare const RANDOM_SEED_LIMIT: number;
+/** The info line an agent gets when "random" had no temperature to start from. */
+export declare const UNKNOWN_MODEL_TEMPERATURE_NOTE = "model temperature unknown; kept the model's sampler";
+/** The info line an agent gets when its range was held to the limit. */
+export declare function rangeOverLimitNote(requested: number): string;
+/** What a lead asked for: as the tool input states it, after tolerant reading. */
+export interface SpawnSampling {
+    temperature?: number | typeof SPAWN_RANDOM;
+    seed?: number | typeof SPAWN_RANDOM;
+    /** Percent, 0-100. Asks for a randomized temperature on its own. */
+    temperature_range?: number;
+}
+/**
+ * One agent's sampler, drawn: every random choice made, the model's own
+ * temperature not yet read. A plain `{temperature, seed}` of numbers is one
+ * with nothing random in it.
+ */
+export interface SpawnSamplingDraw {
+    /** Fixed: used as given. */
+    temperature?: number;
+    seed?: number;
+    /** The seed was drawn, not given. */
+    seedRandom?: boolean;
+    /**
+     * Randomize the temperature: `base` (or, absent, the model's own) moved by
+     * `draw * range` percent, `draw` uniform in [-1, 1].
+     */
+    temperatureRandom?: {
+        base?: number;
+        range: number;
+        draw: number;
+        /** What was asked for, when it was over the limit and `range` is not it. */
+        requestedRange?: number;
+    };
+}
+/** What one agent ran with, for its row, its result and its record. */
+export interface RealizedSpawnSampling {
+    temperature?: number;
+    seed?: number;
+    /** The seed was drawn per agent (`seed: "random"`). */
+    seedRandom?: boolean;
+    /** Present when the temperature was randomized: what it was drawn around. */
+    temperatureBase?: number;
+    /** Percent, present when the temperature was randomized (or asked to be). */
+    temperatureRange?: number;
+    /** An info line for the row: why a requested value was not applied. */
+    note?: string;
+}
+/** A source of uniform numbers in [0, 1). Injected by tests. */
+export type SamplingRandom = () => number;
+/** The fields as a spawn tool's input schema states them. */
+export declare const SpawnSamplingFields: {
+    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>;
+};
+/** The one line each spawn tool's description gives the options. */
+export declare const SPAWN_SAMPLING_NOTE = "Optional `temperature` and `seed` set the sampler for the agents they cover, over their model's own; omit them to keep the model's. A `seed` that covers several agents is offset by each agent's index among them (seed, seed+1, ...), so they do not sample identically. Either may be \"random\": `seed: \"random\"` gives each agent its own seed; `temperature: \"random\"` gives each a draw within 2% of its model's temperature (a model at 1.0 gets 0.98 to 1.02), which is the intended variation. Set `temperature_range` only when the user states a number: it is the percent to draw within, around a numeric `temperature` or the model's own, held to 10 at most. ";
+/**
+ * The sampler a tool input names, or `undefined` when it names none.
+ *
+ * Tolerant of the shapes a model sends: a numeric string is read as its
+ * number, "Random" as "random", a range of "2%" as 2, and `temperatureRange`
+ * as `temperature_range`. Anything that is not usable is dropped rather than
+ * sent -- a negative temperature, a fractional seed, a range over 100.
+ */
+export declare function readSpawnSampling(input: unknown): SpawnSampling | undefined;
+/**
+ * The sampler for the `index`th agent made from one entry.
+ *
+ * A numeric seed is offset by the index so that N agents running one task do
+ * not draw N identical samples; a "random" one stays "random", and each agent
+ * draws its own. The temperature is the same request for all of them.
+ */
+export declare function samplingForCopy(sampling: SpawnSampling | undefined, index: number): SpawnSampling | undefined;
+/** `inner` over `outer`, field by field: an entry's own value beats the call's. */
+export declare function mergeSpawnSampling(outer: SpawnSampling | undefined, inner: SpawnSampling | undefined): SpawnSampling | undefined;
+/** The fields to spread into a tool input; nothing when unset. */
+export declare function spawnSamplingFields(sampling: SpawnSampling | undefined): SpawnSampling;
+/**
+ * Make one agent's random choices: its seed, and where in the range its
+ * temperature falls. Once per agent -- not per attempt -- so a re-placement
+ * runs the same draw.
+ */
+export declare function drawSpawnSampling(sampling: SpawnSampling | undefined, random?: SamplingRandom): SpawnSamplingDraw | undefined;
+type SamplingConnection = Pick<AgentConfig, "providerId" | "modelId" | "baseUrl" | "temperature" | "providerConfig">;
+/**
+ * The temperature the agent's model runs at when the spawn names none, from
+ * the first source that states one:
+ *
+ * 1. the connection's own `temperature` -- a node's or the session's setting;
+ * 2. its sampler bag, `providerConfig.sampling.temperature` -- a profile's or
+ *    a node's `settings.sampling`, which is what reaches the wire;
+ * 3. for Ollama, the Modelfile's `temperature` parameter, from `/api/show`;
+ * 4. for a llama.cpp/opencoti server, `/props`' default generation settings,
+ *    when they have already been read.
+ *
+ * `undefined` when none of them does: nothing here guesses one.
+ */
+export declare function modelTemperatureOf(connection: SamplingConnection): number | undefined;
+/**
+ * Read the model's own temperature from its server, when a draw needs it and
+ * no local setting states it: Ollama's `/api/show` (the same read its handler
+ * makes before the first request, cached per model) or opencoti's `/props`
+ * (read once per server at session start). Anything else is not asked.
+ * Failure is not an error: the agent then keeps the model's sampler.
+ */
+export declare function primeModelTemperature(draw: SpawnSamplingDraw | undefined, connection: SamplingConnection, fetchImpl?: typeof fetch): Promise<void>;
+/**
+ * One agent's draw made concrete against its model's own temperature.
+ *
+ * A randomized temperature is `base * (1 + draw * range / 100)`, rounded to
+ * three decimals and never below 0. With no base -- the spawn named none and
+ * the model states none -- the temperature is left unset and `note` says so:
+ * the model's sampler stands, and nothing is invented in its place.
+ */
+export declare function realizeSpawnSampling(draw: SpawnSamplingDraw | undefined, modelTemperature: number | undefined): RealizedSpawnSampling | undefined;
+/** The two values a realized sampler puts on the wire; nothing when unset. */
+export declare function samplingValues(sampling: Pick<RealizedSpawnSampling, "temperature" | "seed"> | undefined): {
+    temperature?: number;
+    seed?: number;
+};
+/**
+ * The compact line a row shows for a realized sampler: `seed 2847193 · T 0.713`.
+ * `undefined` when there is nothing to show.
+ */
+export declare function describeRealizedSampling(sampling: RealizedSpawnSampling | undefined): string | undefined;
+/**
+ * An agent config with the lead's sampler over its connection's.
+ *
+ * `temperature` goes to both places a provider reads it from: the config's
+ * own field, which becomes the request's `temperature`, and the provider
+ * config's `sampling` bag, which is what Ollama and llama.cpp/opencoti put on
+ * the wire. Setting only the first would leave a profile's
+ * `sampling.temperature` in the bag to contradict it. `seed` has only the bag:
+ * no other route carries one.
+ *
+ * With no sampler the config is returned untouched -- the same object.
+ */
+export declare function applySpawnSampling<T extends AgentConfig>(config: T, sampling: Pick<RealizedSpawnSampling, "temperature" | "seed"> | undefined): T;
+export {};