@inflexa-ai/harness 0.1.1

package/dist/lib/result.js

@@ -0,0 +1,103 @@
+/**
+ * neverthrow conventions for cortex.
+ *
+ * The agent loop and execution boundary model failure as values, not throws.
+ * The house rules:
+ *
+ *  1. `try/catch` lives ONLY inside the thin wrappers at calls to code
+ *     external to ours — a third-party SDK, the `pg` driver, `fs`, the DBOS
+ *     runtime. Those wrappers turn a throw into an `err(DomainError)`.
+ *     Everything above them flows `Result` / `ResultAsync`.
+ *  2. Absence is NOT an error. A "not found" stays in the ok channel as a
+ *     data variant (`ok({ found: false })`), never an `err`. `err` is
+ *     reserved for what used to be `throw`n — an unexpected upstream failure.
+ *  3. A `Result` is unwrapped at exactly three edges, each speaking its own
+ *     dialect of failure:
+ *       - HTTP routes `.match(...)` a `Result` into a response.
+ *       - The DBOS step boundary throws on `err` (`unwrapOrThrow` /
+ *         `resultStep` in `loop/run-step.ts`): durability records a step as
+ *         failed — and retries / fails fast — ONLY on a thrown exception, so
+ *         an `err` crossing `DBOS.runStep` MUST become a throw.
+ *       - Tool dispatch maps `err` into an `is_error` `tool_result`
+ *         (`loop/run-agent.ts`).
+ *
+ * Control-flow exceptions (DBOS cancellation, `AbortError`) are NOT failures
+ * and live OUTSIDE the `Result` error channel — they are thrown verbatim and
+ * must never be captured as an `err`.
+ *
+ * Sites import `ok`/`err`/`Result`/`ResultAsync`/`fromPromise`/`fromThrowable`
+ * directly from `neverthrow`; this module owns only the cortex-specific glue.
+ */
+import { Err, Ok } from "neverthrow";
+/**
+ * A thrown wrapper for a structured error value that is not already an
+ * `Error`. The original value rides on `.cause`, so the cause-walking
+ * classifiers (`classifyProviderError`, `isBudgetExceeded`) still reach the
+ * `status` / `code` signals they look for after a `Result` is rethrown at a
+ * boundary.
+ */
+export class ResultError extends Error {
+    value;
+    constructor(value) {
+        super(describe(value), { cause: value });
+        this.value = value;
+        this.name = "ResultError";
+    }
+}
+function describe(value) {
+    if (value instanceof Error)
+        return value.message;
+    if (value && typeof value === "object" && "type" in value) {
+        // Prefer a human `message` field when the structured error carries one
+        // (e.g. a `ProviderError`) so the wrapped `Error.message` stays
+        // pattern-matchable (`isBudgetExceeded`'s message backstop); fall back
+        // to the `type` discriminant otherwise.
+        const message = value.message;
+        if (typeof message === "string" && message.length > 0)
+            return message;
+        return String(value.type);
+    }
+    return String(value);
+}
+/**
+ * Bridge a `Result` error value into a thrown `Error` at a boundary that
+ * speaks exceptions. An error that is already an `Error` is thrown verbatim
+ * (its class, `.cause`, and any `status` survive); anything else is wrapped
+ * in `ResultError` with the structured value on `.cause`.
+ */
+export function toThrowable(value) {
+    return value instanceof Error ? value : new ResultError(value);
+}
+/**
+ * Unwrap a `Result`, throwing on `err`. The canonical Result→throw bridge for
+ * the DBOS step edge and any other boundary whose failure protocol is an
+ * exception (a driver's throw-to-rollback). The throw is isolated here so the
+ * rest of the code stays Result-shaped.
+ *
+ * Use it ONLY where a throw is the boundary's failure contract:
+ *
+ *  - **DBOS workflow/step bodies** (directly, or composed via `resultStep` in
+ *    `loop/run-step.ts`). DBOS records a step as failed — and retries / fails
+ *    fast — only on a thrown exception; a *returned* `err` would be durably
+ *    cached as a successful step output and replayed as success forever.
+ *  - **Tool `execute` bodies**, where the loop's dispatch catch maps the
+ *    throw into a model-visible error tool result (`loop/run-agent.ts`).
+ *  - **Driver edges whose protocol is a throw** (e.g. throw-to-rollback).
+ *
+ * Anywhere else, keep the `Result` flowing: return it, chain
+ * `.andThen`/`.map`/`.mapErr`, or `.match` both branches. Never reach for
+ * this to dodge error handling in composable domain logic.
+ *
+ * The `must-use-result` lint rule recognizes `unwrapOrThrow(...)` as
+ * consuming its Result (see the plugin patch in `eslint.config.js`) — do not
+ * rewrite call sites into inline `.match`+throw forms to appease lint.
+ */
+export function unwrapOrThrow(result) {
+    if (result.isErr())
+        throw toThrowable(result.error);
+    return result.value;
+}
+/** Runtime brand check — is this value a neverthrow `Result`? */
+export function isResult(value) {
+    return value instanceof Ok || value instanceof Err;
+}

