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 +4 -4
- package/dist/api/audit.d.ts +22 -1
- package/dist/api/deep-journey.d.ts +11 -3
- package/dist/api/shared.d.ts +13 -0
- package/dist/contract/types.gen.d.ts +42 -23
- package/dist/contract/version.d.ts +1 -1
- package/dist/index.cjs +92 -21
- package/dist/index.js +92 -21
- package/dist/main.cjs +61 -60
- package/package.json +1 -1
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
|
|
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
|
|
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
|
-
|
|
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` |
|
|
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.
|
package/dist/api/audit.d.ts
CHANGED
|
@@ -1,7 +1,28 @@
|
|
|
1
1
|
import type { AuditScanResult, AuditScoreResult } from "../contract";
|
|
2
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
92
|
-
*
|
|
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
|
*/
|
package/dist/api/shared.d.ts
CHANGED
|
@@ -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.
|
|
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;
|
|
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.
|
|
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
|
|
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.
|
|
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
|
|
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.
|
|
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.
|
|
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
|
|
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?:
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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?:
|
|
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;
|
|
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
|
|
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 (
|
|
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`
|
|
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.
|
|
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.
|
|
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
|
|
81
|
+
async function errorBody(res) {
|
|
82
|
+
let payload = null;
|
|
82
83
|
try {
|
|
83
|
-
|
|
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
|
-
|
|
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:
|
|
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: {
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
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 ${
|
|
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);
|