@ouro.bot/cli 0.1.0-alpha.99 → 0.1.0-alpha.990

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

@@ -0,0 +1,489 @@
+"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_REPLY_LINE = 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.readEnabledReachChannels = readEnabledReachChannels;
+exports.resolveNoticeTargets = resolveNoticeTargets;
+exports.noticeDeliveryId = noticeDeliveryId;
+exports.chooseTeamsBot = chooseTeamsBot;
+exports.createNoticeSender = createNoticeSender;
+exports.createOwnerNotifier = createOwnerNotifier;
+const node_crypto_1 = require("node:crypto");
+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 identity_1 = require("../../heart/identity");
+const reach_channel_1 = require("../../heart/reach-channel");
+const runtime_1 = require("../../nerves/runtime");
+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;
+/** Distinct sessions named in a digest; the remaining sessions are counted. */
+exports.NOTICE_LIST_MAX = 6;
+exports.NOTICE_RETRY_MS = 30_000;
+const NAME_MAX = 60;
+const REASON_MAX = 300;
+const NOTE_MAX = 400;
+const REPLY_MAX = 240;
+const BLOCK_DESCRIPTION = {
+    reply_invalid: "I couldn't come up with a safe reply",
+    menu_disallowed: "it's showing a menu, and I don't pick menu options",
+    host_unverified: "I couldn't confirm it was safe to type there",
+    guidance: "your Shepherd guidance says to leave it",
+    loop_guard: "I've already answered it too many times",
+    focus: "you're in it or just left it",
+    state_changed: "it changed while I was looking",
+    custody: "an earlier reply may still be on its way",
+    stopped: "Shepherd was stopping",
+};
+/** 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()}…`;
+}
+/**
+ * The session as a person would name it: the agent, the tab or workspace title it works under, and its folder. A host
+ * handle such as `surface:12` is added only when another session would read the same, so a reply reaches the right one.
+ */
+function label(agentName, cwd, titles) {
+    const agent = agentName ? plain(agentName, NAME_MAX) : "";
+    const folder = cwd ? plain(path.basename(cwd), NAME_MAX) : "";
+    const title = titles.map(value => value ? plain(value, NAME_MAX) : "").find(value => value && value.toLowerCase() !== folder.toLowerCase());
+    return `${agent || "A coding agent"}${title ? ` on ${title}` : ""}${folder ? ` in ${folder}` : ""}`;
+}
+function who(record, location) {
+    const session = typeof location === "object" ? location : undefined;
+    return label(record.agent ?? session?.agent, record.cwd ?? session?.cwd, [record.title ?? session?.title, record.workspaceTitle ?? session?.workspaceTitle]);
+}
+function handle(record, location) {
+    const ref = typeof location === "string" ? location : location?.ref;
+    return plain(ref || record.session.slice(0, 8), NAME_MAX);
+}
+/** The judge's own note to the owner, used when Shepherd took no action that the note could misdescribe. */
+const NOTE_KINDS = new Set(["gate", "done", "waiting", "working"]);
+/** One return as one or two sentences, written to the owner: who, what happened, and what Shepherd did. */
+function noticeLine(record, location, ambiguous = false) {
+    const subject = `${who(record, location)}${ambiguous ? ` (${handle(record, location)})` : ""}`;
+    const note = record.note ? plain(record.note, NOTE_MAX) : "";
+    if (note && NOTE_KINDS.has(record.kind))
+        return `${subject}: ${note}`;
+    const reason = plain(record.reason, REASON_MAX);
+    const because = reason ? ` ${reason.replace(/^./, first => first.toUpperCase())}${/[.!?…]$/.test(reason) ? "" : "."}` : "";
+    switch (record.kind) {
+        case "premature":
+            if (record.action === "respond" && record.reply) {
+                const sent = record.reply.startsWith("key:") ? `pressed ${plain(record.reply.slice(4), 10)}` : `told it: "${plain(record.reply, REPLY_MAX)}"`;
+                return `${subject} stopped early, so I ${sent}.${because}`;
+            }
+            if (record.actionBlockReason)
+                return `${subject} stopped early. I didn't answer because ${BLOCK_DESCRIPTION[record.actionBlockReason]}.${because}`;
+            return `${subject} stopped early and I left it for you.${because}`;
+        case "gate":
+            return `${subject} needs you.${because}`;
+        case "done":
+            return `${subject} says it's done.${because}`;
+        case "waiting":
+            return `${subject} is waiting on something outside it; it isn't done yet.${because}`;
+        case "loop_guard":
+            return `${subject} kept stopping, so I stopped answering it and left it for you.${because}`;
+        case "working":
+            return `${subject} is still working, with news.${because}`;
+        case "unclear":
+            return `I couldn't tell what ${subject} is doing.${because}`;
+        default:
+            return `I couldn't check on ${subject}.${because}`;
+    }
+}
+/** Closes every notice: the person answers in the same conversation, and the agent relays it with `shepherd_send`. */
+exports.NOTICE_REPLY_LINE = "Reply here and I'll pass it on.";
+/** A bounded display of latest observations; all input records retain delivery custody. */
+function noticeMessage(records, refs = new Map(), context = {}) {
+    const latest = new Map();
+    for (const record of records) {
+        const key = JSON.stringify([record.host, record.session]);
+        const previous = latest.get(key);
+        const at = Date.parse(record.at);
+        const previousAt = previous ? Date.parse(previous.at) : NaN;
+        if (!previous || (Number.isFinite(at) && (!Number.isFinite(previousAt) || at > previousAt))
+            || ((!Number.isFinite(at) && !Number.isFinite(previousAt) || at === previousAt) && record.transition > previous.transition))
+            latest.set(key, record);
+    }
+    const sessions = [...latest].sort(([a], [b]) => a < b ? -1 : 1).map(([, record]) => record);
+    // Labels shared by two different sessions, among those the host lists and those in this message.
+    const owners = new Map();
+    const claim = (name, id) => owners.set(name, (owners.get(name) ?? new Set()).add(id));
+    for (const [id, location] of refs)
+        if (typeof location === "object")
+            claim(label(location.agent, location.cwd, [location.title, location.workspaceTitle]), id);
+    for (const record of sessions)
+        claim(who(record, refs.get(record.session)), record.session);
+    const lines = sessions.slice(0, exports.NOTICE_LIST_MAX).map(record => {
+        const line = noticeLine(record, refs.get(record.session), owners.get(who(record, refs.get(record.session))).size > 1);
+        if (!context.recovered)
+            return line;
+        const at = Date.parse(record.at);
+        return `${line} (${Number.isFinite(at) ? `observed at ${new Date(at).toISOString()}` : "observation time unknown"})`;
+    });
+    const more = sessions.length - lines.length;
+    const body = sessions.length === 1 ? lines[0]
+        : [`${sessions.length} updates:`, ...lines.map(line => `- ${line}`), ...(more > 0 ? [`- and ${more} more.`] : [])].join("\n");
+    const recovered = sessions.length === 1 ? "Catching up on something I saw earlier, so it may be out of date:" : "Catching up on things I saw earlier, so these may be out of date:";
+    return `${context.recovered ? `${recovered}\n${body}` : body}\n\n${exports.NOTICE_REPLY_LINE}`;
+}
+/**
+ * The channels this agent can reach people on from this machine: its enabled Teams sense, and its enabled BlueBubbles
+ * sense when this machine has a BlueBubbles connection (credentials live per machine, so another machine may own it).
+ */
+function readEnabledReachChannels(agent, agentRoot, blueBubblesConfig = config_1.getBlueBubblesConfig) {
+    const enabled = new Set();
+    try {
+        const senses = (0, identity_1.loadAgentConfig)({ agentName: agent, agentRoot }).senses;
+        if (senses?.bluebubbles?.enabled) {
+            try {
+                blueBubblesConfig();
+                enabled.add("bluebubbles");
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_notice_bluebubbles_not_attached", message: "BlueBubbles is enabled but not connected on this machine, so owner notices use another channel", meta: { agent, error: error.message } });
+            }
+        }
+        if (senses?.teams?.enabled)
+            enabled.add("teams");
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_notice_channels_unreadable", message: "could not read which channels are enabled, so no owner notice channel is reachable", meta: { agent, error: error.message } });
+    }
+    return enabled;
+}
+/** Every channel id a friend record holds, in the same `channel:handle` form `resolveReachTarget` returns. */
+function personIdentities(friend) {
+    const identities = new Set();
+    // Only called for a reachable friend, whose externalIds is therefore a list.
+    for (const entry of friend.externalIds) {
+        // A `group:` id names a group chat the friend is in, which other people share; it never identifies the person.
+        if (typeof entry?.externalId !== "string" || entry.externalId.trim() === "" || entry.externalId.startsWith("group:"))
+            continue;
+        if (entry.provider === "imessage-handle")
+            identities.add(`bluebubbles:${entry.externalId.toLowerCase()}`);
+        if (entry.provider === "aad")
+            identities.add(`teams:${entry.externalId.toLowerCase()}`);
+    }
+    return identities;
+}
+/**
+ * Who hears the notice, and where: the family friend who is this machine's own user (`local` id), else every family
+ * friend, on the channel `resolveReachTarget` chooses for them, once per
+ * person on that channel even when several friend records share one id. With no 1:1 session yet, the send opens one:
+ * BlueBubbles by the friend's handle, Teams by a new 1:1 conversation.
+ */
+async function resolveNoticeTargets(agentRoot, store = new friends_1.FileFriendStore(path.join(agentRoot, "friends")), enabledChannels = new Set(), username = (0, friends_1.machineOwnerUsername)()) {
+    const seen = new Set();
+    const targets = [];
+    const family = (await store.listAll()).filter(friend => friend.trustLevel === "family");
+    // The notice is the owner's: when family friends are linked to this machine's own user, only they hear it, never
+    // their relatives, even when none of them is reachable yet.
+    const owners = family.filter(friend => (Array.isArray(friend.externalIds) ? friend.externalIds : [])
+        .some(entry => typeof entry?.provider === "string" && typeof entry.externalId === "string" && (0, friends_1.isLocalMachineOwnerIdentity)(entry.provider, entry.externalId, username)));
+    for (const friend of owners.length > 0 ? owners : family) {
+        const reach = (0, reach_channel_1.resolveReachTarget)({
+            friend, enabledChannels, sessionsDir: path.join(agentRoot, "state", "sessions"), friendsDir: path.join(agentRoot, "friends"),
+            agentName: path.basename(agentRoot, ".ouro"),
+        });
+        if ("unreachable" in reach)
+            continue;
+        // One notice per person: a friend whose iMessage handle or Teams id another target already has is that person.
+        const identities = personIdentities(friend);
+        identities.add(`${reach.channel}:${reach.handle}`);
+        if ([...identities].some(identity => seen.has(identity)))
+            continue;
+        for (const identity of identities)
+            seen.add(identity);
+        const alertKey = (0, await_alert_1.resolveAlertKey)(agentRoot, friend.id, reach.channel);
+        // A BlueBubbles fallback key must be a DM: a group key would be refused, and "shepherd" sends to the handle.
+        const fallback = reach.channel === "bluebubbles" ? (alertKey?.includes(";-;") ? alertKey : null) : alertKey;
+        targets.push({ friendId: friend.id, name: friend.name, channel: reach.channel, key: reach.key ?? fallback ?? "shepherd", ...(reach.tenantId ? { tenantId: reach.tenantId } : {}) });
+    }
+    if (owners.length > 0 && targets.length === 0) {
+        (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_notice_owner_unreachable", message: "this machine's owner has no reachable channel, so the Shepherd owner notice waits; link their iMessage handle or Teams id", meta: { owners: owners.length } });
+    }
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_notice_targets", message: "resolved Shepherd owner notice targets", meta: { count: targets.length } });
+    return targets;
+}
+/** One id per batch and person, so a retried batch is saved into the conversation once. */
+function noticeDeliveryId(friendId, noticeIds) {
+    return `shepherd:${(0, node_crypto_1.createHash)("sha256").update(`${friendId}\0${[...noticeIds].sort().join(",")}`).digest("hex")}`;
+}
+/** 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 on the target's channel through that sense's own proactive path, which applies its trust check, internal-content
+ * guard and 1:1 rule, and saves the notice into the friend's conversation.
+ *
+ * - Teams: `sendProactiveTeamsMessageToSession` 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.
+ * - BlueBubbles: `sendProactiveBlueBubblesMessageToSession` over the BlueBubbles REST API, which checks the server's
+ *   account before sending. When the client cannot be set up (no credentials, say), the notice stays pending.
+ */
+function createNoticeSender(agentRoot, deps = {}) {
+    const bots = new Map();
+    return async (target, text, noticeIds) => {
+        const deliveryId = noticeDeliveryId(target.friendId, noticeIds);
+        if (target.channel === "bluebubbles") {
+            let client;
+            let send;
+            try {
+                /* v8 ignore next 2 -- tests inject the client and sender; the live ones need BlueBubbles credentials @preserve */
+                client = deps.createBlueBubblesClient ? deps.createBlueBubblesClient() : (await Promise.resolve().then(() => __importStar(require("../bluebubbles/client")))).createBlueBubblesClient();
+                send = deps.sendBlueBubbles ?? (await Promise.resolve().then(() => __importStar(require("../bluebubbles")))).sendProactiveBlueBubblesMessageToSession;
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.shepherd_notice_bluebubbles_unavailable", message: "BlueBubbles could not be set up for the Shepherd owner notice; it stays waiting", meta: { friendId: target.friendId, error: error.message } });
+                return { delivered: false, reason: "bluebubbles_unavailable" };
+            }
+            const store = new friends_1.FileFriendStore(path.join(agentRoot, "friends"));
+            return send({ friendId: target.friendId, sessionKey: target.key, text, intent: "generic_outreach", deliveryId, origin: "shepherd" }, { createClient: () => client, createFriendStore: () => store });
+        }
+        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, deliveryId, origin: "shepherd" }, { botApi: await bot, store: new friends_1.FileFriendStore(path.join(agentRoot, "friends")) });
+    };
+}
+/** Collects durable notice intents; acceptance is distinct from transport delivery. */
+function createOwnerNotifier(options) {
+    const { agent, policy } = options;
+    const enabledChannels = options.enabledChannels ?? (() => readEnabledReachChannels(agent, options.agentRoot));
+    const resolveTargets = options.resolveTargets ?? (() => resolveNoticeTargets(options.agentRoot, undefined, enabledChannels()));
+    const send = options.send ?? createNoticeSender(options.agentRoot);
+    const retryWrites = new Map();
+    const recoveredNoticeIds = new Set();
+    const writes = new Set();
+    let cancel = null;
+    let stopped = false;
+    let flushing = null;
+    let drainRequested = false;
+    function schedule(ms) {
+        if (!stopped && policy !== "off")
+            cancel ??= options.schedule(() => {
+                cancel?.();
+                cancel = null;
+                if (flushing)
+                    drainRequested = true;
+                else
+                    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(id => {
+            retryWrites.delete(key);
+            return id;
+        }).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);
+            throw error;
+        });
+        writes.add(write);
+        // Observe cleanup immediately, while the producer still receives the rejecting promise.
+        void write.then(() => { writes.delete(write); }, () => { writes.delete(write); });
+        return write;
+    }
+    async function runFlush() {
+        cancel?.();
+        cancel = null;
+        if (stopped || policy === "off")
+            return;
+        try {
+            await Promise.allSettled([...writes]);
+            const retried = await Promise.allSettled([...retryWrites.values()].map(persistIntent));
+            if (retried.some(result => result.status === "rejected"))
+                schedule(exports.NOTICE_RETRY_MS);
+            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 (stopped)
+                return;
+            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 any enabled channel, 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) {
+                if (stopped)
+                    break;
+                const pending = entries.filter(entry => (0, notice_outbox_1.noticeDeliveryState)(entry, target.friendId) === "pending");
+                if (pending.length > 0) {
+                    // Only the worker that atomically claims a pending entry may initiate transport.
+                    const batch = await (0, notice_outbox_1.claimPendingNotices)(options.agentRoot, pending.map(entry => entry.id), target.friendId, new Date().toISOString());
+                    if (batch.length === 0)
+                        continue;
+                    const ids = batch.map(entry => entry.id);
+                    if (stopped) {
+                        await (0, notice_outbox_1.recordNoticeDelivery)(options.agentRoot, ids, target.friendId, { state: "pending", at: new Date().toISOString(), reason: "stopped before transport" });
+                        break;
+                    }
+                    try {
+                        const result = await send(target, noticeMessage(batch.map(entry => entry.record), refs, { recovered: ids.some(id => recoveredNoticeIds.has(id)) }), ids);
+                        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;
+            if (drainRequested) {
+                drainRequested = false;
+                schedule(exports.NOTICE_COALESCE_MS);
+            }
+        });
+        return flushing;
+    }
+    try {
+        const existing = (0, notice_outbox_1.readNoticeOutbox)(options.agentRoot);
+        for (const entry of existing)
+            recoveredNoticeIds.add(entry.id);
+        if (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)
+                return Promise.resolve({ state: "suppressed", reason: "stopped" });
+            if (!noticeWanted(policy, record))
+                return Promise.resolve({ state: "suppressed", reason: "policy" });
+            const write = persistIntent(record);
+            schedule(exports.NOTICE_COALESCE_MS);
+            return write.then(noticeId => ({ state: "queued", noticeId }));
+        },
+        flush,
+        stop() {
+            stopped = true;
+            cancel?.();
+            cancel = null;
+        },
+    };
+}

