@mnemom/mnemom 0.17.34-next.1 → 0.17.34-next.2

package/dist/durable/seat-proxy.js

@@ -0,0 +1,599 @@
+// The durable seat proxy: the fail-closed terminal credential proxy in front of one durable seat
+// (BACKBONE C3; C13-R1..R12, R14, R15). Run as the hidden `mnemom agent host seat-proxy`, which in
+// product only the host daemon spawns:
+//
+//   mnemom agent host seat-proxy --conversation <uuid> --agent-id <uuid> --door <url> --cwd <dir>
+//       [--session <uuid> --epoch <n> --spawn-id <uuid> [--hello-relay <unix socket>]]
+//
+// The lease key arrives as ONE line on stdin and is never read from the environment, written to a
+// file or logged. The owner's provider credential (claude's x-api-key, or its claude.ai login in
+// authorization) passes through to the door unchanged, exactly as on a `mnemom agent` launch, and is
+// never held past the request, written or logged (dogfood B6). CLAUDE_CONFIG_DIR (env) locates Claude Code's transcript. The optional seat ids
+// (all non-secret) are the seat the daemon registered for this epoch; only they get a hello through
+// the seat socket. stdout gets exactly one line, `READY <port> <socket path>`, once listening.
+//
+// Exit codes (C13 test hooks): 2 config or key refused (no READY), 3 conversation lock held,
+// 4 the door said the key is dead (409 durable_lease_fenced, 401 durable_key_revoked, 410
+// durable_session_ended or durable_unlocked). Log lines (MNEMOM_DURABLE_PROXY_LOG, else stderr)
+// carry the drop reason enum and the exit reason, never a credential, header value or body byte.
+import fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import os from "node:os";
+import { randomBytes } from "node:crypto";
+import { TurnOrigins, claudeConfigDir, TURN_HEADER } from "../turn-origin.mjs";
+import { httpDoorAllowed } from "./test-mode.mjs";
+import { durableTurnHeaderFor } from "./turn-chain.js";
+import { tryLockFile } from "./flock.js";
+import { startSeatSocket, seatSocketPath, unixLineRelay, } from "./seat-socket.js";
+import { ARM_DROP_BODY, ARM_DROP_HEADERS, ARM_DROP_STATUS, ARM_HEADER, armForwardsFor, COUNT_TOKENS_PATH, isWellFormedLeaseKey, parseArm, proxyLockPath, } from "../vendor/durable-contract/index.js";
+export const EXIT_CONFIG = 2;
+export const EXIT_LOCK_HELD = 3;
+export const EXIT_KEY_DEAD = 4;
+const UUID_I = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** A pinned Mnemom agent id, the x-mnemom-agent-id the gateway honours (mirrors AGENT_ID_RE in lib/agent.ts). */
+const AGENT_ID_RE = /^mnm-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const MESSAGES_PATH = "/v1/messages";
+/** The most a dead-key-status (401/409/410) body is buffered to; a longer one is dropped, never truncated. */
+export const DEAD_BODY_CAP = 1024 * 1024;
+/** The largest request body forwarded (the Messages API request limit); a larger one gets a local 413. */
+export const REQUEST_BODY_CAP = 32 * 1024 * 1024;
+const HOP = new Set([
+    "connection",
+    "proxy-connection",
+    "keep-alive",
+    "upgrade",
+    "host",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "content-length",
+]);
+/**
+ * Client headers that never pass: hop-by-hop, proxy-authorization and every x-mnemom-* (the proxy
+ * sets the Mnemom ones from the lease). The provider credential (authorization, x-api-key) passes:
+ * the seat carries it exactly as `mnemom agent` does (dogfood B6 ruling, superseding C13-R2/R8).
+ */
+export function isStrippedClientHeader(name) {
+    const n = name.toLowerCase();
+    return HOP.has(n) || n.startsWith("x-mnemom-") || n === "proxy-authorization";
+}
+const OPTION_KEYS = {
+    "--conversation": "conversation",
+    "--agent-id": "agentId",
+    "--door": "door",
+    "--cwd": "cwd",
+    "--session": "session",
+    "--epoch": "epoch",
+    "--spawn-id": "spawnId",
+    "--hello-relay": "helloRelay",
+};
+/**
+ * Parse and validate the argv after `seat-proxy`. Errors name the option, never echo a value.
+ * `isDir` and `env` are injected so the check is pure.
+ */
+export function parseSeatProxyArgs(argv, env, isDir) {
+    const raw = {};
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        const eq = tok.indexOf("=");
+        const name = eq > 0 ? tok.slice(0, eq) : tok;
+        const key = OPTION_KEYS[name];
+        if (!key)
+            return { ok: false, error: "unknown argument" };
+        if (key in raw)
+            return { ok: false, error: `${name} given twice` };
+        let value;
+        if (eq > 0)
+            value = tok.slice(eq + 1);
+        else {
+            value = argv[i + 1];
+            i++;
+        }
+        if (value === undefined)
+            return { ok: false, error: `${name} needs a value` };
+        raw[key] = value;
+    }
+    if (!raw.conversation || !UUID_I.test(raw.conversation))
+        return { ok: false, error: "--conversation must be the registry conversation uuid" };
+    if (!raw.agentId || !AGENT_ID_RE.test(raw.agentId))
+        return { ok: false, error: "--agent-id must be the pinned agent uuid" };
+    if (!raw.cwd || !raw.cwd.startsWith("/") || !isDir(raw.cwd))
+        return { ok: false, error: "--cwd must be an absolute directory" };
+    let door;
+    try {
+        door = new URL(raw.door ?? "");
+    }
+    catch {
+        return { ok: false, error: "--door must be a URL" };
+    }
+    if (door.protocol !== "https:" && door.protocol !== "http:")
+        return { ok: false, error: "--door must be https" };
+    if (door.username || door.password)
+        return { ok: false, error: "--door must carry no userinfo" };
+    // T3 (C13-R11): an http door only on a loopback host, only under the CLI test-mode guard.
+    if (door.protocol === "http:" && !httpDoorAllowed(door.href, env))
+        return { ok: false, error: "--door must be https" };
+    const seatGiven = ["session", "epoch", "spawnId", "helloRelay"].some((k) => k in raw);
+    let seat = null;
+    if (seatGiven) {
+        const epoch = Number(raw.epoch);
+        if (!raw.session || !UUID_I.test(raw.session))
+            return { ok: false, error: "--session must be a uuid" };
+        if (!raw.spawnId || !UUID_I.test(raw.spawnId))
+            return { ok: false, error: "--spawn-id must be a uuid" };
+        if (!/^\d{1,15}$/.test(raw.epoch ?? "") || !Number.isSafeInteger(epoch))
+            return { ok: false, error: "--epoch must be a non-negative integer" };
+        if (raw.helloRelay !== undefined && !raw.helloRelay.startsWith("/"))
+            return { ok: false, error: "--hello-relay must be an absolute socket path" };
+        seat = { sessionId: raw.session, epoch, spawnId: raw.spawnId };
+    }
+    return {
+        ok: true,
+        args: {
+            conversation: raw.conversation,
+            agentId: raw.agentId,
+            door,
+            cwd: raw.cwd,
+            seat,
+            helloRelay: raw.helloRelay ?? null,
+        },
+    };
+}
+/** The first stdin line (CR stripped), or "" on EOF / timeout. Only the first line is ever read. */
+export function readKeyLine(stream, timeoutMs = 10_000) {
+    return new Promise((resolve) => {
+        let buf = "";
+        const finish = (v) => {
+            clearTimeout(timer);
+            stream.removeListener("data", onData);
+            stream.removeListener("end", onEnd);
+            stream.removeListener("error", onEnd);
+            if (typeof stream.pause === "function")
+                stream.pause();
+            resolve(v.replace(/\r$/, ""));
+        };
+        const onData = (d) => {
+            buf += d.toString();
+            const i = buf.indexOf("\n");
+            if (i >= 0)
+                finish(buf.slice(0, i));
+            else if (buf.length > 4096)
+                finish("");
+        };
+        const onEnd = () => finish(buf);
+        const timer = setTimeout(() => finish(""), timeoutMs);
+        stream.on("data", onData);
+        stream.on("end", onEnd);
+        stream.on("error", onEnd);
+    });
+}
+// ---------------------------------------------------------------- response decisions
+/** The arm verdict for one door response: forward, or the drop reason. */
+export function armVerdict(pathname, rawHeaders) {
+    const values = [];
+    for (let i = 0; i + 1 < rawHeaders.length; i += 2)
+        if (rawHeaders[i].toLowerCase() === ARM_HEADER)
+            values.push(rawHeaders[i + 1]);
+    if (values.length === 0)
+        return { forward: false, reason: "arm_missing" };
+    if (values.length > 1)
+        return { forward: false, reason: "arm_unparseable" };
+    const v = values[0];
+    if (armForwardsFor(pathname, v))
+        return { forward: true };
+    const a = parseArm(v);
+    if (a === null || a.posture !== "unattended")
+        return { forward: false, reason: "arm_unparseable" };
+    return {
+        forward: false,
+        reason: a.hold !== "on" ? "unattended_hold_off" : "unattended_fence_off",
+    };
+}
+/** The dead-key signal in a door response (C13-R7), read from the JSON body's error.type. */
+export function deadKeyReason(status, body) {
+    if (status !== 401 && status !== 409 && status !== 410)
+        return null;
+    let type;
+    try {
+        const j = JSON.parse(body);
+        type =
+            j && typeof j === "object" && j.error && typeof j.error === "object"
+                ? j.error.type
+                : undefined;
+    }
+    catch {
+        return null;
+    }
+    if (status === 409 && type === "durable_lease_fenced")
+        return "fenced_exit";
+    if (status === 401 && type === "durable_key_revoked")
+        return "revoked_exit";
+    if (status === 410 && (type === "durable_session_ended" || type === "durable_unlocked"))
+        return "ended_exit";
+    return null;
+}
+/** Whether a request path is origin-form and free of dot segments (raw or percent-encoded). */
+export function isCleanOriginForm(url) {
+    if (!url.startsWith("/") || url.startsWith("//"))
+        return false;
+    const p = url.split("?")[0];
+    let decoded;
+    try {
+        decoded = decodeURIComponent(p);
+    }
+    catch {
+        return false;
+    }
+    return !decoded.split("/").some((seg) => seg === "." || seg === "..") && !decoded.includes("\\");
+}
+/** Where a request goes: the two model POSTs are forwarded; startup paths are answered locally. */
+export function routeOf(method, pathname) {
+    if (method === "POST" && pathname === MESSAGES_PATH)
+        return "messages";
+    if (method === "POST" && pathname === COUNT_TOKENS_PATH)
+        return "count_tokens";
+    if ((method === "HEAD" || method === "GET") && pathname === "/api/hello")
+        return "hello";
+    if (method === "POST" && pathname.startsWith("/api/event_logging/"))
+        return "telemetry";
+    return "refused";
+}
+function sendDrop(res, requestId) {
+    if (res.headersSent) {
+        res.destroy();
+        return;
+    }
+    res.sendDate = false;
+    res.writeHead(ARM_DROP_STATUS, { ...ARM_DROP_HEADERS, "request-id": requestId });
+    res.end(ARM_DROP_BODY);
+}
+function sendLocal(res, status, type, message) {
+    res.writeHead(status, { "content-type": "application/json" });
+    res.end(JSON.stringify({ type: "error", error: { type, message } }));
+}
+/** Thrown by readAll when a body passes its cap. */
+class OverCap extends Error {
+}
+/**
+ * The whole body. Rejects with OverCap as soon as it passes `cap` bytes (it never yields a truncated
+ * body), and with an Error when the stream closes before its end.
+ */
+function readAll(stream, cap) {
+    return new Promise((resolve, reject) => {
+        const parts = [];
+        let n = 0;
+        let settled = false;
+        const onData = (d) => {
+            n += d.length;
+            if (n <= cap) {
+                parts.push(d);
+                return;
+            }
+            settled = true;
+            stream.removeListener("data", onData);
+            reject(new OverCap());
+        };
+        stream.on("data", onData);
+        stream.on("end", () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(Buffer.concat(parts));
+        });
+        stream.on("error", (e) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(e);
+        });
+        stream.on("close", () => {
+            if (settled)
+                return;
+            settled = true;
+            reject(new Error("closed before end"));
+        });
+    });
+}
+function responseHeaders(rawHeaders) {
+    const out = {};
+    for (let i = 0; i + 1 < rawHeaders.length; i += 2) {
+        const name = rawHeaders[i].toLowerCase();
+        if (HOP.has(name) && name !== "content-length")
+            continue;
+        const prev = out[name];
+        out[name] =
+            prev === undefined ? rawHeaders[i + 1] : [].concat(prev, rawHeaders[i + 1]);
+    }
+    return out;
+}
+/** The request handler of a seat proxy for `cfg` with lease key `key`. */
+export function createSeatProxyHandler(cfg, key, deps, state = { dead: null }) {
+    const doorPath = cfg.door.pathname.replace(/\/$/, "");
+    const transport = cfg.door.protocol === "https:" ? https : http;
+    const agent = new transport.Agent({ keepAlive: true, maxSockets: 32 });
+    const reqId = deps.requestId ?? (() => `req_mnmdrop_${randomBytes(12).toString("hex")}`);
+    const requestBodyCap = deps.requestBodyCap ?? REQUEST_BODY_CAP;
+    const deadBodyCap = deps.deadBodyCap ?? DEAD_BODY_CAP;
+    return (req, res) => {
+        const url = req.url ?? "";
+        // Node routes CONNECT to the server's 'connect' event, which refuseConnect (wired in
+        // seatProxyMain) answers; the method check here still refuses one that reaches the handler.
+        if (req.method === "CONNECT" || !isCleanOriginForm(url)) {
+            deps.log(`${req.method ?? "?"} refused (not origin-form)`);
+            req.resume();
+            sendLocal(res, 400, "invalid_request_error", "mnemom seat proxy: origin-form request path required");
+            return;
+        }
+        const pathname = url.split("?")[0];
+        const route = routeOf(req.method ?? "", pathname);
+        if (route === "hello") {
+            req.resume();
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end(req.method === "HEAD" ? undefined : "{}");
+            return;
+        }
+        if (route === "telemetry") {
+            req.resume();
+            res.writeHead(200, { "content-type": "application/json" });
+            res.end("{}");
+            return;
+        }
+        if (route === "refused") {
+            req.resume();
+            deps.log(`${req.method} ${pathname.slice(0, 80)} refused (path not allowed)`);
+            sendLocal(res, 404, "not_found_error", "mnemom seat proxy: path not allowed");
+            return;
+        }
+        void readAll(req, requestBodyCap)
+            .then(async (body) => {
+            const turn = await durableTurnHeaderFor(deps.turns, pathname, req.headers, {
+                durable: true,
+            });
+            if (turn.kind === "local") {
+                deps.log(`${pathname} drop ${turn.reason}`);
+                sendDrop(res, reqId());
+                return;
+            }
+            if (state.dead) {
+                // After a dead-key answer nothing is forwarded again (C13-R7).
+                sendDrop(res, reqId());
+                return;
+            }
+            const headers = {};
+            for (const [k, v] of Object.entries(req.headers))
+                if (v !== undefined && !isStrippedClientHeader(k))
+                    headers[k] = v;
+            // The lease key replaces any x-mnemom-api-key claude sent (stripped above).
+            headers["x-mnemom-api-key"] = key;
+            headers["x-mnemom-agent-id"] = cfg.agentId;
+            if (turn.kind === "chained")
+                headers[TURN_HEADER] = turn.value;
+            headers["content-length"] = String(body.length);
+            forward(pathname, url, headers, body, res, turn.note);
+        })
+            .catch((e) => {
+            if (!(e instanceof OverCap)) {
+                sendDrop(res, reqId());
+                return;
+            }
+            // Discard the rest of the upload and refuse locally; nothing goes upstream.
+            req.resume();
+            deps.log(`${pathname} refused request_too_large`);
+            res.shouldKeepAlive = false;
+            sendLocal(res, 413, "request_too_large", "mnemom seat proxy: request body too large");
+        });
+    };
+    function forward(pathname, url, headers, body, res, note) {
+        const target = new URL(cfg.door.origin + doorPath + url);
+        const started = Date.now();
+        const up = transport.request(target, { method: "POST", headers, agent }, (ur) => {
+            const status = ur.statusCode;
+            const verdict = armVerdict(pathname, ur.rawHeaders);
+            const deadCandidate = status === 401 || status === 409 || status === 410;
+            if (deadCandidate) {
+                void readAll(ur, deadBodyCap).then((buf) => {
+                    const dead = deadKeyReason(status, buf.toString("utf8"));
+                    if (dead)
+                        state.dead = dead;
+                    if (verdict.forward) {
+                        res.writeHead(status, responseHeaders(ur.rawHeaders));
+                        res.end(buf);
+                    }
+                    else {
+                        deps.log(`${pathname} ${status} drop ${verdict.reason}`);
+                        sendDrop(res, reqId());
+                    }
+                    if (dead) {
+                        deps.log(`${dead} after ${status}`);
+                        let exited = false;
+                        const exitOnce = () => {
+                            if (exited)
+                                return;
+                            exited = true;
+                            deps.exit(EXIT_KEY_DEAD);
+                        };
+                        res.once("finish", exitOnce);
+                        res.once("close", exitOnce);
+                    }
+                }, (e) => {
+                    if (e instanceof OverCap) {
+                        // Never forward a truncated body (its content-length would lie): drop, no exit.
+                        ur.destroy();
+                        deps.log(`${pathname} ${status} drop dead_body_over_cap`);
+                    }
+                    sendDrop(res, reqId());
+                });
+                return;
+            }
+            if (!verdict.forward) {
+                ur.resume();
+                deps.log(`${pathname} ${status} drop ${verdict.reason}`);
+                sendDrop(res, reqId());
+                return;
+            }
+            res.writeHead(status, responseHeaders(ur.rawHeaders));
+            ur.pipe(res);
+            ur.on("end", () => deps.log(`${pathname} -> ${status} ${Date.now() - started}ms turn=${note}`));
+            // A cut upstream ends the client response too (Node signals it by close without complete).
+            ur.on("close", () => {
+                if (!ur.complete)
+                    res.destroy();
+            });
+        });
+        up.on("error", () => {
+            deps.log(`${pathname} upstream_error`);
+            sendDrop(res, reqId());
+        });
+        res.on("close", () => {
+            if (!res.writableFinished)
+                up.destroy();
+        });
+        up.end(body);
+    }
+}
+export function defaultMainDeps() {
+    return {
+        env: process.env,
+        stdin: process.stdin,
+        stdout: (line) => void process.stdout.write(line),
+        stderr: (line) => void process.stderr.write(line),
+        exit: (code) => process.exit(code),
+        home: os.homedir(),
+        isDir: (p) => {
+            try {
+                return fs.statSync(p).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        },
+        lock: (p) => tryLockFile(p),
+        relayFor: (p) => unixLineRelay(p),
+    };
+}
+function makeLog(env, stderr) {
+    const file = env.MNEMOM_DURABLE_PROXY_LOG || "";
+    return (line) => {
+        const s = `${new Date().toISOString()} seat-proxy ${String(line).replace(/[\r\n]+/g, " ")}\n`;
+        if (file) {
+            try {
+                fs.appendFileSync(file, s, { mode: 0o600 });
+                return;
+            }
+            catch {
+                /* fall through to stderr */
+            }
+        }
+        stderr(s);
+    };
+}
+/**
+ * The 'connect' listener for a seat proxy's loopback servers: a CONNECT (a tunnel request, never
+ * origin-form) is refused with a 400 and the socket closed. Without a listener Node would drop the
+ * socket silently; this makes the refusal explicit and logged.
+ */
+export function refuseConnect(log) {
+    return (_req, socket) => {
+        log("CONNECT refused (not origin-form)");
+        socket.on("error", () => socket.destroy());
+        socket.end("HTTP/1.1 400 Bad Request\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+    };
+}
+function listen(server, port, host) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            server.removeListener("error", reject);
+            resolve(server.address().port);
+        });
+    });
+}
+/**
+ * `mnemom agent host seat-proxy …`: validate, read the key, take the conversation lock, listen,
+ * print READY. Resolves with the running proxy, or with an exit code it already passed to `exit`.
+ */
+export async function seatProxyMain(argv, deps = defaultMainDeps()) {
+    const fail = (code, msg) => {
+        deps.stderr(`mnemom agent host seat-proxy: ${msg}\n`);
+        deps.exit(code);
+        return code;
+    };
+    const parsed = parseSeatProxyArgs(argv, deps.env, deps.isDir);
+    if (!parsed.ok)
+        return fail(EXIT_CONFIG, parsed.error);
+    const cfg = parsed.args;
+    const log = makeLog(deps.env, deps.stderr);
+    const key = await readKeyLine(deps.stdin, deps.keyTimeoutMs);
+    if (!isWellFormedLeaseKey(key))
+        return fail(EXIT_CONFIG, "no lease key on stdin (expected one mnm_ds_ line)");
+    const lock = deps.lock(proxyLockPath(deps.home, cfg.conversation));
+    if (!lock.ok) {
+        if (lock.reason === "held") {
+            log("lock held by another proxy for this conversation");
+            return fail(EXIT_LOCK_HELD, "the conversation lock is held by another proxy");
+        }
+        return fail(EXIT_CONFIG, "could not take the conversation lock");
+    }
+    const turns = new TurnOrigins({ configDir: claudeConfigDir(deps.env), cwd: cfg.cwd });
+    const state = { dead: null };
+    const handler = createSeatProxyHandler(cfg, key, { log, exit: deps.exit, turns }, state);
+    const onConnect = refuseConnect(log);
+    const v4 = http.createServer(handler).on("connect", onConnect);
+    let port;
+    try {
+        port = await listen(v4, 0, deps.hostV4 ?? "127.0.0.1");
+    }
+    catch {
+        return fail(EXIT_CONFIG, "could not listen on 127.0.0.1");
+    }
+    const v6 = http.createServer(handler).on("connect", onConnect);
+    let v6up = true;
+    await listen(v6, port, deps.hostV6 ?? "::1").catch(() => {
+        v6up = false; // no IPv6 loopback on this host: 127.0.0.1 alone
+    });
+    const socketPath = seatSocketPath(deps.home, cfg.conversation);
+    let sock;
+    try {
+        sock = await startSeatSocket({
+            socketPath,
+            seat: cfg.seat,
+            relay: cfg.helloRelay ? deps.relayFor(cfg.helloRelay) : null,
+            log,
+        });
+    }
+    catch (err) {
+        v4.close();
+        if (v6up)
+            v6.close();
+        try {
+            fs.closeSync(lock.fd); // release the conversation lock: nothing is listening for it now
+        }
+        catch {
+            /* already closed */
+        }
+        log(`seat socket failed (${err.message}); closed 127.0.0.1:${port}`);
+        return fail(EXIT_CONFIG, "could not open the seat socket");
+    }
+    log(`listening 127.0.0.1:${port}${v6up ? " [::1]" : ""} door=${cfg.door.origin}`);
+    deps.stdout(`READY ${port} ${socketPath}\n`);
+    return {
+        port,
+        socketPath,
+        close: async () => {
+            await Promise.all([
+                new Promise((r) => v4.close(() => r())),
+                v6up ? new Promise((r) => v6.close(() => r())) : Promise.resolve(),
+                new Promise((r) => sock.close(() => r())),
+            ]);
+            if (lock.ok) {
+                try {
+                    fs.closeSync(lock.fd);
+                }
+                catch {
+                    /* already closed */
+                }
+            }
+        },
+    };
+}

