agent-working-memory 0.17.0 → 0.19.0

package/src/core/model-daemon-server.ts

@@ -0,0 +1,344 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The shared model daemon process (see model-daemon.ts for the design).
+ *
+ * It runs ONE inference at a time. onnxruntime-node's CPU arena grows to the largest
+ * tensor a session has run, so concurrent runs on the same session would multiply the
+ * high-water mark this daemon exists to bound. One at a time costs no speed: four
+ * processes recalling at once on one machine finished in 12.3 min with their own models
+ * and 11.6 min through one daemon, because they compete for the same cores anyway.
+ *
+ * Scheduling: interactive requests run before background ones. An embed is run one
+ * chunk at a time; an unfinished interactive embed goes to the back of its lane, so
+ * sessions take turns and one session's 100-memory write-batch cannot hold up another
+ * session's recall; an unfinished background embed goes to the front of its lane, so
+ * its chunks stay in order. A request whose connection has closed is dropped unrun.
+ * Each step reports `started` when it begins, and a job sent back to the queue between
+ * chunks reports `requeued`, so a client's run timer covers only time the daemon spends
+ * on its job: its timeout measures a stuck daemon, never a busy one. A step that runs
+ * longer than AWM_MODEL_DAEMON_STUCK_MS (default: the client's step timeout, 2 min; for
+ * a warm, which may download the models, the client's 10 min) means the daemon is wedged
+ * on a promise that will never settle: it exits, and the next client starts a fresh one.
+ * The two limits are the same so that a client that gave up on a step is never left
+ * reconnecting to the daemon still stuck on it.
+ *
+ * The daemon exits when no authenticated client has been connected for
+ * AWM_MODEL_DAEMON_IDLE_MS (default 5 min). Clients hold one connection each for the
+ * life of their process.
+ */
+
+import { createServer, connect, type Server, type Socket } from 'node:net';
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { setTimeout as delay } from 'node:timers/promises';
+import {
+  PROTOCOL_VERSION, HELLO_MAX_BYTES, MAX_FRAME_BYTES, addressProblem, encodeFrame, envInt, FrameReader,
+  modelDaemonPaths, proof, proofMatches, runDirProblem, REQUEST_TIMEOUT_MS, WARM_TIMEOUT_MS,
+  type AuthFrame, type HelloFrame, type Lane, type RequestFrame, type ResponseFrame,
+} from './model-daemon.js';
+import { VERSION } from '../version.js';
+
+export interface DaemonHandlers {
+  embed(args: { texts: string[]; pooling: 'cls' | 'mean'; dimensions: number }): Promise<number[][]>;
+  rerank(args: { query: string; passages: string[] }): Promise<Array<{ index: number; score: number }>>;
+  expand(args: { prompt: string; maxNewTokens: number; noRepeatNgramSize: number }): Promise<string>;
+  warm(): Promise<void>;
+  /** Texts per scheduling step for an embed; 0 = the whole request at once. */
+  embedChunk: number;
+}
+
+export interface DaemonOptions {
+  fingerprint: string;
+  runDir?: string;
+  idleMs?: number;
+  handlers: DaemonHandlers;
+  log?: (msg: string) => void;
+  /** Called when the idle lease runs out, after the server has closed. The entry exits. */
+  onIdle?: () => void;
+  /** A step running longer than this is wedged (a warm gets WARM_TIMEOUT_MS at least). */
+  stuckMs?: number;
+  /** Called when a step is wedged. The entry exits with an error. */
+  onStuck?: () => void;
+}
+
+interface Job {
+  socket: Socket;
+  id: number;
+  op: RequestFrame['op'];
+  lane: Lane;
+  args: any;
+  /** Embed: the next slice to run and the vectors so far. */
+  offset?: number;
+  vectors?: number[][];
+}
+
+export interface RunningDaemon {
+  server: Server;
+  address: string;
+  fingerprint: string;
+  close(): Promise<void>;
+}
+
+const HELLO_TIMEOUT_MS = 5_000;
+
+/** Windows refuses a rename over a file another process has open; clients open it briefly. */
+async function replaceFile(tmp: string, target: string): Promise<void> {
+  for (let attempt = 0; ; attempt++) {
+    try { renameSync(tmp, target); return; } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if ((code !== 'EPERM' && code !== 'EBUSY' && code !== 'EACCES') || attempt >= 40) {
+        try { unlinkSync(tmp); } catch { /* nothing to clean */ }
+        throw err;
+      }
+      await delay(25);
+    }
+  }
+}
+
+/** A unix socket file left by a crashed daemon refuses connections; a live one accepts. */
+function removeStaleSocket(address: string): Promise<void> {
+  if (process.platform === 'win32' || !existsSync(address)) return Promise.resolve();
+  return new Promise(resolve => {
+    const probe = connect(address);
+    probe.once('connect', () => { probe.destroy(); resolve(); });
+    probe.once('error', () => { try { unlinkSync(address); } catch { /* raced */ } resolve(); });
+  });
+}
+
+export async function startModelDaemon(opts: DaemonOptions): Promise<RunningDaemon> {
+  const { fingerprint } = opts;
+  const paths = modelDaemonPaths(fingerprint, opts.runDir);
+  const idleMs = opts.idleMs ?? envInt('AWM_MODEL_DAEMON_IDLE_MS', 300_000);
+  const log = opts.log ?? ((m: string) => console.error(`[model-daemon ${new Date().toISOString()}] ${m}`));
+  const h = opts.handlers;
+
+  const problem = addressProblem(paths);
+  if (problem) throw new Error(problem);
+  mkdirSync(paths.runDir, { recursive: true, mode: 0o700 });
+  try { chmodSync(paths.runDir, 0o700); } catch { /* not ours to change, or Windows */ }
+  const unsafe = runDirProblem(paths.runDir);
+  if (unsafe) throw new Error(unsafe);
+  const stuckMs = opts.stuckMs ?? envInt('AWM_MODEL_DAEMON_STUCK_MS', envInt('AWM_MODEL_DAEMON_TIMEOUT_MS', REQUEST_TIMEOUT_MS));
+  await removeStaleSocket(paths.address);
+
+  const token = randomBytes(32).toString('hex');
+  const sockets = new Set<Socket>();   // every connection, authenticated or not
+  /** Requests a client gave up on, per connection: never started, or never continued. */
+  const cancelled = new WeakMap<Socket, Set<number>>();
+  const isCancelled = (job: Job) => cancelled.get(job.socket)?.has(job.id) ?? false;
+  /** Until the token file is ours, a hello is told to retry, not proved with a token the
+   * file does not hold yet (the rename may be retried on Windows). */
+  let tokenReady = false;
+  const clients = new Set<Socket>();   // authenticated ones: these hold the lease
+  const interactive: Job[] = [];
+  const background: Job[] = [];
+  const served: Record<string, number> = {};
+  const startedAt = Date.now();
+  let busy = false;
+  let current: { op: string; since: number } | null = null;
+  let idleTimer: ReturnType<typeof setTimeout> | null = null;
+  let closing: Promise<void> | null = null;
+
+  const send = (socket: Socket, frame: ResponseFrame) => {
+    if (!socket.destroyed) socket.write(encodeFrame(frame));
+  };
+
+  const armIdle = () => {
+    if (idleTimer || clients.size > 0 || idleMs <= 0 || closing) return;
+    idleTimer = setTimeout(() => {
+      idleTimer = null;
+      if (clients.size > 0) return;
+      // A step still running (a first-run warm downloading the models) finishes first.
+      if (current || interactive.length || background.length) { armIdle(); return; }
+      log(`no clients for ${idleMs} ms, exiting`);
+      void running.close().then(() => (opts.onIdle ?? (() => process.exit(0)))());
+    }, idleMs);
+    idleTimer.unref?.();
+  };
+
+  /** Runs one step of a job. Returns true when the job is finished. */
+  async function step(job: Job): Promise<boolean> {
+    send(job.socket, { id: job.id, started: true });
+    if (job.vectors) {
+      const texts: string[] = job.args.texts;
+      const size = h.embedChunk > 0 ? h.embedChunk : texts.length;
+      const slice = texts.slice(job.offset!, job.offset! + size);
+      job.vectors.push(...await h.embed({ ...job.args, texts: slice }));
+      job.offset! += slice.length;
+      if (job.offset! < texts.length) return false;
+      send(job.socket, { id: job.id, ok: true, result: job.vectors });
+      return true;
+    }
+    let result: unknown;
+    switch (job.op) {
+      case 'embed': result = await h.embed(job.args); break;
+      case 'rerank': result = await h.rerank(job.args); break;
+      case 'expand': result = await h.expand(job.args); break;
+      case 'warm': await h.warm(); result = true; break;
+      default: throw new Error(`unknown op ${String(job.op)}`);
+    }
+    send(job.socket, { id: job.id, ok: true, result });
+    return true;
+  }
+
+  async function pump(): Promise<void> {
+    if (busy) return;
+    busy = true;
+    try {
+      for (;;) {
+        const job = interactive.shift() ?? background.shift();
+        if (!job) break;
+        if (job.socket.destroyed || isCancelled(job)) continue;
+        let done = true;
+        current = { op: job.op, since: Date.now() };
+        try {
+          done = await step(job);
+        } catch (err) {
+          send(job.socket, { id: job.id, ok: false, error: (err as Error)?.message ?? String(err) });
+        } finally {
+          current = null;
+        }
+        if (done) { served[job.op] = (served[job.op] ?? 0) + 1; continue; }
+        // Back in the queue between chunks: the client's run timer stops until the next
+        // step starts, because waiting here is the daemon being busy, not stuck.
+        if (isCancelled(job)) continue;
+        send(job.socket, { id: job.id, requeued: true });
+        if (job.lane === 'interactive') interactive.push(job);
+        else background.unshift(job);
+      }
+    } finally {
+      busy = false;
+    }
+  }
+
+  const onRequest = (socket: Socket, frame: RequestFrame) => {
+    if (typeof frame?.id !== 'number') return;
+    if (frame.op === 'cancel') {
+      // The client gave up waiting: drop the job, or stop it after its running step.
+      const id = (frame.args as any)?.id;
+      if (typeof id !== 'number') return;
+      let set = cancelled.get(socket);
+      if (!set) cancelled.set(socket, (set = new Set()));
+      if (set.size >= 10_000) set.clear();
+      set.add(id);
+      for (const q of [interactive, background]) {
+        const i = q.findIndex(j => j.socket === socket && j.id === id);
+        if (i >= 0) q.splice(i, 1);
+      }
+      return;
+    }
+    if (frame.op === 'stats') {
+      send(socket, {
+        id: frame.id, ok: true, result: {
+          pid: process.pid, fingerprint, version: VERSION, uptimeMs: Date.now() - startedAt,
+          clients: clients.size, queued: { interactive: interactive.length, background: background.length },
+          served, rssBytes: process.memoryUsage().rss,
+          current: current ? { op: current.op, runningMs: Date.now() - current.since } : null,
+        },
+      });
+      return;
+    }
+    const lane: Lane = frame.lane === 'background' ? 'background' : 'interactive';
+    const job: Job = { socket, id: frame.id, op: frame.op, lane, args: frame.args };
+    if (frame.op === 'embed' && Array.isArray((frame.args as any)?.texts)) {
+      job.offset = 0;
+      job.vectors = [];
+    }
+    (lane === 'background' ? background : interactive).push(job);
+    void pump();
+  };
+
+  const server = createServer(socket => {
+    sockets.add(socket);
+    socket.setEncoding('utf8');
+    let stage: 'hello' | 'auth' | 'ready' = 'hello';
+    let clientNonce = '';
+    let daemonNonce = '';
+    const helloTimer = setTimeout(() => socket.destroy(), HELLO_TIMEOUT_MS);
+    const refuse = (error: string) => { clearTimeout(helloTimer); socket.end(encodeFrame({ t: 'hello', ok: false, error })); };
+    const reader = new FrameReader(frame => {
+      if (stage === 'ready') return onRequest(socket, frame as RequestFrame);
+      if (closing) return refuse('closing');
+      if (!tokenReady) return refuse('starting');
+      if (stage === 'hello') {
+        const hello = frame as HelloFrame;
+        if (hello?.t !== 'hello') return refuse('expected hello');
+        if (hello.protocol !== PROTOCOL_VERSION) return refuse(`protocol ${hello.protocol} != ${PROTOCOL_VERSION}`);
+        if (hello.fingerprint !== fingerprint) return refuse('fingerprint mismatch');
+        if (typeof hello.nonce !== 'string' || hello.nonce.length < 32) return refuse('bad nonce');
+        clientNonce = hello.nonce;
+        daemonNonce = randomBytes(16).toString('hex');
+        stage = 'auth';
+        socket.write(encodeFrame({
+          t: 'challenge', nonce: daemonNonce, pid: process.pid, version: VERSION,
+          proof: proof(token, 'daemon', clientNonce, daemonNonce, fingerprint),
+        }));
+        return;
+      }
+      const auth = frame as AuthFrame;
+      if (auth?.t !== 'auth' || !proofMatches(proof(token, 'client', clientNonce, daemonNonce, fingerprint), auth.proof)) {
+        return refuse('bad token');
+      }
+      clearTimeout(helloTimer);
+      stage = 'ready';
+      reader.limit = MAX_FRAME_BYTES;
+      clients.add(socket);
+      if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+      socket.write(encodeFrame({ t: 'hello', ok: true }));
+    }, HELLO_MAX_BYTES);
+    socket.on('data', (chunk: string) => { if (!reader.push(chunk)) socket.destroy(); });
+    socket.on('error', () => { /* the close handler cleans up */ });
+    socket.on('close', () => {
+      clearTimeout(helloTimer);
+      sockets.delete(socket);
+      if (clients.delete(socket)) armIdle();
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(paths.address, () => { server.off('error', reject); resolve(); });
+  });
+  if (process.platform !== 'win32') { try { chmodSync(paths.address, 0o600); } catch { /* best effort */ } }
+  // The token is written only once this daemon owns the address. A second daemon that
+  // lost the race (EADDRINUSE above) must not overwrite the live one's token. A client
+  // that connected in the gap read no token or an old one; it is refused and retries.
+  const tmp = `${paths.token}.${process.pid}`;
+  writeFileSync(tmp, token, { mode: 0o600 });
+  try {
+    await replaceFile(tmp, paths.token);
+  } catch (err) {
+    server.close();
+    throw err;
+  }
+  tokenReady = true;
+  log(`listening on ${paths.address} (pid ${process.pid}, AWM ${VERSION}, fingerprint ${fingerprint})`);
+  armIdle();
+
+  const watchdog = stuckMs > 0 ? setInterval(() => {
+    if (!current) return;
+    const limit = current.op === 'warm' ? Math.max(stuckMs, WARM_TIMEOUT_MS) : stuckMs;
+    if (Date.now() - current.since <= limit) return;
+    log(`${current.op} has run for ${Date.now() - current.since} ms: wedged, exiting so a fresh daemon can start`);
+    if (watchdog) clearInterval(watchdog);
+    void running.close().then(() => (opts.onStuck ?? (() => process.exit(1)))());
+  }, Math.min(5_000, Math.max(50, Math.floor(stuckMs / 4)))) : null;
+  watchdog?.unref?.();
+
+  const running: RunningDaemon = {
+    server, address: paths.address, fingerprint,
+    close: () => (closing ??= new Promise<void>(resolve => {
+      if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
+      if (watchdog) clearInterval(watchdog);
+      // Every connection, including one still in its handshake: server.close() waits for
+      // all of them, and a late hello must not authenticate against a closing daemon.
+      for (const s of sockets) s.destroy();
+      server.close(() => {
+        try { if (readFileSync(paths.token, 'utf8') === token) unlinkSync(paths.token); } catch { /* already gone */ }
+        resolve();
+      });
+    })),
+  };
+  return running;
+}

package/src/core/model-daemon.ts

@@ -0,0 +1,243 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Shared model daemon: what the client and the daemon agree on.
+ *
+ * Every AWM MCP process used to load its own three ONNX models (embedder, cross-encoder,
+ * query expander): about 1.1 GB per process even with the input-shape caps, so six
+ * Claude Code sessions held 6+ GB of identical weights and arenas. With
+ * AWM_MODEL_DAEMON=1, one per-user process holds the models and every AWM process on the
+ * machine sends inference to it over a local socket. Store, engine and recall stay in
+ * each process; only the three dispatch calls in ml-worker.ts cross the socket.
+ *
+ * This module has no model imports, so a client that only talks to the daemon never
+ * loads @huggingface/transformers' models itself.
+ *
+ * - The daemon is keyed by a FINGERPRINT of the inference config the model modules
+ *   actually captured (model ids, dtype, dimensions, pooling, shape caps), the model
+ *   cache dir, the AWM version and package root, the user and the run dir. Two installs,
+ *   two versions or two configs get separate daemons and can never mix vectors. The
+ *   spawned daemon is given the client's captured config as env, so a value applied
+ *   after the modules loaded (a .env file) cannot make the two disagree; the handshake
+ *   checks the fingerprint again.
+ * - Transport: a named pipe on Windows, a unix socket in ~/.awm/run (0700) elsewhere.
+ * - Authentication is mutual, by HMAC over two nonces with the token the daemon wrote to
+ *   the run dir (0600). The token itself never crosses the socket, so a process that
+ *   took the pipe name first learns nothing and is refused by the client.
+ * - Frames are newline-delimited JSON. JSON.stringify escapes every newline inside a
+ *   value, so a newline only ever ends a frame. Before authentication a connection may
+ *   send HELLO_MAX_BYTES; after it, MAX_FRAME_BYTES.
+ */
+
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir, userInfo } from 'node:os';
+import { dirname, join, relative, resolve, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { VERSION } from '../version.js';
+
+export const PROTOCOL_VERSION = 2;
+export const MAX_FRAME_BYTES = 64 * 1024 * 1024;
+export const HELLO_MAX_BYTES = 4 * 1024;
+/** A step must finish within this (client run timer and daemon watchdog both). */
+export const REQUEST_TIMEOUT_MS = 120_000;
+/** The first warm can include a first-run model download (client and daemon both). */
+export const WARM_TIMEOUT_MS = 10 * 60_000;
+/** Exit code of a daemon whose own fingerprint is not the one its spawner expected. */
+export const EXIT_FINGERPRINT_DRIFT = 3;
+/** Longest unix socket path every platform accepts (macOS: 104 bytes with the NUL). */
+const UNIX_SOCKET_MAX = 103;
+
+export type ModelOp = 'embed' | 'rerank' | 'expand' | 'warm' | 'stats' | 'cancel';
+/** Interactive work (prime hook, recall, writes) runs ahead of background backfill. */
+export type Lane = 'interactive' | 'background';
+
+/** What the model modules captured at import; registered with ml-worker. */
+export type InferenceConfig = Record<string, string | number>;
+
+/** Client → daemon, first frame. */
+export interface HelloFrame { t: 'hello'; protocol: number; fingerprint: string; nonce: string }
+/** Daemon → client: its proof, and a refusal carries `error`. */
+export interface ChallengeFrame { t: 'challenge'; nonce: string; proof: string; pid: number; version: string }
+/** Client → daemon: the client's proof. */
+export interface AuthFrame { t: 'auth'; proof: string }
+export interface HelloResult { t: 'hello'; ok: boolean; error?: string }
+export interface RequestFrame { id: number; op: ModelOp; lane?: Lane; args?: unknown }
+/** `started` starts the client's run timer and `requeued` stops it; the final frame has `ok`. */
+export interface ResponseFrame { id: number; ok?: boolean; started?: true; requeued?: true; result?: unknown; error?: string }
+
+/** Env names the config is passed to a spawned daemon as. */
+const CONFIG_ENV: Record<string, string> = {
+  embedModel: 'AWM_EMBED_MODEL', embedDims: 'AWM_EMBED_DIMS', embedPooling: 'AWM_EMBED_POOLING',
+  embedBatch: 'AWM_EMBED_BATCH', rerankModel: 'AWM_RERANKER_MODEL', rerankDtype: 'AWM_RERANKER_DTYPE',
+  rerankBatch: 'AWM_RERANK_BATCH', rerankQueryTokens: 'AWM_RERANK_QUERY_TOKENS',
+};
+
+export function configEnv(config: InferenceConfig): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [k, name] of Object.entries(CONFIG_ENV)) if (config[k] !== undefined) env[name] = String(config[k]);
+  return env;
+}
+
+function safeUser(): string {
+  try { return userInfo().username; } catch { return process.env.USERNAME ?? process.env.USER ?? ''; }
+}
+
+export function packageRoot(): string {
+  // src/core/model-daemon.ts (dev) and dist/core/model-daemon.js (build): two levels up.
+  return resolve(join(dirname(fileURLToPath(import.meta.url)), '..', '..'));
+}
+
+export function defaultRunDir(env: NodeJS.ProcessEnv = process.env): string {
+  return env.AWM_RUN_DIR || join(homedir(), '.awm', 'run');
+}
+
+/**
+ * Size and mtime of the modules whose code decides what inference returns. A rebuild or
+ * a dev edit without a version bump is a different daemon, not the old one serving old
+ * code to new clients. The client and the daemon run from the same files, so they agree.
+ */
+export function codeStamp(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const ext = import.meta.url.endsWith('.ts') ? '.ts' : '.js';
+  const files = ['embeddings', 'reranker', 'query-expander', 'model-daemon', 'model-daemon-server', 'ml-worker', 'rerank-window']
+    .map(m => { try { const s = statSync(join(here, m + ext)); return `${m}:${s.size}:${Math.floor(s.mtimeMs)}`; } catch { return `${m}:-`; } });
+  // An `npm update` of the inference libraries changes results without an AWM version bump.
+  const req = createRequire(import.meta.url);
+  const libs = ['@huggingface/transformers', 'onnxruntime-node'].map(name => {
+    // Not `${name}/package.json`: a package's "exports" may not expose it.
+    try {
+      for (let dir = dirname(req.resolve(name)); dir !== dirname(dir); dir = dirname(dir)) {
+        try {
+          const pkg = req(join(dir, 'package.json'));
+          if (pkg.name === name) return `${name}@${pkg.version}`;
+        } catch { /* keep walking up */ }
+      }
+    } catch { /* not installed */ }
+    return `${name}@-`;
+  });
+  return [...files, ...libs].join(',');
+}
+
+/** 16 hex chars. Everything is a parameter so tests can compare configs in one process. */
+export function modelDaemonFingerprint(
+  config: InferenceConfig,
+  o: { env?: NodeJS.ProcessEnv; version?: string; root?: string; code?: string } = {},
+): string {
+  const env = o.env ?? process.env;
+  const parts = [
+    `protocol=${PROTOCOL_VERSION}`, `version=${o.version ?? VERSION}`, `root=${o.root ?? packageRoot()}`,
+    `code=${o.code ?? codeStamp()}`,
+    `user=${safeUser()}`, `home=${homedir()}`, `run=${defaultRunDir(env)}`,
+    // Read lazily by model-cache.ts, so the env at this point is the env it would use.
+    `cache=${env.AWM_CACHE_DIR || env.HF_HOME || ''}`,
+    ...Object.keys(config).sort().map(k => `${k}=${config[k]}`),
+  ];
+  return createHash('sha256').update(parts.join('\n')).digest('hex').slice(0, 16);
+}
+
+export interface DaemonPaths {
+  runDir: string;
+  /** Pipe name on Windows, socket path elsewhere. */
+  address: string;
+  token: string;
+  lock: string;
+  log: string;
+}
+
+export function modelDaemonPaths(fingerprint: string, runDir: string = defaultRunDir()): DaemonPaths {
+  const base = join(runDir, `models-${fingerprint}`);
+  return {
+    runDir,
+    // Windows pipe names are one machine-wide namespace; the fingerprint includes the
+    // user, home and run dir, so two users never share a name by accident.
+    address: process.platform === 'win32' ? `\\\\.\\pipe\\awm-models-${fingerprint}` : `${base}.sock`,
+    token: `${base}.token`,
+    lock: `${base}.lock`,
+    log: `${base}.log`,
+  };
+}
+
+/** A unix socket path the OS will refuse, or null. */
+export function addressProblem(paths: DaemonPaths): string | null {
+  if (process.platform === 'win32') return null;
+  return Buffer.byteLength(paths.address) > UNIX_SOCKET_MAX
+    ? `socket path is ${Buffer.byteLength(paths.address)} bytes (max ${UNIX_SOCKET_MAX}); set AWM_RUN_DIR to a shorter directory you own (not a shared one like /tmp)`
+    : null;
+}
+
+/**
+ * A run dir another user can write to, or that this user does not own, is refused off
+ * Windows: the token and the log are written there, and another user could plant a
+ * symlink in their place. (On Windows the dir sits under the user's profile, whose ACL
+ * already excludes other users.)
+ */
+export function runDirProblem(runDir: string): string | null {
+  if (process.platform === 'win32') {
+    // No uid to compare. The profile's ACL excludes other users; a dir outside it
+    // (C:\Users\Public, a shared drive) may not.
+    const rel = relative(homedir(), resolve(runDir));
+    return rel && (rel.startsWith('..') || isAbsolute(rel)) ? `run dir ${runDir} is outside your user profile` : null;
+  }
+  if (typeof process.getuid !== 'function') return null;
+  try {
+    const s = statSync(runDir);
+    if (s.uid !== process.getuid()) return `run dir ${runDir} is not owned by this user`;
+    if (s.mode & 0o022) return `run dir ${runDir} is writable by other users`;
+    return null;
+  } catch (err) {
+    return `run dir ${runDir}: ${(err as Error).message}`;
+  }
+}
+
+export function proof(token: string, role: 'daemon' | 'client', clientNonce: string, daemonNonce: string, fingerprint: string): string {
+  return createHmac('sha256', token).update(`${role}|${clientNonce}|${daemonNonce}|${fingerprint}`).digest('hex');
+}
+
+export function proofMatches(expected: string, got: unknown): boolean {
+  if (typeof got !== 'string' || got.length !== expected.length) return false;
+  return timingSafeEqual(Buffer.from(expected), Buffer.from(got));
+}
+
+/**
+ * Splits a byte stream into frames. push() returns false when the unterminated tail is
+ * over `limit`. Chunks without a newline are kept as a list and only the new chunk is
+ * searched, so a long frame arriving in many chunks costs linear time: appending to one
+ * string and searching it again would copy the whole buffer on every chunk.
+ */
+export class FrameReader {
+  private parts: string[] = [];
+  private size = 0;
+  constructor(private readonly onFrame: (frame: unknown) => void, public limit = MAX_FRAME_BYTES) {}
+
+  push(chunk: string): boolean {
+    let nl: number;
+    while ((nl = chunk.indexOf('\n')) >= 0) {
+      const line = this.parts.length ? this.parts.join('') + chunk.slice(0, nl) : chunk.slice(0, nl);
+      this.parts = [];
+      this.size = 0;
+      chunk = chunk.slice(nl + 1);
+      if (!line) continue;
+      let frame: unknown;
+      try { frame = JSON.parse(line); } catch { return false; }
+      this.onFrame(frame);
+    }
+    if (chunk) { this.parts.push(chunk); this.size += chunk.length; }
+    return this.size <= this.limit;
+  }
+}
+
+export function encodeFrame(frame: unknown): string {
+  return `${JSON.stringify(frame)}\n`;
+}
+
+export function isModelDaemonEnabled(): boolean {
+  return process.env.AWM_MODEL_DAEMON === '1';
+}
+
+/** Non-negative integer env var; anything else falls back (an explicit 0 is kept). */
+export function envInt(name: string, fallback: number): number {
+  const v = Number(process.env[name]?.trim() || NaN);
+  return Number.isInteger(v) && v >= 0 ? v : fallback;
+}