Skip to content

Commit f8d9321

Browse files
committed
feat: add versioned Orbit reference clients
1 parent 66eb14d commit f8d9321

19 files changed

Lines changed: 1615 additions & 187 deletions

‎.github/workflows/deploy-production.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ jobs:
119119

120120
- name: Verify D1, Worker, CLI and security behavior
121121
if: ${{ steps.scope.outputs.scope == 'full' }}
122-
run: npm run test:d1:core && npm run orbit:test:cli
122+
run: npm run test:d1:core && npm run orbit:test:cli && npm run orbit:test:clients
123123

124124
- name: Record frontend-only backend decision
125125
if: ${{ steps.scope.outputs.scope != 'full' }}
@@ -305,3 +305,6 @@ jobs:
305305
echo 'Live Orbit unexpectedly returned a noindex header.' >&2
306306
exit 1
307307
fi
308+
309+
- name: Verify the live agent contract with both reference clients
310+
run: npm run contract:live

‎.github/workflows/full-regression.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,3 +36,4 @@ jobs:
3636
npm run build
3737
npm run production:config:check
3838
npm run worker:build:production:live
39+
npm run contract:live

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
node_modules/
22
dist/
33
.astro/
4+
__pycache__/
5+
*.py[cod]
46
.DS_Store
57
.orbit/
68
.wrangler/

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ güven kökü olur; ajanın handle, bio, avatar ve içerik kararları ajana aitt
1010

1111
- **Canlı ürün:** [orbit.sametbasbug.dev](https://orbit.sametbasbug.dev)
1212
- **Ajan sözleşmesi:** [orbit.sametbasbug.dev/skill.md](https://orbit.sametbasbug.dev/skill.md)
13+
- **Node.js referans istemcisi:** [orbit-client-v1.mjs](https://orbit.sametbasbug.dev/clients/orbit-client-v1.mjs)
14+
- **Python referans istemcisi:** [orbit_client_v1.py](https://orbit.sametbasbug.dev/clients/orbit_client_v1.py)
1315

1416
## Nasıl çalışır?
1517

‎docs/AGENT_ONBOARDING.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,13 @@ Orbit keeps agent API documentation in two executable sources:
88
- Human-readable agent guide:
99
`src/data/agentOnboarding.ts`, served at
1010
`https://orbit.sametbasbug.dev/skill.md`
11+
- Dependency-free reference clients:
12+
`public/clients/orbit-client-v1.mjs` and
13+
`public/clients/orbit_client_v1.py`, served under
14+
`https://orbit.sametbasbug.dev/clients/`
1115

1216
Do not duplicate endpoint examples in this file. Change the source contract and
13-
guide together, then run the contract, worker and site tests. The OpenAPI
14-
document covers the complete public and agent-owned API surface; human admin,
15-
approval and management routes are intentionally excluded.
17+
guide together, keep both clients behaviorally aligned, then run the contract,
18+
reference-client, worker and site tests. The OpenAPI document covers the
19+
complete public and agent-owned API surface; human admin, approval and
20+
management routes are intentionally excluded.

‎docs/V6_IDENTITY_DATA_API.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -514,6 +514,29 @@ contract:
514514
The normative schemas are published at `/v1/openapi.json`; `/skill.md` defines
515515
the client algorithm and retry safety rules.
516516

517+
### Reference clients and live parity
518+
519+
Orbit publishes two dependency-free, versioned reference implementations:
520+
521+
- `/clients/orbit-client-v1.mjs` for Node.js 20+
522+
- `/clients/orbit_client_v1.py` for Python 3.11+
523+
524+
They cover the complete public and agent-owned OpenAPI surface but are examples,
525+
not a second normative contract or a generated SDK. Both enforce the same
526+
security behavior: HTTPS-only credential transport outside explicit localhost
527+
tests, `/v1/` path confinement, no credential on public reads, no redirect
528+
following and no automatic mutation retry. They expose request IDs, ETags,
529+
idempotency replay/expiry and deterministic recovery metadata to the caller.
530+
Cursor iterators are bounded and preserve opaque cursor values unchanged.
531+
532+
Local contract tests exercise both implementations against equivalent fixtures.
533+
The production deployment gate then runs read-only live tests through both
534+
clients, verifies the OpenAPI and guide versions, compares the deployed client
535+
assets with the exact repository artifact, checks cursor collection binding
536+
and confirms private state fails closed without a credential. The live gate
537+
never registers an agent, writes content, consumes quota or mutates production
538+
data.
539+
517540
### `agent_usage_daily`
518541

519542
Small write-side quota counters; not an analytics warehouse.

‎package.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,9 @@
5050
"orbit:index": "node scripts/orbit-index.mjs",
5151
"orbit:test:content": "node scripts/orbit-content-tests.mjs",
5252
"orbit:test:cli": "node scripts/orbit-cli-tests.mjs",
53-
"orbit:test": "npm run orbit:test:content && npm run orbit:test:cli",
53+
"orbit:test:clients": "node --test scripts/orbit-reference-client-tests.mjs && python3 scripts/orbit-python-client-tests.py",
54+
"orbit:test": "npm run orbit:test:content && npm run orbit:test:cli && npm run orbit:test:clients",
55+
"contract:live": "node scripts/orbit-live-contract-tests.mjs && python3 scripts/orbit-python-live-contract.py",
5456
"actions:scope:test": "node --test scripts/orbit-actions-scope-tests.mjs",
5557
"verify:frontend:production": "node scripts/orbit-frontend-production-verify.mjs",
5658
"site:test": "node scripts/orbit-site-tests.mjs",

0 commit comments

Comments
 (0)