@ouro.bot/cli 0.1.0-alpha.96 → 0.1.0-alpha.961

package/dist/senses/shepherd/checkin-config.js

@@ -0,0 +1,76 @@
+"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.normalizeShepherdCheckInMinutes = normalizeShepherdCheckInMinutes;
+exports.readShepherdCheckInMinutes = readShepherdCheckInMinutes;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../../nerves/runtime");
+function normalizeShepherdCheckInMinutes(value) {
+    if (value === undefined)
+        return 60;
+    if (typeof value === "number" && Number.isInteger(value) && (value === 0 || value >= 30 && value <= 1440))
+        return value;
+    (0, runtime_1.emitNervesEvent)({
+        level: "error", component: "config/identity", event: "config_identity.error",
+        message: "agent config has invalid Shepherd check-in cadence", meta: { field: "senses.shepherd.checkInMinutes" },
+    });
+    throw new Error("senses.shepherd.checkInMinutes must be 0 or an integer from 30 through 1440");
+}
+function object(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function readShepherdCheckInMinutes(agentRoot) {
+    try {
+        let value = JSON.parse(fs.readFileSync(path.join(agentRoot, "agent.json"), "utf8"));
+        for (const key of ["senses", "shepherd"]) {
+            if (!object(value))
+                throw new Error("agent.json has invalid Shepherd check-in config");
+            value = value[key];
+            if (value === undefined)
+                return normalizeShepherdCheckInMinutes(undefined);
+        }
+        if (!object(value))
+            throw new Error("agent.json has invalid Shepherd check-in config");
+        return normalizeShepherdCheckInMinutes(value.checkInMinutes);
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error", component: "config/identity", event: "config_identity.error",
+            message: "could not read Shepherd check-in configuration", meta: { operation: "read_check_in_config" },
+        });
+        throw error;
+    }
+}

package/dist/senses/shepherd/checkin-store.js

