@cerebriline/core 4.100.240

package/dist/runtime/orchestration/session-runtime-orchestrator.d.ts

@@ -0,0 +1,339 @@
+/**
+ * Per-session `SessionRuntime` orchestrator.
+ *
+ * Owns all cross-turn state for one logical agent session:
+ *
+ *   - `ConversationStore`      — message transcript + session-started gate
+ *   - `MistakeTracker`         — per-session consecutive-mistake counter
+ *   - `LoopDetectionTracker`   — per-session repeated-tool-call detector
+ *   - `MessageBuilder`         — provider-message assembly cache
+ *   - `AgentRuntimeHooks`      — runtime-native hooks from config/extensions
+ *   - `RuntimeEventAdapter`    — per-run stateful `AgentRuntimeEvent`
+ *                                → legacy `AgentEvent` translator
+ *   - listener registry        — host subscribers see legacy `AgentEvent`s
+ *   - pending tool set, abort  — per-run lifecycle housekeeping
+ *
+ * A fresh `AgentRuntime` is instantiated per run via
+ * `createAgentRuntime(createAgentRuntimeConfig({...}))`. All
+ * session-level state outlives any one `AgentRuntime`, making
+ * OAuth-retry and run replay feasible.
+ */
+import type { AgentRuntime } from "@cerebriline/agents";
+import { createAgentRuntime } from "@cerebriline/agents";
+import { type AgentConfig, type AgentEvent, type AgentExtensionRegistry, type AgentResult, type AgentTool, type BasicLogger, type ITelemetryService, type Message, type MessageWithMetadata } from "@cerebriline/shared";
+import { MessageBuilder } from "../../session/services/message-builder";
+import { type ConnectionUpdate } from "../config/connection-update";
+export declare const SESSION_RUN_IN_PROGRESS_ERROR_CODE = "session_run_in_progress";
+/**
+ * A session was asked to shut down while one of its runs was still in flight and
+ * no abort had been requested.
+ *
+ * Carries a code so callers can recognise it structurally after it crosses the
+ * hub's JSON boundary, where an `Error` arrives as a bare message. Connectors use
+ * it to tell "this thread's session is unusable" apart from a genuine run failure,
+ * and to recover by starting a fresh session instead of wedging the thread.
+ */
+export declare class SessionRunInProgressError extends Error {
+    readonly agentId?: string | undefined;
+    readonly code = "session_run_in_progress";
+    constructor(agentId?: string | undefined);
+}
+/**
+ * Whether a tool result reports that it made things worse.
+ *
+ * Failure is not the only way a call gets nowhere. An edit can land, report
+ * `success: true`, and leave the file with diagnostics it did not have before —
+ * which the host marks on the result as `regressed`. Measured on a live
+ * session: eight consecutive `editor` calls, every one successful, the file's
+ * diagnostics 2 → 20, and the class under repair written into the file three
+ * times over. Read as eight productive calls, the barren-repeat counter was
+ * reset on each and the loop stop could never fire.
+ *
+ * Same conservative reading as `allOperationsFailed`: only an explicit `true`
+ * counts, so an unrecognised shape can never end a task that was working.
+ *
+ * Exported for tests: it is the whole of the new loop signal, and driving a
+ * full runtime to assert one boolean would test the harness instead.
+ */
+export declare function introducedRegression(output: unknown): boolean;
+/**
+ * Whether a tool result says the call asked for nothing.
+ *
+ * This is a different animal from ordinary failure. An edit can fail for a
+ * reason that will not hold next time — a range that had moved, a read that had
+ * gone stale — and retrying it is reasonable. A "No change" refusal is the
+ * tool reporting that it compared the payload against the file and they were
+ * already identical, so an identical retry is answerable in advance.
+ *
+ * Measured: the same `editor` call, lines 94-96 and the same 1,336 characters,
+ * sent seven times against six of these refusals, with the whole file re-read
+ * between four of them. Twenty-four minutes, no edit, and the run ended on the
+ * loop stop regardless.
+ *
+ * Matches on the marker the message is built from rather than a copied string,
+ * and only where the envelope reports failure — a file whose contents happen to
+ * mention "No change" cannot trip it.
+ *
+ * Exported for tests, like `introducedRegression`: it is one boolean, and
+ * driving a full runtime to assert it would test the harness instead.
+ */
+export declare function declaredNoOp(output: unknown): boolean;
+/**
+ * Listener invoked for every legacy `AgentEvent` produced by the
+ * session runtime. Use `subscribeEvents(listener)` — it returns an
+ * `unsubscribe` function.
+ */
+export type SessionEventListener = (event: AgentEvent) => void;
+/** Subset of host-side deps needed by the session orchestrator. */
+export interface SessionRuntimeOrchestratorDeps {
+    readonly logger?: BasicLogger;
+    readonly telemetry?: ITelemetryService;
+    /**
+     * Test hook: override the `AgentRuntime` factory. Production
+     * callers leave this undefined and get the real `createAgentRuntime`.
+     */
+    readonly createAgentRuntimeImpl?: (config: Parameters<typeof createAgentRuntime>[0]) => AgentRuntime;
+}
+/** Connection overrides applied via `updateConnection`. */
+export type ConnectionOverrides = ConnectionUpdate;
+/**
+ * Per-session orchestrator. Construct once per agent session; call
+ * `run` / `continue` repeatedly. The class matches the subset of
+ * runtime-facing session surface.
+ */
+export declare class SessionRuntime {
+    private config;
+    private readonly agentId;
+    private readonly parentAgentId?;
+    private readonly logger?;
+    readonly telemetry?: ITelemetryService;
+    private readonly conversation;
+    private readonly mistakeTracker;
+    private readonly loopTracker;
+    /** Loop-guard warnings awaiting the tool result they belong to. */
+    private readonly pendingLoopWarnings;
+    /**
+     * Hard loop verdicts seen in this session, counted across tool names rather
+     * than per call signature. A run that works its way out of one loop and into
+     * another has not recovered, and the second one gets no second warning.
+     */
+    private loopHardEscalations;
+    /**
+     * The calls already inspected in the current assistant message, by
+     * signature, and the ids of the identical siblings that were not.
+     *
+     * An identical call in the same message is not a repeat: no answer came
+     * back between them, so there is nothing the model failed to learn from.
+     * Counted as consecutive attempts, a fan-out of fifteen identical agents
+     * -- what the user asked for on pandorum 2026-09-23 (6djrz) -- tripped the
+     * last warning at the fifth and stopped the run at the sixth, failing all
+     * 75 calls of the message. The batch counts once; the next message's
+     * repeat is still a repeat.
+     */
+    private loopBatchIteration;
+    private readonly loopBatchKeys;
+    private readonly loopBatchSiblings;
+    /**
+     * True when `execution.loopDetection === false` at construction
+     * time. Loop inspection is skipped entirely — the tracker still
+     * exists for API compatibility but is never fed.
+     */
+    private readonly loopDetectionDisabled;
+    readonly messageBuilder: MessageBuilder;
+    /**
+     * Contribution registry that hosts extension-provided tools,
+     * commands, message builders, and providers. Lazily initialized
+     * on first run (parity with legacy `Agent.ensureExtensionsInitialized`
+     * at `packages/agents/src/agent.ts:1122-1147`).
+     */
+    private readonly contributionRegistry;
+    private extensionsInitialized;
+    private readonly listeners;
+    private readonly createAgentRuntimeImpl;
+    /** Stable run id for the active run. */
+    private activeRunId;
+    /** True while a run is in flight. `canStartRun()` is the negation. */
+    private running;
+    /** True once `abort()` has been requested for the active run. */
+    private abortRequested;
+    /** Last abort reason requested for the active run. */
+    private abortReason;
+    /** Set by {@link requestCompaction}, taken by the next prepared turn. */
+    private compactionRequested;
+    /** Reference to the current run's `AgentRuntime` so `abort` can forward. */
+    private activeRuntime;
+    /** Promise returned from the current run so shutdown can await its drain. */
+    private activeRunPromise;
+    /** Per-run `Agent → AgentEvent` adapter; `reset()` each run. */
+    private readonly eventAdapter;
+    /** Session-shutdown gate — rejects late runs. */
+    private shutdownCalled;
+    /** Running tally of tool-call records for `AgentResult.toolCalls`. */
+    private currentRunToolCalls;
+    /** Aggregated usage across the current run. */
+    private currentRunUsage;
+    /** Tool-start timestamps for `ToolCallRecord.durationMs`. */
+    private toolStartedAt;
+    /** Tool-call input snapshot for `ToolCallRecord.input`. */
+    private toolInputs;
+    /**
+     * Per-turn tool outcome counters used by the MistakeTracker wiring.
+     * Reset on every `turn-started` event; consumed on `turn-finished`
+     * to feed `mistakeTracker.record` when every tool call erred and no
+     * successful call landed. Matches legacy `agent.ts` tool-failure
+     * mistake-feed path (§3.4.6 + pre-Step-9 oracle lines 972-997).
+     */
+    private currentTurnSuccessfulTools;
+    private currentTurnFailedTools;
+    private currentTurnFailureDetails;
+    /**
+     * Serial queue for `MistakeTracker.record(...)` + loop-detection
+     * side-effects fired from the sync `handleRuntimeEvent` stream. The
+     * tracker's `record()` is async but the runtime event stream is
+     * synchronous, so we chain tracker work onto a promise and await it
+     * in `executeRun` before returning the `AgentResult`.
+     */
+    private activeTrackerWork;
+    /** True when tracker logic has issued an abort for the active run. */
+    /**
+     * Set once a model has refused an image. Session-scoped: capabilities do not
+     * change mid-run, and re-attaching after a refusal only repeats it.
+     */
+    private imageInputRefused;
+    private trackerAbortInFlight;
+    private readonly handleExternalAbort;
+    constructor(config: AgentConfig, deps?: SessionRuntimeOrchestratorDeps);
+    getAgentId(): string;
+    getConversationId(): string;
+    getMessages(): MessageWithMetadata[];
+    /** True when no run is currently active and the session is not shut down. */
+    canStartRun(): boolean;
+    /**
+     * Snapshot of the contribution registry (tools, commands, and other
+     * extension contributions).
+     *
+     * Before the first run, the registry is in the `validate` phase:
+     * extensions are validated but their `setup()` callbacks have not
+     * run yet, so the snapshot only reflects eagerly-declared
+     * contributions. After the first `run()`/`continue()`, the
+     * registry is initialized (§`ensureExtensionsInitialized`), and
+     * the snapshot reflects everything extensions registered via
+     * `api.registerTool` / `registerCommand` / `registerMessageBuilder`
+     * / `registerProvider` / `registerAutomationEventType`.
+     */
+    getExtensionRegistry(): AgentExtensionRegistry<AgentTool, Message[]>;
+    /** Append additional tools to every subsequent turn's runtime config. */
+    addTools(tools: AgentTool[]): void;
+    /** Mutate provider / reasoning fields for subsequent runs. */
+    updateConnection(overrides: ConnectionOverrides): void;
+    /**
+     * The turn cap for the next run or continuation. `undefined` is no cap.
+     *
+     * A delegated agent stopped at its cap is continued, not restarted: the
+     * lead raises the cap and the same conversation goes on from its last turn.
+     * Each run counts its turns from zero, so this is the allowance for that
+     * one continuation.
+     */
+    setMaxIterations(maxIterations: number | undefined): void;
+    getMaxIterations(): number | undefined;
+    /**
+     * Compact before the next model request, as a manual compaction. For the
+     * lead's `compact_agents`: frees the agent's KV cells without stopping it.
+     * Takes effect at the agent's next turn; a run that has ended does it on
+     * its next continuation.
+     */
+    requestCompaction(): void;
+    /** Whether a compaction was asked for and not yet begun, for status. */
+    hasCompactionRequest(): boolean;
+    private takeCompactionRequest;
+    clearHistory(): void;
+    restore(messages: readonly MessageWithMetadata[]): void;
+    private resetConversationBoundaryTrackers;
+    /**
+     * Subscribe to **legacy** `AgentEvent`s. The session runtime
+     * translates the new `AgentRuntimeEvent` stream via
+     * `RuntimeEventAdapter` before fanout, so consumers see the
+     * pre-swap shape.
+     */
+    subscribeEvents(listener: SessionEventListener): () => void;
+    abort(reason?: unknown): void;
+    /** Shut the session down after any active run drains. */
+    shutdown(_reason?: string, _timeoutMs?: number): Promise<void>;
+    run(userMessage: string, userImages?: string[], userFiles?: string[]): Promise<AgentResult>;
+    /**
+     * Start a run whose conversation opens with `head`, then the task.
+     *
+     * The head is user turns that precede the task verbatim -- a sub-agent's
+     * shared knowledge and role. Seeded as their own turns rather than folded
+     * into the task, because on a KV pool each is a layer several agents share,
+     * and it only shares if it is its own turn, byte for byte.
+     */
+    runWithHead(head: readonly string[], userMessage: string): Promise<AgentResult>;
+    continue(userMessage?: string, userImages?: string[], userFiles?: string[]): Promise<AgentResult>;
+    private composeSystemPrompt;
+    private executeRun;
+    /**
+     * Retry a run once when it failed with an auth-like error and the host
+     * refreshed credentials via `config.onAuthError`. The failed attempt's
+     * trail is already persisted to the conversation store, so the retry
+     * continues from where the stream died instead of replaying the run.
+     */
+    private executeRunWithAuthRetry;
+    private executeRunInternal;
+    /**
+     * Initialize the contribution registry once per session. Runs
+     * extension `setup()` callbacks so they can `registerTool`,
+     * `registerCommand`, `registerMessageBuilder`, and
+     * `registerProvider`. Matches legacy `Agent.ensureExtensionsInitialized`
+     * at pre-Step-9 `agent.ts:1122-1147`:
+     *
+     *   - on `hookErrorMode === "throw"`, setup failures propagate;
+     *   - otherwise setup failures emit a recoverable `error` event
+     *     via the legacy event channel and leave the registry
+     *     partially initialized.
+     *
+     * Idempotent: subsequent calls are no-ops once the registry has
+     * been activated.
+     */
+    private ensureExtensionsInitialized;
+    private createRuntimeHooks;
+    private createRuntimePrepareTurn;
+    private prepareMessagesForModelRequest;
+    private prepareProviderMessagesForApi;
+    private handleRuntimeEvent;
+    private syncConversationFromRuntimeMessage;
+    private emitLegacyEvent;
+    private stampIdentity;
+    /**
+     * Feed the `LoopDetectionTracker` with a tool-call and react to
+     * the returned verdict. Parity with pre-Step-9 agent.ts L917-954:
+     *
+     *   - `"soft"`  → append a recovery notice telling the model to
+     *                 change approach;
+     *   - `"hard"`  → feed `MistakeTracker.record` with
+     *                 `forceAtLimit:true`. When the tracker returns
+     *                 `action: "stop"`, append the stop notice and
+     *                 abort the active runtime.
+     */
+    /**
+     * Report a finished tool call's outcome to the loop tracker, so a repeat
+     * that keeps failing can be told apart from one that keeps working.
+     */
+    private noteLoopOutcome;
+    private inspectLoopForToolCall;
+    /**
+     * Enqueue a mistake-record onto the serial tracker work chain. The
+     * runtime event stream is synchronous but `MistakeTracker.record`
+     * is async — chaining onto a shared promise preserves ordering
+     * (legacy parity) and lets `executeRun` await draining before
+     * returning the `AgentResult`.
+     *
+     * When the tracker returns `action: "stop"`, append the stop notice
+     * to the conversation and abort the active runtime so the run ends
+     * with `finishReason: "aborted"`.
+     */
+    /** Clear the tracker in order with any records already queued. */
+    private enqueueMistakeReset;
+    private enqueueMistakeRecord;
+    private buildLegacyResult;
+}

