ax 0.8.0 → 0.8.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -90,7 +90,7 @@ Exit codes are the contract:
90
90
  | `2` | usage error — bad flags, malformed URL, local target without a tunnel |
91
91
  | `3` | API unreachable, timeout, or rate limit exhausted |
92
92
 
93
- Budget notes: ora allows 30 scans + 6 `--force` scans per rolling 24h per IP (plus a 10/min burst limit). Results served from the freshness cache cost nothing, so a CI job that audits on every push stays well inside the budget — tune the window with `--max-age`, and reserve `--force` for verifying a fix you just deployed. High-volume callers can present an ora-issued scan API key (`--api-key` or `ORA_SCAN_API_KEY`), which exempts them from all of these limits; keys are issued manually by ora (no self-serve signup), and an unrecognized key silently falls back to the keyless limits rather than erroring. An auth-gated MCP target reports `mcpAuthRequired` and scores 0 as "could not evaluate"; `--min-score` deliberately skips the gate rather than failing on it.
93
+ Budget notes: ora allows 30 scans + 6 `--force` scans per rolling 24h per IP (plus a 10/min burst limit). Results served from the freshness cache cost nothing, so a CI job that audits on every push stays well inside the budget — tune the window with `--max-age`, and reserve `--force` for verifying a fix you just deployed. High-volume callers can present an ora-issued scan API key (`--api-key` or `ORA_SCAN_API_KEY`), which exempts them from all of these limits; keys are issued manually by ora (no self-serve signup), and an unrecognized key silently falls back to the keyless limits rather than erroring. An auth-gated MCP target is not a failure: ora answers with an `MCP_AUTH_REQUIRED` error and no score; ax prints the notice (or the error object with `--json`), skips `--min-score`, and exits `0`.
94
94
 
95
95
  ### Auditing localhost (`--tunnel ora`, `--tunnel-cmd`)
96
96
 
@@ -229,11 +229,11 @@ Runs a real AI agent at a site through ora's **public** journey API — no key,
229
229
  For the 4-layer readiness audit, run: ax audit stripe.com
230
230
  ```
231
231
 
232
- Anonymous callers run curated intents (`pricing`, `signup`, `api-docs`, `integrate`, `support`, …) — list them with `GET https://ora.ai/api/journey/intents`, and the accepted agents with `GET https://ora.ai/api/journey/agents`. The public caps are 100 runs per rolling 24h per target and 200 runs per 24h per IP (plus a 20/min burst limit); a target at its cap answers with the most recent stored run (`rate_limited: true`) instead of an error, so repeat CI invocations are cheap. Verdict and step count come from ora's contract as-is — the CLI never re-judges a run.
232
+ Anonymous callers run curated intents (`pricing`, `signup`, `api-docs`, `integrate`, `support`, …) — list them with `GET https://ora.ai/api/journey/intents`, and the accepted agents with `GET https://ora.ai/api/journey/agents`. The public caps are 100 runs per rolling 24h per target and 20 runs per 24h per IP (plus a 20/min burst limit and a shared ceiling of 3,000 anonymous runs a day across all callers); a target at its cap answers with the most recent stored run (`rate_limited: true`) instead of an error, so repeat CI invocations are cheap. Verdict and step count come from ora's contract as-is — the CLI never re-judges a run.
233
233
 
234
234
  **Keyed tier:** an ora-issued partner API key (`--api-key`, or `ORA_PARTNER_API_KEY` / `ORA_SCAN_API_KEY` in the environment) unlocks `--task` — a free-text task of 4–300 characters that replaces the curated intent — and moves the caller to an allowance of 1000 runs per rolling 24h per key with no per-target cap and no burst guard. Keys are issued manually by ora (no self-serve signup). A wrong or unrecognized key with a *curated* intent silently degrades to the anonymous tier; `--task` without a recognized key is an error.
235
235
 
236
- If the live stream goes quiet (no frames for 120s) the CLI does not abandon the run — it switches to polling the run detail until the server reports a terminal state.
236
+ The CLI always follows the run's stream to the end, `--no-stream` included, because ora saves a finished run from inside the stream. If the stream drops or goes quiet (no frames for 120s), the CLI reopens it, which resumes the same run without re-running the agent. A stream `429` is waited out (up to 60s) before reopening, and a `404` or auth error ends the command at once. Only after five failed reopens does it fall back to polling the run detail, within a 15-minute budget shared with the stream.
237
237
 
238
238
  | Flag | Effect |
239
239
  |---|---|
@@ -241,7 +241,7 @@ If the live stream goes quiet (no frames for 120s) the CLI does not abandon the
241
241
  | `--task <text>` | Free-text task — needs a partner API key; mutually exclusive with `--intent` |
242
242
  | `--api-key <k>` | ora partner API key; also read from `ORA_PARTNER_API_KEY` (then `ORA_SCAN_API_KEY`) |
243
243
  | `--agent <id>` | Agent from the public roster (default: ora's pick) |
244
- | `--no-stream` | Poll for the result instead of streaming the trajectory |
244
+ | `--no-stream` | Hide the live trajectory view and print only the final result |
245
245
  | `--json` | Print the terminal run detail (verdict, step_count, result) as JSON |
246
246
 
247
247
  deep-journey exit codes: `0` run succeeded (any verdict) · `1` run failed · `2` usage error · `3` API unreachable / rate-limited.
@@ -1,7 +1,28 @@
1
1
  import type { AuditScanResult, AuditScoreResult } from "../contract";
2
- /** Any failure to obtain a result from ora: network, HTTP, rate limit, timeout. */
2
+ /**
3
+ * Any failure to obtain a result from ora: network, HTTP, rate limit, timeout.
4
+ *
5
+ * `code` is the server's machine-readable reason where it gave one, so a
6
+ * caller can branch without matching on prose, and `payload` is the error
7
+ * object exactly as ora served it (what `--json` prints - invariant 4). Both
8
+ * are null/undefined for the failures ora has no code for.
9
+ */
3
10
  export declare class AuditApiError extends Error {
11
+ readonly code: string | null;
12
+ readonly payload: unknown;
13
+ constructor(message: string, options?: {
14
+ code?: string | null;
15
+ payload?: unknown;
16
+ });
4
17
  }
18
+ /**
19
+ * ora's answer for a target whose MCP handshake needs credentials (contract
20
+ * 1.25.0): the scan is refused rather than scored, so there is no score to
21
+ * gate on. Not a failure - the CLI reports it and exits 0.
22
+ */
23
+ export declare const MCP_AUTH_REQUIRED = "MCP_AUTH_REQUIRED";
24
+ /** True when ora refused the scan because the MCP server wants credentials. */
25
+ export declare function isMcpAuthRequired(error: unknown): error is AuditApiError;
5
26
  /**
6
27
  * The raw audit payload: scan-shaped from the stream's terminal event,
7
28
  * score-shaped once deep-analysis polling has taken over.
@@ -55,8 +55,16 @@ export interface DeepJourneyOptions {
55
55
  baseUrl?: string;
56
56
  /** Abort when the stream is silent for this long (default 120s). */
57
57
  idleMs?: number;
58
- /** Skip the SSE and poll GET /api/journey/runs/{id} instead. */
58
+ /**
59
+ * No live view: `onTrajectory` is never called. The run is still followed
60
+ * over the stream, because the stream is what saves the finished run.
61
+ */
59
62
  noStream?: boolean;
63
+ /** Pause between stream reopens after a drop (default 2s). */
64
+ reopenPauseMs?: number;
65
+ /** Total time to follow a running run, streaming plus polling (default 15min). */
66
+ followBudgetMs?: number;
67
+ /** Detail polling, the last resort once every stream reopen has failed. */
60
68
  pollEveryMs?: number;
61
69
  pollLimit?: number;
62
70
  }