package/dist/lib/storage.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Application `pg.Pool` construction.
+ *
+ * One `pg.Pool` backs every Cortex query — Cortex tables, the per-analysis
+ * pgvector indexes, route handlers, and durable-workflow steps all share the
+ * same pool so connection budgets stay predictable. The pool is built once at
+ * the composition root and threaded as a constructor dep (see the harness-durable-runtime spec).
+ */
+import { type Pool } from "pg";
+/**
+ * Narrow config slice the app pool reads — the six `DB_PG_*` connection
+ * fields plus the optional pool-size override. Composition roots map their
+ * validated `Env` onto this; the harness never reaches for an env loader.
+ */
+export interface PoolConfig {
+    readonly host: string;
+    readonly port: string;
+    readonly database: string;
+    readonly user: string;
+    readonly password: string;
+    readonly sslMode: "disable" | "require" | "verify-ca" | "verify-full";
+    readonly poolMax?: string;
+}
+/**
+ * Construct the application `pg.Pool`. Called exactly once, at the process
+ * composition root (`server.ts:main()`), and threaded as a constructor dep
+ * from there. No module reaches for the pool ambiently (see the harness-durable-runtime spec).
+ */
+export declare function createPool(config: PoolConfig): Pool;

package/dist/lib/storage.js

@@ -0,0 +1,37 @@
+/**
+ * Application `pg.Pool` construction.
+ *
+ * One `pg.Pool` backs every Cortex query — Cortex tables, the per-analysis
+ * pgvector indexes, route handlers, and durable-workflow steps all share the
+ * same pool so connection budgets stay predictable. The pool is built once at
+ * the composition root and threaded as a constructor dep (see the harness-durable-runtime spec).
+ */
+import pg from "pg";
+import { resolveAppPoolSize } from "../runtime/pools.js";
+function poolOptions(config) {
+    return {
+        host: config.host,
+        port: parseInt(config.port, 10),
+        database: config.database,
+        user: config.user,
+        password: config.password,
+        // Per-pod app pool; DBOS owns its system-DB connections separately
+        // (see the postgres-storage-backend spec). The boot guard checks this fits `max_connections`.
+        max: resolveAppPoolSize(config.poolMax),
+        // `pg` accepts `ssl: false` to disable entirely, or an object with
+        // `rejectUnauthorized` to tune TLS. We map sslmode to those forms.
+        ssl: config.sslMode === "disable"
+            ? false
+            : config.sslMode === "verify-full" || config.sslMode === "verify-ca"
+                ? { rejectUnauthorized: true }
+                : { rejectUnauthorized: false },
+    };
+}
+/**
+ * Construct the application `pg.Pool`. Called exactly once, at the process
+ * composition root (`server.ts:main()`), and threaded as a constructor dep
+ * from there. No module reaches for the pool ambiently (see the harness-durable-runtime spec).
+ */
+export function createPool(config) {
+    return new pg.Pool(poolOptions(config));
+}

