@cerebriline/core 4.100.240

package/dist/extensions/tools/team/agent-iteration-cap.d.ts

@@ -0,0 +1,328 @@
+/**
+ * A delegated agent at its iteration cap waits for the lead; its work is kept.
+ *
+ * Ruled (lead-agent-control spec, D): hitting `maxIterations` must not lose
+ * the work -- the lead decides whether to resume it with a raised cap, or stop
+ * or restart it. Until now the cap ended the run like an error, the agent's
+ * overlay was handed back and disposed, and the transcript went with the
+ * agent object.
+ *
+ * So a run that stops at its cap is *suspended* here, in state
+ * `awaiting_lead`, with everything it needs to go on: the conversation (the
+ * agent object, alive), its private workspace (its path does not tear it down
+ * while it waits) and its place in the round. The lead is told -- once for all
+ * the agents of a session that stop together -- and answers with
+ * {@link resumeSuspended} (the `resume_agent` tool) or a stop. A blocking
+ * round does not return while one of its agents waits: the spawn call is the
+ * thing waiting, and the lead's side turn is where it decides.
+ *
+ * **A loop is treated like the cap.** A run the repeated-call loop guard
+ * stopped -- the same call, arguments unchanged, sent again after its warning
+ * -- is suspended the same way (user ruling, 2026-09-26: the lead is told the
+ * agent was looping and picks resume_agent or restart_agent with new
+ * instructions). Ending it there threw its work away: three workers of the
+ * 0926b swarm were ended so, reported only as "stopped".
+ *
+ * With nobody to ask -- a host that registered no lead listener, so no side
+ * turn and no queue -- the agent is *detached*: its spawn returns at once with
+ * the agent reported `awaiting_lead`, and the agent stays suspended with its
+ * resources held until `resume_agent` continues it in the background or it is
+ * stopped. {@link createDelegatedAgentLifetime} is how the spawn path defers
+ * its teardown to that point.
+ *
+ * **The engine session is kept while a listening lead decides**, and released
+ * only for an agent detached with nobody to ask. Released on every wait, it
+ * cost more than it freed (bs2 8244, 2026-09-26, 64 suspensions of 32 agents,
+ * the lead answering in about two minutes): closing the session erases the
+ * engine's running mark, so the resumed agent was admitted as a new session,
+ * and the pool's enforced tps floor -- which holds new sessions back and lets
+ * running ones through -- refused it every minute for up to half an hour. Its
+ * owner, with no finished request in five minutes, lapsed, and its pools with
+ * it. A swarm worker's window is its owner's booking anyway; kept, the agent
+ * also resumes on its own cache instead of re-prefilling its transcript.
+ * The client-side node lease (or endpoint slot) is kept either way: it pins
+ * the agent to the node its transcript was produced on, and giving it up would
+ * let the harness re-place it onto a different model mid-conversation.
+ */
+import type { AgentResult } from "@cerebriline/shared";
+import type { AgentOracleResult, DelegatedAgentCheck } from "./agent-check";
+import { type SubagentStopActor } from "./subagent-cancellation";
+/** The tool the lead continues a waiting agent with (built on {@link resumeSuspended}). */
+export declare const RESUME_AGENT_TOOL_NAME = "resume_agent";
+/**
+ * What a resume adds when neither the lead names an amount nor the agent was
+ * spawned with a cap (a loop-guard or supervisor stop of an uncapped agent,
+ * where the amount is not used).
+ */
+export declare const DEFAULT_RESUME_ITERATIONS = 30;
+/** How long agents stopping together wait for each other's notice. */
+export declare const AWAITING_LEAD_BATCH_MS = 3000;
+/** What the agent-layer needs of the agent it runs: a `SessionRuntime`. */
+export interface CappableAgent {
+    getAgentId(): string;
+    /** Optional so a stand-in agent need not have it; a `SessionRuntime` does. */
+    getMaxIterations?(): number | undefined;
+    setMaxIterations?(maxIterations: number | undefined): void;
+    continue(message?: string): Promise<AgentResult>;
+}
+/**
+ * Why an agent waits on the lead: its iteration cap, a loop the guard
+ * stopped, or a grind the struggle supervisor stopped.
+ */
+export type AwaitingLeadReason = "iteration_cap" | "looping" | "struggling";
+/** An agent waiting on the lead, as the lead and the status tool see it. */
+export interface AwaitingLeadView {
+    /** The agent's own id (its runtime's). */
+    agentId: string;
+    /** What the round calls it. */
+    name: string;
+    sessionId?: string;
+    /** The id `stop_agents` and the chat row know it by, when it has one. */
+    cancelId?: string;
+    /** Iterations it has used, over every run so far. */
+    iterations: number;
+    /** Its cap so far: the first one plus every raise. */
+    maxIterations: number;
+    /**
+     * The cap it was spawned with: what a resume that names no amount adds
+     * (60 -> 120 -> 180). Absent when it had none.
+     */
+    firstCap?: number;
+    /** When it stopped at the cap. */
+    since: number;
+    /** Its spawn call has returned; a resume runs it in the background. */
+    detached: boolean;
+    /** Why it waits; absent is the cap. */
+    reason?: AwaitingLeadReason;
+    /**
+     * For a loop: the guard's own words, naming the call it repeated. For a
+     * supervisor stop: the supervisor's, saying what it measured.
+     */
+    detail?: string;
+}
+/** Why an agent's run came to an end, as far as the cap is concerned. */
+export type DelegatedStopReason = "iteration_cap" | "loop_guard" | "supervisor"
+/** Stopped gracefully: its last turn was a report, and it ends on that. */
+ | "wrap_up";
+/** A delegated run, with what the cap and the check made of it. */
+export interface DelegatedRunOutcome {
+    /** The last run's result, with iterations and usage summed over every run. */
+    result: AgentResult;
+    /** Iterations used, over the first run and every resume. */
+    iterations: number;
+    /** The cap it ended under: the first plus every raise. Absent is no cap. */
+    maxIterations?: number;
+    /** Set when the cap is what ended it (stopped at the cap by the lead or a user). */
+    stopReason?: DelegatedStopReason;
+    /** Set when it is still waiting on the lead: its spawn returned detached. */
+    state?: "awaiting_lead";
+    /** The lead's check, when one was set. */
+    oracle?: AgentOracleResult;
+}
+export type AwaitingLeadEvent = {
+    type: "suspended";
+    agent: AwaitingLeadView;
+} | {
+    type: "resumed";
+    agent: AwaitingLeadView;
+    extraIterations: number;
+} | {
+    type: "stopped";
+    agent: AwaitingLeadView;
+    reason: string;
+} | {
+    type: "finished";
+    agent: AwaitingLeadView;
+    outcome: DelegatedRunOutcome;
+};
+/**
+ * Be told as agents stop at their cap, resume, are stopped there, or -- a
+ * detached one -- finish. For the round registry and the status tool.
+ */
+export declare function onAwaitingLead(listener: (event: AwaitingLeadEvent) => void): () => void;
+/** Every agent waiting on the lead, or those of one session. */
+export declare function listAwaitingLead(sessionId?: string): AwaitingLeadView[];
+export interface ResumeSuspendedResult {
+    ok: boolean;
+    message: string;
+    agent?: AwaitingLeadView;
+    /** The iterations it was given: the lead's amount, or its first cap. */
+    extraIterations?: number;
+    /**
+     * For a detached agent: its run from here, to its end or its next stop at
+     * the cap. Absent for an agent whose spawn call is still open -- that call
+     * returns its report.
+     */
+    completion?: Promise<DelegatedRunOutcome>;
+}
+/**
+ * Continue an agent waiting at its cap, with `extraIterations` more turns --
+ * by default as many as it was spawned with.
+ *
+ * The primitive `resume_agent` is built on. `idOrName` is the agent's id, its
+ * row's id, or its name in the round; `sessionId` scopes the search to the
+ * lead's session, which a caller should always pass.
+ */
+export declare function resumeSuspended(idOrName: string, extraIterations: number | undefined, sessionId?: string, instructions?: string): ResumeSuspendedResult;
+/**
+ * End an agent waiting at its cap, keeping what it did: its report is its last
+ * output, its changes are handed back as they would be on any other end.
+ */
+export declare function stopSuspended(idOrName: string, options?: {
+    sessionId?: string;
+    reason?: string;
+    report?: boolean;
+}): {
+    ok: boolean;
+    message: string;
+    agent?: AwaitingLeadView;
+};
+/** What a stop did: asked for a report, ended it, or found nothing to stop. */
+export type SubagentStopOutcome = "graceful" | "stopped" | "not_running";
+/**
+ * Stop one agent, the one way every control does it -- the lead's
+ * `stop_agents`, the row's Stop and the panel's Stop all.
+ *
+ * Graceful by default: a running agent finishes its step and reports
+ * (`subagentCancellation.wrapUp`), one waiting on the lead writes its report
+ * where it stopped. `immediate` ends it at once, work kept and no report --
+ * also the way to end one already stopping gracefully. A running agent whose
+ * path has no segment to take a report turn is stopped at once.
+ */
+export declare function stopSubagent(options: {
+    cancelId?: string;
+    /** Its id or name, for one waiting on the lead that has no cancel id. */
+    ref?: string;
+    sessionId?: string;
+    by: SubagentStopActor;
+    immediate?: boolean;
+}): SubagentStopOutcome;
+/** The notice for agents that stopped at their cap, as the lead reads it. */
+export declare function describeAwaitingLead(views: readonly AwaitingLeadView[]): string;
+/** Send what is batched for a session now, rather than when its timer fires. */
+export declare function flushAwaitingLeadNotices(sessionId?: string): void;
+/**
+ * When a spawn path's teardown runs: at once, or -- for an agent detached at
+ * its cap -- once the agent is finally done.
+ */
+export interface DelegatedAgentLifetime {
+    /**
+     * Run `cleanup` now, or -- for a detached agent -- schedule it for when the
+     * agent is finally done and return at once, so the spawn call can return
+     * while the agent waits. Never throws.
+     */
+    end(cleanup: () => Promise<void> | void): Promise<void>;
+    /** Settles once the cleanup handed to {@link end} has run. */
+    readonly ended: Promise<void>;
+    /** Whether the agent was detached (its spawn returned while it waits). */
+    readonly detached: boolean;
+    /** Set by the run when it detaches: teardown waits for `done`. */
+    holdUntil(done: Promise<unknown>): void;
+}
+export declare function createDelegatedAgentLifetime(): DelegatedAgentLifetime;
+export interface RunDelegatedWithCapOptions {
+    agent: CappableAgent;
+    /** The first run: `agent.run(task)` or `agent.runWithHead(...)`. */
+    start: () => Promise<AgentResult>;
+    /** What the round calls it. */
+    name: string;
+    /** The cap it was built with, when the agent cannot say. */
+    maxIterations?: number;
+    /** The lead's session. */
+    sessionId?: string;
+    /** The id its row and `stop_agents` know it by. */
+    cancelId?: string;
+    /** Its stop: a stop while it waits ends it at the cap, work kept. */
+    signal?: AbortSignal;
+    /** Its row. */
+    emitUpdate?: (update: unknown) => void;
+    /** The lead's check on it, already wired into its completion boundary. */
+    check?: DelegatedAgentCheck;
+    /** Gives the engine session back while it waits; see the file comment. */
+    releaseEngineSession?: () => Promise<unknown>;
+    /**
+     * Where teardown is deferred to when the agent is detached. Without one it
+     * is never detached: with nobody to ask, it is ended at the cap instead,
+     * its work kept.
+     */
+    lifetime?: DelegatedAgentLifetime;
+    /**
+     * The agent's struggle supervisor, when it has one: a resume after its
+     * stop is watched from zero again.
+     */
+    supervisor?: {
+        rearm(): void;
+    };
+    /** A detached agent's final outcome, for the path's own end-of-run work. */
+    onDetachedFinish?: (outcome: DelegatedRunOutcome) => Promise<void> | void;
+    /**
+     * Where a detached agent's resume runs: its path's placement -- the node
+     * lease on the node it ran on, or the endpoint's slot gate. Its spawn call
+     * returned and gave those back, so without this the resumed agent would
+     * run outside every bound. An agent held inside its call keeps its lease
+     * and does not use it.
+     */
+    resumeThrough?: <T>(run: () => Promise<T>) => Promise<T>;
+}
+/** What an agent is told when the lead raises its cap, or lets it go on after a loop. */
+export declare function resumeNote(extraIterations: number, reason?: AwaitingLeadReason, instructions?: string): string;
+/** Whether the struggle supervisor, not a stop from outside, ended this run. */
+export declare function stoppedBySupervisor(result: Pick<AgentResult, "finishReason"> & {
+    abortReason?: string;
+}, signal?: AbortSignal): boolean;
+/** Whether the repeated-call loop guard, not a stop from outside, ended this run. */
+export declare function stoppedByLoopGuard(result: Pick<AgentResult, "finishReason"> & {
+    abortReason?: string;
+}, signal?: AbortSignal): boolean;
+/**
+ * The last turn of an agent the lead stopped at its cap: its report. At the
+ * cap an agent's last output is usually a tool call's preamble -- the lead
+ * got "Now let me check line 90" as the report of 60 iterations of work.
+ */
+export declare const FINAL_REPORT_NOTE = "[SYSTEM MESSAGE] Your iteration budget is spent and the lead is taking your work as it is. Do not call any tool. In this one reply, report: what you changed (files and what for), what you verified and how, and what is still broken or unfinished -- exactly where you stopped.";
+/**
+ * The last turn of an agent stopped gracefully while it was working: what it
+ * has, before it goes. A stop that aborted it outright left the lead its file
+ * changes and no word of what they were (13 of 15 agents, swarm czbnh).
+ */
+export declare function wrapUpNote(by: "lead" | "user" | undefined): string;
+/** What the lead reads above a graceful stop's report. */
+export declare function wrapUpHeading(by: "lead" | "user" | undefined): string;
+/**
+ * A graceful stop's last turn, run on the transcript the stopped segment
+ * left: one reply, no check, no cap to wait at. Its answer is the agent's
+ * report; with none, the run reads as stopped with no answer, as an
+ * outright stop does.
+ */
+export declare function runWrapUpReport(options: {
+    agent: CappableAgent & {
+        restore(messages: never): void;
+    };
+    messages: readonly unknown[];
+    by: "lead" | "user" | undefined;
+}): Promise<DelegatedRunOutcome>;
+/** Turns before the cap at which an agent is told to wrap up. */
+export declare function capWarningMargin(cap: number): number;
+/**
+ * A warning for an agent nearing its cap, once per run: finish and report,
+ * rather than be cut off mid-step. Fed the agent's events for its turn count;
+ * `take` is read at each turn boundary (`consumePendingUserMessage`). A
+ * resume starts a new run with its own allowance, and a new warning.
+ */
+export declare function createCapWarning(getCap: () => number | undefined): {
+    observe(event: {
+        type: string;
+        iteration?: number;
+    }): void;
+    take(): string | undefined;
+};
+/**
+ * Run a delegated agent to its end, suspending it at its cap for the lead.
+ *
+ * Every spawn path runs its agent through this, so the cap behaves the same
+ * on all of them. A run with no cap, or one that finishes under it, passes
+ * straight through.
+ */
+export declare function runDelegatedWithCap(options: RunDelegatedWithCapOptions): Promise<DelegatedRunOutcome>;
+/** Test seam. */
+export declare function __resetAwaitingLead(): void;

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

