create-open-autonomy 2.1.2 → 2.2.0

package/README.md

@@ -31,10 +31,10 @@ LICENSE              Apache-2.0, seeded; the project's own
 package.json, test/  the project's own check (`bun run check`), starting with one test
 hermes/              the agent: SOUL.md, its two skills (develop, pm), profiles/treasurer (the second profile: the one that pays), kanban.seed.json (the board's first tasks, in order),
                      cron/jobs.seed.json (the PM, hourly), config.yaml (the model: the project's own choice), the seed hook
-.open-autonomy/      the platform connection: config.yaml (account, publish policy, rail bounds), reporter.ts (the bridge:
-                     sessions, the board, the setup), mint-key.ts (the key, the adopter way), setup.ts (the host, by one
-                     command), the vendored SDK, kit.json (which kit, version and parameters made this repository)
-container/           the stack: the agent, the key valve, the reporter; the pinned Hermes image
+.open-autonomy/      the platform connection: config.yaml (account, publish policy, rail bounds), reporter.ts (the publisher:
+                     sessions, the board, the setup), mint-key.ts (the key, the adopter way), start.ts (the agent's four
+                     processes, the one way it starts), the vendored SDK, kit.json (which kit, version and parameters made this repository)
+container/           a real setup: one image whose entrypoint is start.ts as root, dropping the gateway to the image's user; the pinned Hermes
 .github/workflows/   ci.yml (the project's check on every branch), land.yml (the landing convention)
 ```
 
@@ -70,6 +70,6 @@ for a listed partner within a bound. Both leave records on the public audit trai
 
 ## Nothing in the agent's reach is a secret that matters
 
-The agent's `.env` says `OPEN_AUTONOMY_KEY=valve`. Pushes sign through an ssh-agent forwarded from the host
-holding one repository-scoped deploy key. Delivery uses at most a Discord bot token. Every session's turns
+The agent's `.env` says `OPEN_AUTONOMY_KEY=valve`. Pushes sign through an ssh-agent the start script loads with
+one repository-scoped deploy key, which the gateway never holds. Delivery uses at most a Discord bot token. Every session's turns
 are published; the platform redacts secret-shaped text at intake as the second wall.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-open-autonomy",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "The default Open Autonomy starter kit: a complete repository that runs its own Hermes agent against the platform, with the SDK wired in. `bun create open-autonomy <dir>` scaffolds one.",
   "license": "Apache-2.0",
   "repository": {
@@ -24,12 +24,11 @@
     "access": "public"
   },
   "scripts": {
-    "test": "bun test test/*.test.ts",
     "typecheck": "bunx tsc --noEmit",
-    "check": "bun test test/*.test.ts && bunx tsc --noEmit"
+    "check": "bunx tsc --noEmit"
   },
   "dependencies": {
-    "@open-autonomy/sdk": "2.1.0"
+    "@open-autonomy/sdk": "2.2.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.10",

package/src/kit.ts

@@ -9,7 +9,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 
-export const KIT = { name: 'hermes', version: '2.1.2' } as const;
+export const KIT = { name: 'hermes', version: '2.2.0' } as const;
 export const KIT_FILE = '.open-autonomy/kit.json';
 const TEMPLATE = resolve(import.meta.dir, '..', 'template');
 
@@ -17,7 +17,7 @@ export interface KitParams { project: string; account: string }
 export interface KitRecord { kit: string; version: string; params: KitParams; divergences: string[] }
 
 // What the kit keeps current. Everything else in the template is seeded once.
-const OWNED = [/^hermes\/(?!config\.yaml$|kanban\.seed\.json$)/, /^\.open-autonomy\/(reporter\.ts|mint-key\.ts|setup\.ts|package\.json|sdk\/)/, /^container\//, /^\.github\/workflows\/(ci|land)\.yml$/];
+const OWNED = [/^hermes\/(?!config\.yaml$|kanban\.seed\.json$)/, /^\.open-autonomy\/(reporter\.ts|mint-key\.ts|start\.ts|package\.json|sdk\/)/, /^container\//, /^\.github\/workflows\/(ci|land)\.yml$/];
 export const isOwned = (rel: string): boolean => OWNED.some((re) => re.test(rel));
 
 export function validateParams(p: Partial<KitParams>): KitParams {
@@ -38,7 +38,7 @@ function walk(dir: string, base = dir): string[] {
 // The Open Autonomy SDK is vendored into the generated repository under .open-autonomy/sdk, kit-owned, so
 // the reporter and the key tool run from a bare clone with no package to publish or install.
 const SDK_SRC = resolve(dirname(Bun.resolveSync('@open-autonomy/sdk/package.json', import.meta.dir)), 'src');
-const SDK_FILES = ['client.ts', 'roadmap.ts', 'drivers.ts', 'rails.ts'];
+const SDK_FILES = ['client.ts', 'roadmap.ts', 'drivers.ts', 'rails.ts', 'valve.ts'];
 
 // Every template file, rendered. Placeholders are `__PROJECT__` and `__ACCOUNT__` (and `__ACCOUNT_ENC__`,
 // the account as a URL path segment); binary-looking files pass through untouched.
@@ -98,10 +98,10 @@ export function check(dir: string): Outcome {
 // Kit-owned files the repository has that the kit no longer renders: what an earlier kit made and this one
 // retired. `upgrade` removes them; a project that keeps one names it in `divergences`. Only the families the
 // kit writes are looked at — never the agent's runtime state beside them (its database, sessions, logs, .env).
-const RETIRABLE = [/^hermes\/(skills|hooks|scripts)\//, /^\.open-autonomy\/([a-z-]+\.ts|sdk\/)/, /^container\//];
+const RETIRABLE = [/^hermes\/(skills|hooks|scripts)\//, /^\.open-autonomy\/([a-z-]+\.ts|sdk\/)/, /^container\//, /^\.github\/workflows\/(ci|land)\.yml$/];
 function retired(dir: string, rendered: Map<string, Buffer>, rec: KitRecord): string[] {
   const out: string[] = [];
-  for (const root of ['hermes/skills', 'hermes/hooks', 'hermes/scripts', '.open-autonomy', 'container']) {
+  for (const root of ['hermes/skills', 'hermes/hooks', 'hermes/scripts', '.open-autonomy', 'container', '.github/workflows']) {
     const at = join(dir, root);
     if (!existsSync(at)) continue;
     for (const rel of walk(at).map((f) => `${root}/${f}`)) if (RETIRABLE.some((re) => re.test(rel)) && isOwned(rel) && !rendered.has(rel) && !rec.divergences.includes(rel)) out.push(rel);

package/template/.github/workflows/land.yml

@@ -1,7 +1,6 @@
 name: Land a branch
-# Nothing pushes to `main`: branch protection requires a pull request and the `ci` check, with no bypass.
-# Work lands by pushing a branch: this workflow opens its pull request once and arms native auto-merge, so
-# it merges exactly when the required checks pass on its head commit.
+# Nothing pushes to `main`: branch protection requires a pull request, with no bypass, and no check stands
+# between a branch and main. Work lands by pushing a branch: this workflow opens its pull request once and merges it.
 #   agent/**  the agent's own work        land/**  a maintainer's
 on:
   push:
@@ -26,5 +25,5 @@ jobs:
               --body "Opened by the landing workflow for \`$BRANCH\`. It merges on its own when the required checks pass."
             existing=$(gh pr list -R "$REPO" --head "$BRANCH" --state open --json number -q '.[0].number')
           fi
-          gh pr merge -R "$REPO" "$existing" --auto --merge
-          echo "pull request #$existing: auto-merge armed"
+          gh pr merge -R "$REPO" "$existing" --merge
+          echo "pull request #$existing: merged"

package/template/.open-autonomy/config.yaml

@@ -11,10 +11,9 @@ publish:
   private:          # session ids or job names that never publish, whatever their kind
     - []
 
-# Where sessions come from: the Hermes home the reporter reads through supercode, and where it keeps its
-# own cursor. Inside the container stack these are the mounted volume and the checkout.
-hermes_home: /opt/data
-state_file: /work/project/.open-autonomy/reporter-state.json
+# Where sessions come from: the Hermes home the reporter reads through supercode (HERMES_HOME in its
+# environment), and where it keeps its own cursor (beside this file).
+state_file: reporter-state.json
 
 # The rails the agent may spend through beyond model calls, and the owner's bounds on each. Off unless a
 # bound is set. Every rail leaves a record on the public audit trail naming itself.

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

@@ -5,14 +5,14 @@
 // 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]
+//   HERMES_HOME=<the agent's home> OPEN_AUTONOMY_BASE_URL=http://127.0.0.1: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 { dirname, 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';
@@ -54,8 +54,8 @@ function readConfig(path: string): Config {
   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'),
+    hermes_home: top.hermes_home ?? process.env.HERMES_HOME ?? '',
+    state_file: resolve(dirname(configPath), top.state_file ?? 'reporter-state.json'),
   };
 }
 

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

@@ -0,0 +1,106 @@
+#!/usr/bin/env bun
+// Start the agent. The same processes wherever it runs; only how this script is started differs:
+//   on your machine   `bun .open-autonomy/start.ts` — everything as you, no isolation, for development
+//   in a container    the image's entrypoint, as root with the secrets mounted for root alone and `--as <user>`:
+//                     the gateway and the reporter run as that user and can reach no key (container/README.md)
+//
+//   bun .open-autonomy/start.ts [--home <dir>] [--secrets <dir>] [--project <dir>] [--origin <url>] [--as <user>]
+//
+// The processes, in order:
+//   ssh-agent   holds <secrets>/deploy_key, its socket at <home>/ssh-agent.sock; the gateway pushes through it
+//               and never holds the key (absent: pushes are your own git's business)
+//   the clone   <project> cloned from --origin when it is not a checkout yet (a container's first boot)
+//   the home    hermes/ in the checkout copied into <home> before every start — the repository is the source of
+//               truth for what the agent IS; the home keeps what it has since done (its .env is kept)
+//   valve       <secrets>/agent.env on :8787 (the developer's key), <secrets>/treasurer.env on :8788 (the
+//               treasurer's, the only one that pays) — the agent's .env names the valve and the word `valve`
+//   reporter    keyless, publishing the home's sessions and board through the valve
+//   gateway     `hermes gateway run` in the checkout, HERMES_HOME=<home>
+// When any of them ends, all of them end and this exits 1: the supervisor outside (you, launchd, Docker) restarts.
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir, userInfo } from 'node:os';
+import { basename, resolve } from 'node:path';
+
+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 project = resolve(arg('--project') ?? resolve(import.meta.dir, '..'));
+const home = resolve(arg('--home') ?? process.env.AGENT_HOME ?? resolve(homedir(), '.local', 'state', 'open-autonomy', basename(project), 'home'));
+const secrets = resolve(arg('--secrets') ?? process.env.AGENT_SECRETS ?? resolve(homedir(), '.config', 'open-autonomy'));
+const origin = arg('--origin') ?? process.env.ORIGIN;
+const as = arg('--as');
+const say = (m: string) => console.log(`start: ${m}`);
+const sock = resolve(home, 'ssh-agent.sock');
+
+// Who the agent's processes run as: you, or with --as the named user (root drops to it; the secrets stay root's).
+const user = as ? (() => { const r = Bun.spawnSync({ cmd: ['id', '-u', as], stdout: 'pipe', stderr: 'pipe' }); const g = Bun.spawnSync({ cmd: ['id', '-g', as], stdout: 'pipe' }); if (r.exitCode !== 0) throw new Error(`start: no such user ${as}`); return { name: as, uid: Number(r.stdout.toString().trim()), gid: Number(g.stdout.toString().trim()) }; })() : null;
+const drop = (cmd: string[]): string[] => (user ? ['setpriv', `--reuid=${user.uid}`, `--regid=${user.gid}`, '--clear-groups', ...cmd] : cmd);
+const own = (path: string) => { if (user) Bun.spawnSync({ cmd: ['chown', '-R', `${user.uid}:${user.gid}`, path] }); };
+const agentEnv = (): Record<string, string> => ({ ...process.env as Record<string, string>, HERMES_HOME: home, ...(user ? { HOME: home, USER: user.name, LOGNAME: user.name } : {}), ...(existsSync(sock) ? { SSH_AUTH_SOCK: sock } : {}), GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND ?? 'ssh -o StrictHostKeyChecking=accept-new' });
+
+const children: Array<{ name: string; proc: ReturnType<typeof Bun.spawn> }> = [];
+let ending = false;
+function spawn(name: string, cmd: string[], opts: { cwd?: string; env?: Record<string, string>; asAgent?: boolean }) {
+  const proc = Bun.spawn({ cmd: opts.asAgent ? drop(cmd) : cmd, cwd: opts.cwd ?? project, env: opts.env ?? (process.env as Record<string, string>), stdout: 'inherit', stderr: 'inherit', stdin: 'ignore' });
+  children.push({ name, proc });
+  proc.exited.then((code) => { if (ending) return; ending = true; say(`${name} ended (${code}); stopping the rest`); for (const c of children) if (c.proc !== proc) c.proc.kill(); setTimeout(() => process.exit(1), 500); });
+  return proc;
+}
+for (const sig of ['SIGTERM', 'SIGINT'] as const) process.on(sig, () => { ending = true; for (const c of children) c.proc.kill(); setTimeout(() => process.exit(0), 300); });
+
+mkdirSync(home, { recursive: true });
+own(home);
+
+// 1. ssh-agent, as the agent (an agent only answers its own uid, or root): the key is added by us, from a file
+//    the agent cannot read, and lives in the agent's memory alone.
+const deployKey = resolve(secrets, 'deploy_key');
+if (existsSync(deployKey)) {
+  rmSync(sock, { force: true });
+  spawn('ssh-agent', ['ssh-agent', '-D', '-a', sock], { asAgent: true, cwd: home });
+  const t0 = Date.now(); while (!existsSync(sock) && Date.now() - t0 < 5000) Bun.sleepSync(50);
+  const add = Bun.spawnSync({ cmd: ['ssh-add', '-q', deployKey], env: { ...process.env, SSH_AUTH_SOCK: sock }, stdout: 'pipe', stderr: 'pipe' });
+  if (add.exitCode !== 0) { console.error(`start: ssh-add ${deployKey}: ${add.stderr.toString().trim()}`); process.exit(1); }
+  say(`ssh-agent holds the deploy key at ${sock}`);
+} else say(`no ${deployKey}: pushes use your own git and keys`);
+
+// 2. The checkout.
+if (!existsSync(resolve(project, '.git'))) {
+  if (!origin) { console.error(`start: ${project} is not a checkout and no --origin to clone`); process.exit(1); }
+  mkdirSync(project, { recursive: true }); own(project);
+  const clone = Bun.spawnSync({ cmd: drop(['git', 'clone', '-q', origin, project]), env: agentEnv(), stdout: 'inherit', stderr: 'inherit' });
+  if (clone.exitCode !== 0) { console.error(`start: cannot clone ${origin}`); process.exit(1); }
+  say(`cloned ${origin} → ${project}`);
+}
+
+// 3. The home, from the checkout: everything under hermes/ except its .env, which is the home's own.
+const committed = resolve(project, 'hermes');
+if (existsSync(committed)) cpSync(committed, home, { recursive: true, filter: (src) => basename(src) !== '.env' });
+const envFile = resolve(home, '.env');
+if (!existsSync(envFile)) {
+  const lines = ['OPEN_AUTONOMY_BASE_URL=http://127.0.0.1:8787/v1', 'OPEN_AUTONOMY_KEY=valve'];
+  for (const k of ['DISCORD_BOT_TOKEN', 'DISCORD_HOME_CHANNEL']) if (process.env[k]) lines.push(`${k}=${process.env[k]}`);
+  writeFileSync(envFile, `${lines.join('\n')}\n`);
+}
+own(home);
+say(`home ${home} synced from ${committed}`);
+
+// 4. The valve: one key file per port; a missing developer's key is the one thing that stops the start.
+const keys: string[] = [];
+if (existsSync(resolve(secrets, 'agent.env'))) keys.push('--key', `${resolve(secrets, 'agent.env')}:8787`);
+if (existsSync(resolve(secrets, 'treasurer.env'))) keys.push('--key', `${resolve(secrets, 'treasurer.env')}:8788`);
+if (!keys.length) { console.error(`start: no ${resolve(secrets, 'agent.env')} — mint the developer's key: bun .open-autonomy/mint-key.ts`); process.exit(1); }
+if (user) {
+  // The whole point of --as: the agent's user must not be able to read a key.
+  const peek = Bun.spawnSync({ cmd: drop(['cat', resolve(secrets, 'agent.env')]), stdout: 'pipe', stderr: 'pipe' });
+  if (peek.exitCode === 0) { console.error(`start: ${resolve(secrets, 'agent.env')} is readable by ${user.name}; the secrets must belong to root alone`); process.exit(1); }
+}
+// The valve and the reporter run from this script's own directory (its node_modules, its vendored SDK): in a
+// container that is the image's copy, and the checkout only has to be the project.
+spawn('valve', ['bun', resolve(import.meta.dir, 'sdk', 'valve.ts'), ...keys], {});
+
+// 5. The reporter and the gateway, as the agent.
+const env = agentEnv();
+spawn('reporter', ['bun', resolve(import.meta.dir, 'reporter.ts'), '--config', resolve(project, '.open-autonomy', 'config.yaml')], { asAgent: true, env: { ...env, OPEN_AUTONOMY_BASE_URL: 'http://127.0.0.1:8787/v1' } });
+spawn('gateway', ['hermes', 'gateway', 'run'], { asAgent: true, env });
+say(`gateway up in ${project} as ${user?.name ?? userInfo().username}, home ${home}; the valve on :8787${keys.length > 2 ? ' and :8788' : ''}`);
+if (!readFileSync(resolve(project, '.open-autonomy', 'config.yaml'), 'utf8').includes('account:')) say('warning: .open-autonomy/config.yaml names no account');
+await new Promise(() => {});

package/template/AGENTS.md

@@ -1,7 +1,7 @@
 # __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.
+- **Checks.** `bun run check` from the repository root is the project's definition of green, in under thirty seconds. It must pass before every push. Behavior is verified by running the system, not by tests written for the occasion.
 - **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.

package/template/CONSTITUTION.md

@@ -17,6 +17,8 @@ else it got right. Changing this file is the owner's act, never a task's.
   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.
+- **No automated test runs for more than thirty seconds.** All of them together, ever. Behavior is verified by
+  driving the running system.
 
 ## Out of scope
 

package/template/CONTRIBUTING.md

@@ -5,8 +5,9 @@ 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.
+- **Thirty seconds, total, forever.** `bun run check` is every test and typecheck there is, and it must finish in
+  under thirty seconds. A test guards an invariant of the constitution or it is not written; behavior is verified by
+  driving the running system. Test cruft compounds, because every agent that follows writes more of it.
 - **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.

package/template/README.md

@@ -13,12 +13,13 @@ every session it works, every cent it spends and everything it ships is public.
 - `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.
+- `.open-autonomy/start.ts` starts it: the valve that holds the project's keys, the reporter, the Hermes gateway;
+  `container/` runs the same script as a container's entrypoint, for a real setup.
 
 ```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
+bun .open-autonomy/start.ts                    # the agent, here, as you (container/README.md for the container)
 ```
 
 Made with the Open Autonomy Hermes kit; `create-open-autonomy check .` says whether the kit's files are current.

package/template/_gitignore

@@ -60,3 +60,4 @@ hermes/.skills_prompt_snapshot.json
 
 # The reporter's own cursor (which sessions it has published how far).
 .open-autonomy/reporter-state.json
+.open-autonomy/bun.lock

package/template/container/Dockerfile

@@ -1,7 +1,7 @@
-# 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.
+# The agent's container: stock Hermes at the pinned tag (container/hermes.pin, built by container/build-hermes.sh) plus
+# bun and git over ssh, started by the same script that starts it on a laptop (.open-autonomy/start.ts), here as root
+# with `--as hermes`: the secrets mounted at /secrets are root's, and the gateway runs as the image's `hermes` user
+# and can reach no key. The checkout is cloned into /work/project on first boot; the home lives at /opt/data.
 ARG HERMES_IMAGE=hermes-agent:v2026.8.31
 FROM ${HERMES_IMAGE}
 USER root
@@ -10,4 +10,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends openssh-client
 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
+# The start script and the reporter's dependencies, from the image — the checkout arrives after the first boot.
+COPY .open-autonomy /opt/agent/.open-autonomy
+RUN cd /opt/agent/.open-autonomy && bun install --no-save && ./node_modules/.bin/supercode --version
+RUN mkdir -p /work/project /opt/data && chown hermes:hermes /work/project /opt/data
+ENV PATH="/opt/agent/.open-autonomy/node_modules/.bin:${PATH}"
+ENTRYPOINT ["bun", "/opt/agent/.open-autonomy/start.ts", "--project", "/work/project", "--home", "/opt/data", "--secrets", "/secrets", "--as", "hermes"]

package/template/container/README.md

@@ -1,49 +1,40 @@
 # Running the agent
 
-Three containers in one VM, none holding a secret that matters:
-
-- **agent** — stock Hermes at the pinned tag (`hermes.pin`), with the project checkout at `/work/project`
-  and the home volume at `/opt/data`, seeded from `hermes/` and re-synced from the repository on every start.
-- **valve** — holds the developer's key (spend + narrate). The agent's model calls and the reporter's narration
-  go through it; key management and admin routes never do. It re-reads the key file when it changes, so a
-  rotated key needs no restart.
-- **valve-pay** — holds the treasurer's key, the only one with the `pay` scope. The treasurer profile alone is
-  pointed at it, so a purchase can only be made by the treasurer, within the owner's bounds.
-- **reporter** — keyless. Reads the agent's sessions through supercode and publishes them to the project's
-  page through the valve, as they happen.
-
-Every session's turns are published, so the agent's environment holds nothing whose leak matters:
-its `.env` says `OPEN_AUTONOMY_KEY=valve`; pushes sign through an ssh-agent forwarded from the host holding
-one repository-scoped deploy key; delivery uses at most a Discord bot token, which can only post as the bot.
-
-## The host
-
-`bun .open-autonomy/setup.ts` does the steps below, idempotently, and says what it cannot do and what to run
-next; the world's stack step calls the same file. By hand:
-
-- `~/.config/open-autonomy/agent.env` — the developer's key, from `bun .open-autonomy/mint-key.ts`;
-  `~/.config/open-autonomy/treasurer.env` — the treasurer's, from `bun .open-autonomy/mint-key.ts --scopes
-  spend,narrate,pay --out ~/.config/open-autonomy/treasurer.env`. Rotate it with
-  `bun .open-autonomy/mint-key.ts --rotate`: the valve takes the new key from the file without a restart, and its
-  `/healthz` (and its log, and the reporter's) say when the key expires; both warn inside fourteen days.
-- An ssh-agent holding only the deploy key, forwarded into the Docker host (on macOS with colima:
-  `SSH_AUTH_SOCK=~/.config/open-autonomy/agent.sock colima start <profile> --ssh-agent`).
-- The pinned Hermes image: `sh container/build-hermes.sh` builds it from `hermes.pin`.
-
-Then the two volumes, once: `oa-home` from your `hermes/` (with a `.env` naming
-`OPEN_AUTONOMY_BASE_URL=http://valve:8787/v1`, `OPEN_AUTONOMY_KEY=valve`, and the Discord token if any) and
-`oa-repo`, a clone made with the deploy key. Then:
+The agent is four processes: an ssh-agent holding the deploy key, the valve holding the project's keys (the
+developer's on :8787, the treasurer's on :8788, each re-read when its file changes), the keyless reporter, and
+the Hermes gateway. One script starts them, `.open-autonomy/start.ts`, and it is the only way they are started.
+
+**On your machine**, for development: everything as you, no isolation.
+
+```bash
+bun .open-autonomy/mint-key.ts                                   # the developer's key → ~/.config/open-autonomy/agent.env
+bun .open-autonomy/mint-key.ts --scopes spend,narrate,pay --out ~/.config/open-autonomy/treasurer.env
+bun .open-autonomy/start.ts                                      # ssh-agent, valve, reporter, gateway; Ctrl-C ends all
+HERMES_HOME=~/.local/state/open-autonomy/<project>/home hermes kanban list   # the board, from another shell
+```
+
+**In a container**, for a real setup: the same script is the image's entrypoint, run as root with the secrets
+mounted for root alone; the gateway and the reporter run as the image's `hermes` user and can reach no key
+(the script refuses to start if they could). Every session's turns are published, so the agent's environment
+holds nothing whose leak matters: its `.env` says `OPEN_AUTONOMY_KEY=valve`; pushes sign through the
+ssh-agent's socket; delivery uses at most a Discord bot token, which can only post as the bot.
+
+- `~/.config/open-autonomy/agent.env` and `treasurer.env`: the keys, as above (rotate with `--rotate`; the
+  valve takes the new key from the file without a restart).
+- `~/.config/open-autonomy/deploy_key`: a deploy key for this one repository, write access:
+  `ssh-keygen -t ed25519 -N '' -f ~/.config/open-autonomy/deploy_key` and
+  `gh repo deploy-key add ~/.config/open-autonomy/deploy_key.pub --allow-write`. The container clones through it
+  on first boot.
+- The pinned Hermes image: `sh container/build-hermes.sh` builds it from `hermes.pin` (~10 minutes, once).
 
 ```bash
 AGENT_SECRETS=~/.config/open-autonomy docker compose -f container/compose.yml up -d --build
-docker exec -u $UID oa-agent hermes cron list            # the schedule: the PM, hourly, seeded from hermes/cron/jobs.seed.json
-docker exec -u $UID oa-agent hermes kanban create 'A task' --body '- its acceptance line' --assignee default --workspace dir:/work/project --skill develop   # file work
-docker exec -u $UID oa-agent hermes kanban list                  # the board: the task, its lane, its attempts
-docker logs -f oa-reporter                               # what is being published
+docker logs -f oa-agent                                                          # the start's four processes
+docker exec -u hermes oa-agent hermes kanban list                                # the board
+docker exec -u hermes oa-agent hermes kanban create 'A task' --body '- its acceptance line' --assignee default --workspace dir:/work/project --skill develop
 ```
 
-Several stacks on one Docker host, two projects or a project beside a world's copy of it: give each a name,
-`bun .open-autonomy/setup.ts --stack <name>` and `STACK=<name> docker compose -p <name> …`; the containers and
-volumes carry it (`<name>-agent`, `<name>-home`). The default is `oa`.
+Several stacks on one Docker host: `STACK=<name> docker compose -p <name> …`; the container and volumes carry
+the name (`<name>-agent`, `<name>-home`, `<name>-repo`). The default is `oa`.
 
-The kit owns this directory; `create-open-autonomy upgrade .` brings it forward.
+The kit owns this directory and `.open-autonomy/start.ts`; `create-open-autonomy upgrade .` brings them forward.

package/template/container/compose.yml

@@ -1,53 +1,14 @@
-# The project's agent, as it runs: three containers in one VM, none holding a secret that matters.
-#   agent      stock Hermes (the gateway: the schedule, and Discord when configured) with the project checkout;
-#              two profiles, the developer and the treasurer
-#   valve      holds the developer's key (spend + narrate): the model routes and the narration routes
-#   valve-pay  holds the treasurer's key (spend + narrate + pay): the same routes and the rails; only the
-#              treasurer profile is pointed at it
-#   reporter   keyless; reads the agent's sessions through supercode and publishes them through the valve
-# The home and the checkout live in Docker volumes: SQLite over a host bind mount is a bus error waiting
-# to happen, and nothing on the host needs them. Inspect with `docker exec`.
+# The agent as a real setup runs it: one container, started by the same script a laptop uses
+# (.open-autonomy/start.ts), as root with the secrets mounted for root alone; the gateway inside runs as the
+# image's `hermes` user and can reach no key. The home and the checkout live in Docker volumes (SQLite over a
+# bind mount is a bus error waiting to happen); inspect them with `docker exec`.
 #
 #   AGENT_SECRETS=~/.config/open-autonomy docker compose -f container/compose.yml up -d --build
+#
 # Several stacks on one Docker host (two projects, or a project beside a world's copy of it): each has its own
-# STACK name, which the containers and volumes carry, and its own compose project: `STACK=<name> docker compose
+# STACK name, which the container and volumes carry, and its own compose project: `STACK=<name> docker compose
 # -p <name> …`. The default is `oa`.
 services:
-  valve:
-    build:
-      context: ..
-      dockerfile: container/Dockerfile.valve
-    image: __PROJECT__-valve:local
-    container_name: ${STACK:-oa}-valve
-    restart: unless-stopped
-    environment:
-      - AGENT_ENV_FILE=/secrets/agent.env
-    volumes:
-      - ${AGENT_SECRETS:-~/.config/open-autonomy}/agent.env:/secrets/agent.env:ro
-    networks: [agent]
-  valve-pay:
-    build:
-      context: ..
-      dockerfile: container/Dockerfile.valve
-    image: __PROJECT__-valve:local
-    container_name: ${STACK:-oa}-valve-pay
-    restart: unless-stopped
-    environment:
-      - AGENT_ENV_FILE=/secrets/treasurer.env
-    volumes:
-      - ${AGENT_SECRETS:-~/.config/open-autonomy}/treasurer.env:/secrets/treasurer.env:ro
-    networks: [agent]
-  # The committed home (SOUL, skills, config, the schedule seed) into the volume before the gateway starts:
-  # hermes/ in the repository is the source of truth for what the agent IS; the volume only holds what the
-  # agent has since done.
-  home-sync:
-    image: alpine:3
-    container_name: ${STACK:-oa}-home-sync
-    restart: "no"
-    command: ["sh", "-c", "cd /repo/hermes && find . -type f ! -name '.env' -exec cp -a --parents {} /opt/data/ \\; && chown -R ${AGENT_UID:-501}:${AGENT_GID:-20} /opt/data && echo 'home synced from the repository'"]
-    volumes:
-      - oa-home:/opt/data
-      - oa-repo:/repo:ro
   agent:
     build:
       context: ..
@@ -57,46 +18,16 @@ services:
     image: __PROJECT__-agent:local
     container_name: ${STACK:-oa}-agent
     restart: unless-stopped
-    depends_on:
-      valve: { condition: service_started }
-      home-sync: { condition: service_completed_successfully }
-    command: ["gateway", "run"]
-    environment:
-      # The host user's ids: the forwarded ssh-agent socket is theirs.
-      - HERMES_UID=${AGENT_UID:-501}
-      - HERMES_GID=${AGENT_GID:-20}
-      - SSH_AUTH_SOCK=/ssh-agent
-      - GIT_SSH_COMMAND=ssh -o StrictHostKeyChecking=accept-new
-    volumes:
-      - oa-home:/opt/data
-      - oa-repo:/work/project
-      - /run/host-services/ssh-auth.sock:/ssh-agent
-    networks: [agent]
-  reporter:
-    build:
-      context: ..
-      dockerfile: container/Dockerfile.reporter
-    image: __PROJECT__-reporter:local
-    container_name: ${STACK:-oa}-reporter
-    restart: unless-stopped
-    # The agent's own ids: the home it reads and the checkout it keeps its cursor in are the agent's.
-    user: "${AGENT_UID:-501}:${AGENT_GID:-20}"
-    depends_on:
-      valve: { condition: service_started }
-      agent: { condition: service_started }
     environment:
-      - OPEN_AUTONOMY_BASE_URL=http://valve:8787/v1
-      - HERMES_HOME=/opt/data
+      - ORIGIN=${ORIGIN:-git@github.com:__ACCOUNT__.git} # cloned on first boot, through the deploy key
+      - DISCORD_BOT_TOKEN=${DISCORD_BOT_TOKEN:-}
+      - DISCORD_HOME_CHANNEL=${DISCORD_HOME_CHANNEL:-}
     volumes:
-      - oa-home:/opt/data:ro
-      - oa-repo:/work/project
-    networks: [agent]
+      - ${AGENT_SECRETS:-~/.config/open-autonomy}:/secrets:ro
+      - home:/opt/data
+      - repo:/work/project
 volumes:
-  oa-home:
+  home:
     name: ${STACK:-oa}-home
-    external: true # seeded once from hermes/ (container/README.md)
-  oa-repo:
+  repo:
     name: ${STACK:-oa}-repo
-    external: true # the agent's clone
-networks:
-  agent: {}

package/template/hermes/README.md

@@ -12,7 +12,8 @@ to this project's account and paid for by its patrons. The board is the roadmap:
 (`hermes kanban create`), the gateway's dispatcher pulls them down in order and runs each as a worker session
 that builds it and lands it on an `agent/<task id>` branch, the review lane (Hermes's own) verifies the handoff
 against `CONSTITUTION.md` and `CONTRIBUTING.md` in a session of its own, and once an hour the PM job reads the whole board and unsticks what is
-stuck. The reporter beside it (`.open-autonomy/reporter.ts`) publishes the board, every session, the agent's setup,
+stuck. Beside it the valve holds the keys, an ssh-agent holds the deploy key, and the reporter
+(`.open-autonomy/reporter.ts`) publishes the board, every session, the agent's setup,
 and the project's documents (`CONSTITUTION.md` as what it is, `CHANGELOG.md` as what shipped) to the project's
 page as they happen. The platform reads none of these files itself.
 

package/template/hermes/SOUL.md

@@ -1,6 +1,6 @@
 You are this project's agent: the checked-in Hermes agent that builds the project you run in, month after month, on a token budget its sponsors fund through Open Autonomy. Your home is the repository you run in. Everything you are is readable there: this file, your two skills, your one scheduled job.
 
-The board is the roadmap. The owner files tasks on it; your dispatcher pulls them down in order and runs each as a worker session (the develop skill), the review lane verifies every handoff, and once an hour you look at the whole board and unstick what is stuck (the pm skill). When you review, the bar is two documents: `CONSTITUTION.md`, whose invariants no change may violate and whose out-of-scope no change may enter, and `CONTRIBUTING.md`, which the diff is held to. Every acceptance line made true and verified, and nothing in the diff that no line asked for, tests included. Approve in one paragraph naming what you checked; otherwise send it back naming each failing line. You finish things: a task is done when its acceptance lines are true in the running system, not when code exists. You never invent tasks; filing is the owner's job.
+The board is the roadmap. The owner files tasks on it; your dispatcher pulls them down in order and runs each as a worker session (the develop skill), the review lane verifies every handoff, and once an hour you look at the whole board and unstick what is stuck (the pm skill). When you review, the bar is two documents: `CONSTITUTION.md`, whose invariants no change may violate and whose out-of-scope no change may enter, and `CONTRIBUTING.md`, which the diff is held to. Every acceptance line made true and verified by running the system, nothing in the diff that no line asked for, and no test that guards nothing in the constitution: test cruft is the one debt that compounds. Approve in one paragraph naming what you checked; otherwise send it back naming each failing line. You finish things: a task is done when its acceptance lines are true in the running system, not when code exists. You never invent tasks; filing is the owner's job.
 
 You spend sponsors' money. Every model call you make is metered to this project's account and shown in public. Be economical: read before you write, run the check once, and stop when the work is verified. Do not loop on a failure you cannot explain; say what you found and block the task with what is missing.
 

package/template/hermes/cron/jobs.seed.json

@@ -5,8 +5,7 @@
       "prompt": "You are this project's PM for the hour. Run the pm skill: read the board, unstick what is stuck, report.",
       "schedule": "every 60m",
       "skills": ["pm"],
-      "deliver": "discord",
-      "workdir": "/work/project"
+      "deliver": "discord"
     }
   ]
 }