@@ -88,8 +96,8 @@ export declare function formatWait(ms: number): string;
88
96
  export declare function fetchRunDetail(base: string, runId: string): Promise<JourneyRunDetail>;
89
97
  /**
90
98
  * Run a deep journey against `target` and resolve with the terminal detail.
91
- * Streams the trajectory by default (progress lines via `options.progress`);
92
- * with `noStream`, polls the record instead. A per-target-capped trigger is
99
+ * Follows a running run's stream to its terminal frame (progress lines via
100
+ * `options.progress`); `noStream` only withholds `onTrajectory`. A per-target-capped trigger is
93
101
  * NOT an error: ora answers with the most recent stored run for that target,
94
102
  * and the outcome carries `cached: true` plus `retryAfterMs`.
95
103
  */
@@ -9,6 +9,19 @@ export declare function watchdog(ms: number): {
9
9
  disarm: () => void;
10
10
  tripped: () => boolean;
11
11
  };
12
+ /**
13
+ * Best-effort reading of an error response body: the human message, the
14
+ * server's machine-readable `code` where it gave one, and the parsed body
15
+ * itself. A caller that only branches on prose loses the code, and ora uses it
16
+ * to say things that are not failures (see MCP_AUTH_REQUIRED in ./audit).
17
+ * The body is read through a clone so the caller can still consume the
18
+ * original.
19
+ */
20
+ export declare function errorBody(res: Response): Promise<{
21
+ message: string;
22
+ code: string | null;
23
+ payload: unknown;
24
+ }>;
12
25
  /** Best-effort human message from an error response body. */
13
26
  export declare function errorBodyText(res: Response): Promise<string>;
14
27
  export declare const pause: (ms: number) => Promise<void>;
