ax 0.9.1 → 0.10.1
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/.env.example +6 -6
- package/README.md +48 -30
- package/dist/api/agent-files.d.ts +10 -2
- package/dist/contract/types.gen.d.ts +20 -8
- package/dist/contract/version.d.ts +1 -1
- package/dist/index.cjs +6 -4
- package/dist/index.js +6 -4
- package/dist/main.cjs +183 -70
- package/package.json +1 -1
package/.env.example
CHANGED
|
@@ -1,18 +1,17 @@
|
|
|
1
1
|
# ora platform API (agentic journeys / runs). Copy to `.env` and fill in.
|
|
2
|
-
# The public commands (audit, webmcp-audit, deep-journey, skill) use the public
|
|
2
|
+
# The public commands (audit, webmcp-audit, deep-journey, skill, generate-files) use the public
|
|
3
3
|
# ora.ai host and need none of these — `ax audit <url>` works with zero
|
|
4
4
|
# configuration, and so does `ax webmcp-audit http://localhost:3000`.
|
|
5
5
|
|
|
6
6
|
# Secret API key (looks like ora_sk_...). Required by `journey` and by
|
|
7
7
|
# `audit --tunnel ora` (needs the tunnels:write + tunnels:connect scopes), which
|
|
8
|
-
# exchange it for a short-lived bearer token.
|
|
9
|
-
# token to lift the anonymous ingest limits (10/min, 20 per 24h per IP); optional there.
|
|
8
|
+
# exchange it for a short-lived bearer token.
|
|
10
9
|
ORA_API_KEY=
|
|
11
10
|
|
|
12
|
-
# Platform API base. Defaults to
|
|
11
|
+
# Platform API base. Defaults to https://api.agentfront.sh (production) if unset.
|
|
13
12
|
ORA_PLATFORM_URL=https://api.agentfront.sh
|
|
14
13
|
|
|
15
|
-
# Public API base, used by audit, webmcp-audit, deep-journey and
|
|
14
|
+
# Public API base, used by audit, webmcp-audit, deep-journey, skill and generate-files.
|
|
16
15
|
# Defaults to https://ora.ai if unset. Point it at a local ora to test against
|
|
17
16
|
# one (e.g. http://localhost:3000).
|
|
18
17
|
# ORA_API_URL=https://ora.ai
|
|
@@ -34,5 +33,6 @@ ORA_PLATFORM_URL=https://api.agentfront.sh
|
|
|
34
33
|
|
|
35
34
|
# ora-issued partner API key for `ax deep-journey` (same as --api-key):
|
|
36
35
|
# unlocks free-text --task runs and the 1000 runs/24h keyed allowance
|
|
37
|
-
# (no per-target cap, no burst guard). Issued manually by ora.
|
|
36
|
+
# (no per-target cap, no burst guard). Issued manually by ora. `ax webmcp-audit`
|
|
37
|
+
# also sends it (then ORA_SCAN_API_KEY) to lift its daily ingest limit.
|
|
38
38
|
# ORA_PARTNER_API_KEY=
|
package/README.md
CHANGED
|
@@ -18,20 +18,20 @@
|
|
|
18
18
|
npx ax audit https://stripe.com
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
**No account, no API key.** Everything below works out of the box
|
|
21
|
+
**No account, no API key.** Everything below works out of the box. The exceptions are [`journey`](#for-ora-partners) and `audit --tunnel ora`, which need an ora platform key, and `deep-journey --task`, which needs a partner key.
|
|
22
22
|
|
|
23
23
|
<p align="center">
|
|
24
24
|
<img src="https://raw.githubusercontent.com/ora/ax/main/.github/assets/demo.gif" width="880" alt="ax audit https://stripe.com — live progress, then the layered report and ora's ranked top fixes" />
|
|
25
25
|
</p>
|
|
26
26
|
|
|
27
|
-
|
|
27
|
+
Six commands:
|
|
28
28
|
|
|
29
29
|
- **`audit <url>`** — run ora's hosted agent-readiness audit against a site: live progress, then a layered report of what passed, what's broken, and ora's ranked list of the highest-impact fixes (or `--json` for the raw contract payload). No account or API key needed. Gate CI with `--min-score`.
|
|
30
30
|
- **`webmcp-audit <url>`** — audit a page's `document.modelContext` tools in a real browser. Works on any http(s) URL, localhost included, so you can check a surface before you publish it. Measures the page the way ora's capture worker does and has ora score it; nothing is stored, published, or ranked.
|
|
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
|
|
34
|
+
- **`generate-files <domain>`** — draft the files agents look for on a site (`ard.json`, `ai-catalog.json`, `poppy.json`, `llms.txt`, a `robots.txt` edit, an API catalog, MCP server cards), filled in from ora's last scan of the domain.
|
|
35
35
|
|
|
36
36
|
## audit
|
|
37
37
|
|
|
@@ -91,7 +91,7 @@ Exit codes are the contract:
|
|
|
91
91
|
| `2` | usage error — bad flags, malformed URL, local target without a tunnel |
|
|
92
92
|
| `3` | API unreachable, timeout, or rate limit exhausted |
|
|
93
93
|
|
|
94
|
-
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
|
|
94
|
+
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 these limits (a key scoped to `pap:read` keeps a daily cap and cannot `--force`); 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`.
|
|
95
95
|
|
|
96
96
|
### Auditing localhost (`--tunnel ora`, `--tunnel-cmd`)
|
|
97
97
|
|
|
@@ -144,7 +144,7 @@ or bundles a browser. Set `CHROME_PATH` if yours lives somewhere unusual.
|
|
|
144
144
|
To drive a browser you started yourself, pass `--chrome-endpoint` (a `ws://` URL, an http origin,
|
|
145
145
|
or `host:port`) and start it with `--remote-debugging-port`. The command never attaches to a
|
|
146
146
|
browser you did not name — including anything already on port 9222 — because silently borrowing a
|
|
147
|
-
Chrome with the WebMCP flags on would
|
|
147
|
+
Chrome with the WebMCP flags on would make your page read differently here than it does on ora.
|
|
148
148
|
|
|
149
149
|
**Do not enable the WebMCP flags on a Chrome you point it at.** The audit asks whether a real
|
|
150
150
|
browser gives an agent WebMCP on your page. A Chrome started with `--enable-features=WebMCPTesting`
|
|
@@ -158,15 +158,19 @@ present in order to call your tools.
|
|
|
158
158
|
passes and the same probe code ora's worker runs, plus a viewport screenshot at ora's 1280×720. As
|
|
159
159
|
ora does, it loads the page with images, media and webfonts refused — stylesheets still apply — so
|
|
160
160
|
the screenshot the grader sees is the one ora would have taken. That capture is
|
|
161
|
-
posted to ora, which runs
|
|
162
|
-
streams back a score. The CLI
|
|
161
|
+
posted to ora, which runs its 19 checks, two model hops and the tool-selection simulation, and
|
|
162
|
+
streams back a score. The CLI never calls your tools, so the three checks that need a tool call
|
|
163
|
+
(`invoke-success-rate`, `visible-effect`, `hint-vs-observed`) read `Not applicable` on a local
|
|
164
|
+
audit. The CLI scores nothing itself (design decision #1) — grade, findings,
|
|
163
165
|
category scores and the simulation are all rendered as ora sent them.
|
|
164
166
|
|
|
165
|
-
**Availability is
|
|
166
|
-
|
|
167
|
-
|
|
167
|
+
**Availability is reported, not scored.** ora says whether an in-browser agent can use the page
|
|
168
|
+
(`agent-ready`, `not agent-ready`, or unknown) and why, and the report leads with it. It never
|
|
169
|
+
changes the score: a `not agent-ready` page still gets its score and pillars. The one exception is
|
|
170
|
+
a page whose only tools are declarative forms: its pillars are scored, and its grade is withheld,
|
|
171
|
+
because ora finds those tools in the markup and cannot watch a browser register them.
|
|
168
172
|
|
|
169
|
-
|
|
173
|
+
The score is four pillars — `shared-experience` (30), `task-completion` (25),
|
|
170
174
|
`tool-quality` (25), `trust` (20). It is **not** the 0–100 agent-readiness score from `ax audit`:
|
|
171
175
|
different inputs, different rubric, never comparable.
|
|
172
176
|
|
|
@@ -190,8 +194,9 @@ the leaderboard, the badge, or your public scorecard — to appear there, publis
|
|
|
190
194
|
on webmcp.ora.ai. Pass `--json` and pipe it to a file if you want to see exactly what was sent
|
|
191
195
|
back; the capture itself is what the report's header describes.
|
|
192
196
|
|
|
193
|
-
Anonymous use is rate-limited to 10/min and 20 per 24h per IP
|
|
194
|
-
(`--api-key` / `
|
|
197
|
+
Anonymous use is rate-limited to 10/min and 20 per 24h per IP. An ora-issued partner or scan API
|
|
198
|
+
key (`--api-key`, or `ORA_PARTNER_API_KEY` / `ORA_SCAN_API_KEY`) lifts the daily limit; the
|
|
199
|
+
per-minute limit still applies.
|
|
195
200
|
|
|
196
201
|
### CI gate
|
|
197
202
|
|
|
@@ -201,8 +206,9 @@ Anonymous use is rate-limited to 10/min and 20 per 24h per IP; an ora API key
|
|
|
201
206
|
|
|
202
207
|
Any CI image with Chrome installed works; nothing to launch first.
|
|
203
208
|
|
|
204
|
-
Exit codes
|
|
205
|
-
|
|
209
|
+
Exit codes follow `audit`: `0` ok · `1` below `--min-score` · `2` usage (no debuggable Chrome, the
|
|
210
|
+
page did not load, or a capture ora would refuse) · `3` API, a failed capture, or no score
|
|
211
|
+
returned. The gate reads the score, not the grade — a withheld grade would otherwise let
|
|
206
212
|
everything through.
|
|
207
213
|
|
|
208
214
|
## deep-journey
|
|
@@ -230,18 +236,18 @@ Runs a real AI agent at a site through ora's **public** journey API — no key,
|
|
|
230
236
|
For the 4-layer readiness audit, run: ax audit stripe.com
|
|
231
237
|
```
|
|
232
238
|
|
|
233
|
-
Anonymous callers run curated intents (`pricing`, `signup`, `api-docs`, `integrate`, `support`, …) — list them with `GET https://ora.ai/api/journey/intents`, and the
|
|
239
|
+
Anonymous callers run curated intents (`pricing`, `signup`, `api-docs`, `integrate`, `support`, …) — list them with `GET https://ora.ai/api/journey/intents`, and the publicly offered agents with `GET https://ora.ai/api/journey/agents`. The public caps are 100 runs per rolling 24h per target and task, 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.
|
|
234
240
|
|
|
235
241
|
**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.
|
|
236
242
|
|
|
237
|
-
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
|
|
243
|
+
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; any other HTTP error from the stream (a `404`, an auth error, a `5xx`) 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.
|
|
238
244
|
|
|
239
245
|
| Flag | Effect |
|
|
240
246
|
|---|---|
|
|
241
247
|
| `--intent <id>` | Curated task id (server default when omitted) |
|
|
242
248
|
| `--task <text>` | Free-text task — needs a partner API key; mutually exclusive with `--intent` |
|
|
243
249
|
| `--api-key <k>` | ora partner API key; also read from `ORA_PARTNER_API_KEY` (then `ORA_SCAN_API_KEY`) |
|
|
244
|
-
| `--agent <id>` | Agent from the public roster (default: ora's
|
|
250
|
+
| `--agent <id>` | Agent from the public roster (default: `cas-haiku`, Claude Code on the Haiku model ora's roster lists) |
|
|
245
251
|
| `--no-stream` | Hide the live trajectory view and print only the final result |
|
|
246
252
|
| `--json` | Print the terminal run detail (verdict, step_count, result) as JSON |
|
|
247
253
|
|
|
@@ -258,19 +264,30 @@ ax skill agent-ready-website --install # write .claude/skills/<name>/SKILL.md
|
|
|
258
264
|
ax skill --json # the raw registry index
|
|
259
265
|
```
|
|
260
266
|
|
|
261
|
-
Skills come from ora's public registry (`https://ora.ai/.well-known/agent-skills/`) and every
|
|
267
|
+
Skills come from ora's public registry (`https://ora.ai/.well-known/agent-skills/`) and every skill whose index entry carries a sha256 digest is verified against it, byte for byte, 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.
|
|
262
268
|
|
|
263
269
|
## generate-files
|
|
264
270
|
|
|
265
271
|
```
|
|
266
|
-
ax generate-files example.com # writes
|
|
267
|
-
ax generate-files example.com --out public # writes public
|
|
272
|
+
ax generate-files example.com # writes into the current directory
|
|
273
|
+
ax generate-files example.com --out public # writes into public/ (your site's web root)
|
|
268
274
|
ax generate-files example.com --json # ora's payload, files + notes, nothing written
|
|
269
275
|
```
|
|
270
276
|
|
|
271
|
-
Drafts the files agents look for
|
|
277
|
+
Drafts the files agents look for on a site, filled in from ora's last scan of the domain (no new crawl). For a domain ora has never scanned you get only a website entry and a minimal `poppy.json`, so run `ax audit` first to fill in the rest:
|
|
272
278
|
|
|
273
|
-
|
|
279
|
+
| File | Written to | What it is |
|
|
280
|
+
|---|---|---|
|
|
281
|
+
| `ard.json`, `ai-catalog.json` | `.well-known/` | An [Agentic Resource Discovery](https://agenticresourcediscovery.org/) catalog (the same document at the [AI Catalog Standard](https://ai-catalog.io/)'s path). Every entry is anchored to your domain, not to ora |
|
|
282
|
+
| `poppy.json` | `.well-known/` | A [Personal Agent Protocol](https://personalagentprotocol.org/docs/spec) file for signed-out browsing; the OAuth issuer and APIs ora saw are printed as notes, because naming them is only correct once they implement the protocol |
|
|
283
|
+
| `llms.txt` | web root | An index of the docs, APIs and agent endpoints ora found; skipped when you already publish one |
|
|
284
|
+
| `robots.txt` | web root | An edit of your current robots.txt: every line kept, a group added for AI search crawlers and user-requested agents your `User-agent: *` rules block (copying your other rules), and a `Sitemap:` line. Training crawlers and crawlers you block by name are never touched |
|
|
285
|
+
| `api-catalog` | `.well-known/` | An [RFC 9727](https://www.rfc-editor.org/rfc/rfc9727) API catalog pointing at your OpenAPI description |
|
|
286
|
+
| `server-card` | `<mcp path>/` | A draft MCP server card for each MCP server that has none. A card for a server on another host (`mcp.example.com`) is listed with its URL, not written; `--json` carries its body |
|
|
287
|
+
|
|
288
|
+
A file ora cannot draft honestly (you already publish it, ora never read the original, or ora found nothing to put in it) is left out and explained under "Not drafted". These are drafts: read each file and its notes before you publish.
|
|
289
|
+
|
|
290
|
+
Nothing is overwritten: if any target file exists - your `robots.txt` included - nothing is written and the command exits `2`. Pass `--force` to overwrite, or `--out <dir>` to write elsewhere and compare. 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}?include=all`.
|
|
274
291
|
|
|
275
292
|
## Library use
|
|
276
293
|
|
|
@@ -297,14 +314,14 @@ const { detail } = await deepJourney("stripe.com", {
|
|
|
297
314
|
harness: agent.harness,
|
|
298
315
|
model: agent.model,
|
|
299
316
|
});
|
|
300
|
-
console.log(detail.verdict, detail.step_count, detail.result?.insight
|
|
317
|
+
console.log(detail.verdict, detail.step_count, detail.result?.insight?.summary);
|
|
301
318
|
```
|
|
302
319
|
|
|
303
320
|
`detail` is the contract's `JourneyRunDetail`; `fetchJourneyIntents` lists the curated intents. The same public caps apply — a capped target resolves with the most recent stored run (`cached: true` on the outcome), not an error.
|
|
304
321
|
|
|
305
322
|
## For ora partners
|
|
306
323
|
|
|
307
|
-
Everything above runs without an account. The commands
|
|
324
|
+
Everything above runs without an account. The commands in this section are for teams working with ora directly, and there is no self-serve signup: keys are issued by ora (contact [hello@ora.ai](mailto:hello@ora.ai)). Two kinds of key exist. `journey` (and `audit --tunnel ora`) needs an ora platform key (`ora_sk_…`). A separate partner or scan key, passed with `--api-key`, lifts the anonymous rate limits on `audit` and `deep-journey`, and the daily limit on `webmcp-audit`.
|
|
308
325
|
|
|
309
326
|
### journey
|
|
310
327
|
|
|
@@ -375,14 +392,15 @@ A `.env` in the working directory is read on startup — copy `.env.example` and
|
|
|
375
392
|
|
|
376
393
|
| Var | Used by | Default | Purpose |
|
|
377
394
|
|---|---|---|---|
|
|
378
|
-
| `ORA_API_URL` | audit, deep-journey, skill, generate-files | `https://ora.ai` | Public API base (no auth) |
|
|
395
|
+
| `ORA_API_URL` | audit, webmcp-audit, deep-journey, skill, generate-files | `https://ora.ai` | Public API base (no auth); also the ingest base for `webmcp-audit` |
|
|
379
396
|
| `ORA_PLATFORM_URL` | journey, audit `--tunnel ora` | `https://api.agentfront.sh` | Authenticated platform API base |
|
|
380
397
|
| `ORA_TUNNEL` | audit | — (optional) | `ora` opens ora's own tunnel for a local target (same as `--tunnel ora`) |
|
|
381
398
|
| `ORA_TUNNEL_CMD` | audit | — (optional) | Tunnel command for a local target (same as `--tunnel-cmd`); wins over `ORA_TUNNEL` |
|
|
382
|
-
| `
|
|
383
|
-
| `
|
|
384
|
-
| `
|
|
385
|
-
| `
|
|
399
|
+
| `ORA_API_KEY` | journey, audit `--tunnel ora` | — (required for both) | ora platform key (`ora_sk_…`); exchanged for a bearer token (the tunnel needs the `tunnels:write` + `tunnels:connect` scopes) |
|
|
400
|
+
| `ORA_SCAN_API_KEY` | audit, deep-journey, webmcp-audit | — (optional) | ora-issued scan API key; lifts every scan rate limit (issued manually by ora). deep-journey and webmcp-audit accept it as a partner-key fallback |
|
|
401
|
+
| `ORA_PARTNER_API_KEY` | deep-journey, webmcp-audit | — (optional) | ora-issued partner API key; unlocks `--task` and the 1000/24h keyed allowance on deep-journey, and lifts webmcp-audit's daily limit |
|
|
402
|
+
| `CHROME_PATH` | webmcp-audit | — (auto-detected) | The Chrome to launch, when yours is not in a standard location |
|
|
403
|
+
| `AX_WEBMCP_NO_SANDBOX` | webmcp-audit | — (unset) | `1` launches Chrome without its sandbox. Containers only: the audited page is untrusted and the sandbox contains it |
|
|
386
404
|
|
|
387
405
|
## Contract versioning
|
|
388
406
|
|
|
@@ -1,15 +1,21 @@
|
|
|
1
1
|
export interface AgentFile {
|
|
2
|
-
/** Where the
|
|
2
|
+
/** Where the file is served, as a path on its host, e.g. "/.well-known/ard.json". */
|
|
3
3
|
path: string;
|
|
4
4
|
spec: {
|
|
5
5
|
name: string;
|
|
6
6
|
version: string;
|
|
7
7
|
url: string;
|
|
8
8
|
};
|
|
9
|
-
/** The JSON document to publish at `path
|
|
9
|
+
/** The JSON document to publish at `path`; `{}` for a text file (see `body`). */
|
|
10
10
|
content: Record<string, unknown>;
|
|
11
11
|
/** What to review or add before publishing. */
|
|
12
12
|
notes: string[];
|
|
13
|
+
/** Content-Type to serve the file with. */
|
|
14
|
+
mediaType?: string;
|
|
15
|
+
/** The exact bytes to publish. */
|
|
16
|
+
body?: string;
|
|
17
|
+
/** The full address the file is served at; a server card can live on a subdomain. */
|
|
18
|
+
url?: string;
|
|
13
19
|
}
|
|
14
20
|
export interface AgentFilesBundle {
|
|
15
21
|
domain: string;
|
|
@@ -17,6 +23,8 @@ export interface AgentFilesBundle {
|
|
|
17
23
|
/** When ora last scanned the domain; null when it never has. */
|
|
18
24
|
scannedAt: string | null;
|
|
19
25
|
files: AgentFile[];
|
|
26
|
+
/** Why an included file is absent, in plain sentences. */
|
|
27
|
+
notes?: string[];
|
|
20
28
|
}
|
|
21
29
|
/**
|
|
22
30
|
* Any failure to get the files from ora. `status` is the HTTP status when ora
|
|
@@ -131,7 +131,7 @@ export interface paths {
|
|
|
131
131
|
"/api/agent-files/{domain}": {
|
|
132
132
|
/**
|
|
133
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>`.
|
|
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. Pass ?include= for llms.txt, an edit of the site's robots.txt, an RFC 9727 api-catalog and draft MCP server cards. 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
135
|
*/
|
|
136
136
|
get: operations["generateAgentFiles"];
|
|
137
137
|
};
|
|
@@ -431,7 +431,7 @@ export interface components {
|
|
|
431
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.
|
|
432
432
|
* @enum {string}
|
|
433
433
|
*/
|
|
434
|
-
contractVersion: "1.
|
|
434
|
+
contractVersion: "1.31.0";
|
|
435
435
|
/**
|
|
436
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.
|
|
437
437
|
* @enum {boolean}
|
|
@@ -634,7 +634,7 @@ export interface components {
|
|
|
634
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.
|
|
635
635
|
* @enum {string}
|
|
636
636
|
*/
|
|
637
|
-
contractVersion: "1.
|
|
637
|
+
contractVersion: "1.31.0";
|
|
638
638
|
/** @description Wall-clock duration of the scan that produced this stored result */
|
|
639
639
|
durationMs: number | null;
|
|
640
640
|
/**
|
|
@@ -682,7 +682,7 @@ export interface components {
|
|
|
682
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.
|
|
683
683
|
* @enum {string}
|
|
684
684
|
*/
|
|
685
|
-
contractVersion: "1.
|
|
685
|
+
contractVersion: "1.31.0";
|
|
686
686
|
/** @description The four scored layers in scoring order, with display name and current weight. */
|
|
687
687
|
layers: {
|
|
688
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'. */
|
|
@@ -781,7 +781,7 @@ export interface components {
|
|
|
781
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.
|
|
782
782
|
* @enum {string}
|
|
783
783
|
*/
|
|
784
|
-
contractVersion: "1.
|
|
784
|
+
contractVersion: "1.31.0";
|
|
785
785
|
/** @description The apex domain derived from the requested URL. */
|
|
786
786
|
domain: string;
|
|
787
787
|
/** @description The normalized URL the run targeted. */
|
|
@@ -2188,9 +2188,11 @@ export interface components {
|
|
|
2188
2188
|
*/
|
|
2189
2189
|
scannedAt: string | null;
|
|
2190
2190
|
files: components["schemas"]["AgentFile"][];
|
|
2191
|
+
/** @description Why an included file is absent (the site already publishes it, Ora never read the original, nothing to list), in plain sentences. Empty without ?include=. */
|
|
2192
|
+
notes: string[];
|
|
2191
2193
|
};
|
|
2192
2194
|
AgentFile: {
|
|
2193
|
-
/** @description Where the
|
|
2195
|
+
/** @description Where the file is served, as a path on its host, e.g. /.well-known/ard.json. */
|
|
2194
2196
|
path: string;
|
|
2195
2197
|
/** @description The standard the file follows. */
|
|
2196
2198
|
spec: {
|
|
@@ -2198,12 +2200,18 @@ export interface components {
|
|
|
2198
2200
|
version: string;
|
|
2199
2201
|
url: string;
|
|
2200
2202
|
};
|
|
2201
|
-
/** @description The JSON document to publish at path. */
|
|
2203
|
+
/** @description The JSON document to publish at path; an empty object for a text file (llms.txt, robots.txt), whose bytes are in body. */
|
|
2202
2204
|
content: {
|
|
2203
2205
|
[key: string]: unknown;
|
|
2204
2206
|
};
|
|
2205
2207
|
/** @description What to review or add before publishing, in plain sentences. */
|
|
2206
2208
|
notes: string[];
|
|
2209
|
+
/** @description Content-Type to serve the file with, e.g. application/json, application/linkset+json, text/markdown, text/plain. */
|
|
2210
|
+
mediaType: string;
|
|
2211
|
+
/** @description The exact bytes to publish (JSON files pretty-printed with a trailing newline). */
|
|
2212
|
+
body: string;
|
|
2213
|
+
/** @description The full address the file is served at: https://<domain><path>, except an MCP server card, which lives on its server's host (possibly a subdomain). */
|
|
2214
|
+
url: string;
|
|
2207
2215
|
};
|
|
2208
2216
|
McpAuthRequiredResponse: {
|
|
2209
2217
|
/** @description Why the MCP server could not be inspected. */
|
|
@@ -3097,10 +3105,14 @@ export interface operations {
|
|
|
3097
3105
|
};
|
|
3098
3106
|
/**
|
|
3099
3107
|
* 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>`.
|
|
3108
|
+
* @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. Pass ?include= for llms.txt, an edit of the site's robots.txt, an RFC 9727 api-catalog and draft MCP server cards. 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
3109
|
*/
|
|
3102
3110
|
generateAgentFiles: {
|
|
3103
3111
|
parameters: {
|
|
3112
|
+
query?: {
|
|
3113
|
+
/** @description Extra files to draft beyond the default three, comma-separated: llms.txt, robots.txt (an edit of the site's current robots.txt that keeps every line and only adds what lets AI search crawlers and user-requested agents in, plus a Sitemap line; training crawlers and crawlers the owner blocked by name are never touched), api-catalog (RFC 9727), mcp-server-card (a draft card for each of the domain's MCP servers that has none, served on the server's own host). `all` asks for every one. Unknown names are ignored. Opt-in, so a client built for the three files never receives a path it cannot place. A file Ora cannot draft honestly (the site already publishes it, or Ora never read it) is left out and explained in the bundle `notes`. */
|
|
3114
|
+
include?: string;
|
|
3115
|
+
};
|
|
3104
3116
|
path: {
|
|
3105
3117
|
/** @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
3118
|
domain: string;
|
|
@@ -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.31.0";
|
package/dist/index.cjs
CHANGED
|
@@ -88,9 +88,11 @@ var AgentFilesApiError = class extends Error {
|
|
|
88
88
|
this.payload = options.payload;
|
|
89
89
|
}
|
|
90
90
|
};
|
|
91
|
-
var
|
|
91
|
+
var SAFE_SEGMENT = /^[a-z0-9._-]+$/;
|
|
92
92
|
function isSafeAgentFilePath(path) {
|
|
93
|
-
|
|
93
|
+
if (!path.startsWith("/")) return false;
|
|
94
|
+
const segments = path.slice(1).split("/");
|
|
95
|
+
return segments.length >= 1 && segments.length <= 6 && segments.every((seg) => SAFE_SEGMENT.test(seg) && seg !== "." && seg !== "..");
|
|
94
96
|
}
|
|
95
97
|
function trimTrailingSlashes(value) {
|
|
96
98
|
let end = value.length;
|
|
@@ -102,7 +104,7 @@ function normalizeDomainInput(input) {
|
|
|
102
104
|
}
|
|
103
105
|
async function fetchAgentFiles(domain, options = {}) {
|
|
104
106
|
const base = trimTrailingSlashes(options.baseUrl ?? process.env.ORA_API_URL ?? PUBLIC_BASE);
|
|
105
|
-
const url = `${base}/api/agent-files/${encodeURIComponent(normalizeDomainInput(domain))}`;
|
|
107
|
+
const url = `${base}/api/agent-files/${encodeURIComponent(normalizeDomainInput(domain))}?include=all`;
|
|
106
108
|
let res;
|
|
107
109
|
try {
|
|
108
110
|
res = await fetch(url, {
|
|
@@ -140,7 +142,7 @@ async function fetchAgentFiles(domain, options = {}) {
|
|
|
140
142
|
}
|
|
141
143
|
|
|
142
144
|
// src/contract/version.ts
|
|
143
|
-
var BUILT_AGAINST = "1.
|
|
145
|
+
var BUILT_AGAINST = "1.31.0";
|
|
144
146
|
|
|
145
147
|
// src/contract/index.ts
|
|
146
148
|
function minor(version) {
|
package/dist/index.js
CHANGED
|
@@ -50,9 +50,11 @@ var AgentFilesApiError = class extends Error {
|
|
|
50
50
|
this.payload = options.payload;
|
|
51
51
|
}
|
|
52
52
|
};
|
|
53
|
-
var
|
|
53
|
+
var SAFE_SEGMENT = /^[a-z0-9._-]+$/;
|
|
54
54
|
function isSafeAgentFilePath(path) {
|
|
55
|
-
|
|
55
|
+
if (!path.startsWith("/")) return false;
|
|
56
|
+
const segments = path.slice(1).split("/");
|
|
57
|
+
return segments.length >= 1 && segments.length <= 6 && segments.every((seg) => SAFE_SEGMENT.test(seg) && seg !== "." && seg !== "..");
|
|
56
58
|
}
|
|
57
59
|
function trimTrailingSlashes(value) {
|
|
58
60
|
let end = value.length;
|
|
@@ -64,7 +66,7 @@ function normalizeDomainInput(input) {
|
|
|
64
66
|
}
|
|
65
67
|
async function fetchAgentFiles(domain, options = {}) {
|
|
66
68
|
const base = trimTrailingSlashes(options.baseUrl ?? process.env.ORA_API_URL ?? PUBLIC_BASE);
|
|
67
|
-
const url = `${base}/api/agent-files/${encodeURIComponent(normalizeDomainInput(domain))}`;
|
|
69
|
+
const url = `${base}/api/agent-files/${encodeURIComponent(normalizeDomainInput(domain))}?include=all`;
|
|
68
70
|
let res;
|
|
69
71
|
try {
|
|
70
72
|
res = await fetch(url, {
|
|
@@ -102,7 +104,7 @@ async function fetchAgentFiles(domain, options = {}) {
|
|
|
102
104
|
}
|
|
103
105
|
|
|
104
106
|
// src/contract/version.ts
|
|
105
|
-
var BUILT_AGAINST = "1.
|
|
107
|
+
var BUILT_AGAINST = "1.31.0";
|
|
106
108
|
|
|
107
109
|
// src/contract/index.ts
|
|
108
110
|
function minor(version) {
|