package/dist/runtime/orchestration/session-runtime.d.ts

@@ -0,0 +1,118 @@
+import type { AgentConfig, AgentEvent, AgentHooks, AgentResult, AgentTool, BasicLogger, ITelemetryService, ModelTool, RuntimeConfigExtensionKind, ToolApprovalRequest, ToolApprovalResult } from "@cerebriline/shared";
+import type { AgentPluginPackageMcpServer, AgentPluginPackageSkill } from "../../extensions/agent-plugin";
+import type { UserInstructionConfigService } from "../../extensions/config";
+import type { ReadReceipts, RunCommandExecutionController, ToolExecutors } from "../../extensions/tools";
+import type { AgentTeamsRuntime, DelegatedAgentConfigProvider, DelegatedPrepareTurnTarget, SubAgentEndContext, SubAgentStartContext, TeamEvent } from "../../extensions/tools/team";
+import type { ConfiguredAgentConfig } from "../../extensions/tools/team/configured-agent-config";
+import type { DelegatedSandboxes } from "../../extensions/tools/team/delegated-sandboxes";
+import type { SpawnToolOptions } from "../../extensions/tools/team/spawn-agent-tool";
+import type { WorkspaceManager } from "../../services/workspace/workspace-manager";
+import type { CoreSessionConfig } from "../../types/config";
+/**
+ * Internal structural alias for the lead-agent handle that
+ * {@link BuiltRuntime.registerLeadAgent} hands off to
+ * `runtime-builder.ts`. Narrowed to only the `.addTools()` surface the
+ * callback exercises; avoids depending on `@cerebriline/agents`' `Agent`
+ * class during the PLAN.md §3.6 Step 5 type-only migration. When
+ * SessionRuntime is rebuilt in Step 6, this field is expected to be
+ * dropped entirely per §3.5 row #2.
+ */
+type LeadAgentHandle = {
+    addTools(tools: AgentTool[]): unknown;
+};
+export interface BuiltRuntime {
+    tools: AgentTool[];
+    modelTools?: ModelTool[];
+    hooks?: AgentHooks;
+    logger?: BasicLogger;
+    telemetry?: ITelemetryService;
+    teamRuntime?: AgentTeamsRuntime;
+    teamRestoredFromPersistence?: boolean;
+    delegatedAgentConfigProvider?: DelegatedAgentConfigProvider;
+    /**
+     * The agent files this session loaded, kept so a host can list them and
+     * delegate to one on the user's say-so rather than the model's. The tools
+     * built from them are in `tools`; this is the mapping back to what the user
+     * wrote and named.
+     */
+    configuredAgents?: readonly ConfiguredAgentConfig[];
+    extensions?: AgentConfig["extensions"];
+    completionPolicy?: AgentConfig["completionPolicy"];
+    registerLeadAgent?: (agent: LeadAgentHandle) => void;
+    shutdown: (reason: string) => Promise<void> | void;
+}
+export interface RuntimeBuilderInput {
+    config: CoreSessionConfig;
+    /**
+     * Host-resolved stable end-user identity, forwarded so delegated agents
+     * (sub-agents / teammates) emit the same telemetry `userId` as the lead.
+     */
+    distinctId?: string;
+    hooks?: AgentHooks;
+    extensions?: AgentConfig["extensions"];
+    onTeamEvent?: (event: TeamEvent) => void;
+    onSubAgentEvent?: (event: AgentEvent) => void;
+    onSubAgentStart?: (context: SubAgentStartContext) => void | Promise<void>;
+    onSubAgentEnd?: (context: SubAgentEndContext) => void | Promise<void>;
+    createSpawnTool?: (options?: SpawnToolOptions) => AgentTool;
+    /** `spawn_swarm`, when the host can build one. See `local/spawn-tool.ts`. */
+    createSwarmTool?: () => AgentTool;
+    /**
+     * The session's delegated-agent workspaces. Configured agents and
+     * teammates -- the delegated paths the runtime builder runs itself -- each
+     * open one, so their writes land in a private overlay and come back to the
+     * lead as revisions. Absent, they keep the lead's executors and get no
+     * shell.
+     */
+    delegatedSandboxes?: () => DelegatedSandboxes;
+    onTeamRestored?: () => void;
+    userInstructionService?: UserInstructionConfigService;
+    pluginSkillDirectories?: ReadonlyArray<string>;
+    agentPluginSkills?: ReadonlyArray<AgentPluginPackageSkill>;
+    agentPluginMcpServers?: ReadonlyArray<AgentPluginPackageMcpServer>;
+    configExtensions?: RuntimeConfigExtensionKind[];
+    toolExecutors?: Partial<ToolExecutors>;
+    readReceipts?: ReadReceipts;
+    runCommandExecutionController?: RunCommandExecutionController;
+    toolPolicies?: CoreSessionConfig["toolPolicies"];
+    workspaceManager?: WorkspaceManager;
+    logger?: BasicLogger;
+    telemetry?: ITelemetryService;
+    requestToolApproval?: (request: ToolApprovalRequest) => Promise<ToolApprovalResult> | ToolApprovalResult;
+    /**
+     * Builds a context pipeline for one delegated agent -- a sub-agent or a
+     * teammate -- called once per agent so each gets its own.
+     *
+     * The lead's pipeline cannot be shared: it is closed over this session's
+     * compaction sidecar, so handing the same function to a delegated agent
+     * would project the lead's summary onto the delegate's transcript and then
+     * overwrite the lead's state with one computed from the delegate's
+     * messages. A factory is what lets every agent compact against its own
+     * history while still using the session's strategy, summarizer and window.
+     *
+     * Omitted means delegated agents run with no context pipeline at all, which
+     * is neither bounded nor visible: their transcripts grow past the model's
+     * window and the only sign is the provider quietly truncating the prompt.
+     */
+    createDelegatedPrepareTurn?: (agent?: DelegatedPrepareTurnTarget) => AgentConfig["prepareTurn"];
+    /**
+     * The other half of that pipeline, for the same agents.
+     *
+     * Stateless -- it writes a note about reasoning that is already being
+     * discarded -- so unlike the pipeline above it is shared, not rebuilt.
+     */
+    condenseDiscardedReasoning?: AgentConfig["condenseDiscardedReasoning"];
+}
+export interface RuntimeBuilder {
+    build(input: RuntimeBuilderInput): Promise<BuiltRuntime> | BuiltRuntime;
+}
+export interface SessionRuntime {
+    start(config: CoreSessionConfig): Promise<{
+        sessionId: string;
+    }>;
+    send(sessionId: string, prompt: string): Promise<AgentResult | undefined>;
+    abort(sessionId: string, reason?: unknown): Promise<void>;
+    stop(sessionId: string): Promise<void>;
+    poll(): Promise<string[]>;
+}
+export {};

