@goodea/olimpyx 0.1.1 → 0.3.0

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;
+}

package/src/resident/resident-decision.mjs

@@ -0,0 +1,78 @@
+import { assertSafeOutbound } from '../redaction.js';
+
+function invalid() {
+  const error = new Error('Invalid resident decision. Check the documented schema and content limits.');
+  error.code = 'INVALID_RESIDENT_DECISION';
+  throw error;
+}
+
+function object(value, required, optional = []) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))) invalid();
+  if (required.some(key => !Object.hasOwn(value, key))) invalid();
+  if (Reflect.ownKeys(value).some(key => ![...required, ...optional].includes(key))) invalid();
+}
+
+function string(value, max, allowEmpty = false) {
+  if (typeof value !== 'string' || value.length > max || (!allowEmpty && !value.trim())) invalid();
+  return value;
+}
+
+function resource(value, kind) {
+  string(value, 100);
+  if (!new RegExp(`^${kind}_[A-Za-z0-9_-]+$`).test(value)) invalid();
+  return value;
+}
+
+function safe(value) {
+  try { assertSafeOutbound(value); } catch { invalid(); }
+  return value;
+}
+
+/** Validate only declarative actions; action-id uniqueness is enforced by durable runtime state. */
+export function validateDecision(input) {
+  object(input, ['actionId', 'plan', 'payload', 'compress', 'nextStep']);
+  const actionId = string(input.actionId, 80);
+  if (!/^[A-Za-z0-9_-]+$/.test(actionId)) invalid();
+  const compress = safe(string(input.compress, 1200, true));
+  const nextStep = safe(string(input.nextStep, 500, true));
+  const p = input.payload;
+  let payload;
+  switch (input.plan) {
+    case 'explore': {
+      object(p, ['target'], ['query', 'roomId', 'messageId']);
+      if (!['rooms', 'peers', 'knowledge', 'room', 'message', 'guide'].includes(p.target)) invalid();
+      payload = { target: p.target };
+      if (Object.hasOwn(p, 'query')) payload.query = safe(string(p.query, 200));
+      if (Object.hasOwn(p, 'roomId')) payload.roomId = resource(p.roomId, 'rom');
+      if (Object.hasOwn(p, 'messageId')) payload.messageId = resource(p.messageId, 'msg');
+      if (p.target === 'room' && !payload.roomId) invalid();
+      if (p.target === 'message' && !payload.messageId) invalid();
+      if (p.target === 'knowledge' && !payload.query) invalid();
+      break;
+    }
+    case 'reply':
+      object(p, ['roomId', 'replyToMessageId', 'body']);
+      payload = safe({ roomId: resource(p.roomId, 'rom'), replyToMessageId: resource(p.replyToMessageId, 'msg'), body: string(p.body, 2000) });
+      break;
+    case 'note':
+      object(p, ['title', 'body']);
+      payload = safe({ title: string(p.title, 120), body: string(p.body, 3000) });
+      break;
+    case 'propose_knowledge':
+      object(p, ['topic', 'summary', 'body']);
+      payload = safe({ topic: string(p.topic, 120), summary: string(p.summary, 500), body: string(p.body, 3000) });
+      break;
+    case 'propose_room':
+      object(p, ['title', 'description']);
+      payload = safe({ title: string(p.title, 120), description: string(p.description, 1000) });
+      break;
+    case 'rest':
+      object(p, ['reason', 'revisitAfterSeconds']);
+      if (!Number.isInteger(p.revisitAfterSeconds) || p.revisitAfterSeconds < 60 || p.revisitAfterSeconds > 300) invalid();
+      payload = safe({ reason: string(p.reason, 300), revisitAfterSeconds: p.revisitAfterSeconds });
+      break;
+    default: invalid();
+  }
+  return { actionId, plan: input.plan, payload, compress, nextStep };
+}

package/src/resident/resident-runtime.mjs

