@kingsoftcloud/agentkit-harness-node 0.0.0-stage → 0.0.2

package/src/native/workspace-mutation-lock.mjs

@@ -0,0 +1,74 @@
+/** Cooperative cross-process exclusion for synchronous workspace publications.
+ * Never hold this lock across an await: a same-process contender would block
+ * the event loop needed by its owner. SQLite releases it on process death.
+ */
+import { createHash } from 'node:crypto';
+import { closeSync, existsSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { constants } from 'node:fs';
+import { canonical } from '@kingsoftcloud/agentkit-harness-core';
+import { openPrivate, privateDirectory, privateFile } from './local-command-state.mjs';
+
+export const WORKSPACE_MUTATION_LOCK = 'agentkit.workspace-mutation-lock/v1';
+const failure = code => Object.assign(new Error(code), { code });
+// Keep the native handle strongly reachable even when a caller only uses the
+// returned release function for its side effect. V8 may otherwise collect an
+// unused closure (and its DatabaseSync) while the lock is intentionally held.
+const activeDatabases = new Set();
+
+function canonicalTarget(path) {
+  let parent = resolve(path); const missing = [];
+  while (!existsSync(parent)) { missing.unshift(basename(parent)); parent = dirname(parent); }
+  return join(realpathSync(parent), ...missing);
+}
+
+export function workspaceMutationLockPath(path) {
+  const target = canonicalTarget(path);
+  return join(dirname(target), '.native-locks', `lock-${createHash('sha256').update(target).digest('hex')}.sqlite`);
+}
+
+export function acquireWorkspaceMutationLock(path, { timeoutMs = 10000 } = {}) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 120000) throw failure('workspace_lock_timeout_invalid');
+  const filename = workspaceMutationLockPath(path);
+  privateDirectory(dirname(filename), true);
+  // Open/create through the no-follow private file checks before SQLite opens
+  // it, including every auxiliary file SQLite might use in this directory.
+  const fd = openPrivate(filename, constants.O_RDWR | constants.O_CREAT); closeSync(fd);
+  for (const suffix of ['-journal', '-wal', '-shm']) privateFile(filename + suffix, true);
+  let db;
+  try {
+    db = new DatabaseSync(filename);
+    // BEGIN IMMEDIATE alone does not necessarily acquire a write lock on a
+    // brand-new empty database. Keep a single durable sentinel row so a
+    // second process reliably contends on the same SQLite write transaction.
+    db.exec(`PRAGMA busy_timeout=${timeoutMs}; CREATE TABLE IF NOT EXISTS workspace_lock (id INTEGER PRIMARY KEY CHECK (id = 1)); BEGIN IMMEDIATE; INSERT OR IGNORE INTO workspace_lock (id) VALUES (1);`);
+    activeDatabases.add(db);
+  } catch (error) {
+    try { db?.close(); } catch {}
+    if ([5, 6].includes(error.errcode)) throw failure('workspace_mutation_busy');
+    throw error;
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    try { db.exec('ROLLBACK'); } finally { activeDatabases.delete(db); db.close(); }
+  };
+}
+
+/** Detect identity replacement as well as in-place mutation after permission
+ * waits or SQLite waits. assertCurrent is the Host's live ledger/fence check. */
+export function workspaceMutationGuard(request, assertCurrent, checkRoot) {
+  if (assertCurrent != null && typeof assertCurrent !== 'function') throw failure('workspace_authority_invalid');
+  const fields = ['scope', 'sessionId', 'runId', 'turnId', 'buildId', 'parentRunId', 'taskChainId',
+    'operationKey', 'executionFence', 'call', 'definition', 'interaction', 'contract', 'originalOperationKey', 'originalClaimedFence'];
+  const identity = () => canonical(Object.fromEntries(fields.filter(key => request[key] !== undefined).map(key => [key, request[key]])));
+  const before = identity(), signal = request.signal;
+  return () => {
+    checkRoot();
+    if (signal !== request.signal || before !== identity()) throw failure('workspace_execution_context_changed');
+    signal?.throwIfAborted();
+    if (assertCurrent && assertCurrent(request) !== true) throw failure('workspace_execution_authority_changed');
+  };
+}

package/src/native/workspace-patch-worker.mjs

