@namzu/sdk 52.3.0 → 52.5.0

package/dist/runtime/jobs/websocket-source.d.ts

@@ -0,0 +1,120 @@
+import type { Sandbox } from '../../types/sandbox/index.js';
+import type { MonitorWebSocketTarget } from '../../types/tool/index.js';
+import type { JobHost, JobSource } from './registry.js';
+/**
+ * A WebSocket as a monitor's source.
+ *
+ * A command's stdout is not the only thing worth watching: some services push
+ * their events (a CI run's log stream, a server's change feed) and offer no
+ * command that prints them. This module turns such a connection into the same
+ * thing a command is to the registry: a process-shaped object that writes
+ * lines on stdout, can be asked to stop, and ends. Everything after that (the
+ * 200 ms batches, the rationing, the expiry, the stop, the untrusted frame the
+ * model reads it in) is the registry's and is shared with commands unchanged.
+ *
+ * What is different is where it runs and what it can reach. A command runs
+ * where the registry's spawn puts it, inside a sandbox if there is one; this
+ * connection is opened by the HOST process, outside any sandbox. So the
+ * address is checked before anything is sent, a sandbox that isolates the
+ * network refuses it unless it has said the host is allowed, and the tool
+ * asks a person first (see `tools/builtins/monitor.ts`).
+ */
+/** The largest frame accepted; a bigger one ends the watch. Same as the reference. */
+export declare const WEBSOCKET_MAX_PAYLOAD_BYTES = 1048576;
+export declare const WEBSOCKET_HANDSHAKE_TIMEOUT_MS = 15000;
+/** After a polite close, how long a peer gets to answer before the socket is destroyed. */
+export declare const WEBSOCKET_CLOSE_GRACE_MS = 1000;
+export declare const WEBSOCKET_URL_MAX_CHARS = 2048;
+export declare const WEBSOCKET_PROTOCOLS_MAX = 16;
+/** Why a URL cannot be a monitor's source, or undefined when it can. */
+export declare function webSocketUrlProblem(raw: string): string | undefined;
+/** Why a subprotocol list is not valid, or undefined when it is. */
+export declare function webSocketProtocolsProblem(protocols: readonly string[]): string | undefined;
+/** What a record and an approval call this source: the URL as given, which can carry no credentials. */
+export declare function webSocketJobCommand(url: string): string;
+/** The address check refused, in words for the model. */
+export declare class WebSocketRefusedError extends Error {
+    constructor(message: string);
+}
+export interface WebSocketVetOptions {
+    /**
+     * How a name becomes addresses. Defaults to `node:dns`. For tests only, and
+     * never reachable from a tool argument: the hook belongs to whoever builds
+     * the tool (`createMonitorTool`).
+     */
+    readonly resolve?: (hostname: string) => Promise<readonly string[]>;
+    /**
+     * Allow addresses inside the host's own network. For tests only: a local
+     * server on 127.0.0.1 is the one honest reason to, and it is a decision the
+     * code that builds the tool makes, never the model.
+     */
+    readonly allowPrivateAddresses?: boolean;
+}
+/** The host name of a WebSocket URL as a resolver or an address check wants it. */
+export declare function webSocketHostname(raw: string): string;
+/**
+ * Resolve the host and refuse unless EVERY address is outside the host's own
+ * network; return the addresses that were checked.
+ *
+ * Refusal covers a name that does not resolve, one that resolves to nothing,
+ * and one with any private address among its answers: a name that answers both
+ * a public and a private address is a name an attacker controls, and a
+ * connection may pick either. Failing to resolve is a refusal and never a
+ * pass: an empty list satisfies "no private address found" and the connection
+ * that followed would resolve the name again against whatever answered.
+ */
+export declare function vetWebSocketTarget(raw: string, options?: WebSocketVetOptions): Promise<readonly {
+    readonly address: string;
+    readonly family: 4 | 6;
+}[]>;
+/**
+ * A `lookup` for the socket that answers with the addresses that were checked
+ * and nothing else.
+ *
+ * This is what closes the gap `web_fetch` documents: there the address is
+ * checked, then the platform `fetch` resolves the name AGAIN, so a name that
+ * answers publicly the first time and privately the second (DNS rebinding)
+ * gets through. Here the connection never asks DNS: it is handed the checked
+ * addresses, so there is no second answer to differ. The URL still names the
+ * host, so TLS keeps its SNI and its certificate check on the hostname and not
+ * on an address.
+ */
+export declare function pinnedLookup(addresses: readonly {
+    readonly address: string;
+    readonly family: 4 | 6;
+}[]): (_hostname: string, options: {
+    all?: boolean;
+    family?: number | string;
+} | undefined, callback: (error: NodeJS.ErrnoException | null, address: string | {
+    address: string;
+    family: number;
+}[], family?: number) => void) => void;
+/** `api.example.com` is that host; `.example.com` is the domain and its subdomains. */
+export declare function hostMatchesPolicy(hostname: string, allowedHosts: readonly string[]): boolean;
+/**
+ * Why a sandbox forbids this connection, or undefined when it does not.
+ *
+ * The connection is opened by the host process, outside the boundary, so a
+ * sandbox's network rules do not bind it. If a turn runs under a sandbox that
+ * isolates the network, letting the host connect would be a way out of that
+ * isolation, so it is refused unless the sandbox's live policy names the host.
+ * A sandbox that does not isolate the network says nothing about it, and the
+ * connection is allowed, subject to the address check and to review.
+ */
+export declare function webSocketSandboxRefusal(sandbox: Sandbox | undefined, hostname: string): string | undefined;
+export declare const webSocketRejectedNotice: (status: number) => string;
+export declare const webSocketErrorNotice: (message: string) => string;
+export declare const webSocketClosedNotice: (code: number, reason: string) => string;
+export declare const webSocketDroppedNotice: () => string;
+export interface WebSocketSourceOptions {
+    readonly target: MonitorWebSocketTarget;
+    readonly host: JobHost;
+}
+/**
+ * Open the connection and return it as a job's process.
+ *
+ * The socket library is loaded when the first monitor of this kind starts, so
+ * a session that never watches a WebSocket never pays for it.
+ */
+export declare function connectWebSocketSource(options: WebSocketSourceOptions): JobSource;
+//# sourceMappingURL=websocket-source.d.ts.map

