@goodea/olimpyx 0.1.0 → 0.3.0

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

package/src/resident/resident-store.mjs

@@ -0,0 +1,157 @@
+import { constants } from 'node:fs';
+import { chmod, lstat, mkdir, open, readFile, rename, rmdir, unlink } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+const noFollow = constants.O_NOFOLLOW;
+const missing = (error) => error.code === 'ENOENT';
+
+/** Private permanent storage. Filenames are fixed, never selected by model input.
+ * Callers serialize read/modify/write operations with withLock().
+ */
+export class ResidentStore {
+  constructor(home, { now = Date.now } = {}) {
+    this.root = join(home, 'resident');
+    this.now = now;
+  }
+
+  async prepare() {
+    await mkdir(this.root, { recursive: true, mode: 0o700 });
+    if (!(await lstat(this.root)).isDirectory()) throw new Error('Resident storage must be a real directory');
+    await chmod(this.root, 0o700);
+  }
+
+  async syncDirectory() {
+    const directory = await open(this.root, constants.O_RDONLY | noFollow);
+    try { await directory.sync(); } finally { await directory.close(); }
+  }
+
+  async read() {
+    let file;
+    try {
+      file = await open(join(this.root, 'state.json'), constants.O_RDONLY | noFollow);
+      return JSON.parse(await file.readFile('utf8'));
+    } catch (error) {
+      if (missing(error)) return null;
+      throw error;
+    } finally { await file?.close(); }
+  }
+
+  async save(state) {
+    const content = JSON.stringify(state);
+    if (content === undefined) throw new Error('State must be JSON serializable');
+    await this.prepare();
+    const temporary = join(this.root, `.state-${randomUUID()}.tmp`);
+    let file;
+    try {
+      file = await open(temporary, 'wx', 0o600);
+      await file.writeFile(`${content}\n`);
+      await file.sync();
+      await file.close();
+      file = null;
+      await rename(temporary, join(this.root, 'state.json'));
+      await this.syncDirectory();
+    } finally {
+      await file?.close();
+      await unlink(temporary).catch((error) => { if (!missing(error)) throw error; });
+    }
+  }
+
+  async append(record) {
+    const content = JSON.stringify(record);
+    if (content === undefined) throw new Error('Journal record must be JSON serializable');
+    await this.prepare();
+    const file = await open(join(this.root, 'memory.jsonl'), constants.O_CREAT | constants.O_RDWR | noFollow, 0o600);
+    try {
+      await file.chmod(0o600);
+      let end = (await file.stat()).size;
+      // A newline commits a record. Remove only a torn final record before appending.
+      const buffer = Buffer.alloc(8192);
+      let position = end;
+      while (position > 0) {
+        const start = Math.max(0, position - buffer.length);
+        const { bytesRead } = await file.read(buffer, 0, position - start, start);
+        const newline = buffer.subarray(0, bytesRead).lastIndexOf(10);
+        if (newline >= 0) { end = start + newline + 1; break; }
+        position = start;
+        end = start;
+      }
+      await file.truncate(end);
+      const bytes = Buffer.from(`${content}\n`);
+      let written = 0;
+      while (written < bytes.length) {
+        const result = await file.write(bytes, written, bytes.length - written, end + written);
+        if (!result.bytesWritten) throw new Error('Journal write made no progress');
+        written += result.bytesWritten;
+      }
+      await file.sync();
+    } finally { await file.close(); }
+    await this.syncDirectory();
+  }
+
+  async readRecent(limit = 5, maxChars = 6000) {
+    if (!Number.isSafeInteger(limit) || limit < 0 || !Number.isSafeInteger(maxChars) || maxChars < 0 || maxChars > 1_000_000) {
+      throw new Error('Invalid recent-memory bounds');
+    }
+    if (!limit || !maxChars) return [];
+    let file;
+    try {
+      file = await open(join(this.root, 'memory.jsonl'), constants.O_RDONLY | noFollow);
+      const size = (await file.stat()).size;
+      const start = Math.max(0, size - (maxChars * 4 + 8));
+      const buffer = Buffer.alloc(size - start);
+      const { bytesRead } = await file.read(buffer, 0, buffer.length, start);
+      let text = buffer.subarray(0, bytesRead).toString('utf8');
+      if (start) text = text.slice(text.indexOf('\n') + 1);
+      const lines = text.split('\n');
+      lines.pop(); // Ignore an incomplete final record, including a partial JSON token.
+      const records = [];
+      let used = 0;
+      for (let index = lines.length - 1; index >= 0 && records.length < limit; index -= 1) {
+        const line = lines[index];
+        if (used + line.length + 1 > maxChars) break;
+        records.unshift(JSON.parse(line));
+        used += line.length + 1;
+      }
+      return records;
+    } catch (error) {
+      if (missing(error)) return [];
+      throw error;
+    } finally { await file?.close(); }
+  }
+
+  async withLock(callback) {
+    await this.prepare();
+    const guard = join(this.root, '.lock-acquisition');
+    const path = join(this.root, 'lock.json');
+    const owner = { token: randomUUID(), pid: process.pid, hostname: hostname(), createdAt: this.now() };
+    try { await mkdir(guard, { mode: 0o700 }); } catch (error) {
+      if (error.code === 'EEXIST') throw new Error('Resident lock acquisition is busy; stale acquisition guards require manual inspection');
+      throw error;
+    }
+    try {
+      let existing;
+      try { existing = JSON.parse(await readFile(path, 'utf8')); } catch (error) { if (!missing(error)) throw error; }
+      if (existing) {
+        if (existing.hostname !== hostname() || !Number.isSafeInteger(existing.pid) || existing.pid <= 0 || typeof existing.token !== 'string') {
+          throw new Error('Resident lock owner cannot be safely verified');
+        }
+        let dead = false;
+        try { process.kill(existing.pid, 0); } catch (error) { dead = error.code === 'ESRCH'; }
+        if (!dead) throw new Error('Resident operation is already active');
+        await unlink(path);
+      }
+      const lock = await open(path, 'wx', 0o600);
+      try { await lock.writeFile(JSON.stringify(owner)); await lock.sync(); } finally { await lock.close(); }
+      await this.syncDirectory();
+    } finally { await rmdir(guard); }
+    try { return await callback(); } finally {
+      const current = JSON.parse(await readFile(path, 'utf8'));
+      if (current.token === owner.token) {
+        await unlink(path);
+        await this.syncDirectory();
+      }
+    }
+  }
+}