package/dist/runtime/orchestration/user-input-builder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * User-input / first-turn content assembler.
+ *
+ * Opens the first user content array for a turn, loading user file contents via
+ * the injected `userFileContentLoader`.
+ */
+import type * as LlmsProviders from "@cerebriline/llms";
+export declare function buildInitialUserContent(userMessage: string, userImages?: string[], userFiles?: string[], userFileContentLoader?: (path: string) => Promise<string>): Promise<string | LlmsProviders.ContentBlock[]>;
+/**
+ * Normalize a user message shape into a plain string when possible.
+ *
+ * Accepts either a string or a LlmsProviders.Message; returns the best-effort
+ * concatenated plain-text body. Non-text content is ignored.
+ */
+export declare function normalizeUserMessage(input: string | LlmsProviders.Message | undefined): string;

package/dist/runtime/process-start-token.d.ts

@@ -0,0 +1,23 @@
+export type ProcessStartTokenProbeResult = {
+    status: "found";
+    token: string;
+} | {
+    status: "missing";
+} | {
+    status: "unavailable";
+};
+export declare function parseLinuxProcessStartToken(stat: string, bootId: string): string | undefined;
+/** Distinguishes an absent process from an unavailable identity probe. */
+export declare function probeProcessStartToken(pid: number): ProcessStartTokenProbeResult;
+/**
+ * Returns a token for one generation of a process ID.
+ *
+ * A PID alone is not an identity because the operating system can reuse it
+ * after a process exits. The token is derived from the kernel-reported process
+ * start time so callers can distinguish a live process from a later process
+ * that inherited the same PID.
+ */
+export declare function getProcessStartToken(pid: number): string | undefined;
+/** Non-blocking probe for latency-sensitive runtime paths. */
+export declare function probeProcessStartTokenAsync(pid: number): Promise<ProcessStartTokenProbeResult>;
+export declare function getProcessStartTokenAsync(pid: number): Promise<string | undefined>;

