openmausbot 0.1.55

package/dist-server/server/openmaus-status-capsule.js

@@ -0,0 +1,329 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { parseJson } from "./schema.js";
+const SCHEMA = "aos.openmausbot_status.v1";
+const TTL_SECONDS = 300;
+const MAX_CACHE_BYTES = 16_384;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const UTC_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+const digestSchema = z.string().regex(DIGEST);
+const slotSchema = z.object({
+    slot: z.string().regex(/^vm-[1-4]$/),
+    container: z.enum(["running", "stopped", "missing"]),
+    readiness: z.enum(["ready", "not_ready"]),
+    network: z.enum(["loopback", "unsafe", "unknown"]),
+    security: z.enum(["hardened", "unsafe", "unknown"]),
+    persistence: z.enum(["durable", "unsafe", "unknown"]),
+}).strict();
+const uiSchema = z.object({
+    two_up: z.boolean(),
+    max_visible: z.union([z.literal(1), z.literal(2)]),
+    max_interactive: z.literal(1),
+    default_watch_only: z.boolean(),
+}).strict();
+const capsuleSchema = z.object({
+    schema: z.literal(SCHEMA),
+    observed_at: z.string().regex(UTC_TIMESTAMP),
+    fresh_until: z.string().regex(UTC_TIMESTAMP),
+    ttl_seconds: z.literal(TTL_SECONDS),
+    source_sha256: digestSchema.nullable(),
+    dual_view_sha256: digestSchema.nullable(),
+    receipt_sha256: digestSchema,
+    refresh_status: z.enum(["success", "failed"]),
+    failure_reason: z.enum([
+        "config_unavailable",
+        "bots_unavailable",
+        "vm_status_unavailable",
+        "capacity_exceeded",
+        "source_hash_unavailable",
+        "source_hash_mismatch",
+    ]).optional(),
+    runtime_state: z.enum(["ready", "degraded", "unknown"]),
+    mode: z.enum(["shared", "per-bot", "unknown"]),
+    max_instances: z.number().int().min(1).max(4).nullable(),
+    ready_count: z.number().int().min(0).max(4),
+    slots: z.array(slotSchema).max(4),
+    ui: uiSchema,
+}).strict();
+const jsonObjectSchema = z.record(z.string(), z.custom());
+export const OPENMAUS_STATUS_CACHE_PATH = join(homedir(), ".local/state/aos-session-bridge/openmausbot/latest.json");
+function canonicalValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalValue);
+    const parsedObject = jsonObjectSchema.safeParse(value);
+    if (!parsedObject.success)
+        return value;
+    const sorted = {};
+    for (const key of Object.keys(parsedObject.data).sort()) {
+        const child = parsedObject.data[key];
+        if (child !== undefined)
+            sorted[key] = canonicalValue(child);
+    }
+    return sorted;
+}
+function canonical(value) {
+    return JSON.stringify(canonicalValue(value));
+}
+function sha256(value) {
+    return `sha256:${createHash("sha256").update(value, "utf8").digest("hex")}`;
+}
+function timestamp(value) {
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed))
+        return null;
+    if (new Date(parsed).toISOString().replace(".000Z", "Z") !== value)
+        return null;
+    return parsed;
+}
+function expectedUi(twoUp) {
+    return {
+        two_up: twoUp,
+        max_visible: twoUp ? 2 : 1,
+        max_interactive: 1,
+        default_watch_only: twoUp,
+    };
+}
+function sameUi(left, right) {
+    return (left.two_up === right.two_up &&
+        left.max_visible === right.max_visible &&
+        left.max_interactive === right.max_interactive &&
+        left.default_watch_only === right.default_watch_only);
+}
+function unsignedDocument(capsule) {
+    const document = {
+        schema: capsule.schema,
+        observed_at: capsule.observed_at,
+        fresh_until: capsule.fresh_until,
+        ttl_seconds: capsule.ttl_seconds,
+        source_sha256: capsule.source_sha256,
+        dual_view_sha256: capsule.dual_view_sha256,
+        refresh_status: capsule.refresh_status,
+        runtime_state: capsule.runtime_state,
+        mode: capsule.mode,
+        max_instances: capsule.max_instances,
+        ready_count: capsule.ready_count,
+        slots: capsule.slots.map((slot) => ({
+            slot: slot.slot,
+            container: slot.container,
+            readiness: slot.readiness,
+            network: slot.network,
+            security: slot.security,
+            persistence: slot.persistence,
+        })),
+        ui: {
+            two_up: capsule.ui.two_up,
+            max_visible: capsule.ui.max_visible,
+            max_interactive: capsule.ui.max_interactive,
+            default_watch_only: capsule.ui.default_watch_only,
+        },
+    };
+    if (capsule.failure_reason !== undefined)
+        document.failure_reason = capsule.failure_reason;
+    return document;
+}
+function validSlotState(slot) {
+    return (slot.readiness !== "ready" ||
+        (slot.container === "running" &&
+            slot.network === "loopback" &&
+            slot.security === "hardened" &&
+            slot.persistence === "durable"));
+}
+function validateCapsule(value) {
+    const parsed = capsuleSchema.safeParse(value);
+    if (!parsed.success)
+        return null;
+    const capsule = parsed.data;
+    const observed = timestamp(capsule.observed_at);
+    const freshUntil = timestamp(capsule.fresh_until);
+    if (observed === null || freshUntil === null || freshUntil - observed !== TTL_SECONDS * 1000)
+        return null;
+    if (capsule.receipt_sha256 !== sha256(canonical(unsignedDocument(capsule))))
+        return null;
+    if (!capsule.slots.every((slot, index) => slot.slot === `vm-${index + 1}` && validSlotState(slot))) {
+        return null;
+    }
+    const readyCount = capsule.slots.filter((slot) => slot.readiness === "ready").length;
+    if (capsule.ready_count !== readyCount)
+        return null;
+    const twoUp = Boolean(capsule.refresh_status === "success" &&
+        capsule.mode === "per-bot" &&
+        capsule.max_instances !== null &&
+        capsule.max_instances >= 2 &&
+        capsule.source_sha256 !== null &&
+        capsule.dual_view_sha256 !== null &&
+        capsule.source_sha256 === capsule.dual_view_sha256);
+    if (!sameUi(capsule.ui, expectedUi(twoUp)))
+        return null;
+    if (capsule.refresh_status === "failed") {
+        if (capsule.failure_reason === undefined ||
+            capsule.runtime_state !== "unknown" ||
+            capsule.mode !== "unknown" ||
+            capsule.max_instances !== null ||
+            capsule.ready_count !== 0 ||
+            capsule.slots.length !== 0 ||
+            !sameUi(capsule.ui, expectedUi(false)))
+            return null;
+    }
+    else {
+        const expectedRuntime = capsule.slots.length > 0 && readyCount === capsule.slots.length ? "ready" : "degraded";
+        if (capsule.failure_reason !== undefined ||
+            capsule.runtime_state !== expectedRuntime ||
+            (capsule.mode !== "shared" && capsule.mode !== "per-bot") ||
+            capsule.max_instances === null ||
+            readyCount > capsule.max_instances ||
+            capsule.source_sha256 === null ||
+            capsule.dual_view_sha256 === null ||
+            capsule.source_sha256 !== capsule.dual_view_sha256)
+            return null;
+    }
+    return capsule;
+}
+function privateCache(path) {
+    const uid = process.getuid?.();
+    if (uid === undefined)
+        return null;
+    let descriptor = null;
+    try {
+        const parentStatus = lstatSync(dirname(path));
+        const fileStatus = lstatSync(path);
+        if (parentStatus.isSymbolicLink() ||
+            !parentStatus.isDirectory() ||
+            parentStatus.uid !== uid ||
+            (parentStatus.mode & 0o777) !== 0o700)
+            return null;
+        if (fileStatus.isSymbolicLink() ||
+            !fileStatus.isFile() ||
+            fileStatus.uid !== uid ||
+            (fileStatus.mode & 0o777) !== 0o600 ||
+            fileStatus.size > MAX_CACHE_BYTES)
+            return null;
+        descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const openedStatus = fstatSync(descriptor);
+        if (!openedStatus.isFile() ||
+            openedStatus.uid !== uid ||
+            (openedStatus.mode & 0o777) !== 0o600 ||
+            openedStatus.dev !== fileStatus.dev ||
+            openedStatus.ino !== fileStatus.ino ||
+            openedStatus.size > MAX_CACHE_BYTES)
+            return null;
+        const contents = readFileSync(descriptor);
+        return contents.length <= MAX_CACHE_BYTES ? contents : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (descriptor !== null) {
+            try {
+                closeSync(descriptor);
+            }
+            catch {
+                // Cleanup failures must not escape the fail-closed cache read.
+            }
+        }
+    }
+}
+function unknownDigest(reason, freshness = "unknown", receipt) {
+    return {
+        schema: SCHEMA,
+        freshness,
+        reason,
+        ...receipt,
+        runtimeState: "unknown",
+        mode: "unknown",
+        maxInstances: null,
+        readyCount: 0,
+        slots: [],
+        ui: {
+            twoUp: false,
+            maxVisible: 1,
+            maxInteractive: 1,
+            defaultWatchOnly: false,
+            oneActiveController: true,
+        },
+    };
+}
+export function readOpenMausStatus(options = {}) {
+    const raw = privateCache(options.cachePath ?? OPENMAUS_STATUS_CACHE_PATH);
+    if (raw === null)
+        return unknownDigest("missing_or_insecure");
+    let capsule;
+    try {
+        capsule = validateCapsule(parseJson(raw.toString("utf8")));
+    }
+    catch {
+        capsule = null;
+    }
+    if (capsule === null)
+        return unknownDigest("invalid");
+    const observed = timestamp(capsule.observed_at);
+    const freshUntil = timestamp(capsule.fresh_until);
+    const now = (options.now ?? new Date()).getTime();
+    const receipt = { observedAt: capsule.observed_at, receiptSha256: capsule.receipt_sha256 };
+    if (!Number.isFinite(now) || now < observed)
+        return unknownDigest("clock_skew");
+    if (now >= freshUntil)
+        return unknownDigest("stale", "stale", receipt);
+    if (capsule.refresh_status === "failed")
+        return unknownDigest("refresh_failed", "fresh", receipt);
+    const result = {
+        schema: SCHEMA,
+        freshness: "fresh",
+        ...receipt,
+        runtimeState: capsule.runtime_state,
+        mode: capsule.mode,
+        maxInstances: capsule.max_instances,
+        readyCount: capsule.ready_count,
+        slots: capsule.slots,
+        ui: {
+            twoUp: capsule.ui.two_up,
+            maxVisible: capsule.ui.max_visible,
+            maxInteractive: 1,
+            defaultWatchOnly: capsule.ui.default_watch_only,
+            oneActiveController: true,
+        },
+    };
+    if (capsule.source_sha256 !== null)
+        result.sourceSha256 = capsule.source_sha256;
+    if (capsule.dual_view_sha256 !== null)
+        result.dualViewSha256 = capsule.dual_view_sha256;
+    return result;
+}
+export function openMausStatusSystemPrompt(options = {}) {
+    const status = readOpenMausStatus(options);
+    const receipt = [
+        status.observedAt ? `observed_at=${status.observedAt}` : null,
+        status.receiptSha256 ? `receipt_sha256=${status.receiptSha256}` : null,
+        status.sourceSha256 ? `source_sha256=${status.sourceSha256}` : null,
+        status.dualViewSha256 ? `accepted_dual_view_sha256=${status.dualViewSha256}` : null,
+        status.sourceSha256 && status.dualViewSha256
+            ? `source_match=${status.sourceSha256 === status.dualViewSha256}`
+            : null,
+    ].filter(Boolean).join("; ");
+    const runtime = status.freshness === "fresh" && status.reason === undefined
+        ? [
+            `runtime_state=${status.runtimeState}`,
+            `mode=${status.mode}`,
+            `maximum_instances=${status.maxInstances}`,
+            `ready_count=${status.readyCount}`,
+        ].join("; ")
+        : "runtime_state=unknown; mode=unknown; maximum_instances=unknown; ready_count=0";
+    const slots = status.slots.length
+        ? status.slots
+            .map((slot) => `${slot.slot}(container=${slot.container},readiness=${slot.readiness},network=${slot.network},security=${slot.security},persistence=${slot.persistence})`)
+            .join(",")
+        : "none";
+    return [
+        "TRUSTED OPENMAUSBOT STATUS (read-only, validated, no transcript or credential data):",
+        `schema=${status.schema}; freshness=${status.freshness}${status.reason ? `; reason=${status.reason}` : ""}`,
+        receipt || "receipt=unavailable",
+        runtime,
+        `anonymous_slots=${slots}`,
+        `ui.two_up=${status.ui.twoUp}; ui.max_visible=${status.ui.maxVisible}; ui.max_interactive=1; ui.default_watch_only=${status.ui.defaultWatchOnly}; one_active_controller=true`,
+        "Opening a viewer or two-up workspace never starts or provisions a VM. Only one pane may be interactive at a time; switching control must release the previous pane before activating the next.",
+        "Treat missing, stale, failed, clock-skewed, malformed, or receipt-hash-mismatched runtime data as unknown. Do not infer bot identities, viewer URLs, paths, messages, models, accounts, or credentials from this block.",
+    ].join("\n");
+}

