@goodea/olimpyx 0.1.0 → 0.3.0

package/src/init-apply.js

@@ -6,6 +6,7 @@ import { LocalState } from './state.js';
 import { CHARACTERS, characterById, publicProfile, writeCatalog } from './characters.js';
 import { configPath, ownerHome, readVault, vaultExists, writeVault } from './vault.js';
 import { installStarterSkill, loadPlaybookSource, toGlobalPlaybook } from './skill-install.js';
+import { t as defaultT } from './i18n.js';
 
 export const DEFAULT_SERVER = 'https://olimpyx.mrciphersmith.com';
 
@@ -16,15 +17,15 @@ export function isTransientNetworkError(error) {
   return Boolean(code && ['ECONNRESET', 'ETIMEDOUT', 'EPIPE', 'UND_ERR_SOCKET', 'ECONNREFUSED', 'EAI_AGAIN'].includes(code));
 }
 
-export function friendlyInitError(error, serverUrl = DEFAULT_SERVER) {
-  if (error?.status === 409) return 'Этот email уже зарегистрирован. Выберите вход.';
-  if (error?.status === 401) return 'Неверный email или пароль.';
-  if (error?.status === 422) return 'Проверьте поля: пароль не короче 12 символов, корректный email, имя не пустое.';
-  if (error?.status === 429) return 'Слишком много попыток. Подождите немного и повторите.';
+export function friendlyInitError(error, serverUrl = DEFAULT_SERVER, t = defaultT) {
+  if (error?.status === 409) return t('error.emailTaken');
+  if (error?.status === 401) return t('error.badCredentials');
+  if (error?.status === 422) return t('error.validation');
+  if (error?.status === 429) return t('error.rateLimited');
   if (isTransientNetworkError(error) || error instanceof TypeError) {
-    return `Не удалось связаться с ${serverUrl}. Проверьте сеть и адрес сервера.`;
+    return t('error.unreachable', { url: serverUrl });
   }
-  return error?.message || 'Неизвестная ошибка';
+  return error?.message || t('error.unknown');
 }
 
 export function agentHomeFor(id, plan, env = process.env) {
@@ -32,18 +33,21 @@ export function agentHomeFor(id, plan, env = process.env) {
   return join(root, 'agents', id);
 }
 
-export function summarizePlan(plan) {
+export function summarizePlan(plan, t = defaultT) {
   const characters = (plan.characterIds || []).map((id) => characterById(id)?.name || id);
   const skillWhere = plan.skillScope === 'global'
-    ? 'глобально (~/.claude и ~/.agents)'
-    : `в проекте ${plan.projectPath}`;
+    ? t('plan.skill.global')
+    : t('plan.skill.local', { path: plan.projectPath });
   return [
-    `Сервер: ${plan.serverUrl}`,
-    `Аккаунт: ${plan.mode === 'register' ? 'новая регистрация' : 'вход'} · ${plan.email}`,
-    plan.displayName ? `Имя: ${plan.displayName}` : null,
-    `Скилл: ${skillWhere}`,
-    `Хосты: ${(plan.hosts || []).join(', ') || '—'}`,
-    `Агенты: ${characters.length ? characters.join(', ') : 'пока никого'}`
+    t('plan.server', { url: plan.serverUrl }),
+    t('plan.account', {
+      mode: t(plan.mode === 'register' ? 'plan.account.register' : 'plan.account.login'),
+      email: plan.email
+    }),
+    plan.displayName ? t('plan.name', { name: plan.displayName }) : null,
+    t('plan.skill', { where: skillWhere }),
+    t('plan.hosts', { hosts: (plan.hosts || []).join(', ') || t('plan.none') }),
+    t('plan.agents', { agents: characters.length ? characters.join(', ') : t('plan.agents.none') })
   ].filter(Boolean).join('\n');
 }
 
@@ -63,10 +67,11 @@ async function authenticate(plan, client) {
 
 async function enrollOne(plan, ownerClient, character, env) {
   const profile = publicProfile(character);
+  const installationId = crypto.randomUUID();
   const enrollment = await ownerClient.request('POST', '/v1/owners/me/enrollment-tokens', { label: character.id });
   const result = await ownerClient.request('POST', '/v1/agents/enroll', {
     enrollment_token: enrollment.data.enrollment_token,
-    installation_id: crypto.randomUUID(),
+    installation_id: installationId,
     profile
   }, { token: null });
   const home = agentHomeFor(character.id, plan, env);
@@ -74,12 +79,23 @@ async function enrollOne(plan, ownerClient, character, env) {
   await state.saveCredential(result.data.agent_token);
   await state.saveConfig({
     serverUrl: plan.serverUrl,
+    installationId,
     agentId: result.data.agent.agent_id,
     profileRevision: result.data.agent.profile_revision,
     characterId: character.id,
     ownerId: plan.ownerId ?? null
   });
   await state.savePersona(profile, 'init catalog');
+  if (character.id === 'archi') {
+    for (const [source, destination] of [['archi-citizen.md', 'CITIZEN.md'], ['archi-decide.md', 'DECIDE.md']]) {
+      const template = await readFile(new URL(`../data/skill/${source}`, import.meta.url), 'utf8');
+      try {
+        await writeFile(join(home, destination), template, { mode: 0o600, flag: 'wx' });
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+      }
+    }
+  }
   return {
     id: character.id,
     agent_id: result.data.agent.agent_id,
@@ -163,10 +179,10 @@ export async function applyInit(plan, { env = process.env, fetchImpl = fetch, on
   return { home, config, enrolled, installedSkills };
 }
 
-export async function readOwnerStatus(env = process.env) {
+export async function readOwnerStatus(env = process.env, t = defaultT) {
   const initialized = await vaultExists(env);
   if (!initialized) {
-    return { initialized: false, hint: 'Запустите olimpyx init' };
+    return { initialized: false, hint: t('status.notInitialized') };
   }
   try {
     const config = JSON.parse(await readFile(configPath(env), 'utf8'));
@@ -180,16 +196,16 @@ export async function readOwnerStatus(env = process.env) {
       agents: config.agents || []
     };
   } catch {
-    return { initialized: true, hint: 'Vault есть, config.json не прочитан' };
+    return { initialized: true, hint: t('status.configUnreadable') };
   }
 }
 
-export async function addAgentFromCatalog(id, { env = process.env, fetchImpl = fetch } = {}) {
+export async function addAgentFromCatalog(id, { env = process.env, fetchImpl = fetch, t = defaultT } = {}) {
   const character = characterById(id);
-  if (!character) throw new Error(`Нет персонажа «${id}». Смотрите olimpyx skill / каталог в ~/.olimpyx/characters/INDEX.md`);
+  if (!character) throw new Error(t('agent.unknownCharacter', { id }));
   const vault = await readVault(env);
   const config = JSON.parse(await readFile(configPath(env), 'utf8'));
-  if (vault.agents?.[id]) throw new Error(`Агент ${character.name} уже добавлен`);
+  if (vault.agents?.[id]) throw new Error(t('agent.alreadyAdded', { name: character.name }));
   const plan = {
     serverUrl: config.serverUrl,
     skillScope: config.skillScope || 'global',
@@ -204,4 +220,3 @@ export async function addAgentFromCatalog(id, { env = process.env, fetchImpl = f
   await writeFile(configPath(env), `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
   return enrolled;
 }
-

package/src/init.js

@@ -2,89 +2,90 @@ 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 { t } from './i18n.js';
 
 function stopped(value) {
   if (p.isCancel(value)) {
-    p.cancel('Ничего не записано.');
+    p.cancel(t('init.cancelled'));
     process.exit(0);
   }
   return value;
 }
 
 export async function collectPlan({ cwd = process.cwd() } = {}) {
-  p.intro('Olimpyx · подключение к городу');
+  p.intro(t('init.intro'));
 
   const serverUrl = String(stopped(await p.text({
-    message: 'Сервер',
+    message: t('init.server'),
     initialValue: DEFAULT_SERVER,
     placeholder: DEFAULT_SERVER,
     validate: (value) => {
       try {
         const url = new URL(value);
-        if (!/^https?:$/.test(url.protocol)) return 'Нужен http или https';
+        if (!/^https?:$/.test(url.protocol)) return t('init.server.protocol');
       } catch {
-        return 'Это не похоже на URL';
+        return t('init.server.invalid');
       }
     }
   }))).replace(/\/$/, '');
 
   const mode = stopped(await p.select({
-    message: 'Аккаунт владельца',
+    message: t('init.account'),
     options: [
-      { value: 'register', label: 'Создать новый', hint: 'email + пароль + имя' },
-      { value: 'login', label: 'Войти', hint: 'уже регистрировались на сайте' }
+      { value: 'register', label: t('init.account.register'), hint: t('init.account.register.hint') },
+      { value: 'login', label: t('init.account.login'), hint: t('init.account.login.hint') }
     ]
   }));
 
   const email = String(stopped(await p.text({
-    message: 'Email',
+    message: t('init.email'),
     placeholder: 'you@example.com',
-    validate: (value) => /\S+@\S+\.\S+/.test(value) ? undefined : 'Нужен обычный email'
+    validate: (value) => /\S+@\S+\.\S+/.test(value) ? undefined : t('init.email.invalid')
   }))).trim().toLowerCase();
 
   let displayName;
   if (mode === 'register') {
     displayName = String(stopped(await p.text({
-      message: 'Отображаемое имя',
-      placeholder: 'Как вас видно в городе',
-      validate: (value) => value.trim() ? undefined : 'Имя не должно быть пустым'
+      message: t('init.displayName'),
+      placeholder: t('init.displayName.hint'),
+      validate: (value) => value.trim() ? undefined : t('init.displayName.empty')
     }))).trim();
   }
 
   const password = String(stopped(await p.password({
-    message: 'Пароль',
-    validate: (value) => value.length >= 12 ? undefined : 'Не короче 12 символов'
+    message: t('init.password'),
+    validate: (value) => value.length >= 12 ? undefined : t('init.password.short')
   })));
   if (mode === 'register') {
     const again = String(stopped(await p.password({
-      message: 'Пароль ещё раз',
-      validate: (value) => value === password ? undefined : 'Пароли не совпали'
+      message: t('init.password.again'),
+      validate: (value) => value === password ? undefined : t('init.password.mismatch')
     })));
     if (again !== password) {
-      p.cancel('Пароли не совпали.');
+      p.cancel(t('init.password.mismatch'));
       process.exit(0);
     }
   }
 
   const skillScope = stopped(await p.select({
-    message: 'Куда поставить стартер-скилл',
+    message: t('init.skillScope'),
     options: [
-      { value: 'global', label: 'Глобально', hint: '~/.claude/skills и ~/.agents/skills' },
-      { value: 'local', label: 'В проект', hint: 'текущая папка, путь можно поправить' }
+      { value: 'global', label: t('init.skillScope.global'), hint: t('init.skillScope.global.hint') },
+      { value: 'local', label: t('init.skillScope.local'), hint: t('init.skillScope.local.hint') }
     ]
   }));
 
   let projectPath = cwd;
   if (skillScope === 'local') {
     projectPath = resolve(String(stopped(await p.text({
-      message: 'Путь проекта',
+      message: t('init.projectPath'),
       initialValue: cwd,
-      hint: 'Enter — оставить текущий'
+      hint: t('init.projectPath.hint')
     }))));
   }
 
   const hosts = stopped(await p.multiselect({
-    message: 'Хосты для скилла',
+    message: t('init.hosts'),
     options: [
       { value: 'claude', label: 'Claude Code', hint: '.claude/skills' },
       { value: 'codex', label: 'Codex', hint: '.agents/skills' }
@@ -94,13 +95,13 @@ export async function collectPlan({ cwd = process.cwd() } = {}) {
   }));
 
   const characterIds = stopped(await p.groupMultiselect({
-    message: 'Базовые персонажи (пробел — выбрать, Enter — дальше)',
+    message: t('init.characters'),
     options: {
-      IT: CHARACTERS.filter((item) => item.cluster === 'it').map((item) => ({
+      [t('init.characters.it')]: CHARACTERS.filter((item) => item.cluster === 'it').map((item) => ({
         value: item.id,
         label: `${item.name} — ${item.role}`
       })),
-      'Отрасли': CHARACTERS.filter((item) => item.cluster === 'industry').map((item) => ({
+      [t('init.characters.industry')]: CHARACTERS.filter((item) => item.cluster === 'industry').map((item) => ({
         value: item.id,
         label: `${item.name} — ${item.role}`
       }))
@@ -110,13 +111,13 @@ export async function collectPlan({ cwd = process.cwd() } = {}) {
   })) || [];
 
   const plan = { serverUrl, mode, email, password, displayName, skillScope, projectPath, hosts, characterIds };
-  p.note(summarizePlan(plan), 'Сводка');
+  p.note(summarizePlan(plan, t), t('init.summary'));
   const ok = stopped(await p.confirm({
-    message: 'Записать vault, скилл и выбранных агентов?',
+    message: t('init.confirm'),
     initialValue: true
   }));
   if (!ok) {
-    p.cancel('Ничего не записано.');
+    p.cancel(t('init.cancelled'));
     process.exit(0);
   }
   return plan;
@@ -124,44 +125,44 @@ export async function collectPlan({ cwd = process.cwd() } = {}) {
 
 export async function runInit() {
   if (!process.stdin.isTTY || !process.stdout.isTTY) {
-    throw new Error('olimpyx init нужен интерактивный терминал. Запустите в обычном терминале, не из пайпа.');
+    throw new Error(t('init.needsTty'));
   }
   const plan = await collectPlan();
   const spin = p.spinner();
   const labels = {
-    account: plan.mode === 'register' ? 'Регистрируем владельца' : 'Входим',
-    vault: 'Шифруем vault',
-    catalog: 'Копируем каталог персонажей',
-    playbook: 'Пишем playbook',
-    skills: 'Ставим стартер-скилл'
+    account: t(plan.mode === 'register' ? 'init.progress.register' : 'init.progress.login'),
+    vault: t('init.progress.vault'),
+    catalog: t('init.progress.catalog'),
+    playbook: t('init.progress.playbook'),
+    skills: t('init.progress.skills')
   };
-  spin.start('Подключаемся…');
+  spin.start(t('init.progress.connecting'));
   try {
     const result = await applyInit(plan, {
       onProgress: (step) => {
-        if (step.startsWith('agent:')) spin.message(`Регистрируем ${step.slice(6)}`);
+        if (step.startsWith('agent:')) spin.message(t('init.progress.agent', { name: step.slice(6) }));
         else spin.message(labels[step] || step);
       }
     });
-    spin.stop('Готово');
+    spin.stop(t('init.progress.done'));
     const agentLines = result.enrolled.length
       ? result.enrolled.map((item) => `  ${item.id} → ${item.home}`).join('\n')
-      : '  (никого — добавите позже: olimpyx agent add prometheus)';
+      : `  ${t('init.written.noAgents')}`;
     p.note(
       [
-        `Дом владельца: ${result.home}`,
-        `Скилл:`,
+        t('init.written.home', { path: result.home }),
+        t('init.written.skill'),
         ...result.installedSkills.map((path) => `  ${path}`),
-        'Агенты:',
+        t('init.written.agents'),
         agentLines,
         '',
-        'Дальше: olimpyx status · olimpyx skill'
+        t('init.written.next')
       ].join('\n'),
-      'Что записано'
+      t('init.written')
     );
-    p.outro('Пароль больше не нужно класть в файлы проекта.');
+    p.outro(t('init.outro'));
   } catch (error) {
-    spin.stop('Не вышло');
+    spin.stop(t('init.progress.failed'));
     throw error;
   }
 }

package/src/resident/cli.mjs

@@ -0,0 +1,101 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import { configPath } from '../vault.js';
+import { ResidentStore } from './resident-store.mjs';
+import { ResidentRuntime, safeErrorCode } from './resident-runtime.mjs';
+import { OlimpyxResident, safeView } from './olimpyx-resident.mjs';
+
+export const RESIDENT_USAGE = `Usage: olimpyx resident <prompt|start|observe|act|status|end> --agent archi
+       olimpyx resident <command> --home /absolute/participant/home
+act requires --decision-stdin. start --new-experiment is an explicit owner restart after end.
+The existing host model is the participant. No model API or background process is launched.
+Each network command is bounded to 8 seconds. Default experiment: 30 minutes, 3 messages.
+`;
+
+function parse(args) {
+  const [command, ...rest] = args;
+  if (command === '--help' || !command) return { command: 'help' };
+  if (!['prompt', 'start', 'observe', 'act', 'status', 'end'].includes(command)) throw new Error('unknown_resident_command');
+  const options = { command };
+  for (let i = 0; i < rest.length; i += 1) {
+    const key = rest[i];
+    if (key === '--home' || key === '--agent') {
+      if (!rest[i + 1] || rest[i + 1].startsWith('--') || options[key.slice(2)]) throw new Error('invalid_resident_options');
+      options[key.slice(2)] = rest[++i];
+    } else if (key === '--decision-stdin' && command === 'act') options.decisionStdin = true;
+    else if (key === '--new-experiment' && command === 'start') options.newExperiment = true;
+    else throw new Error('invalid_resident_options');
+  }
+  if (options.home && options.agent) throw new Error('choose_home_or_agent');
+  if (options.home && !isAbsolute(options.home)) throw new Error('home_must_be_absolute');
+  if (command === 'act' && !options.decisionStdin) throw new Error('act_requires_decision_stdin');
+  return options;
+}
+
+async function participantHome(options, env) {
+  if (options.home) return options.home;
+  if (options.agent) {
+    const config = JSON.parse(await readFile(configPath(env), 'utf8'));
+    const entry = config.agents?.find((agent) => agent.id === options.agent);
+    if (!entry?.home || !isAbsolute(entry.home)) throw new Error('agent_not_initialized_use_init_or_agent_add');
+    return entry.home;
+  }
+  if (env.OLIMPYX_HOME && isAbsolute(env.OLIMPYX_HOME)) return resolve(env.OLIMPYX_HOME);
+  throw new Error('provide_agent_or_absolute_home');
+}
+
+async function decisionFromStdin(input, signal) {
+  signal.addEventListener('abort', () => input.destroy?.(), { once: true });
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of input) {
+    signal.throwIfAborted();
+    size += Buffer.byteLength(chunk);
+    if (size > 16000) throw new Error('decision_input_too_large');
+    chunks.push(Buffer.from(chunk));
+  }
+  signal.throwIfAborted();
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+
+export async function runResidentCli(args, { env = process.env, stdin = process.stdin, stdout = process.stdout, fetchImpl = fetch } = {}) {
+  let options;
+  try { options = parse(args); }
+  catch (error) { stdout.write(`${JSON.stringify({ ok: false, error: error.message })}\n`); process.exitCode = 1; return; }
+  if (options.command === 'help') { stdout.write(RESIDENT_USAGE); return; }
+  if (options.command === 'prompt') {
+    stdout.write(await readFile(new URL('../../data/skill/archi-citizen.md', import.meta.url), 'utf8'));
+    stdout.write('\n\n');
+    stdout.write(await readFile(new URL('../../data/skill/archi-decide.md', import.meta.url), 'utf8'));
+    return;
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(new Error('operation_deadline')), 8000);
+  const stop = () => controller.abort(new Error('host_interrupted'));
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+  try {
+    const home = await participantHome(options, env);
+    const store = new ResidentStore(home);
+    const transport = new OlimpyxResident(home, { signal: controller.signal, fetchImpl });
+    const runtime = new ResidentRuntime({ store, transport });
+    let input = { newExperiment: options.newExperiment };
+    if (options.command === 'act') {
+      try { input = await decisionFromStdin(stdin, controller.signal); }
+      catch (error) {
+        await store.withLock(() => store.append({ ts: Date.now(), type: 'invalid_input', code: safeErrorCode(error) }));
+        throw error;
+      }
+    }
+    const result = await runtime.run(options.command, input);
+    stdout.write(`${JSON.stringify(safeView(result, transport.secrets), null, 2)}\n`);
+  } catch (error) {
+    const code = controller.signal.aborted ? 'operation_interrupted_or_timed_out' : safeErrorCode(error);
+    stdout.write(`${JSON.stringify({ ok: false, error: code, hint: 'Read status. Retry a pending action with its original actionId and body; do not enroll again.' })}\n`);
+    process.exitCode = 1;
+  } finally {
+    clearTimeout(timer);
+    process.removeListener('SIGINT', stop);
+    process.removeListener('SIGTERM', stop);
+  }
+}

package/src/resident/olimpyx-resident.mjs

@@ -0,0 +1,158 @@
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { OlimpyxClient } from '../client.js';
+import { ResidentStore } from './resident-store.mjs';
+import { LocalState } from '../state.js';
+import { SECRET_RULES, assertSafeOutbound } from '../redaction.js';
+import { checkSessionBeginBudget, checkSessionBudget, enforceSendBudget, recordSend, recordSessionEnd } from '../budget.js';
+
+const fail = (code, status) => Object.assign(new Error(code), { code, ...(status ? { status } : {}) });
+
+/** Bound external content before it enters model context or our durable journal. */
+export function safeView(value, secrets = [], depth = 0) {
+  if (depth > 10) return '[depth limit]';
+  if (typeof value === 'string') {
+    let text = value;
+    for (const secret of secrets) if (secret) text = text.split(secret.trim()).join('[REDACTED]');
+    for (const [, pattern] of SECRET_RULES) text = text.replace(new RegExp(pattern.source, `${pattern.flags.replace('g', '')}g`), '[REDACTED]');
+    return text.length > 18000 ? `${text.slice(0, 18000)} [truncated]` : text;
+  }
+  if (Array.isArray(value)) return value.slice(0, 20).map((item) => safeView(item, secrets, depth + 1));
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).slice(0, 60).map(([key, nested]) => [key,
+    /(?:token|credential|password|secret|api.?key|authorization)/i.test(key) ? '[REDACTED]' : safeView(nested, secrets, depth + 1)]));
+  return value;
+}
+
+export class OlimpyxResident {
+  constructor(home, { signal, fetchImpl = fetch, now = Date.now } = {}) {
+    this.home = home;
+    this.state = new LocalState(home);
+    this.signal = signal;
+    this.fetchImpl = fetchImpl;
+    this.now = now;
+    this.secrets = [];
+  }
+
+  client(token) {
+    const outer = this;
+    return new class extends OlimpyxClient {
+      request(method, path, body, options = {}) {
+        return super.request(method, path, body, { ...options, timeoutMs: Math.min(options.timeoutMs ?? 2000, 2000), signal: outer.signal });
+      }
+    }({ serverUrl: this.config.serverUrl, token, fetchImpl: this.fetchImpl });
+  }
+
+  async initialize() {
+    this.config = await this.state.loadConfig();
+    if (!this.config.agentId || !this.config.serverUrl) throw fail('participant_not_initialized');
+    const server = new URL(this.config.serverUrl);
+    if (!['https:', 'http:'].includes(server.protocol) || server.username || server.password) throw fail('invalid_server_url');
+    this.agentToken = await this.state.loadCredential();
+    this.secrets.push(this.agentToken);
+    return { agentId: this.config.agentId, ownerId: this.config.ownerId };
+  }
+
+  async connect(callerId) {
+    this.callerId = callerId;
+    const local = await this.state.loadSession(callerId);
+    if (local) {
+      this.secrets.push(local.token);
+      this.active = this.client(local.token);
+      // Ask the server first even after local expiry: a stop or supersession is
+      // terminal and must never be mistaken for permission to start again.
+      try {
+        await this.active.request('POST', `/v1/sessions/${encodeURIComponent(local.session_id)}/heartbeat`, { observed_at: new Date(this.now()).toISOString() });
+        if (Date.parse(local.caller_deadline) > this.now()) {
+          await this.state.renewSession(callerId);
+        } else {
+          await this.state.saveSession({ ...local, session_token: local.token }, callerId);
+        }
+        this.sessionId = local.session_id;
+        const budget = await checkSessionBudget(this.home, local.session_id);
+        if (budget.exhausted) throw fail('local_session_budget');
+        return { sessionId: this.sessionId, recovered: false };
+      } catch (error) {
+        if (error.code !== 'session_expired') throw error;
+        await recordSessionEnd(this.home, local.session_id);
+      }
+    }
+    const budget = await checkSessionBeginBudget(this.home);
+    if (budget.exhausted) throw fail('local_session_budget');
+    const response = await this.client(this.agentToken).request('POST', '/v1/sessions', {
+      installation_id: this.config.installationId ?? this.config.agentId,
+      host: { kind: 'other' }, persona_revision: Number(this.config.profileRevision ?? 1)
+    });
+    const session = response.data;
+    if (!session?.session_id || !session?.session_token) throw fail('invalid_session_response');
+    this.secrets.push(session.session_token);
+    await this.state.saveSession(session, callerId);
+    this.sessionId = session.session_id;
+    this.active = this.client(session.session_token);
+    await checkSessionBudget(this.home, session.session_id);
+    return { sessionId: session.session_id, recovered: Boolean(local) };
+  }
+
+  async read(path) {
+    const result = await this.active.request('GET', path);
+    // Keep a full guide once, but cap other prose and page sizes for small contexts.
+    const safe = safeView(result, this.secrets);
+    if (path === '/v1/city-guide') return safe;
+    return shorten(safe);
+  }
+
+  async ack(cursor) {
+    await this.active.request('POST', '/v1/inbox/cursors', { cursor });
+  }
+
+  async reply(payload, key) {
+    assertSafeOutbound(payload);
+    if (typeof key !== 'string' || !key.trim()) throw fail('reply_key_required', 422);
+    // Runtime holds the participant lock. Paths are derived from a hash, never
+    // from model-controlled filenames; receipts contain only redacted results.
+    const keyHash = createHash('sha256').update(key).digest('hex');
+    const payloadHash = createHash('sha256').update(JSON.stringify(payload)).digest('hex');
+    const receipts = new ResidentStore(join(this.home, 'resident-receipts', keyHash));
+    const receipt = await receipts.read();
+    if (receipt) {
+      if (receipt.payloadHash !== payloadHash) throw fail('reply_key_conflict', 409);
+      if (!Number.isFinite(receipt.sentAt) || !Object.hasOwn(receipt, 'result')) throw fail('invalid_reply_receipt');
+      await recordSend(this.home, { key, now: receipt.sentAt });
+      return receipt.result;
+    }
+    const message = (await this.active.request('GET', `/v1/messages/${encodeURIComponent(payload.replyToMessageId)}`)).data;
+    if (!message || message.room_id !== payload.roomId) throw fail('reply_room_mismatch', 422);
+    const senderId = message.sender?.actor_id ?? message.sender_id;
+    if (senderId === this.config.agentId) throw fail('self_reply_refused', 422);
+    await enforceSendBudget(this.active, this.home, { agentId: this.config.agentId, ownerId: this.config.ownerId,
+      kind: 'reply', roomId: payload.roomId, replyToMessageId: payload.replyToMessageId });
+    const result = await this.active.request('POST', `/v1/rooms/${encodeURIComponent(payload.roomId)}/messages`, {
+      body: payload.body, reply_to_message_id: payload.replyToMessageId
+    }, { headers: { 'idempotency-key': key } });
+    const safeResult = safeView(result, this.secrets);
+    const sentAt = this.now();
+    // Commit delivery evidence before accounting. A replay after either write
+    // never resends or gets blocked by the already-consumed local send budget.
+    await receipts.save({ payloadHash, sentAt, result: safeResult });
+    await recordSend(this.home, { key, now: sentAt });
+    return safeResult;
+  }
+
+  async end(callerId) {
+    const local = await this.state.loadSession(callerId);
+    if (!local) return;
+    try {
+      await this.client(local.token).request('POST', `/v1/sessions/${encodeURIComponent(local.session_id)}/end`, { reason: 'agent_ended' });
+    } catch (error) {
+      if (!['session_expired', 'session_stopped', 'session_superseded', 'agent_revoked', 'restricted'].includes(error.code)) throw error;
+    }
+    await recordSessionEnd(this.home, local.session_id);
+    await this.state.clearSession(callerId);
+  }
+}
+
+function shorten(value) {
+  if (typeof value === 'string') return value.length > 1500 ? `${value.slice(0, 1500)} [truncated; use a targeted read]` : value;
+  if (Array.isArray(value)) return value.map(shorten);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, shorten(nested)]));
+  return value;
+}