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 +15 -2
- package/dist/api/agent-files.d.ts +48 -0
- package/dist/contract/types.gen.d.ts +89 -7
- package/dist/contract/version.d.ts +1 -1
- package/dist/index.cjs +98 -30
- package/dist/index.d.ts +1 -0
- package/dist/index.js +96 -30
- package/dist/main.cjs +65 -62
- package/package.json +2 -2
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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/
|
|
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 ??
|
|
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
|
|
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 ??
|
|
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
|
|
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 ??
|
|
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";
|