@@ -0,0 +1,17 @@
+import { parentPort, workerData } from 'node:worker_threads';
+import { derivePatchedContent } from '@kingsoftcloud/agentkit-harness-core/patch-apply';
+
+try {
+  let bytes = 0;
+  const changes = workerData.map(item => {
+    const text = item.section.type === 'update' ? derivePatchedContent(item.text, item.section.chunks).content
+      : item.section.type === 'add' ? item.section.contents : '';
+    bytes += Buffer.byteLength(text);
+    if (Buffer.byteLength(text) > 2 * 1024 * 1024 || bytes > 16 * 1024 * 1024)
+      throw Object.assign(Error('Patched output exceeds the 2 MiB per-file or 16 MiB total limit'), { code: 'patch_budget_exceeded' });
+    return text;
+  });
+  parentPort.postMessage({ contract: 'zcode-patch/v1', changes });
+} catch (error) {
+  parentPort.postMessage({ contract: 'zcode-patch/v1', error: String(error.message), code: error.code ?? 'apply_patch_hunk_not_found' });
+}

package/src/native/workspace-patch.mjs

@@ -0,0 +1,17 @@
+import { Worker } from 'node:worker_threads';
+
+/** Pure hunk verification. Publication remains in the owning workspace port. */
+export async function prepareWorkspacePatch(input, { signal, timeoutMs = 2000 } = {}) {
+  signal?.throwIfAborted();
+  const worker = new Worker(new URL('./workspace-patch-worker.mjs', import.meta.url), { workerData: input, execArgv: [],
+    resourceLimits: { maxOldGenerationSizeMb: 128, maxYoungGenerationSizeMb: 16, stackSizeMb: 4 } });
+  return new Promise(resolve => {
+    let output, settled = false;
+    const finish = value => { if (settled) return; settled = true; clearTimeout(timer); signal?.removeEventListener('abort', stop); resolve(value); };
+    const stop = () => { worker.unref(); void worker.terminate().catch(() => {}); finish(null); };
+    const timer = setTimeout(stop, timeoutMs);
+    worker.once('message', value => { output = value; }); worker.once('error', stop);
+    worker.once('exit', code => finish(!signal?.aborted && code === 0 && output?.contract === 'zcode-patch/v1' ? output : null));
+    signal?.addEventListener('abort', stop, { once: true }); if (signal?.aborted) stop();
+  });
+}

package/src/native/workspace-paths.mjs