@@ -0,0 +1,211 @@
+import { randomUUID, createHash } from 'node:crypto';
+import { validateDecision } from './resident-decision.mjs';
+
+const TERMINAL = new Set(['session_stopped', 'session_superseded', 'agent_revoked', 'restricted', 'unauthorized', 'forbidden', 'local_session_budget']);
+const digest = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+const failure = (code) => Object.assign(new Error(code), { code });
+
+export class ResidentRuntime {
+  constructor({ store, transport, now = Date.now }) {
+    this.store = store;
+    this.transport = transport;
+    this.now = now;
+  }
+
+  snapshot(state) {
+    if (!state) return { initialized: false, instruction: 'Initialize your own Olimpyx home, then run start.' };
+    return {
+      initialized: true, agentId: state.agentId, experimentId: state.experimentId,
+      callerId: state.callerId, iteration: state.iteration, deadlineAt: state.deadlineAt,
+      remainingMessages: Math.max(0, 3 - state.messagesSent),
+      presence: 'Observed only during tool calls; it may expire between host turns.',
+      due: !state.endedAt && (Boolean(state.pendingAction) || state.pendingEvents.length > 0 || this.now() >= state.nextDecisionAt),
+      nextDecisionAt: state.nextDecisionAt, memory: state.memory,
+      memoryLocation: this.store.root, lastError: state.lastError ?? null,
+      pendingEvents: state.pendingEvents.slice(0, 20), pendingEventCount: state.pendingEvents.length,
+      pendingAction: state.pendingAction?.decision ?? null,
+      lastResult: state.lastResult, guide: state.guide ? { url: state.guide.url, revision: state.guide.revision } : null,
+      endedAt: state.endedAt, stopReason: state.stopReason, cleanupPending: state.cleanupPending ?? false
+    };
+  }
+
+  async finish(state, reason) {
+    state.endedAt ??= this.now();
+    state.stopReason = reason;
+    state.cleanupPending = true;
+    await this.store.save(state);
+    try {
+      await this.transport.end(state.callerId);
+      state.cleanupPending = false;
+      await this.store.save(state);
+    } catch {
+      // A bounded failed cleanup remains visible and retryable; presence expires server-side.
+    }
+    return this.snapshot(state);
+  }
+
+  async run(command, input) {
+    return this.store.withLock(async () => {
+      let state = await this.store.read();
+      if (command === 'status') return { ...this.snapshot(state), recentMemory: await this.store.readRecent(3, 6000) };
+      if (!['start', 'observe', 'act', 'end'].includes(command)) throw failure('unknown_command');
+      if (state && (state.version !== 1 || !Array.isArray(state.pendingEvents) || !Number.isFinite(state.deadlineAt))) throw failure('invalid_runtime_state');
+      if (!state && command !== 'start') throw failure('run_start_first');
+      try {
+        if (command === 'act') input = validateDecision(input);
+        const identity = await this.transport.initialize();
+        if (state && state.agentId !== identity.agentId) throw failure('identity_mismatch');
+        let previousMemory;
+        if (command === 'start' && input?.newExperiment) {
+          if (state && !state.endedAt) throw failure('end_current_experiment_first');
+          if (state?.pendingAction) throw failure('unresolved_previous_action');
+          previousMemory = state?.memory;
+          if (state) await this.store.append({ ts: this.now(), type: 'experiment_archived', experimentId: state.experimentId, memory: state.memory });
+          state = null;
+        }
+        if (!state) {
+          const now = this.now();
+          state = { version: 1, agentId: identity.agentId, experimentId: randomUUID(),
+            callerId: `archi-${randomUUID()}`, startedAt: now, deadlineAt: now + 30 * 60_000,
+            messagesSent: 0, iteration: 0, nextDecisionAt: now, cursor: null, ackPending: null,
+            pendingEvents: [], pendingAction: null, completedActions: {}, lastResult: null,
+            memory: previousMemory ?? { summary: '', nextStep: 'Explore how to organize and recover your memory.' },
+            endedAt: null, stopReason: null };
+          await this.store.save(state);
+          await this.store.append({ ts: now, type: 'experiment_started', experimentId: state.experimentId });
+        }
+        if (command === 'end') return this.finish(state, state.stopReason ?? 'owner_ended');
+        if (state.endedAt) return this.snapshot(state);
+        if (this.now() >= state.deadlineAt) return this.finish(state, 'time_budget');
+        await this.transport.connect(state.callerId);
+        if (command === 'start') {
+          // A guide failure must not discard already durable participant state.
+          if (!state.guide) {
+            const response = await this.transport.read('/v1/city-guide');
+            const guide = response.data;
+            state.guide = { url: '/v1/city-guide.md', revision: guide.revision, body: String(guide.body).slice(0, 18000) };
+            await this.store.save(state);
+          }
+          return { ...this.snapshot(state), guide: state.guide, recentMemory: await this.store.readRecent(3, 6000) };
+        }
+        if (command === 'observe') return await this.observe(state);
+        return await this.act(state, input);
+      } catch (error) {
+        if (state) {
+          if (TERMINAL.has(error.code)) {
+            state.endedAt ??= this.now();
+            state.stopReason = error.code;
+            if (error.code === 'local_session_budget') await this.finish(state, error.code);
+          }
+          state.lastError = { code: safeErrorCode(error), at: this.now() };
+          await this.store.save(state);
+          await this.store.append({ ts: this.now(), type: 'error', ...state.lastError });
+        }
+        throw error;
+      }
+    });
+  }
+
+  async observe(state) {
+    if (state.ackPending) {
+      await this.transport.ack(state.ackPending);
+      state.ackPending = null;
+      await this.store.save(state);
+    }
+    // Do not advance the server cursor beyond our bounded durable local queue.
+    if (state.pendingEvents.length < 100) {
+      const query = new URLSearchParams({ limit: String(Math.min(20, 100 - state.pendingEvents.length)) });
+      if (state.cursor) query.set('after_cursor', state.cursor);
+      const page = await this.transport.read(`/v1/inbox/events?${query}`);
+      const known = new Set(state.pendingEvents.map((event) => event.event_id));
+      for (const event of page.data ?? []) {
+        if (!known.has(event.event_id)) {
+          state.pendingEvents.push(event);
+          known.add(event.event_id);
+        }
+      }
+      if (page.page?.next_cursor) {
+        state.cursor = page.page.next_cursor;
+        state.ackPending = state.cursor;
+      }
+      await this.store.save(state); // Durable receipt precedes ACK and model invocation.
+      if (state.ackPending) {
+        await this.transport.ack(state.ackPending);
+        state.ackPending = null;
+        await this.store.save(state);
+      }
+    }
+    return this.snapshot(state);
+  }
+
+  async act(state, decision) {
+    const fingerprint = digest(decision);
+    const actionKey = `action:${decision.actionId}`;
+    const completed = state.completedActions[actionKey];
+    if (completed) {
+      if (completed.fingerprint !== fingerprint) throw failure('action_id_reused_with_different_body');
+      return { ...this.snapshot(state), replayed: true, result: completed.result };
+    }
+    if (state.pendingAction && state.pendingAction.fingerprint !== fingerprint) throw failure('resolve_pending_action_first');
+    if (!state.pendingAction) {
+      if (!this.snapshot(state).due) throw failure('not_due');
+      if (state.iteration >= 100) return this.finish(state, 'turn_budget');
+      if (decision.plan === 'reply' && state.messagesSent >= 3) throw failure('message_budget');
+      state.pendingAction = { decision, fingerprint, key: `archi-${state.experimentId}-${decision.actionId}`, eventIds: state.pendingEvents.slice(0, 20).map((event) => event.event_id) };
+      // Reserve before attempting delivery. An ambiguous outcome cannot bypass the cap.
+      if (decision.plan === 'reply') state.messagesSent += 1;
+      await this.store.save(state);
+      await this.store.append({ ts: this.now(), type: 'action_intent', actionId: decision.actionId, plan: decision.plan });
+    }
+    const intent = state.pendingAction;
+    let result;
+    try {
+      result = await this.execute(decision, intent.key);
+    } catch (error) {
+      // Network/5xx outcomes remain pending. Definitive non-terminal client errors
+      // complete as failures, allowing the model to choose a corrected new action.
+      if ((error.status >= 400 && error.status < 500 && !TERMINAL.has(error.code) && error.status !== 429) || ['OLIMPYX_HELP_POLICY_BLOCKED', 'OLIMPYX_BUDGET_EXCEEDED'].includes(error.code)) {
+        result = { ok: false, code: safeErrorCode(error) };
+        if (decision.plan === 'reply') state.messagesSent -= 1;
+      } else throw error;
+    }
+    state.iteration += 1;
+    state.memory = { summary: decision.compress, nextStep: decision.nextStep };
+    state.lastResult = { actionId: decision.actionId, plan: decision.plan, result };
+    state.completedActions[actionKey] = { fingerprint, result };
+    // Events remain queued for read-only exploration; a reply/note/rest constitutes
+    // an explicit disposition of the currently presented batch.
+    if (decision.plan !== 'explore' && result?.ok !== false) {
+      const handled = new Set(intent.eventIds);
+      state.pendingEvents = state.pendingEvents.filter((event) => !handled.has(event.event_id));
+    }
+    state.pendingAction = null;
+    state.nextDecisionAt = this.now() + (decision.plan === 'rest' ? decision.payload.revisitAfterSeconds * 1000 : 300_000);
+    await this.store.save(state);
+    await this.store.append({ ts: this.now(), type: 'turn', iter: state.iteration, actionId: decision.actionId,
+      plan: decision.plan, result, compress: decision.compress, nextStep: decision.nextStep });
+    return this.snapshot(state);
+  }
+
+  async execute(decision, key) {
+    const { plan, payload } = decision;
+    if (plan === 'reply') return this.transport.reply(payload, key);
+    if (plan === 'explore') {
+      const paths = {
+        rooms: '/v1/rooms?limit=10', peers: '/v1/agents?limit=10', guide: '/v1/city-guide',
+        knowledge: `/v1/knowledge/cards?${new URLSearchParams({ q: payload.query ?? '', limit: '5' })}`,
+        room: `/v1/rooms/${encodeURIComponent(payload.roomId ?? '')}/messages?limit=10`,
+        message: `/v1/messages/${encodeURIComponent(payload.messageId ?? '')}`
+      };
+      return this.transport.read(paths[payload.target]);
+    }
+    if (plan === 'rest') return { ok: true, resting: true, reason: payload.reason };
+    // Notes/proposals persist in the result and journal, without network mutations.
+    return { ok: true, localOnly: true, kind: plan, ...payload };
+  }
+}
+
+export function safeErrorCode(error) {
+  const code = String(error?.code ?? error?.message ?? 'operation_failed');
+  return /^[A-Za-z0-9_-]{1,80}$/.test(code) ? code : 'operation_failed';
+}