@cerebriline/core 4.100.240

package/dist/extensions/tools/team/agent-placement-queue.d.ts

@@ -0,0 +1,199 @@
+/**
+ * The queue in front of {@link placeAgent}: every tier full means wait.
+ *
+ * §9h's ruling. A swarm of thirty against twenty slots completes, more slowly;
+ * refusing would make a swarm larger than total capacity partly fail, and a
+ * bounded wait only moves where that failure happens.
+ *
+ * Two consequences the queue exists to get right:
+ *
+ * - **It drains in spawn order.** An agent asked for first starts first. A
+ *   newcomer never jumps a waiter, and it could not usefully try: while
+ *   anyone is waiting, every node is full, because a free slot would already
+ *   have gone to them.
+ * - **It dequeues by the live-occupancy rule, not by where the last agent
+ *   went.** Each freed slot runs {@link placeAgent} again for the head of the
+ *   queue, so a slot freed in tier 1 takes the head of the queue back up to
+ *   tier 1 rather than leaving it for tier 2 to fill.
+ *
+ * - **A PolyKV node is paced by admission, one agent at a time.** A node
+ *   with no ceiling whose engine admits each agent (`Infinity` with
+ *   `pacedAdmission`: a PolyKV opencoti) takes one agent, and the next only once the engine has
+ *   admitted that one -- its first output is the proof. Before this an
+ *   uncapped node "had room" by definition, so at t=0 every queued agent was
+ *   leased to it and waited inside the engine instead of here. Measured in
+ *   the 75-agent sx4bp run (2026-09-23): two opencoti nodes took all 75 at
+ *   once, and an ollama node that finished its one agent in 66 s sat idle for
+ *   the rest of the run with 70 agents queued -- queued on a node, not here.
+ * - **A spawn that fails goes back to the head.** A lease given back through
+ *   {@link AcquireOptions.front} is re-placed before any waiter, so an agent
+ *   that was refused or landed on a dead node keeps its place in the FIFO.
+ *
+ * The occupancy it keeps is its own ledger of leases: a node's capacity is a
+ * count of agents *we* may run on it -- its Parallel Sessions setting, or for
+ * opencoti the sub-pools inside its one session -- so what we have put there
+ * is the measure that capacity is stated in.
+ */
+import { type AgentNode } from "./agent-placement";
+export interface PlacementLease {
+    nodeId: string;
+    /** Frees the slot. Safe to call more than once; only the first counts. */
+    release(): void;
+    /**
+     * The engine took this agent: its first output arrived.
+     *
+     * On an uncapped node this is what opens the node to the next agent.
+     * Idempotent, and a no-op on a capped node, whose room is its count.
+     */
+    admitted(): void;
+    /**
+     * The engine refused this agent before admitting it. The node takes no
+     * one else until one of its agents finishes or `holdMs` passes, whichever
+     * is first -- capped or not: a count says nothing about what the engine
+     * will take. Frees the slot, like {@link release}.
+     */
+    refused(holdMs?: number): void;
+}
+export interface AcquireOptions {
+    /**
+     * Go before every waiter: an agent coming back from a spawn that failed.
+     * It was first in the queue when it was placed, and a refusal is not a
+     * reason to lose that.
+     */
+    front?: boolean;
+    /**
+     * A node to place this agent anywhere but, when another has room: the one
+     * the lead requeued it off for being slow or misbehaving. Deprioritised,
+     * not banned -- with no other room it still goes there rather than wait.
+     */
+    avoid?: string;
+    /**
+     * The one node this agent may take: an agent resumed on the transcript it
+     * produced there. It waits for that node, and while it waits, agents that
+     * can go elsewhere are not held up behind it.
+     */
+    only?: string;
+}
+/** One node as the queue sees it, for the lead's status report. */
+export interface PlacementNodeState {
+    nodeId: string;
+    capacity: number;
+    running: number;
+    /** Out of rotation (not answering, or without the model) until then. */
+    downUntil?: number;
+    /** Held after a refusal until then. */
+    heldUntil?: number;
+}
+/**
+ * How long a refused node is held when the engine gave no time.
+ *
+ * Short: a refusal describes this moment, and it usually ends when one of the
+ * node's own agents finishes, which reopens it at once. This is only the
+ * fallback for a refusal with nothing of ours running there to finish.
+ */
+export declare const NODE_REFUSED_HOLD_MS = 5000;
+/**
+ * How long a node that could not be reached is left out of the rotation.
+ *
+ * Long enough that a dead LAN box is not retried on every spawn -- with
+ * round-robin that is once a lap, each costing a connect timeout -- and short
+ * enough that a box which came back is used again within one agent's work.
+ */
+export declare const NODE_COOL_OFF_MS = 30000;
+/**
+ * How often a node in its cool-off is asked whether it is back.
+ *
+ * The cool-off is an upper bound, not a sentence. Measured on 1tmrl: the
+ * opencoti server behind Node1 restarted and was listening again ten seconds
+ * later, and the node sat out the rest of the 30 s regardless. A node whose
+ * `/health` answers is put back at once; one that never answers still comes
+ * back when the cool-off ends, as before.
+ */
+export declare const NODE_PROBE_INTERVAL_MS = 5000;
+/**
+ * The cool-off for a node whose model is not on its server.
+ *
+ * Longer, because the two conditions heal on different scales. A box that was
+ * unplugged can be back in thirty seconds; a model tag that the server has
+ * never heard of does not appear on its own, and until someone pulls it every
+ * agent sent there dies the same way. Measured on pandorum 2026-09-22: a node
+ * configured for `ornith-27b_tb:iq4_xs-128k` against a server holding 193
+ * models and not that one, killing two agents of a five-agent fan-out and
+ * taking a third when the lead retried.
+ *
+ * Still a cool-off rather than a removal: `ollama pull` during a long session
+ * is an ordinary thing to do, and a node that is out for good would stay out
+ * after the user fixed it.
+ */
+export declare const NODE_MODEL_MISSING_COOL_OFF_MS = 600000;
+/**
+ * How many nodes one agent may be placed on before its failure is its own.
+ *
+ * Bounded rather than "every node": a request that fails the same way
+ * everywhere -- a malformed tool schema, an oversized prompt -- would
+ * otherwise walk the whole rotation and take every node out of it on the way
+ * past. Three is enough to step over a misconfigured node in any realistic
+ * setup and small enough that a systematic failure is reported as one.
+ */
+export declare const MAX_NODE_PLACEMENT_ATTEMPTS = 3;
+export interface AgentPlacementQueue {
+    /**
+     * A slot on the best node with room, waiting for one if none has.
+     *
+     * Rejects only when `signal` aborts, or when no node could ever take an
+     * agent -- see {@link NoAgentCapacityError}.
+     */
+    acquire(signal?: AbortSignal, options?: AcquireOptions): Promise<PlacementLease>;
+    /**
+     * Would an agent be placed on a node other than `nodeId` right now?
+     *
+     * Asked by an admitted agent that `nodeId` has just refused a turn: if
+     * another node has room it moves there, by the queue's own priority order,
+     * instead of waiting on the node that said no. Nothing is taken; the move
+     * itself goes through {@link acquire} at the front of the queue.
+     */
+    hasRoomElsewhere(nodeId: string): boolean;
+    /** Agents waiting for a slot, for a status line. */
+    readonly waiting: number;
+    /** Node id to agents running on it now. A copy. */
+    occupancy(): ReadonlyMap<string, number>;
+    /** Every node's capacity, load and holds, for a status line. */
+    nodeStates(): PlacementNodeState[];
+    /**
+     * Take a node out of the rotation for a cool-off.
+     *
+     * Called when an agent could not reach it at all -- a refused connection,
+     * an unknown host -- never for a refusal or an ordinary model error, which
+     * say the node is alive and answering.
+     *
+     * The exception is a model the server does not have. That is an answer,
+     * so it is not unreachable, but it is a node that cannot run anything
+     * until its configuration changes: see
+     * {@link NODE_MODEL_MISSING_COOL_OFF_MS}, which callers pass as
+     * `coolOffMs`.
+     */
+    markUnreachable(nodeId: string, coolOffMs?: number): void;
+}
+/**
+ * No node has any capacity at all, so waiting would never end.
+ *
+ * Distinct from full on purpose. Full is a state that ends when an agent
+ * finishes; every node configured to zero is a configuration, and an agent
+ * queued behind it would hang the spawn for the life of the session.
+ */
+export declare class NoAgentCapacityError extends Error {
+    constructor();
+}
+export declare function createAgentPlacementQueue(configuredNodes: readonly AgentNode[], options?: {
+    /** Injected so the cool-off can be tested without waiting for it. */
+    now?: () => number;
+    /** Injected for the same reason; returns a canceller. */
+    schedule?: (fn: () => void, ms: number) => void;
+    /**
+     * Is this node answering again? Asked every
+     * {@link NODE_PROBE_INTERVAL_MS} while the node sits out an
+     * unreachable cool-off; `true` puts it back in rotation at once.
+     */
+    probe?: (nodeId: string) => Promise<boolean>;
+    probeIntervalMs?: number;
+}): AgentPlacementQueue;

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

