@vib-rato/agent-core 0.16.0

package/dist/types/agent-loop.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Agent loop that works with AgentMessage throughout.
+ * Transforms to Message[] only at the LLM call boundary.
+ */
+import { type AssistantMessage, type AssistantMessageEvent, type Context, EventStream } from "@vib-rato/ai";
+import type { AttemptScope } from "./attempt-scope";
+import { type AgentRunCoverage, type AgentRunSummary } from "./run-collector";
+import { type AgentContext, type AgentEvent, type AgentLoopConfig, type AgentMessage, type StreamFn } from "./types";
+/** Sentinel returned by the abort race in `streamAssistantResponse`. */
+/**
+ * Defensive caps for a provisional managed attempt. These are intentionally
+ * well above ordinary streamed responses; they only bound memory when an
+ * upstream emits an unbounded event stream before the attempt can commit.
+ */
+export declare const MANAGED_ATTEMPT_MAX_STAGED_EVENTS = 10000;
+export declare const MANAGED_ATTEMPT_MAX_STAGED_BYTES: number;
+/**
+ * Hard ceilings for the operator overrides. The caps exist to bound memory, so
+ * an override may raise them only within a range that still leaves the guard
+ * meaningful — near-`MAX_SAFE_INTEGER` values would trade a typed, bounded
+ * `local_buffer_overflow` for a process OOM, which is strictly harder to
+ * diagnose. Above-ceiling overrides clamp to the ceiling with a warning
+ * instead of being honored.
+ *
+ * The ceilings are derived from a survivable PEAK-RSS budget, not from the
+ * counted-bytes number: peak resident memory holds the live payload, its
+ * detached snapshot, and the retained batch simultaneously, so it is a
+ * multiple of the counted bytes. Sizing itself is walk-based (no JSON string
+ * or UTF-8 copy is materialized to measure), which is why the factor below
+ * covers the live value plus one detached copy plus batch retention with
+ * headroom. The bytes ceiling is the peak budget divided by that multiplier,
+ * so an override at the ceiling still fits an ordinary host. The events
+ * ceiling is the object-count equivalent for the same budget at a
+ * conservative per-item floor.
+ */
+export declare const MANAGED_STAGED_PEAK_RSS_BUDGET_BYTES: number;
+export declare const MANAGED_STAGED_PEAK_RSS_FACTOR = 4;
+export declare const MANAGED_ATTEMPT_STAGED_EVENTS_CEILING = 2000000;
+export declare const MANAGED_ATTEMPT_STAGED_BYTES_CEILING: number;
+/**
+ * Max events staged by a provisional managed-attempt transaction before it is
+ * rejected. Configurable via `VIB_FALLBACK_MAX_STAGED_EVENTS` (default
+ * `MANAGED_ATTEMPT_MAX_STAGED_EVENTS`, ceiling
+ * `MANAGED_ATTEMPT_STAGED_EVENTS_CEILING`). Read once per transaction so
+ * operators can raise the cap without a rebuild and tests can exercise the
+ * knob in-process. Values must be positive integers after the trusted
+ * resolver ignores surrounding whitespace; invalid or
+ * non-positive values fall back to the default, and values above the ceiling
+ * clamp to it with a warning.
+ *
+ * @internal
+ */
+export declare function managedAttemptMaxStagedEvents(): number;
+/**
+ * Max bytes staged by a provisional managed-attempt transaction before it is
+ * rejected. Configurable via `VIB_FALLBACK_MAX_STAGED_BYTES` (default
+ * `MANAGED_ATTEMPT_MAX_STAGED_BYTES`, ceiling
+ * `MANAGED_ATTEMPT_STAGED_BYTES_CEILING`). Read once per transaction; values
+ * must be positive integers after the trusted resolver ignores surrounding
+ * whitespace, anything else falls back to the
+ * default, and values above the ceiling clamp to it with a warning.
+ *
+ * @internal
+ */
+export declare function managedAttemptMaxStagedBytes(): number;
+/**
+ * Closed set of local-failure sites. A bounded diagnostic may name only these
+ * literals: the log is shape-only, so no caller-supplied or provider-derived
+ * string may ever reach it.
+ */
+declare const MANAGED_LOCAL_FAILURE_STAGES: readonly ["shell.role", "shell.content", "event.snapshot", "event.contentIndex", "event.delta", "event.content", "event.toolcall", "event.done.reason", "event.error.reason", "event.unknownType", "staging.losslessSnapshot", "staging.measure", "staging.sanitize", "staging.preMeasure", "staging.overflow", "overflow.preMeasure", "overflow.staged"];
+type ManagedLocalFailureStage = (typeof MANAGED_LOCAL_FAILURE_STAGES)[number];
+/**
+ * How many times a single turn may be re-requested because its tool arguments
+ * arrived as `\uXXXX` escapes instead of literal UTF-8.
+ *
+ * The defect is a wire-format accident that resampling clears, so a small
+ * budget recovers the overwhelming majority of turns; past it the terminal
+ * per-call rejection takes over rather than spending the run on retries.
+ */
+export declare const ESCAPED_NONASCII_RECOVERY_PROMPT: string;
+/**
+ * Start an agent loop with a new prompt message.
+ * The prompt is added to the context and events are emitted for it.
+ */
+export declare function agentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn, emitAgentStart?: boolean, initialScope?: AttemptScope): EventStream<AgentEvent, AgentMessage[]>;
+/**
+ * Continue an agent loop from the current context without adding a new message.
+ * Used for retries - context already has user message or tool results.
+ *
+ * **Important:** The last message in context must convert to a `user` or `toolResult` message
+ * via `convertToLlm`. If it doesn't, the LLM provider will reject the request.
+ * This cannot be validated here since `convertToLlm` is only called once per turn.
+ */
+export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn, emitAgentStart?: boolean, initialScope?: AttemptScope): EventStream<AgentEvent, AgentMessage[]>;
+/**
+ * Structured, shape-only overflow diagnostic carried on the terminal
+ * `AssistantMessage` of a managed run that died of a staging-buffer overflow.
+ * Every field is closed-vocabulary or numeric, so parent surfaces can render a
+ * trustworthy summary WITHOUT trusting the free-form `errorMessage` string
+ * (which a foreign, self-labeled error can still fill with arbitrary text).
+ */
+export interface ManagedBufferOverflowDiagnostic {
+    stage: ManagedLocalFailureStage | "unknown";
+    exceeded: "events" | "bytes" | "both";
+    stagedEventCount: number;
+    stagedBytes: number;
+    incomingEventBytes: number;
+    maxStagedEvents: number;
+    maxStagedBytes: number;
+}
+/**
+ * The complete set of local-diagnostic authority fields a terminal
+ * `AssistantMessage` may carry. Produced only by
+ * {@link managedLocalErrorDiagnostic}, so `errorKind` and `bufferOverflow`
+ * always travel together from one identity check.
+ */
+export interface ManagedLocalErrorDiagnostic {
+    errorKind: "local_snapshot_failure" | "local_buffer_overflow";
+    bufferOverflow?: ManagedBufferOverflowDiagnostic;
+}
+/**
+ * Single identity-checked source of local-failure authority. Returns
+ * `undefined` unless the error is genuinely `instanceof` one of this module's
+ * private local-failure classes — a foreign error that merely sets
+ * `errorKind: "local_buffer_overflow"` fails the identity check and receives
+ * NEITHER the kind nor the structured shape, so a provider or custom-stream
+ * failure can never be reported to the parent as a local staging-buffer
+ * overflow (#4618).
+ *
+ * Every producer of a terminal assistant message (`managedFailureMessage` and
+ * the `Agent` run catch) MUST derive both fields from this function instead of
+ * reading `errorKind`/`errorMessage` off the thrown value.
+ */
+export declare function managedLocalErrorDiagnostic(error: unknown): ManagedLocalErrorDiagnostic | undefined;
+/**
+ * Hard work budget for one degraded snapshot: every visited node AND every
+ * enumerated own key is debited against this budget before it is processed
+ * (accessor keys and re-visits of shared objects included), and any remainder
+ * collapses to the deterministic `"[truncated]"` placeholder. Well above
+ * ordinary streamed events; it only bounds hostile graphs.
+ */
+export declare const MANAGED_SNAPSHOT_MAX_NODES = 100000;
+/**
+ * Cycle-aware deep clone that always returns a detached, JSON-serializable
+ * value. Used whenever a detached snapshot cannot be safely obtained or
+ * measured: after `structuredClone` fails, and again when a (successfully
+ * cloned) snapshot cannot be serialized for byte accounting.
+ *
+ * Totality rules — the walk must never dispatch through payload-controlled
+ * code, throw, or do unbounded work:
+ * - proxies (revoked or live) are collapsed to `"[unserializable]"` BEFORE
+ *   any reflective operation, so `ownKeys`/descriptor traps are never
+ *   dispatched (`util.types.isProxy` identifies proxies without touching
+ *   their handlers);
+ * - only intrinsics are used on the remaining ordinary objects (no
+ *   `input.map`, no `input.getTime()`, no `input.length` reads);
+ * - arrays are enumerated through their own present keys, never their
+ *   declared length, so a sparse array cannot force a dense allocation
+ *   proportional to `length`; sparse/exotic arrays degrade to a null-proto
+ *   record of their present indices, and the dense-shape decision verifies
+ *   every index against its ordinal;
+ * - the walk debits `maxNodes` budget per visited node and per enumerated
+ *   key before processing it; anything beyond the budget becomes
+ *   `"[truncated]"` (the one linear primitive per visited node is a single
+ *   `Object.keys` call on a non-proxy object the process already holds);
+ * - property values are read via own-property descriptors, so accessors are
+ *   never invoked (a snapshot must not cause observable side effects) and are
+ *   replaced with `"[accessor]"`;
+ * - functions/symbols and any property that cannot be read safely become
+ *   short placeholders, `bigint` becomes its decimal string, and references
+ *   back into the current path collapse to `"[Circular]"`;
+ * - records are built on a null prototype so a `__proto__` key cannot mutate
+ *   the clone's prototype chain.
+ *
+ * Exported for direct regression coverage of the budget accounting; runtime
+ * callers use the default budget via {@link managedAttemptSnapshot}.
+ */
+export declare function sanitizedDetachedClone<T>(value: T, maxNodes?: number): T;
+/**
+ * Exact serialized size of a staged snapshot, computed by walking the JSON
+ * surface. Replaces the previous `JSON.stringify` + `TextEncoder.encode`
+ * measurement, which materialized a full copy of the serialized value — and
+ * a second copy of its UTF-8 encoding — BEFORE the cap check could reject
+ * it: the budget-sized transient allocation the memory guard exists to
+ * prevent (exact-head 078e22c0 finding 1). Returns `undefined` when the
+ * value cannot be serialized, matching the previous measurement's failure
+ * mode so callers keep their sanitize fallbacks.
+ *
+ * @internal
+ */
+export declare function managedSnapshotJsonByteLength(value: unknown): number | undefined;
+export declare function managedAssistantEventSnapshot(event: AssistantMessageEvent, message: AssistantMessage, degradedFieldDiagnostics?: Set<string>): AssistantMessageEvent;
+/**
+ * Detailed-result handle returned by {@link agentLoopDetailed}. Adds the
+ * run-level telemetry/coverage rollup to the existing `AgentMessage[]`
+ * payload without changing the resolved type of `stream.result()`.
+ */
+export interface AgentLoopDetailedResult {
+    readonly messages: AgentMessage[];
+    readonly telemetry: AgentRunSummary | undefined;
+    readonly coverage: AgentRunCoverage | undefined;
+}
+/**
+ * Convenience wrapper over {@link agentLoop} that exposes the run-level
+ * summary + coverage alongside the messages. The returned `stream` is the
+ * same `EventStream` callers already consume; `detailed()` awaits the
+ * stream's `agent_end` event and returns the additive fields.
+ *
+ * Existing `stream.result()` semantics are preserved — it still resolves to
+ * `AgentMessage[]`. Use {@link agentLoopDetailed} when you need the rollup;
+ * use {@link agentLoop} when you do not.
+ */
+export declare function agentLoopDetailed(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): {
+    readonly stream: EventStream<AgentEvent, AgentMessage[]>;
+    readonly detailed: () => Promise<AgentLoopDetailedResult>;
+};
+/**
+ * Like {@link agentLoopDetailed} but built on top of
+ * {@link agentLoopContinue}.
+ */
+export declare function agentLoopContinueDetailed(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn): {
+    readonly stream: EventStream<AgentEvent, AgentMessage[]>;
+    readonly detailed: () => Promise<AgentLoopDetailedResult>;
+};
+export declare function normalizeMessagesForProvider(messages: Context["messages"], model: AgentLoopConfig["model"]): Context["messages"];
+export declare const INTENT_FIELD = "_i";
+export declare function normalizeTools(tools: AgentContext["tools"], injectIntent: boolean): Context["tools"];
+export {};