package/dist/runtime/safety/loop-detection.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Repeated tool-call loop detection.
+ *
+ * @see PLAN.md §3.1 — helpers moved from `packages/agents/src/context/loop-detection.ts`.
+ * @see PLAN.md §3.2.3 — public surface of `LoopDetectionTracker`.
+ *
+ * The pure helpers (`createLoopDetectionState`, `resetLoopDetectionState`,
+ * `toolCallSignature`, `checkRepeatedToolCall`) are ported verbatim. The
+ * `LoopDetectionTracker` class is a thin wrapper that owns a
+ * `LoopDetectionState` and exposes the `inspect()` / `reset()` surface that
+ * `SessionRuntime` installs as a `beforeTool` hook per §3.2.3.
+ */
+import type { LoopDetectionConfig } from "@cerebriline/shared";
+export interface LoopDetectionState {
+    lastToolName: string;
+    lastToolSignature: string;
+    consecutiveIdenticalCount: number;
+    /** Per `name:signature`, how many times it has been tried and failed. */
+    barrenCounts: Map<string, number>;
+    /**
+     * Signatures the tool has declared no-ops. Separate from `barrenCounts`
+     * because this is not a tally: one such outcome is already conclusive.
+     */
+    futileKeys: Set<string>;
+    /**
+     * Signatures that have succeeded at least once this session.
+     *
+     * A repeat of one of these is a different situation from a repeat that has
+     * only ever failed: the work is done and the model has not registered it.
+     */
+    appliedKeys: Set<string>;
+    /** Signatures already told once that their work had landed. */
+    settledKeys: Set<string>;
+    /**
+     * Per futile signature, how many strikes it has spent.
+     *
+     * Kept apart from `barrenCounts` because a futile call is refused before it
+     * runs, so it never reaches `noteOutcome` to be tallied there.
+     */
+    futileStrikes: Map<string, number>;
+    /** The call awaiting its outcome, so the result can be attributed. */
+    pendingKey: string;
+    /**
+     * Per signature, the last answer it got and how many times in a row that
+     * same answer came back. The no-progress half of the detector: a call whose
+     * result never changes is not advancing the task, however far apart its
+     * repeats are.
+     */
+    resultCycles: Map<string, {
+        signature: string;
+        repeats: number;
+    }>;
+}
+export declare function createLoopDetectionState(): LoopDetectionState;
+export declare function resetLoopDetectionState(state: LoopDetectionState): void;
+export declare function toolCallSignature(input: unknown): string;
+/**
+ * A repeated call as someone who did not make it can read it: the tool and
+ * its arguments, each string cut short.
+ *
+ * For the lead, whose "LOOPING" notice about a delegated agent used to say
+ * only that the loop guard fired. The agent knows what it was repeating; the
+ * lead deciding whether to resume it with other instructions did not, so it
+ * could only say "stop repeating" (pandorum h0o2o, 2026-09-28).
+ */
+export declare function describeRepeatedCall(name: string, input: unknown): string;
+/**
+ * The tools that change the workspace.
+ *
+ * Named rather than inferred: there is no flag on `AgentTool` saying a tool
+ * writes, and guessing from the name would count `read_files` the day someone
+ * adds `read_files_and_fix`. A tool this does not know about counts as an
+ * ordinary call, which is the safe direction -- it withholds a stop rather than
+ * inventing one.
+ *
+ * `restore_file` is one of them. It is the only tool here that writes by
+ * *removing* work, and a run that keeps calling it is the specific loop this
+ * set was extended for.
+ */
+export declare const WRITE_CLASS_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * Tools that report on something that moves by itself, so the same call can
+ * rightly be sent again and again: a lead waiting on its agents polls
+ * `agents_status`, and each answer is a later picture of them. The guard's
+ * premise -- "the arguments have not changed, so neither will the result" --
+ * does not hold for them. Measured on pandorum 2026-09-26: a lead in a side
+ * turn polled `agents_status` six times with no arguments while its swarm ran,
+ * and the guard stopped it.
+ */
+export declare const POLLING_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * The answer a tool gave, with the part that cannot repeat taken out.
+ *
+ * `editor` and `restore_file` both end their message with the revision the file
+ * is now at, and that ordinal goes up on every write. So two answers that are
+ * otherwise byte-identical are never equal, and a detector comparing answers
+ * sees a fresh one every time.
+ *
+ * Measured on pandorum 2026-09-18, session `1789748860618_ya4ps`: ten rounds of
+ * `restore_file` → `read_files` → `editor` with byte-identical arguments, and
+ * the two editor answers differed in three characters --
+ * `is now revision #13` against `is now revision #15`. The cycle counter reset
+ * to one on every round and no warning was ever produced. The number that makes
+ * the message useful to the model is the number that made the loop invisible to
+ * the guard, so it is removed here and nowhere else: the model still reads the
+ * real revision.
+ */
+export declare function loopResultSignature(output: unknown): string;
+export interface LoopCheckResult {
+    softWarning: boolean;
+    hardEscalation: boolean;
+}
+export declare function checkRepeatedToolCall(state: LoopDetectionState, toolName: string, signature: string, config: LoopDetectionConfig): LoopCheckResult;
+/**
+ * Verdict returned by {@link LoopDetectionTracker.inspect}.
+ *
+ * - `"ok"`   — no repeated call detected.
+ * - `"soft"` — soft-warning threshold reached; SessionRuntime may surface a
+ *              recovery notice but should not block the call.
+ * - `"hard"` — hard-escalation threshold reached; SessionRuntime decides what
+ *              follows from it.
+ *
+ * `message` is the diagnosis only, never the consequence. What happens next is
+ * the consumer's to decide and to word: the first hard verdict is delivered to
+ * the model as a last warning and the run continues, so a message that ended
+ * "stopping to avoid a loop" would have described something that did not
+ * happen. See `inspectLoopForToolCall` in the session orchestrator.
+ */
+export interface LoopDetectionVerdict {
+    kind: "ok" | "soft" | "hard";
+    message?: string;
+}
+/** Minimal call shape the tracker needs; matches `AgentToolCallPart` subset. */
+export interface LoopDetectionCall {
+    name: string;
+    input: unknown;
+}
+/**
+ * Per-session repeated-tool-call detector.
+ *
+ * `SessionRuntime` owns the instance and installs a `beforeTool` hook
+ * (see `AgentRuntimeHooks.beforeTool`) that calls `inspect()` to decide
+ * whether to return `{ skip, stop, reason }`.
+ */
+export declare class LoopDetectionTracker {
+    private readonly config;
+    private readonly state;
+    constructor(config?: Partial<LoopDetectionConfig>);
+    inspect(call: LoopDetectionCall): LoopDetectionVerdict;
+    /**
+     * Attribute an outcome to the call `inspect()` last saw.
+     *
+     * A productive call clears its own tally rather than merely not adding to
+     * it: a command that works, stops working, then works again is a normal
+     * edit-test cycle, and it should not inherit a count from the failures in
+     * between.
+     */
+    noteOutcome(productive: boolean, futile?: boolean, resultSignature?: string): void;
+    reset(): void;
+}