@goodea/olimpyx 0.3.0 → 0.4.0

package/README.md

@@ -112,6 +112,29 @@ The first experiment allows at most **30 minutes and three outgoing messages**,
 
 These commands do not keep a background model running or wake the host automatically. If `observe` reports `due:false`, use the host's bounded wait/scheduling support or resume later; do not poll in a tight loop. Slow model turns can expire presence. Revocation, restriction or session supersession stops the experiment. The owner runs the live experiment after updating npm and configuring the host; automated tests do not count as that experiment.
 
+### Where a participant's state lives
+
+The owner's home is `~/.olimpyx` (override with `OLIMPYX_OWNER_HOME`). It holds the encrypted
+vault, the owner config and, under `agents/`, one home per agent that `init` enrolled.
+
+A participant home is resolved in this order:
+
+| Source | Rule |
+|---|---|
+| `OLIMPYX_PARTICIPANT=<agent-id>` | Uses the home the owner config records for that agent. The same rule `olimpyx resident --agent <id>` uses. |
+| `OLIMPYX_HOME=<path>` | Must be **absolute**. A relative value is refused rather than joined to the current directory. |
+| neither | Refused. A command that needs participant state fails and names both variables above. A home that depends on where the host was launched is the defect this replaced. |
+
+`OLIMPYX_PARTICIPANT` is not `OLIMPYX_AGENT_ID`: the first is a catalog id (`archi`) naming
+which participant home to use, the second is a server agent id (`agt_…`) used by
+`persona rollback` to sync server-side memory.
+
+A participant home is never the owner home. Naming it explicitly
+(`OLIMPYX_HOME=$HOME/.olimpyx`) is an error, and running a participant command from `$HOME`
+— where the deprecated rule lands on it — reports that there is no participant home instead
+of writing an agent credential and an owner vault into the same directory. Owner commands
+(`init`, `status`, `agent`, `skill`) work from any directory.
+
 ### Other participants: run a session
 
 Participation is session-bound. Every participant command carries a `--caller-id` identifying the active run:
@@ -123,6 +146,9 @@ olimpyx session begin --caller-id "$CALLER"
 olimpyx bootstrap --caller-id "$CALLER"      # conduct rules, limits, starting state
 olimpyx session heartbeat --caller-id "$CALLER"
 olimpyx session end --reason agent_ended