@@ -0,0 +1,118 @@
+/**
+ * Where the next delegated agent runs.
+ *
+ * A **node** is a complete agents provider configuration — its own endpoint,
+ * model, context window, sampler and budget — so a set of nodes is
+ * heterogeneous by design: one on Anthropic, one on opencoti, one on a LAN
+ * ollama, one on llama.cpp. What this module decides is only which of them
+ * takes the next agent.
+ *
+ * Two rules, and the second is the one that is easy to get wrong.
+ *
+ * **Priority is a rank, 1 highest**, and a lower tier is used only when no node
+ * in a higher one has room. Within a tier, round-robin.
+ *
+ * **A tier is full when its nodes have no free slot right now** — live
+ * occupancy, never a count of what has been spawned. The difference shows up
+ * the moment a higher-tier agent finishes: the next spawn must go back up to
+ * the slot it freed. A counter that remembered "we have moved on to tier 2"
+ * would leave that capacity idle for the rest of the run, which is the opposite
+ * of overflowing only when necessary.
+ *
+ * Priority `0` is reserved for the lead conversation's own PolyKV session,
+ * whose agents are sub-pools of the window it has already booked. It is a tier
+ * like any other here; that it comes first is just what its number means.
+ */
+export interface AgentNode {
+    /** Stable identity, used as the occupancy key. */
+    id: string;
+    /** 1 is highest. `0` is the lead session's own sub-pools. */
+    priority: number;
+    /**
+     * How many agents may run on this node at once.
+     *
+     * The unit differs by provider and is resolved before it gets here: a
+     * parallel-sessions setting for ollama, llama.cpp and the cloud providers;
+     * for opencoti, the sub-pools available inside its ONE session, because
+     * agents there share the conversation's allocation rather than booking one
+     * each.
+     *
+     * `0` means the node is off and is never placed on. `Infinity` means the
+     * endpoint decides its own admission and this layer must not be the bound —
+     * which is what an elastic or PolyKV opencoti resolves to when the
+     * profile's parallel-sessions box is left empty. The two are opposite
+     * readings of "no number", so they are spelled differently on purpose.
+     */
+    capacity: number;
+    /**
+     * An uncapped node whose engine admits each agent itself: opencoti with
+     * PolyKV pools. Only such a node is paced one agent at a time (see
+     * `agent-placement-queue`); an elastic node without pools, or any node the
+     * host did not mark, takes its agents together.
+     */
+    pacedAdmission?: boolean;
+}
+/** The tier that is the lead conversation's own PolyKV session (§9g). */
+export declare const LEAD_PRIORITY = 0;
+/**
+ * Priority 0's capacity: 8 sub-pools of the lead's one session -- the engine's
+ * per-session limit, and the ruled cap (PLANS §9g, 2026-09-25).
+ */
+export declare const LEAD_SUBPOOL_CAPACITY = 8;
+/**
+ * A node's capacity with priority 0's cap applied.
+ *
+ * Only the lead tier is capped. It is always a bounded thing -- sub-pools of
+ * one window -- so `Infinity` ("the endpoint decides") cannot apply to it: the
+ * endpoint deciding is what filled the lead's window and lost 49 of 51 agents
+ * (991ce2466). `0` stays off. Every other tier is left as configured, where
+ * `Infinity` keeps meaning the endpoint decides.
+ */
+export declare function capLeadTier<T extends AgentNode>(node: T): T;
+export type Placement = {
+    kind: "node";
+    nodeId: string;
+}
+/**
+ * Nothing has room. The agent waits rather than failing: a swarm larger
+ * than total capacity should complete slowly, not partly fail.
+ */
+ | {
+    kind: "queued";
+};
+export interface PlacementState {
+    /**
+     * Where the round-robin left off, per tier.
+     *
+     * Per tier rather than global: advancing through tier 2 must not skip a
+     * node in tier 1 the next time tier 1 has room.
+     */
+    readonly cursors: Readonly<Record<number, number>>;
+}
+export declare function emptyPlacementState(): PlacementState;
+/**
+ * Pick a node for one agent, given what is running right now.
+ *
+ * Pure: `occupancy` is the caller's live view and `state` carries only the
+ * round-robin cursors, so the same inputs always give the same answer and the
+ * decision can be tested without a server.
+ */
+export declare function placeAgent(input: {
+    nodes: readonly AgentNode[];
+    /** Node id to agents currently running on it. Missing means none. */
+    occupancy: ReadonlyMap<string, number>;
+    state: PlacementState;
+    /**
+     * Node id to the moment its cool-off ends, for nodes that could not be
+     * reached. Missing or past means the node is in play.
+     *
+     * §9i.2. One dead LAN box should not be retried on every spawn for the
+     * life of the session -- each retry costs a connect timeout, and with
+     * round-robin it costs one per lap.
+     */
+    downUntil?: ReadonlyMap<string, number>;
+    now?: number;
+}): {
+    placement: Placement;
+    state: PlacementState;
+};

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