package/dist-server/server/openmausbot.js

@@ -0,0 +1,6 @@
+// Entry point for the `openmausbot` command (see cli.ts).
+import { main } from "./cli.js";
+main().then((code) => process.exit(code), (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist-server/server/package-export.js

@@ -0,0 +1,157 @@
+import { parseBotPackage } from "./bot-package.js";
+function portableKey(value, fallback, used) {
+    const stem = value
+        .normalize("NFKD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 48) || fallback;
+    let key = stem;
+    for (let suffix = 2; used.has(key); suffix++)
+        key = `${stem}-${suffix}`;
+    used.add(key);
+    return key;
+}
+function samePlaybook(a, b) {
+    return a.name === b.name && a.summary === b.summary && a.instructions === b.instructions &&
+        a.triggers.join("\n") === b.triggers.join("\n");
+}
+/** Export a workspace definition, never its runtime state. Connected-app
+ * labels are retained as setup intent, but grants, credentials, approvals,
+ * transcripts, memory, paths, engines, and schedules' active state are not. */
+export function createBotPackageExport(input) {
+    const bots = input.bots.filter((bot) => !bot.hidden);
+    if (!bots.length)
+        throw new Error("Create a bot before exporting your package");
+    const packageKeys = new Set();
+    const idToKey = new Map();
+    for (const [index, bot] of bots.entries()) {
+        idToKey.set(bot.id, portableKey(bot.name, `bot-${index + 1}`, packageKeys));
+    }
+    const playbooks = [];
+    const playbookKeys = new Set();
+    const agentPlaybooks = new Map();
+    for (const bot of bots) {
+        const agentKey = idToKey.get(bot.id);
+        const assigned = [];
+        for (const playbook of bot.playbooks ?? []) {
+            const existing = playbooks.find((candidate) => candidate.key === playbook.key);
+            if (existing && samePlaybook(playbook, existing)) {
+                assigned.push(existing.key);
+                continue;
+            }
+            let key = playbook.key;
+            if (existing)
+                key = `${agentKey}-${playbook.key}`;
+            key = portableKey(key, `${agentKey}-playbook`, playbookKeys);
+            if (!playbooks.some((candidate) => candidate.key === key))
+                playbooks.push({ ...playbook, key });
+            assigned.push(key);
+        }
+        agentPlaybooks.set(bot.id, assigned);
+    }
+    const requirements = new Map();
+    for (const bot of bots) {
+        for (const app of bot.installedPackage?.requiredApps ?? []) {
+            if (!requirements.has(app.slug))
+                requirements.set(app.slug, { ...app });
+        }
+    }
+    const roomKeys = new Set();
+    const rooms = [];
+    for (const [index, group] of input.groups.filter((group) => !group.dm).entries()) {
+        const members = group.memberIds.flatMap((id) => idToKey.has(id) ? [idToKey.get(id)] : []);
+        if (!members.length)
+            continue;
+        const defaultResponder = group.defaultResponder.kind === "member" && idToKey.has(group.defaultResponder.botId)
+            ? { kind: "agent", agent: idToKey.get(group.defaultResponder.botId) }
+            : group.defaultResponder.kind === "everyone"
+                ? { kind: "everyone" }
+                : { kind: "mentions" };
+        rooms.push({
+            key: portableKey(group.name, `room-${index + 1}`, roomKeys),
+            name: group.name,
+            members,
+            bulletin: group.bulletin,
+            defaultResponder,
+        });
+    }
+    const routineKeys = new Set();
+    const routines = input.routines.flatMap((routine, index) => {
+        // Package v1 only has a single-agent routine shape. Silently exporting a
+        // room goal as a bot task would change what it does after import, so keep
+        // it out until the portable format can name a package-local room.
+        if (routine.target === "room-goal")
+            return [];
+        const agent = idToKey.get(routine.botId);
+        if (!agent)
+            return [];
+        return [{
+                key: portableKey(routine.name, `routine-${index + 1}`, routineKeys),
+                name: routine.name,
+                agent,
+                prompt: routine.prompt,
+                runOn: routine.runOn,
+                schedule: routine.schedule.type === "once"
+                    ? { type: "once", at: routine.schedule.at }
+                    : routine.schedule.type === "interval"
+                        ? {
+                            type: "interval",
+                            everyMinutes: routine.schedule.everyMinutes,
+                            anchorAt: routine.schedule.anchorAt,
+                        }
+                        : { type: "daily", time: routine.schedule.time, weekdays: [...routine.schedule.weekdays] },
+                durationMinutes: routine.durationMinutes,
+                ...(routine.timeoutMinutes === undefined ? {} : { timeoutMinutes: routine.timeoutMinutes }),
+                enabledAfterInstall: false,
+            }];
+    });
+    const id = portableKey(input.name, "openmaus-package", new Set());
+    const agents = bots.map((bot) => {
+        const appearance = { color: bot.color };
+        if (bot.mascotExpression)
+            appearance.mascotExpression = bot.mascotExpression;
+        if (bot.mascotBody)
+            appearance.mascotBody = bot.mascotBody;
+        const agent = {
+            key: idToKey.get(bot.id),
+            name: bot.name,
+            title: bot.title,
+            description: bot.description,
+            appearance,
+        };
+        const assigned = agentPlaybooks.get(bot.id);
+        if (assigned?.length)
+            agent.playbooks = assigned;
+        return agent;
+    });
+    const definition = {
+        id,
+        release: "1.0.0",
+        name: input.name,
+        tagline: `A portable OpenMausBot setup with ${bots.length} ${bots.length === 1 ? "bot" : "bots"}.`,
+        summary: "Exported from OpenMausBot. Review the roles, rooms, playbooks, connector requirements, and paused routines before sharing or publishing.",
+        category: "Community",
+        author: { name: input.authorName?.trim() || "OpenMausBot user" },
+        license: "Unspecified",
+        outcomes: ["Recreate this bot setup without copying private runtime state."],
+        setupMinutes: Math.min(240, Math.max(2, bots.length + requirements.size * 2)),
+        requirements: { apps: [...requirements.values()], capabilities: [] },
+        agents,
+    };
+    const chief = bots.find((bot) => bot.chiefOfStaff);
+    if (chief)
+        definition.chiefOfStaff = idToKey.get(chief.id);
+    if (rooms.length)
+        definition.rooms = rooms;
+    if (routines.length)
+        definition.routines = routines;
+    if (playbooks.length)
+        definition.playbooks = playbooks;
+    return parseBotPackage({
+        format: "openmaus.package",
+        version: 1,
+        package: definition,
+    });
+}

package/dist-server/server/pair-cli.js

@@ -0,0 +1,7 @@
+// Compatibility alias: `openmausbot pair` lives in cli.ts now. Kept because
+// docs and images reference dist-server/pair-cli.js.
+import { main } from "./cli.js";
+main(["pair", ...process.argv.slice(2)]).then((code) => process.exit(code), (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist-server/server/peer-approval-key.js

@@ -0,0 +1,5 @@
+/** Stable persisted grant for one peer action and one target — a bot for
+ * the two peer actions, the room for post_to_room. */
+export function peerAllowKey(action, targetId) {
+    return `${action}:${targetId}`;
+}

package/dist-server/server/peer-approval.js

@@ -0,0 +1,182 @@
+// Harness-native peer-comm approval gate.
+//
+// A bot with `approvePeerComms = true` may not call ask_bot or
+// delegate_bot without a human approving the specific contact. The
+// approval rides on the same options-card flow provider permissions
+// already use: a card pushed into the SOURCE bot's thread with a
+// `requestId`, answered by the user via /api/bots/:id/respond (or
+// /api/threads/:id/respond) which the harness intercepts via
+// `resolvePeerComms` BEFORE forwarding to the provider adapter. That
+// way nothing front-end has to learn about peer comms.
+//
+// "Always allow" rides on the existing per-bot `alwaysAllow` list. The
+// card carries an ID-based `allowKey` and
+// the user-facing Always-allow flow already mirrors that key back into
+// `alwaysAllow`, so the two sides never disagree about what was granted.
+import { newId } from "./contracts.js";
+import { peerAllowKey } from "./peer-approval-key.js";
+export { peerAllowKey } from "./peer-approval-key.js";
+/** Mark the card answered so the UI stops treating it as pending. Mirrors
+ * what the `request.resolved` fold does for provider cards; a harness-native
+ * card never emits that event, so it has to settle itself. */
+function settleCard(pending, behavior, source) {
+    const existing = pending.bus.store
+        .messagesFor(pending.threadId)
+        .find((m) => m.id === pending.messageId);
+    if (!existing?.card || existing.card.answered)
+        return;
+    pending.bus.store.patchMessage(pending.threadId, pending.messageId, {
+        card: { ...existing.card, answered: behavior, dismissed: source !== "user" },
+    });
+}
+/** requestId → pending ask. Lives only in memory — restarting the
+ * server cancels every in-flight approval, like provider permissions do. */
+const pendingComms = new Map();
+const APPROVAL_TIMEOUT_MS = 15 * 60_000;
+/** The narrow grant "always allow" remembers for a peer comm. Mirrored
+ * back into `bot.alwaysAllow` when the user picks "Always allow" on the
+ * card. */
+function allowKeyAllowed(from, allowKey) {
+    return from.alwaysAllow?.includes(allowKey) ?? false;
+}
+/** How the card names what is about to happen. */
+const ACTION_VERB = {
+    ask_bot: "contact",
+    delegate_bot: "delegate to",
+    post_to_room: "post in",
+};
+function pushApprovalCard(bus, from, target, message, action, requestId, sourceThreadId) {
+    const subtitle = message.length > 200 ? `${message.slice(0, 200)}…` : message;
+    const note = bus.store.appendMessage(sourceThreadId, {
+        role: "bot",
+        kind: "options",
+        card: {
+            // a room is named as a room; only a bot gets an @
+            title: `@${from.name} wants to ${ACTION_VERB[action]} ${action === "post_to_room" ? `“${target.name}”` : `@${target.name}`}`,
+            subtitle,
+            options: ["Allow", "Deny", "Always allow"],
+            requestId,
+            tool: action,
+            allowKey: peerAllowKey(action, target.id),
+        },
+    });
+    return note;
+}
+/** Ask the user (in the source task thread) whether `from` may `action` `target`.
+ * Resolves with `"allow"` or `"deny"`. If `from.alwaysAllow` already
+ * covers the (action, target) pair, returns `"allow"` immediately
+ * without a card. */
+export function requestPeerApproval(bus, from, target, message, action, sourceThreadId = from.threadId) {
+    if (allowKeyAllowed(from, peerAllowKey(action, target.id))) {
+        return Promise.resolve("allow");
+    }
+    return new Promise((resolve) => {
+        const requestId = newId();
+        // the card has to exist before the entry, so a timeout or an answer can
+        // always find it to settle
+        const card = pushApprovalCard(bus, from, target, message, action, requestId, sourceThreadId);
+        const timer = setTimeout(() => {
+            // 15 minutes without an answer → deny. Keeps an unattended bot from
+            // stalling its own turn forever (matches the Claude broker timeout).
+            const pending = pendingComms.get(requestId);
+            if (!pending)
+                return;
+            pendingComms.delete(requestId);
+            settleCard(pending, "deny", "system");
+            resolve("deny");
+        }, APPROVAL_TIMEOUT_MS);
+        timer.unref?.(); // a waiting card must never hold the process open
+        pendingComms.set(requestId, {
+            resolve,
+            timer,
+            fromBotId: from.id,
+            toBotId: target.id,
+            message,
+            threadId: sourceThreadId,
+            messageId: card.id,
+            bus,
+        });
+    });
+}
+/** Called by the respond endpoints BEFORE forwarding to the provider
+ * adapter. Returns true if the requestId belonged to a pending peer
+ * approval (and resolves it); false if it was a provider request and
+ * the endpoint should keep going. */
+export function resolvePeerComms(_bus, requestId, behavior) {
+    const pending = pendingComms.get(requestId);
+    if (!pending)
+        return false;
+    pendingComms.delete(requestId);
+    clearTimeout(pending.timer);
+    const allow = behavior === "allow";
+    settleCard(pending, allow ? "allow" : "deny", "user");
+    pending.resolve(allow ? "allow" : "deny");
+    return true;
+}
+/** Drop every approval waiting on a bot that no longer exists (or is being
+ * deleted), denying it so the caller's turn doesn't wait out the timeout. */
+export function cancelPeerApprovalsFor(botId) {
+    for (const [requestId, pending] of [...pendingComms]) {
+        if (pending.fromBotId !== botId && pending.toBotId !== botId)
+            continue;
+        pendingComms.delete(requestId);
+        clearTimeout(pending.timer);
+        settleCard(pending, "deny", "system");
+        pending.resolve("deny");
+    }
+}
+/** Deny every peer-communication approval owned by a thread whose turn was
+ * interrupted. Patching the card alone is not enough: the in-memory promise
+ * must resolve too, or the delegation queue waits until its 15-minute timer. */
+export function cancelPeerApprovalsForThread(threadId) {
+    for (const [requestId, pending] of pendingComms) {
+        if (pending.threadId !== threadId)
+            continue;
+        pendingComms.delete(requestId);
+        clearTimeout(pending.timer);
+        settleCard(pending, "deny", "system");
+        pending.resolve("deny");
+    }
+}
+/** Every thread a peer card can be raised in. A card lands in the thread
+ * the CALLER is speaking from, and since a bot's turn can now run in a room
+ * — ask_bot and post_to_room are both callable from there — that thread is
+ * as often a room's as a bot's. A walk that knew only about bot threads
+ * would leave a room's composer blocked behind a card nothing can answer. */
+function peerCardThreads(bus) {
+    const threadIds = new Set();
+    for (const bot of bus.store.bots) {
+        threadIds.add(bot.threadId);
+        for (const task of bot.tasks ?? [])
+            threadIds.add(task.threadId);
+    }
+    for (const group of bus.store.groups) {
+        threadIds.add(group.threadId);
+        for (const task of group.tasks ?? [])
+            threadIds.add(task.threadId);
+    }
+    return threadIds;
+}
+/** Cards left on disk by a previous run can never be answered — their
+ * in-memory approval died with the process. Settle them at boot so a
+ * crashed run doesn't leave a thread with a permanently blocked composer. */
+export function dismissStalePeerCards(bus) {
+    let dismissed = 0;
+    for (const threadId of peerCardThreads(bus)) {
+        for (const message of bus.store.messagesFor(threadId)) {
+            const card = message.card;
+            if (!card?.requestId || card.answered || card.dismissed)
+                continue;
+            if (card.tool !== "ask_bot" && card.tool !== "delegate_bot" && card.tool !== "post_to_room")
+                continue;
+            if (pendingComms.has(card.requestId))
+                continue;
+            const patched = bus.store.patchMessage(threadId, message.id, {
+                card: { ...card, answered: "deny", dismissed: true },
+            });
+            if (patched)
+                dismissed += 1;
+        }
+    }
+    return dismissed;
+}