@ouro.bot/cli 0.1.0-alpha.93 → 0.1.0-alpha.930

package/dist/senses/shepherd/notice-outbox.js

@@ -0,0 +1,262 @@
+"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.noticeRecordId = noticeRecordId;
+exports.readNoticeOutbox = readNoticeOutbox;
+exports.enqueueNotice = enqueueNotice;
+exports.noticeDeliveryState = noticeDeliveryState;
+exports.knownNotice = knownNotice;
+exports.declareNoticeTargets = declareNoticeTargets;
+exports.claimPendingNotices = claimPendingNotices;
+exports.recordNoticeDelivery = recordNoticeDelivery;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_util_1 = require("node:util");
+const file_lock_1 = require("../../heart/file-lock");
+const runtime_1 = require("../../nerves/runtime");
+const redact_1 = require("./redact");
+const returns_1 = require("./returns");
+const MAX_BYTES = 2 * 1024 * 1024;
+const RECENT_SENT = 256;
+const STATES = new Set(["pending", "sent", "unknown"]);
+const KINDS = new Set(["premature", "gate", "done", "working", "waiting", "unclear", "error", "loop_guard"]);
+const fileFor = (root) => path.join((0, returns_1.shepherdStateDir)(root), "notice-outbox.json");
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+const nullableString = (value) => value === null || typeof value === "string";
+function isReturn(value) {
+    return object(value)
+        && ["at", "host", "session", "transition", "kind", "action", "reason"].every(key => typeof value[key] === "string")
+        && KINDS.has(String(value.kind)) && ["respond", "let_through"].includes(String(value.action))
+        && ["agent", "cwd", "task", "reply"].every(key => nullableString(value[key]))
+        && ["latencyMs", "inputTokens"].every(key => value[key] === null || typeof value[key] === "number")
+        && (value.title === undefined || typeof value.title === "string")
+        && (value.workspaceTitle === undefined || nullableString(value.workspaceTitle));
+}
+function isDelivery(value) {
+    return object(value) && typeof value.state === "string" && STATES.has(value.state)
+        && typeof value.at === "string" && Number.isSafeInteger(value.attempts) && Number(value.attempts) >= 0
+        && (value.reason === undefined || typeof value.reason === "string")
+        && (value.messageId === undefined || typeof value.messageId === "string");
+}
+function noticeRecordId(record) {
+    return (0, node_crypto_1.createHash)("sha256").update(JSON.stringify([record.host, record.session, record.transition, record.at])).digest("hex");
+}
+function readNoticeOutbox(root) {
+    let raw;
+    try {
+        raw = fs.readFileSync(fileFor(root), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    if (Buffer.byteLength(raw) > MAX_BYTES)
+        throw new Error("Shepherd notice outbox exceeds its 2 MiB limit");
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Shepherd notice outbox is malformed JSON");
+    }
+    if (!object(value) || value.schemaVersion !== 1 || !Array.isArray(value.entries))
+        throw new Error("invalid Shepherd notice outbox schema");
+    const entries = [];
+    const seen = new Set();
+    for (const entry of value.entries) {
+        if (!object(entry) || typeof entry.id !== "string" || !isReturn(entry.record)
+            || !object(entry.deliveries) || !Object.values(entry.deliveries).every(isDelivery)
+            || entry.id !== noticeRecordId(entry.record) || seen.has(entry.id))
+            throw new Error("invalid Shepherd notice outbox entry");
+        seen.add(entry.id);
+        entries.push({ id: entry.id, record: entry.record, deliveries: entry.deliveries });
+    }
+    return entries;
+}
+function atomicWrite(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const encoded = JSON.stringify(value);
+    if (Buffer.byteLength(encoded) > MAX_BYTES)
+        throw new Error("Shepherd notice outbox exceeds its 2 MiB limit");
+    const temp = `${file}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+    const fd = fs.openSync(temp, "wx", 0o600);
+    try {
+        fs.writeFileSync(fd, encoded);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    fs.renameSync(temp, file);
+}
+function persist(root, entries) {
+    const sent = entries.filter(entry => Object.keys(entry.deliveries).length > 0 && Object.values(entry.deliveries).every(value => value.state === "sent"));
+    const older = sent.slice(0, Math.max(0, sent.length - RECENT_SENT));
+    const ids = new Set(older.map(entry => entry.id));
+    // Archive acceptances before removing their payloads from the active snapshot.
+    for (const entry of older)
+        atomicWrite(path.join((0, returns_1.shepherdStateDir)(root), "notice-receipts", `${entry.id}.json`), entry);
+    atomicWrite(fileFor(root), { schemaVersion: 1, entries: entries.filter(entry => !ids.has(entry.id)) });
+}
+function archived(root, id) {
+    const file = path.join((0, returns_1.shepherdStateDir)(root), "notice-receipts", `${id}.json`);
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const value = JSON.parse(raw);
+    if (!object(value) || value.id !== id || !isReturn(value.record) || !object(value.deliveries)
+        || !Object.values(value.deliveries).every(isDelivery))
+        throw new Error("invalid archived Shepherd notice receipt");
+    return { id, record: value.record, deliveries: value.deliveries };
+}
+function mutate(root, change) {
+    const dir = (0, returns_1.shepherdStateDir)(root);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return (0, file_lock_1.withFileLock)(dir, "notice-outbox", () => {
+        const entries = readNoticeOutbox(root);
+        const result = change(entries);
+        persist(root, entries);
+        return result;
+    }, { waitMs: 1000 });
+}
+function enqueueNotice(root, record) {
+    if (!isReturn(record))
+        return Promise.reject(new Error("invalid Shepherd return for a notice"));
+    const redacted = {
+        ...record,
+        reason: (0, redact_1.redactSecrets)(record.reason),
+        reply: record.reply === null ? null : (0, redact_1.redactSecrets)(record.reply),
+        ...(record.title !== undefined ? { title: (0, redact_1.redactSecrets)(record.title) } : {}),
+        ...(record.workspaceTitle !== undefined && record.workspaceTitle !== null ? { workspaceTitle: (0, redact_1.redactSecrets)(record.workspaceTitle) } : {}),
+    };
+    const normalized = JSON.parse(JSON.stringify(redacted));
+    if (!isReturn(normalized))
+        return Promise.reject(new Error("invalid normalized Shepherd return for a notice"));
+    const safe = normalized;
+    const id = noticeRecordId(safe);
+    return mutate(root, entries => {
+        const existing = entries.find(entry => entry.id === id) ?? archived(root, id);
+        if (existing && !(0, node_util_1.isDeepStrictEqual)(existing.record, safe))
+            throw new Error("the same return has a different notice body");
+        if (!existing)
+            entries.push({ id, record: safe, deliveries: {} });
+        return id;
+    }).then(value => {
+        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_notice_queued", message: "persisted a Shepherd owner notice intent", meta: { id } });
+        return value;
+    });
+}
+function noticeDeliveryState(entry, friendId) {
+    return Object.hasOwn(entry.deliveries, friendId) ? entry.deliveries[friendId].state : "pending";
+}
+function knownNotice(root, id, entries) {
+    if (!/^[a-f0-9]{64}$/.test(id))
+        throw new Error(`unknown notice: ${id}`);
+    return entries.find(value => value.id === id) ?? archived(root, id);
+}
+function validTarget(friendId) {
+    return !!friendId && !["__proto__", "constructor", "prototype"].includes(friendId);
+}
+function selectedEntries(root, entries, ids) {
+    return ids.map(id => {
+        const entry = knownNotice(root, id, entries);
+        if (!entry)
+            throw new Error(`unknown notice: ${id}`);
+        return entry;
+    });
+}
+function declareNoticeTargets(root, ids, friendIds, at) {
+    if (!friendIds.every(validTarget))
+        return Promise.reject(new Error("invalid notice target"));
+    return mutate(root, entries => {
+        for (const entry of selectedEntries(root, entries, ids)) {
+            if (!entries.includes(entry) && friendIds.some(friendId => !Object.hasOwn(entry.deliveries, friendId)))
+                throw new Error("notice is already settled; it cannot acquire new recipients");
+            for (const friendId of friendIds) {
+                if (!Object.hasOwn(entry.deliveries, friendId))
+                    entry.deliveries[friendId] = { state: "pending", at, attempts: 0 };
+            }
+        }
+    });
+}
+/** Claim under the same cross-process lock as receipts, before any transport side effect. */
+function claimPendingNotices(root, ids, friendId, at) {
+    if (!validTarget(friendId))
+        return Promise.reject(new Error("invalid notice target"));
+    return mutate(root, entries => {
+        const claimed = selectedEntries(root, entries, ids).filter(entry => noticeDeliveryState(entry, friendId) === "pending");
+        for (const entry of claimed) {
+            if (!entries.includes(entry))
+                throw new Error("notice is already settled; it cannot acquire new recipients");
+            entry.deliveries[friendId] = {
+                state: "unknown", at, reason: "awaiting transport acceptance", attempts: (entry.deliveries[friendId]?.attempts ?? 0) + 1,
+            };
+        }
+        return claimed;
+    });
+}
+function recordNoticeDelivery(root, ids, friendId, receipt) {
+    if (!validTarget(friendId))
+        return Promise.reject(new Error("invalid notice target"));
+    return mutate(root, entries => {
+        let updated = 0;
+        for (const entry of selectedEntries(root, entries, ids)) {
+            if (!entries.includes(entry) && !Object.hasOwn(entry.deliveries, friendId))
+                throw new Error("notice is already settled; it cannot acquire new recipients");
+            const previous = Object.hasOwn(entry.deliveries, friendId) ? entry.deliveries[friendId] : undefined;
+            // A late failure cannot erase an acceptance another worker already recorded.
+            if (previous?.state === "sent")
+                continue;
+            entry.deliveries[friendId] = {
+                ...receipt,
+                ...(receipt.reason ? { reason: (0, redact_1.redactSecrets)(receipt.reason) } : {}),
+                attempts: previous?.state === "unknown" ? previous.attempts : (previous?.attempts ?? 0) + 1,
+            };
+            updated += 1;
+        }
+        return updated;
+    }).then(updated => {
+        if (updated > 0)
+            (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_notice_receipt", message: "persisted a Shepherd owner notice delivery outcome", meta: { friendId, state: receipt.state, notices: updated } });
+    });
+}

package/dist/senses/shepherd/owner-notice.js

@@ -0,0 +1,325 @@
+"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.NOTICE_RETRY_MS = exports.NOTICE_LIST_MAX = exports.NOTICE_COALESCE_MS = void 0;
+exports.noticeWanted = noticeWanted;
+exports.plain = plain;
+exports.noticeLine = noticeLine;
+exports.noticeMessage = noticeMessage;
+exports.resolveNoticeTargets = resolveNoticeTargets;
+exports.chooseTeamsBot = chooseTeamsBot;
+exports.createTeamsNoticeSender = createTeamsNoticeSender;
+exports.createOwnerNotifier = createOwnerNotifier;
+const path = __importStar(require("node:path"));
+const friends_1 = require("@ouro.bot/friends");
+const await_alert_1 = require("../../heart/awaiting/await-alert");
+const config_1 = require("../../heart/config");
+const runtime_1 = require("../../nerves/runtime");
+const returns_1 = require("./returns");
+const notice_outbox_1 = require("./notice-outbox");
+/**
+ * The owner notice: after a judged return, the agent's owner hears what happened in one short plain message on their
+ * own channel. It is deterministic, written here and sent with no model turn, so the owner hears about every return the
+ * policy covers whether or not the Ouro agent decides it matters. Returns that arrive close together share one message.
+ */
+exports.NOTICE_COALESCE_MS = 5_000;
+/** Returns named one by one in a coalesced message; the rest are counted. */
+exports.NOTICE_LIST_MAX = 6;
+exports.NOTICE_RETRY_MS = 30_000;
+const NAME_MAX = 60;
+const REASON_MAX = 300;
+const REPLY_MAX = 240;
+/** Kinds a "needs-me" owner still hears about. */
+const NEEDS_ME = new Set(["gate", "done", "loop_guard"]);
+function noticeWanted(policy, record) {
+    if (policy === "off")
+        return false;
+    return policy === "every" || NEEDS_ME.has(record.kind);
+}
+/**
+ * Untrusted terminal text as one bounded plain line: no control or invisible characters, and nothing Teams could read as
+ * markup, a mention or code (`< > [ ] * ~ # | \ @` and backticks). Double quotes become single, so a quoted reply stays one quote.
+ */
+function plain(value, max) {
+    const flat = value
+        .replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+/gu, " ")
+        .replace(/[<>[\]*~#|\\@`]+/g, " ")
+        .replace(/"/g, "'")
+        .replace(/\s+/g, " ")
+        .trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max - 1).trimEnd()}…`;
+}
+function who(record, location) {
+    const session = typeof location === "object" ? location : undefined;
+    const agentName = record.agent ?? session?.agent;
+    const cwd = record.cwd ?? session?.cwd;
+    const agent = agentName ? plain(agentName, NAME_MAX) : "";
+    const folder = cwd ? plain(path.basename(cwd), NAME_MAX) : "";
+    const ref = typeof location === "string" ? location : session?.ref;
+    const handle = plain(ref ?? record.session.slice(0, 8), NAME_MAX);
+    const labels = [record.workspaceTitle ?? session?.workspaceTitle, record.title ?? session?.title].filter((label) => !!label).map((label) => plain(label, NAME_MAX));
+    const where = labels.length ? `${labels.join(" / ")}; ${handle}` : handle;
+    return `${agent || "A coding agent"}${folder ? ` in ${folder}` : ""}${where ? ` (${where})` : ""}`;
+}
+/** One return as one sentence pair: who returned, what Shepherd did, and why. */
+function noticeLine(record, location) {
+    const subject = who(record, location);
+    const why = `Why: ${plain(record.reason, REASON_MAX) || "no reason given"}`;
+    switch (record.kind) {
+        case "premature":
+            if (record.action === "respond" && record.reply) {
+                const sent = record.reply.startsWith("key:") ? `pressed ${plain(record.reply.slice(4), 10)}` : `sent it back: "${plain(record.reply, REPLY_MAX)}"`;
+                return `${subject} stopped early, so I ${sent}. ${why}`;
+            }
+            return `${subject} stopped early, but I did not answer it, so it is waiting for you. ${why}`;
+        case "gate":
+            return `${subject} needs you. ${why}`;
+        case "done":
+            return `${subject} says it is done. ${why}`;
+        case "waiting":
+            return `${subject} is waiting on an outside dependency; the work is not yet delivered. ${why}`;
+        case "loop_guard":
+            return `${subject}: I stopped answering it after too many replies, so it is waiting for you. ${why}`;
+        case "working":
+            return `${subject} is still working in the background and has news. ${why}`;
+        case "unclear":
+            return `${subject} stopped and I could not tell what it needs, so I left it. ${why}`;
+        default:
+            return `${subject} stopped but I could not judge it, so I left it. ${why}`;
+    }
+}
+/** One message for a burst: a single return is its line; several are a short list, the extra ones counted. */
+function noticeMessage(records, refs = new Map()) {
+    const lines = records.slice(0, exports.NOTICE_LIST_MAX).map((record) => noticeLine(record, refs.get(record.session)));
+    if (records.length === 1)
+        return lines[0];
+    const more = records.length - lines.length;
+    return [`${records.length} coding agents stopped:`, ...lines.map((line) => `- ${line}`), ...(more > 0 ? [`- and ${more} more.`] : [])].join("\n");
+}
+function teamsAadId(friend) {
+    const ext = friend.externalIds.find((entry) => entry.provider === "aad" && !entry.externalId.startsWith("group:"));
+    return ext ? { id: ext.externalId.toLowerCase(), tenantId: ext.tenantId } : null;
+}
+/**
+ * Who hears the notice: every family friend reachable on Teams (a Teams user id the bot can open a chat with), once per
+ * Teams user even when several friend records share one. Teams is the only proactive channel wired today.
+ */
+async function resolveNoticeTargets(agentRoot, store = new friends_1.FileFriendStore(path.join(agentRoot, "friends"))) {
+    const seen = new Set();
+    const targets = [];
+    for (const friend of await store.listAll()) {
+        if (friend.trustLevel !== "family")
+            continue;
+        const aad = teamsAadId(friend);
+        if (!aad || seen.has(aad.id))
+            continue;
+        seen.add(aad.id);
+        targets.push({ friendId: friend.id, name: friend.name, key: (0, await_alert_1.resolveAlertKey)(agentRoot, friend.id, "teams") ?? "shepherd", ...(aad.tenantId ? { tenantId: aad.tenantId } : {}) });
+    }
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_notice_targets", message: "resolved Shepherd owner notice targets", meta: { count: targets.length } });
+    return targets;
+}
+/** The bot whose tenant is the friend's: the secondary bot when it serves that tenant, else the primary. */
+function chooseTeamsBot(tenantId, primary, secondary) {
+    if (tenantId && secondary.clientId && secondary.tenantId === tenantId)
+        return secondary;
+    return primary.clientId ? primary : null;
+}
+/* v8 ignore start -- the live Teams SDK client; its token and REST calls need a real bot registration @preserve */
+async function liveBotApi(config) {
+    const { App } = await Promise.resolve().then(() => __importStar(require("@microsoft/teams.apps")));
+    const app = new App({
+        clientId: config.clientId,
+        ...(config.clientSecret ? { clientSecret: config.clientSecret } : {}),
+        tenantId: config.tenantId,
+        ...(config.managedIdentityClientId ? { managedIdentityClientId: config.managedIdentityClientId } : {}),
+    });
+    return { id: app.id, conversations: app.api.conversations };
+}
+/* v8 ignore stop */
+/**
+ * Sends through the Teams sense's own proactive path (`sendProactiveTeamsMessageToSession`: trust check, internal-content
+ * guard, 1:1 chat with the friend's Teams id) with a bot client of this process's own, built from the agent's Teams
+ * credentials. Nothing listens on a port: the client only acquires a bot token and calls the Bot Framework.
+ */
+function createTeamsNoticeSender(agentRoot, deps = {}) {
+    const bots = new Map();
+    return async (target, text) => {
+        const config = chooseTeamsBot(target.tenantId, (deps.primary ?? config_1.getTeamsConfig)(), (deps.secondary ?? config_1.getTeamsSecondaryConfig)());
+        if (!config)
+            return { delivered: false, reason: "no_teams_bot" };
+        let bot = bots.get(config.clientId);
+        if (!bot) {
+            /* v8 ignore next -- tests inject the bot client; the live Bot Framework client is built only in the running sense @preserve */
+            bot = (deps.botApi ?? liveBotApi)(config);
+            bots.set(config.clientId, bot);
+            // A client that could not be built is built again for the next notice.
+            bot.catch(() => bots.delete(config.clientId));
+        }
+        const { sendProactiveTeamsMessageToSession } = await Promise.resolve().then(() => __importStar(require("../teams")));
+        return sendProactiveTeamsMessageToSession({ friendId: target.friendId, sessionKey: target.key, text, textFormat: "plain", intent: "generic_outreach", captureReceipt: true }, { botApi: await bot, store: new friends_1.FileFriendStore(path.join(agentRoot, "friends")) });
+    };
+}
+/** Collects notices for NOTICE_COALESCE_MS after the first, then sends them as one message. It never throws. */
+function createOwnerNotifier(options) {
+    const { agent, policy } = options;
+    const resolveTargets = options.resolveTargets ?? (() => resolveNoticeTargets(options.agentRoot));
+    const send = options.send ?? createTeamsNoticeSender(options.agentRoot);
+    const retryWrites = new Map();
+    const writes = new Set();
+    let cancel = null;
+    let stopped = false;
+    let flushing = null;
+    function schedule(ms) {
+        if (!stopped && policy !== "off")
+            cancel ??= options.schedule(() => { void flush(); }, ms);
+    }
+    function persistIntent(record) {
+        const key = `${record.host}:${record.session}:${record.transition}:${record.at}`;
+        retryWrites.set(key, record);
+        const write = (0, notice_outbox_1.enqueueNotice)(options.agentRoot, record).then(() => {
+            retryWrites.delete(key);
+        }).catch(error => {
+            (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.shepherd_notice_error", message: "could not persist a Shepherd owner notice intent; it remains waiting", meta: { agent, error: error.message } });
+            schedule(exports.NOTICE_RETRY_MS);
+        }).finally(() => { writes.delete(write); });
+        writes.add(write);
+        return write;
+    }
+    async function runFlush() {
+        cancel?.();
+        cancel = null;
+        if (stopped || policy === "off")
+            return;
+        await Promise.all([...writes]);
+        for (const record of [...retryWrites.values()])
+            await persistIntent(record);
+        try {
+            const entries = (0, notice_outbox_1.readNoticeOutbox)(options.agentRoot).filter(entry => noticeWanted(policy, entry.record) && (Object.keys(entry.deliveries).length === 0 || Object.values(entry.deliveries).some(value => value.state !== "sent")));
+            if (entries.length === 0)
+                return;
+            const refs = new Map();
+            try {
+                for (const session of await options.listSessions())
+                    refs.set(session.id, session);
+            }
+            catch {
+                // Without the host's handles, each notice names a short session id instead.
+            }
+            const targets = await resolveTargets();
+            if (targets.length === 0) {
+                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_notice_no_target", message: "no family friend is reachable on Teams, so the Shepherd owner notice was not sent", meta: { agent, returns: entries.length } });
+                schedule(exports.NOTICE_RETRY_MS);
+                return;
+            }
+            await (0, notice_outbox_1.declareNoticeTargets)(options.agentRoot, entries.map(entry => entry.id), targets.map(target => target.friendId), new Date().toISOString());
+            const reachable = new Set(targets.map(target => target.friendId));
+            let retry = entries.some(entry => Object.entries(entry.deliveries).some(([friendId, delivery]) => delivery.state === "pending" && !reachable.has(friendId)));
+            for (const target of targets) {
+                const pending = entries.filter(entry => (0, notice_outbox_1.noticeDeliveryState)(entry, target.friendId) === "pending");
+                for (let start = 0; start < pending.length && !stopped; start += exports.NOTICE_LIST_MAX) {
+                    // Only the worker that atomically claims a pending entry may initiate transport.
+                    const batch = await (0, notice_outbox_1.claimPendingNotices)(options.agentRoot, pending.slice(start, start + exports.NOTICE_LIST_MAX).map(entry => entry.id), target.friendId, new Date().toISOString());
+                    if (batch.length === 0)
+                        continue;
+                    const ids = batch.map(entry => entry.id);
+                    try {
+                        const result = await send(target, noticeMessage(batch.map(entry => entry.record), refs));
+                        const state = result.delivered ? "sent"
+                            : result.delivery ? result.delivery.state === "not_sent" ? "pending" : "unknown"
+                                : result.reason && result.reason !== "send_error" ? "pending" : "unknown";
+                        await (0, notice_outbox_1.recordNoticeDelivery)(options.agentRoot, ids, target.friendId, {
+                            state, at: new Date().toISOString(), ...(result.reason ? { reason: result.reason } : {}),
+                            ...(result.delivery?.messageId ? { messageId: result.delivery.messageId } : {}),
+                        });
+                        retry ||= state === "pending";
+                        (0, runtime_1.emitNervesEvent)({
+                            level: result.delivered ? "info" : "warn", component: "senses",
+                            event: result.delivered ? "senses.shepherd_notice_sent" : "senses.shepherd_notice_not_sent",
+                            message: result.delivered ? "sent the Shepherd owner notice" : "the Shepherd owner notice was not delivered",
+                            meta: { agent, friendId: target.friendId, returns: batch.length, ...(result.delivered ? {} : { reason: result.reason ?? "unknown" }) },
+                        });
+                    }
+                    catch (error) {
+                        (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.shepherd_notice_error", message: "sending the Shepherd owner notice failed; its outcome remains unknown", meta: { agent, friendId: target.friendId, error: error.message } });
+                    }
+                }
+            }
+            if (retry)
+                schedule(exports.NOTICE_RETRY_MS);
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.shepherd_notice_error", message: "preparing the Shepherd owner notice failed", meta: { agent, error: error.message } });
+            schedule(exports.NOTICE_RETRY_MS);
+        }
+    }
+    function flush() {
+        if (flushing)
+            return flushing;
+        flushing = runFlush().finally(() => { flushing = null; });
+        return flushing;
+    }
+    try {
+        const existing = (0, notice_outbox_1.readNoticeOutbox)(options.agentRoot);
+        let recovered = false;
+        for (const record of (0, returns_1.readReturns)(options.agentRoot)) {
+            if (record.noticeEligible === true && noticeWanted(policy, record) && !(0, notice_outbox_1.knownNotice)(options.agentRoot, (0, notice_outbox_1.noticeRecordId)(record), existing)) {
+                void persistIntent(record);
+                recovered = true;
+            }
+        }
+        if (recovered || existing.some(entry => Object.keys(entry.deliveries).length === 0 || Object.values(entry.deliveries).some(value => value.state === "pending")))
+            schedule(exports.NOTICE_RETRY_MS);
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({ level: "error", component: "senses", event: "senses.shepherd_notice_error", message: "could not read waiting Shepherd owner notices", meta: { agent, error: error.message } });
+        schedule(exports.NOTICE_RETRY_MS);
+    }
+    return {
+        notify(record) {
+            if (stopped || !noticeWanted(policy, record))
+                return Promise.resolve();
+            const write = persistIntent(record);
+            schedule(exports.NOTICE_COALESCE_MS);
+            return write;
+        },
+        flush,
+        stop() {
+            stopped = true;
+            cancel?.();
+            cancel = null;
+        },
+    };
+}

package/dist/senses/shepherd/redact.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FINGERPRINT_READ_LINES = exports.FINGERPRINT_LINES = void 0;
+exports.redactSecrets = redactSecrets;
+exports.screenTail = screenTail;
+exports.withoutNumbers = withoutNumbers;
+exports.screenFingerprint = screenFingerprint;
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../../nerves/runtime");
+/**
+ * Terminal screens and agents' last messages can show credentials. Everything Shepherd hands to a
+ * model or a tool result (screen text, last messages) goes through this first. It is a best-effort net for
+ * secret-shaped strings, not a guarantee, so callers also keep their output bounded.
+ */
+const REDACTED = "[redacted]";
+const WHOLE_MATCH = [
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+    /\bsk-[A-Za-z0-9_-]{16,}/g,
+    /\bgh[pousr]_[A-Za-z0-9]{20,}/g,
+    /\bgithub_pat_[A-Za-z0-9_]{20,}/g,
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g,
+    /\bv1\.[A-Za-z0-9_-]{40,}\.[A-Za-z0-9_-]{40,}/g,
+    /\bxox[abprs]-[A-Za-z0-9-]{10,}/g,
+];
+/** Keep the label (group 1), redact the value. */
+const LABELLED_VALUE = [
+    /(\b(?:Bearer|Basic)\s+)[A-Za-z0-9._~+/=-]{6,}/gi,
+    /(\b(?:password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key|client[_-]?secret)\s*[=:]\s*)(?:"[^"]*"|'[^']*'|[^\s'"&]+)/gi,
+    /([?&](?:token|key|api_key|access_token|sig|signature)=)[^&\s]+/gi,
+];
+function redactSecrets(text) {
+    let result = text;
+    for (const pattern of WHOLE_MATCH)
+        result = result.replace(pattern, REDACTED);
+    for (const pattern of LABELLED_VALUE)
+        result = result.replace(pattern, `$1${REDACTED}`);
+    if (result !== text) {
+        (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_redacted", message: "redacted secret-shaped text from cmux output", meta: { removedChars: text.length - result.length } });
+    }
+    return result;
+}
+/** The last `lines` lines of a screen, without its trailing blank space. */
+function screenTail(text, lines) {
+    return text.replace(/\s+$/, "").split("\n").slice(-lines).join("\n");
+}
+/**
+ * A screen with its numbers taken out: a timer or token counter at a waiting prompt is not the
+ * screen moving on. A timer can tick, grow a unit (`59s` to `1m 0s`), and come and go between
+ * redraws, shifting the padding beside it, so runs of numbers with time units vanish along with
+ * the space around them, and runs of spaces and line-end padding do not count.
+ */
+function withoutNumbers(screen) {
+    return screen.replace(/[ \t]*(\d+[hms]?[ \t]*)+/g, " ").replace(/[ \t]+/g, " ").replace(/ $/gm, "");
+}
+/** Lines a screen fingerprint covers, and the fewest lines a read must take to compute one. */
+exports.FINGERPRINT_LINES = 20;
+exports.FINGERPRINT_READ_LINES = 40;
+/**
+ * A short fingerprint of what a terminal shows now: its last lines, redacted, with numbers blanked so a ticking timer does
+ * not count as a change. `shepherd_read` hands it out and `shepherd_send` compares it, so a key is pressed only on the
+ * screen someone actually saw.
+ */
+function screenFingerprint(text) {
+    return (0, node_crypto_1.createHash)("sha256").update(withoutNumbers(screenTail(redactSecrets(text), exports.FINGERPRINT_LINES))).digest("hex").slice(0, 16);
+}