package/dist/durable/seat-socket.d.ts

@@ -0,0 +1,46 @@
+import net from "node:net";
+/** The one fixed refusal line (bytes before the newline). A local literal: S1 freezes no seat-socket refusal line yet (gap c3-seat-proxy-enums-not-in-s1). */
+export declare const SEAT_SOCKET_REFUSAL = "{\"ok\":false,\"error\":\"seat_op_refused\"}";
+/** Our own hello cannot reach the daemon (no relay configured, or the relay failed). */
+export declare const SEAT_SOCKET_UNAVAILABLE = "{\"ok\":false,\"error\":\"seat_hello_unavailable\"}";
+/** A frame (the bytes before the newline) longer than this many bytes is refused without parsing. */
+export declare const SEAT_SOCKET_MAX_FRAME: number;
+/** macOS sun_path is 104 bytes including the NUL. */
+export declare const SOCKET_PATH_MAX = 103;
+/** The seat this proxy serves: registered by the daemon at spawn (all three are non-secret ids). */
+export interface SeatIdentity {
+    sessionId: string;
+    epoch: number;
+    spawnId: string;
+}
+export type HelloRelay = (frame: {
+    op: "hello";
+    session_id: string;
+    epoch: number;
+    spawn_id: string;
+}) => Promise<string>;
+/** Whether a parsed frame is the seat's own hello. Everything else is refused. */
+export declare function isOwnHello(frame: unknown, seat: SeatIdentity | null): boolean;
+/** The reply line (without newline) for one request line. Never throws. */
+export declare function answerFrame(line: string, seat: SeatIdentity | null, relay: HelloRelay | null): Promise<{
+    reply: string;
+    outcome: "refused" | "relayed" | "unavailable";
+}>;
+/**
+ * The socket path for a conversation: under ~/.mnemom/durable/seats when it fits sun_path, else a
+ * short path under /tmp/mnm-seat-<uid>/ (a 0700 directory the seat uid owns), named by a hash of
+ * HOME and the conversation id.
+ */
+export declare function seatSocketPath(home: string, conversationId: string, uid?: number): string;
+/** Create (or check) the socket's directory: 0700 and owned by this uid. Throws when it is not. */
+export declare function ensureSocketDir(dir: string, uid?: number): void;
+/** Relay a hello to the daemon's control socket: one JSON line out, one line back. */
+export declare function unixLineRelay(socketPath: string, timeoutMs?: number): HelloRelay;
+export interface SeatSocketOptions {
+    socketPath: string;
+    seat: SeatIdentity | null;
+    relay: HelloRelay | null;
+    log: (line: string) => void;
+}
+/** Listen on the seat socket (file mode 0600). Resolves once listening. */
+export declare function startSeatSocket(opts: SeatSocketOptions): Promise<net.Server>;