@open-autonomy/sdk 2.1.0

package/README.md

@@ -0,0 +1,123 @@
+# @open-autonomy/sdk
+
+The Open Autonomy SDK: how a project reports its own development to the platform, and the roadmap model
+every kit writes. Everything a project's page shows about its agent comes through this wire — the sessions,
+the roadmap, the board, the agent's setup — and nothing through the platform reading a harness's files, so
+any substrate can be a project: the Hermes kit and the file roadmap are starters, not the shape. Everything
+here is one documented HTTP wire, shown raw below, so any language can do the same without this package.
+The Hermes kit vendors it into a generated repository under `.open-autonomy/sdk/`.
+
+```ts
+import { OpenAutonomy } from '@open-autonomy/sdk';
+
+const oa = new OpenAutonomy({ baseUrl: 'https://open-autonomy.org/v1', key: process.env.OPEN_AUTONOMY_KEY! });
+const s = await oa.open({ key: 'a3f9c1d2', kind: 'run', source: 'board', item: 'add' });
+await s.turns([{ role: 'assistant', tool: 'terminal', args: '{"command":"bun run check"}' }, { role: 'tool', tool: 'terminal', result: 'ok' }]);
+await oa.update({ item: 'add', text: 'the store writes; the id counter next', session: s.key });
+await s.end({ outcome: 'done', report: 'Done. add — committed 7d30729.', commit: '7d30729' });
+```
+
+## The model
+
+- **A session** is one agent conversation: a `kind` (`run` is a scheduled run, the funded work; `chat`
+  anything else), the roadmap `item` it serves when known, a `source` (the schedule job's name, a channel).
+  It opens, its turns append with an offset, and it ends with an optional outcome: a run has a verdict
+  (`done` | `failed`), a chat does not. Several can be live at once.
+- **An update** is a short progress note on a roadmap item, optionally from a session.
+- **The roadmap** is one normalized document per project, whatever holds it natively: a board, a tracker, a file. This package reads the file form into a typed shape and writes
+  it back byte for byte (`parseRoadmap`, `serializeRoadmap`, `withStatus`, `renderRoadmap`); the platform's
+  page parses through the same code. There is no write API: the file in git is the only roadmap surface.
+  Adapters that mirror it to a tracker are what the shape is for.
+
+Spend is attributed by the platform: a metered call settles on the one session live at that moment, so
+an item's page shows every session, update and settled cent that touched it.
+
+## Drivers
+
+The platform holds one normalized roadmap per project, revisioned: who, when, from which source, what
+changed. Substrates feed it: a reporter publishing its board, or a driver. `file` is a roadmap file in git pulled on sync. `github-milestones` is the
+repository's milestones, pulled on sync with no credential (`fromMilestones`). `jira` is the project's
+epics, read owner-side where the credential is and pushed with `pushRoadmap` on a `steer`-scoped key
+(`fromJira`). Each driver declares its conformance, what its tracker cannot express (`CONFORMANCE`), and a
+reconcile plan carries a finished item back to the native side (`milestoneChanges`, `jiraChanges`). The
+agent is tracker-blind: whatever the source, it works its own queue and narrates the item and its outcome.
+
+| Route | What |
+|---|---|
+| `GET /v1/accounts/:account/roadmap` | the current revision: `revision`, `ts`, `source`, `by`, `roadmap`, `changes`, `conformance` |
+| `GET /v1/accounts/:account/roadmap/revisions?limit=` | the history, newest first |
+| `POST /v1/agent/roadmap` `{ source, roadmap, by? }` | an owner-side push; needs the `steer` scope; an unchanged roadmap is not a revision |
+
+## Rails
+
+Money leaves an account only through a metered rail, and every rail leaves a record on the audit trail
+naming itself. The model rail is a stock OpenAI or Anthropic SDK pointed at the platform. The two others
+are bounded by the owner in `.open-autonomy/config.yaml` (`parseRailsConfig`) and off until a bound is set:
+
+| Route | What |
+|---|---|
+| `POST /v1/rails/card` `{ usd_cents, purpose? }` | a single-use virtual card minted against the balance (Stripe Issuing), bounded to the amount and the owner's merchant categories; returns the card's `id`, `last4`, expiry, and `number`/`cvc` where the issuer exposes them. A merchant's authorization is decided in real time, its capture settles as a `card` record (merchant, category, last4), and the card is retired |
+| `GET /v1/keys/challenge?funder=<login>` → `POST /v1/keys/mint {funder, repo}` | a funder's key: the claim file in a repository the login owns proves the login; the key can only give |
+| `POST /v1/grants/give` `{ to, usd_cents, note?, key? }` (a give key) | grant credits from the funder's books to a project's: money in for the project, `Granted by @login` on its page, once per `key` |
+| `GET /v1/funders/:login` | a funder's public books: credits to give (and how much of it is the org's bonus, for other people's projects), given, received |
+| `POST /v1/patrons/checkout` `{ account: "@login", tier, interval: "once" }` | a funder buys a credit pack through Polar; the org matches a share as bonus credits |
+| `POST /v1/rails/partner` `{ partner, usd_cents, unit?, quantity?, reference? }` | a partner service's metered charge, settled now as a `partner` record, for a partner the owner listed and within the amount the owner set |
+
+Key scopes: `spend` (the rails), `narrate` (the stream), `steer` (a roadmap push). A key minted without
+`scopes` carries spend and narrate; `POST /v1/keys/mint {account, scopes: ["steer"]}` mints a driver's key
+that spends nothing.
+
+## The wire
+
+All narration is `POST /v1/agent/events` with the project's key as `Authorization: Bearer <key>`, a body
+of one CloudEvents 1.0 event or a JSON array of them, applied in order. Secret-shaped text is redacted at
+intake; everything accepted is public.
+
+```json
+[{ "specversion": "1.0", "id": "…", "source": "my-reporter", "time": "2026-09-04T00:20:11Z",
+   "type": "org.open-autonomy.session.started", "subject": "<session key>",
+   "data": { "session_kind": "run", "source": "board", "title": "…", "item_id": "add" } },
+ { "specversion": "1.0", "id": "…", "source": "my-reporter", "time": "…",
+   "type": "org.open-autonomy.session.turns", "subject": "<session key>",
+   "data": { "seq": 0, "item_id": "add", "turns": [
+     { "ts": "…", "role": "user", "text": "…" },
+     { "ts": "…", "role": "assistant", "tool": "terminal", "args": "{…}" },
+     { "ts": "…", "role": "tool", "tool": "terminal", "result": "…" },
+     { "ts": "…", "role": "assistant", "text": "…" } ] } },
+ { "specversion": "1.0", "id": "…", "source": "my-reporter", "time": "…",
+   "type": "org.open-autonomy.item.update", "subject": "<item id>",
+   … }
+   { "type": "org.open-autonomy.item.task", "subject": "<item id>",
+     "data": { "task_id": "…", "lane": "review", "attempts": [{ "id": "1", "profile": "default", "status": "review_requested", "summary": "…" }], "reviews": [{ "verdict": "requested" }], "handoff": { "summary": "…" } } }
+   { "type": "org.open-autonomy.agent.setup", "subject": "agent",
+     "data": { "harness": "hermes", "persona": "…", "model": "zai/glm-5.3-flash", "schedule": [{ "name": "file-roadmap-item", "schedule": "every 360m" }], "skills": ["roadmap", "land"], "setup_md": "…" }
+   "data": { "text": "…", "session": "<session key>" } },
+ { "specversion": "1.0", "id": "…", "source": "my-reporter", "time": "…",
+   "type": "org.open-autonomy.session.ended", "subject": "<session key>",
+   "data": { "outcome": "done", "report": "…", "commit_sha": "7d30729", "item_id": "add", "ended_at": "…" } }]
+```
+
+`seq` is the offset of the first turn in the session's own order: a retry or a reconnect that replays
+offsets already applied is ignored (`idempotent: true` in that event's result), so a reporter that restarts
+reads the session back and continues from its `next_seq`. The response is `{ ok, results: [{ id, ok,
+session | update, idempotent?, error? }] }`; the first failing event stops the batch.
+
+Public reads, no key:
+
+| Route | What |
+|---|---|
+| `GET /v1/accounts/:account/sessions?limit=` | the stream, newest first, and `live`: the keys live now |
+| `GET /v1/accounts/:account/sessions/:key` | one session with its transcript tail and `next_seq` |
+| `GET /v1/accounts/:account/sessions/:key/events` | Server-Sent Events: `turn` (id = offset), `status`; `Last-Event-ID` resumes |
+| `GET /v1/accounts/:account/items/:item` | every session, update and settled cent on the item |
+| `GET /v1/accounts/:account/items/:item/events` | Server-Sent Events: `item` on change, until nothing is live |
+| `POST /v1/agent/events` with type `org.open-autonomy.project.docs` `{ about_md?, shipped_md? }` | the project's documents, from whatever files the substrate keeps: what it is (the page leads with the first paragraph), what shipped |
+| `GET /v1/accounts/:account/events` | Server-Sent Events: `project` on change (the books, the live set, the roadmap revision); stays open |
+| `GET /v1/accounts/:account` | the books: balance, spend, runway |
+| `GET /v1/accounts/:account/calls?limit=&before=` | the audit trail, every metered spend, newest first |
+
+Keys, the adopter way: `GET /v1/keys/challenge?account=owner/repo` names a claim to commit to
+`.open-autonomy-claim` on the default branch; `POST /v1/keys/mint {account, models?}` mints once the file
+is at HEAD; `POST /v1/keys/rotate` with the current key mints a successor and leaves the old one a day of
+grace. A key is verified by its signature and expiry alone, so it survives every redeploy; the platform's
+registry can only revoke it or shorten it.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@open-autonomy/sdk",
+  "version": "2.1.0",
+  "description": "The Open Autonomy SDK: the roadmap model and its codec, the development-stream client (sessions, turns, updates), and the key helpers. Everything it does is a documented HTTP wire any language can speak without it.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-autonomy-org/open-autonomy.git",
+    "directory": "packages/sdk"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./roadmap": "./src/roadmap.ts",
+    "./client": "./src/client.ts",
+    "./drivers": "./src/drivers.ts",
+    "./rails": "./src/rails.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test test/*.test.ts",
+    "typecheck": "bunx tsc --noEmit",
+    "check": "bun test test/*.test.ts && bunx tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.10",
+    "typescript": "^5.9.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,235 @@
+// The development-stream client: how a project reports its own work to the platform, on its key. Every
+// method is one HTTP call whose raw form is documented in the README, so any language can do the same
+// without this package.
+//
+// Sessions are conversations: opened with a kind (`run` is a scheduled run, the funded work; `chat`
+// anything else) and, when known, the roadmap item they serve; turns append with an offset so a retry or
+// a reconnect is idempotent; a session ends with an optional outcome. Updates are short progress notes on
+// an item. All of it goes to POST /v1/agent/events as CloudEvents 1.0, one or a batch.
+
+import type { Roadmap } from './roadmap.ts';
+
+export interface ClientOptions {
+  baseUrl: string; // e.g. https://open-autonomy.org/v1 (the key valve's forwarded address inside a stack)
+  key: string;
+  fetch?: typeof fetch;
+}
+
+export type TurnRole = 'user' | 'assistant' | 'tool' | 'system';
+export interface Turn { ts?: string; role: TurnRole; text?: string; tool?: string; args?: string; result?: string }
+export type SessionOutcome = 'done' | 'failed';
+
+export interface SessionStart { key: string; kind?: string; title?: string; item?: string; source?: string; startedAt?: string }
+export interface SessionEnd { key: string; outcome?: SessionOutcome; report?: string; commit?: string; item?: string; endedAt?: string }
+export interface Update { item: string; text: string; session?: string; at?: string }
+// The board's state for a roadmap item, as the agent's harness keeps it: the task's lane, every attempt at
+// it, the handoff and the review verdicts. Published by the reporter from the harness's own board.
+export interface TaskAttempt { id: string; profile?: string; status: string; started_at?: string; ended_at?: string; outcome?: string; summary?: string }
+export interface TaskReview { verdict: 'requested' | 'approved' | 'changes_requested' | 'escalated'; by?: string; reason?: string; at?: string }
+export interface TaskState { item: string; task_id: string; lane: string; title?: string; assignee?: string; attempts: TaskAttempt[]; reviews: TaskReview[]; handoff?: { summary?: string; metadata?: unknown }; updated_at?: string }
+export const TASK_EVENT_TYPE = 'org.open-autonomy.item.task';
+// Who the agent is and how it runs, as its substrate publishes it: a persona (the identity text it runs
+// with), its model, its schedule, what it knows how to do, and how to run it. The platform shows this
+// beside the roadmap; it reads no harness's files for it.
+export interface AgentSetup { harness?: string; persona?: string; model?: string; provider?: string; schedule?: Array<{ name: string; schedule: string; description?: string }>; skills?: string[]; setup_md?: string }
+export const SETUP_EVENT_TYPE = 'org.open-autonomy.agent.setup';
+// The project's documents, from whatever files the substrate keeps: what the project is (`about_md`; the page
+// leads with its first paragraph) and what shipped (`shipped_md`). Each field replaces what was there.
+export interface ProjectDocs { about_md?: string; shipped_md?: string }
+export const DOCS_EVENT_TYPE = 'org.open-autonomy.project.docs';
+
+export interface CloudEvent {
+  specversion: '1.0';
+  id: string;
+  source: string;
+  type: string;
+  subject: string;
+  time: string;
+  datacontenttype: 'application/json';
+  data: Record<string, unknown>;
+}
+
+export const EVENT_TYPES = {
+  started: 'org.open-autonomy.session.started',
+  turns: 'org.open-autonomy.session.turns',
+  ended: 'org.open-autonomy.session.ended',
+  update: 'org.open-autonomy.item.update',
+} as const;
+
+export function sessionStartedEvent(s: SessionStart, source = 'open-autonomy-sdk'): CloudEvent {
+  return event(EVENT_TYPES.started, s.key, { session_kind: s.kind, title: s.title, item_id: s.item, source: s.source }, s.startedAt, source);
+}
+export function sessionTurnsEvent(key: string, seq: number, turns: Turn[], item?: string, source = 'open-autonomy-sdk'): CloudEvent {
+  return event(EVENT_TYPES.turns, key, { seq, turns, item_id: item }, undefined, source);
+}
+export function sessionEndedEvent(e: SessionEnd, source = 'open-autonomy-sdk'): CloudEvent {
+  return event(EVENT_TYPES.ended, e.key, { outcome: e.outcome, report: e.report, commit_sha: e.commit, item_id: e.item, ended_at: e.endedAt }, e.endedAt, source);
+}
+export function updateEvent(u: Update, source = 'open-autonomy-sdk'): CloudEvent {
+  return event(EVENT_TYPES.update, u.item, { text: u.text, session: u.session }, u.at, source);
+}
+
+function event(type: string, subject: string, data: Record<string, unknown>, time?: string, source = 'open-autonomy-sdk'): CloudEvent {
+  return { specversion: '1.0', id: crypto.randomUUID(), source, type, subject, time: time ?? new Date().toISOString(), datacontenttype: 'application/json', data: Object.fromEntries(Object.entries(data).filter(([, v]) => v !== undefined)) };
+}
+
+export interface EventResult { id?: string; ok: boolean; error?: string; idempotent?: boolean; session?: SessionSummary; update?: UpdateRecord }
+export interface SessionSummary {
+  key: string; account: string; kind: string; status: 'live' | 'ended'; outcome?: SessionOutcome; title?: string; item_id?: string; source?: string;
+  started_at: string; ended_at?: string; report?: string; commit_sha?: string; turn_count: number; next_seq: number; tool_calls: number; usd_cents: number; calls: number; updated_at: string;
+}
+export interface SessionRecord extends Omit<SessionSummary, 'tool_calls'> { turns: Array<Turn & { seq?: number }> }
+export interface UpdateRecord { id: string; account: string; item_id: string; ts: string; text: string; session?: string }
+export interface ItemView { ok: true; account: string; item_id: string; live: string[]; sessions: SessionSummary[]; updates: UpdateRecord[]; usd_cents: number }
+
+export class OpenAutonomy {
+  private readonly base: string;
+  private readonly fetchImpl: typeof fetch;
+  constructor(private readonly opts: ClientOptions) {
+    this.base = opts.baseUrl.replace(/\/$/, '');
+    this.fetchImpl = opts.fetch ?? fetch;
+  }
+
+  // POST /v1/agent/events  (Authorization: Bearer <key>; body: one CloudEvent or an array)
+  async send(events: CloudEvent | CloudEvent[]): Promise<{ ok: boolean; status: number; results: EventResult[] }> {
+    const res = await this.fetchImpl(`${this.base}/agent/events`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${this.opts.key}`, 'content-type': 'application/cloudevents-batch+json' },
+      body: JSON.stringify(Array.isArray(events) ? events : [events]),
+    });
+    const body = await res.json().catch(() => ({})) as { ok?: boolean; results?: EventResult[] };
+    return { ok: res.ok && body.ok === true, status: res.status, results: body.results ?? [] };
+  }
+
+  // A session, as a small object that remembers its offset. `resume` reads the platform's own offset first,
+  // so a reporter that restarts mid-session continues where the books are rather than replaying.
+  async open(start: SessionStart): Promise<Session> {
+    const r = await this.send(sessionStartedEvent(start));
+    if (!r.ok) throw new Error(`open ${start.key}: ${r.status} ${r.results[0]?.error ?? ''}`);
+    return new Session(this, start.key, r.results[0]?.session?.next_seq ?? 0);
+  }
+
+  async resume(key: string, account: string, fallback: SessionStart): Promise<Session> {
+    const existing = await this.session(account, key);
+    if (existing) return new Session(this, key, existing.next_seq);
+    return this.open(fallback);
+  }
+
+  async update(u: Update): Promise<UpdateRecord | undefined> {
+    const r = await this.send(updateEvent(u));
+    return r.results[0]?.update;
+  }
+
+  // A grant: credits from this funder's books to a project's, once per idempotency key, with a word.
+  async give(g: { to: string; usd_cents: number; note?: string; key?: string }): Promise<{ ok: boolean; error?: string; from?: string; to_balance_usd_cents?: number; from_balance_usd_cents?: number }> {
+    const res = await this.fetchImpl(`${this.base}/grants/give`, { method: 'POST', headers: { authorization: `Bearer ${this.opts.key}`, 'content-type': 'application/json' }, body: JSON.stringify(g) });
+    return await res.json() as { ok: boolean; error?: string };
+  }
+
+  // The agent's setup, replacing what was there.
+  async setup(s: AgentSetup): Promise<boolean> {
+    const r = await this.send(event(SETUP_EVENT_TYPE, 'agent', s as unknown as Record<string, unknown>));
+    return r.results[0]?.ok === true;
+  }
+
+  // The project's documents, replacing what was there.
+  async docs(d: ProjectDocs): Promise<boolean> {
+    const r = await this.send(event(DOCS_EVENT_TYPE, 'project', d as unknown as Record<string, unknown>));
+    return r.results[0]?.ok === true;
+  }
+
+  // The board's state for an item: the task's lane, attempts, handoff and reviews, replacing what was there.
+  async task(t: TaskState): Promise<boolean> {
+    const { item, ...data } = t;
+    const r = await this.send(event(TASK_EVENT_TYPE, item, data as unknown as Record<string, unknown>, data.updated_at));
+    return r.results[0]?.ok === true;
+  }
+
+  // Public reads (no key): the stream, one session with its transcript, one item with everything on it.
+  async sessions(account: string, limit = 30): Promise<{ live: string[]; sessions: SessionSummary[] }> {
+    const res = await this.fetchImpl(`${this.base}/accounts/${encodeURIComponent(account)}/sessions?limit=${limit}`);
+    return await res.json() as { live: string[]; sessions: SessionSummary[] };
+  }
+  async session(account: string, key: string): Promise<SessionRecord | undefined> {
+    const res = await this.fetchImpl(`${this.base}/accounts/${encodeURIComponent(account)}/sessions/${encodeURIComponent(key)}`);
+    if (!res.ok) return undefined;
+    return ((await res.json()) as { session?: SessionRecord }).session;
+  }
+  async item(account: string, itemId: string): Promise<ItemView> {
+    const res = await this.fetchImpl(`${this.base}/accounts/${encodeURIComponent(account)}/items/${encodeURIComponent(itemId)}`);
+    return await res.json() as ItemView;
+  }
+
+  // The roadmap as the platform holds it: the current normalized revision, and its history.
+  //   GET /v1/accounts/:account/roadmap            GET /v1/accounts/:account/roadmap/revisions?limit=
+  async roadmap(account: string): Promise<RoadmapRevision | undefined> {
+    const res = await this.fetchImpl(`${this.base}/accounts/${encodeURIComponent(account)}/roadmap`);
+    if (!res.ok) return undefined;
+    return ((await res.json()) as { revision?: RoadmapRevision }).revision;
+  }
+  async roadmapRevisions(account: string, limit = 20): Promise<RoadmapRevision[]> {
+    const res = await this.fetchImpl(`${this.base}/accounts/${encodeURIComponent(account)}/roadmap/revisions?limit=${limit}`);
+    return ((await res.json()) as { revisions?: RoadmapRevision[] }).revisions ?? [];
+  }
+  // An owner-side driver pushes the normalized roadmap it pulled from its tracker. Needs the `steer` scope,
+  // which a spending key does not carry.
+  //   POST /v1/agent/roadmap  (Authorization: Bearer <steer key>)  { source, roadmap, by? }
+  async pushRoadmap(roadmap: Roadmap, source: string, by?: string): Promise<{ ok: boolean; status: number; revision?: RoadmapRevision; unchanged?: boolean; error?: string }> {
+    const res = await this.fetchImpl(`${this.base}/agent/roadmap`, { method: 'POST', headers: { authorization: `Bearer ${this.opts.key}`, 'content-type': 'application/json' }, body: JSON.stringify({ source, roadmap, by }) });
+    const body = await res.json().catch(() => ({})) as { ok?: boolean; revision?: RoadmapRevision; unchanged?: boolean; error?: { code?: string } };
+    return { ok: res.ok && body.ok === true, status: res.status, revision: body.revision, unchanged: body.unchanged, error: body.error?.code };
+  }
+}
+
+export interface RoadmapRevision {
+  revision: number;
+  ts: string;
+  source: string;
+  by?: string;
+  roadmap: Roadmap;
+  changes: Array<{ id: string; kind: 'added' | 'removed' | 'status' | 'edited'; from?: string; to?: string }>;
+  conformance: string[];
+}
+
+export class Session {
+  constructor(private readonly client: OpenAutonomy, readonly key: string, public seq: number) {}
+  async turns(turns: Turn[], item?: string): Promise<void> {
+    if (!turns.length) return;
+    const r = await this.client.send(sessionTurnsEvent(this.key, this.seq, turns, item));
+    if (r.ok) this.seq += turns.length;
+  }
+  async end(end: Omit<SessionEnd, 'key'> = {}): Promise<void> {
+    await this.client.send(sessionEndedEvent({ ...end, key: this.key }));
+  }
+}
+
+// Key helpers: the adopter way, with no admin token anywhere. Prove control of the repository by
+// committing the claim the platform names, then mint; rotate with the current key.
+export interface KeyChallenge { ok: boolean; account: string; file: string; claim: string; valid_through: string }
+export interface MintedKey { ok: boolean; token: string; key: { kid: string; account: string; models: string[]; iat: string; exp: string }; previous?: { kid: string; exp: string } }
+
+export async function keyChallenge(baseUrl: string, account: string, fetchImpl: typeof fetch = fetch): Promise<KeyChallenge> {
+  const res = await fetchImpl(`${baseUrl.replace(/\/$/, '')}/keys/challenge?account=${encodeURIComponent(account)}`);
+  return await res.json() as KeyChallenge;
+}
+// `scopes` picks what the key may do (the platform's default is spend + narrate): a treasurer's key adds `pay`,
+// the rails; an owner-side driver's is `steer` alone.
+export async function keyMint(baseUrl: string, account: string, models?: string[], scopes?: string[], fetchImpl: typeof fetch = fetch): Promise<MintedKey> {
+  const res = await fetchImpl(`${baseUrl.replace(/\/$/, '')}/keys/mint`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ account, models, ...(scopes ? { scopes } : {}) }) });
+  return await res.json() as MintedKey;
+}
+// `graceSeconds` shortens how long the old key keeps working (the platform's default is a day; it never lengthens).
+// A funder: a person who holds grant credits on their own books (`@login`). Their key proves their GitHub
+// login through the claim file in a repository they own and can only give.
+export async function funderChallenge(baseUrl: string, login: string, fetchImpl: typeof fetch = fetch): Promise<KeyChallenge & { funder?: string }> {
+  const res = await fetchImpl(`${baseUrl.replace(/\/$/, '')}/keys/challenge?funder=${encodeURIComponent(login)}`);
+  return await res.json() as KeyChallenge & { funder?: string };
+}
+export async function funderMint(baseUrl: string, login: string, repo: string, fetchImpl: typeof fetch = fetch): Promise<MintedKey> {
+  const res = await fetchImpl(`${baseUrl.replace(/\/$/, '')}/keys/mint`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ funder: login, repo }) });
+  return await res.json() as MintedKey;
+}
+export async function keyRotate(baseUrl: string, currentKey: string, options: { graceSeconds?: number; fetchImpl?: typeof fetch } = {}): Promise<MintedKey> {
+  const res = await (options.fetchImpl ?? fetch)(`${baseUrl.replace(/\/$/, '')}/keys/rotate`, { method: 'POST', headers: { authorization: `Bearer ${currentKey}`, 'content-type': 'application/json' }, body: JSON.stringify(options.graceSeconds === undefined ? {} : { grace_seconds: options.graceSeconds }) });
+  return await res.json() as MintedKey;
+}

package/src/drivers.ts

@@ -0,0 +1,134 @@
+// Roadmap drivers: one normalized roadmap, several native homes. `file` is the default — ROADMAP.yml in
+// git, the platform pulls it on sync. `github-milestones` is platform-pulled too, credential-free (public
+// milestones). `jira` runs owner-side, where the credential is, and pushes through the SDK on a steer-scoped
+// key. Each driver declares its conformance: what its tracker cannot express, so a reader knows which fields
+// are the driver's own defaults rather than the project's word. The agent stays tracker-blind: it works and
+// narrates ROADMAP.yml, and a driver's `reconcile` plan carries a finished item back to the native side.
+import { ROADMAP_SCHEMA, type Roadmap, type RoadmapItem, type RoadmapStatus } from './roadmap.ts';
+
+export type RoadmapSource = 'file' | 'github-milestones' | 'jira';
+export const ROADMAP_SOURCES: readonly RoadmapSource[] = ['file', 'github-milestones', 'jira'];
+
+export interface RoadmapConfig {
+  source: RoadmapSource;
+  path: string;
+  github?: { repo?: string };
+  jira?: { base_url?: string; project?: string; jql?: string; done_transition?: string };
+}
+
+// `.open-autonomy/config.yaml`'s `roadmap:` block. The config's shape is small and fixed: a line reader.
+export function parseRoadmapConfig(yaml: string): RoadmapConfig {
+  const cfg: RoadmapConfig = { source: 'file', path: 'ROADMAP.yml' };
+  let block = '';
+  let sub = '';
+  for (const raw of yaml.split('\n')) {
+    const line = raw.replace(/\s+#.*$/, '').trimEnd();
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const top = /^([a-z_]+):\s*(.*)$/.exec(line);
+    if (top) { block = top[2] === '' ? top[1] : ''; sub = ''; continue; }
+    if (block !== 'roadmap') continue;
+    const l2 = /^  ([a-z_]+):\s*(.*)$/.exec(line);
+    if (l2) {
+      sub = l2[2] === '' ? l2[1] : '';
+      const v = l2[2].trim().replace(/^["']|["']$/g, '');
+      if (l2[1] === 'source' && (ROADMAP_SOURCES as readonly string[]).includes(v)) cfg.source = v as RoadmapSource;
+      if (l2[1] === 'path' && v) cfg.path = v;
+      continue;
+    }
+    const l3 = /^    ([a-z_]+):\s*(.+)$/.exec(line);
+    if (l3 && (sub === 'github' || sub === 'jira')) {
+      const v = l3[2].trim().replace(/^["']|["']$/g, '');
+      const target: Record<string, string> = (cfg[sub] ??= {});
+      target[l3[1]] = v;
+    }
+  }
+  return cfg;
+}
+
+export interface DriverConformance { source: RoadmapSource; cannot: string[] }
+
+export const CONFORMANCE: Record<RoadmapSource, string[]> = {
+  file: [],
+  'github-milestones': ['priority (a milestone has none; every item is medium)', 'proposed (a milestone is open or closed; open is planned)', 'acceptance lines are the description\'s bullet lines, or its paragraphs'],
+  jira: ['phase (an epic has none; the epic\'s rank order is the phase)', 'proposed and active map from the status category: to-do is planned, in-progress is active, done is done'],
+};
+
+// ---- GitHub milestones -----------------------------------------------------------------------------------
+export interface Milestone { number: number; title: string; description?: string | null; state: 'open' | 'closed'; due_on?: string | null; created_at?: string }
+
+export const slug = (s: string): string => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80) || 'item';
+
+// Milestones as the roadmap: due date order is the phase (undated last, by creation), a closed milestone is
+// done, an open one planned; the description's bullets (else its paragraphs) are the acceptance lines.
+const orderedMilestones = (milestones: Milestone[]): Milestone[] => [...milestones].sort((a, b) => (a.due_on ? Date.parse(a.due_on) : Infinity) - (b.due_on ? Date.parse(b.due_on) : Infinity) || (Date.parse(a.created_at ?? '') || 0) - (Date.parse(b.created_at ?? '') || 0) || a.number - b.number);
+export function fromMilestones(milestones: Milestone[]): Roadmap {
+  const ordered = orderedMilestones(milestones);
+  const seen = new Set<string>();
+  let phase = 0;
+  let lastDue: string | null | undefined;
+  const items: RoadmapItem[] = ordered.map((m) => {
+    if (m.due_on !== lastDue || phase === 0) { phase += 1; lastDue = m.due_on; }
+    let id = slug(m.title);
+    while (seen.has(id)) id = `${id}-${m.number}`;
+    seen.add(id);
+    return { id, title: m.title, status: m.state === 'closed' ? 'done' : 'planned', phase: String(phase), priority: 'medium', acceptance: acceptanceOf(m.description ?? '') };
+  });
+  return { schema: ROADMAP_SCHEMA, items };
+}
+function acceptanceOf(text: string): string[] {
+  const bullets = text.split('\n').map((l) => /^\s*[-*]\s+(.+?)\s*$/.exec(l)?.[1]).filter((l): l is string => !!l);
+  if (bullets.length) return bullets;
+  return text.trim() ? text.trim().split(/\n{2,}/).map((p) => p.replace(/\s+/g, ' ').trim()).filter(Boolean) : [];
+}
+// What the native side must change to match the roadmap: an item done in the roadmap closes its milestone.
+export function milestoneChanges(roadmap: Roadmap, milestones: Milestone[]): Array<{ number: number; title: string; state: 'open' | 'closed' }> {
+  const ordered = orderedMilestones(milestones);
+  const byId = new Map(fromMilestones(milestones).items.map((it, i) => [it.id, ordered[i]] as const));
+  const out: Array<{ number: number; title: string; state: 'open' | 'closed' }> = [];
+  for (const it of roadmap.items) {
+    const m = byId.get(it.id);
+    if (!m) continue;
+    const want: 'open' | 'closed' = it.status === 'done' ? 'closed' : 'open';
+    if (m.state !== want) out.push({ number: m.number, title: m.title, state: want });
+  }
+  return out;
+}
+
+// ---- Jira epics -------------------------------------------------------------------------------------------
+export interface JiraEpic { key: string; summary: string; description?: string | null; statusCategory: 'new' | 'indeterminate' | 'done' | (string & {}); rank?: number; priority?: string | null }
+
+// Epics as the roadmap: the epic key is the item id, rank order the phase, the status category the status.
+export function fromJira(epics: JiraEpic[]): Roadmap {
+  const ordered = [...epics].sort((a, b) => (a.rank ?? Number.MAX_SAFE_INTEGER) - (b.rank ?? Number.MAX_SAFE_INTEGER) || a.key.localeCompare(b.key));
+  const status = (c: string): RoadmapStatus => (c === 'done' ? 'done' : c === 'indeterminate' ? 'active' : 'planned');
+  return { schema: ROADMAP_SCHEMA, items: ordered.map((e, i) => ({ id: e.key, title: e.summary, status: status(e.statusCategory), phase: String(i + 1), priority: (e.priority ?? 'medium').toLowerCase(), acceptance: acceptanceOf(e.description ?? '') })) };
+}
+// An item done in the roadmap transitions its epic; one active starts it.
+export function jiraChanges(roadmap: Roadmap, epics: JiraEpic[]): Array<{ key: string; to: 'done' | 'active' }> {
+  const byKey = new Map(epics.map((e) => [e.key, e]));
+  const out: Array<{ key: string; to: 'done' | 'active' }> = [];
+  for (const it of roadmap.items) {
+    const e = byKey.get(it.id);
+    if (!e) continue;
+    if (it.status === 'done' && e.statusCategory !== 'done') out.push({ key: e.key, to: 'done' });
+    else if (it.status === 'active' && e.statusCategory === 'new') out.push({ key: e.key, to: 'active' });
+  }
+  return out;
+}
+
+// ---- the normalized roadmap's own diff ---------------------------------------------------------------------
+export interface RoadmapChange { id: string; kind: 'added' | 'removed' | 'status' | 'edited'; from?: string; to?: string }
+export function diffRoadmaps(before: Roadmap | undefined, after: Roadmap): RoadmapChange[] {
+  const prev = new Map((before?.items ?? []).map((i) => [i.id, i]));
+  const next = new Map(after.items.map((i) => [i.id, i]));
+  const out: RoadmapChange[] = [];
+  for (const [id, it] of next) {
+    const p = prev.get(id);
+    if (!p) { out.push({ id, kind: 'added', to: it.status }); continue; }
+    if (p.status !== it.status) out.push({ id, kind: 'status', from: p.status, to: it.status });
+    else if (p.title !== it.title || p.phase !== it.phase || p.priority !== it.priority || p.acceptance.join('\n') !== it.acceptance.join('\n')) out.push({ id, kind: 'edited' });
+  }
+  for (const id of prev.keys()) if (!next.has(id)) out.push({ id, kind: 'removed' });
+  return out;
+}
+export const sameRoadmap = (a: Roadmap | undefined, b: Roadmap): boolean => !!a && diffRoadmaps(a, b).length === 0 && a.schema === b.schema;

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './roadmap.ts';
+export * from './client.ts';
+export * from './drivers.ts';
+export * from './rails.ts';

package/src/rails.ts

@@ -0,0 +1,49 @@
+// The rails a project's agent may spend through, as its owner bounds them in `.open-autonomy/config.yaml`:
+//
+//   rails:
+//     card:                     # a single-use virtual card minted against the balance (Stripe Issuing)
+//       max_usd_cents: 2500     # the most one card may be minted for (0, the default: the rail is off)
+//       categories: [computer_software_stores, ...]   # Stripe merchant categories a card may pay at
+//     partner:                  # a partner service settling a metered charge against the balance
+//       max_usd_cents: 500      # the most one charge may be (0, the default: the rail is off)
+//       partners: [...]         # the partner ids allowed to settle
+//
+// The model rail needs no bounds beyond the balance and the key's models. Every rail leaves a record on the
+// audit trail naming itself.
+export interface RailsConfig {
+  card: { max_usd_cents: number; categories: string[] };
+  partner: { max_usd_cents: number; partners: string[] };
+}
+export const RAILS_OFF: RailsConfig = { card: { max_usd_cents: 0, categories: [] }, partner: { max_usd_cents: 0, partners: [] } };
+
+export function parseRailsConfig(yaml: string): RailsConfig {
+  const cfg: RailsConfig = { card: { max_usd_cents: 0, categories: [] }, partner: { max_usd_cents: 0, partners: [] } };
+  let block = '';
+  let rail: 'card' | 'partner' | '' = '';
+  let list: 'categories' | 'partners' | '' = '';
+  for (const raw of yaml.split('\n')) {
+    const line = raw.replace(/\s+#.*$/, '').trimEnd();
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const top = /^([a-z_]+):\s*(.*)$/.exec(line);
+    if (top) { block = top[2] === '' ? top[1] : ''; rail = ''; list = ''; continue; }
+    if (block !== 'rails') continue;
+    const l2 = /^  ([a-z_]+):\s*$/.exec(line);
+    if (l2) { rail = l2[1] === 'card' || l2[1] === 'partner' ? l2[1] : ''; list = ''; continue; }
+    if (!rail) continue;
+    const l3 = /^    ([a-z_]+):\s*(.*)$/.exec(line);
+    if (l3) {
+      const [, key, value] = l3;
+      list = '';
+      if (key === 'max_usd_cents') cfg[rail].max_usd_cents = Math.max(0, Math.floor(Number(value) || 0));
+      else if ((key === 'categories' && rail === 'card') || (key === 'partners' && rail === 'partner')) {
+        const inline = /^\[(.*)\]$/.exec(value.trim());
+        if (inline) (cfg[rail] as Record<string, unknown>)[key] = inline[1].split(',').map((s) => s.trim().replace(/^["']|["']$/g, '')).filter(Boolean);
+        else list = key;
+      }
+      continue;
+    }
+    const item = /^      -\s+(.+)$/.exec(line);
+    if (item && list) ((cfg[rail] as Record<string, unknown>)[list] as string[]).push(item[1].trim().replace(/^["']|["']$/g, ''));
+  }
+  return cfg;
+}

package/src/roadmap.ts

@@ -0,0 +1,141 @@
+// The roadmap model and its codec. ROADMAP.yml is the roadmap's home in git and the only place it is
+// written; this module reads it into a typed shape and writes it back byte for byte. The codec keeps
+// every source line, so parse → serialize is the identity and an edit rewrites only the line it touches.
+// Adapters (a tracker that mirrors the roadmap, a page that renders it) are what the shape is for.
+//
+// The file's shape, as every kit writes it:
+//
+//   # comments and blank lines, kept verbatim
+//   schema: open-autonomy.roadmap.v3
+//   items:
+//     - id: <id>
+//       phase: <n>          (optional)
+//       priority: <word>    (optional)
+//       status: proposed | planned | active | done
+//       title: <text>
+//       acceptance:
+//         - <line>
+
+export const ROADMAP_SCHEMA = 'open-autonomy.roadmap.v3';
+export type RoadmapStatus = 'proposed' | 'planned' | 'active' | 'done';
+export const ROADMAP_STATUSES: readonly RoadmapStatus[] = ['proposed', 'planned', 'active', 'done'];
+
+export interface RoadmapItem {
+  id: string;
+  title: string;
+  status: RoadmapStatus;
+  phase?: string;
+  priority?: string;
+  acceptance: string[];
+}
+
+export interface Roadmap {
+  schema: string;
+  items: RoadmapItem[];
+}
+
+// The parsed document: the model plus the source it came from, so it can be written back unchanged.
+export interface RoadmapDocument extends Roadmap {
+  lines: string[];
+  // For each item, the index of its `- id:` line and of each scalar field line it carries.
+  spans: Array<{ id: string; start: number; end: number; fields: Record<string, number> }>;
+}
+
+function unquote(s: string): string {
+  const t = s.trim();
+  const m = /^(['"])(.*)\1$/.exec(t);
+  return m ? m[2].replace(/\\"/g, '"').replace(/''/g, "'") : t;
+}
+
+function quoteIfNeeded(s: string): string {
+  return /^[\w][^:#]*$/.test(s) && !/\s$/.test(s) ? s : JSON.stringify(s);
+}
+
+export function parseRoadmap(text: string): RoadmapDocument {
+  const lines = text.split('\n');
+  const doc: RoadmapDocument = { schema: '', items: [], lines, spans: [] };
+  let cur: { item: RoadmapItem; span: RoadmapDocument['spans'][number]; inAcceptance: boolean } | null = null;
+  const close = (end: number) => { if (cur) { cur.span.end = end; doc.items.push(cur.item); doc.spans.push(cur.span); cur = null; } };
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const schema = /^schema:\s*(.+?)\s*$/.exec(line);
+    if (schema && !cur) { doc.schema = unquote(schema[1]); continue; }
+    const idm = /^(\s*)-\s+id:\s*(.+?)\s*$/.exec(line);
+    if (idm) {
+      close(i);
+      cur = { item: { id: unquote(idm[2]), title: '', status: 'planned', acceptance: [] }, span: { id: unquote(idm[2]), start: i, end: lines.length, fields: { id: i } }, inAcceptance: false };
+      continue;
+    }
+    if (!cur) continue;
+    const field = /^\s+(phase|priority|status|title):\s*(.*?)\s*$/.exec(line);
+    if (field) {
+      cur.inAcceptance = false;
+      const [, key, raw] = field;
+      const val = unquote(raw);
+      cur.span.fields[key] = i;
+      if (key === 'phase') cur.item.phase = val;
+      else if (key === 'priority') cur.item.priority = val;
+      else if (key === 'status') cur.item.status = (ROADMAP_STATUSES as readonly string[]).includes(val) ? val as RoadmapStatus : 'planned';
+      else cur.item.title = val;
+      continue;
+    }
+    if (/^\s+acceptance:\s*$/.test(line)) { cur.inAcceptance = true; cur.span.fields.acceptance = i; continue; }
+    const bullet = /^\s+-\s+(.+?)\s*$/.exec(line);
+    if (bullet && cur.inAcceptance) { cur.item.acceptance.push(unquote(bullet[1])); continue; }
+    if (/^\S/.test(line)) close(i); // a top-level key ends the items block
+  }
+  close(lines.length);
+  return doc;
+}
+
+// The source, unchanged: parse(text) → serialize is the identity.
+export function serializeRoadmap(doc: RoadmapDocument): string {
+  return doc.lines.join('\n');
+}
+
+// A new document with one item's status changed; only that line differs from the source.
+export function withStatus(doc: RoadmapDocument, itemId: string, status: RoadmapStatus): RoadmapDocument {
+  const span = doc.spans.find((s) => s.id === itemId);
+  if (!span) throw new Error(`roadmap: no item ${itemId}`);
+  const lines = [...doc.lines];
+  const at = span.fields.status;
+  if (at !== undefined) lines[at] = lines[at].replace(/^(\s+status:\s*).*$/, `$1${status}`);
+  else {
+    const indent = (lines[span.start].match(/^\s*/)?.[0].length ?? 0) + 2;
+    lines.splice(span.start + 1, 0, `${' '.repeat(indent)}status: ${status}`);
+  }
+  return parseRoadmap(lines.join('\n'));
+}
+
+// A fresh roadmap file from a model (what a kit writes at create time).
+export function renderRoadmap(roadmap: Roadmap, header = ''): string {
+  const out: string[] = [];
+  if (header) out.push(...header.trimEnd().split('\n').map((l) => (l.startsWith('#') || !l ? l : `# ${l}`)));
+  out.push(`schema: ${roadmap.schema || ROADMAP_SCHEMA}`, 'items:');
+  for (const it of roadmap.items) {
+    out.push(`  - id: ${it.id}`);
+    if (it.phase !== undefined) out.push(`    phase: ${it.phase}`);
+    if (it.priority !== undefined) out.push(`    priority: ${it.priority}`);
+    out.push(`    status: ${it.status}`, `    title: ${quoteIfNeeded(it.title)}`);
+    if (it.acceptance.length) { out.push('    acceptance:'); for (const a of it.acceptance) out.push(`      - ${quoteIfNeeded(a)}`); }
+  }
+  return `${out.join('\n')}\n`;
+}
+
+// Where an item stands, for a renderer: the status as written, anything unrecognized queued.
+export type RoadmapState = 'proposed' | 'queued' | 'active' | 'done';
+export function itemState(item: Pick<RoadmapItem, 'status'>): RoadmapState {
+  if (item.status === 'proposed' || item.status === 'active' || item.status === 'done') return item.status;
+  return 'queued';
+}
+
+export function phaseNumber(item: Pick<RoadmapItem, 'phase'>): number {
+  const n = parseInt(item.phase ?? '', 10);
+  return Number.isNaN(n) ? Number.MAX_SAFE_INTEGER : n;
+}
+
+// The item the agent works next: the first active, else the first planned, in phase order.
+export function nextItem(roadmap: Roadmap): RoadmapItem | undefined {
+  const ordered = [...roadmap.items].sort((a, b) => phaseNumber(a) - phaseNumber(b));
+  return ordered.find((i) => i.status === 'active') ?? ordered.find((i) => i.status === 'planned');
+}