create-open-autonomy 2.1.0

package/template/.open-autonomy/reporter.ts

@@ -0,0 +1,320 @@
+#!/usr/bin/env bun
+// The reporter: the project's development stream, published as it happens. An SDK-to-SDK bridge —
+// supercode's harness SDK in (it discovers the agent's Hermes sessions and follows each transcript), the
+// Open Autonomy SDK out (sessions, turns, updates on the project's page). It runs as the stack's keyless
+// third service: it authenticates through the key valve's forwarded narration route and never sees the
+// project's key. Nothing here drives the agent; it only reads.
+//
+//   OPEN_AUTONOMY_BASE_URL=http://valve:8787/v1 bun .open-autonomy/reporter.ts [--config .open-autonomy/config.yaml]
+//
+// Supercode's contract, as its SDK documents it: `subscribeSessionIndex` lists sessions and streams
+// index changes (`sessionIndexEvent`); `session(locator).follow()` yields a snapshot then appended
+// messages; `subscribeSessionActivity` reports presence and turn state. A Hermes home is named by the
+// path of its state.db in `homes.hermes`.
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { SupercodeHarnessClient, type NormalizedMessage, type SessionActivity, type SessionDescriptor, type SessionLocator } from '@volter-ai-dev/supercode-harness-sdk';
+import { ROADMAP_SCHEMA, type RoadmapItem } from './sdk/roadmap.ts';
+import { OpenAutonomy, type Session, type Turn } from './sdk/client.ts';
+
+const arg = (name: string): string | undefined => { const i = process.argv.indexOf(name); return i >= 0 ? process.argv[i + 1] : undefined; };
+const configPath = resolve(arg('--config') ?? resolve(import.meta.dir, 'config.yaml'));
+const cfg = readConfig(configPath);
+const baseUrl = process.env.OPEN_AUTONOMY_BASE_URL ?? `${cfg.platform}/v1`;
+const oa = new OpenAutonomy({ baseUrl, key: process.env.OPEN_AUTONOMY_KEY ?? 'valve' });
+const stateFile = resolve(cfg.state_file);
+const IDLE_END_MS = Number(process.env.OPEN_AUTONOMY_IDLE_END_MS ?? 5 * 60_000);
+const TURN_END_MS = Number(process.env.OPEN_AUTONOMY_TURN_END_MS ?? 15_000);
+const log = (m: string) => console.log(`reporter: ${m}`);
+// The valve holds the key; its health line says when the key expires. Logged once at start so a reader of
+// either log sees the expiry.
+fetch(`${baseUrl.replace(/\/v1\/?$/, '')}/healthz`).then(async (r) => log(`valve: ${(await r.text()).trim()}`)).catch((e: Error) => log(`valve unreachable at start: ${e.message}`));
+
+interface Config { account: string; platform: string; publish: { runs: boolean; chats: boolean; private: string[] }; hermes_home: string; state_file: string }
+// The config's shape is small and fixed, so a line reader suffices: top-level `key: value` and the
+// `publish:` block's own keys and list.
+function readConfig(path: string): Config {
+  const text = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const top: Record<string, string> = {};
+  const publish: Record<string, string> = {};
+  const priv: string[] = [];
+  let block = '';
+  for (const raw of text.split('\n')) {
+    const line = raw.replace(/\s+#.*$/, '').trimEnd();
+    if (!line.trim() || line.trim().startsWith('#')) continue;
+    const topKey = /^([a-z_]+):\s*(.*)$/.exec(line);
+    if (topKey) { block = topKey[2] === '' ? topKey[1] : ''; if (topKey[2]) top[topKey[1]] = topKey[2].trim(); continue; }
+    if (block === 'publish') {
+      const kv = /^\s+([a-z_]+):\s*(.*)$/.exec(line);
+      if (kv) { if (kv[2]) publish[kv[1]] = kv[2].trim(); else if (kv[1] === 'private') publish.private = ''; continue; }
+      const item = /^\s+-\s+(.+)$/.exec(line);
+      if (item && item[1] !== '[]') priv.push(item[1].trim());
+    }
+  }
+  return {
+    account: top.account ?? '', platform: (top.platform ?? 'https://open-autonomy.org').replace(/\/$/, ''),
+    publish: { runs: (publish.runs ?? 'true') !== 'false', chats: (publish.chats ?? 'false') === 'true', private: priv },
+    hermes_home: top.hermes_home ?? process.env.HERMES_HOME ?? '/opt/data',
+    state_file: top.state_file ?? resolve(import.meta.dir, 'reporter-state.json'),
+  };
+}
+
+// What has been published: ended sessions are never reopened; open ones resume at the platform's offset.
+interface State { ended: Record<string, string> }
+const state: State = existsSync(stateFile) ? JSON.parse(readFileSync(stateFile, 'utf8')) as State : { ended: {} };
+const saveState = () => { try { writeFileSync(stateFile, `${JSON.stringify(state, null, 2)}\n`); } catch (e) { log(`cannot write ${stateFile}: ${(e as Error).message}`); } };
+
+// A run: the schedule fired it, or the board's dispatcher spawned it for a task (a worker or a reviewer).
+const kindOf = (d: SessionDescriptor): 'run' | 'chat' => (d.trigger === 'cron' || d.trigger === 'heartbeat' || d.trigger === 'task' ? 'run' : 'chat');
+// A run's source is its job's name. supercode's job model carries the job's id, not its name; Hermes keeps
+// the name beside the id in its own schedule store in the home the reporter reads, so that is where the
+// name comes from (read-only, refreshed whenever an id is new), falling back to the id.
+const jobNames = new Map<string, string>();
+function jobName(id: string): string {
+  if (!jobNames.has(id)) {
+    try {
+      const store = JSON.parse(readFileSync(resolve(cfg.hermes_home, 'cron', 'jobs.json'), 'utf8')) as { jobs?: Array<{ id?: string; name?: string }> } | Array<{ id?: string; name?: string }>;
+      for (const j of Array.isArray(store) ? store : store.jobs ?? []) if (j.id && j.name) jobNames.set(j.id, j.name);
+    } catch { /* no schedule store yet */ }
+  }
+  return jobNames.get(id) ?? id;
+}
+const sourceOf = (d: SessionDescriptor): string => (d.recurrence?.job_id ? jobName(d.recurrence.job_id) : d.trigger === 'task' ? 'board' : d.surface?.platform ?? kindOf(d));
+function publishes(d: SessionDescriptor): boolean {
+  const id = d.locator.session_id;
+  if (cfg.publish.private.includes(id) || (d.recurrence?.job_id && cfg.publish.private.includes(d.recurrence.job_id))) return false;
+  return kindOf(d) === 'run' ? cfg.publish.runs : cfg.publish.chats;
+}
+
+// A transcript message as the platform's turns: a tool call is one turn, its result another.
+function turnsOf(m: NormalizedMessage): Turn[] {
+  const text = typeof m.content === 'string' ? m.content : Array.isArray(m.content) ? m.content.map((p) => (typeof p === 'string' ? p : (p as { text?: string })?.text ?? '')).join('') : '';
+  const ts = m.metadata?.timestamp ?? m.metadata?.ts;
+  if (m.role === 'tool') return [{ ts, role: 'tool', tool: m.name ?? 'tool', result: text.slice(0, 600) }];
+  if (m.role === 'assistant') {
+    const out: Turn[] = [];
+    if (text.trim()) out.push({ ts, role: 'assistant', text: text.slice(0, 2000) });
+    for (const c of m.tool_calls ?? []) out.push({ ts, role: 'assistant', tool: c.function.name, args: c.function.arguments.slice(0, 600) });
+    return out;
+  }
+  if (m.role === 'user') return [{ ts, role: 'user', text: text.slice(0, 2000) }];
+  return [];
+}
+// The task a session serves is the board's task id: the dispatcher's own prompt names it (`work kanban task <id>`), and
+// so does the agent branch (agent/<task id>) in what the session says, runs, or reads back.
+const itemIn = (turns: Turn[]): string | undefined => turns.map((t) => (t.role === 'user' ? /\bkanban task (\S+)/.exec(t.text ?? '')?.[1] : undefined) ?? /\bagent\/([A-Za-z0-9][A-Za-z0-9._-]*)/.exec(`${t.args ?? ''} ${t.text ?? ''} ${t.result ?? ''}`)?.[1]).find(Boolean);
+const shaIn = (turns: Turn[]): string | undefined => turns.map((t) => /PUSHED_BRANCH=agent\/[A-Za-z0-9._-]+ ([0-9a-f]{7,40})/.exec(t.result ?? '')?.[1]).find(Boolean);
+
+// supercode synthesizes this result for a tool call whose answer is not recorded yet; a live follow sees it
+// before the real result lands in its place. Such a turn is held back until it resolves.
+const PLACEHOLDER = '[no tool result recorded — turn interrupted]';
+const contentOf = (m: NormalizedMessage): string => (typeof m.content === 'string' ? m.content : Array.isArray(m.content) ? m.content.map((p) => (typeof p === 'string' ? p : (p as { text?: string })?.text ?? '')).join('') : '');
+const isPlaceholder = (m: NormalizedMessage): boolean => m.role === 'tool' && contentOf(m) === PLACEHOLDER;
+
+class Followed {
+  session?: Session;
+  seq = 0;
+  // How many of the transcript's messages have been published (the platform counts turns; a message may
+  // be several).
+  sentMessages = 0;
+  item?: string;
+  sha?: string;
+  lastAt = Date.now();
+  ended = false;
+  private timer?: ReturnType<typeof setTimeout>;
+  private syncing = false;
+  private dirty = false;
+  constructor(readonly d: SessionDescriptor) {}
+  get key(): string { return this.d.locator.session_id; }
+  async open(): Promise<void> {
+    const start = { key: this.key, kind: kindOf(this.d), source: sourceOf(this.d), title: this.d.title ?? undefined, startedAt: this.d.updated_at_ms ? new Date(this.d.updated_at_ms).toISOString() : undefined };
+    this.session = await oa.resume(this.key, cfg.account, start);
+    this.seq = this.session.seq;
+    // Resuming at the platform's turn offset: the message index it corresponds to.
+    if (this.seq > 0) {
+      const { session } = await sc.loadWindow(this.d.locator, { message_limit: 5000 });
+      let counted = 0;
+      for (const m of session.messages) { if (counted >= this.seq) break; counted += turnsOf(m).length; this.sentMessages += 1; }
+    }
+    log(`${this.key}: ${kindOf(this.d)} (${sourceOf(this.d)}) open at turn ${this.seq}`);
+  }
+  // Publish what the transcript holds beyond what was sent, read through supercode's window: everything up
+  // to the first unresolved tool result, all of it once the session is ending.
+  async sync(final = false): Promise<void> {
+    if (this.syncing) { this.dirty = true; return; }
+    this.syncing = true;
+    try {
+      do {
+        this.dirty = false;
+        const { session } = await sc.loadWindow(this.d.locator, { message_offset: this.sentMessages, message_limit: 500 });
+        const msgs = session.messages;
+        let n = final ? msgs.length : msgs.findIndex(isPlaceholder);
+        if (n < 0) n = msgs.length;
+        const ready = msgs.slice(0, n);
+        const turns = ready.flatMap(turnsOf);
+        if (turns.length) {
+          this.item ??= itemIn(turns);
+          this.sha ??= shaIn(turns);
+          await this.session!.turns(turns, this.item);
+          this.seq = this.session!.seq;
+          this.sentMessages += n;
+          this.lastAt = Date.now();
+        }
+        // The shape of a turn's end: the last message is the assistant's own text with no tool call pending.
+        // The timer is (re)armed only when the transcript moved; a quiet re-read leaves it running.
+        const last = msgs[msgs.length - 1];
+        if (!this.ended && (turns.length || !this.timer)) this.arm(n === msgs.length && last?.role === 'assistant' && !(last.tool_calls?.length));
+      } while (this.dirty);
+    } catch (e) { log(`${this.key}: sync failed (${(e as Error).message})`); }
+    finally { this.syncing = false; }
+  }
+  // A session ends when its transcript has ended: a closing assistant text followed by fifteen seconds of silence
+  // (a tool call in flight is never silence, its result is still to come), else the idle fallback.
+  arm(turnEnded = false): void {
+    clearTimeout(this.timer);
+    this.timer = setTimeout(() => void this.end(turnEnded ? 'turn ended' : 'idle'), turnEnded ? TURN_END_MS : IDLE_END_MS);
+  }
+  async end(why: string): Promise<void> {
+    if (this.ended) return;
+    this.ended = true;
+    clearTimeout(this.timer);
+    await this.sync(true);
+    let outcome: 'done' | 'failed' | undefined;
+    let report: string | undefined;
+    try {
+      const { summary } = await sc.loadWindow(this.d.locator, { message_tail: 20 });
+      report = summary.last_assistant_text?.slice(0, 4000) || undefined;
+      if (kindOf(this.d) === 'run') outcome = summary.end_of_turn && !!report ? 'done' : 'failed';
+    } catch (e) { log(`${this.key}: summary unavailable (${(e as Error).message})`); if (kindOf(this.d) === 'run') outcome = 'failed'; }
+    await this.session?.end({ outcome, report, commit: this.sha, item: this.item, endedAt: new Date().toISOString() });
+    state.ended[this.key] = new Date().toISOString();
+    saveState();
+    log(`${this.key}: ended (${why}${outcome ? `, ${outcome}` : ''})`);
+  }
+}
+
+// supercode is the reporter's own dependency (its npm package carries the binary), so it is found beside
+// this file before anywhere on PATH; SUPERCODE_BIN names another build outright.
+const supercode = [process.env.SUPERCODE_BIN, resolve(import.meta.dir, 'node_modules', '.bin', 'supercode')].filter((p): p is string => !!p).find(existsSync) ?? Bun.which('supercode') ?? 'supercode';
+const sc = new SupercodeHarnessClient({ command: supercode, env: { ...process.env, HERMES_HOME: cfg.hermes_home } as Record<string, string> });
+const homes = { hermes: resolve(cfg.hermes_home, 'state.db') };
+const followed = new Map<string, Followed>();
+const activitySubs = new Map<string, string>();
+
+async function consider(d: SessionDescriptor): Promise<void> {
+  const key = d.locator.session_id;
+  if (d.locator.harness !== 'hermes' || followed.has(key) || state.ended[key]) return;
+  if (!publishes(d)) { log(`${key}: ${kindOf(d)} (${sourceOf(d)}) is private; not published`); state.ended[key] = 'private'; saveState(); return; }
+  const f = new Followed(d);
+  followed.set(key, f);
+  try {
+    await f.open();
+    f.arm();
+    const act = await sc.subscribeSessionActivity([d.locator], homes);
+    activitySubs.set(act.subscription, key);
+    for (const a of act.initial) activity(key, a);
+    void follow(f);
+  } catch (e) { log(`${key}: cannot open (${(e as Error).message})`); followed.delete(key); }
+}
+
+// The follow stream is the trigger: every event means the transcript moved, and the window read is the
+// truth of what it now holds. A slow tick covers a tool result landing in place without an event.
+async function follow(f: Followed): Promise<void> {
+  const tick = setInterval(() => { if (!f.ended) void f.sync(); }, 5000);
+  try {
+    await f.sync();
+    for await (const ev of sc.session(f.d.locator).follow({ view: { tailMessages: 50, maxMessageChars: 200, includeSubagents: false } })) {
+      if (f.ended) break;
+      // `runtime_state` describes a supercode-managed runtime; a Hermes session never has one, so `persisted`
+      // says nothing about whether the run is over. Only a shutdown of one is an end.
+      if (ev.type === 'runtime_state' && ev.state === 'shutting_down' && f.seq > 0) await f.end(`runtime ${ev.state}`);
+      else if (ev.type === 'session_snapshot' || ev.type === 'messages_appended') await f.sync();
+    }
+  } catch (e) { log(`${f.key}: follow ended (${(e as Error).message})`); }
+  finally { clearInterval(tick); }
+}
+
+let seenWorking = new Set<string>();
+function activity(key: string, a: SessionActivity): void {
+  const f = followed.get(key);
+  if (!f || f.ended) return;
+  if (a.turn === 'working' || a.presence === 'running') seenWorking.add(key);
+  else if (a.presence === 'persisted' && a.turn === 'idle' && seenWorking.has(key) && f.seq > 0) void f.end('idle after working');
+}
+
+sc.on('sessionIndexEvent', (ev) => { if ('changes' in ev) for (const c of ev.changes) if (c.kind !== 'removed') void consider(c.descriptor); });
+sc.on('sessionActivityEvent', (ev) => { const key = activitySubs.get(ev.subscription); if (key) for (const a of ev.activities) activity(key, a); });
+sc.on('exit', (code) => { log(`supercode harness serve exited (${code}); stopping`); process.exit(1); });
+
+await sc.start();
+// The board, through supercode's workflow layer, is the project's roadmap and its work record, both published
+// through the SDK. Every task is a roadmap item — its id, its title, its lane as the item's status, the `- `
+// lines of its body as the acceptance — and each task's board state (lane, attempts, handoff, review verdicts)
+// is published under that item whenever it changes. A task the board marks done after a review it requested
+// was approved by that review.
+type BoardTask = { id: string; title?: string; body?: string; assignee?: string; lane: string; priority?: number; created_at?: string; completed_at?: string; attempts?: Array<{ id: string; profile?: string; status: string; started_at?: string; ended_at?: string; outcome?: string; handoff?: { summary?: string; branch?: string; commit?: string } }>; reviews?: Array<{ verdict: string; by?: string; reason?: string; at?: string }> };
+// The lanes as the roadmap's four words: done; running or review is active; blocked or parked (scheduled) waits on a
+// decision, so proposed; the rest is planned.
+const statusOf = (lane: string): RoadmapItem['status'] => (lane === 'done' ? 'done' : lane === 'running' || lane === 'review' ? 'active' : lane === 'blocked' || lane === 'scheduled' ? 'proposed' : 'planned');
+const boardDigests = new Map<string, string>();
+let roadmapDigest = '';
+async function board(): Promise<void> {
+  let read: { workflow?: { boards?: Record<string, { tasks?: Record<string, BoardTask> }> } };
+  try { read = await sc.workflowLoad({ from: 'hermes', home: cfg.hermes_home }) as typeof read; } catch (e) { log(`board unreadable: ${(e as Error).message}`); return; }
+  // The developer's tasks are the roadmap. Tasks assigned to another profile (a purchase request for the treasurer)
+  // are the board's own bookkeeping: their spend shows on the trail under the developer's task, not as items.
+  const tasks = Object.values(read.workflow?.boards ?? {}).flatMap((b) => Object.values(b.tasks ?? {})).filter((t) => t.lane !== 'archived' && (t.assignee ?? 'default') === 'default').sort((a, b) => (a.created_at ?? '').localeCompare(b.created_at ?? '') || a.id.localeCompare(b.id));
+  // A read that found no board at all (the database mid-write) is not an empty board.
+  if (!tasks.length) return;
+  const items: RoadmapItem[] = tasks.map((t) => ({ id: t.id, title: t.title ?? t.id, status: statusOf(t.lane), acceptance: (t.body ?? '').split('\n').filter((l) => /^- /.test(l)).map((l) => l.slice(2).trim()) }));
+  const digest = JSON.stringify(items);
+  if (digest !== roadmapDigest) {
+    try { const r = await oa.pushRoadmap({ schema: ROADMAP_SCHEMA, items }, 'kanban', 'reporter'); if (r.ok) { roadmapDigest = digest; if (!r.unchanged) log(`roadmap published from the board (${items.length} task(s))`); } else log(`roadmap publish refused: ${r.error ?? r.status}`); } catch (e) { log(`roadmap publish failed: ${(e as Error).message}`); }
+  }
+  for (const t of tasks) {
+    const item = t.id;
+    const attempts = (t.attempts ?? []).map((a) => ({ id: a.id, profile: a.profile, status: a.status, started_at: a.started_at, ended_at: a.ended_at, outcome: a.outcome, summary: a.handoff?.summary }));
+    const reviews = (t.reviews ?? []).map((r) => ({ verdict: r.verdict as 'requested', by: r.by, reason: r.reason, at: r.at }));
+    const requested = [...reviews].reverse().find((r) => r.verdict === 'requested');
+    if (t.lane === 'done' && requested && !reviews.some((r) => r.verdict === 'changes_requested' && (r.at ?? '') > (requested.at ?? ''))) reviews.push({ verdict: 'approved' as 'requested', by: attempts[attempts.length - 1]?.profile, at: t.completed_at ?? attempts[attempts.length - 1]?.ended_at });
+    const last = [...(t.attempts ?? [])].reverse().find((a) => a.handoff);
+    const state = { item, task_id: t.id, lane: t.lane, title: t.title, assignee: t.assignee, attempts, reviews, handoff: last?.handoff, updated_at: new Date().toISOString() };
+    const taskDigest = JSON.stringify([state.lane, attempts.map((a) => [a.id, a.status, a.ended_at]), reviews.length, last?.handoff?.summary]);
+    if (boardDigests.get(t.id) === taskDigest) continue;
+    try { if (await oa.task(state)) { boardDigests.set(t.id, taskDigest); log(`board: ${t.id} (${t.lane}, ${attempts.length} attempt(s), ${reviews.length} review(s))`); } } catch (e) { log(`board publish failed for ${t.id}: ${(e as Error).message}`); }
+  }
+}
+// The agent's setup, from the home it runs with — the identity text, the model, the schedule seed, the
+// skills — published whenever they change. The platform reads no harness file.
+const readText = (p: string): string | undefined => { try { return readFileSync(p, 'utf8'); } catch { return undefined; } };
+// The project's documents, from the checkout: CONSTITUTION.md is what the project is (the page leads with its first
+// paragraph), CHANGELOG.md is what shipped. Published when they change. The platform reads no file for either.
+const projectDir = resolve(stateFile, '..', '..');
+let docsDigest = '';
+async function docs(): Promise<void> {
+  const d = { about_md: readText(resolve(projectDir, 'CONSTITUTION.md')), shipped_md: readText(resolve(projectDir, 'CHANGELOG.md')) };
+  const digest = JSON.stringify(d);
+  if (digest === docsDigest || (!d.about_md && !d.shipped_md)) return;
+  try { if (await oa.docs(d)) { docsDigest = digest; log(`documents published (${[d.about_md && 'about', d.shipped_md && 'shipped'].filter(Boolean).join(', ')})`); } } catch (e) { log(`documents publish failed: ${(e as Error).message}`); }
+}
+let setupDigest = '';
+async function setup(): Promise<void> {
+  const home = cfg.hermes_home;
+  const config = readText(resolve(home, 'config.yaml')) ?? '';
+  const model = /^\s+default:\s*(\S+)/m.exec(config)?.[1];
+  const provider = /^\s+provider:\s*(\S+)/m.exec(config)?.[1];
+  let schedule: Array<{ name: string; schedule: string; description?: string }> = [];
+  try { const seed = JSON.parse(readText(resolve(home, 'cron', 'jobs.seed.json')) ?? '{}') as { jobs?: Array<{ name?: string; schedule?: string; prompt?: string; script?: string }> }; schedule = (seed.jobs ?? []).filter((j) => j.name && j.schedule).map((j) => ({ name: j.name!, schedule: j.schedule!, description: j.prompt ?? (j.script ? `runs ${j.script}` : undefined) })); } catch { /* no seed */ }
+  const skills: string[] = [];
+  try { for (const cat of readdirSync(resolve(home, 'skills'))) { try { for (const name of readdirSync(resolve(home, 'skills', cat))) if (existsSync(resolve(home, 'skills', cat, name, 'SKILL.md'))) skills.push(name); } catch { /* a file */ } } } catch { /* no skills */ }
+  const s = { harness: 'hermes', persona: readText(resolve(home, 'SOUL.md')), model, provider, schedule, skills: skills.sort(), setup_md: readText(resolve(home, 'README.md')) };
+  const digest = JSON.stringify(s);
+  if (digest === setupDigest) return;
+  try { if (await oa.setup(s)) { setupDigest = digest; log(`setup published (${model ?? 'no model'}, ${schedule.length} job(s), ${skills.length} skill(s))`); } } catch (e) { log(`setup publish failed: ${(e as Error).message}`); }
+}
+const index = await sc.subscribeSessionIndex({ harnesses: ['hermes'], homes });
+await setup(); await docs(); await board();
+setInterval(() => { void setup(); void docs(); void board(); }, 10_000);
+log(`watching ${cfg.hermes_home} for ${cfg.account} → ${baseUrl} (${index.initial.length} session(s) on the index)`);
+for (const d of index.initial) await consider(d);
+process.on('SIGTERM', () => { void sc.close().then(() => process.exit(0)); });

package/template/.open-autonomy/setup.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env bun
+// The host, set up by one command, idempotently: what container/README.md asks of the owner before
+// `docker compose up`, done or found done, and what it cannot do said plainly. Safe to run again.
+//
+//   bun .open-autonomy/setup.ts [--context <docker context>] [--secrets <dir>] [--origin <url>]
+//                               [--origin-in-container <url>] [--env KEY=VALUE ...] [--uid N --gid N] [--fresh]
+//
+//   1. the key files <secrets>/agent.env (the developer's: spend + narrate) and <secrets>/treasurer.env (the
+//                    treasurer's: spend + narrate + pay), default ~/.config/open-autonomy, from mint-key.ts — found or named
+//   2. the image     hermes-agent:<tag> from container/hermes.pin — present, copied from another Docker host
+//                    that has it, or built (container/build-hermes.sh, ~10 minutes)
+//   3. the volumes   oa-home from hermes/ (its .env: the valve's address, the dummy key, every --env), oa-repo
+//                    a clone of --origin (default: this repository's origin, cloned with your own git and
+//                    keys); --fresh recreates both
+//   4. what is yours the deploy key and the ssh-agent that forwards it, the Discord token; then compose up
+//
+// The world's stack step calls this same file, so what an adopter runs and what the world proves never drift.
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+const here = resolve(import.meta.dir, '..');
+const argv = process.argv.slice(2);
+const arg = (name: string): string | undefined => { const i = argv.indexOf(name); return i >= 0 ? argv[i + 1] : undefined; };
+const args = (name: string): string[] => argv.flatMap((a, i) => (a === name && argv[i + 1] ? [argv[i + 1]] : []));
+const context = arg('--context') ?? process.env.DOCKER_CONTEXT;
+const secrets = resolve(arg('--secrets') ?? join(homedir(), '.config', 'open-autonomy'));
+const uid = arg('--uid') ?? String(process.getuid?.() ?? 501);
+const gid = arg('--gid') ?? String(process.getgid?.() ?? 20);
+const fresh = argv.includes('--fresh');
+const docker = ['docker', ...(context ? ['--context', context] : [])];
+const say = (m: string) => console.log(`setup: ${m}`);
+const run = (cmd: string[], opts: { quiet?: boolean; check?: boolean; env?: Record<string, string>; cwd?: string } = {}) => {
+  const r = Bun.spawnSync({ cmd, cwd: opts.cwd ?? here, stdout: 'pipe', stderr: opts.quiet ? 'pipe' : 'inherit', env: { ...process.env, ...opts.env } });
+  if (opts.check !== false && r.exitCode !== 0) throw new Error(`${cmd.slice(0, 3).join(' ')} … failed (${r.exitCode})${opts.quiet ? `\n${r.stderr.toString().slice(-600)}` : ''}`);
+  return { code: r.exitCode, out: r.stdout.toString() };
+};
+const todo: string[] = [];
+
+// 1. The key file.
+const keyFile = join(secrets, 'agent.env');
+const token = existsSync(keyFile) ? /^OPEN_AUTONOMY_KEY=(.+)$/m.exec(readFileSync(keyFile, 'utf8'))?.[1] : undefined;
+if (token) {
+  try { const c = JSON.parse(Buffer.from(token.split('.')[0], 'base64url').toString('utf8')) as { kid?: string; exp?: string }; say(`key: ${c.kid} in ${keyFile}, expires ${c.exp}`); } catch { say(`key: present in ${keyFile}`); }
+} else {
+  say(`no key in ${keyFile}`);
+  todo.push(`mint the developer's key: bun .open-autonomy/mint-key.ts${secrets === join(homedir(), '.config', 'open-autonomy') ? '' : ` --out ${keyFile}`}`);
+}
+const payFile = join(secrets, 'treasurer.env');
+if (existsSync(payFile) && /^OPEN_AUTONOMY_KEY=/m.test(readFileSync(payFile, 'utf8'))) say(`treasurer's key: in ${payFile}`);
+else { say(`no treasurer's key in ${payFile}`); todo.push(`mint the treasurer's key (the only one that pays): bun .open-autonomy/mint-key.ts --scopes spend,narrate,pay --out ${payFile}`); }
+
+// 2. The image.
+const pin = Object.fromEntries(readFileSync(join(here, 'container', 'hermes.pin'), 'utf8').split('\n').map((l) => l.trim().split('=') as [string, string]).filter(([k]) => k && !k.startsWith('#')));
+const image = `hermes-agent:${pin.HERMES_TAG}`;
+if (run([...docker, 'image', 'inspect', image], { quiet: true, check: false }).code === 0) say(`image: ${image} present`);
+else {
+  const other = run(['docker', 'context', 'ls', '-q'], { quiet: true }).out.split('\n').map((c) => c.trim()).filter((c) => c && c !== context)
+    .find((c) => run(['docker', '--context', c, 'image', 'inspect', image], { quiet: true, check: false }).code === 0);
+  if (other) { say(`image: copying ${image} from Docker host ${other}`); run(['sh', '-c', `docker --context '${other}' save '${image}' | ${docker.join(' ')} load`]); }
+  else { say(`image: building ${image} (container/build-hermes.sh, ~10 minutes)`); run(['sh', join(here, 'container', 'build-hermes.sh')], { env: context ? { DOCKER_CONTEXT: context } : {} }); }
+}
+
+// 3. The volumes.
+const have = (v: string) => run([...docker, 'volume', 'inspect', v], { quiet: true, check: false }).code === 0;
+if (fresh) for (const v of ['oa-home', 'oa-repo']) run([...docker, 'volume', 'rm', '-f', v], { quiet: true, check: false });
+if (have('oa-home') && have('oa-repo')) say('volumes: oa-home and oa-repo present (compose re-syncs the home from hermes/ on every start; --fresh recreates both)');
+else {
+  const origin = arg('--origin') ?? run(['git', 'remote', 'get-url', 'origin'], { quiet: true }).out.trim();
+  const originInside = arg('--origin-in-container') ?? origin;
+  for (const v of ['oa-home', 'oa-repo']) if (!have(v)) run([...docker, 'volume', 'create', v], { quiet: true });
+  const env = [`OPEN_AUTONOMY_BASE_URL=http://valve:8787/v1`, `OPEN_AUTONOMY_KEY=valve`, ...args('--env')];
+  run([...docker, 'run', '--rm', '-v', 'oa-home:/opt/data', '-v', `${join(here, 'hermes')}:/src:ro`, 'alpine:3', 'sh', '-c',
+    `cp -a /src/. /opt/data/ && printf '%s\\n' ${env.map((e) => `'${e.replace(/'/g, "'\\''")}'`).join(' ')} > /opt/data/.env && chown -R ${uid}:${gid} /opt/data`], { quiet: true });
+  say(`home: oa-home seeded from hermes/ (.env: the valve's address, the dummy key${args('--env').length ? `, ${args('--env').map((e) => e.split('=')[0]).join(', ')}` : ''})`);
+  // The clone is made on the host with your own git (and so your own keys), then carried into the volume through a
+  // directory under your home: a Docker host mounts the home directory, not the system's temporary one.
+  mkdirSync(join(homedir(), '.config', 'open-autonomy'), { recursive: true });
+  const tmp = mkdtempSync(join(homedir(), '.config', 'open-autonomy', 'setup-'));
+  try {
+    run(['git', 'clone', '-q', origin, join(tmp, 'repo')], { quiet: true });
+    if (originInside !== origin) run(['git', '-C', join(tmp, 'repo'), 'remote', 'set-url', 'origin', originInside], { quiet: true });
+    run([...docker, 'run', '--rm', '-v', 'oa-repo:/work', '-v', `${join(tmp, 'repo')}:/src:ro`, 'alpine:3', 'sh', '-c', `cp -a /src/. /work/ && chown -R ${uid}:${gid} /work`], { quiet: true });
+  } finally { rmSync(tmp, { recursive: true, force: true }); }
+  say(`repo: oa-repo cloned from ${origin}${originInside !== origin ? ` (origin inside the container: ${originInside})` : ''}`);
+}
+
+// 4. What is the owner's, and what is next.
+say('yours: the deploy key and the ssh-agent that forwards it into the Docker host (container/README.md), and the Discord bot token if you deliver there');
+for (const t of todo) say(`next: ${t}`);
+say(`next: AGENT_SECRETS=${secrets} ${docker.join(' ')} compose -f container/compose.yml up -d --build`);

package/template/AGENTS.md

@@ -0,0 +1,9 @@
+# __PROJECT__ — rules for the agent working this repository
+
+- **What this is.** __PROJECT__, a project that builds itself through Open Autonomy. `CONSTITUTION.md` is what it is and must remain. The board is what you build next, in order. `CONTRIBUTING.md` is how code is written here. `hermes/` is you.
+- **Checks.** `bun run check` from the repository root is the project's definition of green. It must pass before every push.
+- **Verify.** State here where the project is verified: its check, and any local or twinned surface. You cannot reach production and must not try. Where an acceptance line names a surface, exercise the surface.
+- **Git.** You cannot push to `main` and must not try. Work on `agent/<task id>` off a fresh `origin/main`, commit small with the task id first in the subject, and push the branch; the landing workflow opens the pull request and it merges itself when the checks pass. Never rewrite history, never force-push.
+- **Secrets.** There are none for you to use: your model calls and your pushes are authorized outside your reach. Never read or print `.env` files or key material; your sessions are published live.
+- **Do not edit** `LICENSE`, `.github/workflows/`, `container/`, `.open-autonomy/reporter.ts`, or anything under `hermes/` except a skill a task asks you to improve.
+- **Cost.** Your calls are metered and public. Read before writing; run the check once; stop when verified.

package/template/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## Unreleased
+- The repository was created with the Open Autonomy Hermes kit: the agent's home, the platform connection, the container stack and the landing workflows.

package/template/CONSTITUTION.md

@@ -0,0 +1,23 @@
+# __PROJECT__ — constitution
+
+__PROJECT__ is built by its own agent, in the open. Say here, in a paragraph, what the project is, for whom,
+and what it will be when it is done.
+
+What this project is and what it must remain. Its opening paragraph is the project's north star and leads its
+page; the invariants below bind every task, and a review that finds one violated sends the work back whatever
+else it got right. Changing this file is the owner's act, never a task's.
+
+## Invariants
+
+- **The board is the promise.** What will be built, in what order, is filed by the owner. The agent works it and
+  never invents work.
+- **The agent is readable.** Its identity, skills and schedule live in `hermes/`; changing what it does is a
+  commit anyone can read.
+- **Every spend is on the books.** Every model call and every purchase is metered to this project's account on
+  the platform and published, with what it was for.
+- **Done means true in the running system.** A task is done when its acceptance lines hold where the project is
+  verified, not when code exists.
+
+## Out of scope
+
+Name what this project will not become, so a task that drifts there is refused rather than built.

package/template/CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing to __PROJECT__
+
+How code is written here, for people and for the agent alike. The bar every diff is reviewed against, beside
+the constitution's invariants. Short on purpose; the reviewer reads it whole.
+
+- **Language and tooling.** TypeScript on Bun. `bun run check` is the definition of green and runs in seconds.
+- **Shape.** Small modules with one job each, named for what they hold. No layer that exists only to forward.
+- **Tests.** A test proves an acceptance line or guards a bug that happened. No tests for their own sake, no
+  mocks of our own code, no fixtures larger than the thing they test.
+- **Errors.** Fail loudly with the cause in the message. No silent fallbacks.
+- **Docs.** A file's header says what it is for. The README says how to run it. Nothing else is documented twice.
+- **Dependencies.** Add one only when writing it would be more code than reading it. Pin what you add.
+- **History.** One change per commit, the task id first in the subject, signed as the agent.

package/template/LICENSE

@@ -0,0 +1,55 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/template/README.md

@@ -0,0 +1,24 @@
+# __PROJECT__
+
+[![funding](https://open-autonomy.org/v1/accounts/__ACCOUNT_ENC__/runway.svg)](https://open-autonomy.org/p/__ACCOUNT_ENC__)
+[![now](https://open-autonomy.org/v1/accounts/__ACCOUNT_ENC__/now.svg)](https://open-autonomy.org/p/__ACCOUNT_ENC__)
+[![roadmap](https://open-autonomy.org/v1/accounts/__ACCOUNT_ENC__/roadmap.svg)](https://open-autonomy.org/p/__ACCOUNT_ENC__)
+[![activity](https://open-autonomy.org/v1/accounts/__ACCOUNT_ENC__/activity.svg)](https://open-autonomy.org/v1/accounts/__ACCOUNT_ENC__/calls)
+
+This project builds itself. Its agent, a checked-in Hermes home under `hermes/`, works its board top to
+bottom, funded through [Open Autonomy](https://open-autonomy.org/p/__ACCOUNT_ENC__), where
+every session it works, every cent it spends and everything it ships is public.
+
+- `CONSTITUTION.md` says what the project is and must remain; the agent's board says what gets built, in order; `CONTRIBUTING.md` is how code is written here, the bar every change is reviewed against.
+- `AGENTS.md` is the agent's rules for this repository; `hermes/` is the agent.
+- `.open-autonomy/` is the project's connection to the platform: its config, the reporter that publishes
+  the agent's sessions, and the record of the kit that made this repository.
+- `container/` runs it: the agent, the key valve that holds the project's key, and the reporter.
+
+```bash
+bun run check                                  # the project's own definition of green
+bun .open-autonomy/mint-key.ts                 # prove control of this repository, get the project's key
+AGENT_SECRETS=~/.config/open-autonomy docker compose -f container/compose.yml up -d --build
+```
+
+Made with the Open Autonomy Hermes kit; `create-open-autonomy check .` says whether the kit's files are current.

package/template/container/Dockerfile

@@ -0,0 +1,13 @@
+# The agent's container: stock Hermes at the pinned tag (container/hermes.pin, built by
+# container/build-hermes.sh) plus what a worker runs: git over ssh to push, bun for the
+# project's checks. It holds no secret: the key lives in the valve, the push key in an ssh-agent forwarded
+# from the host, and the only thing in its environment is an optional Discord token.
+ARG HERMES_IMAGE=hermes-agent:v2026.8.31
+FROM ${HERMES_IMAGE}
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends openssh-client git ca-certificates curl unzip \
+    && rm -rf /var/lib/apt/lists/*
+ARG BUN_VERSION=1.3.10
+RUN curl -fsSL https://bun.sh/install | BUN_INSTALL=/usr/local bash -s "bun-v${BUN_VERSION}" \
+    && ln -sf /usr/local/bin/bun /usr/local/bin/bunx && bun --version
+RUN mkdir -p /work

package/template/container/Dockerfile.reporter

@@ -0,0 +1,10 @@
+# The reporter: keyless. bun for the reporter itself and its two npm dependencies: supercode (the harness
+# it reads the agent's sessions through, a prebuilt binary per platform) and supercode's harness SDK. The
+# reporter's code is baked at build time; its config and its cursor live in the checkout.
+FROM oven/bun:1.3.10
+COPY .open-autonomy /opt/reporter
+WORKDIR /opt/reporter
+RUN bun install --no-save && chown -R bun:bun /opt/reporter && ./node_modules/.bin/supercode --version
+ENV PATH="/opt/reporter/node_modules/.bin:${PATH}"
+USER bun
+CMD ["bun", "/opt/reporter/reporter.ts", "--config", "/work/project/.open-autonomy/config.yaml"]

package/template/container/Dockerfile.valve

@@ -0,0 +1,5 @@
+# The key valve: the project's key lives here, never in the agent's or the reporter's container.
+FROM oven/bun:1.3.10
+COPY container/key-valve.ts /valve/key-valve.ts
+USER bun
+CMD ["bun", "/valve/key-valve.ts"]