@outcrawl/sdk 0.1.0

package/dist/types/_deps/core/types.d.ts

@@ -0,0 +1,1677 @@
+/**
+ * Outcrawl wire contract.
+ *
+ * Every surface — SDK, REST API, MCP, CLI — speaks these shapes. The API is the
+ * truth; the other three are transports. See `registry.ts` for the capability
+ * list they are all generated or checked against.
+ *
+ * Three rules from the product surface spec are enforced *by omission* here,
+ * and all three are load-bearing:
+ *
+ *   1. The caller never chooses identity, seed, fingerprint, timezone,
+ *      languages or webrtcIp. We mint them. Anything configurable is
+ *      eventually configured wrong, and an incoherent identity is what gets
+ *      caught — not any single value.
+ *   2. The caller never *sees* identity either. `Profile` and `SessionQuery`
+ *      deliberately have no `identity` field. Customers see outcomes; we see
+ *      which identity produced them.
+ *   3. The caller never chooses a model, and never learns which one ran.
+ *      `AgentRequest` has no `model` field: it names a harness — `scout-1` or
+ *      `voyager-1`, see `agent-alias.ts` — and which models that harness runs,
+ *      including on a mid-run failover, is ours. A published per-minute price
+ *      and a caller-chosen model cannot coexist; measured on one real
+ *      production run the cheapest and dearest credible drivers differ by 126x,
+ *      and whoever picks absorbs that. So the caller picks the capability. No
+ *      response type, no usage row, no cache reason and no error message in
+ *      this file carries a model id.
+ */
+import { type AgentAlias } from './agent-alias.js';
+/**
+ * Which browser an execution presents as. Minted by us at
+ * `Target.createBrowserContext`, pinned for the life of a profile, and NEVER
+ * exposed to customers — it appears in no request and no response type in this
+ * file. Operator-side only.
+ */
+export type Identity = 'chrome' | 'brave';
+/**
+ * Proxy targeting is country/region/city ONLY. No ASN, no ZIP, no ISP —
+ * geography is a legitimate product choice, the rest is a way to build an
+ * identity that cannot exist.
+ */
+export interface ExitTarget {
+    country: string;
+    region?: string;
+    city?: string;
+}
+/**
+ * A concrete exit, resolved at session open. Session-scoped, not
+ * profile-scoped: a profile pins the city, the IP rotates underneath it.
+ */
+export interface ResolvedExit {
+    ip: string;
+    country: string;
+    region: string;
+    city: string;
+    /** IANA zone, from the city table. Never client-supplied. */
+    timezone: string;
+    /** Single tag for chrome identity, e.g. "en-US". */
+    languages: string;
+    lat: number;
+    lon: number;
+}
+/**
+ * An exit may be named as a structured target or as a proxy URL of the form
+ * `outcrawl://<country>[/<region>[/<city>]]`, e.g. `outcrawl://us/texas/austin`.
+ */
+export type ExitSpec = ExitTarget | string;
+/**
+ * Counters, all integers. These are safe as `number`: token counts and
+ * millisecond timings sit well inside binary64's exact-integer range.
+ *
+ * The meter does not. `UsageEventRow.quantity` in `@outcrawl/persistence` is an
+ * exact decimal string, and a surface that aggregates usage_events into this
+ * shape is crossing string -> number. That direction is fine. **The reverse
+ * never is**: append the string the meter produced, never a number that has
+ * been through binary64 and back. Money and meters are not floats, and a
+ * rounding error found in a reconciliation months later is unattributable.
+ */
+export interface Usage {
+    inputTokens?: number;
+    outputTokens?: number;
+    reasoningTokens?: number;
+    cachedInputTokens?: number;
+    inferenceTimeMs?: number;
+    cache?: {
+        status: 'HIT' | 'MISS' | 'DISABLED';
+        reason?: string;
+    };
+}
+/** Resources that actually appear on the bill. Charged, not estimated. */
+export interface BilledResources {
+    browserMinutes: number;
+    bandwidthBytes: number;
+    /** Decimal string, e.g. "2.00". Never a float — money is not binary64. */
+    credits: string;
+}
+/** A JSON Schema object. Drives `json` extraction and agent success detection. */
+export type JsonSchema = {
+    readonly [key: string]: unknown;
+};
+/** ISO 8601 instant, e.g. "2026-08-29T11:04:00.000Z". */
+export type Timestamp = string;
+/**
+ * Frame-qualified node reference: `<frameOrdinal>-<backendNodeId>`.
+ *
+ * Backend node ids come from a per-renderer-process static map, and
+ * cross-origin iframes run in different renderer processes under Site
+ * Isolation, so a bare backendNodeId can collide across frames.
+ */
+export type NodeRef = `${number}-${number}`;
+/**
+ * The de facto vocabulary. `html` is post-transform, `rawHtml` is
+ * pre-transform, and `json` cascades — it needs markdown first. That ordering
+ * is why this is one pipeline and not five.
+ */
+export declare const SCRAPE_FORMATS: readonly ["markdown", "html", "rawHtml", "links", "screenshot", "screenshot@fullPage", "json", "changeTracking"];
+export type ScrapeFormat = (typeof SCRAPE_FORMATS)[number];
+export declare function isScrapeFormat(value: unknown): value is ScrapeFormat;
+export interface ScrapeRequest {
+    url: string;
+    /** Defaults to `['markdown']`. */
+    formats?: readonly ScrapeFormat[];
+    /** Defaults to true — strip nav, chrome and boilerplate. */
+    onlyMainContent?: boolean;
+    /** Required when `formats` includes `json`. */
+    schema?: JsonSchema;
+    /** Pinned identity and logged-in state. */
+    profile?: string;
+    /** Geography only. Ignored when `profile` is given — a profile pins its exit. */
+    exit?: ExitSpec;
+    /** Extra settle time after the content classifier fires, in milliseconds. */
+    waitFor?: number;
+    timeoutMs?: number;
+    /** Compared against a previous snapshot when `changeTracking` is requested. */
+    changeTrackingTag?: string;
+}
+/**
+ * How a captcha was resolved on a page.
+ *
+ * `abandoned` is the load-bearing value: the solve outran its budget, so the
+ * document in hand is the interstitial and NOT the page. A caller that treats
+ * it as content is parsing a challenge screen. `not-attempted` means solving
+ * was deliberately never started because the request's own timeout could not
+ * accommodate one — buying a token and then discarding it is worse than not
+ * buying it.
+ */
+export type PageChallengeOutcome = 'solved' | 'unsolved' | 'not-attempted' | 'abandoned';
+export interface PageChallenge {
+    readonly outcome: PageChallengeOutcome;
+    /** Vendor as the browser named it, e.g. `recaptcha`. */
+    readonly detector: string;
+    readonly elapsedMs: number;
+    /** Solve budget this page reserved. 0 means solving was not armed. */
+    readonly budgetMs: number;
+}
+/**
+ * Whether this page was WATCHED for a challenge at all, which is what makes an
+ * absent {@link PageMetadata.challenge} interpretable.
+ *
+ * IT EXISTS BECAUSE THE ABSENCE WAS AMBIGUOUS AND SILENT. `challenge` is
+ * populated only from an armed solve window, and `@outcrawl/render`'s
+ * `unarmedWindow` settles `null` on purpose — with no policy in force the
+ * browser inspects nothing, so reporting a challenge would be inventing an
+ * observation. Correct, and it left every unwatched page indistinguishable
+ * from a page that genuinely had no captcha: HTTP 200, a full charge, the
+ * interstitial as `markdown`, and no field saying so.
+ *
+ * `PipelineTrace` already carried the numbers that resolve it and already
+ * argued the case — "without this number a page that was deliberately left
+ * unsolvable and a page that simply had no captcha are indistinguishable to an
+ * operator". That is the same ambiguity, and it was closed for an OPERATOR
+ * while the CUSTOMER kept it. This field is that fact on the surface the
+ * customer reads.
+ *
+ * `armed` — a solve window was open. An absent `challenge` then means there
+ * was no challenge, and that is a statement rather than a silence.
+ *
+ * `unarmed` — no window. Either this worker is not solving at all
+ * (`--challenge-mode=ignore`, or no provider key), or the request's own
+ * `timeoutMs` could not accommodate a solve. An absent `challenge` here means
+ * WE DO NOT KNOW, and a challenged page is exactly what it looks like.
+ *
+ * `refused` — a window was asked for and the browser declined the policy. Our
+ * fleet's fault rather than the caller's, distinguished from `unarmed` because
+ * "we chose not to look" and "we tried to look and could not" are different
+ * facts and only one of them is actionable by the customer.
+ */
+export type ChallengeWatch = 'armed' | 'unarmed' | 'refused';
+export interface PageMetadata {
+    title?: string;
+    description?: string;
+    /** Content language as declared by the page, not by us. */
+    language?: string;
+    contentType?: string;
+    scrapedAt: Timestamp;
+    /**
+     * True when the cheap stop-early path was not enough and the page was given
+     * time to run its scripts. Every request leaves through the browser's own
+     * network stack either way — the saving is in stopping early, never in
+     * skipping the browser.
+     */
+    escalated: boolean;
+    /**
+     * How a captcha on this page was resolved. Absent when none was OBSERVED,
+     * which is not the same as none having been raised — read
+     * {@link PageMetadata.challengeWatch} to tell those apart.
+     */
+    challenge?: PageChallenge;
+    /**
+     * Whether a challenge could have been observed on this page at all.
+     *
+     * **Required, with no `?`.** An optional field here would reintroduce the
+     * exact defect it closes: a consumer cannot tell an absent watch state from
+     * an unwatched page, and this repository has already shipped six seams whose
+     * omission was read as a decision.
+     */
+    challengeWatch: ChallengeWatch;
+}
+export type ChangeStatus = 'same' | 'changed' | 'new' | 'removed';
+export interface ChangeTracking {
+    status: ChangeStatus;
+    previousScrapedAt?: Timestamp;
+    /** Unified diff over the normalised DOM, present only when status is `changed`. */
+    diff?: string;
+    /** Model summary of the diff — the diff, never the whole page. */
+    summary?: string;
+}
+export interface ScrapeResult {
+    /** Final URL after redirects. */
+    url: string;
+    statusCode: number;
+    markdown?: string;
+    html?: string;
+    rawHtml?: string;
+    links?: string[];
+    /**
+     * The capture itself, base64 PNG, as `Page.captureScreenshot` returned it.
+     * Both `screenshot` and `screenshot@fullPage` land here.
+     *
+     * NOT A URL, and this comment said "Fetchable URL" until it was measured.
+     * Live `POST /v1/scrape` against prod on 2026-09-06 returned 610,368 bytes
+     * of PNG in this field — `89 50 4e 47`, 1200x841, 8-bit RGB — because
+     * `renderFormats` puts `PipelineDeps.screenshot`'s reply here unchanged and
+     * nothing between it and the wire uploads anything. A client that wrote
+     * `fetch(result.screenshot)` on the strength of the old sentence would send
+     * a 610 kB request line.
+     */
+    screenshot?: string;
+    /** Present when `json` was requested; shaped by the supplied schema. */
+    json?: unknown;
+    changeTracking?: ChangeTracking;
+    metadata: PageMetadata;
+    usage: Usage;
+}
+export interface CrawlRequest {
+    url: string;
+    /** Hard ceiling on pages fetched. */
+    limit?: number;
+    maxDepth?: number;
+    includePaths?: readonly string[];
+    excludePaths?: readonly string[];
+    allowSubdomains?: boolean;
+    allowExternalLinks?: boolean;
+    /** Skip sitemap.xml discovery and crawl the link graph only. */
+    ignoreSitemap?: boolean;
+    formats?: readonly ScrapeFormat[];
+    onlyMainContent?: boolean;
+    schema?: JsonSchema;
+    /** One warm context for the whole crawl: one coherent identity, not a thousand. */
+    profile?: string;
+    exit?: ExitSpec;
+    /** Delivered per page as the crawl streams; results are never batched. */
+    webhook?: string;
+}
+/** A crawled page: a scrape result plus its position in the frontier. */
+export interface CrawlPage extends ScrapeResult {
+    depth: number;
+    /** The page whose link graph produced this URL; absent for seeds and sitemap entries. */
+    discoveredFrom?: string;
+}
+export type JobStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
+/**
+ * One URL a crawl could not fetch. Produced by the scheduler in
+ * `@outcrawl/render`, which imports this rather than declaring its own — the
+ * producer owns the behaviour, core owns the wire shape.
+ */
+export interface CrawlFailure {
+    url: string;
+    depth: number;
+    message: string;
+}
+export interface CrawlJob {
+    id: string;
+    status: JobStatus;
+    url: string;
+    /** Pages completed so far. Crawls stream, so this moves. */
+    completed: number;
+    /** Pages currently known to the frontier — an estimate until the crawl ends. */
+    discovered: number;
+    createdAt: Timestamp;
+    /**
+     * Per-URL failures. Present and populated on runs that otherwise succeeded —
+     * a crawl that fetched 88 of 100 pages is a success with twelve failures, not
+     * a failed crawl, so an empty check here is not a success check.
+     *
+     * Declared because without it the information is simply lost at the wire: the
+     * scheduler collects the list, the closing frame is a `CrawlJob`, and a
+     * customer who hit twelve dead links would receive `completed: 88` with no
+     * way to learn which twelve.
+     */
+    failures?: readonly CrawlFailure[];
+    usage: Usage;
+}
+export interface SearchRequest {
+    query: string;
+    limit?: number;
+    /** Render every hit through our pipeline. Without it this is a pass-through. */
+    scrape?: boolean;
+    formats?: readonly ScrapeFormat[];
+    /** Two-letter country bias for the index. */
+    country?: string;
+    lang?: string;
+}
+export interface SearchHit {
+    url: string;
+    title: string;
+    snippet: string;
+    /** 1-based position in the result set. */
+    rank: number;
+    /** Populated only when `scrape` was requested. */
+    markdown?: string;
+    html?: string;
+    rawHtml?: string;
+    links?: string[];
+    json?: unknown;
+}
+export interface SearchResponse {
+    hits: SearchHit[];
+    usage: Usage;
+}
+export declare const NOTIFY_ADAPTERS: readonly ["discord", "slack", "webhook"];
+export type NotifyAdapter = (typeof NOTIFY_ADAPTERS)[number];
+export declare function isNotifyAdapter(value: unknown): value is NotifyAdapter;
+interface NotifyCommon {
+    /** Shapes the payload the adapter emits. Discord embed and Slack Block Kit otherwise. */
+    schema?: JsonSchema;
+}
+/**
+ * Exactly one adapter per monitor. A union rather than a bag of optionals, so
+ * a monitor that notifies nowhere cannot be constructed.
+ */
+export type MonitorNotify = (NotifyCommon & {
+    discord: string;
+}) | (NotifyCommon & {
+    slack: string;
+}) | (NotifyCommon & {
+    webhook: string;
+});
+/**
+ * Normalisation is where these products live or die. A monitor that fires on a
+ * rotating ad or a timestamp is worthless, so the defaults are deliberately
+ * lossy.
+ */
+export interface MonitorNormalisation {
+    /** Default true. */
+    stripTimestamps?: boolean;
+    /** Default true. CSRF tokens, cache-busters, build hashes. */
+    stripNonces?: boolean;
+    /** Default true. */
+    stripAds?: boolean;
+    /** Default true. */
+    stripSessionIds?: boolean;
+    /** Default true — sibling reordering is not a change. */
+    ignoreOrdering?: boolean;
+    /** Subtrees excluded from the diff entirely. */
+    ignoreSelectors?: readonly string[];
+}
+export interface MonitorSpec {
+    url: string;
+    /** Cron expression, e.g. "0 9 * * *". */
+    schedule: string;
+    notify: MonitorNotify;
+    /** Optional human label; the URL is the identity. */
+    label?: string;
+    formats?: readonly ScrapeFormat[];
+    profile?: string;
+    exit?: ExitSpec;
+    /** Run a model over the diff — the diff, not the page. Default false. */
+    judge?: boolean;
+    normalise?: MonitorNormalisation;
+    /** Default true. */
+    enabled?: boolean;
+}
+export interface Monitor extends MonitorSpec {
+    id: string;
+    createdAt: Timestamp;
+    lastCheckedAt?: Timestamp;
+    lastStatus?: ChangeStatus;
+}
+export interface MonitorCheck {
+    monitorId: string;
+    checkedAt: Timestamp;
+    status: ChangeStatus;
+    /** DOM tree diff, not a text diff. Present only when status is `changed`. */
+    diff?: string;
+    summary?: string;
+    /** The replay covering this check. */
+    replayUrl?: string;
+    usage: Usage;
+}
+export interface MonitorQuery {
+    url?: string;
+    /** Glob, e.g. "pricing-*". */
+    label?: string;
+    enabled?: boolean;
+    limit?: number;
+    cursor?: string;
+}
+export declare const CAP_NAMES: readonly ["steps", "budget", "duration"];
+export type CapName = (typeof CAP_NAMES)[number];
+/**
+ * Required on every agent run. The customer sets a ceiling before spending
+ * rather than disputing a bill afterwards, and since failures cost more than
+ * successes the same cap protects our margin.
+ */
+export interface AgentCaps {
+    /** Hard stop; the task then fails cleanly with partial data attached. */
+    steps: number;
+    /** Credits as a decimal string, e.g. "2.00". Not steps, not tokens. */
+    budget: string;
+    /**
+     * Wall clock: `<n>ms` | `<n>s` | `<n>m` | `<n>h`, e.g. "5m".
+     *
+     * **There is no ceiling above this and there is deliberately no longer one.**
+     * A run is a job rather than a held request, so nothing in the platform cuts
+     * it off at a number the caller did not choose: `caps` is the customer's dial
+     * and hours are normal. The `h` unit stopped being decorative on the day the
+     * job model landed.
+     *
+     * What used to live here was `MAX_RUN_DURATION_MS`, a 15-minute refusal that
+     * read as a product limit and was nothing of the kind — it was the edge's
+     * `AbortSignal.timeout` on one forwarded `fetch`, quoted back to customers as
+     * policy. Deleting the held request deleted the ceiling with it; it was never
+     * tuned, because there was nothing to tune.
+     */
+    duration: string;
+}
+export interface AgentRequest {
+    task: string;
+    /** Required, not optional. See `AgentCaps`. */
+    caps: AgentCaps;
+    /** Supplies identity and logged-in state. */
+    profile?: string;
+    /**
+     * When supplied, schema satisfaction *is* the success signal, and
+     * {@link AgentResult.data} comes back schema-shaped.
+     *
+     * Optional, and omitting it no longer costs you the answer: a schema-less run
+     * returns the agent's own closing summary in `data` instead. It is still the
+     * better input when you need named fields, because a schema is also what the
+     * run is judged and held against.
+     */
+    schema?: JsonSchema;
+    /**
+     * Which harness runs this task. Absent means {@link DEFAULT_AGENT_ALIAS}.
+     *
+     * Replaces a `model?: string` field that documented itself as "`'default'`
+     * for the model we host, or a BYOK model id" and was consulted by exactly one
+     * function, whose only behaviour was to refuse every value but `'default'`.
+     * BYOK was never implemented and there is no route for a customer credential
+     * to reach a worker, so the field's whole effect was to publish a choice
+     * nobody had.
+     *
+     * The two names are capabilities, not model tiers: `scout-1` does about an
+     * hour of work on the web; `voyager-1` reasons harder over hours or days. See
+     * `agent-alias.ts` for what each runs and why the caller is not told.
+     */
+    agent?: AgentAlias;
+    /**
+     * Where to POST this run's terminal event, so nothing has to poll.
+     *
+     * Held at the EDGE for the life of the run and never handed to the machine
+     * running it: a fleet Mac is the least-trusted tier in this system, and a
+     * customer's webhook URL is a credential — whoever holds it can post a
+     * convincing "your run finished" into whatever the customer built on top of
+     * it. `server/src/notify.ts` renders the body, the same builder monitors
+     * already use.
+     *
+     * The field predates the job model by months and was read by NOTHING: it
+     * documented itself as "async delivery; the call returns an id immediately"
+     * on a route that returned an `AgentResult` fifteen minutes later. It is real
+     * now.
+     */
+    webhook?: string;
+    /**
+     * How much to push, and optionally where.
+     *
+     * The level is the addition: {@link webhook} above says WHERE and has never
+     * said HOW MUCH, so the only thing it could ever deliver was the terminal
+     * outcome. `notify.level` is what turns one POST at the end into the run's
+     * log as it happens — `step` for what the agent did, `debug` for its
+     * reasoning too, `silent` for a run that must not push at all even though a
+     * webhook is configured.
+     *
+     * `notify.webhook` overrides {@link webhook} when both are present, being the
+     * more specific statement. Neither is forwarded to the machine running the
+     * run and neither is ever the machine's to deliver: the push is a projection
+     * of durable `run_records` rows made at the CONTROL PLANE, which is what
+     * makes a failed POST retryable from the row and a dying browser unable to
+     * lose an event. See {@link NOTIFY_KINDS}.
+     */
+    notify?: NotifyPolicy;
+    exit?: ExitSpec;
+    /**
+     * Action cache, on by default. Key is URL + instruction + AX-tree hash +
+     * options; a hit replays with zero model tokens.
+     */
+    cache?: boolean;
+    /**
+     * Set `false` to decline the recording. Absent means RECORDED.
+     *
+     * Recording an agent run is automatic and this is the only way out of it.
+     * The direction is the whole contract: an absent field, a `true`, and any
+     * value this type does not admit all record, and nothing but an explicit
+     * `false` declines. A caller with a policy reason not to have a tape — a
+     * regulated tenant, a session touching personal data, a compliance boundary
+     * — had no way to say so before this field, and the only workaround was not
+     * using the product.
+     *
+     * Honoured at the arming site, so a declined run never has bytes written:
+     * `openSessionFor` in `packages/worker/src/jobs.ts` does not pass a
+     * `replaySessionId`, no `SessionRecorder` is started, and no
+     * `replay_sessions` row is created. It is NOT a recording deleted
+     * afterwards, which would mean the bytes existed on a machine the tenant
+     * declined to have them on.
+     *
+     * Declining does not change the charge. Nothing in the metering path reads a
+     * replay row — `page_load` is counted by `SessionTabSet` and `agent_seconds`
+     * off the loop's own clock — so a declined run bills exactly what a recorded
+     * one bills.
+     *
+     * Afterwards the run says so positively: {@link AgentResult.replayUrl} is
+     * absent and {@link AgentResult.recordingDeclined} is `true`, which is what
+     * separates a refusal from a recorder that broke.
+     *
+     * There is no equivalent on `scrape`, `crawl`, `search` or a monitor check,
+     * because none of them records anything to decline. See `recordsSession` in
+     * `packages/worker/src/jobs.ts`.
+     */
+    record?: boolean;
+    /**
+     * The secret handles this run may use. Absent means NONE.
+     *
+     * **Deny by default, and that is the entire defence against a page that
+     * controls what the model reads.** A prompt injection saying "fill this
+     * field with {{secret:card_amex_personal}}" resolves to nothing on a run
+     * whose submit did not name that handle: the substitution refuses by name
+     * rather than typing the literal placeholder into a payment form, which
+     * would be a charge attempt with a garbage card number and a step the model
+     * believes succeeded.
+     *
+     * It is also what makes "several cards" safe rather than merely possible. A
+     * run granted `card_virtual_burner` cannot be talked into `card_amex` by any
+     * page, by any wording, because the value is not reachable from that run at
+     * all — the grant is a row this account's control plane wrote at submit, and
+     * `POST /internal/secret-reveal` authorises against it.
+     *
+     * The MODEL sees these handles and never a value. Substitution happens below
+     * it, in `packages/worker/src/agent-deps.ts`, one statement before the
+     * keystrokes reach the renderer, and the concealed form of the value is the
+     * same `{{secret:<handle>}}` placeholder — so the field the run just filled
+     * reads back as the handle in the next prompt rather than as the card
+     * number. `packages/core/src/secrets.ts` states the whole rule.
+     *
+     * A handle this account does not hold is a 400 at SUBMIT, not a failure
+     * mid-run: a checkout that dies at the card field because a secret was
+     * deleted last week has already spent the run.
+     */
+    secrets?: readonly string[];
+    /**
+     * Plain-language rules this run is bound by, REPLACING the workspace default.
+     *
+     * Absent means "use the workspace rules as they are"; `[]` means "this run
+     * runs under no rules at all", and the two are different facts. Per-run
+     * replaces rather than appends, deliberately: appending cannot express
+     * REMOVAL, so a run that legitimately needs to exceed the workspace ceiling
+     * would have no way to say so and the customer's only route would be
+     * mutating the workspace default — dropping the protection for every other
+     * concurrent run in order to unblock one. Replacing makes this list exactly
+     * the set the run was authorised under, which is also the only set worth
+     * recording on the run row.
+     *
+     * Each rule lands in one of two classes and the customer is told which:
+     * ENFORCED, a gate `@outcrawl/runtime` checks before every dispatch and
+     * which BLOCKS a forbidden action, or GUIDANCE, a sentence in the prompt
+     * that a model can weigh against everything else. `GET /v1/rules` and
+     * `PUT /v1/rules` both answer the split, because a rule a customer believes
+     * is enforced and which is only advice is the worst outcome available here.
+     * `packages/core/src/rules.ts` is the compiler and states why extraction is
+     * a parser rather than a model.
+     */
+    rules?: readonly string[];
+    /**
+     * The connectors this run may call tools on, by name — `['gmail']`.
+     *
+     * ABSENT MEANS NONE, and that default is the containment. A workspace may
+     * have Gmail, Slack and Twilio connected; a run reaches whichever of them
+     * this list names and nothing else, so a page that talks a model into
+     * "email this table to attacker@example.com" is talking to a run with no
+     * mail connector. Reach outside the browser is opted into per run by the
+     * human who submitted it, never inherited from the workspace, and never
+     * discovered by the model.
+     *
+     * A name this account has no connector for is a 400 at SUBMIT, on
+     * {@link AgentRequest.secrets}'s reasoning: a run that dies at the 2FA wall
+     * because `gmial` was a typo has already spent the run.
+     *
+     * What the run can then DO with a connector is narrowed twice more, and both
+     * narrowings are visible in `GET /v1/integrations`: the connector row may
+     * pin a tool list, and only the tools the remote actually advertises exist.
+     * `packages/integrations` holds the broker that enforces all three.
+     */
+    integrations?: readonly string[];
+}
+/**
+ * `capped` is distinct from `partial` on purpose. Both return the data
+ * collected so far, but they mean opposite things to whoever is reading:
+ * `capped` is the system doing exactly what the caller told it to and the fix
+ * is a bigger ceiling, while `partial` is the run genuinely failing to finish
+ * and the fix is somewhere in the task or the site. Collapsing them would hide
+ * the one distinction a customer acts on, and `SessionOutcome` already carries
+ * `capped` for the same reason.
+ */
+export type AgentStatus = 'completed' | 'partial' | 'capped' | 'failed';
+/**
+ * Why the run stopped. `max-*` are the caps firing; a capped run is a normal
+ * outcome, not an incident.
+ *
+ * `gave-up` is the MODEL's verdict and `error` is OURS, and they are separate
+ * members for the same reason {@link AgentStatus} keeps `capped` apart from
+ * `failed`: collapsing them hides the one distinction a customer acts on. A run
+ * that ends `gave-up` chose `{"type":"fail","reason":"..."}` — an action the
+ * agent loop advertises on every prompt — because the task could not be done on
+ * the page in front of it. A run that ends `error` hit something that went
+ * wrong on our side: a lost action-lock, a reference naming no node, a step
+ * that threw. One means look at the task, the other means look at us, and while
+ * they shared a string neither a dashboard nor a retry loop could tell which
+ * had happened — so a caller retried, forever, something that will never
+ * succeed.
+ *
+ * Neither is a status: {@link AgentStatus} still answers "did the caller get
+ * what they asked for" (`failed` with no data, `partial` with some), and this
+ * answers why not.
+ *
+ * `cancelled` and `irreversible` are the two that are neither ours nor the
+ * model's. `cancelled` is the CUSTOMER's: somebody called
+ * `POST /v1/agent/{id}/cancel` and the run settled where it stood. It is not
+ * `gave-up` (the model never said anything) and not `error` (nothing of ours
+ * broke), and a retry loop must be able to tell it from both — retrying a run
+ * a human just stopped is the one retry that is certainly wrong.
+ *
+ * `irreversible` is the HARNESS refusing rather than failing. A run is
+ * resumable until its first irreversible action — payment submitted, order
+ * placed, message sent, file handed to a third party, account created — and
+ * permanently un-resumable after it, because nothing can distinguish "the order
+ * went through and the confirmation page died with the browser" from "the order
+ * never went through". A resume past that point REPORTS what the run knew and
+ * does not act: no browser is opened, no step is dispatched, no credit is
+ * spent. Not `error` (nothing of ours broke) and not `gave-up` (the model never
+ * said anything) — the two it would otherwise be collapsed into, and a caller's
+ * retry loop must be able to tell "never retry this" from both.
+ */
+export type AgentStopReason = 'schema-satisfied' | 'task-complete' | 'max-steps' | 'max-budget' | 'max-duration' | 'loop-detected' | 'gave-up' | 'irreversible' | 'cancelled' | 'error';
+/** An action a page could take, resolved but not executed. Also the cache unit. */
+export interface ObservedAction {
+    ref: NodeRef;
+    description: string;
+    /** e.g. "click", "fill", "selectOption". */
+    method: string;
+    args?: readonly string[];
+    /** Heal path: survives a node being genuinely recreated, which the ref cannot. */
+    xpath: string;
+}
+export interface AgentStep {
+    /** 0-based. */
+    index: number;
+    action: ObservedAction;
+    /** The model's stated reason for the action, when the model produced one. */
+    reasoning?: string;
+    at: Timestamp;
+    /**
+     * The tab this step ran on, on a multi-tab run. Absent means single-tab.
+     *
+     * On the wire because two consumers outside the loop cannot do their job
+     * without it. A replay player has nothing else to tell tab B's mutations from
+     * tab A's — every tab's renderer claims main-frame ordinal 0, so an
+     * un-namespaced recording applies one tab's changes to another's tree and
+     * plays back a run that never happened. And a scorer reading these frames
+     * infers which origin a step acted on from the last URL it saw; once focus can
+     * move between tabs, that inference is wrong without this field, and wrong
+     * quietly, which is worse than absent.
+     */
+    tab?: string;
+    /**
+     * The sub-goal this step was working, on a run that stated a plan. Absent
+     * when the run has no plan, or for the steps before one was stated.
+     *
+     * On the wire for the reason `tab` above is: a consumer scoring a run's
+     * progress cannot attribute a step to an outcome without it, and the runtime
+     * recorded it on `StepTrace.goal` all along while this projection dropped it.
+     */
+    goal?: string;
+    usage: Usage;
+}
+/**
+ * A sub-goal of a run, and what became of it.
+ *
+ * On the wire because a five-part task is five completions and one report, and
+ * `status` carries only the report: a run that did four of five errands and a
+ * run that did one are both `partial`, and the difference is the thing the
+ * customer is paying for.
+ *
+ * It is also the only way anything outside the loop can measure long-horizon
+ * behaviour. The runtime held all of this on `AgentResult.goals` and
+ * `StepTrace.goal` and the projection dropped both, so a plan-driven run and a
+ * planless one were byte-identical on the wire — which meant the harness that
+ * exists to score long-horizon runs scored them the same, and an absence read
+ * off that output could not distinguish "no plan was stated" from "plans do not
+ * appear here". One such absence was reported as evidence during this work.
+ *
+ * Optional, and absent rather than `[]` when the run never stated a plan: an
+ * empty array reads as "asked and answered nothing", and absent reads as "this
+ * run had no plan", which is the true statement.
+ */
+export interface AgentGoal {
+    id: string;
+    goal: string;
+    /** Origin hint, when the plan named one. */
+    site?: string;
+    status: 'pending' | 'active' | 'done' | 'failed';
+    /** What closed it: the confirmation on `done`, the reason on `failed`. */
+    summary?: string;
+    /** The step it closed on. Absent while still open. */
+    closedAtStep?: number;
+}
+export interface AgentResult {
+    id: string;
+    /** Published success rates are 42–71%, so `partial` is normal, not an error. */
+    status: AgentStatus;
+    /**
+     * The run's answer. Partial results are returned, never discarded.
+     *
+     * WITH a schema this is schema-shaped, and a partially satisfied schema still
+     * comes back. WITHOUT one it is the agent's closing summary of what it found,
+     * so a question asked without a schema is still answered.
+     *
+     * OPTIONAL, and absence is not an error: it means the run had nothing to
+     * report — "click the unsubscribe link" asks no question — and such a run is
+     * still `completed`. Absent rather than `null` deliberately: `null` is a
+     * value a schema'd extraction can legitimately produce, and overloading it
+     * would make "the answer is null" and "there was no answer" the same reading.
+     *
+     * This field was declared required while the API shipped responses without
+     * it, because nothing populated it on a schema-less run and `JSON.stringify`
+     * erases an `undefined` value.
+     */
+    data?: unknown;
+    usage: Usage;
+    /**
+     * How long the run took, from the loop's own monotonic clock.
+     *
+     * **This is a billed quantity, and that is why it is on the wire.** Agent is
+     * sold at +5 credits per minute; the API meters `agent_seconds` from exactly
+     * this number, and billing a customer per minute while refusing to tell them
+     * the minutes is indefensible. It is also the reading `AgentCaps.duration`
+     * was enforced against, so a `capped` run with `stopReason: 'max-duration'`
+     * can be checked against the ceiling that stopped it.
+     *
+     * Not optional. `SessionSummary.durationMs` is required for the same reason,
+     * and this field existed on the runtime's own result all along —
+     * `toWireResult` simply dropped it, which is how the published per-minute
+     * price came to have no minute anywhere on the customer's side of the wire.
+     */
+    durationMs: number;
+    /**
+     * Watch exactly what the money bought. This is how a charge is disputed.
+     *
+     * OPTIONAL, and the absence is a statement rather than a gap: this run was
+     * not recorded anywhere durable. It was required until now and it lied —
+     * every agent run this product completed returned a link of the shape
+     * `https://outcrawl.ai/replay/r/<id>`, and `replay_sessions` held zero rows
+     * from the day the table was created, because a fleet Mac has no database
+     * credential and so bound an in-memory replay store that was freed when the
+     * process exited.
+     *
+     * A host that cannot honour a link now answers `null` from
+     * `ReplayStore.replayUrl` and this field is spread away — see
+     * `packages/worker/src/main.ts` `replayStore()`, whose memory branch says why
+     * refusing to BOOT over a missing replay credential would be an outage caused
+     * by replay. An absent field reads as "this run was not recorded"; a dead
+     * link reads as "your product is broken", and a customer chasing the second
+     * one opens a support ticket about our routing.
+     *
+     * `MonitorCheck.replayUrl` above has been optional since it was written, for
+     * exactly this reason and left deliberately unpopulated. That is the shape
+     * this codebase already chose once.
+     *
+     * PRESENT means a recording EXISTS, including one still sealing. The link is
+     * gated on `sessions.replay_key`, which is written the moment the recorder
+     * arms and never on `replay_sessions.state`, so a run whose bytes are still
+     * being flushed carries its url — that is what makes a live follow work.
+     * ABSENT therefore means no recording, and {@link recordingDeclined} is what
+     * says which of the two ways it came to have none.
+     */
+    replayUrl?: string;
+    /**
+     * The CALLER declined the recording, with `AgentRequest.record: false`.
+     *
+     * Present and `true` only on a refusal; absent otherwise. It exists because
+     * an absent {@link replayUrl} had two causes and no way to tell them apart:
+     * a tenant who refused a tape, and a recorder that was asked for one and
+     * could not deliver — a sink that declined, a browser that would not arm, a
+     * host booted with no replay credential. Those are a satisfied request and
+     * an incident, and a customer disputing a charge, an auditor checking a
+     * compliance boundary and an operator reading a session with no tape all
+     * need the difference. This repo has shipped that same silence before, where
+     * a `replayUrl` derived from the row id alone made "recorded" and "never
+     * recorded" identical on the wire.
+     *
+     * So the three states are: `replayUrl` present — there is a recording;
+     * `replayUrl` absent with this `true` — the caller refused one and no bytes
+     * were ever written; `replayUrl` absent with this field absent — one was
+     * wanted and not obtained, which is ours to fix.
+     *
+     * TYPED `true` AND NOT `boolean`. A `recordingDeclined: false` on the wire
+     * would be a claim about a decision on every result that ever returns, where
+     * the absence already says everything — the argument {@link replayUrl} makes
+     * for being spread rather than assigned. It also means the default cannot be
+     * spelled: there is no `false` to write, so nothing can express "declined
+     * unless told otherwise".
+     */
+    recordingDeclined?: true;
+    stepsUsed: number;
+    /**
+     * Navigations committed over the run. A billed quantity, metered as
+     * `page_load` at the same per-page rate a scrape pays.
+     *
+     * **Required, with no `?`.** The rate card sells agent minutes on top of the
+     * run's pages and browser time, and with no page count on this object the API
+     * metered a page residual of zero against runs that demonstrably navigated —
+     * the same defect `durationMs` above had, and an optional field would have
+     * reproduced it silently, because zero pages reads as a legal invoice rather
+     * than a missing one.
+     *
+     * Counted in `@outcrawl/runtime` from observed per-tab URL changes, so a click
+     * that navigates counts and switching back to an already-loaded tab does not.
+     * A revisit counts again: five sites with one revisit is six pages, which is
+     * the only reading that does not price a multi-site agent run below six
+     * scrapes of the same six pages.
+     */
+    pages: number;
+    stopReason: AgentStopReason;
+    /** The plan and its outcomes. Absent when the run never stated one. See {@link AgentGoal}. */
+    goals?: readonly AgentGoal[];
+    /** Present when status is `failed`. */
+    error?: string;
+}
+/**
+ * Where a run is, at the instant it was read.
+ *
+ * Exactly {@link AgentStatus} plus the three states a job has and a request
+ * never did. `queued` is accepted-and-not-yet-placed; `running` is on a
+ * machine; `paused` is on a machine and WAITING ON A HUMAN. Everything else is
+ * terminal and is the same vocabulary the finished result reports, so a poller
+ * and a webhook consumer read one union rather than two.
+ *
+ * **There is no `cancelled` here, deliberately.** A cancel is not an outcome:
+ * a run that had already found the answer when somebody stopped it is
+ * `completed` and its data is real. What a human asked for is
+ * {@link AgentRun.cancelRequestedAt} — an instant, written once — and why the
+ * run stopped is `stopReason: 'cancelled'`. Folding the request into the status
+ * would throw away a delivered answer to record a button press.
+ *
+ * **`paused` is ONE state for two doors, and it is not terminal.** A run parks
+ * either because a human took the wheel (`POST /v1/agent/{id}/control`) or
+ * because the agent asked a question (`ask`, answered by
+ * `POST /v1/agent/{id}/answer`), and which of the two it was lives on
+ * {@link AgentRun.pause} rather than in a second status: everything else about
+ * the state is identical, and a second status would double every predicate in
+ * the system in order to record which button was pressed. It is an OPEN state
+ * on the same terms as `queued` and `running` — no `endedAt`, no `stopReason`
+ * — because a park always has an exit: the answer, the handback, or the park's
+ * own deadline, after which the run resumes and is told nobody replied. A run
+ * cannot end `paused`, so no consumer needs to treat it as an outcome.
+ */
+export type AgentRunStatus = 'queued' | 'running' | 'paused' | AgentStatus;
+/**
+ * Whether this run can still do anything, as ONE predicate.
+ *
+ * It was spelled `status !== 'queued' && status !== 'running'` in three places
+ * — the event stream's `done` frame, the upload route's refusal, and the SDK's
+ * `settled()` poll — and every one of them means "has this run finished". A
+ * fourth state that three of those copies had never heard of is how a PARKED
+ * run comes to report `done: true` on its event stream, be refused an upload
+ * for having "ended", and settle an SDK poll with a run that is still waiting
+ * for the answer that poll was about to deliver.
+ *
+ * `paused` counts as OPEN, which is the whole reason this exists: a park is a
+ * run in the middle of its life, holding a warm browser, that is going to take
+ * more steps.
+ */
+export declare function isRunOpen(status: AgentRunStatus): boolean;
+/**
+ * What a run appended, and why.
+ *
+ * ONE log, one sequence space. `result` is the deliverable; the rest is how the
+ * run got there. They share a table and a `seq` because the alternative —
+ * results in one stream and progress in another — needs the two reconciled in
+ * front of a customer, and a step IS a record of what happened.
+ *
+ * `irreversible` is the one a resume reads: past it a run may report and may
+ * not act. See {@link AgentStopReason}. `question` is the one a PERSON reads:
+ * it is the whole discovery path for a parked run, which is why a question is
+ * a durable record rather than a field on the row — a customer who was not
+ * watching finds it in the same log they read for everything else, and it is
+ * pushed to their webhook by the same projection.
+ */
+export declare const AGENT_RECORD_KINDS: readonly ["result", "finding", "ruled-out", "goal", "step", "irreversible", "question"];
+export type AgentRecordKind = (typeof AGENT_RECORD_KINDS)[number];
+/**
+ * How much of the log a subscriber wants.
+ *
+ * Three levels and not a kind list, because the caller who wants "just tell me
+ * what is happening" should not have to know the vocabulary — and because a
+ * level is stable across kinds we add later, where a hand-passed list silently
+ * stops including them.
+ */
+export declare const AGENT_EVENT_LEVELS: readonly ["status", "step", "debug"];
+export type AgentEventLevel = (typeof AGENT_EVENT_LEVELS)[number];
+/** The default when `level` is not asked for: progress without the reasoning. */
+export declare const DEFAULT_AGENT_EVENT_LEVEL: AgentEventLevel;
+/**
+ * Which kinds each level carries. Declared HERE and read by both ends, because
+ * the edge decides what to select and the customer decides what to ask for, and
+ * a level that means two different things at those two places is a stream with
+ * holes in it that nothing reports.
+ */
+export declare const AGENT_EVENT_KINDS: Readonly<Record<AgentEventLevel, readonly AgentRecordKind[]>>;
+/**
+ * How much of a run is PUSHED to a customer's endpoint, as against how much a
+ * subscriber READS.
+ *
+ * ── Why this is not `AgentEventLevel`, and what is shared anyway ─────────────
+ *
+ * {@link AGENT_EVENT_LEVELS} is `status | step | debug` and spells exactly TWO
+ * of the four names below. `silent` has no meaning for a reader — a subscriber
+ * asking for nothing simply does not subscribe — and `error` has no meaning for
+ * a cursor tail, which is a query and not a policy. Going the other way,
+ * `status` is not a delivery level: it selects three kinds, and what a customer
+ * wants pushed at the quiet end is not three kinds, it is the ONE terminal fact
+ * that the run is over.
+ *
+ * So this is a second list of NAMES. It is deliberately not a second list of
+ * KINDS: {@link NOTIFY_KINDS} takes the `step` and `debug` sets by REFERENCE
+ * from {@link AGENT_EVENT_KINDS}, so a kind added to what `step` carries when
+ * read is carried by what `step` pushes in the same edit. Two overlapping
+ * vocabularies is where a drift bug lives; the overlap is therefore not
+ * retyped, it is shared.
+ */
+export declare const NOTIFY_LEVELS: readonly ["silent", "error", "step", "debug"];
+export type NotifyLevel = (typeof NOTIFY_LEVELS)[number];
+export declare function isNotifyLevel(value: unknown): value is NotifyLevel;
+/**
+ * The default when a run names no policy, and it is `error` for a compatibility
+ * reason rather than a taste one: {@link AgentRequest.webhook} already exists
+ * and a bare one has always meant "tell me when it is over". A field that
+ * already exists must not change meaning under the callers who already set it.
+ */
+export declare const DEFAULT_NOTIFY_LEVEL: NotifyLevel;
+/**
+ * Which record kinds each level pushes AS THEY BECOME DURABLE.
+ *
+ * `silent` and `error` push none: the difference between those two is the
+ * terminal outcome, which is not a record — see {@link pushesTerminal}.
+ */
+export declare const NOTIFY_KINDS: Readonly<Record<NotifyLevel, readonly AgentRecordKind[]>>;
+/**
+ * Whether the run's terminal outcome is pushed at this level.
+ *
+ * Everything but `silent`, and `error` in particular. A webhook that is silent
+ * on success was the other candidate reading of that word and it is refused
+ * here: it makes a working endpoint indistinguishable from a broken one, so the
+ * customer cannot tell "still running" from "finished fine" — which is the
+ * failing-state-renders-as-the-passing-state defect this whole field exists to
+ * remove. `error` means "one message, and what I act on is its `status`".
+ */
+export declare function pushesTerminal(level: NotifyLevel): boolean;
+/**
+ * Where a run's events go, and how many of them.
+ *
+ * `level` is REQUIRED, so `notify: {}` is a 400 rather than a policy nobody
+ * chose — the same rule {@link AgentCaps} follows and the same rule
+ * `mcpTool: string | null` follows in the registry. `webhook` is optional
+ * because {@link AgentRequest.webhook} may already carry it; when both are
+ * present this one wins, being the more specific statement.
+ */
+export interface NotifyPolicy {
+    level: NotifyLevel;
+    webhook?: string;
+}
+/**
+ * One appended row.
+ *
+ * `seq` is allocated by the store, is gap-free per run and is the cursor: a
+ * client that has seen `seq` asks for everything `after` it and cannot miss a
+ * row, however many machines, retries or reconnections happened in between.
+ * That property is the whole reason a killed browser does not cost a customer
+ * their output.
+ */
+export interface AgentRecord {
+    seq: number;
+    kind: AgentRecordKind;
+    at: Timestamp;
+    /**
+     * The payload, shaped by `kind`: the extracted record for `result`, the
+     * {@link AgentStep} for `step`, the {@link AgentGoal} for `goal`, and a
+     * stated sentence for `finding`, `ruled-out` and `irreversible`.
+     */
+    value: unknown;
+    /** The step this was produced at, when a step produced it. */
+    step?: number;
+    /** The sub-goal it belongs to, when the run had stated a plan. */
+    goal?: string;
+}
+/**
+ * One run, as `GET /v1/agent/{id}` answers it: status, plan, findings so far,
+ * cost so far.
+ *
+ * Every quantity on it is CURRENT rather than final — `usage`, `credits`,
+ * `stepsUsed`, `pages` and `records` all move while the run is live — because
+ * every run bills for work performed and a customer must be able to watch the
+ * meter rather than discover it.
+ */
+export interface AgentRun {
+    id: string;
+    status: AgentRunStatus;
+    task: string;
+    /** The harness the run was placed on. Never the model behind it. */
+    agent: AgentAlias;
+    caps: AgentCaps;
+    createdAt: Timestamp;
+    /** Absent while `queued`: nothing has picked the run up yet. */
+    startedAt?: Timestamp;
+    /** Absent until terminal. */
+    endedAt?: Timestamp;
+    /** So far, from the loop's own monotonic clock. The billed quantity. */
+    durationMs: number;
+    stepsUsed: number;
+    pages: number;
+    /** Records of kind `result` appended so far. The count beside the output. */
+    records: number;
+    /** The high-water `seq` over EVERY kind — where to resume the event tail. */
+    lastEventSeq: number;
+    /** The plan as it currently stands. Absent when the run never stated one. */
+    goals?: readonly AgentGoal[];
+    usage: Usage;
+    /** Credits spent so far, as a decimal string. What the bill is argued from. */
+    credits: string;
+    /**
+     * The answer, inline, once there is one and it is small enough to be inline.
+     * Above {@link INLINE_RESULT_BYTES} it is absent and {@link outputUrl} plus
+     * {@link records} is the answer — asking for one title must never paginate,
+     * and returning a megabyte on a status poll must never happen.
+     */
+    data?: unknown;
+    /** Where the whole output is fetchable, when it did not fit inline. */
+    outputUrl?: string;
+    stopReason?: AgentStopReason;
+    replayUrl?: string;
+    recordingDeclined?: true;
+    /** Present when `status` is `failed`. */
+    error?: string;
+    /**
+     * When a human asked for this run to stop. Write-once: a second cancel cannot
+     * move the instant, so "who stopped it and when" survives a retried request.
+     * Present while the run is still settling as well as after — a cancel is
+     * asked for, not applied instantly.
+     */
+    cancelRequestedAt?: Timestamp;
+    /**
+     * WHY THIS RUN IS PARKED, present exactly while `status` is `paused`.
+     *
+     * The one place the two doors are told apart. Everything else about a park
+     * is identical — the row, the warm browser, the resume — so `reason` is a
+     * field here rather than a second status, and a consumer that only cares
+     * that the run is waiting can read `status` and stop.
+     *
+     * `expiresAt` is on it because a park a customer cannot see the end of is a
+     * park they cannot plan around: it is when the run gives up waiting and
+     * carries on, not when the run dies.
+     */
+    pause?: AgentPause;
+    /**
+     * When a human asked for the wheel, still unanswered by the machine.
+     *
+     * The same shape and the same reason as {@link cancelRequestedAt}: a park is
+     * ASKED FOR at the edge and applied by the machine on its next report, so
+     * there is an instant where the request exists and the park does not. Naming
+     * that instant is what lets `POST /control` be idempotent and lets a
+     * customer see that their request landed before the run has noticed it.
+     */
+    controlRequestedAt?: Timestamp;
+}
+/**
+ * A park, as every surface reads it.
+ *
+ * ## Why a parked run is a ROW and not a held connection
+ *
+ * Because the thing being waited on is a person, and people are slower than
+ * every timeout in this system. A park expressed as an open request would tie
+ * the answer to one socket, one edge isolate and one machine staying up; a
+ * park expressed as a row is discoverable by a customer who was asleep when it
+ * happened, survives the process, and is answerable from a different device an
+ * hour later. It is the same argument the job model already made for a run.
+ */
+export interface AgentPause {
+    /**
+     * Which door the run went through.
+     *
+     * `control` — a human asked for the wheel; the browser is live and drivable
+     * at {@link viewerUrl}, and the run resumes when they hand it back.
+     * `question` — the agent asked something only the customer can answer, on
+     * `POST /v1/agent/{id}/answer`.
+     */
+    reason: 'control' | 'question';
+    at: Timestamp;
+    /**
+     * When the run stops waiting and carries on — NOT when it dies.
+     *
+     * A park has to expire, because it holds a warm browser and a machine slot
+     * for somebody who may never reply. What expiry does is resume the run: an
+     * unanswered question is answered "nobody replied" and the model decides,
+     * and an unreturned wheel is taken back. So there is no state here a run can
+     * be stuck in, and no stop reason that means "abandoned".
+     */
+    expiresAt: Timestamp;
+    /** What the agent asked. Present exactly when `reason` is `question`. */
+    question?: string;
+    /** The replies the agent offered. Advisory: any answer is accepted. */
+    options?: readonly string[];
+    /** Who is driving. Present exactly when `reason` is `control`. */
+    driver?: string;
+    /**
+     * Where a human goes to watch and drive.
+     *
+     * The durable `/play/{sessionId}` address and never a short-lived signed
+     * token: this URL is put in front of a person, who will paste it into a chat
+     * and open it twenty minutes later.
+     */
+    viewerUrl?: string;
+}
+/**
+ * `POST /v1/agent/{id}/control` — take the wheel, or hand it back.
+ *
+ * ONE route and not two, because "take" and "release" are the same
+ * transition read in opposite directions and a customer holding the wheel
+ * needs exactly one place to look. `action` is required for the reason every
+ * required-and-explicit field in this file is: a default here would be a
+ * guess about whether a person wants control, and both guesses are bad.
+ */
+export interface AgentControlRequest {
+    action: 'take' | 'release';
+    /**
+     * Who is driving, for the audit trail and for the refusal message a second
+     * driver gets. Defaulted to the calling API key's account when absent,
+     * because the honest answer is never nobody.
+     */
+    who?: string;
+}
+export declare const AGENT_CONTROL_FIELDS: readonly ["action", "who"];
+/**
+ * `POST /v1/agent/{id}/answer` — the reply to a question a run parked on.
+ *
+ * Free text, and deliberately not constrained to {@link AgentPause.options}: a
+ * human who was offered two choices and needs a third has information the
+ * model did not have, and the one seam that exists to bring a person's
+ * judgment into a run must not refuse the judgment.
+ */
+export interface AgentAnswerRequest {
+    answer: string;
+    answeredBy?: string;
+}
+export declare const AGENT_ANSWER_FIELDS: readonly ["answer", "answeredBy"];
+/**
+ * Checks a control request. Whole-request validators live here, beside the
+ * types and beside `validateAgentRequest`, so the edge and the machine cannot
+ * disagree about what a valid body is.
+ */
+export declare function validateAgentControlRequest(input: unknown): ValidationResult<AgentControlRequest>;
+/** Checks an answer. An empty answer is refused: it is a park that never ended. */
+export declare function validateAgentAnswerRequest(input: unknown): ValidationResult<AgentAnswerRequest>;
+/**
+ * Above this, the answer does not ride inline on the run row.
+ *
+ * One megabyte, and it is a product decision rather than a database one: under
+ * it a caller who asked for one title gets it in `data` with no second request,
+ * and over it the records are in object storage and `data` would be a megabyte
+ * on every status poll of a two-hour run.
+ */
+export declare const INLINE_RESULT_BYTES = 1048576;
+/** What `POST /v1/agent` answers, in milliseconds. */
+export interface AgentSubmission {
+    id: string;
+    /** `queued`, always. Stated rather than implied so a client can assert it. */
+    status: AgentRunStatus;
+    createdAt: Timestamp;
+}
+/** `GET /v1/agent/{id}/events`. */
+export interface AgentEventQuery {
+    /** Resume: everything with a greater `seq`. Absent starts at the beginning. */
+    after?: number;
+    level?: AgentEventLevel;
+    limit?: number;
+}
+/** `GET /v1/agent/{id}/results`. */
+export interface AgentResultQuery {
+    cursor?: string;
+    limit?: number;
+}
+/**
+ * A frame on the event channel.
+ *
+ * ── THE STREAM IS A PROJECTION OF DURABLE STATE, NOT A LIVE PIPE ─────────────
+ *
+ * Every frame here was a row before it was a frame. The channel reads them from
+ * a cursor and ends; it is never attached to the browser, the machine or the
+ * loop. Three things fall out of that and all three are load-bearing:
+ *
+ *   * a stateless Worker can serve it, because there is nothing to hold;
+ *   * a dropped connection loses nothing — resume at `cursor`;
+ *   * **the browser can die and the stream cannot**, because the stream was
+ *     never attached to it. `docs/AGENTS.md` states that as a property of the
+ *     product; here it is a property of the transport.
+ *
+ * The next reader will want to "upgrade" this to a WebSocket. That would take
+ * all three away in exchange for latency nobody asked for on a run measured in
+ * hours.
+ *
+ * Tagged with `frame` rather than dispatched on shape. `crawl` sniffs its
+ * header frame apart from its page frames and gets away with it because the two
+ * cannot be confused; here a `record` carrying an arbitrary `value` could
+ * legitimately look like anything, including a header.
+ */
+export type AgentEventFrame = 
+/**
+ * First, always, before any record and even when there are none — so a client
+ * that subscribed before the run produced anything receives the run and an
+ * end rather than silence.
+ */
+{
+    readonly frame: 'run';
+    readonly run: AgentRun;
+    readonly level: AgentEventLevel;
+} | {
+    readonly frame: 'record';
+    readonly record: AgentRecord;
+}
+/**
+ * Last, always. `cursor` is where to resume; `done` is whether resuming would
+ * be pointless because the run is terminal and this was the end of its log.
+ */
+ | {
+    readonly frame: 'end';
+    readonly cursor: number;
+    readonly done: boolean;
+};
+/**
+ * A durable identity: minted seed, minted chrome-or-brave, pinned exit city
+ * and its storage. Everything about it is minted and read-only — the caller
+ * names it and nothing else.
+ *
+ * There is deliberately NO `identity` field, and there never will be.
+ * Chrome-vs-brave is minted by us, pinned for the profile's life, and invisible
+ * to customers; `seed`, `fingerprint`, `timezone`, `languages` and `webrtcIp`
+ * are absent for the same reason. Every one of them is a way to build an
+ * identity that cannot exist. The operator side runs the identity loop; the
+ * customer side sees outcomes.
+ */
+export interface Profile {
+    id: string;
+    label: string;
+    /** Pinned exit affinity: country/region/city. The IP rotates underneath it. */
+    exit: ExitTarget;
+    createdAt: Timestamp;
+}
+export interface ProfileCreateRequest {
+    label: string;
+    /** Optional geography. Everything else about the profile is minted. */
+    exit?: ExitTarget;
+}
+export interface ProfileQuery {
+    /** Glob, e.g. "acme-*". */
+    label?: string;
+    limit?: number;
+    cursor?: string;
+}
+export type SessionStatus = 'running' | 'completed' | 'partial' | 'failed';
+/** What actually happened, as opposed to how the call returned. */
+export type SessionOutcome = 'ok' | 'blocked' | 'timeout' | 'capped' | 'error';
+export interface SessionSummary {
+    id: string;
+    status: SessionStatus;
+    outcome?: SessionOutcome;
+    /** Absent for ephemeral sessions. */
+    profileId?: string;
+    /** The agent task, when the session was an agent run. */
+    task?: string;
+    /** Where this session actually came out. Session-scoped, not profile-scoped. */
+    exit?: ResolvedExit;
+    startedAt: Timestamp;
+    endedAt?: Timestamp;
+    durationMs: number;
+    pages: number;
+    /**
+     * Hosted player. First-class, not a URL buried in an agent result.
+     *
+     * Optional for the reason {@link WireAgentResult.replayUrl} gives at length:
+     * a session served by a host with no durable replay storage has no link that
+     * will still resolve after that process exits, and an absent field is the
+     * honest way to say so.
+     */
+    replayUrl?: string;
+    /**
+     * The caller declined a recording for this session. See
+     * {@link AgentResult.recordingDeclined}, which is the same fact on the
+     * result of the run that produced the row, argued at length.
+     *
+     * Read from `sessions.recording_declined`, which is written from the request
+     * that opened the session and never moved afterwards. It is the reason
+     * {@link replayUrl}'s absence is readable: a session with no url and this
+     * `true` was refused, and one with no url and no field was wanted and not
+     * obtained.
+     *
+     * Set for a `/connect` session and an `agent` run, the two capabilities that
+     * record. Absent on a scrape, crawl, search or monitor check, which record
+     * nothing and so have nothing to decline.
+     */
+    recordingDeclined?: true;
+    usage: Usage;
+    billed?: BilledResources;
+}
+/**
+ * Note there is no `identity` filter here, by design. The equivalent internal
+ * query — "every brave block this week" — lives on the operator side, where the
+ * identity loop is run. Customers see outcomes; we see which identity produced
+ * them.
+ */
+export interface SessionQuery {
+    status?: SessionStatus;
+    outcome?: SessionOutcome;
+    /** Glob against the agent task, e.g. "*checkout*". */
+    task?: string;
+    /** Relative (`24h`, `7d`) or an ISO instant. */
+    since?: string;
+    until?: string;
+    profile?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface SessionExportRequest {
+    sessionId: string;
+}
+export interface SessionExport {
+    sessionId: string;
+    /** Portable `.outcrawl` bundle; plays offline. */
+    url: string;
+    bytes: number;
+    expiresAt: Timestamp;
+}
+export type UsageGrouping = 'hour' | 'day' | 'month' | 'capability';
+export interface UsageQuery {
+    /** ISO date or instant. */
+    from: string;
+    to: string;
+    /** Defaults to `day`. */
+    groupBy?: UsageGrouping;
+}
+export interface UsageBucket {
+    /** The day, hour, month or capability name this bucket covers. */
+    key: string;
+    usage: Usage;
+    billed: BilledResources;
+}
+/**
+ * Same numbers as the per-call `usage` fields, aggregated. Nothing appears here
+ * that was not already visible on the call that caused it.
+ */
+export interface UsageReport {
+    from: string;
+    to: string;
+    groupBy: UsageGrouping;
+    buckets: UsageBucket[];
+    total: BilledResources;
+}
+/**
+ * Why credits moved, in the vocabulary a customer is owed an answer in.
+ *
+ * Three values, and every one of them is reachable today: a student grant, a
+ * refund for a run we charged for and should not have, and an operator
+ * correction. There is deliberately no `expiry` and no `spend`.
+ *
+ * No `expiry`, because expiry is the entry's own `expires_at` — a column the
+ * balance reader honours at read time — and not a row somebody has to remember
+ * to write. A sweep that writes expiry rows is a sweep that can fail to run,
+ * and the failure mode is a balance that stays spendable months after it
+ * lapsed.
+ *
+ * No `spend`, because spend is metered usage and writing it here as well would
+ * be two numbers for one fact with nothing holding them equal. `CREDIT_BALANCE`
+ * in `@outcrawl/persistence` carries the whole argument.
+ *
+ * HERE rather than in `@outcrawl/persistence`, where it was, because three
+ * packages now have to agree about it and none of them may hold a copy: the
+ * ledger's `credit_ledger_reason_known` check constraint renders from it, the
+ * router validates `POST /operator/credits` against it, and the CLI's
+ * `--reason` flag offers it. A second list in any of the three is a value one
+ * of them accepts and another refuses.
+ */
+export type CreditReason = 'grant' | 'refund' | 'adjustment';
+export declare const CREDIT_REASONS: readonly ["grant", "refund", "adjustment"];
+/**
+ * What authorised the entry, so a row can be traced back to the thing that
+ * caused it rather than to whoever happened to run the insert.
+ *
+ * Paired with the entry's `reference_id` under a unique constraint, which is
+ * what makes granting itself idempotent: a redeem code presented twice is
+ * `('student_programme', <code id>)` twice and the second insert is a no-op,
+ * not a second 10,000 credits.
+ *
+ * Narrow on purpose. `stripe` is absent because nothing in this tree talks to
+ * Stripe, and a value that cannot be produced is not a source — it is an
+ * unbilled intention every reader of the vocabulary has to rule out, which is
+ * the exact defect `0007_usage_kinds.sql` removed from `UsageKind`.
+ */
+export type CreditSource = 'student_programme' | 'promotion' | 'operator';
+export declare const CREDIT_SOURCES: readonly ["student_programme", "promotion", "operator"];
+/**
+ * What an account still OWNS, as `GET /v1/credits` answers it.
+ *
+ * A different question from {@link UsageReport} and deliberately a different
+ * route, because folding one into the other would break both. A usage report is
+ * WINDOWED — it takes `from` and `to` and answers "what did this account
+ * consume between these instants". This is a POOL: granted once, drawn down by
+ * every credit ever spent against it, and not reset by a month boundary. A
+ * balance shown inside a windowed report would read as that window's balance,
+ * which is the misreading `CREDIT_BALANCE` in `@outcrawl/persistence` warns
+ * about at length.
+ *
+ * It is also NOT the plan's monthly allowance. A paid tier's 5,000 credits a
+ * month are an allowance that resets; these are credits the account was given
+ * and keeps until they are spent or they lapse. The two are enforced and
+ * reported by different machinery on purpose: a student's 10,000-credit grant
+ * folded into the monthly window would silently lapse every month, which is
+ * the opposite of what the promotion promises.
+ *
+ * Every figure is an exact decimal STRING, summed and subtracted by Postgres.
+ * These are credits, and a binary64 that has been through a reconciler cannot
+ * be reconciled back.
+ */
+export interface CreditBalance {
+    /** Unlapsed grants, refunds and adjustments, summed. */
+    granted: string;
+    /**
+     * Entries whose expiry has passed, summed SEPARATELY rather than dropped.
+     *
+     * This field is the answer to "where did my 4,000 credits go". Without it a
+     * reader can only show a smaller number, and the customer is told that the
+     * database says so.
+     */
+    expired: string;
+    /** Priced usage, all time, off the append-only meter. */
+    spent: string;
+    /** `granted - spent`. Negative means the pool was overspent. */
+    balance: string;
+    /**
+     * `balance <= 0`: nothing left in the granted pool.
+     *
+     * REPORTED, NOT ENFORCED. Nothing in the control plane refuses work because
+     * this is true: admission is decided against the plan's monthly allowance,
+     * which a grant deliberately does not move. So an exhausted pool costs an
+     * account nothing today, and a fresh grant buys it nothing either. That is a
+     * product gap, it is named here so no reader mistakes this field for a gate,
+     * and closing it is a pricing decision rather than a wiring one.
+     */
+    exhausted: boolean;
+    /**
+     * Usage rows carrying a price nothing can sum.
+     *
+     * Non-zero means somebody wrote a `credits` value to the meter out of band,
+     * so `spent` is a lower bound and `balance` an upper one — every other figure
+     * here is approximate while this is not zero, and saying so is the point.
+     */
+    malformed: number;
+}
+export declare const PROFILE_KEYS: readonly ["id", "label", "exit", "createdAt"];
+export declare const SESSION_QUERY_KEYS: readonly ["status", "outcome", "task", "since", "until", "profile", "limit", "cursor"];
+/**
+ * The wire form of every list capability: `profiles.list`, `sessions.list`,
+ * `monitors.list`.
+ *
+ * A bare array cannot be the wire form, because every list query carries a
+ * `cursor` and a bare array has nowhere to return the next one. Making the
+ * envelope a type rather than a convention is what stops four surfaces
+ * agreeing today and drifting apart at the first one that forgets.
+ *
+ * `cursor` absent means the last page. It is deliberately not `null`: absence
+ * is the end of the list, and a `null` that means the same thing gives callers
+ * two ways to spell one state.
+ *
+ * `usage` is mandatory here as it is everywhere else. Usage rides on the result
+ * that caused it rather than living in a metrics endpoint, so that the number
+ * on the bill is always attached to the call that produced it. A list is a
+ * billable call like any other.
+ */
+export interface ListResponse<T> {
+    data: T[];
+    cursor?: string;
+    usage: Usage;
+}
+/**
+ * The body of a non-upgrade `GET /connect`: what the router hands a client so
+ * it can reach a browser.
+ *
+ * This lives in core because it has two ends — the router writes it, the SDK
+ * reads it — and neither owns it. Defining it in the server would make a
+ * published client package depend on the control plane to learn a wire shape,
+ * and copying it into both is the drift that having one contract package is
+ * meant to prevent.
+ */
+export interface SessionAllocation {
+    /** Minted at allocation. The `sessions` row the worker will create. */
+    sessionId: string;
+    /** Hand this straight to `connectOverCDP`. */
+    wsEndpoint: string;
+    /** When the ticket in `wsEndpoint` stops being redeemable. */
+    expiresAt: Timestamp;
+}
+/**
+ * The time seam. Every wait and every deadline goes through this, so tests
+ * drive a virtual clock instead of sleeping.
+ *
+ * `now` is a monotonic millisecond reading for measuring elapsed time. It is
+ * **not** a wall-clock timestamp and must never be persisted or compared across
+ * processes — use `Timestamp` for anything that outlives the process.
+ *
+ * This lives in core rather than in the first package that needed it because
+ * three now need one independently — the render pipeline, the agent loop's
+ * duration cap, and the supervisor's heartbeat — and none of them should take a
+ * dependency on another's package to obtain a two-method interface.
+ */
+export interface Clock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+/**
+ * The real one. `performance.now()` rather than `Date.now()`, because a
+ * deadline must not move when NTP steps the wall clock.
+ */
+export declare const systemClock: Clock;
+/**
+ * Wall time, injected. Epoch milliseconds, for values that are **stored** or
+ * compared across processes: when a cache entry was resolved, when a lease was
+ * taken, when a profile was last seen.
+ *
+ * Deliberately a separate name from {@link Clock}, and deliberately not spelled
+ * `clock`. The two have the same shape and opposite contracts, so anything that
+ * unifies them by pattern-matching the word is a bug that does not announce
+ * itself: `new Date(performance.now())` is a valid Date somewhere in 1970, and
+ * every persisted timestamp is quietly wrong while every test still passes.
+ *
+ * Choosing between them: does the value outlive the process? Wall. Is it the
+ * distance between two moments? Monotonic — and then it must be {@link Clock},
+ * because wall time steps backwards when NTP corrects it.
+ */
+export interface WallClock {
+    /** Epoch milliseconds. Subject to NTP steps; never use it for a duration. */
+    now(): number;
+}
+export declare const systemWallClock: WallClock;
+export type ValidationResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    errors: string[];
+};
+/**
+ * `"5m"` -> 300000. Throws on anything {@link DURATION_PATTERN} rejects.
+ *
+ * Canonical here rather than in `@outcrawl/runtime`, which is where it used to
+ * live, because the grammar has to be enforced at BOTH trust boundaries — the
+ * edge validator and the loop's own `validateCaps` — and a second parser beside
+ * a second copy of the pattern is how the two come to disagree about what
+ * `"90m"` means. `@outcrawl/runtime` re-exports this one.
+ */
+export declare function parseDuration(spec: string): number;
+/**
+ * Checks one `caps.duration` against the grammar, returning the error to report
+ * or `undefined`.
+ *
+ * ── THERE IS NO CEILING HERE ANY MORE, AND THAT IS THE POINT ─────────────────
+ *
+ * This function used to refuse anything over `MAX_RUN_DURATION_MS` — 900,000,
+ * spelled `15m` to customers — and the refusal was honest about its own
+ * reasoning: the edge forwarded one `fetch` per REST call under an
+ * `AbortSignal.timeout`, that signal bounded the whole call, and a run that
+ * outlived it had its socket cut mid-stream with no terminal frame. So the
+ * platform could not deliver a longer run and said so.
+ *
+ * A job has no held request. Nothing forwards, nothing times out, and the
+ * number that used to be quoted as a product limit was never one — it was the
+ * shape of the transport, wearing policy's clothes. `docs/AGENTS.md`: "the
+ * refusal currently quoting it is a patch over that and is deleted when this
+ * lands, not tuned." Deleted, not tuned. `caps` is the customer's dial, hours
+ * are normal, and `"12h"` now means twelve hours.
+ *
+ * The function survives the ceiling because its OTHER reason outlives it:
+ * `validateAgentRequest` here and `validateCaps` in `@outcrawl/runtime` must
+ * refuse a malformed duration with the same sentence, so a caller who hits the
+ * loop directly gets the same message as one who came through HTTP. Returns
+ * rather than pushes, for that.
+ */
+export declare function capDurationError(value: unknown): string | undefined;
+/**
+ * The one canonical object guard for this package. `@outcrawl/core` has no
+ * dependencies — it is the contract every other package imports, so it carries
+ * no schema validator — and this guard is defined here once rather than
+ * recreated at each boundary. It proves an object and nothing more; fields stay
+ * `unknown` and are checked individually below.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Every field a submit accepts. This is part of the REQUEST CONTRACT, so it
+ * lives beside the type and the validator rather than in whichever package
+ * happens to parse a body first.
+ *
+ * It moved here from `@outcrawl/api`'s `AGENT_FIELDS` for a measured reason.
+ * A run is a row, and the edge writes that row before it forwards. While the
+ * accept-list was private to the api package the EDGE could not consult it, so
+ * a submit carrying an unknown field was recorded, forwarded, refused a hop
+ * later, and settled `failed` — a permanent run in the customer's history for
+ * work they never successfully submitted. Measured 2026-09-08: one bad field,
+ * `http=400`, `agent_runs` +1.
+ *
+ * `satisfies readonly (keyof AgentRequest)[]` is half its job; the other half
+ * is `_requestFieldsExhaustive` in `@outcrawl/api`, which still fails to
+ * compile if `AgentRequest` grows a field this list does not name. Both halves
+ * now read ONE array, so the edge and the machine cannot disagree about what a
+ * submit may carry.
+ */
+export declare const AGENT_REQUEST_FIELDS: readonly ["task", "caps", "profile", "schema", "agent", "webhook", "notify", "exit", "cache", "record", "secrets", "rules", "integrations"];
+/**
+ * The names in `input` that no submit accepts, in the order given. Empty means
+ * every field is known — it does NOT mean the request is valid, which is
+ * `validateAgentRequest`'s question.
+ */
+export declare function unexpectedAgentFields(input: Record<string, unknown>): readonly string[];
+/**
+ * Validates an agent request at the trust boundary — HTTP body, MCP tool call,
+ * CLI flags. `caps` is required: an agent run with no ceiling is how a bill
+ * becomes a story, so the request is rejected before a browser is allocated
+ * rather than capped later.
+ *
+ * MCP supplies a conservative default when the caller omits `caps`; it must do
+ * so *before* calling this.
+ */
+export declare function validateAgentRequest(input: unknown): ValidationResult<AgentRequest>;
+export {};