package/template/hermes/hooks/seed/handler.py

@@ -108,15 +108,17 @@ def _seed_jobs() -> list:
 # ---- the board -------------------------------------------------------------------------------------------------
 
 def _seed_tasks() -> tuple:
+    import os
+    # Every seed task works in the project checkout: the directory the gateway runs in.
+    workspace = f"dir:{os.getcwd()}"
     seed_file = _hermes_home() / "kanban.seed.json"
     if not seed_file.exists():
-        return "dir:/work/project", []
+        return workspace, []
     try:
         data = json.loads(seed_file.read_text(encoding="utf-8"))
     except (OSError, ValueError) as e:
         logger.error("seed: failed to read %s: %s", seed_file, e)
-        return "dir:/work/project", []
-    workspace = str(data.get("workspace") or "dir:/work/project")
+        return workspace, []
     tasks = [t for t in data.get("tasks", []) if isinstance(t, dict) and t.get("key") and t.get("title")]
     return workspace, tasks
 
@@ -160,6 +162,7 @@ def _seed_board() -> None:
 
 
 async def handle(event_type: str, context: dict) -> None:
+    import os
     _seed_board()
     try:
         from cron.jobs import create_job, load_jobs, update_job
@@ -205,7 +208,7 @@ async def handle(event_type: str, context: dict) -> None:
                 deliver=_deliver_target(name, spec.get("deliver")),
                 skills=spec.get("skills") or None,
                 skill=spec.get("skill"),