package/src/state.js

@@ -13,12 +13,32 @@ async function atomicJson(path, value, mode = 0o600) {
   await rename(temp, path);
 }
 
+// Sanitise caller-id for use as a directory segment. A caller-id is generated
+// by the participant as e.g. `caller-helios-<pid>-<unix>`, so it normally
+// contains only [a-z0-9-]. We still strip anything else defensively so a
+// hostile caller-id cannot escape the per-caller state directory.
+function safeCallerId(callerId) {
+  if (typeof callerId !== 'string' || !callerId.trim()) return null;
+  if (!/^[A-Za-z0-9._-]{1,128}$/.test(callerId)) return null;
+  return callerId;
+}
+
 export class LocalState {
   constructor(root) { this.root = root; }
   async init() {
     await mkdir(this.root, { recursive: true, mode: 0o700 });
     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
+  // mutations live under their own subdir so they no longer clobber each other.
+  async callerDir(callerId) {
+    const id = safeCallerId(callerId);
+    if (!id) return this.root;
+    const dir = join(this.root, 'calls', id);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    return dir;
+  }
   async loadConfig() { return readJson(join(this.root, 'config.json'), {}); }
   async saveConfig(config) { await this.init(); await atomicJson(join(this.root, 'config.json'), config); return config; }
   async loadCredential() { return (await readFile(join(this.root, 'credential'), 'utf8')).trim(); }
@@ -34,46 +54,52 @@ export class LocalState {
     await this.init(); const path = join(this.root, 'owner-credential');
     await writeFile(path, token, { mode: 0o600 }); await chmod(path, 0o600);
   }
-  async loadSession() {
-    const metadata = await readJson(join(this.root, 'session.json'), null);
+  async loadSession(callerId) {
+    const dir = await this.callerDir(callerId);
+    const metadata = await readJson(join(dir, 'session.json'), null);
     if (!metadata) return null;
-    return { ...metadata, token: (await readFile(join(this.root, 'session-credential'), 'utf8')).trim() };
+    return { ...metadata, token: (await readFile(join(dir, 'session-credential'), 'utf8')).trim() };
   }
   async saveSession(session, callerId, callerLeaseMs = 75_000) {
     if (!session?.session_id || !session?.session_token || !callerId) throw new Error('Complete session and callerId are required');
-    await this.init();
-    const credentialPath = join(this.root, 'session-credential');
+    const dir = await this.callerDir(callerId);
+    const credentialPath = join(dir, 'session-credential');
     await writeFile(credentialPath, session.session_token, { mode: 0o600 }); await chmod(credentialPath, 0o600);
     const metadata = { session_id: session.session_id, expires_at: session.expires_at, caller_id: callerId, caller_deadline: new Date(Date.now() + Math.min(callerLeaseMs, 85_000)).toISOString(), inbox_cursor: session.inbox_cursor ?? null };
-    await atomicJson(join(this.root, 'session.json'), metadata); return metadata;
+    await atomicJson(join(dir, 'session.json'), metadata); return metadata;
   }
   async renewSession(callerId, updates = {}, callerLeaseMs = 75_000) {
-    const session = await this.loadSession();
+    const session = await this.loadSession(callerId);
     if (!session) throw new Error('No local session. Run session begin first.');
     if (session.caller_id !== callerId) throw new Error('callerId does not own this participant session');
     if (Date.parse(session.caller_deadline) <= Date.now()) throw new Error('Local caller lease expired; begin a new session');
     const { token: _token, ...metadata } = session;
     const next = { ...metadata, ...updates, caller_deadline: new Date(Date.now() + Math.min(callerLeaseMs, 85_000)).toISOString() };
-    await atomicJson(join(this.root, 'session.json'), next); return next;
+    const dir = await this.callerDir(callerId);
+    await atomicJson(join(dir, 'session.json'), next); return next;
+  }
+  async clearSession(callerId) {
+    const dir = await this.callerDir(callerId);
+    await Promise.all([rm(join(dir, 'session.json'), { force: true }), rm(join(dir, 'session-credential'), { force: true })]);
   }
-  async clearSession() { await Promise.all([rm(join(this.root, 'session.json'), { force: true }), rm(join(this.root, 'session-credential'), { force: true })]); }
-  async beginMutation(method, path, body, explicitKey) {
+  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');
       return { fingerprint: null, key: explicitKey };
     }
-    await this.init();
+    const dir = await this.callerDir(callerId);
     const fingerprint = createHash('sha256').update(JSON.stringify({ method: method.toUpperCase(), path, body: body ?? null })).digest('hex');
-    const pending = await readJson(join(this.root, 'pending-mutations.json'), {});
+    const pending = await readJson(join(dir, 'pending-mutations.json'), {});
     if (!pending[fingerprint]) {
       pending[fingerprint] = { key: randomUUID(), method: method.toUpperCase(), path, created_at: new Date().toISOString() };
-      await atomicJson(join(this.root, 'pending-mutations.json'), pending);
+      await atomicJson(join(dir, 'pending-mutations.json'), pending);
     }
     return { fingerprint, key: pending[fingerprint].key };
   }
-  async completeMutation(fingerprint) {
+  async completeMutation(fingerprint, callerId) {
     if (!fingerprint) return;
-    const path = join(this.root, 'pending-mutations.json');
+    const dir = await this.callerDir(callerId);
+    const path = join(dir, 'pending-mutations.json');
     const pending = await readJson(path, {});
     delete pending[fingerprint];
     if (Object.keys(pending).length === 0) await rm(path, { force: true });