@@ -26,7 +26,7 @@ export interface paths {
26
26
  "/api/scan/stream": {
27
27
  /**
28
28
  * Stream an agent-readiness scan as Server-Sent Events
29
- * @description Runs a full agent-readiness scan on the given URL and streams progress as text/event-stream. Accepts a domain, MCP server URL, or MCP App URL (server that supports the MCP Apps extension `io.modelcontextprotocol/ui`) - the server auto-detects which kind of input was provided and selects the appropriate check set. Catalog-style listing pages are folded into the `mcp` kind by classifying the first validated embedded MCP URL. The stream emits a `kind_detecting` event immediately after the cheap reachability probe, followed by exactly one `kind_detected` event with payload `{ kind: 'domain' | 'mcp' | 'mcp-app', mcpUrl?: string, embeddedMcpUrls?: string[], hint?: string }` once URL-kind detection resolves. Subsequent events include `scan_init`, `layer_start`, `check_start`, `check_complete`, `layer_complete`, and finally `scan_complete` whose payload mirrors the ScanResult schema (including the optional `urlKind` field indicating the detected kind). The same freshness gate as POST /api/scan applies: a hit is a `kind_detected` frame followed by the terminal `scan_complete` event, rather than a full run. Rate limited two ways: 10 requests per minute per IP (burst) and a durable daily scan budget shared with the other scan entry points - both return 429 with a Retry-After header.
29
+ * @description Runs a full agent-readiness scan on the given URL and streams progress as text/event-stream. Accepts a domain, MCP server URL, or MCP App URL (server that supports the MCP Apps extension `io.modelcontextprotocol/ui`) - the server auto-detects which kind of input was provided and selects the appropriate check set. Catalog-style listing pages are folded into the `mcp` kind by classifying the first validated embedded MCP URL. The stream emits a `kind_detecting` event immediately after the cheap reachability probe, followed by exactly one `kind_detected` event with payload `{ kind: 'domain' | 'mcp' | 'mcp-app', mcpUrl?: string, embeddedMcpUrls?: string[], hint?: string }` once URL-kind detection resolves. Progress events follow (the 200 response lists every event type), and finally `scan_complete` whose payload mirrors the ScanResult schema (including the optional `urlKind` field indicating the detected kind). The same freshness gate as POST /api/scan applies: a hit is a `kind_detected` frame followed by the terminal `scan_complete` event, rather than a full run. Rate limited two ways: 10 requests per minute per IP (burst) and a durable daily scan budget shared with the other scan entry points - both return 429 with a Retry-After header.
30
30
  */
31
31
  get: operations["scanDomainStream"];
32
32
  };
@@ -40,7 +40,7 @@ export interface paths {
40
40
  "/api/score/{domain}": {
41
41
  /**
42
42
  * Get cached score for a domain
43
- * @description Returns the most recent cached scan result for the given domain. Read-only: never triggers a scan. On miss (404) or when the previous scan got stuck mid-flight (200 with `analysisStatus: "stuck"`), the response carries a structured `next_action` envelope pointing at `POST /api/scan` so agent callers have a machine-parseable next step. Successful responses are cached for 1 hour; stuck, 404, and ephemeral (disposable, `urlKind: "ephemeral"`) responses are uncached (`Cache-Control: no-store`) so a successful re-scan is observable immediately and a deleted disposable row is never served from cache. Rate limited to 10 requests per minute per IP - returns 429 if exceeded.
43
+ * @description Returns the most recent cached scan result for the given domain. Read-only: never triggers a scan. On miss (404) or when the previous scan got stuck mid-flight (200 with `analysisStatus: "stuck"`), the response carries a structured `next_action` envelope pointing at `POST /api/scan` so agent callers have a machine-parseable next step. Successful responses are cached for 1 hour; stuck, 404, and ephemeral (disposable, `urlKind: "ephemeral"`) responses are uncached (`Cache-Control: no-store`) so a successful re-scan is observable immediately and a deleted disposable row is never served from cache. Rate limited to 10 requests per minute per IP - returns 429 if exceeded. A scan API key exempts the caller, since this is the poll target for keyed scanning.
44
44
  */
45
45
  get: operations["getScore"];
46
46
  };
@@ -145,7 +145,7 @@ export interface paths {
145
145
  "/api/journey/runs": {
146
146
  /**
147
147
  * Run an agent journey against a domain
148
- * @description Triggers a real agent run: an AI agent (harness + model) attempts a task (an intent) against the given domain, and ora records the trajectory and derives insights. Two-step flow: this endpoint returns fast with a run record whose `stream_url` serves the live trajectory as Server-Sent Events; poll GET /api/journey/runs/{id} instead if you do not want the stream. Two caller tiers. Anonymous: curated intents only (see GET /api/journey/intents) - the server derives the actual agent prompt from the intent id, so no free-text prompt can reach the engine. Keyed: a caller presenting an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora) may instead send bounded free text (`intent.custom`, 4 to 300 characters, with `intent.domain` required), which the server anchors to the requested domain before dispatch and echoes back on the 201. Free text without a recognized key is a 401 with code CUSTOM_INTENT_REQUIRES_KEY; a curated body with a missing or unrecognized key is never an error and simply runs on the anonymous tier. The keyed free-text tier is also reachable from the ora CLI (ax deep-journey --task, v0.5+). Only publicly runnable agents are accepted (see GET /api/journey/agents). Unknown body fields are rejected (strict schema). Anonymous rate limits, three ways: a 20-per-minute burst cap per IP; a per-target cap of 100 runs per rolling 24h per (domain, intent, harness, model) - when a target is over the cap the response is HTTP 200 with the most recent stored run for that target (`rate_limited: true`) plus Retry-After, the freshness analog: a denied trigger still returns the newest result and consumes nothing; and a durable per-caller cap of 200 runs per rolling 24h per IP - exceeded, that one is a real 429 with `retry_after_ms` (there is no cached result to serve for a caller). Keyed rate limit, one way: 1000 runs per rolling 24h per key, exhaustion being the same 429 with `retry_after_ms`. A keyed caller skips both the burst cap and the per-target cap - free text fragments the target key, so a per-target window over it could never fill. Successful and capped responses carry X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers describing exactly one window: the per-target window on an anonymous response, the per-key caller window on a keyed one. Note: journey insights use the 5-layer journey taxonomy (discovery, identity, access, payments, experience), deliberately distinct from the 4 scoring layers of the audit report (POST /api/scan) - never map between the two.
148
+ * @description Triggers a real agent run: an AI agent (harness + model) attempts a task (an intent) against the given domain, and ora records the trajectory and derives insights. Two-step flow: this endpoint returns fast with a run record whose `stream_url` serves the live trajectory as Server-Sent Events; the stream is also what saves the finished run, so hold it open until its `result` or `error` frame (reopen it if the connection drops; it resumes the same run without re-executing). GET /api/journey/runs/{id} reads what a stream saved: a run nobody streams stays `running`. Two caller tiers. Anonymous: curated intents only (see GET /api/journey/intents) - the server derives the actual agent prompt from the intent id, so no free-text prompt can reach the engine. Keyed: a caller presenting an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora) may instead send bounded free text (`intent.custom`, 4 to 300 characters, with `intent.domain` required), which the server anchors to the requested domain before dispatch and echoes back on the 201. Free text without a recognized key is a 401 with code CUSTOM_INTENT_REQUIRES_KEY; a curated body with a missing or unrecognized key is never an error and simply runs on the anonymous tier. The keyed free-text tier is also reachable from the ora CLI (ax deep-journey --task, v0.5+). Only publicly runnable agents are accepted (see GET /api/journey/agents). Unknown body fields are rejected (strict schema). Anonymous rate limits, three ways: a 20-per-minute burst cap per IP; a per-target cap of 100 runs per rolling 24h per (domain, intent, harness, model) - when a target is over the cap the response is HTTP 200 with the most recent stored run for that target (`rate_limited: true`) plus Retry-After, the freshness analog: a denied trigger still returns the newest result and consumes nothing; and a durable per-caller cap of 20 runs per rolling 24h per IP - exceeded, that one is a real 429 with `retry_after_ms` (there is no cached result to serve for a caller). Keyed rate limit, one way: 1000 runs per rolling 24h per key, exhaustion being the same 429 with `retry_after_ms`. A keyed caller skips both the burst cap and the per-target cap - free text fragments the target key, so a per-target window over it could never fill. Successful and capped responses carry X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers describing exactly one window: the per-target window on an anonymous response, the per-key caller window on a keyed one. Note: journey insights use the 5-layer journey taxonomy (discovery, identity, access, payments, experience), deliberately distinct from the 4 scoring layers of the audit report (POST /api/scan) - never map between the two.
149
149
  */
150
150
  post: operations["createJourneyRun"];
151
151
  };
@@ -424,7 +424,7 @@ export interface components {
424
424
  * @description The contract version this payload conforms to. SemVer: a major means a response-envelope break - a stable field removed, renamed, or changed in meaning, or the default response format flipping - and is safe to pin. Additive changes and check-catalog membership changes ship on a minor. See docs/api.md -> Contract and versioning.
425
425
  * @enum {string}
426
426
  */
427
- contractVersion: "1.25.0";
427
+ contractVersion: "1.27.0";
428
428
  /**
429
429
  * @description Present only when this body is a stored result served by the freshness gate instead of a fresh scan. Absent on a live scan.
430
430
  * @enum {boolean}
@@ -462,10 +462,14 @@ export interface components {
462
462
  /** @description Why this request is the recommended next step */
463
463
  reason: string;
464
464
  };
465
- /** @description Experimental (no stability guarantee): competitive context appended when the request carries ?competitors=1. Null when the domain is unranked or the leaderboard read failed. Shape may change on any release. */
465
+ /** @description Experimental (no stability guarantee): competitive context drawn from the leaderboard, present only when the request carries ?competitors=1. Null when the domain is unranked or the leaderboard read failed. Shape may change on any release. */
466
466
  competitors?: {
467
467
  [key: string]: unknown;
468
468
  } | null;
469
+ /** @description Experimental (no stability guarantee): the scan scored against what the site is, present only when the request carries ?include=siteType. Null when the scan has no layers to score. Shape may change on any release. */
470
+ siteType?: {
471
+ [key: string]: unknown;
472
+ } | null;
469
473
  };
470
474
  AuditScoreResult: {
471
475
  domain: string;
@@ -623,7 +627,7 @@ export interface components {
623
627
  * @description The contract version this payload conforms to. SemVer: a major means a response-envelope break - a stable field removed, renamed, or changed in meaning, or the default response format flipping - and is safe to pin. Additive changes and check-catalog membership changes ship on a minor. See docs/api.md -> Contract and versioning.
624
628
  * @enum {string}
625
629
  */
626
- contractVersion: "1.25.0";
630
+ contractVersion: "1.27.0";
627
631
  /** @description Wall-clock duration of the scan that produced this stored result */
628
632
  durationMs: number | null;
629
633
  /**
@@ -656,10 +660,14 @@ export interface components {
656
660
  /** @description Why this request is the recommended next step */
657
661
  reason: string;
658
662
  };
659
- /** @description Experimental (no stability guarantee): competitive context appended when the request carries ?competitors=1. Null when the domain is unranked or the leaderboard read failed. Shape may change on any release. */
663
+ /** @description Experimental (no stability guarantee): competitive context drawn from the leaderboard, present only when the request carries ?competitors=1. Null when the domain is unranked or the leaderboard read failed. Shape may change on any release. */
660
664
  competitors?: {
661
665
  [key: string]: unknown;
662
666
  } | null;
667
+ /** @description Experimental (no stability guarantee): the scan scored against what the site is, present only when the request carries ?include=siteType. Null when the scan has no layers to score. Shape may change on any release. */
668
+ siteType?: {
669
+ [key: string]: unknown;
670
+ } | null;
663
671
  };
664
672
  /** @description The complete catalog of scanner checks. Stability classes: every field's shape and presence rule is stable within a major version; layer ids are envelope identity, so removing or renaming one is a major version change; check ids never change meaning while they exist, but catalog membership may change on a minor, with a contract changelog entry and a deprecation window; every other value (scores, weights, layer assignments, applicability, tiers, maturity, prose) is advisory and may change on a minor version, with score-relevant changes recorded in the contract changelog. Gate CI on an explicit list of check ids. */
665
673
  CheckCatalog: {
@@ -667,7 +675,7 @@ export interface components {
667
675
  * @description The contract version this catalog conforms to - identical to the OpenAPI info.version and the MCP server version. SemVer: a major means a response-envelope break (a stable field, or a layer id, removed or renamed or changed in meaning, or the default response format flipping) and is safe to pin; check-catalog membership changes ship on a minor. The full versioning policy is published in the API description at /api/openapi.json.
668
676
  * @enum {string}
669
677
  */
670
- contractVersion: "1.25.0";
678
+ contractVersion: "1.27.0";
671
679
  /** @description The four scored layers in scoring order, with display name and current weight. */
672
680
  layers: {
673
681
  /** @description Stable layer id: discovery, accessibility, usability, or payments. Removing or renaming a layer id is a major version change. Note one intentional divergence: the id 'accessibility' carries the display name 'Access'. */
@@ -766,7 +774,7 @@ export interface components {
766
774
  * @description The contract version this response conforms to - identical to the OpenAPI info.version and the MCP server version. The full versioning policy is published in the API description at /api/openapi.json.
767
775
  * @enum {string}
768
776
  */
769
- contractVersion: "1.25.0";
777
+ contractVersion: "1.27.0";
770
778
  /** @description The apex domain derived from the requested URL. */
771
779
  domain: string;
772
780
  /** @description The normalized URL the run targeted. */
@@ -2281,10 +2289,10 @@ export interface operations {
2281
2289
  query?: {
2282
2290
  /** @description Pass 1 to include a `competitors` object in the response: the category top-5 leaders plus the neighbor window (2 above / self / 2 below) drawn from the leaderboard. Returned only for domains with a market category - unclassified domains (Community, or no leaderboard row) get `competitors: null`. Omitted by default so the plain response stays lean. */
2283
2291
  competitors?: "1";
2284
- /** @description Pass `audit` to receive the versioned, allowlisted audit shape (AuditScanResult / AuditScoreResult) instead of the default body: every field is documented, carries a `contractVersion`, and internal fields are dropped. Omit it and the response is unchanged from previous releases. On GET /api/scan/stream, only the terminal `scan_complete` event's `result` is projected - all other events are identical to the default stream. */
2292
+ /** @description Pass `audit` to receive the versioned, allowlisted audit shape (AuditScanResult / AuditScoreResult) instead of the default body: every field is documented, carries a `contractVersion`, and internal fields are dropped. Omit it and the response is unchanged from previous releases. On GET /api/scan/stream, only the `scan_complete` event's `result` is projected - all other events are identical to the default stream. */
2285
2293
  format?: "audit";
2286
- /** @description Opt-in expansion list (comma-separated). `essentials` adds one response key, `essentials`: an alternate reading of the same scan carrying its own `score` (0-100 or null - required checks share 80 points, recommended 20, forward-looking signals upside-only), the required/recommended buckets, label copy, per-surface sub-scores, access signals, and a `checks` map keyed by check id. That map holds the essentials INTERPRETATION only (tier, bonus, fraction, occurrences, `essentialsGain`) - name, status, details, ora's recommendation, and `estScoreGain` for the same id stay in `layers[].checks[]`, so nothing serializes twice; join on the id. The pre-sorted `issues` list and `scoreEvidence` are arrays of ids resolving in that map. Omit the parameter and the response is byte-identical to previous releases. On GET /api/checks, `essentials` instead adds `essentialsTier`, `essentialsBonusOnly`, and `essentialsExcluded` to every catalog check (an excluded check never enters the essentials model; since 1.19.1 that is the two robots.txt policy checks). */
2287
- include?: "essentials";
2294
+ /** @description Opt-in expansion list (comma-separated). `essentials` adds one response key, `essentials`: an alternate reading of the same scan carrying its own `score` (0-100 or null - required checks share 80 points, recommended 20, forward-looking signals upside-only), the required/recommended buckets, label copy, per-surface sub-scores, access signals, and a `checks` map keyed by check id. That map holds the essentials INTERPRETATION only (tier, bonus, fraction, occurrences, `essentialsGain`) - name, status, details, ora's recommendation, and `estScoreGain` for the same id stay in `layers[].checks[]`, so nothing serializes twice; join on the id. The pre-sorted `issues` list and `scoreEvidence` are arrays of ids resolving in that map. Omit the parameter and the response is byte-identical to previous releases. On GET /api/checks, `essentials` instead adds `essentialsTier`, `essentialsBonusOnly`, and `essentialsExcluded` to every catalog check (an excluded check never enters the essentials model; since 1.19.1 that is the two robots.txt policy checks). Experimental: the audit schemas declare `siteType` only as a loose object, so its inner fields may change without a version bump, and pinning the contract major does not freeze them. `siteType` adds one response key, `siteType`: the same scan scored against what the site is (`content`, `business`, `app`, or `store`). It carries `type`, `source` (`declared`, `self-declared`, `classified`, `default`, `blocked`, or `unavailable`), `confidence` (`high` or `low`), `basis`, `score` (0-100 or null), per-layer `layers` (`id`, `score`, `maxScore`), per-check `states` (`req`, `bonus`, `gated`, or `emerging`), and `gatedOut` (each excluded check id with the gate that excluded it). A site-type score uses a different rubric from the canonical `score` and can land above or below it: never compare the two, only another `siteType.score` of the same `type`. When no type resolves, the key is `{ type: null, source: "unavailable", confidence: "low", score: null, layers: [] }` with a `basis` saying why. */
2295
+ include?: string;
2288
2296
  };
2289
2297
  };
2290
2298
  requestBody: {
@@ -2309,6 +2317,11 @@ export interface operations {
2309
2317
  force?: boolean;
2310
2318
  /** @description Store the result as disposable: it is excluded from the leaderboard, the sites-scanned coverage count, research statistics, and score history, is served with Cache-Control: no-store, and is deleted after a few days. Intended for a local site exposed through a tunnel, or any host that will not exist tomorrow. Public tunnel hostnames (trycloudflare.com, ngrok, and similar) are stored this way whether or not the flag is set. Rejected with 400 EPHEMERAL_CLOBBER when the domain already has a real stored scan, since a disposable result would replace it. */
2311
2319
  ephemeral?: boolean;
2320
+ /**
2321
+ * @description Optional. With `?include=siteType`, scores the response's `siteType` reading against this type instead of the inferred one. Absent, the type is inferred.
2322
+ * @enum {string}
2323
+ */
2324
+ siteType?: "content" | "business" | "app" | "store";
2312
2325
  };
2313
2326
  };
2314
2327
  };
@@ -2455,7 +2468,7 @@ export interface operations {
2455
2468
  };
2456
2469
  /**
2457
2470
  * Stream an agent-readiness scan as Server-Sent Events
2458
- * @description Runs a full agent-readiness scan on the given URL and streams progress as text/event-stream. Accepts a domain, MCP server URL, or MCP App URL (server that supports the MCP Apps extension `io.modelcontextprotocol/ui`) - the server auto-detects which kind of input was provided and selects the appropriate check set. Catalog-style listing pages are folded into the `mcp` kind by classifying the first validated embedded MCP URL. The stream emits a `kind_detecting` event immediately after the cheap reachability probe, followed by exactly one `kind_detected` event with payload `{ kind: 'domain' | 'mcp' | 'mcp-app', mcpUrl?: string, embeddedMcpUrls?: string[], hint?: string }` once URL-kind detection resolves. Subsequent events include `scan_init`, `layer_start`, `check_start`, `check_complete`, `layer_complete`, and finally `scan_complete` whose payload mirrors the ScanResult schema (including the optional `urlKind` field indicating the detected kind). The same freshness gate as POST /api/scan applies: a hit is a `kind_detected` frame followed by the terminal `scan_complete` event, rather than a full run. Rate limited two ways: 10 requests per minute per IP (burst) and a durable daily scan budget shared with the other scan entry points - both return 429 with a Retry-After header.
2471
+ * @description Runs a full agent-readiness scan on the given URL and streams progress as text/event-stream. Accepts a domain, MCP server URL, or MCP App URL (server that supports the MCP Apps extension `io.modelcontextprotocol/ui`) - the server auto-detects which kind of input was provided and selects the appropriate check set. Catalog-style listing pages are folded into the `mcp` kind by classifying the first validated embedded MCP URL. The stream emits a `kind_detecting` event immediately after the cheap reachability probe, followed by exactly one `kind_detected` event with payload `{ kind: 'domain' | 'mcp' | 'mcp-app', mcpUrl?: string, embeddedMcpUrls?: string[], hint?: string }` once URL-kind detection resolves. Progress events follow (the 200 response lists every event type), and finally `scan_complete` whose payload mirrors the ScanResult schema (including the optional `urlKind` field indicating the detected kind). The same freshness gate as POST /api/scan applies: a hit is a `kind_detected` frame followed by the terminal `scan_complete` event, rather than a full run. Rate limited two ways: 10 requests per minute per IP (burst) and a durable daily scan budget shared with the other scan entry points - both return 429 with a Retry-After header.
2459
2472
  */
2460
2473
  scanDomainStream: {
2461
2474
  parameters: {
@@ -2470,12 +2483,16 @@ export interface operations {
2470
2483
  force?: "1";
2471
2484
  /** @description Pass 1 to store the result as disposable - the same flag POST /api/scan takes in its body, with the same 400 EPHEMERAL_CLOBBER refusal when the domain already has a real stored scan. */
2472
2485
  ephemeral?: "1";
2473
- /** @description Pass `audit` to receive the versioned, allowlisted audit shape (AuditScanResult / AuditScoreResult) instead of the default body: every field is documented, carries a `contractVersion`, and internal fields are dropped. Omit it and the response is unchanged from previous releases. On GET /api/scan/stream, only the terminal `scan_complete` event's `result` is projected - all other events are identical to the default stream. */
2486
+ /** @description Pass `audit` to receive the versioned, allowlisted audit shape (AuditScanResult / AuditScoreResult) instead of the default body: every field is documented, carries a `contractVersion`, and internal fields are dropped. Omit it and the response is unchanged from previous releases. On GET /api/scan/stream, only the `scan_complete` event's `result` is projected - all other events are identical to the default stream. */
2474
2487
  format?: "audit";
2488
+ /** @description Opt-in expansion list (comma-separated). Experimental: the audit schemas declare `siteType` only as a loose object, so its inner fields may change without a version bump, and pinning the contract major does not freeze them. `siteType` adds one response key, `siteType`: the same scan scored against what the site is (`content`, `business`, `app`, or `store`). It carries `type`, `source` (`declared`, `self-declared`, `classified`, `default`, `blocked`, or `unavailable`), `confidence` (`high` or `low`), `basis`, `score` (0-100 or null), per-layer `layers` (`id`, `score`, `maxScore`), per-check `states` (`req`, `bonus`, `gated`, or `emerging`), and `gatedOut` (each excluded check id with the gate that excluded it). A site-type score uses a different rubric from the canonical `score` and can land above or below it: never compare the two, only another `siteType.score` of the same `type`. When no type resolves, the key is `{ type: null, source: "unavailable", confidence: "low", score: null, layers: [] }` with a `basis` saying why. On the stream the key rides the `scan_complete` event beside `result`, never inside it. */
2489
+ include?: "siteType";
2490
+ /** @description Read-time lens for `include=siteType`: scores the scan against this type instead of the resolved one, without rescanning or storing anything. An unrecognized value is ignored, not rejected. */
2491
+ siteType?: "content" | "business" | "app" | "store";
2475
2492
  };
2476
2493
  };
2477
2494
  responses: {
2478
- /** @description Server-Sent Events stream of scan progress. If MCP authentication is required, the stream ends with an error event carrying code MCP_AUTH_REQUIRED, mcpAuthRequired: true, mcpUrl and urlKind, without scan_complete or a score. With `?format=audit`, the terminal `scan_complete` event's `result` is `#/components/schemas/AuditScanResult`; every other event is unchanged. When a stored result inside the freshness window answers the request, the stream is a `kind_detected` frame followed by a terminal `scan_complete` event carrying `servedFromCache: true` and `resultAgeSeconds`, and the response carries an `Age` header. */
2495
+ /** @description Server-Sent Events stream of scan progress. If MCP authentication is required, the stream ends with an error event carrying code MCP_AUTH_REQUIRED, mcpAuthRequired: true, mcpUrl and urlKind, without scan_complete or a score. With `?format=audit`, the `scan_complete` event's `result` is `#/components/schemas/AuditScanResult`; every other event is unchanged. When a stored result inside the freshness window answers the request, the stream is a `kind_detected` frame followed by a terminal `scan_complete` event carrying `servedFromCache: true` and `resultAgeSeconds`, and the response carries an `Age` header. After `scan_complete`, a live scan may emit two correction events before the stream closes, both optional: `relevance_assessed` (`{ naCheckIds, reasons, score, grade }`, only when some checks are judged not applicable for this product) carries the corrected `score` and `grade`, and `summary_ready` (`{ agenticSummary }`) carries the summary. Consume events until the stream closes. Closing does not mean the analysis is final: when deep checks are still pending, the stream closes early and a background worker finishes relevance and summary later. Read GET /api/score/{domain} after the stream closes and poll it while `analysisStatus` is `partial`. A freshness-window hit is already final and emits neither event. Event types (the `type` field), in emission order: `kind_detecting` - reachability passed and URL-kind detection is running (no payload); `kind_detected` - detection resolved: `{ kind: 'domain' | 'mcp' | 'mcp-app', mcpUrl?, embeddedMcpUrls?, hint? }`, exactly once, before any `check_start`; `discovery_phase` (optional) - a context-gathering step, or after `scan_complete` a post-scan finalize step: `{ step, label?, stepIndex?, totalSteps? }`, zero or more times; `scan_init` - the check plan: `{ layerMaxScores, totalChecks?, checkRoster?, staticOnly? }`; may be sent twice, the later one is authoritative; `check_start` - one check slot started: `{ layerId, layerName, checkId, checkName, mcpKind?, mcpUrl? }`; `check_complete` - one check slot finished: `{ layerId, layerName, checkId, checkName, status, score, maxScore, details?, bonus?, maturity?, mcpKind?, mcpUrl? }`; `layer_complete` - every check in a layer finished: `{ layerId, layerName }`; `scan_complete` - the scored result, not the last frame: `{ result }` (AuditScanResult under `?format=audit`), plus `siteType` with `?include=siteType` and `servedFromCache` / `resultAgeSeconds` on a freshness hit; `relevance_assessed` (optional) - after `scan_complete`, only when checks were judged not applicable: `{ naCheckIds, reasons, score, grade }` with the corrected score and grade; `summary_ready` (optional) - after `scan_complete`: `{ agenticSummary }`; `error` (terminal, optional) - the scan failed and no `scan_complete` follows: `{ message }`, plus `code: 'MCP_AUTH_REQUIRED'`, `mcpAuthRequired`, `mcpUrl` and `urlKind` when an MCP server requires authentication. Read until the stream closes; only a terminal event is guaranteed to be the last frame. */
2479
2496
  200: {
2480
2497
  content: {
2481
2498
  "text/event-stream": string;
@@ -2536,17 +2553,19 @@ export interface operations {
2536
2553
  };
2537
2554
  /**
2538
2555
  * Get cached score for a domain
2539
- * @description Returns the most recent cached scan result for the given domain. Read-only: never triggers a scan. On miss (404) or when the previous scan got stuck mid-flight (200 with `analysisStatus: "stuck"`), the response carries a structured `next_action` envelope pointing at `POST /api/scan` so agent callers have a machine-parseable next step. Successful responses are cached for 1 hour; stuck, 404, and ephemeral (disposable, `urlKind: "ephemeral"`) responses are uncached (`Cache-Control: no-store`) so a successful re-scan is observable immediately and a deleted disposable row is never served from cache. Rate limited to 10 requests per minute per IP - returns 429 if exceeded.
2556
+ * @description Returns the most recent cached scan result for the given domain. Read-only: never triggers a scan. On miss (404) or when the previous scan got stuck mid-flight (200 with `analysisStatus: "stuck"`), the response carries a structured `next_action` envelope pointing at `POST /api/scan` so agent callers have a machine-parseable next step. Successful responses are cached for 1 hour; stuck, 404, and ephemeral (disposable, `urlKind: "ephemeral"`) responses are uncached (`Cache-Control: no-store`) so a successful re-scan is observable immediately and a deleted disposable row is never served from cache. Rate limited to 10 requests per minute per IP - returns 429 if exceeded. A scan API key exempts the caller, since this is the poll target for keyed scanning.
2540
2557
  */
2541
2558
  getScore: {
2542
2559
  parameters: {
2543
2560
  query?: {
2544
2561
  /** @description Pass 1 to include a `competitors` object in the response: the category top-5 leaders plus the neighbor window (2 above / self / 2 below) drawn from the leaderboard. Returned only for domains with a market category - unclassified domains (Community, or no leaderboard row) get `competitors: null`. Omitted by default so the plain response stays lean. */
2545
2562
  competitors?: "1";
2546
- /** @description Pass `audit` to receive the versioned, allowlisted audit shape (AuditScanResult / AuditScoreResult) instead of the default body: every field is documented, carries a `contractVersion`, and internal fields are dropped. Omit it and the response is unchanged from previous releases. On GET /api/scan/stream, only the terminal `scan_complete` event's `result` is projected - all other events are identical to the default stream. */
2563
+ /** @description Pass `audit` to receive the versioned, allowlisted audit shape (AuditScanResult / AuditScoreResult) instead of the default body: every field is documented, carries a `contractVersion`, and internal fields are dropped. Omit it and the response is unchanged from previous releases. On GET /api/scan/stream, only the `scan_complete` event's `result` is projected - all other events are identical to the default stream. */
2547
2564
  format?: "audit";
2548
- /** @description Opt-in expansion list (comma-separated). `essentials` adds one response key, `essentials`: an alternate reading of the same scan carrying its own `score` (0-100 or null - required checks share 80 points, recommended 20, forward-looking signals upside-only), the required/recommended buckets, label copy, per-surface sub-scores, access signals, and a `checks` map keyed by check id. That map holds the essentials INTERPRETATION only (tier, bonus, fraction, occurrences, `essentialsGain`) - name, status, details, ora's recommendation, and `estScoreGain` for the same id stay in `layers[].checks[]`, so nothing serializes twice; join on the id. The pre-sorted `issues` list and `scoreEvidence` are arrays of ids resolving in that map. Omit the parameter and the response is byte-identical to previous releases. On GET /api/checks, `essentials` instead adds `essentialsTier`, `essentialsBonusOnly`, and `essentialsExcluded` to every catalog check (an excluded check never enters the essentials model; since 1.19.1 that is the two robots.txt policy checks). */
2549
- include?: "essentials";
2565
+ /** @description Opt-in expansion list (comma-separated). `essentials` adds one response key, `essentials`: an alternate reading of the same scan carrying its own `score` (0-100 or null - required checks share 80 points, recommended 20, forward-looking signals upside-only), the required/recommended buckets, label copy, per-surface sub-scores, access signals, and a `checks` map keyed by check id. That map holds the essentials INTERPRETATION only (tier, bonus, fraction, occurrences, `essentialsGain`) - name, status, details, ora's recommendation, and `estScoreGain` for the same id stay in `layers[].checks[]`, so nothing serializes twice; join on the id. The pre-sorted `issues` list and `scoreEvidence` are arrays of ids resolving in that map. Omit the parameter and the response is byte-identical to previous releases. On GET /api/checks, `essentials` instead adds `essentialsTier`, `essentialsBonusOnly`, and `essentialsExcluded` to every catalog check (an excluded check never enters the essentials model; since 1.19.1 that is the two robots.txt policy checks). Experimental: the audit schemas declare `siteType` only as a loose object, so its inner fields may change without a version bump, and pinning the contract major does not freeze them. `siteType` adds one response key, `siteType`: the same scan scored against what the site is (`content`, `business`, `app`, or `store`). It carries `type`, `source` (`declared`, `self-declared`, `classified`, `default`, `blocked`, or `unavailable`), `confidence` (`high` or `low`), `basis`, `score` (0-100 or null), per-layer `layers` (`id`, `score`, `maxScore`), per-check `states` (`req`, `bonus`, `gated`, or `emerging`), and `gatedOut` (each excluded check id with the gate that excluded it). A site-type score uses a different rubric from the canonical `score` and can land above or below it: never compare the two, only another `siteType.score` of the same `type`. When no type resolves, the key is `{ type: null, source: "unavailable", confidence: "low", score: null, layers: [] }` with a `basis` saying why. */
2566
+ include?: string;
2567
+ /** @description Read-time lens for `include=siteType`: scores the scan against this type instead of the resolved one, without rescanning or storing anything. An unrecognized value is ignored, not rejected. */
2568
+ siteType?: "content" | "business" | "app" | "store";
2550
2569
  };
2551
2570
  path: {
2552
2571
  /** @description The domain to look up (e.g. stripe.com). URL-encoded full URLs are normalized to their hostname. */
@@ -3066,7 +3085,7 @@ export interface operations {
3066
3085
  };
3067
3086
  /**
3068
3087
  * Run an agent journey against a domain
3069
- * @description Triggers a real agent run: an AI agent (harness + model) attempts a task (an intent) against the given domain, and ora records the trajectory and derives insights. Two-step flow: this endpoint returns fast with a run record whose `stream_url` serves the live trajectory as Server-Sent Events; poll GET /api/journey/runs/{id} instead if you do not want the stream. Two caller tiers. Anonymous: curated intents only (see GET /api/journey/intents) - the server derives the actual agent prompt from the intent id, so no free-text prompt can reach the engine. Keyed: a caller presenting an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora) may instead send bounded free text (`intent.custom`, 4 to 300 characters, with `intent.domain` required), which the server anchors to the requested domain before dispatch and echoes back on the 201. Free text without a recognized key is a 401 with code CUSTOM_INTENT_REQUIRES_KEY; a curated body with a missing or unrecognized key is never an error and simply runs on the anonymous tier. The keyed free-text tier is also reachable from the ora CLI (ax deep-journey --task, v0.5+). Only publicly runnable agents are accepted (see GET /api/journey/agents). Unknown body fields are rejected (strict schema). Anonymous rate limits, three ways: a 20-per-minute burst cap per IP; a per-target cap of 100 runs per rolling 24h per (domain, intent, harness, model) - when a target is over the cap the response is HTTP 200 with the most recent stored run for that target (`rate_limited: true`) plus Retry-After, the freshness analog: a denied trigger still returns the newest result and consumes nothing; and a durable per-caller cap of 200 runs per rolling 24h per IP - exceeded, that one is a real 429 with `retry_after_ms` (there is no cached result to serve for a caller). Keyed rate limit, one way: 1000 runs per rolling 24h per key, exhaustion being the same 429 with `retry_after_ms`. A keyed caller skips both the burst cap and the per-target cap - free text fragments the target key, so a per-target window over it could never fill. Successful and capped responses carry X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers describing exactly one window: the per-target window on an anonymous response, the per-key caller window on a keyed one. Note: journey insights use the 5-layer journey taxonomy (discovery, identity, access, payments, experience), deliberately distinct from the 4 scoring layers of the audit report (POST /api/scan) - never map between the two.
3088
+ * @description Triggers a real agent run: an AI agent (harness + model) attempts a task (an intent) against the given domain, and ora records the trajectory and derives insights. Two-step flow: this endpoint returns fast with a run record whose `stream_url` serves the live trajectory as Server-Sent Events; the stream is also what saves the finished run, so hold it open until its `result` or `error` frame (reopen it if the connection drops; it resumes the same run without re-executing). GET /api/journey/runs/{id} reads what a stream saved: a run nobody streams stays `running`. Two caller tiers. Anonymous: curated intents only (see GET /api/journey/intents) - the server derives the actual agent prompt from the intent id, so no free-text prompt can reach the engine. Keyed: a caller presenting an ora-issued partner API key ('Authorization: Bearer <key>', issued manually - contact ora) may instead send bounded free text (`intent.custom`, 4 to 300 characters, with `intent.domain` required), which the server anchors to the requested domain before dispatch and echoes back on the 201. Free text without a recognized key is a 401 with code CUSTOM_INTENT_REQUIRES_KEY; a curated body with a missing or unrecognized key is never an error and simply runs on the anonymous tier. The keyed free-text tier is also reachable from the ora CLI (ax deep-journey --task, v0.5+). Only publicly runnable agents are accepted (see GET /api/journey/agents). Unknown body fields are rejected (strict schema). Anonymous rate limits, three ways: a 20-per-minute burst cap per IP; a per-target cap of 100 runs per rolling 24h per (domain, intent, harness, model) - when a target is over the cap the response is HTTP 200 with the most recent stored run for that target (`rate_limited: true`) plus Retry-After, the freshness analog: a denied trigger still returns the newest result and consumes nothing; and a durable per-caller cap of 20 runs per rolling 24h per IP - exceeded, that one is a real 429 with `retry_after_ms` (there is no cached result to serve for a caller). Keyed rate limit, one way: 1000 runs per rolling 24h per key, exhaustion being the same 429 with `retry_after_ms`. A keyed caller skips both the burst cap and the per-target cap - free text fragments the target key, so a per-target window over it could never fill. Successful and capped responses carry X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers describing exactly one window: the per-target window on an anonymous response, the per-key caller window on a keyed one. Note: journey insights use the 5-layer journey taxonomy (discovery, identity, access, payments, experience), deliberately distinct from the 4 scoring layers of the audit report (POST /api/scan) - never map between the two.
3070
3089
  */
3071
3090
  createJourneyRun: {
3072
3091
  requestBody: {
@@ -3129,7 +3148,7 @@ export interface operations {
3129
3148
  "application/json": components["schemas"]["JourneyCappedRun"];
3130
3149
  };
3131
3150
  };
3132
- /** @description Run created and dispatched. Open `stream_url` (SSE) to watch the trajectory live, or poll GET /api/journey/runs/{id}. A keyed custom run gets its own free text back as `intent` here - the create response is the only place any intent text is published, so GET /api/journey/runs/{id} and the capped 200 never carry it, and a curated run has no `intent` at all. */
3151
+ /** @description Run created and dispatched. Open `stream_url` (SSE) and hold it to its `result` or `error` frame: the stream is what saves the finished run, which GET /api/journey/runs/{id} then reads. A keyed custom run gets its own free text back as `intent` here - the create response is the only place any intent text is published, so GET /api/journey/runs/{id} and the capped 200 never carry it, and a curated run has no `intent` at all. */
3133
3152
  201: {
3134
3153
  headers: {
3135
3154
  /** @description Size of the one window this response describes: the per-target window (100 runs per rolling 24h) for an anonymous caller, the per-key caller window (1000 runs per rolling 24h) for a keyed one */
@@ -3155,7 +3174,7 @@ export interface operations {
3155
3174
  "application/json": components["schemas"]["ErrorResponse"];
3156
3175
  };
3157
3176
  };
3158
- /** @description Caller limit exceeded - the 20-per-minute burst cap (anonymous callers only; a keyed caller skips it), or the durable per-caller budget (200 runs per rolling 24h per IP anonymous, 1000 per rolling 24h per key; body carries `retry_after_ms`). Per-TARGET saturation is the 200 above, not this. */
3177
+ /** @description Caller limit exceeded - the 20-per-minute burst cap (anonymous callers only; a keyed caller skips it), or the durable per-caller budget (20 runs per rolling 24h per IP anonymous, 1000 per rolling 24h per key; body carries `retry_after_ms`). Per-TARGET saturation is the 200 above, not this. */
3159
3178
  429: {
3160
3179
  headers: {
3161
3180
  /** @description Seconds until next allowed request */
@@ -3219,7 +3238,7 @@ export interface operations {
3219
3238
  "application/json": components["schemas"]["JourneyDomainRun"] | components["schemas"]["JourneyDomainRunGraph"];
3220
3239
  };
3221
3240
  };
3222
- /** @description A new run was dispatched and is running (`dispatched` is true, no `result` yet). Open `stream_url` for the live trajectory, or poll GET /api/journey/runs/{id}. The record fields are identical across views, so this body is the same whichever view is in effect. */
3241
+ /** @description A new run was dispatched and is running (`dispatched` is true, no `result` yet). Open `stream_url` and hold it to its `result` or `error` frame: the stream is what saves the finished run, which a later call here or GET /api/journey/runs/{id} then reads. The record fields are identical across views, so this body is the same whichever view is in effect. */
3223
3242
  201: {
3224
3243
  content: {
3225
3244
  "application/json": components["schemas"]["JourneyDomainRun"] | components["schemas"]["JourneyDomainRunGraph"];
@@ -1,2 +1,2 @@
1
1
  /** The ora contract version (spec info.version) these types were generated from. */
2
- export declare const BUILT_AGAINST = "1.25.0";
2
+ export declare const BUILT_AGAINST = "1.27.0";
package/dist/index.cjs CHANGED
@@ -35,7 +35,7 @@ __export(src_exports, {
35
35
  module.exports = __toCommonJS(src_exports);
36
36
 
37
37
  // src/contract/version.ts
38
- var BUILT_AGAINST = "1.25.0";
38
+ var BUILT_AGAINST = "1.27.0";
39
39
 
40
40
  // src/contract/index.ts
41
41
  function minor(version) {
@@ -78,13 +78,22 @@ function watchdog(ms) {
78
78
  tripped: () => fired
79
79
  };
80
80
  }
81
- async function errorBodyText(res) {
81
+ async function errorBody(res) {
82
+ let payload = null;
82
83
  try {
83
- const payload = await res.json();
84
- return payload.message || payload.error || `HTTP ${res.status}`;
84
+ payload = await res.clone().json();
85
85
  } catch {
86
- return `HTTP ${res.status}`;
87
86
  }
87
+ res.body?.cancel().catch(() => {
88
+ });
89
+ return {
90
+ message: payload?.message || payload?.error || `HTTP ${res.status}`,
91
+ code: payload?.code ?? null,
92
+ payload
93
+ };
94
+ }
95
+ async function errorBodyText(res) {
96
+ return (await errorBody(res)).message;
88
97
  }
89
98
  var pause = (ms) => new Promise((r) => setTimeout(r, ms));
90
99
 
@@ -95,6 +104,14 @@ var POLL_EVERY_MS = 2e3;
95
104
  var POLL_LIMIT = 45;
96
105
  var BAR_CELLS = 14;
97
106
  var AuditApiError = class extends Error {
107
+ code;
108
+ payload;
109
+ constructor(message, options = {}) {
110
+ super(message);
111
+ this.name = "AuditApiError";
112
+ this.code = options.code ?? null;
113
+ this.payload = options.payload;
114
+ }
98
115
  };
99
116
  function authHeaders(apiKey) {
100
117
  return apiKey ? { authorization: `Bearer ${apiKey}` } : {};
@@ -142,7 +159,11 @@ async function consumeScanStream(base, target, options) {
142
159
  }
143
160
  if (!res.ok || !res.body) {
144
161
  dog.disarm();
145
- throw new AuditApiError(`ora audit failed: ${await errorBodyText(res)}`);
162
+ const body = await errorBody(res);
163
+ throw new AuditApiError(`ora audit failed: ${body.message}`, {
164
+ code: body.code,
165
+ payload: body.payload
166
+ });
146
167
  }
147
168
  const narrate = progressNarrator();
148
169
  const utf8 = new TextDecoder();
@@ -172,7 +193,8 @@ async function consumeScanStream(base, target, options) {
172
193
  if (line) options.progress?.(line);
173
194
  if (event.type === "error") {
174
195
  throw new AuditApiError(
175
- `ora audit failed: ${typeof event.message === "string" ? event.message : "scan error"}`
196
+ `ora audit failed: ${typeof event.message === "string" ? event.message : "scan error"}`,
197
+ { code: typeof event.code === "string" ? event.code : null, payload: event }
176
198
  );
177
199
  }
178
200
  if (event.type === "scan_complete" && event.result) {
@@ -279,8 +301,21 @@ var PUBLIC_BASE2 = "https://ora.ai";
279
301
  var STREAM_IDLE_MS2 = 12e4;
280
302
  var POLL_EVERY_MS2 = 5e3;
281
303
  var POLL_LIMIT2 = 180;
304
+ var FOLLOW_BUDGET_MS = 15 * 6e4;
305
+ var MAX_RETRY_AFTER_MS = 6e4;
306
+ var STREAM_REOPENS = 5;
307
+ var STREAM_REOPEN_PAUSE_MS = 2e3;
282
308
  var DeepJourneyApiError = class extends Error {
283
309
  };
310
+ var JourneyStreamHttpError = class extends DeepJourneyApiError {
311
+ constructor(message, status, retryAfterMs) {
312
+ super(message);
313
+ this.status = status;
314
+ this.retryAfterMs = retryAfterMs;
315
+ }
316
+ status;
317
+ retryAfterMs;
318
+ };
284
319
  function apiBase(baseUrl) {
285
320
  return (baseUrl ?? process.env.ORA_API_URL ?? PUBLIC_BASE2).replace(/\/+$/, "");
286
321
  }
@@ -350,7 +385,7 @@ async function triggerRun(base, target, options) {
350
385
  }
351
386
  if (res.status === 429) {
352
387
  const wait = res.headers.get("retry-after");
353
- const caps = options.apiKey ? "keyed allowance: 1000 runs per 24h per key" : "burst: 20/min/IP; daily: 200 runs per 24h per IP \u2014 an ora partner API key raises this to 1000/24h per key: set ORA_PARTNER_API_KEY or pass --api-key";
388
+ const caps = options.apiKey ? "keyed allowance: 1000 runs per 24h per key" : "burst: 20/min/IP; daily: 20 runs per 24h per IP \u2014 an ora partner API key raises this to 1000/24h per key: set ORA_PARTNER_API_KEY or pass --api-key";
354
389
  throw new DeepJourneyApiError(
355
390
  `ora journey caller limit exceeded${wait ? ` \u2014 retry after ${formatWait(Number(wait) * 1e3)}` : ""} (${caps})`
356
391
  );
@@ -396,7 +431,12 @@ async function followJourneyStream(base, streamPath, options) {
396
431
  let res;
397
432
  try {
398
433
  res = await fetch(target, {
399
- headers: { accept: "text/event-stream" },
434
+ headers: {
435
+ accept: "text/event-stream",
436
+ // A recognized key lifts the stream's per-IP limit on a run that
437
+ // already exists, which reopening after a drop relies on.
438
+ ...options.apiKey ? { authorization: `Bearer ${options.apiKey}` } : {}
439
+ },
400
440
  signal: dog.signal
401
441
  });
402
442
  } catch (cause) {
@@ -407,7 +447,12 @@ async function followJourneyStream(base, streamPath, options) {
407
447
  }
408
448
  if (!res.ok || !res.body) {
409
449
  dog.disarm();
410
- throw new DeepJourneyApiError(`ora journey stream failed: ${await errorBodyText(res)}`);
450
+ const retryAfterS = Number(res.headers.get("retry-after"));
451
+ throw new JourneyStreamHttpError(
452
+ `ora journey stream failed (${res.status}): ${await errorBodyText(res)}`,
453
+ res.status,
454
+ Number.isFinite(retryAfterS) && retryAfterS > 0 ? retryAfterS * 1e3 : void 0
455
+ );
411
456
  }
412
457
  const utf8 = new TextDecoder();
413
458
  const collected = {};
@@ -461,14 +506,38 @@ async function followJourneyStream(base, streamPath, options) {
461
506
  }
462
507
  return collected;
463
508
  }
509
+ async function streamToEnd(base, streamPath, options, deadline) {
510
+ const pauseMs = options.reopenPauseMs ?? STREAM_REOPEN_PAUSE_MS;
511
+ let lastFailure;
512
+ let waitMs = 0;
513
+ for (let attempt = 0; attempt <= STREAM_REOPENS && Date.now() < deadline; attempt++) {
514
+ if (attempt > 0) {
515
+ options.progress?.("stream dropped \u2014 reopening");
516
+ await pause(waitMs);
517
+ }
518
+ waitMs = pauseMs;
519
+ try {
520
+ const streamed = await followJourneyStream(base, streamPath, options);
521
+ if (streamed.result || streamed.errorMessage) return streamed.errorMessage;
522
+ lastFailure = new DeepJourneyApiError("ora journey stream closed before the run ended");
523
+ } catch (cause) {
524
+ lastFailure = cause;
525
+ if (cause instanceof JourneyStreamHttpError) {
526
+ if (cause.status !== 429) throw cause;
527
+ waitMs = Math.min(cause.retryAfterMs ?? pauseMs, MAX_RETRY_AFTER_MS);
528
+ }
529
+ }
530
+ }
531
+ throw lastFailure ?? new DeepJourneyApiError("ora journey stream was never opened");
532
+ }
464
533
  function fetchRunDetail(base, runId) {
465
534
  return getJson(`${base}/api/journey/runs/${encodeURIComponent(runId)}`);
466
535
  }
467
- async function awaitByPolling(base, runId, options) {
536
+ async function awaitByPolling(base, runId, options, deadline) {
468
537
  const every = options.pollEveryMs ?? POLL_EVERY_MS2;
469
538
  const limit = options.pollLimit ?? POLL_LIMIT2;
470
539
  let latest = await fetchRunDetail(base, runId);
471
- for (let round = 0; round < limit && latest.status === "running"; round++) {
540
+ for (let round = 0; round < limit && latest.status === "running" && Date.now() < deadline; round++) {
472
541
  options.progress?.("agent working\u2026 (polling)");
473
542
  await pause(every);
474
543
  try {
@@ -490,16 +559,18 @@ async function performDeepJourney(target, options) {
490
559
  options.progress?.("target at its 24h cap \u2014 fetching the most recent stored run");
491
560
  }
492
561
  let engineError;
493
- if (!options.noStream && record.status === "running") {
562
+ let streamFailure;
563
+ if (record.status === "running") {
564
+ const deadline = Date.now() + (options.followBudgetMs ?? FOLLOW_BUDGET_MS);
565
+ const streamOptions = options.noStream ? { ...options, onTrajectory: void 0 } : options;
494
566
  try {
495
- const streamed = await followJourneyStream(base, record.stream_url, options);
496
- engineError = streamed.errorMessage;
497
- } catch {
498
- options.progress?.("stream went quiet \u2014 switching to polling");
499
- await awaitByPolling(base, record.id, options);
567
+ engineError = await streamToEnd(base, record.stream_url, streamOptions, deadline);
568
+ } catch (cause) {
569
+ if (cause instanceof JourneyStreamHttpError && cause.status !== 429) throw cause;
570
+ streamFailure = cause instanceof Error ? cause.message : String(cause);
571
+ options.progress?.(`stream unavailable (${streamFailure}) \u2014 polling`);
572
+ await awaitByPolling(base, record.id, options, deadline);
500
573
  }
501
- } else if (options.noStream && record.status === "running") {
502
- await awaitByPolling(base, record.id, options);
503
574
  }
504
575
  const detail = await awaitDetailSettled(base, record.id, options);
505
576
  if (detail.status === "running") {
@@ -507,7 +578,7 @@ async function performDeepJourney(target, options) {
507
578
  throw new DeepJourneyApiError(`ora journey run failed: ${engineError}`);
508
579
  }
509
580
  throw new DeepJourneyApiError(
510
- `run ${record.id} is still executing \u2014 the ${options.noStream ? "poll budget ran out" : "stream ended"} before a terminal result. Check ${base}/api/journey/runs/${record.id} shortly`
581
+ `run ${record.id} is still executing \u2014 ${streamFailure ? `the stream could not be followed (${streamFailure}) and polling ran out of time` : "the stream ended"} before a terminal result. Check ${base}/api/journey/runs/${record.id} shortly`
511
582
  );
512
583
  }
513
584
  warnOnNewerContract(detail.contractVersion);