@cerebriline/core 4.100.240

package/dist/runtime/safety/worker-struggle.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Struggle supervision for a headless delegated worker.
+ *
+ * The lead session has had a struggle layer for a while: the {@link
+ * StruggleDetector} scores a run, {@link createStruggleFeed} drives it from the
+ * event stream, and {@link withStruggleSuggestion} lands the verdict on the
+ * next tool result. A delegated worker had none of it.
+ *
+ * What the worker layer does was set by replaying the two 75-agent swarms from
+ * pandorum (sessions yglnz and ysde8, 150 workers) through it, not by reasoning
+ * about what a stuck worker looks like. The replay overturned the first guess:
+ *
+ *  - **The loop is thinking that runs out its budget, turn after turn.** The
+ *    one worker that looped (`k76ar4`) spent its whole thinking budget on 9 of
+ *    18 turns -- each ending on the engine's "I have used my thinking budget"
+ *    -- while telling itself "I have enough evidence to write the report" and
+ *    probing once more. That is not exact repetition (the repeat guards stay
+ *    quiet) and not a long run (it died at turn 18). Across the other 149
+ *    workers only one hit the budget more than twice, and it answered.
+ *
+ *  - **Long is not stuck.** The longest workers (29, 36, 43 turns) all
+ *    answered in the end; they spent their tokens on edits, not on thought. A
+ *    turn-count stop, and a stop on the detector's refused-edit streak, would
+ *    have ended three of them before they reported. So both are nudge-only
+ *    here. A nudge costs a paragraph on a tool result; a stop costs a report.
+ *
+ * The terminal action a headless worker can take is *nudge once, then
+ * recover-and-stop*: the first trigger holds a worker-shaped nudge ("commit
+ * your best finding now as a SUMMARY") for the next tool result; only the
+ * budget loop carrying on after it -- past a grace window, so the nudge has a
+ * chance to land -- stops the worker, through the supervisor's abort signal.
+ * The stop is not data loss: the swarm's digest recovery reads whatever the
+ * worker produced, its reasoning tail included, so a stopped worker still
+ * reports. On the replay: `k76ar4` is nudged at turn 6 and stopped at turn 13,
+ * and no worker that answered is stopped.
+ */
+import type { AgentEvent, AgentToolDefinition } from "@cerebriline/shared";
+import { type StruggleThresholds } from "./struggle-detector";
+import { type WorkerStruggleReason } from "./worker-struggle-stop";
+/**
+ * Before this iteration the detector's window/distress path stays quiet.
+ *
+ * The lead floors this at 20 because a run stuck at iteration 12 is
+ * indistinguishable from one still reading the problem. A worker's whole life
+ * is shorter -- its `maxIterations` is ~40, not the lead's hundreds -- so the
+ * same floor would gate the signal out of most of the run. Lowered here; the
+ * edit-streak path fires outside this floor either way.
+ */
+export declare const WORKER_STRUGGLE_MIN_ITERATION = 8;
+/** Tool-calling turns without a final answer before the one nudge. */
+export declare const WORKER_NUDGE_AFTER_ITERATIONS = 20;
+/** Turns the budget loop is looked for over. */
+export declare const WORKER_BUDGET_WINDOW = 6;
+/** Budget-exhausted turns inside the window that earn the nudge. */
+export declare const WORKER_BUDGET_TURNS_TO_NUDGE = 3;
+/** Budget-exhausted turns after the grace window that stop the worker. */
+export declare const WORKER_BUDGET_TURNS_TO_STOP = 2;
+/** Turns the nudge is given to land before anything counts toward a stop. */
+export declare const WORKER_STRUGGLE_GRACE_ITERATIONS = 2;
+/**
+ * Worker-calibrated detector thresholds.
+ *
+ * Only the iteration floor moves; the failure/edit/transaction counts are the
+ * lead's, calibrated over the harness corpus and no less true of a worker.
+ */
+export declare const WORKER_STRUGGLE_THRESHOLDS: StruggleThresholds;
+export type WorkerStrugglePhase = "watching" | "nudged" | "stopped";
+export type { WorkerStruggleReason };
+export interface WorkerStruggleOptions {
+    /** Detector thresholds; defaults to {@link WORKER_STRUGGLE_THRESHOLDS}. */
+    thresholds?: StruggleThresholds;
+    /** Turns of tool-calling with no answer before the one nudge. */
+    nudgeAfterIterations?: number;
+    /**
+     * The server's thinking-budget message, when the session knows it.
+     *
+     * Without it, a turn counts as budget-exhausted when its reasoning ends on
+     * the generic admission -- see `reasoningHitBudget`.
+     */
+    thinkingBudgetMessage?: string;
+    /** See {@link WORKER_BUDGET_WINDOW}. */
+    budgetWindow?: number;
+    /** See {@link WORKER_BUDGET_TURNS_TO_NUDGE}. */
+    budgetTurnsToNudge?: number;
+    /** See {@link WORKER_BUDGET_TURNS_TO_STOP}. */
+    budgetTurnsToStop?: number;
+    /** Turns the worker is given to heed the nudge before a stop can count. */
+    graceIterations?: number;
+    /** Overrides the nudge text; by default it is worded for what fired it. */
+    nudgeMessage?: string;
+    /** Called on every phase transition, for logging and telemetry. */
+    onTransition?: (phase: WorkerStrugglePhase, reason: WorkerStruggleReason) => void;
+    /**
+     * The controller whose signal stops the worker.
+     *
+     * A spawn path that already owns the worker's abort controller passes it so
+     * one signal carries both the outer cancellation and this supervisor's stop.
+     * Omitted, the supervisor owns one of its own.
+     */
+    abortController?: AbortController;
+}
+export interface WorkerStruggleSupervisor {
+    /** Fold one agent event into the detector and the turn counter. */
+    observe(event: AgentEvent): void;
+    /** Wrap the worker's tools so the held nudge lands on the next result. */
+    wrapTools<T extends AgentToolDefinition>(tools: readonly T[]): T[];
+    /**
+     * Aborts when the worker is stopped, with the stop's words
+     * ({@link describeWorkerStop}) as its reason. A fresh one after
+     * {@link rearm}.
+     */
+    readonly stopSignal: AbortSignal;
+    /** Which stage of the machine the supervisor is in. */
+    readonly phase: WorkerStrugglePhase;
+    /**
+     * Be told of a stop, with the reason the run is to be aborted with. How
+     * the delegated agent's builder aborts the *run* -- not the agent, which
+     * the lead may resume. Returns the unsubscribe.
+     */
+    onStop(listener: (reason: Error) => void): () => void;
+    /**
+     * The lead resumed the worker it stopped: watch it from zero again, as
+     * a fresh attempt is watched, with a nudge and a stop still to give.
+     */
+    rearm(): void;
+}
+/**
+ * Where a worker's turn-count nudge sits, relative to its cap.
+ *
+ * Half the cap: late enough that a worker still reading the problem is left
+ * alone, early enough that the nudge arrives with turns to spare. It is a
+ * nudge only -- on the replayed swarms the longest workers all answered in the
+ * end, so the turn count is not evidence enough to stop one. With no cap set
+ * the supervisor's own default, calibrated to a ~40-iteration worker, stands.
+ * Every delegated path places it the same way: the swarm, `spawn_agent` and a
+ * configured agent.
+ */
+export declare function workerStruggleOptions(maxIterations?: number): Pick<WorkerStruggleOptions, "nudgeAfterIterations">;
+/**
+ * The supervisor a delegated agent gets, built the one way every path builds
+ * it: the nudge placed at half its cap, the server's thinking-budget message
+ * when the session knows it, and each transition logged under its name. Fresh
+ * per attempt, so a re-placed or restarted agent is watched from zero.
+ */
+export declare function createDelegatedStruggleSupervisor(input: {
+    /** How the log names it: `[agents] reviewer`. */
+    label: string;
+    maxIterations?: number;
+    thinkingBudgetMessage?: string;
+    logger?: {
+        log?: (message: string) => void;
+    };
+}): WorkerStruggleSupervisor;
+export { describeWorkerStop, isWorkerStruggleStop, } from "./worker-struggle-stop";
+/**
+ * The nudge a headless worker is handed, worded for what it can actually do.
+ *
+ * The lead's nudge names the expert and `spawn_agent`; a worker has neither, so
+ * naming them would be telling it to reach for a tool it does not hold. What it
+ * can do is stop and report -- the swarm digest is a free-form `SUMMARY:` text
+ * turn -- so that is the instruction. The opening line says what was measured,
+ * because "you keep running out of thinking" is actionable in a way "you have
+ * been going a while" is not.
+ */
+export declare function describeWorkerNudge(reason?: WorkerStruggleReason): string;
+export declare function createWorkerStruggleSupervisor(options?: WorkerStruggleOptions): WorkerStruggleSupervisor;

package/dist/runtime/sandbox/agent-sandbox.d.ts

@@ -0,0 +1,111 @@
+import { AgentOverlay, type OverlayChange } from "./overlay-fs";
+/** The native command-sandbox binary and its hook library. */
+export interface SandboxBinaries {
+    /** Absolute path to the `cerebriline-sandbox` launcher (`.exe` on Windows). */
+    launcher: string;
+    /**
+     * Absolute path to the hook library the launcher injects (Windows `hook.dll`);
+     * on Linux/macOS there is none, so this points back at the launcher, which
+     * ignores it — keeping `wrapSpawn`'s `[hook, log, cmd, ...]` shape uniform.
+     */
+    hook: string;
+    /** Platforms the binaries support. */
+    platforms?: NodeJS.Platform[];
+}
+type SpawnSpec = {
+    executable: string;
+    args: string[];
+    cwd: string;
+    env: Record<string, string>;
+};
+export interface AgentSandbox {
+    readonly overlay: AgentOverlay;
+    readonly overlayRoot: string;
+    /**
+     * Wrap a shell spawn so the command tree runs under the sandbox, or
+     * undefined when this platform has no launcher (the caller then withholds
+     * `run_commands`). Shape matches `ShellExecutorOptions.wrapSpawn`.
+     */
+    readonly wrapSpawn?: (spec: SpawnSpec) => SpawnSpec;
+    /** The agent's change set, for the hand-back to the lead. */
+    changedFiles(): Promise<OverlayChange[]>;
+    /** Remove the overlay and its log once the hand-back has been read. */
+    dispose(): Promise<void>;
+}
+export interface CreateAgentSandboxOptions {
+    /** The lead's workspace, read-only to the agent. */
+    workspaceRoot: string;
+    /** The agent's private overlay directory (in extension storage). */
+    overlayRoot: string;
+    /** The native binaries; absent means tools-only isolation, no sandboxed commands. */
+    binaries?: SandboxBinaries;
+    /**
+     * Confine the agent's commands: they read the system and write only the
+     * workspace (their overlay) and a temp folder. On unless set to `false`.
+     *
+     * The overlay keeps an agent's work off the lead's files and says nothing
+     * about the rest of the machine. In swarm wlafh one agent appended to the
+     * user's PATH and another copied a program into the home folder, and their
+     * reports said "no file changes".
+     */
+    confine?: boolean;
+}
+/**
+ * What the launcher is told to confine a command (see `confine.rs`,
+ * `windows.rs` and `macos.rs` in `sandbox/cerebriline-sandbox`).
+ *
+ * On Linux and macOS the system temp folder stays writable as it is. On
+ * Windows the user's `%TEMP%` is not writable to a low-integrity process and
+ * relabelling it would change the user's system, so the agent gets a temp
+ * folder of its own beside its overlay, which the launcher labels.
+ */
+export declare function confinementEnv(tempRoot: string, platform?: NodeJS.Platform): Record<string, string>;
+/**
+ * The environment with the workspace as the last entry of the search path.
+ *
+ * A command's working directory is the workspace, and whoever writes
+ * `run_game.exe page.html` means the program beside the page. cmd looks in the
+ * working directory by listing it, PowerShell and sh do not look there at all;
+ * on the search path the program is opened by its full name in every shell.
+ * Last, so nothing in the workspace shadows a system command.
+ */
+export declare function withWorkspaceOnPath(env: Record<string, string>, workspaceRoot: string, inherited?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): Record<string, string>;
+export declare function createAgentSandbox(options: CreateAgentSandboxOptions): Promise<AgentSandbox>;
+/**
+ * {@link createAgentSandbox} for a caller that cannot await: a teammate's
+ * toolset is built synchronously when it is spawned. Only the overlay root's
+ * creation differs; the sandbox is the same object.
+ */
+export declare function createAgentSandboxSync(options: CreateAgentSandboxOptions): AgentSandbox;
+/**
+ * Replace a finished sandbox log with `<log>.gz`, at gzip's fastest level.
+ *
+ * The trace is UTF-16 lines of the same few paths, and it compresses about
+ * 22x at level 1 (201 MB to 9 MB in a second, measured on a pandorum swarm
+ * log); the higher levels bought 5% more for the same time. Only once the
+ * agent is gone: every process in its tree appends to the plain file while it
+ * runs. A log that cannot be compressed is left as it is rather than lost,
+ * and an empty or absent one leaves nothing behind.
+ */
+export declare function archiveSandboxLog(logPath: string): Promise<void>;
+/**
+ * The lead's own commands, confined: a wrapper for its command executor, or
+ * undefined when confinement is off.
+ *
+ * The launcher runs in direct mode. There is no overlay, because the lead's
+ * changes are the user's: the command writes the workspace in place and a
+ * temp folder, and the rest of the system is read-only to it.
+ *
+ * With confinement on and no launcher for this platform the wrapper throws,
+ * so the command fails with the reason. Running it unconfined would be the
+ * one outcome the setting exists to prevent.
+ */
+export declare function createLeadConfinement(options: {
+    enabled: boolean;
+    workspaceRoot: string;
+    binaries?: SandboxBinaries;
+    /** Windows only: the temp folder the launcher makes writable. */
+    tempRoot: string;
+    platform?: NodeJS.Platform;
+}): ((spec: SpawnSpec) => SpawnSpec) | undefined;
+export {};

package/dist/runtime/sandbox/overlay-fs.d.ts

@@ -0,0 +1,71 @@
+/** AUFS-style whiteout marker prefix, shared with the native command layer. */
+export declare const WHITEOUT_PREFIX = ".wh.";
+export type OverlayChangeKind = "modified" | "created" | "deleted";
+export interface OverlayChange {
+    /** Workspace-relative path, forward-slashed. */
+    rel: string;
+    kind: OverlayChangeKind;
+    /** Absolute overlay path (absent for a deletion). */
+    overlayPath?: string;
+}
+/**
+ * The agent's overlay. `workspaceRoot` is the lead's tree, read-only here;
+ * `overlayRoot` is the agent's private directory in extension storage.
+ */
+export declare class AgentOverlay {
+    private readonly workspaceRoot;
+    private readonly overlayRoot;
+    private readonly copyUpListeners;
+    constructor(workspaceRoot: string, overlayRoot: string);
+    /**
+     * Be told when a workspace file is copied up into the overlay, after the
+     * copy. The read receipts use it: the agent read the workspace file, and
+     * the copy it is about to edit is that same file.
+     */
+    onCopyUp(listener: (wsPath: string, ovPath: string) => Promise<void> | void): void;
+    /**
+     * `text` with every path into the overlay rewritten to the workspace path
+     * it stands for. For anything an executor hands back to the agent: the
+     * agent is told only about the workspace, and an overlay path in a result
+     * or a refusal is an address it would then read and write directly.
+     */
+    redact(text: string): string;
+    /**
+     * The workspace path an overlay path stands for; any other path unchanged.
+     * A file is one file to the agent whichever side of the overlay it is
+     * currently read from, and anything keyed by path must agree.
+     */
+    logicalPath(p: string): string;
+    /** Where a path lands. Paths outside the workspace are used as given. */
+    private locate;
+    /**
+     * Resolve a path to the real file a *read* should open: the overlay copy if
+     * present, a non-existent overlay path when the file was deleted (so the
+     * caller's own read fails with ENOENT), otherwise the workspace file. Lets an
+     * executor keep using `fs`/`createReadStream` on the returned path.
+     */
+    resolveRead(p: string): Promise<string>;
+    /**
+     * Resolve a path to the real file a *write* should open, copying the
+     * workspace version up into the overlay first so a read-modify-write sees the
+     * lead's content, and dropping any whiteout. The returned overlay path is
+     * what the executor then reads and writes.
+     */
+    resolveWrite(p: string): Promise<string>;
+    read(p: string): Promise<Buffer>;
+    write(p: string, data: Buffer | string): Promise<void>;
+    unlink(p: string): Promise<void>;
+    rename(src: string, dst: string): Promise<void>;
+    mkdir(p: string, opts?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    stat(p: string): Promise<import("node:fs").Stats>;
+    exists(p: string): Promise<boolean>;
+    /** Merged listing: overlay entries, then workspace entries not shadowed,
+     *  minus whiteouted names and the tombstone markers themselves. */
+    readdir(p: string): Promise<string[]>;
+    private listRaw;
+    /** The agent's change set: what to hand the lead as revisions. */
+    changedFiles(): Promise<OverlayChange[]>;
+    private walk;
+}

package/dist/runtime/sandbox/sandbox-binaries.d.ts

@@ -0,0 +1,10 @@
+import type { SandboxBinaries } from "./agent-sandbox";
+/**
+ * The native command-sandbox launcher under `dir`, or undefined when there is
+ * none for this platform. Windows is the Detours launcher + hook DLL; Linux is
+ * the `cerebriline-sandbox` binary (user namespace + overlayfs, no injected
+ * library — the `hook` field is unused there and points at the launcher itself
+ * so the shared `wrapSpawn` shape holds). A platform with no launcher gets file
+ * isolation without a shell rather than an unsandboxed one.
+ */
+export declare function resolveSandboxBinaries(dir?: string): SandboxBinaries | undefined;

package/dist/runtime/tools/subprocess-sandbox-lifecycle.d.ts

@@ -0,0 +1,9 @@
+export declare const MAX_NODE_TIMER_DELAY_MS = 2147483647;
+type ParentProcess = {
+    once(event: "disconnect", listener: () => void): unknown;
+    exit(code: number): unknown;
+};
+export declare function normalizeIdleTimeoutMs(timeoutMs: number | undefined): number | undefined;
+/** Ensure an IPC child cannot survive the process that owns it. */
+export declare function installParentDisconnectGuard(target?: ParentProcess): void;
+export {};

package/dist/runtime/tools/subprocess-sandbox.d.ts

@@ -0,0 +1,62 @@
+export interface SubprocessSandboxOptions {
+    /** Inline script to execute via `node -e`. Mutually exclusive with {@link bootstrapFile}. */
+    bootstrapScript?: string;
+    /** Path to a JavaScript file to execute via `node <file>`. Mutually exclusive with {@link bootstrapScript}. */
+    bootstrapFile?: string;
+    /** Runtime executable for internal JavaScript helpers. Defaults to node/bun instead of packaged CLI binaries. */
+    runtimeExecutable?: string;
+    /**
+     * Shut down the child after this many milliseconds with no calls in flight.
+     * The next call starts a fresh child transparently. Disabled when omitted.
+     */
+    idleTimeoutMs?: number;
+    name?: string;
+    onEvent?: (event: {
+        name: string;
+        payload?: unknown;
+    }) => void;
+}
+export interface SandboxCallOptions {
+    timeoutMs?: number;
+}
+export declare const CLINE_JS_RUNTIME_PATH_ENV = "CLINE_JS_RUNTIME_PATH";
+export declare function resolveSubprocessRuntimeExecutable(options?: {
+    env?: NodeJS.ProcessEnv;
+    execPath?: string;
+    runtimeExecutable?: string;
+}): string;
+export declare function buildSubprocessSandboxCommand(args: string[], options?: {
+    env?: NodeJS.ProcessEnv;
+    execArgv?: string[];
+    name?: string;
+    execPath?: string;
+    runtimeExecutable?: string;
+}): string[];
+export declare class SubprocessSandbox {
+    private readonly options;
+    private readonly idleTimeoutMs;
+    private process;
+    private requestCounter;
+    private readonly pending;
+    private idleTimer;
+    private readonly shutdowns;
+    constructor(options: SubprocessSandboxOptions);
+    private get processLabel();
+    private clearPendingRequest;
+    private clearIdleTimer;
+    private hasPendingRequests;
+    /**
+     * The parent is the sole idle-lifecycle authority. A matching child-side
+     * deadline can fire just before this timer and drop a newly dispatched RPC.
+     * Children should independently handle only parent IPC disconnection.
+     */
+    private armIdleTimer;
+    start(): void;
+    call<TResult = unknown>(method: string, args: unknown, options?: SandboxCallOptions): Promise<TResult>;
+    shutdown(): Promise<void>;
+    private shutdownProcess;
+    private terminateProcess;
+    private onMessage;
+    private failPendingForProcess;
+    private failPending;
+}

package/dist/runtime/tools/tool-approval.d.ts

@@ -0,0 +1,9 @@
+import type { ToolApprovalRequest, ToolApprovalResult } from "@cerebriline/shared";
+export type DesktopToolApprovalOptions = {
+    approvalDir?: string;
+    sessionId?: string;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    nowIso?: () => string;
+};
+export declare function requestDesktopToolApproval(request: ToolApprovalRequest, options?: DesktopToolApprovalOptions): Promise<ToolApprovalResult>;

package/dist/runtime/turn-queue/harness-notes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The harness's notes to the model, and how queued ones merge.
+ *
+ * Every note opens with {@link HARNESS_TAG} so the model can tell the harness
+ * from the user. They are written to be cheap: pandorum 2026-09-26, one
+ * queued note of nine side-turn recaps was 11.4k characters, each recap
+ * quoting the whole stuck-agent report again, and the facts in it were 1.5k.
+ */
+/** What every note from the harness to the model opens with. */
+export declare const HARNESS_TAG = "[SYSTEM MESSAGE]";
+/** The first line of the side-turn recap note. */
+export declare const SIDE_TURN_RECAP_HEADER = "[SYSTEM MESSAGE] Side turns while your agents ran (already done, do not repeat):";
+/**
+ * Two recap notes as one. The user's messages come first, every one kept.
+ * Of the reports on stuck agents only the latest is kept whole: it names the
+ * agents as they are now. An older one survives only as what it did to them.
+ */
+export declare function mergeSideTurnRecaps(older: string, newer: string): string;

package/dist/runtime/turn-queue/pending-prompt-service.d.ts

@@ -0,0 +1,117 @@
+import { type AgentMode } from "@cerebriline/shared";
+import type { CoreSessionEvent, SessionPendingPrompt } from "../../types/events";
+import type { ActiveSession } from "../../types/session";
+import type { PendingPromptMutationResult, PendingPromptsDeleteInput, PendingPromptsUpdateInput } from "../host/runtime-host";
+export type PendingPromptDelivery = "queue" | "steer";
+/**
+ * Who queued a prompt. `harness` is text the runtime writes to the model --
+ * a side turn's recap, a round's report, a nudge about stuck agents -- that
+ * rides the same queue as the user's messages; the UI labels it instead of
+ * showing it as something the user typed.
+ */
+export type PendingPromptOrigin = "user" | "harness";
+/**
+ * Harness notes that merge while they wait: a status report is replaced by a
+ * newer one (it describes the same agents, later), and side-turn recaps are
+ * merged into one note (`mergeSideTurnRecaps`: the user's messages first,
+ * the latest report on the agents whole). Measured
+ * 2026-09-26: a lead held by its round collected seven separate recaps.
+ * An `awaiting` note lists the agents waiting on the lead; it is replaced
+ * too, and rewritten when it is read (`refresh`).
+ */
+export type PendingPromptNoteKind = "status" | "recap" | "awaiting" | "queued";
+/**
+ * Rewrites a harness note as it is delivered: what it says may have changed
+ * since it was queued. `undefined` drops it. Swarm 2026-09-27: 2 of 51 cap
+ * notes reached the lead after it had resumed the agents they named.
+ */
+export type PendingPromptRefresh = () => string | undefined;
+export interface PendingPromptEntry {
+    id: string;
+    prompt: string;
+    mode?: AgentMode;
+    delivery: PendingPromptDelivery;
+    userImages?: string[];
+    userFiles?: string[];
+    origin?: PendingPromptOrigin;
+    /** For a harness note: what it is, so a later one of the same kind merges. */
+    noteKind?: PendingPromptNoteKind;
+    refresh?: PendingPromptRefresh;
+}
+export interface PendingPromptQueueState {
+    pendingPrompts: PendingPromptEntry[];
+}
+export interface PendingPromptsControllerDeps {
+    getSession(sessionId: string): ActiveSession | undefined;
+    emit(event: CoreSessionEvent): void;
+    send(input: {
+        sessionId: string;
+        prompt: string;
+        mode?: AgentMode;
+        userImages?: string[];
+        userFiles?: string[];
+    }): Promise<unknown>;
+}
+export interface PendingPromptEnqueueInput {
+    prompt: string;
+    mode?: AgentMode;
+    delivery: PendingPromptDelivery;
+    userImages?: string[];
+    userFiles?: string[];
+    origin?: PendingPromptOrigin;
+    noteKind?: PendingPromptNoteKind;
+    refresh?: PendingPromptRefresh;
+}
+export interface PendingPromptConsumeResult {
+    entry?: PendingPromptEntry;
+    prompts: SessionPendingPrompt[];
+}
+export declare class PendingPromptService {
+    list(state: PendingPromptQueueState | undefined): SessionPendingPrompt[];
+    update(state: PendingPromptQueueState | undefined, input: PendingPromptsUpdateInput): PendingPromptMutationResult;
+    delete(state: PendingPromptQueueState | undefined, input: PendingPromptsDeleteInput): PendingPromptMutationResult;
+    enqueue(state: PendingPromptQueueState, input: PendingPromptEnqueueInput): SessionPendingPrompt[];
+    consumeSteer(state: PendingPromptQueueState): PendingPromptConsumeResult;
+    shiftNext(state: PendingPromptQueueState): PendingPromptConsumeResult;
+    requeueFront(state: PendingPromptQueueState, entry: PendingPromptEntry): SessionPendingPrompt[];
+    clear(state: PendingPromptQueueState): SessionPendingPrompt[];
+    /** Drop the harness's notes, keeping what the user queued. */
+    dropHarnessNotes(state: PendingPromptQueueState): number;
+}
+export declare class PendingPromptsController {
+    private readonly deps;
+    private readonly service;
+    constructor(deps: PendingPromptsControllerDeps);
+    list(sessionId: string): SessionPendingPrompt[];
+    update(input: PendingPromptsUpdateInput): PendingPromptMutationResult;
+    delete(input: PendingPromptsDeleteInput): PendingPromptMutationResult;
+    enqueue(sessionId: string, entry: {
+        prompt: string;
+        mode?: AgentMode;
+        delivery: "queue" | "steer";
+        userImages?: string[];
+        userFiles?: string[];
+        origin?: PendingPromptOrigin;
+        noteKind?: PendingPromptNoteKind;
+        refresh?: PendingPromptRefresh;
+    }): void;
+    consumeSteer(sessionId: string): PendingPromptEntry | undefined;
+    /**
+     * Drops every queued prompt. Only called when the user aborts a
+     * queue-initiated turn — that gesture means "stop the queued work", not
+     * just "stop this response", so the remainder must not auto-run.
+     */
+    discardQueue(session: ActiveSession): void;
+    /**
+     * A user's Cancel stops the lead; the harness's notes to it must not start
+     * it again. They were the lead's to read at its next boundary, and a
+     * cancelled turn has none: drained, a queued note ran a new turn the moment
+     * the old one stopped -- on pandorum 2026-09-26 it compacted a 58k-token
+     * transcript until a second Cancel. What the user queued still runs.
+     */
+    dropHarnessNotes(session: ActiveSession): void;
+    emitPrompts(session: ActiveSession): void;
+    scheduleDrain(sessionId: string, session: ActiveSession): void;
+    drain(sessionId: string): Promise<void>;
+    private emitSubmitted;
+}

package/dist/services/agent-events.d.ts

@@ -0,0 +1,59 @@
+import type { AgentEvent } from "@cerebriline/shared";
+import type { SessionAccumulatedUsage } from "../runtime/host/runtime-host";
+import type { CoreSessionConfig } from "../types/config";
+import type { CoreSessionEvent } from "../types/events";
+import type { ActiveSession } from "../types/session";
+import { type TelemetryAgentIdentityProperties } from "./telemetry/core-events";
+export declare function extractSkillNameFromToolInput(input: unknown): string | undefined;
+export interface AgentEventContext {
+    sessionId: string;
+    config: CoreSessionConfig;
+    liveSession: ActiveSession | undefined;
+    usageBySession: Map<string, SessionAccumulatedUsage>;
+    aggregateUsageBySession: Map<string, SessionAccumulatedUsage>;
+    persistMessages: (sessionId: string, messages: unknown[], systemPrompt?: string) => void;
+    emit: (event: CoreSessionEvent) => void;
+}
+export interface AgentTelemetryContextOverrides {
+    agentId?: string;
+    conversationId?: string;
+    parentAgentId?: string | null;
+    createdByAgentId?: string;
+    teamId?: string;
+    teamName?: string;
+    teamRole?: "lead" | "teammate";
+    teamAgentId?: string;
+    isPrimaryAgentEvent?: boolean;
+}
+export declare function extractAgentEventMetadata(event: AgentEvent): {
+    agentId?: string;
+    conversationId?: string;
+    parentAgentId?: string;
+};
+export declare function buildTelemetryAgentIdentity(context: AgentTelemetryContextOverrides): TelemetryAgentIdentityProperties | undefined;
+/**
+ * `task.tokens` telemetry contract (inherited from the legacy extension):
+ * one event per completed model request, carrying that request's token/cost
+ * deltas as DISJOINT buckets — `tokensIn` is uncached input only, with cache
+ * reads/writes reported in their own attributes, so
+ * `sum(tokensIn + cacheReadTokens + cacheWriteTokens)` equals total input.
+ *
+ * SDK usage events follow the AI SDK convention instead: `event.inputTokens`
+ * is the FULL request input, cache reads/writes included. Emitting it as
+ * `tokensIn` unchanged re-reports the whole (mostly cached) conversation
+ * context on every request, so per-task sums re-count the same context
+ * tokens once per request. This helper translates to the legacy disjoint
+ * buckets (mirroring the webview's `normalizeUsageEvent`). The clamp keeps
+ * ApiHandler-backed providers — whose `inputTokens` is already uncached-only
+ * — from going negative.
+ */
+export declare function legacyTokenUsageFromUsageEvent(event: Extract<AgentEvent, {
+    type: "usage";
+}>): {
+    tokensIn: number;
+    tokensOut: number;
+    cacheWriteTokens: number;
+    cacheReadTokens: number;
+    totalCost?: number;
+};
+export declare function handleAgentEvent(ctx: AgentEventContext, event: AgentEvent, overrides?: AgentTelemetryContextOverrides): void;

package/dist/services/config.d.ts

@@ -0,0 +1,2 @@
+import type { CoreSessionConfig } from "../types/config";
+export declare function resolveWorkspacePath(config: CoreSessionConfig): string;

package/dist/services/connectors/active-connectors.d.ts

@@ -0,0 +1,2 @@
+import type { ActiveConnectorRecord } from "@cerebriline/shared";
+export declare function listActiveConnectors(): ActiveConnectorRecord[];