package/dist/runtime/jobs/websocket-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-source.d.ts","sourceRoot":"","sources":["../../../src/runtime/jobs/websocket-source.ts"],"names":[],"mappings":"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"}

package/dist/runtime/jobs/websocket-source.js

@@ -0,0 +1,379 @@
+import { lookup as dnsLookup } from 'node:dns/promises';
+import { EventEmitter } from 'node:events';
+import { isIP } from 'node:net';
+import { isPrivateAddress } from '../../connector/web/guarded-fetch.js';
+import { isolationOf } from '../../sandbox/isolation.js';
+/**
+ * A WebSocket as a monitor's source.
+ *
+ * A command's stdout is not the only thing worth watching: some services push
+ * their events (a CI run's log stream, a server's change feed) and offer no
+ * command that prints them. This module turns such a connection into the same
+ * thing a command is to the registry: a process-shaped object that writes
+ * lines on stdout, can be asked to stop, and ends. Everything after that (the
+ * 200 ms batches, the rationing, the expiry, the stop, the untrusted frame the
+ * model reads it in) is the registry's and is shared with commands unchanged.
+ *
+ * What is different is where it runs and what it can reach. A command runs
+ * where the registry's spawn puts it, inside a sandbox if there is one; this
+ * connection is opened by the HOST process, outside any sandbox. So the
+ * address is checked before anything is sent, a sandbox that isolates the
+ * network refuses it unless it has said the host is allowed, and the tool
+ * asks a person first (see `tools/builtins/monitor.ts`).
+ */
+/** The largest frame accepted; a bigger one ends the watch. Same as the reference. */
+export const WEBSOCKET_MAX_PAYLOAD_BYTES = 1_048_576;
+export const WEBSOCKET_HANDSHAKE_TIMEOUT_MS = 15_000;
+/** After a polite close, how long a peer gets to answer before the socket is destroyed. */
+export const WEBSOCKET_CLOSE_GRACE_MS = 1000;
+export const WEBSOCKET_URL_MAX_CHARS = 2048;
+export const WEBSOCKET_PROTOCOLS_MAX = 16;
+/** Longest close reason relayed; the protocol allows 123 bytes. */
+const CLOSE_REASON_MAX_CHARS = 123;
+// ---------------------------------------------------------------------------
+// Input
+// ---------------------------------------------------------------------------
+/** RFC 6455 subprotocol names are RFC 2616 tokens: no separators, no controls. */
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/** Why a URL cannot be a monitor's source, or undefined when it can. */
+export function webSocketUrlProblem(raw) {
+    if (raw.length > WEBSOCKET_URL_MAX_CHARS) {
+        return `The URL is longer than ${WEBSOCKET_URL_MAX_CHARS} characters.`;
+    }
+    // ASCII without whitespace or controls: a model that wants a non-ASCII host
+    // writes it in punycode, and nothing here is left to the parser's leniency
+    // (it strips tabs and newlines silently).
+    if (!/^[\x21-\x7e]+$/.test(raw)) {
+        return 'The URL must be ASCII, with no spaces or control characters.';
+    }
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return 'That is not a URL.';
+    }
+    if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+        return 'The URL must start with ws:// or wss://.';
+    }
+    if (url.username !== '' || url.password !== '') {
+        return 'A URL with a user name or password is not opened.';
+    }
+    if (url.hash !== '')
+        return 'A WebSocket URL cannot have a fragment (#...).';
+    if (url.hostname === '')
+        return 'The URL has no host.';
+    return undefined;
+}
+/** Why a subprotocol list is not valid, or undefined when it is. */
+export function webSocketProtocolsProblem(protocols) {
+    if (protocols.length > WEBSOCKET_PROTOCOLS_MAX) {
+        return `At most ${WEBSOCKET_PROTOCOLS_MAX} subprotocols.`;
+    }
+    for (const protocol of protocols) {
+        if (!TOKEN.test(protocol))
+            return `"${protocol}" is not a valid subprotocol name.`;
+    }
+    if (new Set(protocols).size !== protocols.length)
+        return 'Subprotocol names must be unique.';
+    return undefined;
+}
+/** What a record and an approval call this source: the URL as given, which can carry no credentials. */
+export function webSocketJobCommand(url) {
+    return `websocket ${url}`;
+}
+// ---------------------------------------------------------------------------
+// Where it may connect
+// ---------------------------------------------------------------------------
+/** The address check refused, in words for the model. */
+export class WebSocketRefusedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WebSocketRefusedError';
+    }
+}
+/** The host name of a WebSocket URL as a resolver or an address check wants it. */
+export function webSocketHostname(raw) {
+    return new URL(raw).hostname.toLowerCase().replace(/^\[|\]$/g, '');
+}
+/**
+ * Resolve the host and refuse unless EVERY address is outside the host's own
+ * network; return the addresses that were checked.
+ *
+ * Refusal covers a name that does not resolve, one that resolves to nothing,
+ * and one with any private address among its answers: a name that answers both
+ * a public and a private address is a name an attacker controls, and a
+ * connection may pick either. Failing to resolve is a refusal and never a
+ * pass: an empty list satisfies "no private address found" and the connection
+ * that followed would resolve the name again against whatever answered.
+ */
+export async function vetWebSocketTarget(raw, options = {}) {
+    const hostname = webSocketHostname(raw);
+    let addresses;
+    const literal = isIP(hostname);
+    if (literal !== 0) {
+        addresses = [hostname];
+    }
+    else {
+        const resolve = options.resolve ??
+            (async (name) => (await dnsLookup(name, { all: true })).map((r) => r.address));
+        try {
+            addresses = await resolve(hostname);
+        }
+        catch (err) {
+            throw new WebSocketRefusedError(`Refused "${hostname}": it could not be resolved (${err instanceof Error ? err.message : String(err)}), so nothing here can say where it points.`);
+        }
+        if (addresses.length === 0) {
+            throw new WebSocketRefusedError(`Refused "${hostname}": it resolves to no addresses.`);
+        }
+    }
+    if (options.allowPrivateAddresses !== true) {
+        for (const address of addresses) {
+            if (isPrivateAddress(address)) {
+                throw new WebSocketRefusedError(`Refused "${hostname}": it resolves to ${address}, inside this host's own network. A WebSocket monitor only connects to public addresses.`);
+            }
+        }
+    }
+    return addresses.map((address) => ({ address, family: isIP(address) === 6 ? 6 : 4 }));
+}
+/**
+ * A `lookup` for the socket that answers with the addresses that were checked
+ * and nothing else.
+ *
+ * This is what closes the gap `web_fetch` documents: there the address is
+ * checked, then the platform `fetch` resolves the name AGAIN, so a name that
+ * answers publicly the first time and privately the second (DNS rebinding)
+ * gets through. Here the connection never asks DNS: it is handed the checked
+ * addresses, so there is no second answer to differ. The URL still names the
+ * host, so TLS keeps its SNI and its certificate check on the hostname and not
+ * on an address.
+ */
+export function pinnedLookup(addresses) {
+    return (_hostname, options, callback) => {
+        // A caller that wants one family gets that family's addresses; asking for
+        // one we hold none of is an error rather than a fall back to DNS.
+        const wanted = options?.family === 4 || options?.family === 6 ? options.family : undefined;
+        const usable = wanted === undefined ? addresses : addresses.filter((a) => a.family === wanted);
+        const first = usable[0];
+        if (first === undefined) {
+            const error = new Error('no vetted address of that family');
+            error.code = 'ENOTFOUND';
+            callback(error, '', 0);
+            return;
+        }
+        if (options?.all === true) {
+            callback(null, usable.map((a) => ({ address: a.address, family: a.family })));
+            return;
+        }
+        callback(null, first.address, first.family);
+    };
+}
+/** `api.example.com` is that host; `.example.com` is the domain and its subdomains. */
+export function hostMatchesPolicy(hostname, allowedHosts) {
+    const host = hostname.toLowerCase().replace(/\.$/, '');
+    return allowedHosts.some((entry) => {
+        const allowed = entry.toLowerCase().replace(/\.$/, '');
+        if (allowed.startsWith('.'))
+            return host === allowed.slice(1) || host.endsWith(allowed);
+        return host === allowed;
+    });
+}
+/**
+ * Why a sandbox forbids this connection, or undefined when it does not.
+ *
+ * The connection is opened by the host process, outside the boundary, so a
+ * sandbox's network rules do not bind it. If a turn runs under a sandbox that
+ * isolates the network, letting the host connect would be a way out of that
+ * isolation, so it is refused unless the sandbox's live policy names the host.
+ * A sandbox that does not isolate the network says nothing about it, and the
+ * connection is allowed, subject to the address check and to review.
+ */
+export function webSocketSandboxRefusal(sandbox, hostname) {
+    if (sandbox === undefined)
+        return undefined;
+    if (!isolationOf(sandbox.environment).network)
+        return undefined;
+    const allowed = sandbox.networkPolicy?.allowedHosts;
+    if (allowed !== undefined && hostMatchesPolicy(hostname, allowed))
+        return undefined;
+    return `A WebSocket monitor connects from the host, outside this turn's sandbox, which blocks the network. "${hostname}" is not on the sandbox's list of allowed hosts, so the connection was not opened. Allow the host in the sandbox's network policy, or watch the service from inside the sandbox with a command.`;
+}
+// ---------------------------------------------------------------------------
+// Notices
+// ---------------------------------------------------------------------------
+/** Server-written text, made one short line before it goes into a notice. */
+function oneLine(text) {
+    const line = Array.from(text, (character) => {
+        const code = character.charCodeAt(0);
+        return code < 0x20 || (code >= 0x7f && code <= 0x9f) ? ' ' : character;
+    })
+        .join('')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return line.length <= CLOSE_REASON_MAX_CHARS
+        ? line
+        : `${line.slice(0, CLOSE_REASON_MAX_CHARS)}...`;
+}
+export const webSocketRejectedNotice = (status) => `[WebSocket upgrade rejected: HTTP ${status}]`;
+export const webSocketErrorNotice = (message) => `[WebSocket error: ${oneLine(message)}]`;
+export const webSocketClosedNotice = (code, reason) => {
+    const why = oneLine(reason);
+    return why === '' ? `[WebSocket closed: ${code}]` : `[WebSocket closed: ${code} ${why}]`;
+};
+export const webSocketDroppedNotice = () => `[Dropped a frame larger than ${WEBSOCKET_MAX_PAYLOAD_BYTES} bytes; closing]`;
+function frameBytes(data) {
+    if (Array.isArray(data))
+        return data.reduce((sum, part) => sum + part.length, 0);
+    return data instanceof ArrayBuffer ? data.byteLength : data.length;
+}
+/**
+ * Open the connection and return it as a job's process.
+ *
+ * The socket library is loaded when the first monitor of this kind starts, so
+ * a session that never watches a WebSocket never pays for it.
+ */
+export function connectWebSocketSource(options) {
+    const { target, host } = options;
+    const stand = Object.assign(new EventEmitter(), {
+        pid: undefined,
+        stdout: new EventEmitter(),
+        stderr: new EventEmitter(),
+    });
+    let socket;
+    let graceTimer;
+    // Set once somebody asked the connection to stop (a kill, the expiry, the
+    // output rule). From then on the connection says nothing: the registry has
+    // already told the model why the watch ended, and nothing follows that.
+    let stopping = false;
+    let opened = false;
+    let rejected = false;
+    let oversize = false;
+    // The connection failed before it opened: the error notice was the last word.
+    let failedToOpen = false;
+    let ended = false;
+    const write = (text) => {
+        if (stopping || ended)
+            return;
+        stand.stdout.emit('data', text);
+    };
+    const end = (exitCode) => {
+        if (ended)
+            return;
+        ended = true;
+        clearTimeout(graceTimer);
+        stand.emit('close', exitCode, null);
+    };
+    void import('ws')
+        .then(({ WebSocket }) => {
+        if (stopping) {
+            end(0);
+            return;
+        }
+        const client = new WebSocket(target.url, target.protocols && target.protocols.length > 0 ? [...target.protocols] : undefined, {
+            maxPayload: WEBSOCKET_MAX_PAYLOAD_BYTES,
+            // A redirect could lead to an address nobody checked.
+            followRedirects: false,
+            // A compressed frame inflates past the size cap before it is
+            // measured; refusing the extension leaves every frame as sent.
+            perMessageDeflate: false,
+            handshakeTimeout: WEBSOCKET_HANDSHAKE_TIMEOUT_MS,
+            // Only the vetted addresses; see `pinnedLookup`.
+            lookup: pinnedLookup(target.addresses),
+        });
+        socket = client;
+        client.on('open', () => {
+            opened = true;
+        });
+        client.on('unexpected-response', (_request, response) => {
+            if (stopping)
+                return;
+            rejected = true;
+            response.resume();
+            host.notice(webSocketRejectedNotice(response.statusCode ?? 0), { final: true });
+            // With a listener for this event the library leaves the half-open
+            // request to us.
+            client.terminate();
+        });
+        client.on('error', (error) => {
+            if (stopping || rejected || oversize)
+                return;
+            if (error.code === 'WS_ERR_UNSUPPORTED_MESSAGE_LENGTH') {
+                // The library knows a frame was too big and not how big: it stops
+                // reading at the length field.
+                oversize = true;
+                host.notice(webSocketDroppedNotice(), { final: true });
+                client.terminate();
+                return;
+            }
+            if (!opened) {
+                // It never opened, so there is no close to report after this:
+                // one notice says it failed, and it is the last.
+                failedToOpen = true;
+                host.notice(webSocketErrorNotice(error.message), { final: true });
+                return;
+            }
+            host.notice(webSocketErrorNotice(error.message));
+        });
+        client.on('message', (data, isBinary) => {
+            if (isBinary) {
+                write(`[binary frame, ${frameBytes(data)} bytes]\n`);
+                return;
+            }
+            const text = Array.isArray(data)
+                ? Buffer.concat(data).toString('utf8')
+                : Buffer.from(data).toString('utf8');
+            // Frames are not lines. A newline closes this one, so the next frame
+            // starts a fresh line and a frame without one is not glued to it.
+            write(text.endsWith('\n') ? text : `${text}\n`);
+        });
+        client.on('close', (code, reason) => {
+            const why = reason.toString('utf8');
+            if (!stopping && !rejected && !oversize && !failedToOpen) {
+                host.notice(webSocketClosedNotice(code, why), { final: true });
+                if (opened)
+                    host.connectionClosed(code, oneLine(why));
+            }
+            // A normal or going-away close is the stream ending; anything else,
+            // and a connection that never opened, is a failure.
+            end(opened && (code === 1000 || code === 1001 || code === 1005) ? 0 : 1);
+        });
+    })
+        .catch((error) => {
+        host.notice(webSocketErrorNotice(error instanceof Error ? error.message : String(error)), {
+            final: true,
+        });
+        end(1);
+    });
+    return {
+        child: stand,
+        // Not a process, so the registry's group kill has nothing to signal; this
+        // is how it is stopped. SIGTERM asks politely, SIGKILL (and the grace
+        // running out) destroys the socket.
+        kill(signal) {
+            if (ended)
+                return;
+            if (signal === 'SIGKILL') {
+                stopping = true;
+                if (socket)
+                    socket.terminate();
+                else
+                    end(0);
+                return;
+            }
+            if (stopping)
+                return;
+            stopping = true;
+            if (!socket)
+                return; // the import resolves, sees `stopping`, and ends
+            if (socket.readyState === socket.OPEN) {
+                socket.close(1000);
+                graceTimer = setTimeout(() => socket?.terminate(), WEBSOCKET_CLOSE_GRACE_MS);
+                graceTimer.unref?.();
+            }
+            else {
+                socket.terminate();
+            }
+        },
+    };
+}
+//# sourceMappingURL=websocket-source.js.map