@@ -0,0 +1,386 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refuseCustody = refuseCustody;
+exports.validCustodyInputReceipt = validCustodyInputReceipt;
+exports.copyCustodyInputReceipt = copyCustodyInputReceipt;
+exports.parseCustodyDispatch = parseCustodyDispatch;
+exports.validateCustodyDirectory = validateCustodyDirectory;
+exports.checkInStorePath = checkInStorePath;
+exports.assertNoCustodyMaintenance = assertNoCustodyMaintenance;
+exports.custodyCapacity = custodyCapacity;
+exports.custodyRevision = custodyRevision;
+exports.advanceCustodyRevision = advanceCustodyRevision;
+exports.hasRetiredCustodyInstance = hasRetiredCustodyInstance;
+exports.retiredCustodyKey = retiredCustodyKey;
+exports.readRetiredCustodyRecord = readRetiredCustodyRecord;
+exports.openCustodyDatabase = openCustodyDatabase;
+exports.openCheckInStore = openCheckInStore;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
+const runtime_1 = require("../../nerves/runtime");
+const returns_1 = require("./returns");
+const MAX_ROW = 4096;
+const COMPLETION_HEADROOM = 2300;
+const MAX_DB = 64 * 1024 * 1024;
+const WARN_DB = 48 * 1024 * 1024;
+const warnedDatabases = new WeakSet();
+const bytes = (value) => Buffer.byteLength(JSON.stringify(value));
+const text = (value) => typeof value === "string" && value.length > 0;
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const timestamp = (value) => text(value) && Number.isFinite(Date.parse(value));
+function refuseCustody(reason) {
+    (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_checkin_store_refused",
+        message: "check-in custody operation refused", meta: { reason } });
+    throw new Error(`Shepherd check-in custody: ${reason}`);
+}
+const refuse = refuseCustody;
+function bounded(value, limit, field) {
+    if (!text(value) || bytes(value) > limit)
+        refuse(`${field} byte limit or type`);
+}
+function validInput(value) {
+    return object(value) && ["host", "session", "screenFingerprint", "guidanceRevision", "reply", "transition"].every(key => text(value[key])) &&
+        (value.instance === null || text(value.instance)) && ["immediate", "network", "periodic"].includes(String(value.trigger)) && timestamp(value.at);
+}
+function dispatchId(input) {
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify([
+        input.host, input.session, input.instance, input.screenFingerprint, input.guidanceRevision,
+    ])).digest("hex");
+}
+function validClaim(value) {
+    return object(value) && validInput(value) && text(value.owner) && bytes(value.owner) <= 256 &&
+        ["claimed", "sent", "not_sent", "unknown"].includes(String(value.state)) &&
+        (value.reason === undefined || text(value.reason) && bytes(value.reason) <= 1024)
+        && (value.receipt === undefined || validCustodyInputReceipt(value.receipt)
+            && value.receipt.requestId === value.id && value.receipt.surfaceId === value.session && value.receipt.processInstance === value.instance
+            && receiptMatchesOutcome(value.state, value.receipt));
+}
+function validCustodyInputReceipt(value) {
+    return object(value) && ["requestId", "surfaceId", "workspaceId", "processInstance"].every(key => text(value[key]) && bytes(value[key]) <= 256)
+        && typeof value.pasteAdmitted === "boolean" && typeof value.submitAdmitted === "boolean"
+        && (!value.submitAdmitted || value.pasteAdmitted);
+}
+function copyCustodyInputReceipt(receipt) {
+    const { requestId, surfaceId, workspaceId, processInstance, pasteAdmitted, submitAdmitted } = receipt;
+    return { requestId, surfaceId, workspaceId, processInstance, pasteAdmitted, submitAdmitted };
+}
+function receiptMatchesOutcome(state, receipt) {
+    return state === "sent" ? receipt.pasteAdmitted && receipt.submitAdmitted : state !== "not_sent" || !receipt.pasteAdmitted && !receipt.submitAdmitted;
+}
+function parseCustodyDispatch(row) {
+    if (Buffer.byteLength(row.data) > MAX_ROW)
+        refuse("record byte limit");
+    const value = JSON.parse(row.data);
+    if (!validClaim(value) || value.id !== row.id || dispatchId(value) !== row.id || value.host !== row.host ||
+        value.session !== row.session || value.instance !== row.instance)
+        refuse("invalid dispatch schema");
+    return value;
+}
+const parseDispatch = parseCustodyDispatch;
+function validateCustodyDirectory(directory, create) {
+    const uid = process.getuid();
+    for (let candidate = directory; candidate !== path.dirname(candidate); candidate = path.dirname(candidate)) {
+        const stat = fs.lstatSync(candidate, { throwIfNoEntry: false });
+        if (stat?.isSymbolicLink())
+            refuse("private directory ancestor is a link");
+        if (stat && (!stat.isDirectory() || stat.uid !== 0 && stat.uid !== uid
+            || (stat.mode & 0o022) !== 0 && !(stat.uid === 0 && (stat.mode & 0o1000) !== 0)))
+            refuse("private directory ancestor ownership or mode");
+    }
+    if (create)
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (!fs.lstatSync(directory, { throwIfNoEntry: false }))
+        return false;
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || (stat.mode & 0o7777) !== 0o700 || stat.uid !== uid)
+        refuse("private directory ownership or mode; require 0700");
+    return true;
+}
+function privateFile(file) {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o7777) !== 0o600 || stat.uid !== process.getuid())
+        refuse("private file ownership or mode");
+}
+function checkInStorePath(agentRoot) {
+    return path.join((0, returns_1.shepherdStateDir)(agentRoot), "checkins", "custody.sqlite");
+}
+function assertNoCustodyMaintenance(file) {
+    if (fs.lstatSync(`${file}.maintenance.json`, { throwIfNoEntry: false }))
+        refuse("interrupted or active maintenance; resume the exact owner maintenance request");
+}
+function custodyCapacity(database, writing = false) {
+    const size = Number(database.pragma("page_count", { simple: true })) * Number(database.pragma("page_size", { simple: true }));
+    if (size > MAX_DB || writing && size + 65536 > MAX_DB)
+        refuse("database capacity; no input authorized");
+    if (!warnedDatabases.has(database) && size >= WARN_DB) {
+        warnedDatabases.add(database);
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_checkin_capacity_warning",
+            message: "check-in custody is approaching capacity", meta: { bytes: size, limit: MAX_DB } });
+    }
+    return { bytes: size, capacity: size + 65536 > MAX_DB ? "refused" : size >= WARN_DB ? "warning" : "normal" };
+}
+function custodyRevision(database) {
+    const row = database.prepare("SELECT revision FROM custody_meta WHERE singleton=1").get();
+    if (!row || typeof row.revision !== "number" || !Number.isSafeInteger(row.revision) || row.revision < 0)
+        refuse("invalid custody revision schema");
+    return row.revision;
+}
+function advanceCustodyRevision(database) {
+    const revision = custodyRevision(database) + 1;
+    if (!Number.isSafeInteger(revision))
+        refuse("custody revision capacity");
+    database.prepare("UPDATE custody_meta SET revision=? WHERE singleton=1").run(revision);
+    return revision;
+}
+function hasRetiredCustodyInstance(database, input) {
+    const row = database.prepare(`SELECT key,host,session,instance,data FROM retired_instances WHERE host=? AND session=?
+    AND (instance IS NULL OR ? IS NULL OR instance=?) LIMIT 1`).get(input.host, input.session, input.instance, input.instance);
+    if (!row)
+        return false;
+    validateRetiredRow(row);
+    return true;
+}
+function retiredCustodyKey(input) {
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify([input.host, input.session, input.instance])).digest("hex");
+}
+function readRetiredCustodyRecord(database, input) {
+    const row = database.prepare("SELECT key,host,session,instance,data FROM retired_instances WHERE key=?").get(retiredCustodyKey(input));
+    return row ? validateRetiredRow(row) : null;
+}
+function validateRetiredRow(row) {
+    if (Buffer.byteLength(row.data) > MAX_ROW)
+        refuse("retired instance index capacity");
+    const data = JSON.parse(row.data);
+    const expectedKey = retiredCustodyKey(row);
+    if (!object(data) || !object(data.proof) || row.key !== expectedKey || data.proof.kind !== "host_process_inventory"
+        || data.proof.host !== row.host || data.proof.session !== row.session || data.proof.instance !== row.instance
+        || data.proof.gone !== true || !timestamp(data.proof.checkedAt) || typeof data.proof.wholeSessionRetired !== "boolean"
+        || row.instance === null && !data.proof.wholeSessionRetired)
+        refuse("invalid retired instance schema");
+    if (data.archive !== undefined && (!object(data.archive) || typeof data.archive.path !== "string" || !path.isAbsolute(data.archive.path)
+        || typeof data.archive.digest !== "string" || !/^[a-f0-9]{64}$/.test(data.archive.digest)))
+        refuse("invalid retired archive reference schema");
+    return data;
+}
+function openCustodyDatabase(file, mode) {
+    const readonly = mode === "read" || mode === "maintenance-read";
+    if (!path.isAbsolute(file) || path.normalize(file) !== file)
+        refuse("database path");
+    if (mode !== "maintenance" && mode !== "maintenance-read")
+        assertNoCustodyMaintenance(file);
+    if (!validateCustodyDirectory(path.dirname(file), !readonly))
+        return null;
+    if (readonly) {
+        if (!fs.lstatSync(file, { throwIfNoEntry: false }))
+            return null;
+    }
+    else {
+        try {
+            const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW, 0o600);
+            fs.closeSync(fd);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    privateFile(file);
+    for (const suffix of ["-journal", "-wal", "-shm"])
+        if (fs.lstatSync(`${file}${suffix}`, { throwIfNoEntry: false }))
+            privateFile(`${file}${suffix}`);
+    const database = new better_sqlite3_1.default(file, { fileMustExist: true, readonly });
+    try {
+        const version = database.pragma("user_version", { simple: true });
+        if (![0, 1, 2].includes(Number(version)) || version === 0 && readonly)
+            refuse("unsupported database schema");
+        custodyCapacity(database);
+        database.pragma("busy_timeout = 1000");
+        if (version !== 0) {
+            database.prepare("SELECT id,host,session,instance,data FROM dispatches LIMIT 0").all();
+            database.prepare("SELECT signature,data FROM notices LIMIT 0").all();
+        }
+        if (readonly) {
+            if (version === 2)
+                validateCustodyV2(database);
+            return database;
+        }
+        database.pragma("journal_mode = DELETE");
+        database.pragma("synchronous = FULL");
+        database.pragma(`max_page_count = ${Math.floor(MAX_DB / Number(database.pragma("page_size", { simple: true })))}`);
+        if (version !== 2)
+            database.transaction(() => {
+                if (database.pragma("user_version", { simple: true }) === 2)
+                    return;
+                database.exec(`CREATE TABLE IF NOT EXISTS dispatches (
+        id TEXT PRIMARY KEY NOT NULL, host TEXT NOT NULL, session TEXT NOT NULL, instance TEXT, data TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS dispatch_barriers ON dispatches(host,session,instance);
+      CREATE TABLE IF NOT EXISTS notices (signature TEXT PRIMARY KEY NOT NULL, data TEXT NOT NULL);
+      CREATE TABLE custody_meta (singleton INTEGER PRIMARY KEY CHECK(singleton=1), revision INTEGER NOT NULL);
+      INSERT INTO custody_meta VALUES(1,0);
+      CREATE TABLE custody_requests (actor_id TEXT NOT NULL,request_id TEXT NOT NULL,hash TEXT NOT NULL,receipt TEXT NOT NULL,PRIMARY KEY(actor_id,request_id));
+      CREATE TABLE reconciliations (id TEXT PRIMARY KEY,dispatch_id TEXT NOT NULL,data TEXT NOT NULL);
+      CREATE INDEX reconciliation_dispatch ON reconciliations(dispatch_id);
+      CREATE TABLE retired_instances (key TEXT PRIMARY KEY,host TEXT NOT NULL,session TEXT NOT NULL,instance TEXT,data TEXT NOT NULL);
+      CREATE INDEX retired_scope ON retired_instances(host,session,instance);
+      CREATE TABLE custody_migrations (version INTEGER PRIMARY KEY,data TEXT NOT NULL);`);
+                for (const row of database.prepare("SELECT id,host,session,instance,data FROM dispatches").iterate())
+                    parseDispatch(row);
+                const counts = database.prepare("SELECT COUNT(*) AS count FROM dispatches").get();
+                database.prepare("INSERT INTO custody_migrations VALUES(2,?)").run(JSON.stringify({ fromVersion: version, at: new Date().toISOString(), preservedDispatches: counts.count }));
+                database.pragma("user_version = 2");
+            }).immediate();
+        validateCustodyV2(database);
+        for (const row of database.prepare("SELECT id,host,session,instance,data FROM dispatches").iterate())
+            parseDispatch(row);
+    }
+    catch (error) {
+        database.close();
+        throw error;
+    }
+    return database;
+}
+function validateCustodyV2(database) {
+    custodyRevision(database);
+    for (const query of [
+        "SELECT actor_id,request_id,hash,receipt FROM custody_requests LIMIT 0",
+        "SELECT id,dispatch_id,data FROM reconciliations LIMIT 0",
+        "SELECT key,host,session,instance,data FROM retired_instances LIMIT 0",
+        "SELECT version,data FROM custody_migrations LIMIT 0",
+    ])
+        database.prepare(query).all();
+    for (const row of database.prepare("SELECT key,host,session,instance,data FROM retired_instances").iterate())
+        validateRetiredRow(row);
+}
+function openCheckInStore(file) {
+    const database = openCustodyDatabase(file, "write");
+    const transact = (work) => database.transaction(() => {
+        assertNoCustodyMaintenance(file);
+        custodyCapacity(database, true);
+        return work();
+    }).immediate();
+    function write(record) {
+        const data = JSON.stringify(record);
+        if (Buffer.byteLength(data) > MAX_ROW)
+            refuse("record byte limit");
+        database.prepare(`INSERT INTO dispatches(id,host,session,instance,data) VALUES(?,?,?,?,?)
+      ON CONFLICT(id) DO UPDATE SET data=excluded.data`).run(record.id, record.host, record.session, record.instance, data);
+        advanceCustodyRevision(database);
+    }
+    function notice(signature) {
+        bounded(signature, MAX_ROW - 128, "signature");
+        const row = database.prepare("SELECT data FROM notices WHERE signature=?").get(signature);
+        if (!row)
+            return null;
+        if (Buffer.byteLength(row.data) > MAX_ROW)
+            refuse("notice byte limit");
+        const value = JSON.parse(row.data);
+        if (!object(value) || value.signature !== signature || !timestamp(value.at))
+            refuse("invalid notice schema");
+        return { signature, at: value.at };
+    }
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_checkin_store_opened",
+        message: "opened private check-in custody", meta: { status: "ready" } });
+    return {
+        claimDispatch(input, owner) {
+            if (!validInput(input))
+                refuse("invalid dispatch input schema");
+            bounded(owner, 256, "owner");
+            const record = { ...input, id: dispatchId(input), owner, state: "claimed" };
+            if (bytes(record) + COMPLETION_HEADROOM > MAX_ROW)
+                refuse("reserved record byte limit");
+            return transact(() => {
+                if (hasRetiredCustodyInstance(database, input))
+                    return null;
+                const rows = database.prepare(`SELECT id,host,session,instance,data FROM dispatches
+          WHERE id=? OR (host=? AND session=? AND (instance IS NULL OR ? IS NULL OR instance=?))`)
+                    .all(record.id, input.host, input.session, input.instance, input.instance);
+                for (const row of rows) {
+                    const prior = parseDispatch(row);
+                    if (prior.state === "claimed" || prior.state === "unknown" || prior.id === record.id && prior.state === "sent")
+                        return null;
+                }
+                write(record);
+                return record;
+            });
+        },
+        completeDispatch(id, owner, result) {
+            bounded(owner, 256, "owner");
+            if (!object(result) || !["sent", "not_sent", "unknown"].includes(result.state))
+                refuse("invalid completion state");
+            if (result.reason !== undefined)
+                bounded(result.reason, 1024, "reason");
+            if (result.receipt !== undefined && !validCustodyInputReceipt(result.receipt))
+                refuse("invalid host receipt schema");
+            if (result.receipt && !receiptMatchesOutcome(result.state, result.receipt))
+                refuse("host receipt contradicts completion outcome");
+            transact(() => {
+                const row = database.prepare("SELECT id,host,session,instance,data FROM dispatches WHERE id=?").get(id);
+                if (!row)
+                    refuse("unknown dispatch owner");
+                const prior = parseDispatch(row);
+                if (prior.owner !== owner || prior.state !== "claimed")
+                    refuse("dispatch owner or phase mismatch");
+                if (result.receipt && (result.receipt.requestId !== id || result.receipt.surfaceId !== prior.session
+                    || result.receipt.processInstance !== prior.instance))
+                    refuse("host receipt identity mismatch");
+                write({ ...prior, state: result.state, ...(result.reason === undefined ? {} : { reason: result.reason }),
+                    ...(result.receipt === undefined ? {} : { receipt: copyCustodyInputReceipt(result.receipt) }) });
+            });
+        },
+        shouldNotify(signature) { return notice(signature) === null; },
+        markNotified(signature, at) {
+            bounded(signature, MAX_ROW - 128, "signature");
+            if (!timestamp(at))
+                refuse("invalid notification timestamp");
+            const data = JSON.stringify({ signature, at });
+            if (Buffer.byteLength(data) > MAX_ROW)
+                refuse("notice byte limit");
+            transact(() => {
+                if (!notice(signature)) {
+                    database.prepare("INSERT INTO notices(signature,data) VALUES(?,?)").run(signature, data);
+                    advanceCustodyRevision(database);
+                }
+            });
+        },
+        close() { database.close(); },
+    };
+}