package/dist/lib/streamed-download.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Streaming HTTP download helper with optional ranged-GET parallelism.
+ *
+ * Per-stream working memory is bounded at ~64 KiB regardless of file size —
+ * bodies are never materialized as Buffers. When the caller supplies the
+ * total size and it exceeds `partSize`, the download is split into N ranged
+ * GETs that write into a pre-allocated file at their respective offsets.
+ */
+export interface StreamDownloadOpts {
+    /** Total file size. Required for ranged-parallel downloads. */
+    size?: number;
+    /** Bytes per range. Falls back to single-GET when size <= partSize. */
+    partSize?: number;
+    /** Max ranges in flight. */
+    concurrency?: number;
+    /** Max retries per range or per whole-file stream. */
+    maxRetries?: number;
+    /** Abort signal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Download a URL to `destPath`, streaming the body to disk.
+ *
+ * Creates the destination file (truncating any existing content). On success
+ * the file exists at `destPath`; on failure it may be partially written —
+ * callers should use a temp path + rename pattern if atomicity matters.
+ */
+export declare function streamDownload(url: string, destPath: string, opts?: StreamDownloadOpts): Promise<void>;

package/dist/lib/streamed-download.js

@@ -0,0 +1,111 @@
+/**
+ * Streaming HTTP download helper with optional ranged-GET parallelism.
+ *
+ * Per-stream working memory is bounded at ~64 KiB regardless of file size —
+ * bodies are never materialized as Buffers. When the caller supplies the
+ * total size and it exceeds `partSize`, the download is split into N ranged
+ * GETs that write into a pre-allocated file at their respective offsets.
+ */
+import { createWriteStream } from "node:fs";
+import { open as fsOpen } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { mapConcurrent, sleep } from "./async-utils.js";
+const DEFAULT_PART_SIZE = 32 * 1024 * 1024; // 32 MiB
+const DEFAULT_CONCURRENCY = 4;
+const DEFAULT_MAX_RETRIES = 3;
+const BASE_DELAY_MS = 500;
+/**
+ * Download a URL to `destPath`, streaming the body to disk.
+ *
+ * Creates the destination file (truncating any existing content). On success
+ * the file exists at `destPath`; on failure it may be partially written —
+ * callers should use a temp path + rename pattern if atomicity matters.
+ */
+export async function streamDownload(url, destPath, opts = {}) {
+    const size = opts.size;
+    const partSize = opts.partSize ?? DEFAULT_PART_SIZE;
+    const concurrency = opts.concurrency ?? DEFAULT_CONCURRENCY;
+    const maxRetries = opts.maxRetries ?? DEFAULT_MAX_RETRIES;
+    if (!size || size <= partSize) {
+        await fetchStreamToFile(url, destPath, "w", undefined, maxRetries, opts.signal);
+        return;
+    }
+    // Pre-allocate the file so per-range streams can write at correct offsets.
+    const fh = await fsOpen(destPath, "w");
+    try {
+        await fh.truncate(size);
+    }
+    finally {
+        await fh.close();
+    }
+    const totalParts = Math.ceil(size / partSize);
+    await mapConcurrent(Array.from({ length: totalParts }, (_, i) => i), concurrency, async (i) => {
+        const start = i * partSize;
+        const end = Math.min(start + partSize, size) - 1;
+        await fetchRangeToFile(url, destPath, start, end, maxRetries, opts.signal);
+    });
+}
+async function fetchStreamToFile(url, destPath, flags, start, maxRetries, signal) {
+    let lastError = "";
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        try {
+            const res = await fetch(url, { signal });
+            if (!res.ok) {
+                lastError = `HTTP ${res.status}`;
+                if (res.status >= 500 && attempt < maxRetries - 1) {
+                    await sleep(BASE_DELAY_MS * 2 ** attempt);
+                    continue;
+                }
+                throw new Error(lastError);
+            }
+            if (!res.body)
+                throw new Error("response body is null");
+            const writer = createWriteStream(destPath, start !== undefined ? { flags, start } : { flags });
+            await pipeline(Readable.fromWeb(res.body), writer);
+            return;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err.message : String(err);
+            if (attempt < maxRetries - 1) {
+                await sleep(BASE_DELAY_MS * 2 ** attempt);
+                continue;
+            }
+        }
+    }
+    throw new Error(`download failed after ${maxRetries} attempts: ${lastError}`);
+}
+async function fetchRangeToFile(url, destPath, start, end, maxRetries, signal) {
+    let lastError = "";
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        try {
+            const res = await fetch(url, {
+                headers: { Range: `bytes=${start}-${end}` },
+                signal,
+            });
+            // 206 is the expected success; 200 means the server ignored Range — treat
+            // as fatal since it would overwrite other ranges.
+            if (res.status !== 206) {
+                lastError = `HTTP ${res.status}`;
+                if (res.status >= 500 && attempt < maxRetries - 1) {
+                    await sleep(BASE_DELAY_MS * 2 ** attempt);
+                    continue;
+                }
+                throw new Error(res.status === 200 ? `server ignored Range header (HTTP 200) — parallel download would clobber` : lastError);
+            }
+            if (!res.body)
+                throw new Error("response body is null");
+            const writer = createWriteStream(destPath, { flags: "r+", start });
+            await pipeline(Readable.fromWeb(res.body), writer);
+            return;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err.message : String(err);
+            if (attempt < maxRetries - 1) {
+                await sleep(BASE_DELAY_MS * 2 ** attempt);
+                continue;
+            }
+        }
+    }
+    throw new Error(`range ${start}-${end} failed after ${maxRetries} attempts: ${lastError}`);
+}

