create-open-autonomy 2.3.0 → 2.3.2

package/README.md

@@ -68,6 +68,13 @@ and settled cent per item, live while a session runs.
 balance for a bounded amount at the owner's merchant categories, and a partner service's metered charge
 for a listed partner within a bound. Both leave records on the public audit trail naming the rail.
 
+## The world
+
+A project that talks to a vendor verifies against twins, never the vendor: `bun add -d @volter/twin-world @volter/twin-<vendor>`,
+a `world/world.json` naming them, `bunx volter-world up world/world.json`. The develop skill drives the running
+system in that world, one action at a time (this repository's own `world/` is the shape). Nothing an agent does
+reaches a real API.
+
 ## 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 the start script loads with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-open-autonomy",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "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": {

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.3.0' } as const;
+export const KIT = { name: 'hermes', version: '2.3.2' } as const;
 export const KIT_FILE = '.open-autonomy/kit.json';
 const TEMPLATE = resolve(import.meta.dir, '..', 'template');
 

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

@@ -4,7 +4,7 @@
 //   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>]
+//   bun .open-autonomy/start.ts [--home <dir>] [--secrets <dir>] [--project <dir>] [--origin <url>] [--as <user>] [--valve <port>]
 //
 // The processes, in order:
 //   ssh-agent   holds <secrets>/deploy_key, its socket at <home>/ssh-agent.sock; the gateway pushes through it
@@ -13,7 +13,8 @@
 //   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`
+//               treasurer's, the only one that pays); --valve moves both (the second is the next port) for a second
+//               agent on one host — the home's .env names them (OPEN_AUTONOMY_BASE_URL, OPEN_AUTONOMY_PAY_URL) 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.
@@ -28,6 +29,9 @@ const home = resolve(arg('--home') ?? process.env.AGENT_HOME ?? resolve(homedir(
 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 valvePort = Number(arg('--valve') ?? process.env.VALVE_PORT ?? 8787);
+const baseUrl = `http://127.0.0.1:${valvePort}/v1`;
+const payUrl = `http://127.0.0.1:${valvePort + 1}/v1`;
 const say = (m: string) => console.log(`start: ${m}`);
 const sock = resolve(home, 'ssh-agent.sock');
 
@@ -75,20 +79,20 @@ if (!existsSync(resolve(project, '.git'))) {
 const committed = resolve(project, 'hermes');
 // force: with a filter, Bun's cpSync leaves an existing file alone unless told to overwrite.
 if (existsSync(committed)) cpSync(committed, home, { recursive: true, force: true, filter: (src) => basename(src) !== '.env' });
+// The home's .env is the home's own, except the valve's three lines, which are this start's truth on every start.
 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'];
-  // What the environment says about the agent's channels comes along: Discord's, and GitHub's for a community desk.
-  for (const k of Object.keys(process.env).sort()) if (/^(DISCORD_|GITHUB_TOKEN$|GITHUB_API_URL$)/.test(k) && process.env[k]) lines.push(`${k}=${process.env[k]}`);
-  writeFileSync(envFile, `${lines.join('\n')}\n`);
-}
+const kept = existsSync(envFile) ? readFileSync(envFile, 'utf8').split('\n').filter((l) => l.trim() && !/^OPEN_AUTONOMY_(BASE_URL|PAY_URL|KEY)=/.test(l)) : [];
+const lines = [`OPEN_AUTONOMY_BASE_URL=${baseUrl}`, `OPEN_AUTONOMY_PAY_URL=${payUrl}`, 'OPEN_AUTONOMY_KEY=valve', ...kept];
+// On the first start, what the environment says about the agent's channels comes along: Discord's, and GitHub's for a community desk.
+if (!existsSync(envFile)) for (const k of Object.keys(process.env).sort()) if (/^(DISCORD_|GITHUB_TOKEN$|GITHUB_API_URL$)/.test(k) && 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 (existsSync(resolve(secrets, 'agent.env'))) keys.push('--key', `${resolve(secrets, 'agent.env')}:${valvePort}`);
+if (existsSync(resolve(secrets, 'treasurer.env'))) keys.push('--key', `${resolve(secrets, 'treasurer.env')}:${valvePort + 1}`);
 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.
@@ -101,8 +105,8 @@ 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('reporter', ['bun', resolve(import.meta.dir, 'reporter.ts'), '--config', resolve(project, '.open-autonomy', 'config.yaml')], { asAgent: true, env: { ...env, OPEN_AUTONOMY_BASE_URL: baseUrl } });
 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' : ''}`);
+say(`gateway up in ${project} as ${user?.name ?? userInfo().username}, home ${home}; the valve on :${valvePort}${keys.length > 2 ? ` and :${valvePort + 1}` : ''}`);
 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

@@ -2,7 +2,7 @@
 
 - **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, 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.
+- **Verify.** State here where the project is verified: its check, and any local or twinned surface. A project that talks to a vendor keeps a world in `world/` — the twins are npm packages (`@volter/twin-world` and one `@volter/twin-<vendor>` per vendor, dev dependencies), a `world/world.json` names them, `bunx volter-world up world/world.json` brings them up — and you drive the running system in it, one action at a time; never a real API. 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.

package/template/container/README.md

@@ -1,7 +1,7 @@
 # Running the agent
 
 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
+developer's on :8787, the treasurer's on :8788 — `--valve <port>` moves both — 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.

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

@@ -4,7 +4,7 @@ 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://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>"}'`.
+   `curl -sf -X POST $OPEN_AUTONOMY_PAY_URL/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 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).

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

@@ -6,7 +6,7 @@
 model:
   default: zai/glm-5.3-flash
   provider: custom
-  base_url: http://127.0.0.1:8788/v1 # the valve's second port: the treasurer's key, the only one that pays
+  base_url: ${OPEN_AUTONOMY_PAY_URL} # the valve's second port (the start script writes it into the home's .env): the treasurer's key, the only one that pays
   api_key: valve
   api_mode: chat_completions