ax 0.8.2 → 0.9.0

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
@@ -31,6 +31,7 @@ Five commands:
31
31
  - **`deep-journey <url>`** — run a real AI agent at a site on one of ora's curated tasks through the public journey API: no key, no workspace. A partner API key unlocks free-text tasks (`--task`) and a larger allowance.
32
32
  - **`journey "<intent>"`** — send a real AI agent (claude-code, codex, …) at a site and watch its navigation live as a boxed node-graph, then get the scored insight, tokens, and cost. Partner-only: needs an `ORA_API_KEY` (see [For ora partners](#for-ora-partners)).
33
33
  - **`skill [name]`** — list, print, or install ora's agent skills, digest-verified from the public registry.
34
+ - **`generate-files <domain>`** — draft the agent discovery files a site publishes about itself (`ard.json`, `ai-catalog.json`, `poppy.json`) into `.well-known/`, filled in from ora's last scan of the domain.
34
35
 
35
36
  ## audit
36
37
 
@@ -259,6 +260,18 @@ ax skill --json # the raw registry index
259
260
 
260
261
  Skills come from ora's public registry (`https://ora.ai/.well-known/agent-skills/`) and every byte is verified against the registry's sha256 digest before it is printed or installed. Skill content is never bundled into this package. `--dir <path>` overrides the install directory, and `--json` prints the registry index as JSON instead of the formatted list.
261
262
 
263
+ ## generate-files
264
+
265
+ ```
266
+ ax generate-files example.com # writes ./.well-known/{ard,ai-catalog,poppy}.json
267
+ ax generate-files example.com --out public # writes public/.well-known/... (your site's static root)
268
+ ax generate-files example.com --json # ora's payload, files + notes, nothing written
269
+ ```
270
+
271
+ Drafts the files agents look for under a site's `/.well-known/`: an [Agentic Resource Discovery](https://agenticresourcediscovery.org/) catalog (`ard.json`, the same document as `ai-catalog.json` for the [AI Catalog Standard](https://ai-catalog.io/)'s path) and a [Personal Agent Protocol](https://personalagentprotocol.org/docs/spec) `poppy.json`. ora builds them from what it already knows about the domain (its last scan; no new crawl), so run `ax audit` first for a domain ora has never scanned - without a scan the catalog lists only the website. Every catalog entry is anchored to your domain, not to ora. The `poppy.json` is the minimal valid document (signed-out browsing); the OAuth issuer and APIs ora saw are printed as notes rather than written into it, because naming them is only correct once they implement the protocol. These are drafts: read each file and its notes before you publish.
272
+
273
+ Nothing is overwritten: if any target file exists, nothing is written and the command exits `2` - pass `--force` to overwrite, or `--out <dir>` to write elsewhere. Exit codes: `0` written, `2` usage (bad domain, files exist), `3` API. Same files as the web generator at [directory.ora.ai/generate](https://directory.ora.ai/generate) and `GET https://ora.ai/api/agent-files/{domain}`.
274
+
262
275
  ## Library use
263
276
 
264
277
  The same contract-typed client the CLI uses is importable:
@@ -270,7 +283,7 @@ const { result } = await audit("stripe.com");
270
283
  console.log(result.score, result.grade, result.topFixes);
271
284
  ```
272
285
 
273
- `result` is the raw versioned audit payload (`AuditScanResult` / `AuditScoreResult`, generated from ora's OpenAPI spec). `fetchSkill` / `fetchSkillIndex` expose the digest-verified skill registry.
286
+ `result` is the raw versioned audit payload (`AuditScanResult` / `AuditScoreResult`, generated from ora's OpenAPI spec). `fetchSkill` / `fetchSkillIndex` expose the digest-verified skill registry, and `fetchAgentFiles` the agent files generator.
274
287
 
275
288
  The public journey client is exported too — the same no-key path as `ax deep-journey`:
276
289
 
@@ -362,7 +375,7 @@ A `.env` in the working directory is read on startup — copy `.env.example` and
362
375
 
363
376
  | Var | Used by | Default | Purpose |
364
377
  |---|---|---|---|
365
- | `ORA_API_URL` | audit, deep-journey, skill | `https://ora.ai` | Public API base (no auth) |
378
+ | `ORA_API_URL` | audit, deep-journey, skill, generate-files | `https://ora.ai` | Public API base (no auth) |
366
379
  | `ORA_PLATFORM_URL` | journey, audit `--tunnel ora` | `https://api.agentfront.sh` | Authenticated platform API base |
367
380
  | `ORA_TUNNEL` | audit | — (optional) | `ora` opens ora's own tunnel for a local target (same as `--tunnel ora`) |
368
381
  | `ORA_TUNNEL_CMD` | audit | — (optional) | Tunnel command for a local target (same as `--tunnel-cmd`); wins over `ORA_TUNNEL` |
@@ -0,0 +1,48 @@
1
+ export interface AgentFile {
2
+ /** Where the domain serves the file, e.g. "/.well-known/ard.json". */
3
+ path: string;
4
+ spec: {
5
+ name: string;
6
+ version: string;
7
+ url: string;
8
+ };
9
+ /** The JSON document to publish at `path`. */
10
+ content: Record<string, unknown>;
11
+ /** What to review or add before publishing. */
12
+ notes: string[];
13
+ }
14
+ export interface AgentFilesBundle {
15
+ domain: string;
16
+ productName: string;
17
+ /** When ora last scanned the domain; null when it never has. */
18
+ scannedAt: string | null;
19
+ files: AgentFile[];
20
+ }
21
+ /**
22
+ * Any failure to get the files from ora. `status` is the HTTP status when ora
23
+ * answered (400 = not a public domain), and `payload` the error body exactly as
24
+ * served, which is what `--json` prints.
25
+ */
26
+ export declare class AgentFilesApiError extends Error {
27
+ readonly status: number | null;
28
+ readonly payload: unknown;
29
+ constructor(message: string, options?: {
30
+ status?: number | null;
31
+ payload?: unknown;
32
+ });
33
+ }
34
+ export interface AgentFilesOptions {
35
+ /** Base URL override; otherwise $ORA_API_URL, otherwise https://ora.ai. */
36
+ baseUrl?: string;
37
+ }
38
+ export declare function isSafeAgentFilePath(path: string): boolean;
39
+ /**
40
+ * Drop trailing slashes with a scan rather than `/\/+$/`: that regex retries
41
+ * at every `/` of a long run that is not at the end, quadratic on input a
42
+ * caller controls (CodeQL js/polynomial-redos).
43
+ */
44
+ export declare function trimTrailingSlashes(value: string): string;
45
+ /** Strip a scheme and trailing slash so `https://example.com/` reads as a domain. */
46
+ export declare function normalizeDomainInput(input: string): string;
47
+ /** Fetch the drafted files for `domain` from ora. */
48
+ export declare function fetchAgentFiles(domain: string, options?: AgentFilesOptions): Promise<AgentFilesBundle>;
@@ -128,6 +128,13 @@ export interface paths {
128
128
  */
129
129
  get: operations["ardGetCatalogDump"];
130
130
  };
131
+ "/api/agent-files/{domain}": {
132
+ /**
133
+ * Draft a domain's own agent discovery files (ard.json, ai-catalog.json, poppy.json)
134
+ * @description Drafts the agent discovery files a domain publishes about itself: /.well-known/ard.json (Agentic Resource Discovery), /.well-known/ai-catalog.json (the same catalog at the AI Catalog Standard's path) and /.well-known/poppy.json (Personal Agent Protocol, Draft 0.1). Built from what ora already holds for the domain - no live crawl - so a domain ora never scanned still gets a valid minimal set (a catalog listing its website, a poppy.json for signed-out browsing) with scannedAt null. Every catalog entry is anchored to the domain itself (urn:air:<domain>:..., identity https://<domain>), never to ora, and carries only https URLs on the domain or its subdomains: anything the scan saw on another host is named in the file's notes instead. MCP servers are listed by their server card (the card the scan found, else the reserved <server-url>/server-card location, which the notes ask the owner to serve). The poppy.json is the minimal valid document; what ora saw that a fuller one could name (an OAuth issuer, MCP servers, an OpenAPI description) is listed in that file's notes. Review every file before publishing it. A leading www. is dropped, and any spelling other than the canonical domain answers 308 to /api/agent-files/<domain>. Sends Access-Control-Allow-Origin: * and is CDN-cached. Rate limited to 60 requests per minute per IP - returns 429 if exceeded. Also used by the generator page at directory.ora.ai/generate and by `npx ax generate-files <domain>`.
135
+ */
136
+ get: operations["generateAgentFiles"];
137
+ };
131
138
  "/api/ard/jwks": {
132
139
  /**
133
140
  * Get the public JWK set for verifying signed attestations (Agentic Resource Discovery)
@@ -145,7 +152,7 @@ export interface paths {
145
152
  "/api/journey/runs": {
146
153
  /**
147
154
  * 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; 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.
155
+ * @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). On top of those, all anonymous callers together share a ceiling of 3000 runs per rolling 24h; when it is full every anonymous trigger gets the same 429 with `retry_after_ms` until the oldest run ages out, while keyed callers are unaffected. 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
156
  */
150
157
  post: operations["createJourneyRun"];
151
158
  };
@@ -424,7 +431,7 @@ export interface components {
424
431
  * @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
432
  * @enum {string}
426
433
  */
427
- contractVersion: "1.27.0";
434
+ contractVersion: "1.30.0";
428
435
  /**
429
436
  * @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
437
  * @enum {boolean}
@@ -627,7 +634,7 @@ export interface components {
627
634
  * @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.
628
635
  * @enum {string}
629
636
  */
630
- contractVersion: "1.27.0";
637
+ contractVersion: "1.30.0";
631
638
  /** @description Wall-clock duration of the scan that produced this stored result */
632
639
  durationMs: number | null;
633
640
  /**
@@ -675,7 +682,7 @@ export interface components {
675
682
  * @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.
676
683
  * @enum {string}
677
684
  */
678
- contractVersion: "1.27.0";
685
+ contractVersion: "1.30.0";
679
686
  /** @description The four scored layers in scoring order, with display name and current weight. */
680
687
  layers: {
681
688
  /** @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'. */
@@ -774,7 +781,7 @@ export interface components {
774
781
  * @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.
775
782
  * @enum {string}
776
783
  */
777
- contractVersion: "1.27.0";
784
+ contractVersion: "1.30.0";
778
785
  /** @description The apex domain derived from the requested URL. */
779
786
  domain: string;
780
787
  /** @description The normalized URL the run targeted. */
@@ -2169,6 +2176,35 @@ export interface components {
2169
2176
  /** @description Optional recovery hint (e.g. /api/scan on NOT_FOUND). */
2170
2177
  next?: string;
2171
2178
  };
2179
+ /** @description Draft agent discovery files for one domain, returned by GET /api/agent-files/{domain}. */
2180
+ AgentFilesBundle: {
2181
+ /** @description The domain the files speak for (leading www. dropped). */
2182
+ domain: string;
2183
+ /** @description The product name used in the files; the domain itself when ora knows no name. */
2184
+ productName: string;
2185
+ /**
2186
+ * Format: date-time
2187
+ * @description When ora last scanned the domain; null when it never has, in which case the files carry only what the domain alone implies.
2188
+ */
2189
+ scannedAt: string | null;
2190
+ files: components["schemas"]["AgentFile"][];
2191
+ };
2192
+ AgentFile: {
2193
+ /** @description Where the domain serves the file, e.g. /.well-known/ard.json. */
2194
+ path: string;
2195
+ /** @description The standard the file follows. */
2196
+ spec: {
2197
+ name: string;
2198
+ version: string;
2199
+ url: string;
2200
+ };
2201
+ /** @description The JSON document to publish at path. */
2202
+ content: {
2203
+ [key: string]: unknown;
2204
+ };
2205
+ /** @description What to review or add before publishing, in plain sentences. */
2206
+ notes: string[];
2207
+ };
2172
2208
  McpAuthRequiredResponse: {
2173
2209
  /** @description Why the MCP server could not be inspected. */
2174
2210
  error: string;
@@ -2322,6 +2358,8 @@ export interface operations {
2322
2358
  * @enum {string}
2323
2359
  */
2324
2360
  siteType?: "content" | "business" | "app" | "store";
2361
+ /** @description Optional, defaults to false. A few checks confirm that an endpoint the site declares for agents enforces what it declares by sending it a request that must be refused (for example an unauthenticated POST). Pass true to send those requests for this scan; without it the affected checks reuse the domain's previous result where one exists. */
2362
+ activeProbes?: boolean;
2325
2363
  };
2326
2364
  };
2327
2365
  };
@@ -2483,6 +2521,8 @@ export interface operations {
2483
2521
  force?: "1";
2484
2522
  /** @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. */
2485
2523
  ephemeral?: "1";
2524
+ /** @description Pass 1 to send the requests a few checks send to endpoints the site declares for agents - the query spelling of `activeProbes: true` on POST /api/scan. Absent, they are not sent. */
2525
+ activeProbes?: "1";
2486
2526
  /** @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. */
2487
2527
  format?: "audit";
2488
2528
  /** @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. */
@@ -3055,6 +3095,48 @@ export interface operations {
3055
3095
  };
3056
3096
  };
3057
3097
  };
3098
+ /**
3099
+ * Draft a domain's own agent discovery files (ard.json, ai-catalog.json, poppy.json)
3100
+ * @description Drafts the agent discovery files a domain publishes about itself: /.well-known/ard.json (Agentic Resource Discovery), /.well-known/ai-catalog.json (the same catalog at the AI Catalog Standard's path) and /.well-known/poppy.json (Personal Agent Protocol, Draft 0.1). Built from what ora already holds for the domain - no live crawl - so a domain ora never scanned still gets a valid minimal set (a catalog listing its website, a poppy.json for signed-out browsing) with scannedAt null. Every catalog entry is anchored to the domain itself (urn:air:<domain>:..., identity https://<domain>), never to ora, and carries only https URLs on the domain or its subdomains: anything the scan saw on another host is named in the file's notes instead. MCP servers are listed by their server card (the card the scan found, else the reserved <server-url>/server-card location, which the notes ask the owner to serve). The poppy.json is the minimal valid document; what ora saw that a fuller one could name (an OAuth issuer, MCP servers, an OpenAPI description) is listed in that file's notes. Review every file before publishing it. A leading www. is dropped, and any spelling other than the canonical domain answers 308 to /api/agent-files/<domain>. Sends Access-Control-Allow-Origin: * and is CDN-cached. Rate limited to 60 requests per minute per IP - returns 429 if exceeded. Also used by the generator page at directory.ora.ai/generate and by `npx ax generate-files <domain>`.
3101
+ */
3102
+ generateAgentFiles: {
3103
+ parameters: {
3104
+ path: {
3105
+ /** @description A public host such as example.com (a full https:// URL without a path is also accepted). IPs, ports, paths and localhost are refused. */
3106
+ domain: string;
3107
+ };
3108
+ };
3109
+ responses: {
3110
+ /** @description The drafted files. */
3111
+ 200: {
3112
+ content: {
3113
+ "application/json": components["schemas"]["AgentFilesBundle"];
3114
+ };
3115
+ };
3116
+ /** @description The domain was spelled differently from its canonical form (www., upper case, a trailing dot); Location is /api/agent-files/<domain>. */
3117
+ 308: {
3118
+ content: never;
3119
+ };
3120
+ /** @description INVALID_ARGUMENT - not a public domain. */
3121
+ 400: {
3122
+ content: {
3123
+ "application/json": components["schemas"]["ArdErrorResponse"];
3124
+ };
3125
+ };
3126
+ /** @description RATE_LIMIT_EXCEEDED - max 60 requests per minute per IP. */
3127
+ 429: {
3128
+ content: {
3129
+ "application/json": components["schemas"]["ArdErrorResponse"];
3130
+ };
3131
+ };
3132
+ /** @description INTERNAL_ERROR */
3133
+ 500: {
3134
+ content: {
3135
+ "application/json": components["schemas"]["ArdErrorResponse"];
3136
+ };
3137
+ };
3138
+ };
3139
+ };
3058
3140
  /**
3059
3141
  * Get the public JWK set for verifying signed attestations (Agentic Resource Discovery)
3060
3142
  * @description Returns the public JSON Web Key Set used to verify ora's signed Agentic Resource Discovery (ARD) scorecard attestations. Also served at /.well-known/jwks.json via a rewrite.
@@ -3085,7 +3167,7 @@ export interface operations {
3085
3167
  };
3086
3168
  /**
3087
3169
  * Run an agent journey against a domain
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.
3170
+ * @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). On top of those, all anonymous callers together share a ceiling of 3000 runs per rolling 24h; when it is full every anonymous trigger gets the same 429 with `retry_after_ms` until the oldest run ages out, while keyed callers are unaffected. 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.
3089
3171
  */
3090
3172
  createJourneyRun: {
3091
3173
  requestBody: {
@@ -3174,7 +3256,7 @@ export interface operations {
3174
3256
  "application/json": components["schemas"]["ErrorResponse"];
3175
3257
  };
3176
3258
  };
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. */
3259
+ /** @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, plus 3000 per rolling 24h shared by all anonymous callers, 1000 per rolling 24h per key; body carries `retry_after_ms`). Per-TARGET saturation is the 200 above, not this. */
3178
3260
  429: {
3179
3261
  headers: {
3180
3262
  /** @description Seconds until next allowed request */
@@ -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.27.0";
2
+ export declare const BUILT_AGAINST = "1.30.0";
package/dist/index.cjs CHANGED
@@ -20,12 +20,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
20
20
  // src/index.ts
21
21
  var src_exports = {};
22
22
  __export(src_exports, {
23
+ AgentFilesApiError: () => AgentFilesApiError,
23
24
  AuditApiError: () => AuditApiError,
24
25
  BUILT_AGAINST: () => BUILT_AGAINST,
25
26
  DeepJourneyApiError: () => DeepJourneyApiError,
26
27
  SkillApiError: () => SkillApiError,
27
28
  audit: () => performAudit,
28
29
  deepJourney: () => performDeepJourney,
30
+ fetchAgentFiles: () => fetchAgentFiles,
29
31
  fetchJourneyAgents: () => fetchJourneyAgents,
30
32
  fetchJourneyIntents: () => fetchJourneyIntents,
31
33
  fetchSkill: () => fetchSkill,
@@ -34,30 +36,6 @@ __export(src_exports, {
34
36
  });
35
37
  module.exports = __toCommonJS(src_exports);
36
38
 
37
- // src/contract/version.ts
38
- var BUILT_AGAINST = "1.27.0";
39
-
40
- // src/contract/index.ts
41
- function minor(version) {
42
- const [major = 0, min = 0] = version.split(".").map((n) => Number.parseInt(n, 10));
43
- return [major, min];
44
- }
45
- function isNewerContract(payloadVersion) {
46
- if (!payloadVersion || !/^\d+\.\d+\.\d+$/.test(payloadVersion)) return false;
47
- const [serverMajor, serverMinor] = minor(payloadVersion);
48
- const [builtMajor, builtMinor] = minor(BUILT_AGAINST);
49
- return serverMajor > builtMajor || serverMajor === builtMajor && serverMinor > builtMinor;
50
- }
51
- var warned = false;
52
- function warnOnNewerContract(payloadVersion) {
53
- if (warned || !isNewerContract(payloadVersion)) return;
54
- warned = true;
55
- process.stderr.write(
56
- `ora reports contract ${payloadVersion}; this CLI was built against ${BUILT_AGAINST}. Newer fields may be missing from the output - upgrade with: npm i -g ax@latest
57
- `
58
- );
59
- }
60
-
61
39
  // src/api/shared.ts
62
40
  function watchdog(ms) {
63
41
  const controller = new AbortController();
@@ -97,8 +75,96 @@ async function errorBodyText(res) {
97
75
  }
98
76
  var pause = (ms) => new Promise((r) => setTimeout(r, ms));
99
77
 
100
- // src/api/audit.ts
78
+ // src/api/agent-files.ts
101
79
  var PUBLIC_BASE = "https://ora.ai";
80
+ var TIMEOUT_MS = 3e4;
81
+ var AgentFilesApiError = class extends Error {
82
+ status;
83
+ payload;
84
+ constructor(message, options = {}) {
85
+ super(message);
86
+ this.name = "AgentFilesApiError";
87
+ this.status = options.status ?? null;
88
+ this.payload = options.payload;
89
+ }
90
+ };
91
+ var SAFE_PATH = /^\/\.well-known\/[a-z0-9][a-z0-9._-]*\.json$/;
92
+ function isSafeAgentFilePath(path) {
93
+ return SAFE_PATH.test(path) && !path.includes("..");
94
+ }
95
+ function trimTrailingSlashes(value) {
96
+ let end = value.length;
97
+ while (end > 0 && value[end - 1] === "/") end--;
98
+ return value.slice(0, end);
99
+ }
100
+ function normalizeDomainInput(input) {
101
+ return trimTrailingSlashes(input.trim().replace(/^https?:\/\//i, ""));
102
+ }
103
+ async function fetchAgentFiles(domain, options = {}) {
104
+ const base = trimTrailingSlashes(options.baseUrl ?? process.env.ORA_API_URL ?? PUBLIC_BASE);
105
+ const url = `${base}/api/agent-files/${encodeURIComponent(normalizeDomainInput(domain))}`;
106
+ let res;
107
+ try {
108
+ res = await fetch(url, {
109
+ headers: { accept: "application/json" },
110
+ signal: AbortSignal.timeout(TIMEOUT_MS)
111
+ });
112
+ } catch (cause) {
113
+ throw new AgentFilesApiError(
114
+ `could not reach ora at ${base}: ${cause instanceof Error ? cause.message : String(cause)}`
115
+ );
116
+ }
117
+ if (!res.ok) {
118
+ const { message, payload } = await errorBody(res);
119
+ throw new AgentFilesApiError(message, { status: res.status, payload });
120
+ }
121
+ const body = await res.json();
122
+ if (!Array.isArray(body?.files)) {
123
+ throw new AgentFilesApiError("ora answered without a files list", {
124
+ status: res.status,
125
+ payload: body
126
+ });
127
+ }
128
+ for (const file of body.files) {
129
+ if (!isSafeAgentFilePath(file.path)) {
130
+ throw new AgentFilesApiError(
131
+ `ora named a file path ax will not write: ${JSON.stringify(file.path)}`,
132
+ {
133
+ status: res.status,
134
+ payload: body
135
+ }
136
+ );
137
+ }
138
+ }
139
+ return body;
140
+ }
141
+
142
+ // src/contract/version.ts
143
+ var BUILT_AGAINST = "1.30.0";
144
+
145
+ // src/contract/index.ts
146
+ function minor(version) {
147
+ const [major = 0, min = 0] = version.split(".").map((n) => Number.parseInt(n, 10));
148
+ return [major, min];
149
+ }
150
+ function isNewerContract(payloadVersion) {
151
+ if (!payloadVersion || !/^\d+\.\d+\.\d+$/.test(payloadVersion)) return false;
152
+ const [serverMajor, serverMinor] = minor(payloadVersion);
153
+ const [builtMajor, builtMinor] = minor(BUILT_AGAINST);
154
+ return serverMajor > builtMajor || serverMajor === builtMajor && serverMinor > builtMinor;
155
+ }
156
+ var warned = false;
157
+ function warnOnNewerContract(payloadVersion) {
158
+ if (warned || !isNewerContract(payloadVersion)) return;
159
+ warned = true;
160
+ process.stderr.write(
161
+ `ora reports contract ${payloadVersion}; this CLI was built against ${BUILT_AGAINST}. Newer fields may be missing from the output - upgrade with: npm i -g ax@latest
162
+ `
163
+ );
164
+ }
165
+
166
+ // src/api/audit.ts
167
+ var PUBLIC_BASE2 = "https://ora.ai";
102
168
  var STREAM_IDLE_MS = 6e4;
103
169
  var POLL_EVERY_MS = 2e3;
104
170
  var POLL_LIMIT = 45;
@@ -117,7 +183,7 @@ function authHeaders(apiKey) {
117
183
  return apiKey ? { authorization: `Bearer ${apiKey}` } : {};
118
184
  }
119
185
  async function performAudit(target, options = {}) {
120
- const base = (options.baseUrl ?? process.env.ORA_API_URL ?? PUBLIC_BASE).replace(/\/+$/, "");
186
+ const base = (options.baseUrl ?? process.env.ORA_API_URL ?? PUBLIC_BASE2).replace(/\/+$/, "");
121
187
  options = { ...options, apiKey: options.apiKey || process.env.ORA_SCAN_API_KEY || void 0 };
122
188
  options.progress?.(`Auditing ${target} with ora`);
123
189
  const streamed = await consumeScanStream(base, target, options);
@@ -297,7 +363,7 @@ function decodeEventBlock(block) {
297
363
  }
298
364
 
299
365
  // src/api/deep-journey.ts
300
- var PUBLIC_BASE2 = "https://ora.ai";
366
+ var PUBLIC_BASE3 = "https://ora.ai";
301
367
  var STREAM_IDLE_MS2 = 12e4;
302
368
  var POLL_EVERY_MS2 = 5e3;
303
369
  var POLL_LIMIT2 = 180;
@@ -317,7 +383,7 @@ var JourneyStreamHttpError = class extends DeepJourneyApiError {
317
383
  retryAfterMs;
318
384
  };
319
385
  function apiBase(baseUrl) {
320
- return (baseUrl ?? process.env.ORA_API_URL ?? PUBLIC_BASE2).replace(/\/+$/, "");
386
+ return (baseUrl ?? process.env.ORA_API_URL ?? PUBLIC_BASE3).replace(/\/+$/, "");
321
387
  }
322
388
  async function getJson(url) {
323
389
  let res;
@@ -603,11 +669,11 @@ async function awaitDetailSettled(base, runId, options) {
603
669
 
604
670
  // src/api/skills.ts
605
671
  var import_node_crypto = require("crypto");
606
- var PUBLIC_BASE3 = "https://ora.ai";
672
+ var PUBLIC_BASE4 = "https://ora.ai";
607
673
  var SkillApiError = class extends Error {
608
674
  };
609
675
  function resolveBase(baseUrl) {
610
- return (baseUrl ?? process.env.ORA_API_URL ?? PUBLIC_BASE3).replace(/\/+$/, "");
676
+ return (baseUrl ?? process.env.ORA_API_URL ?? PUBLIC_BASE4).replace(/\/+$/, "");
611
677
  }
612
678
  async function fetchSkillIndex(baseUrl) {
613
679
  const base = resolveBase(baseUrl);
@@ -658,12 +724,14 @@ async function fetchSkill(name, baseUrl) {
658
724
  }
659
725
  // Annotate the CommonJS export names for ESM import in node:
660
726
  0 && (module.exports = {
727
+ AgentFilesApiError,
661
728
  AuditApiError,
662
729
  BUILT_AGAINST,
663
730
  DeepJourneyApiError,
664
731
  SkillApiError,
665
732
  audit,
666
733
  deepJourney,
734
+ fetchAgentFiles,
667
735
  fetchJourneyAgents,
668
736
  fetchJourneyIntents,
669
737
  fetchSkill,
package/dist/index.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ export { type AgentFile, AgentFilesApiError, type AgentFilesBundle, type AgentFilesOptions, fetchAgentFiles, } from "./api/agent-files";
1
2
  export { AuditApiError, type AuditOptions, type AuditOutcome, type AuditResult, performAudit as audit, } from "./api/audit";
2
3
  export { DeepJourneyApiError, type DeepJourneyOptions, type DeepJourneyOutcome, fetchJourneyAgents, fetchJourneyIntents, type JourneyAgentOption, type JourneyIntentOption, performDeepJourney as deepJourney, type RunAllowance, } from "./api/deep-journey";
3
4
  export { type FetchedSkill, fetchSkill, fetchSkillIndex, SkillApiError, type SkillEntry, } from "./api/skills";