@ouro.bot/cli 0.1.0-alpha.92 → 0.1.0-alpha.921

package/dist/a2a/operator-trust.js

@@ -0,0 +1,382 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TrustDirectoryError = exports.TRUST_DIR_ENV = exports.OPERATOR_TRUST_ROOT = void 0;
+exports.overrideTrustRootForTests = overrideTrustRootForTests;
+exports.agentNameFromRoot = agentNameFromRoot;
+exports.operatorTrustDir = operatorTrustDir;
+exports.operatorTrustFile = operatorTrustFile;
+exports.readGrantFile = readGrantFile;
+exports.overrideFchownForTests = overrideFchownForTests;
+exports.ensureTrustDirectory = ensureTrustDirectory;
+exports.overrideDirectoryFlushForTests = overrideDirectoryFlushForTests;
+exports.overrideLockTimeoutForTests = overrideLockTimeoutForTests;
+exports.withTrustedWriteLock = withTrustedWriteLock;
+exports.writeTrustedFile = writeTrustedFile;
+exports.describeGrantFile = describeGrantFile;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+const trusted_files_1 = require("./trusted-files");
+/**
+ * Operator-set grants live in a trust directory outside the agent bundle: `/etc/ouro/trust/<agent>/` by default, or
+ * `<OURO_OPERATOR_TRUST_DIR>/<agent>/` when that variable replaces the trust root. The agent's own uid cannot write there, and the bundle's recursive
+ * `chown` during an in-place upgrade cannot reach it. A file in it counts only when the whole chain above it passes
+ * the trusted-files check (real directories, root-owned, closed to group and other writes, up to `/`).
+ */
+exports.OPERATOR_TRUST_ROOT = "/etc/ouro/trust";
+exports.TRUST_DIR_ENV = "OURO_OPERATOR_TRUST_DIR";
+let trustRoot = exports.OPERATOR_TRUST_ROOT;
+/** Tests keep trust directories under their private temp root instead of `/etc`. Refused outside a test runner. */
+function overrideTrustRootForTests(root) {
+    if (process.env.VITEST === undefined)
+        throw new Error("overrideTrustRootForTests is for tests only");
+    trustRoot = root ?? exports.OPERATOR_TRUST_ROOT;
+}
+/** The agent a bundle root belongs to: `~/AgentBundles/sanctuary.ouro` is `sanctuary`. */
+function agentNameFromRoot(agentRoot) {
+    return path.basename(agentRoot).replace(/\.ouro$/u, "");
+}
+/**
+ * The real path of `target`, resolved once. The deepest ancestor that exists is resolved through every symlink and the rest of
+ * the (not yet created) tail is appended, so a configured `/etc/ouro/trust` becomes `/private/etc/ouro/trust` on macOS and the
+ * ancestor check then walks the directories the grants actually sit in.
+ */
+function resolveReal(target) {
+    const tail = [];
+    for (let current = path.resolve(target);; current = path.dirname(current)) {
+        try {
+            return path.join(fs.realpathSync(current), ...tail);
+        }
+        catch {
+            /* v8 ignore next -- the filesystem root always resolves, so this loop never runs out of ancestors @preserve */
+            if (path.dirname(current) === current)
+                return path.resolve(target);
+            tail.unshift(path.basename(current));
+        }
+    }
+}
+/**
+ * Where this agent's operator-set grants live: `<trust root>/<agent>`. `OURO_OPERATOR_TRUST_DIR` replaces the trust root
+ * (`/etc/ouro/trust`) and keeps the per-agent subdirectory, so one setting serves every agent on the host.
+ */
+function operatorTrustDir(agentRoot) {
+    const override = process.env[exports.TRUST_DIR_ENV];
+    const root = override && override.trim().length > 0 ? override : trustRoot;
+    return path.join(resolveReal(root), agentNameFromRoot(agentRoot));
+}
+function operatorTrustFile(agentRoot, fileName) {
+    return path.join(operatorTrustDir(agentRoot), fileName);
+}
+/**
+ * Reads `{ schemaVersion: 1, grants: { <friendId>: entry } }` from the trust directory. A file that is not trusted, not
+ * JSON or not this shape is `untrusted` and holds no grants; a missing file is `missing`. Within a trusted file, an
+ * entry that fails `valid` is dropped and its friend id is listed in `ignored`.
+ */
+function readGrantFile(agentRoot, fileName, valid) {
+    const raw = (0, trusted_files_1.inspectTrustedJson)(operatorTrustFile(agentRoot, fileName));
+    if (raw.state === "missing")
+        return { state: "missing", grants: {}, ignored: [] };
+    if (raw.state === "untrusted")
+        return { state: "untrusted", reason: raw.reason, grants: {}, ignored: [] };
+    const file = raw.value;
+    const grants = file?.grants;
+    if (!file || typeof file !== "object" || file.schemaVersion !== 1 || !grants || typeof grants !== "object" || Array.isArray(grants)) {
+        return { state: "untrusted", reason: "file is not { schemaVersion: 1, grants: {...} }", grants: {}, ignored: [] };
+    }
+    const kept = {};
+    const ignored = [];
+    for (const [friendId, entry] of Object.entries(grants)) {
+        if (valid(entry))
+            kept[friendId] = entry;
+        else
+            ignored.push(friendId);
+    }
+    return { state: "trusted", grants: kept, ignored };
+}
+/** Why the operator command refused to write. The message says what to fix. */
+class TrustDirectoryError extends Error {
+}
+exports.TrustDirectoryError = TrustDirectoryError;
+const isRoot = () => process.geteuid?.() === 0;
+let fchownHook;
+/** Tests are not root, so they watch ownership changes instead of making them. Refused outside a test runner. */
+function overrideFchownForTests(hook) {
+    if (process.env.VITEST === undefined)
+        throw new Error("overrideFchownForTests is for tests only");
+    fchownHook = hook;
+}
+/* v8 ignore start -- the real fchown only succeeds as root; tests watch the hook instead @preserve */
+function chownToRoot(fd) {
+    if (fchownHook)
+        fchownHook(fd, 0, 0);
+    else
+        fs.fchownSync(fd, 0, 0);
+}
+/* v8 ignore stop */
+/**
+ * Makes sure the trust directory exists and is trusted. A missing directory is created root-owned 0755, one component
+ * at a time, but only below an ancestor that is already trusted. An existing directory (or ancestor) that is not
+ * trusted is refused: the command never takes ownership of something the agent could have made.
+ */
+function ensureTrustDirectory(dir) {
+    const missing = [];
+    let base = path.resolve(dir);
+    for (;;) {
+        const result = (0, trusted_files_1.inspectTrustedDirectory)(base);
+        if (result.state === "trusted")
+            break;
+        if (result.state === "untrusted")
+            throw new TrustDirectoryError(`refusing to write: ${base} is not trusted (${result.reason}). Fix its owner and mode as root; this command never takes ownership of an existing directory.`);
+        missing.push(base);
+        base = path.dirname(base);
+    }
+    for (const next of missing.reverse()) {
+        fs.mkdirSync(next, { mode: 0o755 });
+        const fd = fs.openSync(next, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+        try {
+            if (isRoot())
+                chownToRoot(fd);
+            fs.fchmodSync(fd, 0o755);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+}
+/** Flushes a directory's entries to disk, so a rename or a new file in it survives a crash. */
+function fsyncDirectory(dir) {
+    const fd = fs.openSync(dir, fs.constants.O_RDONLY | fs.constants.O_DIRECTORY | fs.constants.O_NOFOLLOW);
+    try {
+        fs.fsyncSync(fd);
+        directoryFlushHook?.(dir);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+let directoryFlushHook;
+/** Tests watch directory flushes (the ESM fs namespace cannot be spied on). Refused outside a test runner. */
+function overrideDirectoryFlushForTests(hook) {
+    if (process.env.VITEST === undefined)
+        throw new Error("overrideDirectoryFlushForTests is for tests only");
+    directoryFlushHook = hook;
+}
+const LOCK_FILE = ".lock";
+const LOCK_STALE_MS = 2 * 60_000;
+/** A lock written by another host or pid namespace (a different hostname in its body) cannot be checked for a live holder, so it is only taken over after this long. */
+const LOCK_FOREIGN_STALE_MS = 60 * 60_000;
+let lockTimeoutMs = 5000;
+let lockWaitHook;
+let beforeReclaimHook;
+/** Tests shorten the wait for a held lock, can act while it waits, and can act between judging a lock stale and reclaiming it. Refused outside a test runner. */
+function overrideLockTimeoutForTests(timeoutMs, onWait, onBeforeReclaim) {
+    if (process.env.VITEST === undefined)
+        throw new Error("overrideLockTimeoutForTests is for tests only");
+    lockTimeoutMs = timeoutMs ?? 5000;
+    lockWaitHook = onWait;
+    beforeReclaimHook = onBeforeReclaim;
+}
+/** How long ago `file` was last written; a file that is gone counts as brand new, so nobody treats it as stale. */
+function ageMs(file) {
+    try {
+        return Date.now() - fs.lstatSync(file).mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+const lockBody = () => `pid ${process.pid} host ${os.hostname()} at ${new Date().toISOString()}\n`;
+/** True when a process with this pid exists on this host. EPERM means it exists but is someone else's. */
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== "ESRCH";
+    }
+}
+/**
+ * Whether `lock` was left by a writer that is gone. Age alone is not enough: a slow writer can hold the lock for longer than two
+ * minutes. So a lock older than that is stale only when the pid in its body is no longer running on this host. A body that cannot be
+ * read as `pid N host H at T` names no holder at all, and a lock from another host or pid namespace cannot be checked, so it waits
+ * out a much longer age.
+ */
+function lockIsStale(lock) {
+    const age = ageMs(lock);
+    if (age <= LOCK_STALE_MS)
+        return false;
+    let held = null;
+    try {
+        held = /^pid (\d+) host (\S+) at /.exec(fs.readFileSync(lock, "utf8"));
+    }
+    catch {
+        return false;
+    }
+    if (!held)
+        return true;
+    if (held[2] !== os.hostname())
+        return age > LOCK_FOREIGN_STALE_MS;
+    return !processAlive(Number(held[1]));
+}
+/**
+ * Removes a lock that looked stale, but only while holding a second exclusive file (`.lock.reclaim`) and only after looking again:
+ * two writers that both judged the same lock stale cannot then each delete it, which would let the second delete the fresh lock
+ * the first had just taken. A reclaim file that is itself stale belongs to a writer that died and is removed.
+ */
+function reclaimStaleLock(lock) {
+    const guard = `${lock}.reclaim`;
+    try {
+        createExclusive(guard, lockBody());
+    }
+    catch {
+        if (ageMs(guard) > LOCK_STALE_MS)
+            fs.rmSync(guard, { force: true });
+        return;
+    }
+    try {
+        if (lockIsStale(lock))
+            fs.rmSync(lock, { force: true });
+    }
+    finally {
+        fs.rmSync(guard, { force: true });
+    }
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Runs a read-modify-write of the trust files under an exclusive lock file in the trust directory, so two grant commands
+ * cannot both read the old file and then overwrite each other. The lock is created with O_EXCL and records the writer's pid and host;
+ * a lock older than two minutes whose writer is no longer running is taken over. A lock that stays held past the wait names the file to remove.
+ */
+function withTrustedWriteLock(agentRoot, fn) {
+    const dir = operatorTrustDir(agentRoot);
+    ensureTrustDirectory(dir);
+    const lock = path.join(dir, LOCK_FILE);
+    const deadline = Date.now() + lockTimeoutMs;
+    for (;;) {
+        try {
+            createExclusive(lock, lockBody());
+            break;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            if (lockIsStale(lock)) {
+                beforeReclaimHook?.();
+                reclaimStaleLock(lock);
+            }
+            if (Date.now() >= deadline)
+                throw new TrustDirectoryError(`refusing to write: another grant command is writing to ${dir} (lock file ${lock}). If none is running, remove that file and retry. Nothing was written.`);
+            lockWaitHook?.();
+            sleepSync(25);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        fs.rmSync(lock, { force: true });
+    }
+}
+/** Creates `file` exclusively (never through a link or over anything), owned by root with mode 0644 when run as root, and fsyncs it. */
+function createExclusive(file, body) {
+    const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+    try {
+        if (isRoot())
+            chownToRoot(fd);
+        fs.fchmodSync(fd, 0o644);
+        fs.writeFileSync(fd, body);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function rawBytes(file) {
+    let fd;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        return fs.fstatSync(fd).isFile() ? fs.readFileSync(fd) : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/**
+ * Replaces one file in the trust directory. The previous bytes are kept beside it as a timestamped backup, created the
+ * same safe way. The new file is written to an exclusive random temporary name, owned and moded through its descriptor,
+ * fsynced and renamed into place, so a reader never sees a half-written file and nothing already on disk is followed.
+ */
+function writeTrustedFile(agentRoot, fileName, body, now) {
+    const dir = operatorTrustDir(agentRoot);
+    ensureTrustDirectory(dir);
+    const file = path.join(dir, fileName);
+    const previous = rawBytes(file);
+    let backup = null;
+    if (previous) {
+        backup = `${file}.bak-${now.toISOString().replace(/[:.]/gu, "-")}`;
+        createExclusive(backup, previous);
+        fsyncDirectory(dir);
+    }
+    const tmp = path.join(dir, `.${fileName}.${(0, node_crypto_1.randomBytes)(8).toString("hex")}.tmp`);
+    try {
+        createExclusive(tmp, body);
+        fs.renameSync(tmp, file);
+        fsyncDirectory(dir);
+    }
+    catch (error) {
+        fs.rmSync(tmp, { force: true });
+        throw error;
+    }
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.a2a_trust_file_written", message: "wrote an operator-set trust file", meta: { file, backedUp: backup !== null } });
+    return { backup };
+}
+/** A short human line about the file's state for `list` output and warnings. */
+function describeGrantFile(view, file) {
+    if (view.state === "trusted")
+        return `trusted: ${file}`;
+    if (view.state === "missing")
+        return `not present: ${file}`;
+    return `NOT TRUSTED: ${file} (${view.reason}); no grant in it is honoured`;
+}

package/dist/a2a/outbox-client.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callOutboxMethod = callOutboxMethod;
+const node_crypto_1 = require("node:crypto");
+const a2a_client_1 = require("@ouro.bot/friends/a2a-client");
+const client_1 = require("./client");
+const outbox_wire_1 = require("./outbox-wire");
+const sealed_chat_1 = require("./sealed-chat");
+const runtime_1 = require("../nerves/runtime");
+/**
+ * Calls one outbox method on an A2A agent as a verified friend. The request is sealed to the agent's card DID and
+ * signed by `identity`, and the reply is opened only if it was sealed by that same card key, so neither direction
+ * travels in plaintext. Throws with the agent's refusal text when the agent answers with a JSON-RPC error.
+ */
+async function callOutboxMethod(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const sodium = input.sodium ?? await (0, a2a_client_1.ready)();
+    const card = await (0, client_1.fetchA2AAgentCard)(input.cardUrl, fetchImpl);
+    const peerDid = (0, client_1.cardDid)(card);
+    if (!peerDid)
+        throw new Error(`A2A card ${input.cardUrl} serves no DID; outbox calls need one`);
+    const parsed = (0, a2a_client_1.parseDidKey)(peerDid);
+    if (!parsed || !(0, a2a_client_1.verifyCardDidBinding)({ card: { did: peerDid, url: input.cardUrl }, did: peerDid, didDoc: null })) {
+        throw new Error(`A2A card↔DID binding failed for ${peerDid}`);
+    }
+    const endpointUrl = (0, client_1.endpointForCard)(card);
+    const conversationId = (0, node_crypto_1.randomUUID)();
+    const sealed = (0, sealed_chat_1.sealChatMessage)({
+        sodium, from: input.identity, recipientDid: peerDid, recipientEd25519Pub: parsed.ed25519Pub,
+        text: (0, outbox_wire_1.encodeOutboxCommand)(input.method, input.params), conversationId,
+    });
+    const request = {
+        jsonrpc: "2.0", id: (0, node_crypto_1.randomUUID)(), method: input.method,
+        params: { message: { kind: "message", role: "ROLE_USER", messageId: (0, node_crypto_1.randomUUID)(), contextId: conversationId, parts: sealed.parts } },
+    };
+    (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_outbox_call_start", message: "calling an A2A outbox method", meta: { endpointUrl, peerDid, method: input.method } });
+    const rpc = await (0, client_1.postJsonRpc)(endpointUrl, request, fetchImpl);
+    if ("error" in rpc)
+        throw new Error(`A2A error ${rpc.error.code}: ${rpc.error.message}`);
+    const reply = rpc.result;
+    if (!reply || !Array.isArray(reply.parts))
+        throw new Error("A2A outbox call returned no reply message");
+    const opened = await (0, sealed_chat_1.openChatMessage)({ sodium, self: input.identity, message: reply, senderDid: peerDid, senderEd25519Pub: parsed.ed25519Pub });
+    if (!opened.ok)
+        throw new Error(`A2A outbox reply rejected: ${opened.reason}`);
+    let result;
+    try {
+        result = JSON.parse(opened.text);
+    }
+    catch {
+        throw new Error("A2A outbox reply was not JSON");
+    }
+    if (!result || typeof result !== "object" || Array.isArray(result))
+        throw new Error("A2A outbox reply was not a JSON object");
+    (0, runtime_1.emitNervesEvent)({ component: "channels", event: "channel.a2a_outbox_call_end", message: "received an A2A outbox reply", meta: { endpointUrl, peerDid, method: input.method } });
+    return result;
+}

package/dist/a2a/outbox-store.js

@@ -0,0 +1,188 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileOutboxStore = exports.OUTBOX_LIST_MAX_CHARS = exports.OUTBOX_LIST_MAX_LIMIT = exports.OUTBOX_LIST_DEFAULT_LIMIT = exports.OUTBOX_MAX_BODY_CHARS = exports.OUTBOX_MAX_ENTRIES = void 0;
+exports.isOutboxEntryId = isOutboxEntryId;
+exports.outboxRoot = outboxRoot;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const file_lock_1 = require("../heart/file-lock");
+const runtime_1 = require("../nerves/runtime");
+exports.OUTBOX_MAX_ENTRIES = 500;
+exports.OUTBOX_MAX_BODY_CHARS = 6_000;
+exports.OUTBOX_LIST_DEFAULT_LIMIT = 20;
+exports.OUTBOX_LIST_MAX_LIMIT = 50;
+/** One listing reply is a single sealed message of at most 16,000 characters, so a listing stops filling well before that. */
+exports.OUTBOX_LIST_MAX_CHARS = 12_000;
+const FRIEND_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const ENTRY_ID = /^\d{13}-[0-9a-f]{6}$/u;
+function isOutboxEntryId(value) {
+    return typeof value === "string" && ENTRY_ID.test(value);
+}
+function entryDir(agentRoot, friendId) {
+    if (!FRIEND_ID.test(friendId))
+        throw new Error("outbox friend id is invalid");
+    return path.join(agentRoot, "state", "outbox", friendId);
+}
+function outboxRoot(agentRoot) {
+    return path.join(agentRoot, "state", "outbox");
+}
+function readEntry(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!isOutboxEntryId(parsed.id) || typeof parsed.kind !== "string" || typeof parsed.createdAt !== "string" || typeof parsed.body !== "string")
+            return null;
+        return { id: parsed.id, kind: parsed.kind, createdAt: parsed.createdAt, body: parsed.body, ...(parsed.meta ? { meta: parsed.meta } : {}) };
+    }
+    catch {
+        return null;
+    }
+}
+function sortedIds(dir) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    return names.filter((name) => name.endsWith(".json") && isOutboxEntryId(name.slice(0, -5))).map((name) => name.slice(0, -5)).sort();
+}
+class FileOutboxStore {
+    agentRoot;
+    constructor(agentRoot) {
+        this.agentRoot = agentRoot;
+    }
+    /** Adds one entry for `friendId`. The oldest entries beyond the cap are dropped so a peer that never reads cannot fill the disk. */
+    append(friendId, input, now = Date.now()) {
+        const dir = entryDir(this.agentRoot, friendId);
+        fs.mkdirSync(dir, { recursive: true });
+        const id = `${String(now).padStart(13, "0")}-${(0, node_crypto_1.randomBytes)(3).toString("hex")}`;
+        const entry = {
+            id,
+            kind: input.kind,
+            createdAt: new Date(now).toISOString(),
+            body: input.body.slice(0, exports.OUTBOX_MAX_BODY_CHARS),
+            ...(input.meta ? { meta: input.meta } : {}),
+        };
+        const file = path.join(dir, `${id}.json`);
+        const tmp = `${file}.${process.pid}.tmp`;
+        fs.writeFileSync(tmp, `${JSON.stringify(entry, null, 2)}\n`, { mode: 0o600 });
+        fs.renameSync(tmp, file);
+        const ids = sortedIds(dir);
+        const evicted = ids.slice(0, Math.max(0, ids.length - exports.OUTBOX_MAX_ENTRIES));
+        for (const stale of evicted)
+            fs.rmSync(path.join(dir, `${stale}.json`), { force: true });
+        if (evicted.length > 0) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.a2a_outbox_evicted",
+                message: "a peer outbox is full, so its oldest unread entries were dropped",
+                meta: { friendId, evicted: evicted.length, oldestDropped: evicted[0], cap: exports.OUTBOX_MAX_ENTRIES },
+            });
+        }
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.a2a_outbox_appended",
+            message: "queued a message in a peer outbox",
+            meta: { friendId, entryId: id, kind: input.kind },
+        });
+        return entry;
+    }
+    /** Like `append`, but a second call with the same `dedupeKey` while the first entry is still unacked returns that entry, so a retried delivery cannot double-post. */
+    async appendOnce(friendId, dedupeKey, input, now = Date.now()) {
+        const dir = entryDir(this.agentRoot, friendId);
+        // The check and the append happen under one cross-process lock, so two senses retrying the same delivery cannot both miss it.
+        return (0, file_lock_1.withFileLock)(path.join(this.agentRoot, "state", "outbox", ".locks"), `once-${friendId}`, () => {
+            for (const id of sortedIds(dir)) {
+                const entry = readEntry(path.join(dir, `${id}.json`));
+                if (entry?.meta?.dedupeKey === dedupeKey)
+                    return entry;
+            }
+            return this.append(friendId, { ...input, meta: { ...input.meta, dedupeKey } }, now);
+        });
+    }
+    /** Entries after `since` (exclusive), oldest first, within the count and size limits. */
+    list(friendId, options = {}) {
+        const dir = entryDir(this.agentRoot, friendId);
+        const limit = Math.min(Math.max(1, Math.floor(options.limit ?? exports.OUTBOX_LIST_DEFAULT_LIMIT)), exports.OUTBOX_LIST_MAX_LIMIT);
+        const since = options.since ?? "";
+        const ids = sortedIds(dir).filter((id) => id > since);
+        const entries = [];
+        let chars = 0;
+        let more = false;
+        for (const id of ids) {
+            const entry = readEntry(path.join(dir, `${id}.json`));
+            if (!entry)
+                continue;
+            const size = JSON.stringify(entry).length;
+            if (entries.length >= limit || (entries.length > 0 && chars + size > exports.OUTBOX_LIST_MAX_CHARS)) {
+                more = true;
+                break;
+            }
+            entries.push(entry);
+            chars += size;
+        }
+        return { entries, nextCursor: entries.length > 0 ? entries[entries.length - 1].id : null, more };
+    }
+    /** Removes the named entries from this friend's outbox only; ids that are malformed or not there come back as unknown. */
+    ack(friendId, ids) {
+        const dir = entryDir(this.agentRoot, friendId);
+        const acked = [];
+        const unknown = [];
+        for (const id of ids) {
+            const file = isOutboxEntryId(id) ? path.join(dir, `${id}.json`) : null;
+            if (file && fs.existsSync(file)) {
+                fs.rmSync(file, { force: true });
+                acked.push(id);
+            }
+            else {
+                unknown.push(id);
+            }
+        }
+        if (acked.length > 0) {
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.a2a_outbox_acked",
+                message: "a peer cleared entries from its outbox",
+                meta: { friendId, count: acked.length },
+            });
+        }
+        return { acked, unknown };
+    }
+}
+exports.FileOutboxStore = FileOutboxStore;