package/dist/lib/trace-context.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Hono middleware for W3C Trace Context extraction.
+ *
+ * Hono's HTTP server is not auto-instrumented by OTEL (which patches Node's
+ * `http` module, not Hono's request handling). This middleware manually
+ * extracts the `traceparent` header from incoming requests, creates an OTEL
+ * server span, and wraps the handler in `context.with()` so the OtelBridge
+ * and any downstream code see the correct parent span via `context.active()`.
+ */
+import type { MiddlewareHandler } from "hono";
+export declare const traceContextMiddleware: MiddlewareHandler;

package/dist/lib/trace-context.js

@@ -0,0 +1,49 @@
+/**
+ * Hono middleware for W3C Trace Context extraction.
+ *
+ * Hono's HTTP server is not auto-instrumented by OTEL (which patches Node's
+ * `http` module, not Hono's request handling). This middleware manually
+ * extracts the `traceparent` header from incoming requests, creates an OTEL
+ * server span, and wraps the handler in `context.with()` so the OtelBridge
+ * and any downstream code see the correct parent span via `context.active()`.
+ */
+import { trace, context, propagation, SpanKind, SpanStatusCode } from "@opentelemetry/api";
+const tracer = trace.getTracer("cortex.http");
+/**
+ * Middleware that extracts W3C trace context from incoming HTTP headers and
+ * creates a server span. Must be registered before all other middleware so
+ * the OTEL context is available throughout the request lifecycle.
+ */
+const SKIP_TRACE_PATHS = new Set(["/healthz", "/readyz"]);
+export const traceContextMiddleware = async (c, next) => {
+    if (SKIP_TRACE_PATHS.has(c.req.path)) {
+        return next();
+    }
+    const carrier = {};
+    for (const [key, value] of c.req.raw.headers) {
+        carrier[key] = value;
+    }
+    const parentCtx = propagation.extract(context.active(), carrier);
+    const span = tracer.startSpan(`${c.req.method} ${c.req.path}`, {
+        kind: SpanKind.SERVER,
+        attributes: {
+            "http.method": c.req.method,
+            "http.target": c.req.path,
+        },
+    }, parentCtx);
+    const spanCtx = trace.setSpan(parentCtx, span);
+    try {
+        await context.with(spanCtx, () => next());
+        span.setAttribute("http.status_code", c.res.status);
+    }
+    catch (err) {
+        span.setStatus({ code: SpanStatusCode.ERROR });
+        if (err instanceof Error) {
+            span.recordException(err);
+        }
+        throw err;
+    }
+    finally {
+        span.end();
+    }
+};

package/dist/loop/__fixtures__/scripted-provider.d.ts

@@ -0,0 +1,31 @@
+import type { ChatResponse, ChatProvider, ChatRequest } from "../../providers/types.js";
+import type { AgentSession as Session } from "../../auth/types.js";
+export type TextBlock = {
+    type: "text";
+    text: string;
+};
+export type ThinkingBlock = {
+    type: "reasoning";
+    text: string;
+    providerOptions?: {
+        anthropic: {
+            signature: string;
+        };
+    };
+};
+export type ToolUseBlock = {
+    type: "tool-call";
+    toolCallId: string;
+    toolName: string;
+    input: unknown;
+};
+export type ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock;
+export declare function makeMessage(content: ContentBlock[], finishReason: ChatResponse["finishReason"] | "tool_use" | "end_turn" | "max_tokens" | "refusal"): ChatResponse;
+export declare function textBlock(text: string): TextBlock;
+export declare function thinkingBlock(thinking: string, signature: string): ThinkingBlock;
+export declare function toolUseBlock(id: string, name: string, input: unknown): ToolUseBlock;
+export interface ScriptedProvider extends ChatProvider {
+    readonly calls: ChatRequest[];
+    readonly sessions: Session[];
+}
+export declare function scriptedProvider(script: ChatResponse[] | ((callIndex: number, request: ChatRequest) => ChatResponse)): ScriptedProvider;

package/dist/loop/__fixtures__/scripted-provider.js