@@ -0,0 +1,225 @@
+/**
+ * Path resolution, escape/symlink protection and atomic publication for the
+ * Native Node workspace tools. No external dependencies; Node >=22.19 builtins.
+ *
+ * The Python reference (ksadk.toolsets.workspace) resolves workspace paths with
+ * pathlib.Path.resolve(), which follows symlinks for the existing portion of a
+ * path and leaves a non-existent tail lexical. We reproduce that here so a
+ * symlink inside the workspace that points outside is rejected before any read
+ * or write, while a symlink that stays inside is followed.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import {
+  chmodSync, closeSync, existsSync, fsyncSync, linkSync, lstatSync, mkdirSync,
+  openSync, realpathSync, renameSync, unlinkSync, writeSync,
+} from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+export const TWO_MB = 2 * 1024 * 1024;
+
+/** sha256 hex digest of a string (utf-8) or Buffer. */
+export function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+/** True when target is root or located beneath root (both absolute, posix-comparable). */
+export function isInside(target, root) {
+  if (target === root) return true;
+  const rootWithSep = root.endsWith(sep) ? root : root + sep;
+  return target.startsWith(rootWithSep);
+}
+
+/**
+ * Resolve the existing portion of a path through symlinks, leaving a
+ * non-existent tail lexical. Mirrors pathlib.Path.resolve(strict=False).
+ */
+export function realpathExisting(p) {
+  if (existsSync(p)) return realpathSync(p);
+  const tail = [];
+  let head = p;
+  // Walk up to the longest existing ancestor; resolve it, then re-append.
+  while (!existsSync(head)) {
+    const base = dirname(head);
+    if (base === head) break; // reached filesystem root
+    tail.unshift(head.slice(base.length + 1) || head.slice(base.length));
+    head = base;
+  }
+  const realHead = existsSync(head) ? realpathSync(head) : head;
+  return tail.length ? join(realHead, ...tail) : realHead;
+}
+
+/**
+ * Resolve a workspace-relative path and enforce it stays inside the root.
+ * Leading slashes and backslashes are normalized the way the Python port does:
+ * backslashes become '/', a leading '/' is stripped, empty becomes '.'.
+ * Throws a WorkspacePathError when the resolved target escapes the root.
+ */
+export function resolveWorkspacePath(root, rootReal, relativePath) {
+  const raw = String(relativePath ?? '').trim().replace(/\\/g, '/').replace(/^\/+/, '') || '.';
+  const lexical = resolve(rootReal, raw);
+  if (!isInside(lexical, rootReal)) {
+    throw new WorkspacePathError('workspace path must stay inside the workspace root');
+  }
+  const real = realpathExisting(lexical);
+  if (!isInside(real, rootReal)) {
+    throw new WorkspacePathError('workspace path must stay inside the workspace root');
+  }
+  return real;
+}
+
+/** Workspace-relative posix path for a resolved absolute target. */
+export function workspaceRelative(rootReal, target) {
+  const rel = relative(rootReal, target);
+  return rel.split(sep).join('/');
+}
+
+export class WorkspacePathError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'WorkspacePathError';
+    this.code = 'workspace_path_escape';
+  }
+}
+
+/**
+ * Publish a complete sibling file atomically. Never truncate the target in
+ * place: write to a fresh temp sibling, fsync, then link (create-only) or
+ * rename (overwrite). Preserves an existing file's mode. A failed publication
+ * leaves the original content and read-state unchanged.
+ *
+ * Mirrors ksadk.toolsets.workspace_mutation.publish_workspace_bytes.
+ */
+export function publishWorkspaceBytes(target, payload, { createOnly = false } = {}) {
+  const parent = dirname(target);
+  mkdirSync(parent, { recursive: true });
+  let mode = null;
+  try {
+    const info = lstatSync(target);
+    if (!info.isFile()) throw new WorkspaceMutationError('workspace mutation requires a regular file');
+    mode = info.mode & 0o777;
+  } catch (error) {
+    if (error instanceof WorkspaceMutationError) throw error;
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const temporary = join(parent, `.${target.split(sep).pop()}.native-${randomHex(12)}`);
+  const fd = openSync(temporary, 'wx', 0o666);
+  try {
+    writeAll(fd, payload);
+    closeSync(fd);
+    if (mode !== null) applyMode(temporary, mode);
+    if (createOnly) {
+      linkSync(temporary, target); // fails if target now exists (race-safe create)
+    } else {
+      renameSync(temporary, target); // atomic replace of the directory entry
+    }
+  } catch (error) {
+    // writeAll/close/chmod/link/rename failed: ensure the fd is closed and the
+    // temp sibling is removed. The original target is never touched on this
+    // path (link/rename are the only steps that affect it), so its content and
+    // the read-state the caller recorded remain intact.
+    try { closeSync(fd); } catch { /* already closed or never opened */ }
+    safeUnlink(temporary);
+    throw error;
+  } finally {
+    // A successful create-only publication leaves the temporary hard link in
+    // place until it is unlinked here. Rename has already removed its name.
+    safeUnlink(temporary);
+  }
+}
+
+function writeAll(fd, payload) {
+  // The caller owns closing fd on success; on failure the caller's catch
+  // closes it. fsync before returning so the bytes are durable before the
+  // atomic link/rename.
+  const buffer = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, 'utf-8');
+  let offset = 0;
+  while (offset < buffer.length) {
+    const written = writeSync(fd, buffer, offset);
+    if (written <= 0) throw new WorkspaceMutationError('workspace write stalled');
+    offset += written;
+  }
+  fsyncSync(fd);
+}
+
+function applyMode(target, mode) {
+  try {
+    // chmod the temp file to match the pre-existing target's permission bits.
+    chmodSync(target, mode);
+  } catch {
+    /* best-effort; a failed chmod must not abort an otherwise valid publish */
+  }
+}
+
+function safeUnlink(p) {
+  try { unlinkSync(p); } catch { /* already gone */ }
+}
+
+export class WorkspaceMutationError extends Error {
+  constructor(message, code = 'workspace_mutation_failed') {
+    super(message);
+    this.name = 'WorkspaceMutationError';
+    this.code = code;
+  }
+}
+
+function randomHex(bytes) {
+  return randomBytes(bytes).toString('hex');
+}
+
+/** fnmatch-style glob test (case-sensitive, matching POSIX normcase identity). */
+export function fnmatch(name, pattern) {
+  return globToRegex(pattern).test(name);
+}
+
+export function globToRegex(pattern) {
+  let out = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === '*') {
+      out += '.*';
+    } else if (c === '?') {
+      out += '.';
+    } else if (c === '[') {
+      const parsed = parseCharClass(pattern, i);
+      if (parsed) {
+        out += parsed.regex;
+        i = parsed.next - 1;
+      } else {
+        out += '\\[';
+      }
+    } else if ('^$.+(){}|\\'.includes(c)) {
+      out += '\\' + c;
+    } else {
+      out += c;
+    }
+  }
+  return new RegExp('^' + out + '$');
+}
+
+function parseCharClass(pattern, start) {
+  let j = start + 1;
+  let negate = false;
+  if (j < pattern.length && (pattern[j] === '!' || pattern[j] === '^')) {
+    negate = true;
+    j++;
+  }
+  let cls = '';
+  if (j < pattern.length && pattern[j] === ']') {
+    cls += '\\]';
+    j++;
+  }
+  while (j < pattern.length && pattern[j] !== ']') {
+    const ch = pattern[j];
+    if (ch === '\\') cls += '\\\\';
+    else if ('^$.+*?(){}|['.includes(ch)) cls += '\\' + ch;
+    else cls += ch;
+    j++;
+  }
+  if (j >= pattern.length) return null; // no closing bracket; treat '[' literally
+  return { regex: '[' + (negate ? '^' : '') + cls + ']', next: j + 1 };
+}
+
+/** Escape a literal string for use in a RegExp. */
+export function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/native/workspace-state.mjs