@@ -0,0 +1,29 @@
+/**
+ * Agents of one call named apart.
+ *
+ * The lead is free to give several agents the same name -- asked for five
+ * reviews, it sends five entries called `code-review` -- and nothing refused
+ * it, so a round held five agents answering to one name: their rows, the
+ * notices about them ("code-review: refused 13x") and the round index could
+ * not tell them apart (pandorum h0o2o, 2026-09-28, 25 agents under 5 names).
+ *
+ * Failing the call would make the lead spend a turn on a formality. So a name
+ * used more than once becomes `<name>-1`, `<name>-2`, ... in the order given,
+ * the way `count` names its copies, skipping any name already taken in the
+ * call, and the lead is told what was renamed. A name used once is left alone.
+ *
+ * The host keys an agent's row by its position and shows this name, so it
+ * applies the same function (`spawnBatchMembers`); both have to agree.
+ */
+export declare function uniqueAgentNames(names: readonly string[]): {
+    names: string[];
+    renamed: Array<{
+        from: string;
+        to: string[];
+    }>;
+};
+/** The sentence that tells the lead which agents were renamed. */
+export declare function describeRenamedAgents(renamed: ReadonlyArray<{
+    from: string;
+    to: string[];
+}>): string | undefined;

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

@@ -0,0 +1,160 @@
+import { type AcquireOptions } from "./agent-placement-queue";
+import type { DelegatedAgentConfigProvider, DelegatedAgentConnectionConfig } from "./delegated-agent";
+/** What a host says about one node. */
+export interface AgentNodeRuntimeConfig {
+    id: string;
+    /** 1 highest. `0` is the lead's own PolyKV session; see the plan's §9g. */
+    priority: number;
+    /**
+     * Agents this node may run at once.
+     *
+     * Resolved by the host, where the unit differs by provider: a
+     * parallel-sessions setting for ollama, llama.cpp and the cloud providers,
+     * and for opencoti the sub-pools inside its one session.
+     */
+    capacity: number;
+    /** See {@link AgentNode.pacedAdmission}: set by the host for PolyKV. */
+    pacedAdmission?: boolean;
+    /**
+     * What the settings panel calls this node -- `Node1`, `Node2`, `Node3`.
+     *
+     * The id is a storage key (`node-mucuczcm`), generated when the node is
+     * added and shown nowhere in the UI, so a chat row that printed it named
+     * something the user had no way to look up. Reported exactly that way:
+     * "on node-mucuczcm" -- what is this? I expect to see Node1 or Node2.
+     *
+     * Carried rather than derived here because the numbering belongs to the
+     * stored list, including the nodes this one skips: a node that names no
+     * provider is dropped before it reaches the placement engine, and
+     * renumbering around the gap would call Node3 "Node2" on the one screen
+     * where the user is trying to tell them apart.
+     */
+    label?: string;
+    /** The node's own connection, in the shape the Agents tab already stores. */
+    connection: Partial<DelegatedAgentConnectionConfig>;
+    /** See `CoreSessionConfig.agentNodes[].windowShare`. */
+    windowShare?: number;
+    /**
+     * This node is the lead conversation's own opencoti session: priority 0,
+     * "Use PolyKV agents as Priority 0" (PLANS §9g). Its agents are built as
+     * sub-pools of the lead's window, its priority is 0 and its capacity at
+     * most {@link LEAD_SUBPOOL_CAPACITY}, whatever else the entry says.
+     */
+    polykvLead?: boolean;
+}
+/** The id and label the priority-0 node goes by. */
+export declare const POLYKV_LEAD_NODE_ID = "polykv-lead";
+export declare const POLYKV_LEAD_NODE_LABEL = "Model (PolyKV)";
+/** What {@link sessionAgentNodes} reads of a session's config. */
+export interface SessionAgentNodesInput {
+    providerId: string;
+    modelId: string;
+    agentNodes?: readonly AgentNodeRuntimeConfig[];
+    /**
+     * The host's word that the setting is on AND this session's endpoint
+     * confirmed `pools_enabled`. The provider is checked again here.
+     */
+    polykvAgentsPriorityZero?: boolean;
+    /** The lead's own connection, from which the priority-0 node is built. */
+    lead: Partial<DelegatedAgentConnectionConfig>;
+    /**
+     * The session's own agent concurrency (`maxConcurrentAgents`), for the
+     * overflow node made when the host lists none. `0` or absent is "the
+     * endpoint decides", which a node spells `Infinity`.
+     */
+    overflowCapacity?: number;
+}
+/** The overflow tier made when priority 0 is on and the host lists no node. */
+export declare const PRIMARY_OVERFLOW_NODE_ID = "primary";
+export declare function sessionAgentNodes(input: SessionAgentNodesInput): AgentNodeRuntimeConfig[];
+/** Somewhere to run one agent, held until it is given back. */
+export interface PlacedAgentNode {
+    nodeId: string;
+    /** What the settings panel calls it; see {@link AgentNodeRuntimeConfig.label}. */
+    nodeLabel?: string;
+    configProvider: DelegatedAgentConfigProvider;
+    /**
+     * Runs `fn` on this node. The lease IS the gate.
+     *
+     * A placed agent is deliberately NOT also held behind the shared
+     * per-endpoint gate. Two nodes that resolve to one base URL are two lanes
+     * on that server, not one: they are two of its slots, and how many
+     * requests it will take at once is the server's own answer -- `--parallel`
+     * on a llama.cpp family engine, `OLLAMA_NUM_PARALLEL` on ollama, more than
+     * either under PolyKV admission with elastic slots. A node's capacity is
+     * the user saying how much of that to use, and the sum across nodes is
+     * what they asked for.
+     *
+     * It used to apply both, which made the node capacities decorative: the
+     * endpoint gate is one object per provider+baseUrl, so three nodes on one
+     * opencoti ran strictly one agent at a time however they were configured.
+     * Measured on pandorum 2026-09-22 -- three agents, 80s/108s/148s, each
+     * starting only as the one before it finished.
+     *
+     * The server refusing is the backstop, and it is the right one: it knows
+     * its own admission, and we do not.
+     */
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    /** Idempotent: the first call frees the slot. */
+    release(): void;
+    /** The engine took the agent; see {@link PlacementLease.admitted}. */
+    admitted(): void;
+    /**
+     * The engine refused the agent before admitting it. Frees the slot and
+     * holds the node; see {@link PlacementLease.refused}.
+     */
+    refused(holdMs?: number): void;
+    /**
+     * This node could not be reached at all; leave it out of the rotation for
+     * a cool-off. See {@link AgentPlacementQueue.markUnreachable}.
+     *
+     * `coolOffMs` overrides the default, for a condition that heals on a
+     * different scale -- a model the server does not have, which no amount of
+     * waiting fixes on its own.
+     */
+    markUnreachable(coolOffMs?: number): void;
+}
+export interface AgentNodePlacement {
+    /** The node for the next agent, waiting for one when all are full. */
+    place(signal?: AbortSignal, options?: AcquireOptions): Promise<PlacedAgentNode>;
+    /** The session's own delegated connection, for callers that skip placement. */
+    base: DelegatedAgentConfigProvider;
+    occupancy(): ReadonlyMap<string, number>;
+    /**
+     * Whether a node other than `nodeId` has room now; see the queue's
+     * `hasRoomElsewhere`. Optional for hand-built placements in tests.
+     */
+    hasRoomElsewhere?(nodeId: string): boolean;
+    readonly waiting: number;
+    /**
+     * Every node as the lead's status tool reports it: what it runs, how full
+     * it is, and whether it is out of rotation. Optional for hand-built
+     * placements in tests.
+     */
+    describe?(): AgentNodeStatus[];
+}
+/** One node, for `agents_status`. */
+export interface AgentNodeStatus {
+    nodeId: string;
+    label?: string;
+    priority: number;
+    providerId?: string;
+    modelId?: string;
+    baseUrl?: string;
+    /** The node's provider config: its PolyKV section, when it has one. */
+    providerConfig?: unknown;
+    capacity: number;
+    running: number;
+    /** Out of rotation until then: not answering, or without its model. */
+    downUntil?: number;
+    /** Held after a refusal until then. */
+    heldUntil?: number;
+}
+/**
+ * `undefined` when no node is configured, which is every session that predates
+ * this: the caller then takes the single delegated connection it always took.
+ */
+export declare function createAgentNodePlacement(input: {
+    nodes: readonly AgentNodeRuntimeConfig[];
+    base: DelegatedAgentConfigProvider;
+}): AgentNodePlacement | undefined;