@@ -0,0 +1,57 @@
+import { okAsync } from "neverthrow";
+function mapFinishReason(finishReason) {
+    switch (finishReason) {
+        case "tool_use":
+            return "tool-calls";
+        case "end_turn":
+            return "stop";
+        case "max_tokens":
+            return "length";
+        case "refusal":
+            return "content-filter";
+        default:
+            return finishReason;
+    }
+}
+export function makeMessage(content, finishReason) {
+    return {
+        message: { role: "assistant", content },
+        finishReason: mapFinishReason(finishReason),
+    };
+}
+export function textBlock(text) {
+    return { type: "text", text };
+}
+export function thinkingBlock(thinking, signature) {
+    return { type: "reasoning", text: thinking, providerOptions: { anthropic: { signature } } };
+}
+export function toolUseBlock(id, name, input) {
+    return { type: "tool-call", toolCallId: id, toolName: name, input };
+}
+export function scriptedProvider(script) {
+    const calls = [];
+    const sessions = [];
+    const reply = typeof script === "function"
+        ? script
+        : (i) => {
+            const r = script[i];
+            if (r === undefined) {
+                throw new Error(`scriptedProvider: no scripted reply for call ${i}`);
+            }
+            return r;
+        };
+    return {
+        capabilities: { toolCalling: true },
+        calls,
+        sessions,
+        chat(request, session) {
+            const i = calls.length;
+            calls.push(request);
+            sessions.push(session);
+            return okAsync(reply(i, request));
+        },
+        chatStream() {
+            throw new Error("scriptedProvider: chatStream is not used by runAgent");
+        },
+    };
+}

package/dist/loop/budget-exceeded.d.ts

@@ -0,0 +1,22 @@
+/**
+ * HTTP 402 `budget_exceeded` classifier.
+ *
+ * Detects when an LLM call failed because the billing gateway reported the
+ * caller's budget was exhausted. This is NOT a transient error — retrying
+ * is wasteful because every subsequent call charged to the same budget will
+ * also fail until the user tops up.
+ *
+ * Classification order (first hit wins):
+ *   1. Structured `statusCode === 402` (or `status === 402`) on any
+ *      link of the cause chain. The gateway emits 402 exclusively for
+ *      `budget_exceeded`, so a structured 402 is unambiguous.
+ *   2. Pattern fallback: `/budget.?exceeded/i` on the stringified
+ *      top-level error message. Covers stringified throws and paths
+ *      where no `statusCode` is attached (ops scripts, sandbox-server
+ *      surfacing upstream billing errors as text).
+ *
+ * Returns `false` for all other errors. Safe to call with any value;
+ * non-Error inputs hit the stringified-pattern branch and return `false`
+ * unless the string happens to match.
+ */
+export declare function isBudgetExceeded(err: unknown): boolean;

package/dist/loop/budget-exceeded.js

@@ -0,0 +1,41 @@
+/**
+ * HTTP 402 `budget_exceeded` classifier.
+ *
+ * Detects when an LLM call failed because the billing gateway reported the
+ * caller's budget was exhausted. This is NOT a transient error — retrying
+ * is wasteful because every subsequent call charged to the same budget will
+ * also fail until the user tops up.
+ *
+ * Classification order (first hit wins):
+ *   1. Structured `statusCode === 402` (or `status === 402`) on any
+ *      link of the cause chain. The gateway emits 402 exclusively for
+ *      `budget_exceeded`, so a structured 402 is unambiguous.
+ *   2. Pattern fallback: `/budget.?exceeded/i` on the stringified
+ *      top-level error message. Covers stringified throws and paths
+ *      where no `statusCode` is attached (ops scripts, sandbox-server
+ *      surfacing upstream billing errors as text).
+ *
+ * Returns `false` for all other errors. Safe to call with any value;
+ * non-Error inputs hit the stringified-pattern branch and return `false`
+ * unless the string happens to match.
+ */
+const BUDGET_EXCEEDED_PATTERNS = [/budget.?exceeded/i];
+/** Max depth walked on the cause chain looking for a structured statusCode. */
+const MAX_CAUSE_HOPS = 5;
+function hasStatus402(err) {
+    let cursor = err;
+    for (let i = 0; i < MAX_CAUSE_HOPS && cursor; i++) {
+        const e = cursor;
+        const code = e.statusCode ?? e.status;
+        if (code === 402)
+            return true;
+        cursor = e.cause;
+    }
+    return false;
+}
+export function isBudgetExceeded(err) {
+    if (hasStatus402(err))
+        return true;
+    const msg = err instanceof Error ? err.message : String(err ?? "");
+    return BUDGET_EXCEEDED_PATTERNS.some((p) => p.test(msg));
+}