package/dist/senses/shepherd/client.js

@@ -0,0 +1,196 @@
+"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.CmuxSocketError = void 0;
+exports.createCmuxClient = createCmuxClient;
+const node_crypto_1 = require("node:crypto");
+const net = __importStar(require("node:net"));
+const shepherd_config_1 = require("../../heart/shepherd-config");
+const runtime_1 = require("../../nerves/runtime");
+class CmuxSocketError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "CmuxSocketError";
+    }
+}
+exports.CmuxSocketError = CmuxSocketError;
+const ACCESS_REFUSED = /access denied|authentication required|invalid password|not authorized|unauthori[sz]ed/i;
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function parseRecord(line) {
+    try {
+        const value = JSON.parse(line);
+        return isRecord(value) ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+function createCmuxClient(connection, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 5_000;
+    const repair = (0, shepherd_config_1.shepherdRepairHint)(options.agentName ?? "<agent>");
+    const wrap = (line) => connection.auth.kind === "capability"
+        ? `_cmux_capability_v1 ${connection.auth.token} ${line}`
+        : line;
+    const refusal = (text) => text.startsWith("ERROR:") && ACCESS_REFUSED.test(text)
+        ? new CmuxSocketError("auth", `cmux refused the socket connection (${text.slice(0, 200)}); ${repair}`)
+        : null;
+    const connectError = (error) => new CmuxSocketError("unavailable", `cmux socket is not reachable at ${connection.socketPath} (${String(error.code)}); is cmux running?`);
+    /** Opens a connection, runs the password handshake when needed, and hands back a line reader. */
+    function open(onLine, onEnd) {
+        return new Promise((resolve) => {
+            const socket = net.createConnection(connection.socketPath);
+            let buffer = "";
+            let handshake = connection.auth.kind === "password";
+            socket.setEncoding("utf-8");
+            socket.on("error", (error) => onEnd(connectError(error)));
+            socket.on("close", () => onEnd());
+            socket.on("data", (chunk) => {
+                buffer += chunk;
+                let index = buffer.indexOf("\n");
+                while (index >= 0) {
+                    const line = buffer.slice(0, index).trim();
+                    buffer = buffer.slice(index + 1);
+                    index = buffer.indexOf("\n");
+                    if (!line)
+                        continue;
+                    if (handshake) {
+                        handshake = false;
+                        if (line.startsWith("ERROR:") && !line.includes("Unknown command 'auth'")) {
+                            socket.destroy();
+                            onEnd(new CmuxSocketError("auth", `cmux rejected the socket password (${line.slice(0, 200)}); ${repair}`));
+                            continue;
+                        }
+                        resolve(socket);
+                        continue;
+                    }
+                    onLine(line);
+                }
+            });
+            socket.on("connect", () => {
+                if (connection.auth.kind === "password")
+                    socket.write(`auth ${connection.auth.password}\n`);
+                else
+                    resolve(socket);
+            });
+        });
+    }
+    function request(line) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let socket = null;
+            const finish = (error, value) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                socket?.destroy();
+                if (error)
+                    reject(error);
+                else
+                    resolve(value);
+            };
+            const timer = setTimeout(() => finish(new CmuxSocketError("timeout", `cmux did not answer within ${timeoutMs} ms`)), timeoutMs);
+            void open((response) => finish(refusal(response), response), (error) => finish(error ?? new CmuxSocketError("unavailable", "cmux closed the socket before answering"))).then((opened) => {
+                socket = opened;
+                opened.write(`${wrap(line)}\n`);
+            });
+        });
+    }
+    const v2Line = (method, params) => JSON.stringify({ id: (0, node_crypto_1.randomUUID)(), method, params });
+    function parseV2(text) {
+        const parsed = parseRecord(text);
+        if (!parsed)
+            throw new CmuxSocketError(text.startsWith("ERROR:") ? "command_failed" : "protocol", `unexpected cmux response: ${text.slice(0, 200)}`);
+        if (parsed.ok === true)
+            return isRecord(parsed.result) ? parsed.result : {};
+        const error = isRecord(parsed.error) ? parsed.error : {};
+        throw new CmuxSocketError(typeof error.code === "string" ? error.code : "error", typeof error.message === "string" && error.message ? error.message : "cmux error");
+    }
+    return {
+        async call(method, params = {}) {
+            const text = await request(v2Line(method, params));
+            const result = parseV2(text);
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_call", message: "cmux socket call answered", meta: { method } });
+            return result;
+        },
+        async command(line) {
+            const text = await request(line);
+            if (text.startsWith("ERROR:"))
+                throw new CmuxSocketError("command_failed", text.slice(0, 500));
+            return text;
+        },
+        stream(params, handlers) {
+            let closed = false;
+            let socket = null;
+            const end = (error) => {
+                if (closed)
+                    return;
+                closed = true;
+                socket?.destroy();
+                handlers.onClose(error);
+            };
+            void open((line) => {
+                if (closed)
+                    return;
+                const refused = refusal(line);
+                if (refused)
+                    return end(refused);
+                const frame = parseRecord(line);
+                if (!frame)
+                    return end(new CmuxSocketError("protocol", `unexpected cmux event frame: ${line.slice(0, 200)}`));
+                if (frame.ok === false) {
+                    try {
+                        parseV2(line);
+                    }
+                    catch (error) {
+                        return end(error);
+                    }
+                }
+                handlers.onFrame(frame);
+            }, end).then((opened) => {
+                socket = opened;
+                if (closed)
+                    opened.destroy();
+                else
+                    opened.write(`${wrap(v2Line("events.stream", params))}\n`);
+            });
+            return { close: () => end() };
+        },
+    };
+}