@@ -0,0 +1,272 @@
+/**
+ * Per-session persisted execution state for the Native Node workspace tools.
+ *
+ * Two pieces of state are owned by this port and must survive an instance or
+ * process restart, keyed by sessionId:
+ *   - read-state: the last observed file revision per relative path, used to
+ *     gate edits/overwrites (read-after-modify and stale-read rejection).
+ *   - pending approvals: outstanding approval_required interactions, used to
+ *     validate the interactionId/callId binding on an approval reply.
+ *
+ * Credentials are never stored. Pending approvals keep only an arguments
+ * digest, never the tool arguments themselves. The store is single-session:
+ * one port instance owns one sessionId; cross-session isolation comes from a
+ * separate per-session directory under stateDir.
+ *
+ * sessionId is an untrusted caller-supplied identifier. It is never joined
+ * into the filesystem path verbatim, because a value like "../x" or "a/b"
+ * would escape stateDir or collide with another session's directory. The
+ * on-disk directory is keyed by a sha256 hex digest of the normalized id, which
+ * contains no path separators; the original id is stored inside the
+ * JSON files for audit/inspection only.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+const READ_STATE_VERSION = 'native-workspace-read-state/v1';
+const PENDING_VERSION = 'native-workspace-pending-approvals/v1';
+const PENDING_TTL_MS = 10 * 60 * 1000;
+const HEX = /^[0-9a-f]{64}$/;
+
+/** A recorded observed revision of a workspace file. mtimeNs is a BigInt. */
+export function makeReadState(fields) {
+  return {
+    path: fields.path,
+    mtimeNs: BigInt(fields.mtimeNs),
+    sizeBytes: Number(fields.sizeBytes),
+    startLine: Number(fields.startLine),
+    endLine: Number(fields.endLine),
+    totalLines: Number(fields.totalLines),
+    partial: Boolean(fields.partial),
+    canonicalPath: fields.canonicalPath,
+    contentSha256: fields.contentSha256,
+  };
+}
+
+/** Serialize a read state for JSON storage (BigInt mtimeNs -> string). */
+export function serializeReadState(state) {
+  return {
+    path: state.path,
+    mtimeNs: state.mtimeNs.toString(),
+    sizeBytes: state.sizeBytes,
+    startLine: state.startLine,
+    endLine: state.endLine,
+    totalLines: state.totalLines,
+    partial: state.partial,
+    canonicalPath: state.canonicalPath,
+    contentSha256: state.contentSha256,
+  };
+}
+
+/** Deserialize a JSON-stored read state back to a BigInt-mtimeNs object. */
+export function deserializeReadState(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)
+    || typeof raw.path !== 'string' || !raw.path || isAbsolute(raw.path) || raw.path.includes('\0')
+    || raw.path.split('/').includes('..') || typeof raw.canonicalPath !== 'string' || !isAbsolute(raw.canonicalPath)
+    || typeof raw.contentSha256 !== 'string' || !HEX.test(raw.contentSha256)
+    || typeof raw.mtimeNs !== 'string' || !/^-?\d+$/.test(raw.mtimeNs)
+    || typeof raw.partial !== 'boolean') return null;
+  if (!['sizeBytes', 'startLine', 'endLine', 'totalLines'].every(key => Number.isSafeInteger(raw[key]))
+    || raw.sizeBytes < 0 || raw.startLine < 1 || raw.endLine < 0 || raw.totalLines < 0
+    || raw.endLine > raw.totalLines
+    || (raw.totalLines > 0 && (raw.startLine > raw.endLine || raw.endLine === 0))
+    || (!raw.partial && (raw.startLine !== 1 || raw.endLine !== raw.totalLines))) return null;
+  return makeReadState(raw);
+}
+
+export class WorkspaceStateStore {
+  constructor(stateDir, sessionId) {
+    this.sessionId = normalizeSessionId(sessionId);
+    // The on-disk directory is a sha256 hex of the normalized id, so a caller
+    // cannot traverse out of stateDir ("../x") or collide with another session
+    // by embedding a path separator. The original id is kept in the JSON files
+    // for inspection but never used as a filesystem path component.
+    this.sessionKey = sessionKeyFor(this.sessionId);
+    this.dir = join(stateDir, this.sessionKey);
+    this._readStatePath = join(this.dir, 'read-state.json');
+    this._pendingPath = join(this.dir, 'pending-approvals.json');
+    /** Map<relativePath, readState> (BigInt mtimeNs, in memory). */
+    this._readState = new Map();
+    /** Map<interactionId, pending> (in memory). */
+    this._pending = new Map();
+    this._loaded = false;
+  }
+
+  _ensureLoaded() {
+    if (this._loaded) return;
+    this._loaded = true;
+    this._readState = this._loadReadState();
+    this._pending = this._loadPending();
+  }
+
+  _loadReadState() {
+    try {
+      const raw = JSON.parse(readFileSync(this._readStatePath, 'utf-8'));
+      if (raw && raw.version === READ_STATE_VERSION && raw.sessionId === this.sessionId
+        && raw.entries && typeof raw.entries === 'object' && !Array.isArray(raw.entries)) {
+        this._conversationBranch = raw.conversationBranch;
+        const map = new Map();
+        for (const [key, value] of Object.entries(raw.entries)) {
+          const state = deserializeReadState(value);
+          // Drop entries missing the fields validateReadState needs; an edit
+          // against a dropped entry is correctly re-rejected as file_not_read
+          // rather than crashing the restart on a BigInt/NaN coercion.
+          if (state && state.path === key) {
+            map.set(key, state);
+          }
+        }
+        return map;
+      }
+    } catch { /* missing or corrupt: start clean */ }
+    return new Map();
+  }
+
+  _loadPending() {
+    try {
+      const raw = JSON.parse(readFileSync(this._pendingPath, 'utf-8'));
+      if (raw && raw.version === PENDING_VERSION && raw.sessionId === this.sessionId
+        && raw.entries && typeof raw.entries === 'object' && !Array.isArray(raw.entries)) {
+        return new Map(Object.entries(raw.entries).filter(([id, pending]) => pending && pending.interactionId === id
+          && typeof pending.callId === 'string' && pending.callId.trim() && typeof pending.name === 'string' && pending.name.trim()
+          && typeof pending.argumentsDigest === 'string' && HEX.test(pending.argumentsDigest)
+          && Number.isSafeInteger(pending.createdAt) && pending.createdAt >= 0
+          && Number.isSafeInteger(pending.expiresAt) && pending.expiresAt >= pending.createdAt));
+      }
+    } catch { /* missing or corrupt: start clean */ }
+    return new Map();
+  }
+
+  _persistReadState() {
+    this._ensureDir();
+    const payload = {
+      version: READ_STATE_VERSION,
+      sessionId: this.sessionId,
+      ...(this._conversationBranch ? { conversationBranch: this._conversationBranch } : {}),
+      entries: Object.fromEntries(
+        [...this._readState.values()].map(serializeReadState).map((s) => [s.path, s]),
+      ),
+    };
+    atomicWriteJson(this._readStatePath, payload);
+  }
+
+  _persistPending() {
+    this._ensureDir();
+    const payload = {
+      version: PENDING_VERSION,
+      sessionId: this.sessionId,
+      entries: Object.fromEntries(this._pending),
+    };
+    atomicWriteJson(this._pendingPath, payload);
+  }
+
+  _ensureDir() {
+    mkdirSync(this.dir, { recursive: true });
+  }
+
+  getReadState(relativePath) {
+    this._ensureLoaded();
+    return this._readState.get(relativePath);
+  }
+
+  recordReadState(state) {
+    this._ensureLoaded();
+    this._readState.set(state.path, state);
+    this._persistReadState();
+  }
+
+  clearReadState() {
+    this._ensureLoaded();
+    this._readState.clear();
+    this._persistReadState();
+  }
+
+  adoptConversationBranch(branch, restore = () => []) {
+    if (!branch) return;
+    if (!Number.isSafeInteger(branch.generation) || branch.generation < 1 || typeof branch.commandId !== 'string' || !branch.commandId.trim())
+      throw Object.assign(Error('workspace_read_branch_invalid'), { code: 'workspace_read_branch_invalid' });
+    this._ensureLoaded();
+    if (this._conversationBranch?.generation === branch.generation && this._conversationBranch.commandId === branch.commandId) return;
+    if (this._conversationBranch?.generation >= branch.generation)
+      throw Object.assign(Error('workspace_read_branch_conflict'), { code: 'workspace_read_branch_conflict' });
+    // Never let a read on the removed branch authorize an edit after rewind.
+    // Fresh reads in this generation remain valid across later turns/restarts.
+    const retained = new Map();
+    for (const raw of restore()) {
+      const state = deserializeReadState(raw);
+      if (state && !state.partial) retained.set(state.path, state);
+    }
+    const previousReads = this._readState, previousBranch = this._conversationBranch;
+    this._readState = retained; this._conversationBranch = { ...branch };
+    try { this._persistReadState(); }
+    catch (error) { this._readState = previousReads; this._conversationBranch = previousBranch; throw error; }
+  }
+
+  addPending({ callId, name, argumentsDigest, ttlMs = PENDING_TTL_MS }) {
+    this._ensureLoaded();
+    const now = Date.now();
+    const interactionId = randomUUID();
+    const pending = {
+      interactionId,
+      callId,
+      name,
+      argumentsDigest,
+      createdAt: now,
+      expiresAt: now + ttlMs,
+    };
+    this._pending.set(interactionId, pending);
+    this._persistPending();
+    return pending;
+  }
+
+  getPending(interactionId) {
+    this._ensureLoaded();
+    const pending = this._pending.get(interactionId);
+    if (!pending) return undefined;
+    if (pending.expiresAt < Date.now()) {
+      this._pending.delete(interactionId);
+      this._persistPending();
+      return undefined;
+    }
+    return pending;
+  }
+
+  consumePending(interactionId) {
+    this._ensureLoaded();
+    const pending = this._pending.get(interactionId);
+    if (!pending) return undefined;
+    this._pending.delete(interactionId);
+    this._persistPending();
+    if (pending.expiresAt < Date.now()) return undefined;
+    return pending;
+  }
+}
+
+/** Write JSON atomically (temp sibling + rename) to avoid torn reads on restart. */
+export function atomicWriteJson(dest, value) {
+  const dir = join(dest, '..');
+  mkdirSync(dir, { recursive: true });
+  const tmp = join(dir, `.${dest.split('/').pop()}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`);
+  writeFileSync(tmp, JSON.stringify(value), 'utf-8');
+  renameSync(tmp, dest);
+}
+
+/**
+ * The sha256 directory key contains no path separators, so identifiers cannot
+ * traverse out of stateDir. Stored records also carry the original identity.
+ */
+export function sessionKeyFor(sessionId) {
+  const digest = createHash('sha256').update(normalizeSessionId(sessionId), 'utf-8').digest('hex');
+  return HEX.test(digest) ? digest : 'default';
+}
+
+function normalizeSessionId(sessionId) {
+  if (sessionId === undefined) return 'default';
+  if (typeof sessionId !== 'string' || !sessionId.trim()) throw new TypeError('workspace sessionId must be a nonempty string');
+  return sessionId;
+}
+
+/** sha256 hex digest of a JSON-serializable value (stable key order). */
+export function argumentsDigest(value) {
+  return createHash('sha256').update(JSON.stringify(value ?? null)).digest('hex');
+}