package/dist/loop/metrics.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Agent-loop OTel metrics → Middleware.io.
+ *
+ * Every `runAgent` completion records two signals:
+ *   - cortex.harness.agent.iterations — histogram of LLM iterations per run.
+ *     A creeping distribution is a leading indicator of prompt drift.
+ *   - cortex.harness.agent.cap_hits   — counter, incremented once per run
+ *     that exhausted `maxIterations` and took the forced wrap-up path.
+ *
+ * Instruments are created lazily on first use so the loop binds to whatever
+ * `MeterProvider` is registered globally at runtime (production: the OTLP
+ * exporter from `harness/lib/otel.ts`; tests: an in-memory reader).
+ */
+/** Record one completed `runAgent` invocation. */
+export declare function recordAgentRun(run: {
+    readonly agentId: string;
+    readonly iterations: number;
+    readonly cappedOut: boolean;
+}): void;
+/**
+ * Drop the memoized instruments so the next `recordAgentRun` rebinds to a
+ * freshly-registered `MeterProvider`. Test-only — production registers its
+ * provider once at startup.
+ */
+export declare function __resetMetricsForTest(): void;

package/dist/loop/metrics.js

@@ -0,0 +1,46 @@
+/**
+ * Agent-loop OTel metrics → Middleware.io.
+ *
+ * Every `runAgent` completion records two signals:
+ *   - cortex.harness.agent.iterations — histogram of LLM iterations per run.
+ *     A creeping distribution is a leading indicator of prompt drift.
+ *   - cortex.harness.agent.cap_hits   — counter, incremented once per run
+ *     that exhausted `maxIterations` and took the forced wrap-up path.
+ *
+ * Instruments are created lazily on first use so the loop binds to whatever
+ * `MeterProvider` is registered globally at runtime (production: the OTLP
+ * exporter from `harness/lib/otel.ts`; tests: an in-memory reader).
+ */
+import { metrics } from "@opentelemetry/api";
+let instruments;
+function getInstruments() {
+    if (instruments === undefined) {
+        const meter = metrics.getMeter("cortex.harness.loop");
+        instruments = {
+            iterations: meter.createHistogram("cortex.harness.agent.iterations", {
+                description: "LLM iterations executed per runAgent completion",
+                unit: "{iteration}",
+            }),
+            capHits: meter.createCounter("cortex.harness.agent.cap_hits", {
+                description: "runAgent completions that exhausted maxIterations and took the " + "forced tool-less wrap-up path",
+            }),
+        };
+    }
+    return instruments;
+}
+/** Record one completed `runAgent` invocation. */
+export function recordAgentRun(run) {
+    const { iterations, capHits } = getInstruments();
+    const attributes = { agent_id: run.agentId };
+    iterations.record(run.iterations, attributes);
+    if (run.cappedOut)
+        capHits.add(1, attributes);
+}
+/**
+ * Drop the memoized instruments so the next `recordAgentRun` rebinds to a
+ * freshly-registered `MeterProvider`. Test-only — production registers its
+ * provider once at startup.
+ */
+export function __resetMetricsForTest() {
+    instruments = undefined;
+}

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

@@ -0,0 +1,28 @@
+import { type FinishReason } from "ai";
+import type { AgentSession } from "../auth/types.js";
+import type { AgentChat } from "../providers/types.js";
+import type { AgentDefinition, EmitFn, LoopMessage, RunStep } from "./types.js";
+export interface AgentFinish {
+    readonly reason: FinishReason | "max_iterations";
+    readonly cappedOut: boolean;
+    readonly truncationRecoveries: number;
+}
+export interface RunAgentResult {
+    readonly messages: LoopMessage[];
+    readonly finish: AgentFinish;
+}
+export interface StepNameFormatter {
+    llm(iteration: number): string;
+    tool(toolName: string, toolUseId: string): string;
+}
+export declare const DEFAULT_STEP_NAME_FORMATTER: StepNameFormatter;
+export interface RunAgentOptions {
+    readonly provider: AgentChat;
+    readonly signal: AbortSignal;
+    readonly emit: EmitFn;
+    readonly runStep: RunStep;
+    readonly formatStepName?: StepNameFormatter;
+    readonly isFatalLoopError?: (err: unknown) => boolean;
+}
+export declare function runAgent(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: RunAgentOptions): Promise<RunAgentResult>;
+export declare function finalText(messages: readonly LoopMessage[]): string;