-                workdir=spec.get("workdir"),
+                workdir=os.getcwd(),
                 script=spec.get("script"),
                 no_agent=bool(spec.get("no_agent")),
                 model=None if spec.get("no_agent") else model,

package/template/hermes/kanban.seed.json

@@ -1,5 +1,4 @@
 {
-  "workspace": "dir:/work/project",
   "tasks": [
     {
       "key": "hello",

package/template/hermes/profiles/treasurer/SOUL.md

@@ -4,10 +4,10 @@ For each request, in order:
 
 1. `kanban_show` it and read the owner's bounds in `.open-autonomy/config.yaml` (`rails:`). A request over the bound, or at a merchant outside the owner's categories, is refused: `kanban_block` it with the reason, and never widen a bound; that is the owner's commit.
 2. Mint the card through your valve, naming the developer's task so the purchase shows on its page:
-   `curl -sf -X POST http://valve-pay:8787/v1/rails/card -H 'authorization: Bearer valve' -H 'content-type: application/json' -d '{"usd_cents": <ceiling>, "purpose": "<why>", "item": "<the developer's task id>"}'`.
+   `curl -sf -X POST http://127.0.0.1:8788/v1/rails/card -H 'authorization: Bearer valve' -H 'content-type: application/json' -d '{"usd_cents": <ceiling>, "purpose": "<why>", "item": "<the developer's task id>"}'`.
    The answer carries the card. It is single-use, bounded to that amount and the owner's categories, and retires on capture.
 3. Pay the merchant yourself, the way the request says. The card's number goes into the merchant's checkout and nowhere else: never into a comment, a file, a commit or a message.
-4. Record the receipt on the developer's task and release it: `HERMES_HOME=/opt/data /opt/hermes/bin/hermes kanban comment <developer task> "RECEIPT: <what> at <merchant>, $<amount> on card ····<last4>"`, then `HERMES_HOME=/opt/data /opt/hermes/bin/hermes kanban unblock <developer task>` (the terminal's shell has neither the home nor the binary on its path; both are named in full).
+4. Record the receipt on the developer's task and release it: `hermes kanban comment <developer task> "RECEIPT: <what> at <merchant>, $<amount> on card ····<last4>"`, then `hermes kanban unblock <developer task>` (the terminal's shell has neither the home nor the binary on its path; both are named in full).
 5. `kanban_complete` your task with the receipt in one line.
 
 You never write code, never touch the developer's branch, and never buy what no request asked for. Every cent you spend is on the project's public books, under the task it served.

package/template/hermes/profiles/treasurer/config.yaml

@@ -6,7 +6,7 @@
 model:
   default: zai/glm-5.3-flash
   provider: custom
-  base_url: http://valve-pay:8787/v1 # the treasurer's valve: the only key that pays
+  base_url: http://127.0.0.1:8788/v1 # the valve's second port: the treasurer's key, the only one that pays
   api_key: valve
   api_mode: chat_completions
 

package/template/hermes/skills/open-autonomy/develop/SKILL.md

@@ -22,11 +22,13 @@ is not done.
 2. Read `CONSTITUTION.md` (what the project is and must remain: a task that would break an invariant or enter
    what is out of scope is blocked, not built), `CONTRIBUTING.md` (how code is written here) and `AGENTS.md`.
    Read the code an acceptance line touches before you write.
-3. Build it. Match `CONTRIBUTING.md`. Write a test only where an acceptance line names one, or where the project's
-   check would otherwise not cover the line; never tests for their own sake.
-4. Verify every acceptance line where `AGENTS.md` says the project is verified: in the project's own twin world
-   when it keeps one (`world/`), as its operator, driving the real surface; otherwise the project's check. You
-   cannot reach production and must not try. Run the check once, green, before every push.
+3. Build it. Match `CONTRIBUTING.md`. Write no test unless the acceptance line guards an invariant of the
+   constitution and `bun run check` stays under thirty seconds with it; behavior is verified by running the system,
+   never by a test written for the occasion.
+4. Verify every acceptance line by driving the running system where `AGENTS.md` says it is verified: in the
+   project's own twin world when it keeps one (`world/`), as its operator, one action at a time, reading what
+   comes back; otherwise by running the program itself. You cannot reach production and must not try. Run
+   `bun run check` once, green, before every push.
 5. Commit small, signed as the agent, the task id first in the subject:
    `git commit -s --author="Open Autonomy agent <agent@open-autonomy.org>" -m "<task id>: <what changed>"`.
 6. Push the branch: `git push -u origin agent/<task id>`. The landing workflow opens the pull request and merges
@@ -44,7 +46,7 @@ You cannot pay: your key reaches the model, not the rails. The treasurer, a seco
 holds the only key that can. Ask it the way a company does, once, and wait:
 
 1. File the request, the one task you may create:
-   `kanban_create` with `assignee: "treasurer"`, `workspace_kind: "dir"`, `workspace_path: "/work/project"` (so the
+   `kanban_create` with `assignee: "treasurer"`, `workspace_kind: "dir"`, `workspace_path: <the project checkout, your working directory>` (so the
    treasurer reads the owner's bounds), title `Purchase: <what> at <merchant>, at most $<ceiling>`, and a body of
    `- ` lines: what, merchant (and its category), at most N cents, purpose, `for task: <your task id>`,
    and how to pay (the merchant's checkout: a URL, a command). Stay within the owner's bounds in
@@ -61,7 +63,7 @@ The card never passes through you. Every purchase lands on the public audit trai
 
 The board's tools (`kanban_show`, `kanban_create`, `kanban_block`, `kanban_request_review`) are yours in the
 conversation. From the terminal the CLI needs its home and its path named in full:
-`HERMES_HOME=/opt/data /opt/hermes/bin/hermes kanban …`.
+`hermes kanban …` (HERMES_HOME is set in your environment).
 
 ## Cost
 

package/template/hermes/skills/open-autonomy/pm/SKILL.md

@@ -23,7 +23,7 @@ as a worker session, and the review lane verifies every handoff. Your hour is ab
      restarts a worker that will only block again, and the board escalates repeated blocks into decomposition.
    - `running` with no heartbeat for over an hour, or `review` with no reviewer for over an hour: `hermes kanban
      unblock <id>` returns it to ready.
-   The CLI from your shell needs its home and path in full: `HERMES_HOME=/opt/data /opt/hermes/bin/hermes kanban …`.
+   From your shell the CLI is `hermes kanban …` (HERMES_HOME is set in your environment).
 3. Report, in one paragraph, where the job says: what was done since the last hour, what is in progress, what is
    stuck and why, and what the owner must decide. When the board is empty, say so; nothing else to do.
 

package/template/package.json

@@ -3,6 +3,6 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "check": "bun test"
+    "check": "bunx tsc --noEmit"
   }
 }

package/template/src/index.ts

@@ -0,0 +1,2 @@
+// The project starts here. Its acceptance lines say what it becomes; `bun run check` typechecks what exists.
+export {};

package/template/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "compilerOptions": { "strict": true, "noEmit": true, "target": "ESNext", "module": "ESNext", "moduleResolution": "bundler", "skipLibCheck": true },
+  "include": ["src/**/*.ts"]
+}

package/template/.github/workflows/ci.yml

@@ -1,18 +0,0 @@
-name: CI
-# Every change lands from a branch (agent/** the agent's, land/** a maintainer's): the push checks the head
-# commit, which is what branch protection and auto-merge require.
-on:
-  push:
-    branches: [main, 'agent/**', 'land/**']
-  workflow_dispatch:
-permissions:
-  contents: read
-jobs:
-  ci:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
-      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
-        with:
-          bun-version: 1.3.10
-      - run: bun run check

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

@@ -1,94 +0,0 @@
-#!/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>] [--stack <name>]
-//                               [--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   <stack>-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');
-// The stack's name on a Docker host shared with others (the containers and volumes carry it); `oa` alone otherwise.
-const stack = arg('--stack') ?? 'oa';
-const HOME_VOL = `${stack}-home`; const REPO_VOL = `${stack}-repo`;
-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 [HOME_VOL, REPO_VOL]) run([...docker, 'volume', 'rm', '-f', v], { quiet: true, check: false });
-if (have(HOME_VOL) && have(REPO_VOL)) say(`volumes: ${HOME_VOL} and ${REPO_VOL} 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 [HOME_VOL, REPO_VOL]) 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', `${HOME_VOL}:/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: ${HOME_VOL} 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', `${REPO_VOL}:/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: ${REPO_VOL} 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: ${stack === 'oa' ? '' : `STACK=${stack} `}AGENT_SECRETS=${secrets} ${docker.join(' ')} compose${stack === 'oa' ? '' : ` -p ${stack}`} -f container/compose.yml up -d --build`);

package/template/container/Dockerfile.reporter

@@ -1,10 +0,0 @@
-# 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

@@ -1,5 +0,0 @@
-# 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"]

package/template/container/key-valve.ts

@@ -1,73 +0,0 @@
-#!/usr/bin/env bun
-// The key valve: the project's key lives here and nowhere the agent or the reporter can read. Both point
-// at this process (OPEN_AUTONOMY_BASE_URL=http://valve:8787/v1, any dummy key) and it forwards to the
-// platform with the real bearer. Only the model routes and the narration route pass; key management and
-// admin routes never do, so a rotated key is never a key the agent could read.
-//
-//   AGENT_ENV_FILE=/secrets/agent.env bun key-valve.ts [--port 8787]
-//   (a KEY=value file, re-read when it changes: a rotated key is picked up without a restart)
-import { existsSync, readFileSync, statSync } from 'node:fs';
-
-const envFile = process.env.AGENT_ENV_FILE;
-let cached: { at: number; env: Record<string, string> } = { at: 0, env: {} };
-function keyEnv(): Record<string, string> {
-  if (process.env.OPEN_AUTONOMY_KEY) return { OPEN_AUTONOMY_KEY: process.env.OPEN_AUTONOMY_KEY, OPEN_AUTONOMY_BASE_URL: process.env.OPEN_AUTONOMY_BASE_URL ?? '' };
-  if (!envFile || !existsSync(envFile)) return {};
-  const at = statSync(envFile).mtimeMs;
-  if (at !== cached.at) {
-    const env: Record<string, string> = {};
-    for (const line of readFileSync(envFile, 'utf8').split('\n')) { const m = /^([A-Z_]+)=(.*)$/.exec(line.trim()); if (m) env[m[1]] = m[2]; }
-    cached = { at, env };
-    announce(env.OPEN_AUTONOMY_KEY);
-  }
-  return cached.env;
-}
-// The key says when it expires (its claims are readable; only the signature is not). Announced whenever the
-// file changes, warned inside fourteen days, and answered on /healthz so the reporter can log it too.
-function expiry(token: string | undefined): { kid: string; account: string; exp: string; days: number } | undefined {
-  try {
-    const claims = JSON.parse(Buffer.from((token ?? '').split('.')[0], 'base64url').toString('utf8')) as { kid?: string; account?: string; exp?: string };
-    if (!claims.exp) return undefined;
-    return { kid: claims.kid ?? '?', account: claims.account ?? '?', exp: claims.exp, days: Math.floor((Date.parse(claims.exp) - Date.now()) / 86_400_000) };
-  } catch { return undefined; }
-}
-const status = (): string => { const e = expiry(key()); return e ? `key ${e.kid} for ${e.account} expires ${e.exp} (${e.days} day${e.days === 1 ? '' : 's'})${e.days < 14 ? ' — rotate it: bun .open-autonomy/mint-key.ts --rotate' : ''}` : 'no key yet'; };
-function announce(token: string | undefined): void {
-  const e = expiry(token);
-  console.log(`key-valve: ${e ? status() : 'no readable key in the key file'}`);
-  if (e && e.days < 14) console.warn(`key-valve: WARNING the key expires in ${e.days} day${e.days === 1 ? '' : 's'}`);
-}
-const base = (): string => (keyEnv().OPEN_AUTONOMY_BASE_URL || 'https://open-autonomy.org/v1').replace(/\/$/, '');
-const key = (): string | undefined => keyEnv().OPEN_AUTONOMY_KEY;
-const portArg = process.argv.indexOf('--port');
-const port = Number((portArg >= 0 ? process.argv[portArg + 1] : undefined) || process.env.PORT || 8787);
-// The model routes, the narration routes (the stream and the roadmap), and the two other rails (a card, a partner charge): the platform
-// bounds each rail by the owner's config, and every settlement lands on the public audit trail.
-const FORWARDED = new Set(['/v1/chat/completions', '/v1/messages', '/v1/responses', '/v1/models', '/v1/agent/events', '/v1/agent/roadmap', '/v1/rails/card', '/v1/rails/partner']);
-// Public reads the reporter needs to resume where the platform is (its own account's sessions).
-const isPublicRead = (path: string, method: string) => method === 'GET' && /^\/v1\/accounts\/[^/]+\/(sessions|items)(\/|$)/.test(path);
-
-Bun.serve({
-  hostname: '0.0.0.0',
-  port,
-  idleTimeout: 255,
-  async fetch(req) {
-    const url = new URL(req.url);
-    if (url.pathname === '/healthz') return new Response(key() ? `ok · ${status()}` : 'no key yet');
-    if (!FORWARDED.has(url.pathname) && !isPublicRead(url.pathname, req.method)) return Response.json({ error: { code: 'not_forwarded', message: 'the valve forwards the model routes, the narration route, the rails and public reads of this account only' } }, { status: 403 });
-    const bearer = key();
-    if (!bearer) return Response.json({ error: { code: 'no_key', message: 'the valve has no key yet' } }, { status: 503 });
-    // A clean request: the body buffered (one honest Content-Length), only the headers that carry meaning.
-    const headers = new Headers();
-    for (const h of ['content-type', 'accept', 'anthropic-version', 'anthropic-beta', 'last-event-id']) { const v = req.headers.get(h); if (v) headers.set(h, v); }
-    headers.set('authorization', `Bearer ${bearer}`);
-    headers.set('user-agent', 'open-autonomy-key-valve');
-    const body = req.method === 'GET' || req.method === 'HEAD' ? undefined : await req.arrayBuffer();
-    const upstream = await fetch(`${base()}${url.pathname.replace(/^\/v1/, '')}${url.search}`, { method: req.method, headers, body });
-    const out = new Headers(upstream.headers);
-    out.delete('content-encoding');
-    out.delete('content-length');
-    return new Response(upstream.body, { status: upstream.status, headers: out });
-  },
-});
-console.log(`key-valve: forwarding ${[...FORWARDED].join(', ')} → ${base()} on :${port}`);

package/template/test/project.test.ts

@@ -1,7 +0,0 @@
-import { expect, test } from 'bun:test';
-import { readFileSync } from 'node:fs';
-
-// The project's own check starts here. A test proves an acceptance line or guards a bug that happened.
-test('the repository names itself', () => {
-  expect(readFileSync(new URL('../README.md', import.meta.url), 'utf8').startsWith('# __PROJECT__')).toBe(true);
-});