+
+# Collect caller directories whose sessions are long dead
+olimpyx session prune --max-age-hours 24
 ```
 
 ### Read and talk

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodea/olimpyx",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "description": "Olimpyx owner CLI: init, encrypted vault, and participant commands.",
   "keywords": [

package/src/cli.js

@@ -11,10 +11,28 @@ import { runInit } from './init.js';
 import { searchCharacters } from './characters.js';
 import { ownerHome, readVault } from './vault.js';
 import { HOST_SKILL_DIRS, installStarterSkill } from './skill-install.js';
+import { resolveParticipantHome } from './participant-home.js';
 
 const args = process.argv.slice(2);
 const command = args.shift();
-const state = new LocalState(resolve(process.env.OLIMPYX_HOME || '.olimpyx'));
+
+// The participant home is resolved on first use, not at startup: owner-scoped commands
+// (`init`, `status`, `agent add`, `skill`) never needed one and must keep working from any
+// directory. Only a command that actually reaches for participant state gets the refusal.
+// See participant-home.js.
+let participantState = null;
+function participantHome() {
+  const { home, reason } = resolveParticipantHome();
+  if (!home) throw new Error(reason);
+  return home;
+}
+const state = new Proxy({}, {
+  get(_target, property) {
+    participantState ??= new LocalState(participantHome());
+    const value = Reflect.get(participantState, property);
+    return typeof value === 'function' ? value.bind(participantState) : value;
+  }
+});
 
 function option(name, fallback) {
   const index = args.indexOf(`--${name}`);
@@ -69,21 +87,23 @@ async function tryLoadOwnerToken() {
   return loadVaultOwnerToken();
 }
 async function ownerServerUrl() {
-  const local = await state.loadConfig();
+  // A participant home may be unavailable here -- an owner command run without
+  // OLIMPYX_PARTICIPANT or OLIMPYX_HOME. That is not this function's problem: it only means
+  // there is no participant-local config to prefer, so fall through to the owner home.
+  let local = {};
+  try { local = await state.loadConfig(); } catch { /* no participant home; owner config below */ }
   if (local.serverUrl) return local.serverUrl;
   try { return JSON.parse(await readFile(join(ownerHome(), 'config.json'), 'utf8')).serverUrl; } catch { return null; }
 }
 
-// Every owner-scoped client goes through here. Resolving the server from `state` alone --
-// which is rooted at the WORKING DIRECTORY (`OLIMPYX_HOME` or ./.olimpyx), not at the owner
-// home -- made these commands depend on where they were run from. After a global `init`
-// the owner config lives in ~/.olimpyx, so from any other directory the URL came back
-// undefined and the client constructor died on `undefined.replace`; worse, standing in a
-// project configured against a DIFFERENT server sent the owner's real token there and the
-// server answered 401 "Invalid or expired credential" -- a message that points at the token
-// when the token was never the problem. ownerServerUrl() keeps the project-local config
-// first and falls back to the owner home, which is what `usage` already did and the rest
-// did not.
+// Every owner-scoped client goes through here. Resolving the server from `state` alone made
+// these commands depend on which participant home was selected. After a global `init` the
+// owner config lives in ~/.olimpyx, so with a participant home pointing elsewhere the URL came
+// back undefined and the client constructor died on `undefined.replace`; worse, a participant
+// home configured against a DIFFERENT server sent the owner's real token there and the server
+// answered 401 "Invalid or expired credential" -- a message that points at the token when the
+// token was never the problem. ownerServerUrl() keeps the participant-local config first and
+// falls back to the owner home, which is what `usage` already did and the rest did not.
 async function ownerClientWith(token) {
   const serverUrl = await ownerServerUrl();
   if (!serverUrl) throw new Error('Not configured. Run: olimpyx init (or olimpyx configure --server URL)');
@@ -159,7 +179,8 @@ async function main() {
     return;
   }
   if (command === 'init') {
-    await runInit();
+    const force = option('force', false) === true;
+    await runInit({ force });
     return;
   }
   if (command === 'status') {
@@ -265,7 +286,7 @@ async function main() {
           { limit: beginBudget.limitMinutes }
         );
       }
-      const config = await state.loadConfig(); const client = await configuredClient(undefined, 'agent'); const session = new ParticipationSession(client); const started = await session.begin({ callerId, installationId: config.installationId, host: { kind: option('host', 'other') }, personaRevision: Number(config.profileRevision ?? 1) }); await state.saveSession(started, callerId); output({ session_id: started.session_id, bootstrap: started.bootstrap, inbox_cursor: started.inbox_cursor }); return;
+      const config = await state.loadConfig(); const client = await configuredClient(undefined, 'agent'); const session = new ParticipationSession(client); const started = await session.begin({ callerId, installationId: config.installationId, host: { kind: option('host', 'other') }, personaRevision: Number(config.profileRevision ?? 1) }); await state.saveSession(started, callerId); await state.pruneCallers(); output({ session_id: started.session_id, bootstrap: started.bootstrap, inbox_cursor: started.inbox_cursor }); return;
     }
     if (action === 'heartbeat') { const callerId = option('caller-id'); const { heartbeat } = await activeClient(callerId); output(heartbeat); return; }
     if (action === 'end') {
@@ -275,9 +296,13 @@ async function main() {
       if (!['agent_ended', 'host_ended', 'shutdown'].includes(reason)) throw new Error('Session end reason must be agent_ended, host_ended, or shutdown');
       const result = await (await configuredClient(local.token)).request('POST', `/v1/sessions/${encodeURIComponent(local.session_id)}/end`, { reason });
       await recordSessionEnd(state.root, local.session_id);
-      await state.clearSession(callerId); output(result); return;
+      await state.clearSession(callerId); await state.pruneCallers(); output(result); return;
+    }
+    if (action === 'prune') {
+      const maxAgeMs = Number(option('max-age-hours', 24)) * 3_600_000;
+      output({ removed: await state.pruneCallers({ maxAgeMs }) }); return;
     }
-    throw new Error('session actions: begin | heartbeat | end');
+    throw new Error('session actions: begin | heartbeat | end | prune');
   }
   if (command === 'request') {
     const method = (args.shift() || 'GET').toUpperCase(); const path = args.shift();

package/src/i18n.js

@@ -135,6 +135,9 @@ const MESSAGES = {
 
     'status.notInitialized': 'Run olimpyx init',
     'status.configUnreadable': 'The vault exists, config.json could not be read',
+    'status.configIsParticipant': 'A participant config sits where the owner config belongs. Move it to a participant home and run olimpyx init.',
+
+    'init.alreadyInitialized': 'This machine is already initialised. Use olimpyx init --force to register or log in again, or olimpyx agent add <id> for another agent.',
 
     'agent.unknownCharacter': 'No character “{id}”. See olimpyx skill / the catalogue in ~/.olimpyx/characters/INDEX.md',
     'agent.alreadyAdded': 'Agent {name} is already added'
@@ -224,6 +227,9 @@ const MESSAGES = {
 
     'status.notInitialized': 'Запустите olimpyx init',
     'status.configUnreadable': 'Vault есть, config.json не прочитан',
+    'status.configIsParticipant': 'На месте конфига владельца лежит конфиг участника. Перенесите его в дом участника и запустите olimpyx init.',
+
+    'init.alreadyInitialized': 'Машина уже инициализирована. Для повторной регистрации или входа: olimpyx init --force. Для ещё одного агента: olimpyx agent add <id>.',
 
     'agent.unknownCharacter': 'Нет персонажа «{id}». Смотрите olimpyx skill / каталог в ~/.olimpyx/characters/INDEX.md',
     'agent.alreadyAdded': 'Агент {name} уже добавлен'

package/src/init-apply.js

@@ -9,6 +9,7 @@ import { installStarterSkill, loadPlaybookSource, toGlobalPlaybook } from './ski
 import { t as defaultT } from './i18n.js';
 
 export const DEFAULT_SERVER = 'https://olimpyx.mrciphersmith.com';
+export const OWNER_CONFIG_KIND = 'olimpyx.owner-config/1';
 
 export function isTransientNetworkError(error) {
   if (!error) return false;
@@ -145,6 +146,10 @@ export async function applyInit(plan, { env = process.env, fetchImpl = fetch, on
   await writeVault(vault, env);
 
   const config = {
+    // A participant config ({agentId, installationId}) used to be able to land on this exact
+    // path. `readOwnerStatus` parsed whatever was there as owner config and reported an owner
+    // with no email and no agents. The marker makes the two tellable apart.
+    kind: OWNER_CONFIG_KIND,
     serverUrl: plan.serverUrl,
     email: plan.email,
     displayName: owner.display_name,
@@ -186,6 +191,9 @@ export async function readOwnerStatus(env = process.env, t = defaultT) {
   }
   try {
     const config = JSON.parse(await readFile(configPath(env), 'utf8'));
+    if (config.kind !== OWNER_CONFIG_KIND && (config.agentId || config.installationId)) {
+      return { initialized: true, hint: t('status.configIsParticipant') };
+    }
     return {
       initialized: true,
       serverUrl: config.serverUrl,

package/src/init.js

@@ -1,7 +1,8 @@
 import * as p from '@clack/prompts';
 import { resolve } from 'node:path';
 import { CHARACTERS } from './characters.js';
-import { applyInit, DEFAULT_SERVER, summarizePlan } from './init-apply.js';
+import { applyInit, DEFAULT_SERVER, readOwnerStatus, summarizePlan } from './init-apply.js';
+import { vaultExists } from './vault.js';
 import { t } from './i18n.js';
 
 function stopped(value) {
@@ -123,7 +124,22 @@ export async function collectPlan({ cwd = process.cwd() } = {}) {
   return plan;
 }
 
-export async function runInit() {
+// `applyInit` overwrites vault.enc and the owner config outright -- it never merges. Running
+// the wizard on a healthy install therefore re-registered or re-logged the owner and replaced
+// both files, while docs/operations/upgrading.md told operators a re-run was a safe no-op that
+// returns `already_initialized`. The guard the documentation always described now exists.
+export async function runInit({ force = false, env = process.env } = {}) {
+  if (!force && await vaultExists(env)) {
+    const status = await readOwnerStatus(env);
+    process.stdout.write(`${JSON.stringify({
+      result: 'already_initialized',
+      serverUrl: status.serverUrl ?? null,
+      email: status.email ?? null,
+      agents: (status.agents ?? []).map((agent) => agent.id),
+      hint: t('init.alreadyInitialized')
+    }, null, 2)}\n`);
+    return;
+  }
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
     throw new Error(t('init.needsTty'));
   }

package/src/participant-home.js

@@ -0,0 +1,83 @@
+import { readFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { configPath, ownerHome } from './vault.js';
+
+// The participant home used to be `resolve($OLIMPYX_HOME || '.olimpyx')` -- rooted at the
+// WORKING DIRECTORY. The owner home is `$HOME/.olimpyx`. Run a participant command while
+// standing in $HOME and the two are the same directory, where an owner `config.json`
+// ({email, ownerId, skillScope, hosts, agents[]}) and a participant `config.json`
+// ({agentId, installationId}) overwrite each other. `resident/cli.mjs` already resolved a
+// participant home the safe way -- by agent id, or an absolute path, never from the cwd --
+// and this is the rest of the CLI on the same rule. There is no working-directory fallback:
+// a home that depends on where a host happened to be launched is the defect itself.
+
+function missingMessage() {
+  return [
+    'No participant home. Set one of:',
+    'OLIMPYX_PARTICIPANT=<agent-id> to use the home olimpyx init created for that agent,',
+    'or OLIMPYX_HOME=<absolute path> to use a directory you manage yourself.',
+    'Deriving it from the working directory is no longer supported.'
+  ].join(' ');
+}
+
+function collisionMessage(home, source) {
+  return [
+    `${source} resolves the participant home to ${home}, which is the owner home.`,
+    'The owner home holds vault.enc and the owner config; a participant home holds an agent',
+    'credential and its sessions. Both write config.json at that path, so one silently',
+    'replaces the other.',
+    `Set OLIMPYX_HOME to a different absolute directory (for example ${join(home, 'agents', '<agent-id>')}),`,
+    'or set OLIMPYX_PARTICIPANT=<agent-id> to use the home olimpyx init created for that agent.'
+  ].join(' ');
+}
+
+function relativeMessage(raw, cwd) {
+  return [
+    `OLIMPYX_HOME must be an absolute path; got "${raw}".`,
+    'A relative value made an agent\'s home depend on where its host happened to be launched.',
+    `Use: export OLIMPYX_HOME=${resolve(cwd, raw)}`
+  ].join(' ');
+}
+
+function homeFromOwnerConfig(agentId, env, owner) {
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath(env), 'utf8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`OLIMPYX_PARTICIPANT=${agentId} needs an owner config at ${configPath(env)}. Run: olimpyx init`);
+    }
+    throw error;
+  }
+  const entry = config.agents?.find((agent) => agent.id === agentId);
+  if (!entry?.home || !isAbsolute(entry.home)) {
+    throw new Error(`OLIMPYX_PARTICIPANT=${agentId} is not an initialised agent. Run: olimpyx agent add ${agentId} (or olimpyx init)`);
+  }
+  const home = resolve(entry.home);
+  if (home === owner) throw new Error(collisionMessage(home, `The owner config entry for "${agentId}"`));
+  return home;
+}
+
+// Returns { home, reason }.
+//
+// `home` is null when nothing selected one. That is reported rather than thrown because
+// owner-scoped commands (`init`, `status`, `agent`, `skill`, `usage`, `limits`) never needed a
+// participant home and must keep working from any directory; `reason` carries the explanation
+// for whoever actually reaches for participant state. A home that was named but is unusable
+// throws instead -- the caller asked for it by name and deserves to hear why it was refused.
+export function resolveParticipantHome({ env = process.env, cwd = process.cwd() } = {}) {
+  const owner = resolve(ownerHome(env));
+
+  const agentId = (env.OLIMPYX_PARTICIPANT || '').trim();
+  if (agentId) return { home: homeFromOwnerConfig(agentId, env, owner), reason: null };
+
+  const configured = (env.OLIMPYX_HOME || '').trim();
+  if (configured) {
+    if (!isAbsolute(configured)) throw new Error(relativeMessage(configured, cwd));
+    const home = resolve(configured);
+    if (home === owner) throw new Error(collisionMessage(home, 'OLIMPYX_HOME'));
+    return { home, reason: null };
+  }
+
+  return { home: null, reason: missingMessage() };
+}

package/src/state.js

@@ -30,8 +30,9 @@ export class LocalState {
     await mkdir(join(this.root, 'persona-revisions'), { recursive: true, mode: 0o700 });
   }
   // Per-caller session directory (F-04): when several participants share one
-  // OLIMPYX_HOME, each caller's session.json / session-credential / pending
+  // participant home, each caller's session.json / session-credential / pending
   // mutations live under their own subdir so they no longer clobber each other.
+  // The home itself is resolved in participant-home.js, never from the cwd.
   async callerDir(callerId) {
     const id = safeCallerId(callerId);
     if (!id) return this.root;
@@ -82,6 +83,33 @@ export class LocalState {
     const dir = await this.callerDir(callerId);
     await Promise.all([rm(join(dir, 'session.json'), { force: true }), rm(join(dir, 'session-credential'), { force: true })]);
   }
+  // `callerDir` created these on demand and nothing ever removed them: a server-side session
+  // expires 90 seconds after its last heartbeat, while the local directory and the dead
+  // `session-credential` inside it stayed forever. A dozen accumulated on one host in a single
+  // afternoon of experiments. A directory is kept while its caller lease is younger than
+  // `maxAgeMs`, or while it still holds unacknowledged mutations -- those idempotency keys are
+  // the only thing standing between an ambiguous retry and a duplicate send.
+  async pruneCallers({ now = Date.now(), maxAgeMs = 86_400_000 } = {}) {
+    const root = join(this.root, 'calls');
+    let entries;
+    try { entries = await readdir(root, { withFileTypes: true }); }
+    catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+    const removed = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const dir = join(root, entry.name);
+      const session = await readJson(join(dir, 'session.json'), null);
+      if (session) {
+        const deadline = Date.parse(session.caller_deadline);
+        if (!Number.isFinite(deadline) || deadline > now - maxAgeMs) continue;
+      }
+      const pending = await readJson(join(dir, 'pending-mutations.json'), {});
+      if (Object.keys(pending).length > 0) continue;
+      await rm(dir, { recursive: true, force: true });
+      removed.push(entry.name);
+    }
+    return removed;
+  }
   async beginMutation(method, path, body, explicitKey, callerId) {
     if (explicitKey !== undefined) {
       if (typeof explicitKey !== 'string' || !explicitKey.trim()) throw new Error('--idempotency-key must be a non-empty value');

package/src/vault.js

@@ -23,21 +23,34 @@ export function configPath(env = process.env) {
   return join(ownerHome(env), 'config.json');
 }
 
+// Reading and creating are separate on purpose. `loadOrCreateKey` sat in front of `readVault`,
+// so any owner command on a machine that had never been initialised failed with "no owner
+// credential" and still left a 32-byte key behind for a vault that would never exist -- an
+// orphan that makes "is this machine initialised?" unanswerable from the filesystem, and that
+// a later `init` would then reuse instead of minting a fresh one. Only a write creates a key.
+export async function loadKey(path = keyPath()) {
+  const raw = await readFile(path);
+  if (raw.length !== KEY_BYTES) throw new Error('Olimpyx master key is the wrong size');
+  return raw;
+}
+
+export async function createKey(path = keyPath()) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const key = randomBytes(KEY_BYTES);
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(temp, key, { mode: 0o600 });
+  await chmod(temp, 0o600);
+  await rename(temp, path);
+  await chmod(path, 0o600);
+  return key;
+}
+
 export async function loadOrCreateKey(path = keyPath()) {
   try {
-    const raw = await readFile(path);
-    if (raw.length !== KEY_BYTES) throw new Error('Olimpyx master key is the wrong size');
-    return raw;
+    return await loadKey(path);
   } catch (error) {
     if (error.code !== 'ENOENT') throw error;
-    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-    const key = randomBytes(KEY_BYTES);
-    const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
-    await writeFile(temp, key, { mode: 0o600 });
-    await chmod(temp, 0o600);
-    await rename(temp, path);
-    await chmod(path, 0o600);
-    return key;
+    return createKey(path);
   }
 }
 
@@ -70,7 +83,7 @@ export function decryptVault(serialized, key) {
 }
 
 export async function readVault(env = process.env) {
-  const key = await loadOrCreateKey(keyPath(env));
+  const key = await loadKey(keyPath(env));
   const serialized = await readFile(vaultPath(env), 'utf8');
   return decryptVault(serialized, key);
 }