ax 0.2.2 → 0.6.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/.env.example +27 -0
- package/LICENSE +21 -0
- package/README.md +291 -0
- package/dist/api/audit.d.ts +47 -0
- package/dist/api/deep-journey.d.ts +90 -0
- package/dist/api/platform.d.ts +139 -0
- package/dist/api/shared.d.ts +14 -0
- package/dist/api/skills.d.ts +25 -0
- package/dist/contract/index.d.ts +22 -0
- package/dist/contract/types.gen.d.ts +3270 -0
- package/dist/contract/version.d.ts +2 -0
- package/dist/index.cjs +600 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +563 -0
- package/dist/main.cjs +40 -0
- package/package.json +66 -23
- package/ReadMe.md +0 -15
- package/ax.coffee +0 -38
- package/ax.js +0 -65
package/.env.example
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# ora platform API (agentic journeys / runs). Copy to `.env` and fill in.
|
|
2
|
+
# The public commands (audit, deep-journey, skill) use the public ora.ai host
|
|
3
|
+
# and need none of these — `ax audit <url>` works with zero configuration.
|
|
4
|
+
|
|
5
|
+
# Secret API key (looks like ora_sk_...). Exchanged for a short-lived bearer token.
|
|
6
|
+
ORA_API_KEY=
|
|
7
|
+
|
|
8
|
+
# Platform API base. Defaults to staging if unset.
|
|
9
|
+
ORA_PLATFORM_URL=https://api.agentfront.sh
|
|
10
|
+
|
|
11
|
+
# Public scan API base. Defaults to https://ora.ai if unset.
|
|
12
|
+
# ORA_API_URL=https://ora.ai
|
|
13
|
+
|
|
14
|
+
# Tunnel command for auditing a local target (same as --tunnel-cmd):
|
|
15
|
+
# a command that exposes the local server and prints its public https URL.
|
|
16
|
+
# ORA_TUNNEL_CMD='ngrok http 3000 --log stdout'
|
|
17
|
+
|
|
18
|
+
# ora-issued scan API key for `ax audit` (same as --api-key): exempts the
|
|
19
|
+
# caller from the scan rate limits (30/day + 6 force/day + 10/min burst).
|
|
20
|
+
# Issued manually by ora — no self-serve signup. Leave unset for normal use.
|
|
21
|
+
# `ax deep-journey` also accepts it as a partner-key fallback.
|
|
22
|
+
# ORA_SCAN_API_KEY=
|
|
23
|
+
|
|
24
|
+
# ora-issued partner API key for `ax deep-journey` (same as --api-key):
|
|
25
|
+
# unlocks free-text --task runs and the 1000 runs/24h keyed allowance
|
|
26
|
+
# (no per-target cap, no burst guard). Issued manually by ora.
|
|
27
|
+
# ORA_PARTNER_API_KEY=
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 era labs
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,291 @@
|
|
|
1
|
+
# ax — the ora CLI
|
|
2
|
+
|
|
3
|
+
Score any site's agent readiness — and watch real AI agents navigate it. Powered by [ora](https://ora.ai)'s hosted APIs.
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
npx ax audit https://stripe.com
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Four commands:
|
|
10
|
+
|
|
11
|
+
- **`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`.
|
|
12
|
+
- **`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.
|
|
13
|
+
- **`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. Requires an `ORA_API_KEY`.
|
|
14
|
+
- **`skill [name]`** — list, print, or install ora's agent skills, digest-verified from the public registry.
|
|
15
|
+
|
|
16
|
+
## audit
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
ax audit <url> [--min-score n] [--max-age s] [--force] [--tunnel-cmd c] [--api-key k] [--json] [--show-passing] [--show-skipped]
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
stripe.com 78/100 B+
|
|
24
|
+
Stripe offers strong developer resource discoverability, but lacks an OpenAPI specification.
|
|
25
|
+
|
|
26
|
+
Discovery ██████░░░░ 6/9 passed · 1 skipped
|
|
27
|
+
✗ Issues (2)
|
|
28
|
+
┌───┬──────────────┬───────────────────────────┬──────────────────────────────┐
|
|
29
|
+
│ │ Check │ What's wrong │ How to fix │
|
|
30
|
+
├───┼──────────────┼───────────────────────────┼──────────────────────────────┤
|
|
31
|
+
│ ✗ │ sitemap.md │ status 404 │ Publish /sitemap.md listing… │
|
|
32
|
+
├───┼──────────────┼───────────────────────────┼──────────────────────────────┤
|
|
33
|
+
│ ⚠ │ robots.txt │ partially restricted │ Allow AI crawlers in robots… │
|
|
34
|
+
└───┴──────────────┴───────────────────────────┴──────────────────────────────┘
|
|
35
|
+
|
|
36
|
+
Top fixes (ranked by ora)
|
|
37
|
+
1. sitemap-md ≈ +4 pts
|
|
38
|
+
2. robots-txt ≈ +1.2 pts
|
|
39
|
+
|
|
40
|
+
cached result (43 min old) · pass --force for a fresh scan
|
|
41
|
+
Full report: https://ora.ai/stripe.com
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
| Flag | Effect |
|
|
45
|
+
|---|---|
|
|
46
|
+
| `--min-score <n>` | Exit `1` when the score is below `n` (0-100) — the CI gate |
|
|
47
|
+
| `--max-age <s>` | Accept a cached result up to `s` seconds old (server default 6h, clamped to 1-24h) |
|
|
48
|
+
| `--force` | Bypass the cache and rescan — spends the stricter 6/day force budget |
|
|
49
|
+
| `--tunnel-cmd <c>` | Expose a local target through your own tunnel command and audit the public URL it prints (also read from `ORA_TUNNEL_CMD`) |
|
|
50
|
+
| `--api-key <k>` | ora-issued scan API key — lifts every scan rate limit (also read from `ORA_SCAN_API_KEY`) |
|
|
51
|
+
| `--json` | The raw ora audit payload on stdout, exactly as the API served it |
|
|
52
|
+
| `--show-passing` | List every passing check, not just the per-layer summary bar |
|
|
53
|
+
| `--show-skipped` | Include not-applicable/pending checks with their reason |
|
|
54
|
+
|
|
55
|
+
The **Top fixes** list is ranked by ora server-side (non-bonus fixes first, then estimated score uplift) — the CLI renders it verbatim. All `≈ +N pts` figures are estimates. Check *tiers* (required / recommended / emerging) are advisory display metadata and never determine the score.
|
|
56
|
+
|
|
57
|
+
### CI gate
|
|
58
|
+
|
|
59
|
+
```yaml
|
|
60
|
+
- name: Agent-readiness gate
|
|
61
|
+
run: npx ax audit https://your-site.com --min-score 70
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Exit codes are the contract:
|
|
65
|
+
|
|
66
|
+
| Code | Meaning |
|
|
67
|
+
|---|---|
|
|
68
|
+
| `0` | success (and score ≥ `--min-score` when given) |
|
|
69
|
+
| `1` | score below `--min-score` |
|
|
70
|
+
| `2` | usage error — bad flags, malformed URL, local target without a tunnel |
|
|
71
|
+
| `3` | API unreachable, timeout, or rate limit exhausted |
|
|
72
|
+
|
|
73
|
+
Budget notes: ora allows 30 scans + 6 `--force` scans per rolling 24h per IP (plus a 10/min burst limit). Results served from the freshness cache cost nothing, so a CI job that audits on every push stays well inside the budget — tune the window with `--max-age`, and reserve `--force` for verifying a fix you just deployed. High-volume callers can present an ora-issued scan API key (`--api-key` or `ORA_SCAN_API_KEY`), which exempts them from all of these limits; keys are issued manually by ora (no self-serve signup), and an unrecognized key silently falls back to the keyless limits rather than erroring. An auth-gated MCP target reports `mcpAuthRequired` and scores 0 as "could not evaluate"; `--min-score` deliberately skips the gate rather than failing on it.
|
|
74
|
+
|
|
75
|
+
### Auditing localhost (`--tunnel-cmd`)
|
|
76
|
+
|
|
77
|
+
A local dev server only exists on your machine, so ora can't reach it. The simplest option is to audit a publicly reachable deployment of the same code (e.g. a preview URL). To audit localhost itself, bring your own tunnel: pass `--tunnel-cmd` (or set `ORA_TUNNEL_CMD`) with a command that exposes the local server and prints its public `https://` URL. The CLI runs it, audits the URL it prints, and tears the tunnel down when done.
|
|
78
|
+
|
|
79
|
+
```
|
|
80
|
+
ax audit localhost:3000 --tunnel-cmd 'ngrok http 3000 --log stdout'
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
- **The CLI ships no tunnel vendor and never downloads executables at runtime** — any tunnel tool you already have works, as long as it prints its public URL to stdout or stderr.
|
|
84
|
+
- The result is stored as **ephemeral**: excluded from ora's rankings and deleted after a few days.
|
|
85
|
+
- Off-site checks (registry listings, brand search) usually fail for a throwaway tunnel hostname — the report says so. Use tunnel audits to iterate on your on-site surface, not to compare scores.
|
|
86
|
+
- Free tiers of some tunnel vendors serve an interstitial warning page to browser-like requests, which can distort what the scanner sees — prefer a vendor/plan that serves your origin directly.
|
|
87
|
+
|
|
88
|
+
## deep-journey
|
|
89
|
+
|
|
90
|
+
```
|
|
91
|
+
ax deep-journey <url> [--intent id | --task text] [--agent id] [--api-key k] [--no-stream] [--json]
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
```
|
|
95
|
+
ax deep-journey stripe.com --intent pricing
|
|
96
|
+
ax deep-journey zapier.com --task "Find how to build a Slack → Sheets zap" # needs a partner key
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Runs a real AI agent at a site through ora's **public** journey API — no key, no workspace needed for curated tasks. The agent's trajectory streams live as progress lines; the terminal output is ora's verdict, the billable step count, and the generated insight:
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
✓ task satisfied stripe.com
|
|
103
|
+
14 steps · 6 turns · 41.2s
|
|
104
|
+
|
|
105
|
+
The agent found the pricing page in two hops via llms.txt and correctly
|
|
106
|
+
summarised the standard and custom tiers.
|
|
107
|
+
- llms.txt was load-bearing: it linked /pricing directly
|
|
108
|
+
- no web search was needed; every path came from on-site links
|
|
109
|
+
|
|
110
|
+
For the 4-layer readiness audit, run: ax audit stripe.com
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Anonymous callers run curated intents (`pricing`, `signup`, `api-docs`, `integrate`, `support`, …) — list them with `GET https://ora.ai/api/journey/intents`, and the accepted agents with `GET https://ora.ai/api/journey/agents`. The public caps are 100 runs per rolling 24h per target and 200 runs per 24h per IP (plus a 20/min burst limit); a target at its cap answers with the most recent stored run (`rate_limited: true`) instead of an error, so repeat CI invocations are cheap. Verdict and step count come from ora's contract as-is — the CLI never re-judges a run.
|
|
114
|
+
|
|
115
|
+
**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.
|
|
116
|
+
|
|
117
|
+
If the live stream goes quiet (no frames for 120s) the CLI does not abandon the run — it switches to polling the run detail until the server reports a terminal state.
|
|
118
|
+
|
|
119
|
+
| Flag | Effect |
|
|
120
|
+
|---|---|
|
|
121
|
+
| `--intent <id>` | Curated task id (server default when omitted) |
|
|
122
|
+
| `--task <text>` | Free-text task — needs a partner API key; mutually exclusive with `--intent` |
|
|
123
|
+
| `--api-key <k>` | ora partner API key; also read from `ORA_PARTNER_API_KEY` (then `ORA_SCAN_API_KEY`) |
|
|
124
|
+
| `--agent <id>` | Agent from the public roster (default: ora's pick) |
|
|
125
|
+
| `--no-stream` | Poll for the result instead of streaming the trajectory |
|
|
126
|
+
| `--json` | Print the terminal run detail (verdict, step_count, result) as JSON |
|
|
127
|
+
|
|
128
|
+
deep-journey exit codes: `0` run succeeded (any verdict) · `1` run failed · `2` usage error · `3` API unreachable / rate-limited.
|
|
129
|
+
|
|
130
|
+
This differs from `ax journey` (below), which drives the authenticated platform with free-text goals and renders the full trajectory graph; `deep-journey` is the zero-setup public path.
|
|
131
|
+
|
|
132
|
+
## skill
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
ax skill # list the registry
|
|
136
|
+
ax skill agent-ready-website # print a SKILL.md
|
|
137
|
+
ax skill agent-ready-website --install # write .claude/skills/<name>/SKILL.md
|
|
138
|
+
ax skill --json # the raw registry index
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
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.
|
|
142
|
+
|
|
143
|
+
## journey
|
|
144
|
+
|
|
145
|
+
```
|
|
146
|
+
ax journey "<intent>" [--domain d] [--harness h] [--model m] [--json]
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
```
|
|
150
|
+
ax journey "Find the API docs and how to authenticate" --domain stripe.com
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Triggers a real agent run on ora's platform and renders the journey live — the whole graph repaints in place as the agent moves:
|
|
154
|
+
|
|
155
|
+
```
|
|
156
|
+
▶ stripe.com · claude-code
|
|
157
|
+
|
|
158
|
+
9 steps · 3 reasoning · 1 search
|
|
159
|
+
|
|
160
|
+
╭────────────────────────────────────────────────────────────────────────────────╮
|
|
161
|
+
│ ◆ Find the API docs and how to authenticate. Fetch the actual pages to verify. │
|
|
162
|
+
╰─┬──────────────────────────────────────────────────────────────────────────────╯
|
|
163
|
+
│ (…) The user is asking me to find the API documentation for Stripe…
|
|
164
|
+
│ ╭──────────────────────────────────────────────╮
|
|
165
|
+
╰──┤ 🔍 "Stripe API documentation authentication" │
|
|
166
|
+
╰─┬────────────────────────────────────────────╯
|
|
167
|
+
│ ╭─────────────────────────────────────────╮
|
|
168
|
+
├──┤ 🌐 docs.stripe.com/api/authentication ✓ │
|
|
169
|
+
│ ╰─────────────────────────────────────────╯
|
|
170
|
+
│ ╭───────────────────────────╮
|
|
171
|
+
╰──┤ 🌐 docs.stripe.com/apis ✓ │
|
|
172
|
+
╰───────────────────────────╯
|
|
173
|
+
|
|
174
|
+
────────────────────────────────────────────────────
|
|
175
|
+
✓ completed 9 turns · 30.8s · 119.1k tokens · $0.031
|
|
176
|
+
|
|
177
|
+
Visibility █████████████████████░ 95/100 ✓ intent satisfied
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Edges come from ora's own per-step attribution (link-follows nest under the page that linked them; searches hang off the intent). `(…)` markers are the agent's reasoning, placed above the action it led to.
|
|
181
|
+
|
|
182
|
+
| Flag | Effect |
|
|
183
|
+
|---|---|
|
|
184
|
+
| `--domain <d>` | Site the agent targets (e.g. `stripe.com`) |
|
|
185
|
+
| `--harness <h>` | Agent harness: `claude-code` (default), `codex`, `openclaw`, `hermess`, `claude-agent`, `eve`, … |
|
|
186
|
+
| `--model <m>` | Model override (e.g. `claude-haiku-4-5-20251001` — cheap and good for demos) |
|
|
187
|
+
| `--json` | Full result as JSON: run metadata, usage, insight, and the raw trajectory |
|
|
188
|
+
|
|
189
|
+
Note: run-to-run variance is real — agents sometimes answer from search snippets without fetching, which scores differently. Run a few journeys before drawing conclusions.
|
|
190
|
+
|
|
191
|
+
Journey exit codes: `0` run outcome `success` · `1` non-success outcome · `2` any error.
|
|
192
|
+
|
|
193
|
+
### Setup
|
|
194
|
+
|
|
195
|
+
`journey` needs an ora platform API key (scopes `runs:read` + `runs:write`):
|
|
196
|
+
|
|
197
|
+
```sh
|
|
198
|
+
export ORA_API_KEY=ora_sk_... # your shell, CI secret store, etc.
|
|
199
|
+
ax journey "Find the pricing page" --domain example.com
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
For local development, copy `.env.example` to `.env` — the CLI reads a `.env` in the working directory on startup (exported variables win over the file).
|
|
203
|
+
|
|
204
|
+
## Library use
|
|
205
|
+
|
|
206
|
+
The same contract-typed client the CLI uses is importable:
|
|
207
|
+
|
|
208
|
+
```ts
|
|
209
|
+
import { audit } from "ax";
|
|
210
|
+
|
|
211
|
+
const { result } = await audit("stripe.com");
|
|
212
|
+
console.log(result.score, result.grade, result.topFixes);
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
`result` is the raw versioned audit payload (`AuditScanResult` / `AuditScoreResult`, generated from ora's OpenAPI spec). `fetchSkill` / `fetchSkillIndex` expose the digest-verified skill registry.
|
|
216
|
+
|
|
217
|
+
The public journey client is exported too — the same no-key path as `ax deep-journey`:
|
|
218
|
+
|
|
219
|
+
```ts
|
|
220
|
+
import { deepJourney, fetchJourneyAgents } from "ax";
|
|
221
|
+
|
|
222
|
+
const { agents, defaultId } = await fetchJourneyAgents();
|
|
223
|
+
const agent = agents.find((a) => a.id === defaultId)!;
|
|
224
|
+
const { detail } = await deepJourney("stripe.com", {
|
|
225
|
+
intentId: "pricing",
|
|
226
|
+
harness: agent.harness,
|
|
227
|
+
model: agent.model,
|
|
228
|
+
});
|
|
229
|
+
console.log(detail.verdict, detail.step_count, detail.result?.insight.summary);
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
`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.
|
|
233
|
+
|
|
234
|
+
## Environment variables
|
|
235
|
+
|
|
236
|
+
All configuration is environment-first: the consumer defines the variables, the CLI only reads them.
|
|
237
|
+
|
|
238
|
+
A `.env` in the working directory is read on startup — copy `.env.example` and fill it in. Anything already exported wins over the file, so a key set for your shell or by CI beats a stale `.env`.
|
|
239
|
+
|
|
240
|
+
| Var | Used by | Default | Purpose |
|
|
241
|
+
|---|---|---|---|
|
|
242
|
+
| `ORA_API_URL` | audit, deep-journey, skill | `https://ora.ai` | Public API base (no auth) |
|
|
243
|
+
| `ORA_PLATFORM_URL` | journey | `https://api.agentfront.sh` | Authenticated platform API base |
|
|
244
|
+
| `ORA_TUNNEL_CMD` | audit | — (optional) | Tunnel command for a local target (same as `--tunnel-cmd`) |
|
|
245
|
+
| `ORA_API_KEY` | journey | — (required) | Secret key (`ora_sk_…`), exchanged for a short-lived bearer token |
|
|
246
|
+
| `ORA_SCAN_API_KEY` | audit, deep-journey | — (optional) | ora-issued scan API key; lifts every scan rate limit (issued manually by ora). deep-journey accepts it as a partner-key fallback |
|
|
247
|
+
| `ORA_PARTNER_API_KEY` | deep-journey | — (optional) | ora-issued partner API key; unlocks `--task` and the 1000/24h keyed allowance |
|
|
248
|
+
|
|
249
|
+
## Contract versioning
|
|
250
|
+
|
|
251
|
+
The audit types are generated from ora's served OpenAPI spec (`pnpm contract:gen`); the build is pinned to a contract version and CI fails when production drifts from the checked-in types. At runtime, the CLI prints one stderr warning when ora reports a newer contract than the build — upgrade with `npm i -g ax@latest`.
|
|
252
|
+
|
|
253
|
+
## Migrating from 0.1.x
|
|
254
|
+
|
|
255
|
+
- `ax scan` is now `ax audit` (no alias).
|
|
256
|
+
- `--json` prints the raw ora audit payload instead of the old reshaped envelope: stable check ids, layer ids, `grade`, `topFixes`, and `contractVersion` — key your scripts to those fields.
|
|
257
|
+
- Audit API failures now exit `3` (usage errors stay `2`).
|
|
258
|
+
|
|
259
|
+
## Development
|
|
260
|
+
|
|
261
|
+
```sh
|
|
262
|
+
pnpm install
|
|
263
|
+
pnpm test # vitest (watch)
|
|
264
|
+
pnpm test:ci # single run + coverage
|
|
265
|
+
pnpm typecheck
|
|
266
|
+
pnpm lint
|
|
267
|
+
pnpm contract:gen # regenerate src/contract/ from the served OpenAPI spec
|
|
268
|
+
pnpm build # tsup → dist/main.cjs (bin) + dist/index.* (library)
|
|
269
|
+
pnpm smoke # run the built binary the way a user would (needs build)
|
|
270
|
+
pnpm verify:pack # check the tarball npm would publish (needs build)
|
|
271
|
+
node dist/main.cjs audit https://example.com
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Manual testing without burning the live scan rate limit:
|
|
275
|
+
|
|
276
|
+
```sh
|
|
277
|
+
node scripts/mock-scan-server.mjs &
|
|
278
|
+
ORA_API_URL=http://localhost:8799 node dist/main.cjs audit https://example.com
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
To exercise the published-package experience locally: `npm pack`, then `npx ./ora-ai-ax-<version>.tgz audit https://example.com`, or `pnpm link --global` and use `ax` directly.
|
|
282
|
+
|
|
283
|
+
## Releasing
|
|
284
|
+
|
|
285
|
+
Publishing runs from GitHub Actions only — **Actions → Release → Run workflow**,
|
|
286
|
+
pick a `patch`/`minor`/`major` bump. See [RELEASING.md](RELEASING.md) for the
|
|
287
|
+
runbook, required setup, and failure recovery.
|
|
288
|
+
|
|
289
|
+
## License
|
|
290
|
+
|
|
291
|
+
MIT
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import type { AuditScanResult, AuditScoreResult } from "../contract";
|
|
2
|
+
/** Any failure to obtain a result from ora: network, HTTP, rate limit, timeout. */
|
|
3
|
+
export declare class AuditApiError extends Error {
|
|
4
|
+
}
|
|
5
|
+
/**
|
|
6
|
+
* The raw audit payload: scan-shaped from the stream's terminal event,
|
|
7
|
+
* score-shaped once deep-analysis polling has taken over.
|
|
8
|
+
*/
|
|
9
|
+
export type AuditResult = AuditScanResult | AuditScoreResult;
|
|
10
|
+
export interface AuditOutcome {
|
|
11
|
+
/** The raw `?format=audit` contract payload, untouched. */
|
|
12
|
+
result: AuditResult;
|
|
13
|
+
/**
|
|
14
|
+
* ora's one-line agentic verdict. Rides the stream's `summary_ready` event,
|
|
15
|
+
* not the audit payload, so it is carried alongside rather than injected.
|
|
16
|
+
*/
|
|
17
|
+
verdict?: string;
|
|
18
|
+
}
|
|
19
|
+
export interface AuditOptions {
|
|
20
|
+
/** Receives one-line progress updates while the scan streams and polls. */
|
|
21
|
+
progress?: (line: string) => void;
|
|
22
|
+
/** Base URL override; otherwise $ORA_API_URL, otherwise https://ora.ai. */
|
|
23
|
+
baseUrl?: string;
|
|
24
|
+
/** Abort when the stream is silent for this long (default 60s). */
|
|
25
|
+
idleMs?: number;
|
|
26
|
+
pollEveryMs?: number;
|
|
27
|
+
pollLimit?: number;
|
|
28
|
+
/** Freshness window in seconds (server clamps to [3600, 86400]). */
|
|
29
|
+
maxAgeSeconds?: number;
|
|
30
|
+
/** Bypass the freshness cache (spends the stricter 6/day force budget). */
|
|
31
|
+
force?: boolean;
|
|
32
|
+
/** Store the result as disposable (tunnel hosts are auto-classified). */
|
|
33
|
+
ephemeral?: boolean;
|
|
34
|
+
/**
|
|
35
|
+
* ora-issued scan API key (contract 1.10.0): exempts the caller from every
|
|
36
|
+
* scan-family rate limit. Falls back to $ORA_SCAN_API_KEY. Safe to send
|
|
37
|
+
* blind — the server degrades an unrecognized key to keyless, never a 401.
|
|
38
|
+
*/
|
|
39
|
+
apiKey?: string;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Audit `target` and resolve with ora's raw audit payload. When the stream
|
|
43
|
+
* ends with analysis still marked partial, keeps polling
|
|
44
|
+
* GET /api/score/{domain}?format=audit until it settles (complete or stuck)
|
|
45
|
+
* or the poll budget runs out.
|
|
46
|
+
*/
|
|
47
|
+
export declare function performAudit(target: string, options?: AuditOptions): Promise<AuditOutcome>;
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
import type { JourneyRun, JourneyRunDetail } from "../contract";
|
|
2
|
+
/** Any failure to obtain a run from ora: network, HTTP, rate limit, stream error. */
|
|
3
|
+
export declare class DeepJourneyApiError extends Error {
|
|
4
|
+
}
|
|
5
|
+
export interface JourneyIntentOption {
|
|
6
|
+
id: string;
|
|
7
|
+
label: string;
|
|
8
|
+
hint: string;
|
|
9
|
+
template: string;
|
|
10
|
+
}
|
|
11
|
+
export interface JourneyAgentOption {
|
|
12
|
+
id: string;
|
|
13
|
+
label: string;
|
|
14
|
+
variant: string;
|
|
15
|
+
harness: string;
|
|
16
|
+
model: string;
|
|
17
|
+
blurb?: string;
|
|
18
|
+
}
|
|
19
|
+
/** The per-target allowance the POST response advertises via X-RateLimit-*. */
|
|
20
|
+
export interface RunAllowance {
|
|
21
|
+
limit?: number;
|
|
22
|
+
remaining?: number;
|
|
23
|
+
/** Unix ms when the next per-target slot frees; absent when unknown. */
|
|
24
|
+
resetAtMs?: number;
|
|
25
|
+
}
|
|
26
|
+
export interface DeepJourneyOptions {
|
|
27
|
+
/** Curated intent id; the server default when omitted. */
|
|
28
|
+
intentId?: string;
|
|
29
|
+
/**
|
|
30
|
+
* Free-text task (the keyed custom arm, 4-300 chars server-side). Needs a
|
|
31
|
+
* partner API key; mutually exclusive with `intentId` (the command layer
|
|
32
|
+
* enforces the exclusivity, this client just sends whichever arm is set).
|
|
33
|
+
*/
|
|
34
|
+
task?: string;
|
|
35
|
+
/**
|
|
36
|
+
* ora-issued partner API key, sent as `Authorization: Bearer`. Unlocks
|
|
37
|
+
* free-text tasks and moves the caller to the 1000/24h per-key allowance
|
|
38
|
+
* (no per-target cap, no burst guard). Falls back to $ORA_PARTNER_API_KEY,
|
|
39
|
+
* then $ORA_SCAN_API_KEY (the shared partner registry serves both
|
|
40
|
+
* surfaces). Safe to send a wrong key with a curated intent - the server
|
|
41
|
+
* silently degrades to the keyless tier.
|
|
42
|
+
*/
|
|
43
|
+
apiKey?: string;
|
|
44
|
+
harness: string;
|
|
45
|
+
model: string;
|
|
46
|
+
/** Receives one-line progress updates while the run streams/polls. */
|
|
47
|
+
progress?: (line: string) => void;
|
|
48
|
+
/** Base URL override; otherwise $ORA_API_URL, otherwise https://ora.ai. */
|
|
49
|
+
baseUrl?: string;
|
|
50
|
+
/** Abort when the stream is silent for this long (default 120s). */
|
|
51
|
+
idleMs?: number;
|
|
52
|
+
/** Skip the SSE and poll GET /api/journey/runs/{id} instead. */
|
|
53
|
+
noStream?: boolean;
|
|
54
|
+
pollEveryMs?: number;
|
|
55
|
+
pollLimit?: number;
|
|
56
|
+
}
|
|
57
|
+
export interface DeepJourneyOutcome {
|
|
58
|
+
/** The projected run record from the trigger (or the cached latest run). */
|
|
59
|
+
record: JourneyRun;
|
|
60
|
+
/** True when the per-target cap answered with the stored latest run. */
|
|
61
|
+
cached: boolean;
|
|
62
|
+
/** Milliseconds until a per-target slot frees, on a cached answer. */
|
|
63
|
+
retryAfterMs?: number;
|
|
64
|
+
allowance: RunAllowance;
|
|
65
|
+
/** Terminal detail: status, verdict, step_count, and result once succeeded. */
|
|
66
|
+
detail: JourneyRunDetail;
|
|
67
|
+
/** The stream's terminal error message, when the run failed mid-stream. */
|
|
68
|
+
engineError?: string;
|
|
69
|
+
}
|
|
70
|
+
/** The curated intents a public run can execute. */
|
|
71
|
+
export declare function fetchJourneyIntents(baseUrl?: string): Promise<{
|
|
72
|
+
intents: JourneyIntentOption[];
|
|
73
|
+
defaultId: string;
|
|
74
|
+
}>;
|
|
75
|
+
/** The agents an anonymous run request accepts. */
|
|
76
|
+
export declare function fetchJourneyAgents(baseUrl?: string): Promise<{
|
|
77
|
+
agents: JourneyAgentOption[];
|
|
78
|
+
defaultId: string;
|
|
79
|
+
}>;
|
|
80
|
+
export declare function formatWait(ms: number): string;
|
|
81
|
+
/** Non-streaming run detail (verdict, step_count, result once succeeded). */
|
|
82
|
+
export declare function fetchRunDetail(base: string, runId: string): Promise<JourneyRunDetail>;
|
|
83
|
+
/**
|
|
84
|
+
* Run a deep journey against `target` and resolve with the terminal detail.
|
|
85
|
+
* Streams the trajectory by default (progress lines via `options.progress`);
|
|
86
|
+
* with `noStream`, polls the record instead. A per-target-capped trigger is
|
|
87
|
+
* NOT an error: ora answers with the most recent stored run for that target,
|
|
88
|
+
* and the outcome carries `cached: true` plus `retryAfterMs`.
|
|
89
|
+
*/
|
|
90
|
+
export declare function performDeepJourney(target: string, options: DeepJourneyOptions): Promise<DeepJourneyOutcome>;
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
export interface RunSummary {
|
|
2
|
+
run_id: string;
|
|
3
|
+
domain?: string;
|
|
4
|
+
intent?: string;
|
|
5
|
+
harness?: string;
|
|
6
|
+
model?: string;
|
|
7
|
+
effective_model?: string;
|
|
8
|
+
outcome: string;
|
|
9
|
+
num_turns?: number;
|
|
10
|
+
duration_ms?: number;
|
|
11
|
+
started_at?: string;
|
|
12
|
+
finished_at?: string;
|
|
13
|
+
last_seq?: number;
|
|
14
|
+
}
|
|
15
|
+
export interface InsightRecommendation {
|
|
16
|
+
title: string;
|
|
17
|
+
detail: string;
|
|
18
|
+
priority?: string;
|
|
19
|
+
}
|
|
20
|
+
export interface JourneyInsight {
|
|
21
|
+
summary?: string;
|
|
22
|
+
outcome?: string;
|
|
23
|
+
visibility_score?: number;
|
|
24
|
+
intent_satisfied?: boolean;
|
|
25
|
+
task_satisfied?: string;
|
|
26
|
+
key_observations?: string[];
|
|
27
|
+
friction_points?: string[];
|
|
28
|
+
recommendations?: InsightRecommendation[];
|
|
29
|
+
intent_category?: string;
|
|
30
|
+
journey_layers?: string[];
|
|
31
|
+
/** Usage of the analyzer that produced the insight — not the run itself. */
|
|
32
|
+
usage?: {
|
|
33
|
+
input_tokens?: number;
|
|
34
|
+
output_tokens?: number;
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* One entry of a `trajectory` snapshot. Richer than the raw `step` events: a
|
|
39
|
+
* tool call arrives merged with its result (status, duration, structured
|
|
40
|
+
* output) plus ora's attribution of where the agent got the target from.
|
|
41
|
+
*/
|
|
42
|
+
export interface JourneyStep {
|
|
43
|
+
id: number;
|
|
44
|
+
turn: number;
|
|
45
|
+
type: string;
|
|
46
|
+
kind?: string;
|
|
47
|
+
text?: string;
|
|
48
|
+
thinking?: string;
|
|
49
|
+
tool?: string;
|
|
50
|
+
action?: string;
|
|
51
|
+
input?: Record<string, unknown>;
|
|
52
|
+
input_display?: string;
|
|
53
|
+
summary?: string;
|
|
54
|
+
label?: string;
|
|
55
|
+
status?: number;
|
|
56
|
+
duration_ms?: number;
|
|
57
|
+
is_error?: boolean;
|
|
58
|
+
output_structured?: {
|
|
59
|
+
body?: string;
|
|
60
|
+
links?: Array<{
|
|
61
|
+
title?: string;
|
|
62
|
+
url?: string;
|
|
63
|
+
}>;
|
|
64
|
+
};
|
|
65
|
+
elapsed_ms?: number;
|
|
66
|
+
attribution?: {
|
|
67
|
+
kind?: string;
|
|
68
|
+
method?: string;
|
|
69
|
+
confidence?: string;
|
|
70
|
+
/** For link-follows: the exact step this URL was discovered on. */
|
|
71
|
+
referrer?: {
|
|
72
|
+
step_id?: number;
|
|
73
|
+
turn?: number;
|
|
74
|
+
artifact_kind?: string;
|
|
75
|
+
url_path?: string;
|
|
76
|
+
};
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
/** A raw `step` event payload (loosely typed; the CLI never renders from these). */
|
|
80
|
+
export interface RawRunStep {
|
|
81
|
+
type: string;
|
|
82
|
+
turn?: number;
|
|
83
|
+
tool?: string;
|
|
84
|
+
[extra: string]: unknown;
|
|
85
|
+
}
|
|
86
|
+
/** Run-level token/cost totals, read from the runs list after completion. */
|
|
87
|
+
export interface RunSpend {
|
|
88
|
+
totalTokens?: number;
|
|
89
|
+
inputTokens?: number;
|
|
90
|
+
outputTokens?: number;
|
|
91
|
+
cacheReadTokens?: number;
|
|
92
|
+
cacheCreationTokens?: number;
|
|
93
|
+
costUsd?: number;
|
|
94
|
+
}
|
|
95
|
+
export interface JourneyHooks {
|
|
96
|
+
/** Fired exactly once when the run exists (the stream's own `run` event is ignored). */
|
|
97
|
+
opened?: (runId: string) => void;
|
|
98
|
+
/**
|
|
99
|
+
* A full-trajectory snapshot arrived. These flow every few seconds while
|
|
100
|
+
* the agent works and are the ONLY live signal — drive all UI from here.
|
|
101
|
+
*/
|
|
102
|
+
snapshot?: (steps: JourneyStep[]) => void;
|
|
103
|
+
/**
|
|
104
|
+
* A raw `step` event arrived. ⚠ The server flushes these in one burst at
|
|
105
|
+
* the very end of the run; rendering from them means a blank screen until
|
|
106
|
+
* the agent finishes.
|
|
107
|
+
*/
|
|
108
|
+
step?: (step: RawRunStep, seq: number) => void;
|
|
109
|
+
finished?: (summary: RunSummary) => void;
|
|
110
|
+
scored?: (insight: JourneyInsight) => void;
|
|
111
|
+
}
|
|
112
|
+
export interface RunRequest {
|
|
113
|
+
intent: string;
|
|
114
|
+
domain?: string;
|
|
115
|
+
harness?: string;
|
|
116
|
+
model?: string;
|
|
117
|
+
/** "harness" = tool-using agent (default); "direct" = single LLM answer. */
|
|
118
|
+
executionKind?: "harness" | "direct";
|
|
119
|
+
baseUrl?: string;
|
|
120
|
+
apiKey?: string;
|
|
121
|
+
idleMs?: number;
|
|
122
|
+
}
|
|
123
|
+
export interface JourneyRun {
|
|
124
|
+
runId: string;
|
|
125
|
+
intent: string;
|
|
126
|
+
domain?: string;
|
|
127
|
+
harness?: string;
|
|
128
|
+
result?: RunSummary;
|
|
129
|
+
insight?: JourneyInsight;
|
|
130
|
+
usage?: RunSpend;
|
|
131
|
+
steps: RawRunStep[];
|
|
132
|
+
/** The last trajectory snapshot seen — the definitive step list. */
|
|
133
|
+
trajectory: JourneyStep[];
|
|
134
|
+
}
|
|
135
|
+
export declare function decodeEventBlock(block: string): {
|
|
136
|
+
event: string;
|
|
137
|
+
data: string;
|
|
138
|
+
} | null;
|
|
139
|
+
export declare function launchJourney(request: RunRequest, hooks?: JourneyHooks): Promise<JourneyRun>;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Idle watchdog for a long-lived stream: aborts the fetch when `poke()` hasn't
|
|
3
|
+
* been called for `ms`. Unlike a fixed deadline, a stream that keeps emitting
|
|
4
|
+
* can run indefinitely — which is what a slow-but-healthy scan or agent needs.
|
|
5
|
+
*/
|
|
6
|
+
export declare function watchdog(ms: number): {
|
|
7
|
+
signal: AbortSignal;
|
|
8
|
+
poke: () => void;
|
|
9
|
+
disarm: () => void;
|
|
10
|
+
tripped: () => boolean;
|
|
11
|
+
};
|
|
12
|
+
/** Best-effort human message from an error response body. */
|
|
13
|
+
export declare function errorBodyText(res: Response): Promise<string>;
|
|
14
|
+
export declare const pause: (ms: number) => Promise<void>;
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
export declare class SkillApiError extends Error {
|
|
2
|
+
}
|
|
3
|
+
export interface SkillEntry {
|
|
4
|
+
name: string;
|
|
5
|
+
type?: string;
|
|
6
|
+
description?: string;
|
|
7
|
+
/** Path or absolute URL to the SKILL.md. */
|
|
8
|
+
url: string;
|
|
9
|
+
/** `sha256:<hex>` over the exact SKILL.md bytes. */
|
|
10
|
+
digest?: string;
|
|
11
|
+
}
|
|
12
|
+
export declare function resolveBase(baseUrl?: string): string;
|
|
13
|
+
export declare function fetchSkillIndex(baseUrl?: string): Promise<SkillEntry[]>;
|
|
14
|
+
export declare function digestOf(bytes: Uint8Array): string;
|
|
15
|
+
export interface FetchedSkill {
|
|
16
|
+
entry: SkillEntry;
|
|
17
|
+
/** The exact SKILL.md bytes, digest-verified against the index. */
|
|
18
|
+
bytes: Uint8Array;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* Fetch one skill's SKILL.md and verify it against the index digest. A
|
|
22
|
+
* mismatch is refused outright - never serve bytes the index does not vouch
|
|
23
|
+
* for.
|
|
24
|
+
*/
|
|
25
|
+
export declare function fetchSkill(name: string, baseUrl?: string): Promise<FetchedSkill>;
|