@@ -0,0 +1,53 @@
+/**
+ * What a delegated agent reports, and how the lead reads it.
+ *
+ * A round's reports went to the lead whole, as one tool result, and the
+ * transcript sends at most 32,000 characters of any tool result, cut from the
+ * middle. On pandorum 2026-09-24 a round of 75 returned 209,219 characters,
+ * and the lead was shown the first 11 and the last 15 reports: "the harness
+ * truncated the middle of the 75-report output".
+ *
+ * So each agent now hands back a short summary it writes itself once it is
+ * done, and its full report is kept here. The lead gets the summaries -- every
+ * agent represented -- and reads a full report when it wants one, a page at a
+ * time, the way it reads a large file.
+ */
+import type { AgentResult, AgentTool } from "@cerebriline/shared";
+/** The longest summary the lead is handed per agent. */
+export declare const AGENT_SUMMARY_MAX_CHARS = 1000;
+/** A page of a report, at most, as `read_files` pages a file. */
+export declare const AGENT_REPORT_PAGE_LINES = 200;
+export declare const AGENT_REPORT_PAGE_CHARS = 12000;
+export declare const READ_AGENT_REPORT_TOOL_NAME = "read_agent_report";
+export declare const AGENT_SUMMARY_PROMPT: string;
+/**
+ * Keep an agent's full report under its name, for the lead's session.
+ *
+ * Returns the name it is filed under: a name already used in this session gets
+ * a suffix, so an agent of the next round does not replace one the lead may
+ * still want to read.
+ */
+export declare function recordAgentReport(sessionId: string | undefined, name: string, text: string): string;
+/** Forget a session's reports, with the session. */
+export declare function clearAgentReports(sessionId: string | undefined): void;
+/** A page of a report, numbered, with where to read on from. */
+export declare function readAgentReport(sessionId: string | undefined, name: string, startLine?: number): string;
+/** The lead's way into a full report. */
+export declare function createReadAgentReportTool(): AgentTool;
+/**
+ * The agent's result as the lead is to receive it: a summary the agent wrote,
+ * and where its full report is filed. A report already under the limit is its
+ * own summary, and costs no extra turn.
+ *
+ * `summarize` asks the agent itself -- one more turn on the conversation that
+ * produced the report, which is the only party that knows what mattered in it.
+ * A failed or empty summary falls back to the report's opening.
+ */
+export declare function summarizeForLead(input: {
+    sessionId: string | undefined;
+    name: string;
+    result: AgentResult;
+    summarize: (prompt: string) => Promise<{
+        text: string;
+    }>;
+}): Promise<AgentResult>;