package/dist/runtime/jobs/websocket-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket-source.js","sourceRoot":"","sources":["../../../src/runtime/jobs/websocket-source.ts"],"names":[],"mappings":"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"}

package/dist/runtime/query/auto-review/classifier.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The auto-review classifier: a model that reads one proposed action in the
+ * light of the conversation and says whether it may run.
+ *
+ * It backs the `classify` review mode. The mode decides WHICH calls are put to
+ * it (see `review-policy.ts`); this decides what happens to one. Four things
+ * are non-negotiable, and each has a test:
+ *
+ * - **Two passes.** A short pass (at most 64 output tokens) answers block or
+ *   allow. Allow ends it. Block goes to a longer pass (at most 8192) that may
+ *   reason about the person's authority, and its verdict stands.
+ * - **Fail closed.** A provider error, an unreadable answer, or running out of
+ *   retries blocks the call. There is no path from "could not check" to "run".
+ * - **No tool results.** The transcript it reads holds what the person and the
+ *   agent said and what the agent asked tools to do, never what they returned.
+ * - **Counting.** Blocks are counted so a host can stop a session that keeps
+ *   hitting them: after a run of consecutive blocks, or a total, the decision
+ *   carries `limitReached` and the host chooses what to do. The classifier
+ *   never changes a mode.
+ */
+import type { ToolManager } from '../../../toolsets/manager.js';
+import type { TokenUsage } from '../../../types/common/index.js';
+import type { ToolCallSummary } from '../../../types/hitl/index.js';
+import { type Message } from '../../../types/message/index.js';
+import type { LLMProvider } from '../../../types/provider/interface.js';
+import { type BackoffPolicy } from '../../../utils/backoff.js';
+import { type Logger } from '../../../utils/logger.js';
+import { type AutoReviewRules } from './rules.js';
+/** Which pass produced a decision. `0` means neither ran. */
+export type AutoReviewStage = 0 | 1 | 2;
+/** What one review came to. */
+export type AutoReviewDecision = {
+    readonly verdict: 'allow';
+    readonly stage: 1 | 2;
+    readonly latencyMs: number;
+} | {
+    readonly verdict: 'block';
+    /**
+     * `rule`: the classifier judged it unsafe. `unavailable`: the check could
+     * not be completed. `unreadable`: the answer was not a verdict.
+     * `aborted`: the turn was cancelled while it ran.
+     */
+    readonly cause: 'rule' | 'unavailable' | 'unreadable' | 'aborted';
+    readonly stage: AutoReviewStage;
+    /** One plain sentence, fit to show the person and to tell the model. */
+    readonly reason: string;
+    /** The rule the classifier named, when it named one. */
+    readonly rule?: string;
+    readonly latencyMs: number;
+    /**
+     * Set on the block that brought the counters to a limit. They are reset
+     * as this is returned; what to do about it is the host's decision.
+     */
+    readonly limitReached?: 'consecutive' | 'total';
+} | {
+    /**
+     * The conversation is too long for the check to read. Nothing was
+     * judged; the host should compact and try again.
+     */
+    readonly verdict: 'too_long';
+};
+/** One action to be reviewed. */
+export interface AutoReviewRequest {
+    /** The call under review. Its id is left out of the transcript so it is not shown twice. */
+    readonly call: Pick<ToolCallSummary, 'id' | 'name' | 'input'>;
+    /** The conversation so far. Tool results in it are ignored. */
+    readonly transcript: readonly Message[];
+    /** Where tool definitions are read for `classifierInput`. */
+    readonly tools?: Pick<ToolManager, 'get'>;
+    readonly signal?: AbortSignal;
+}
+/** How many blocks the classifier tolerates before it tells the host to step in. */
+export interface AutoReviewLimits {
+    /** Blocks in a row. Default 3. */
+    readonly consecutive?: number;
+    /** Blocks over the whole session, until a limit is reported. Default 20. */
+    readonly total?: number;
+}
+export interface AutoReviewClassifierOptions {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    /** Additions to, or replacements of, the built-in rule lists. */
+    readonly rules?: AutoReviewRules;
+    readonly log?: Logger;
+    /** Told what each pass cost, so a host can charge it to the session. */
+    readonly onUsage?: (usage: TokenUsage, stage: 1 | 2) => void;
+    readonly limits?: AutoReviewLimits;
+    /**
+     * The longest rendered transcript, in characters, that is sent. Longer is
+     * reported as `too_long`. Default 400 000 (roughly 100 000 tokens).
+     */
+    readonly maxTranscriptChars?: number;
+    /** The most characters one transcript entry keeps. Default 2000. */
+    readonly maxEntryChars?: number;
+    /** Retries after a failed provider call. Default 2. */
+    readonly maxRetries?: number;
+    /** The wait before a retry. Default 2 s doubling to 10 s, with some jitter. */
+    readonly retryDelay?: BackoffPolicy;
+    /** How long the first pass may take. Default 60 s. */
+    readonly quickDeadlineMs?: number;
+    /** How long the second pass may take. Default 120 s. */
+    readonly reasonedDeadlineMs?: number;
+    /** Sampling temperature. Default 0. */
+    readonly temperature?: number;
+    /** The wait between retries; replaced by tests so they never wait for real. */
+    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Jitter source for the retry delay. */
+    readonly random?: () => number;
+    /** Clock for latency. */
+    readonly now?: () => number;
+}
+export interface AutoReviewClassifier {
+    /** Reviews one action. Never throws for a provider failure: that is a block. */
+    review(request: AutoReviewRequest): Promise<AutoReviewDecision>;
+    /** The block counters right now. */
+    readonly denials: {
+        readonly consecutive: number;
+        readonly total: number;
+    };
+    /** Zeroes the block counters. */
+    reset(): void;
+}
+export declare const DEFAULT_AUTO_REVIEW_LIMITS: {
+    readonly consecutive: 3;
+    readonly total: 20;
+};
+/** The words the model is told when a call is blocked. */
+export declare function autoReviewBlockedFeedback(reason: string): string;
+export declare function createAutoReviewClassifier(options: AutoReviewClassifierOptions): AutoReviewClassifier;
+//# sourceMappingURL=classifier.d.ts.map