package/dist/senses/shepherd/prompt-state.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inspectCodingPrompt = inspectCodingPrompt;
+const node_util_1 = require("node:util");
+const runtime_1 = require("../../nerves/runtime");
+/** Rendered-shape allowlist, not a shell/prompt heuristic. Unknown variants never authorize input. */
+function inspectCodingPrompt(agent, screen) {
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.shepherd_prompt_inspected", message: "classified a coding composer" });
+    const unknown = { activity: "unknown", composer: "unknown" };
+    const lines = (0, node_util_1.stripVTControlCharacters)(screen).split("\n").map(line => line.trimEnd());
+    const name = agent.toLowerCase();
+    if (!["copilot", "claude", "claude code", "codex"].includes(name))
+        return unknown;
+    if (/press enter to confirm|esc to cancel|allow this|approve this|❯\s*\d|›\s*\d[.)]/i.test(lines.join("\n")))
+        return unknown;
+    let input;
+    let footer;
+    if (name === "copilot") {
+        const top = lines.findLastIndex(line => /^\s*[╭╻]▄{8,}$/.test(line));
+        const bottom = lines.findIndex((line, i) => i > top && /^\s*╹▀{8,}$/.test(line));
+        if (top < 0 || bottom <= top + 1)
+            return unknown;
+        if (lines[top].length !== lines[bottom].length)
+            return unknown;
+        const body = lines.slice(top + 1, bottom);
+        if (!body.every(line => /^\s*┃/.test(line)))
+            return unknown;
+        input = body.map(line => line.replace(/^\s*┃ ?/, ""));
+        footer = lines.slice(bottom + 1).join("\n");
+        if (!/(?:Interactive|Autopilot).*\/\s*commands|esc interrupt/i.test(footer))
+            return unknown;
+    }
+    else if (name === "claude" || name === "claude code") {
+        const top = lines.findLastIndex(line => /^\s*╭─{8,}╮$/.test(line));
+        const bottom = lines.findIndex((line, i) => i > top && /^\s*╰─{8,}╯$/.test(line));
+        if (top < 0 || bottom <= top + 1)
+            return unknown;
+        if (lines[top].length !== lines[bottom].length)
+            return unknown;
+        const body = lines.slice(top + 1, bottom);
+        if (!/^\s*│ >/.test(body[0]) || !body.every(line => /^\s*│.*│$/.test(line)))
+            return unknown;
+        input = body.map((line, i) => line.replace(/^\s*│ ?/, "").replace(/│$/, "").replace(i === 0 ? /^> ?/ : /^/, ""));
+        footer = lines.slice(bottom + 1).join("\n");
+        if (!/bypass permissions on|shift\+tab to cycle|esc to interrupt/i.test(footer))
+            return unknown;
+    }
+    else {
+        const prompt = lines.findLastIndex(line => /^›(?: |$)/.test(line));
+        const foot = lines.findIndex((line, i) => i > prompt && /\? for shortcuts/.test(line));
+        if (prompt < 0 || foot < 0 || lines.slice(foot + 1).some(line => line.trim()))
+            return unknown;
+        input = [lines[prompt].slice(1), ...lines.slice(prompt + 1, foot)];
+        footer = lines[foot];
+    }
+    if (input.some(line => /\[.*\]|enter a prompt|ask anything|type a message|implement \{/i.test(line)))
+        return unknown;
+    const working = /esc(?: to)? interrupt|\b[1-9]\d* (?:running|background (?:tasks?|agents?|terminals?))\b|background terminal running/i.test(footer);
+    return { activity: working ? "working" : "idle", composer: input.some(line => line.trim().length > 0) ? "draft" : "empty" };
+}