openmausbot 0.1.86 → 0.1.87

package/dist-server/server/package-import.js

@@ -0,0 +1,458 @@
+// Adding a shared team to this installation.
+//
+// Import is additive-only. A package is untrusted input (a file someone
+// sent, GitHub, the community catalog), so it is structurally unable to reach
+// records the person already has: every bot, group chat, routine, section and
+// connection it creates is NEW, and every privilege-bearing field is chosen
+// here, never read from the file. What the file may set is persona and
+// structure: names, standing instructions, looks, playbooks, skills (which
+// land switched off), group chats, routines (which land paused), the team
+// brief and Chief, starter notes, and connection SLOTS (an address and the
+// names of values the person fills in later; never the values).
+//
+// `trust` is a function argument, never read from a request. The HTTP import
+// route always passes "file". Only the organization library (wave 2, a
+// separate module) passes "org": its skills arrive switched on because the
+// organization's Admin published them, and its records carry the provenance
+// the organization channel needs. Everything else is identical.
+//
+// A failure anywhere rolls back every record this import created.
+import { createHash, randomUUID } from "node:crypto";
+import { mcpServerNameError, MAX_MCP_SERVERS, parseStoredMcpServer } from "./mcp-registry.js";
+import { AGENT_PARTS, agentReleaseValues, connectionLocalValue, connectionReleaseValue, pair, pairs, playbookValues, ROOM_PARTS, roomReleaseValues, ROUTINE_PARTS, routineReleaseValues, scheduleValue, sha256Hex, TEAM_PARTS, } from "./package-parts.js";
+import { importedMemberProfile } from "./team-manifest.js";
+import { takeImportName } from "../shared/import-name.js";
+import { decodeBase64 } from "../shared/package-format.js";
+export const NO_BOTS_MESSAGE = "This package has no bots. Add it from your organization's shelf, or update OpenMausBot.";
+/** A file with skills only: a file never adds a skill without a bot or a preset to hold it. */
+export const NO_PRESETS_MESSAGE = "This file has no bots or preset bots to add. Its skills can be added from your organization's shelf.";
+/** A refusal before anything was created, as a plain sentence. */
+export class PackageImportError extends Error {
+    status = 400;
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "PackageImportError";
+        this.code = code;
+    }
+}
+/** Deterministic, so reconnecting to the same organization recognizes what
+ * it already added. `packageId` is Admin's package UUID. */
+export function orgInstallId(adminOrigin, organizationId, packageId) {
+    return createHash("sha256").update(`omb-install:v1\n${adminOrigin}\n${organizationId}\n${packageId}`, "utf8").digest("hex").slice(0, 32);
+}
+function memberFromAgent(agent) {
+    return {
+        key: agent.key,
+        name: agent.name,
+        title: agent.title ?? "",
+        description: agent.description ?? "",
+        ...(agent.soul !== undefined ? { soul: agent.soul } : {}),
+        appearance: {
+            color: agent.appearance.color,
+            ...(agent.appearance.mascotExpression ? { mascotExpression: agent.appearance.mascotExpression } : {}),
+            ...(agent.appearance.mascotBody ? { mascotBody: agent.appearance.mascotBody } : {}),
+        },
+    };
+}
+/** The first free server name for a slot: key, key-2, … (never an existing
+ * or reserved name, so a slot can never bind to credentials already here). */
+function freeServerName(key, taken) {
+    for (let n = 1; n < 100; n += 1) {
+        const name = n === 1 ? key : `${key}-${n}`;
+        if (name.length > 32)
+            return null;
+        if (mcpServerNameError(name) || Object.hasOwn(taken, name))
+            continue;
+        return name;
+    }
+    return null;
+}
+/** Add a shared team (v1 or v2, already parsed) as new records. */
+export function importPackageDocument(document, options, deps) {
+    const pkg = document.package;
+    const library = !pkg.agents.length || !pkg.team;
+    // A library package (skills and presets, no bots) from a file needs the preset store.
+    if (library && options.trust !== "org" && !deps.presets)
+        throw new PackageImportError("no_bots", NO_BOTS_MESSAGE);
+    if (options.trust === "org") {
+        const org = options.org;
+        if (!org)
+            throw new PackageImportError("invalid_package", "This package is missing its organization details.");
+        if (org.installId !== orgInstallId(org.adminOrigin, org.organizationId, org.packageId)) {
+            throw new PackageImportError("invalid_package", "This package's install id does not match its organization.");
+        }
+        if (pkg.publisher?.organization !== org.publisher.slug) {
+            throw new PackageImportError("invalid_package", "This package was not published by the organization that shared it.");
+        }
+        if (org.ref !== `${org.publisher.slug}/${pkg.id}`) {
+            throw new PackageImportError("invalid_package", "This package is not the one your organization listed.");
+        }
+        if (!deps.skills.installOrg || !deps.routines.stampInstalledPackage) {
+            throw new PackageImportError("invalid_package", "This installation cannot add packages from an organization.");
+        }
+        // A bot someone made from one of the install's presets carries its
+        // install id too, but it is theirs, not one of the package's records;
+        // preset rows are not records either. Re-adding a removed team, or
+        // retrying after a crash, re-registers its presets in place (presets.ts).
+        if (deps.store.bots.some((bot) => bot.installedPackage?.installId === org.installId && !bot.installedPackage.presetKey) ||
+            deps.store.groups.some((group) => group.installedPackage?.installId === org.installId)) {
+            return { alreadyAdded: true, installId: org.installId };
+        }
+        // A library package (skills and presets, no team) creates no bots:
+        // its skills are offered under Bot → Skills, its presets go to New bot,
+        // and the organization library keeps the index of what it offers.
+        if (library) {
+            const registered = deps.presets?.register(document, { source: "org", installId: org.installId, org });
+            return {
+                alreadyAdded: false, installId: org.installId, name: pkg.name, section: "", bots: [], groups: [], routines: [],
+                offeredSkills: (pkg.skills?.entries ?? []).map((skill) => skill.name), connections: [],
+                skipped: registered?.skipped ?? (pkg.presets ?? []).map((preset) => ({ part: `presets[${preset.key}]`, reason: "presets_not_supported_yet" })),
+                brief: false, notes: 0,
+                ...(registered ? { presets: [...registered.added, ...registered.existing] } : {}),
+                org: { kind: "library", section: "", team: { parts: {} }, bots: {}, rooms: {}, routines: {}, connections: {} },
+            };
+        }
+    }
+    if (library)
+        return importLibraryFile(document, deps.presets);
+    return runImport({ kind: "package", document }, options, deps);
+}
+/** A preset file (skills and presets, no team): the presets go to New bot,
+ * and the skills are offered (a file never installs a skill without a bot or
+ * a preset to hold it). */
+function importLibraryFile(document, presets) {
+    const pkg = document.package;
+    if (!pkg.presets?.length)
+        throw new PackageImportError("no_bots", NO_PRESETS_MESSAGE);
+    const installId = randomUUID();
+    const registered = presets.register(document, { source: "file", installId });
+    return {
+        alreadyAdded: false, installId, name: pkg.name, section: "", bots: [], groups: [], routines: [],
+        offeredSkills: (pkg.skills?.entries ?? []).map((skill) => skill.name), connections: [],
+        skipped: registered.skipped, brief: false, notes: 0, presets: [...registered.added, ...registered.existing],
+    };
+}
+/** Add a legacy `openmaus.team` file: people only (plus a project room when
+ * the caller asks for one). */
+export function importTeamManifest(manifest, options, deps) {
+    return runImport({ kind: "manifest", manifest }, { ...options, trust: "file" }, deps);
+}
+function runImport(source, options, deps) {
+    const { store } = deps;
+    const pkg = source.kind === "package" ? source.document.package : null;
+    const name = pkg?.name ?? (source.kind === "manifest" ? source.manifest.team.name : "");
+    const teamName = pkg?.team?.name ?? name;
+    const org = options.trust === "org" ? options.org : undefined;
+    const installId = pkg ? org?.installId ?? randomUUID() : undefined;
+    const members = pkg
+        ? pkg.agents.map((agent) => ({ member: memberFromAgent(agent), agent }))
+        : source.manifest.team.members.map((member) => ({ member, agent: undefined }));
+    const importedBots = [];
+    const createdGroups = [];
+    const createdRoutines = [];
+    const createdServers = [];
+    const createdPresets = [];
+    const skipped = [];
+    const orgIndex = { kind: "team", section: "", team: { parts: {} }, bots: {}, rooms: {}, routines: {}, connections: {} };
+    // Names already in use, hidden bots included: an archived bot can be
+    // un-archived later, and a revived duplicate would be just as ambiguous.
+    const takenNames = new Set(store.bots.map((bot) => bot.name.trim().toLowerCase()));
+    const botIds = new Map();
+    let group;
+    let section;
+    let notes = 0;
+    try {
+        const selection = deps.defaultSelection();
+        const existingSections = new Set([...store.sections, ...store.bots.map((bot) => bot.section), ...store.groups.map((candidate) => candidate.section)]
+            .filter((value) => Boolean(value?.trim()))
+            .map((value) => value.trim().toLowerCase()));
+        // Every template gets its own new section, numbered on collision. Never
+        // merge into an existing section (or replace its Chief).
+        section = takeImportName(teamName, existingSections, 60);
+        // Connection slots first, so bots can be bound to exactly these servers.
+        const serverForKey = new Map();
+        const connections = [];
+        if (pkg?.connections?.length) {
+            const next = { ...deps.mcp.servers() };
+            for (const connection of pkg.connections) {
+                const part = `connections[${connection.key}]`;
+                if (Object.keys(next).length >= MAX_MCP_SERVERS) {
+                    skipped.push({ part, reason: "too_many_connections" });
+                    continue;
+                }
+                const serverName = freeServerName(connection.key, next);
+                const server = {
+                    type: connection.mcp.transport,
+                    url: connection.mcp.url,
+                    ...(connection.mcp.valueNames.length ? { headers: Object.fromEntries(connection.mcp.valueNames.map((header) => [header, ""])) } : {}),
+                    // Off until the person fills in the values and switches it on.
+                    enabled: false,
+                };
+                if (!serverName || !parseStoredMcpServer(serverName, server).ok) {
+                    skipped.push({ part, reason: "connection_invalid" });
+                    continue;
+                }
+                if (deps.mcp.refusal(serverName, server)) {
+                    skipped.push({ part, reason: "connection_refused_by_policy" });
+                    continue;
+                }
+                next[serverName] = server;
+                createdServers.push(serverName);
+                serverForKey.set(connection.key, serverName);
+                connections.push({ key: connection.key, name: serverName, label: connection.label });
+                if (org) {
+                    orgIndex.connections[connection.key] = { name: serverName, ...pair(connectionReleaseValue(connection), connectionLocalValue(server)) };
+                }
+            }
+            if (createdServers.length)
+                deps.mcp.persist(next);
+        }
+        const playbookByKey = new Map((pkg?.playbooks ?? []).map((playbook) => [playbook.key, playbook]));
+        const skillByName = new Map((pkg?.skills?.entries ?? []).map((skill) => [skill.name, skill]));
+        for (const { member, agent } of members) {
+            // importedMemberProfile is the authority boundary: persona fields
+            // only, colliding names numbered. seedMessages: false — an imported
+            // bot must not open by greeting the user as though it were new.
+            const created = store.createBot({
+                ...importedMemberProfile(member, takenNames),
+                modelSelection: selection,
+                section,
+                ...(options.visibility ? { visibility: options.visibility } : {}),
+            }, { seedMessages: false });
+            importedBots.push(created);
+            botIds.set(member.key, created.id);
+            const playbooks = (agent?.playbooks ?? []).flatMap((key) => {
+                const playbook = playbookByKey.get(key);
+                return playbook ? [{ ...playbook }] : [];
+            });
+            let avatar = {};
+            let avatarHash = null;
+            if (agent?.appearance.avatar) {
+                const bytes = decodeBase64(agent.appearance.avatar.data);
+                if (!bytes)
+                    throw new Error(`The picture for ${member.name} could not be read`);
+                avatar = { avatarUrl: deps.images.save(bytes, agent.appearance.avatar.mime), avatarCrop: agent.appearance.avatar.crop };
+                avatarHash = sha256Hex(bytes);
+            }
+            const installed = pkg
+                ? {
+                    id: pkg.id,
+                    name: pkg.name,
+                    release: pkg.release,
+                    requiredApps: pkg.requirements.apps.map((app) => ({ ...app })),
+                    source: org ? "org" : "file",
+                    installId,
+                    agentKey: member.key,
+                    ...(agent?.approval ? { suggestedApproval: agent.approval } : {}),
+                    ...(org ? { publisher: { ...org.publisher }, ref: org.ref, sha256: org.sha256 } : {}),
+                }
+                : undefined;
+            // composio: false — a shared persona never starts with reach into the
+            // person's connected apps (absence would mean allowed). Approval is
+            // never set: every imported bot starts on Ask, whatever was suggested.
+            store.patchBot(created.id, {
+                composio: false,
+                connectorTools: {},
+                ...(playbooks.length ? { playbooks } : {}),
+                ...(installed ? { installedPackage: installed } : {}),
+                ...(agent?.connections ? { mcpServers: agent.connections.flatMap((key) => serverForKey.has(key) ? [serverForKey.get(key)] : []) } : {}),
+                ...avatar,
+            });
+            for (const skillName of agent?.skills ?? []) {
+                const skill = skillByName.get(skillName);
+                if (!skill)
+                    throw new Error(`Package skill "${skillName}" is unavailable`);
+                // A file's `source` is display provenance only; the organization
+                // channel names its own source so ownership can never be forged.
+                // Organization skills arrive switched on, stamped with their install.
+                const added = org
+                    ? deps.skills.installOrg(created.id, `org:${org.ref}@${pkg.release}`, skill.instructions, { installId: org.installId, key: skill.name, release: pkg.release, ...pair(skill.instructions, skill.instructions) })
+                    : deps.skills.install(created.id, skill.source ?? `package:${pkg.id}`, [{ path: "SKILL.md", content: skill.instructions }]);
+                if ("error" in added)
+                    throw new Error(`Package skill "${skillName}" could not be imported: ${added.error}`);
+            }
+            // Starter notes are copied once, on this first add.
+            for (const [path, text] of Object.entries(agent?.seed?.memory ?? {})) {
+                if (path === "MEMORY.md")
+                    deps.memory.writeIndex(created.id, text);
+                else
+                    deps.memory.writeTopic(created.id, path.slice("memory/".length), text);
+                notes += 1;
+            }
+            // An organization bot's part hashes are its last write, so a bot that
+            // has them is complete (org-library.ts reads that after a crash).
+            if (org && agent) {
+                const written = store.bot(created.id);
+                const local = {
+                    name: written.name,
+                    title: written.title ?? "",
+                    description: written.description ?? "",
+                    soul: written.soul ?? "",
+                    look: {
+                        color: written.color,
+                        mascotExpression: written.mascotExpression ?? null,
+                        mascotBody: written.mascotBody ?? null,
+                        avatar: avatarHash,
+                        crop: written.avatarCrop ?? null,
+                    },
+                    playbooks: playbookValues(written.playbooks ?? []),
+                    skills: [...(agent.skills ?? [])].sort(),
+                    connections: [...(written.mcpServers ?? [])].sort(),
+                    approval: "ask",
+                };
+                store.patchBot(created.id, { packageBase: pairs(AGENT_PARTS, agentReleaseValues(agent, playbookByKey), local) });
+                orgIndex.bots[member.key] = created.id;
+            }
+        }
+        // The brief goes before the group chats and routines, and the leader is
+        // set last, so an organization Add the app stopped partway through can
+        // tell a finished team from a partial one (org-library.ts).
+        const brief = Boolean(pkg?.team?.brief?.trim());
+        if (brief)
+            deps.sections.writeBrief(section, pkg.team.brief);
+        // A package is an explicit structure import: its rooms are created from
+        // package-local keys only, then normalized to the fresh bot ids.
+        const groupIds = new Map();
+        for (const room of pkg?.rooms ?? []) {
+            const ids = room.members.map((key) => botIds.get(key));
+            let created = store.createGroup(room.name, ids, false, section);
+            createdGroups.push(created);
+            const defaultResponder = room.defaultResponder.kind === "agent"
+                ? { kind: "member", botId: botIds.get(room.defaultResponder.agent) }
+                : { kind: room.defaultResponder.kind };
+            created = store.patchGroup(created.id, {
+                bulletin: room.bulletin ?? "",
+                defaultResponder,
+                setupCompletedAt: Date.now(),
+            }) ?? created;
+            groupIds.set(room.key, created.id);
+            if (org) {
+                const local = {
+                    name: created.name,
+                    bulletin: created.bulletin ?? "",
+                    members: [...created.memberIds].sort(),
+                    defaultResponder: created.defaultResponder,
+                };
+                created = store.patchGroup(created.id, {
+                    installedPackage: { installId: org.installId, key: room.key, memberKeys: [...room.members].sort(), parts: pairs(ROOM_PARTS, roomReleaseValues(room), local) },
+                }) ?? created;
+                orgIndex.rooms[room.key] = created.id;
+            }
+        }
+        for (const routine of pkg?.routines ?? []) {
+            // Routines always arrive paused from a file. The organization channel
+            // also pauses them for now; honouring enabledAfterInstall there is a
+            // later, Admin-side decision.
+            let timeoutMinutes = routine.timeoutMinutes;
+            if (timeoutMinutes !== undefined && (timeoutMinutes < 5 || timeoutMinutes > 240)) {
+                timeoutMinutes = Math.min(240, Math.max(5, timeoutMinutes));
+                skipped.push({ part: `routines[${routine.key}].timeoutMinutes`, reason: "run_limit_adjusted" });
+            }
+            const input = {
+                name: routine.name,
+                prompt: routine.prompt,
+                botId: botIds.get(routine.agent),
+                ...(routine.room !== undefined ? { target: "room-goal", groupId: groupIds.get(routine.room) } : {}),
+                runOn: routine.runOn,
+                enabled: false,
+                schedule: routine.schedule,
+                durationMinutes: routine.durationMinutes,
+                ...(timeoutMinutes === undefined ? {} : { timeoutMinutes }),
+                ...(routine.overlap ? { overlap: routine.overlap } : {}),
+                ...(routine.continuity && routine.room === undefined ? { continuity: true } : {}),
+            };
+            const created = deps.routines.create(input);
+            createdRoutines.push(created);
+            if (org) {
+                const local = {
+                    name: created.name,
+                    prompt: created.prompt,
+                    schedule: scheduleValue(created),
+                    target: { botId: created.botId, groupId: created.groupId ?? null },
+                };
+                deps.routines.stampInstalledPackage(created.id, { installId: org.installId, key: routine.key, parts: pairs(ROUTINE_PARTS, routineReleaseValues(routine), local) });
+                orgIndex.routines[routine.key] = created.id;
+            }
+        }
+        if (pkg?.team?.leader)
+            store.setChiefOfStaff(botIds.get(pkg.team.leader));
+        if (org && pkg?.team) {
+            orgIndex.section = section;
+            orgIndex.team.parts = pairs(TEAM_PARTS, {
+                name: pkg.team.name, brief: pkg.team.brief ?? "", leader: pkg.team.leader ?? null,
+            }, {
+                name: section, brief: brief ? pkg.team.brief : "", leader: pkg.team.leader ? botIds.get(pkg.team.leader) : null,
+            });
+        }
+        let presets;
+        // An organization install always registers, so a release re-added without
+        // presets also drops the rows an earlier one left (presets.ts).
+        if (source.kind === "package" && deps.presets && (pkg?.presets?.length || org)) {
+            const registered = deps.presets.register(source.document, { source: org ? "org" : "file", installId: installId, ...(org ? { org } : {}) });
+            createdPresets.push(...registered.added.map((preset) => preset.id));
+            skipped.push(...registered.skipped);
+            presets = [...registered.added, ...registered.existing];
+        }
+        else
+            for (const preset of pkg?.presets ?? [])
+                skipped.push({ part: `presets[${preset.key}]`, reason: "presets_not_supported_yet" });
+        // The legacy project room is created last, so a failure anywhere above
+        // leaves no half-built project behind.
+        if (!pkg && options.mode === "project" && importedBots.length > 0) {
+            const roomName = options.room?.trim() || name;
+            group = store.createGroup(roomName, importedBots.map((bot) => bot.id), false, section);
+            createdGroups.push(group);
+            if (options.cwd) {
+                // `cwd` is the folder the room WANTS; the store pins it on the
+                // first turn (pinGroupCwd).
+                group = store.patchGroup(group.id, { cwd: options.cwd }) ?? group;
+            }
+        }
+        const referenced = new Set((pkg?.agents ?? []).flatMap((agent) => agent.skills ?? []));
+        const bots = importedBots.map((bot) => store.bot(bot.id));
+        for (const bot of bots)
+            deps.broadcast?.({ kind: "bot", bot });
+        if (group)
+            deps.broadcast?.({ kind: "group", group });
+        return {
+            alreadyAdded: false,
+            ...(installId ? { installId } : {}),
+            ...(org ? { org: orgIndex } : {}),
+            name,
+            section,
+            bots,
+            groups: createdGroups.map((created) => store.group(created.id) ?? created),
+            ...(group ? { group } : {}),
+            routines: createdRoutines,
+            offeredSkills: (pkg?.skills?.entries ?? []).filter((skill) => !referenced.has(skill.name)).map((skill) => skill.name),
+            connections,
+            skipped,
+            brief,
+            notes,
+            ...(presets ? { presets } : {}),
+        };
+    }
+    catch (error) {
+        // A room of deleted members must not survive either — patchGroup can
+        // throw (disk) after createGroup already saved.
+        for (const routine of createdRoutines)
+            deps.routines.remove(routine.id);
+        for (const created of createdGroups)
+            store.deleteGroup(created.id);
+        for (const bot of importedBots)
+            store.deleteBot(bot.id);
+        deps.presets?.remove(createdPresets);
+        if (createdServers.length) {
+            const next = { ...deps.mcp.servers() };
+            for (const serverName of createdServers)
+                delete next[serverName];
+            deps.mcp.persist(next);
+        }
+        // This import allocated a fresh section (and maybe its brief); a failed
+        // installation retires that identity again.
+        if (section && store.sections.includes(section))
+            store.changeEmptySection(section, null);
+        throw error;
+    }
+}

package/dist-server/server/package-parts.js

@@ -0,0 +1,87 @@
+// Part hashes for records added from an organization's library (contract
+// §1.6). Every part of an added team keeps two hashes: `r`, the value the
+// release shipped, and `w`, the value OpenMausBot wrote at install. The
+// automatic updater compares them later: `hash(local) ≠ w` means the person
+// edited the part, `r(new release) ≠ r` means the publisher changed it. Only
+// the hashes are kept, never a second copy of the content.
+//
+// The value shapes are frozen: a stamp written today must still compare
+// correctly in a later version, so change nothing here without a new stamp
+// version.
+import { createHash } from "node:crypto";
+import { canonicalJson, decodeBase64 } from "../shared/package-format.js";
+export const AGENT_PARTS = ["name", "title", "description", "soul", "look", "playbooks", "skills", "connections", "approval"];
+export const ROOM_PARTS = ["name", "bulletin", "members", "defaultResponder"];
+export const ROUTINE_PARTS = ["name", "prompt", "schedule", "target"];
+export const TEAM_PARTS = ["name", "brief", "leader"];
+export const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** sha256hex(utf8(canonicalJson(value ?? null))) */
+export function partHash(value) {
+    return sha256Hex(canonicalJson(value ?? null));
+}
+export const pair = (release, written) => ({ r: partHash(release), w: partHash(written) });
+export function releaseLook(appearance) {
+    const bytes = appearance.avatar ? decodeBase64(appearance.avatar.data) : null;
+    return {
+        color: appearance.color,
+        mascotExpression: appearance.mascotExpression ?? null,
+        mascotBody: appearance.mascotBody ?? null,
+        avatar: bytes ? sha256Hex(bytes) : null,
+        crop: appearance.avatar?.crop ?? null,
+    };
+}
+export function playbookValues(playbooks) {
+    return playbooks.map(({ key, name, summary, triggers, instructions }) => ({ key, name, summary, triggers: [...triggers], instructions }));
+}
+/** The release side of every bot part. */
+export function agentReleaseValues(agent, playbooks) {
+    return {
+        name: agent.name,
+        title: agent.title ?? "",
+        description: agent.description ?? "",
+        soul: agent.soul ?? "",
+        look: releaseLook(agent.appearance),
+        playbooks: playbookValues((agent.playbooks ?? []).flatMap((key) => (playbooks.has(key) ? [playbooks.get(key)] : []))),
+        skills: [...(agent.skills ?? [])].sort(),
+        connections: [...(agent.connections ?? [])].sort(),
+        approval: agent.approval ?? null,
+    };
+}
+export const roomReleaseValues = (room) => ({
+    name: room.name,
+    bulletin: room.bulletin ?? "",
+    members: [...room.members].sort(),
+    defaultResponder: room.defaultResponder.kind === "agent"
+        ? { kind: "agent", agent: room.defaultResponder.agent }
+        : { kind: room.defaultResponder.kind },
+});
+/** One normal form for a routine's timing on both sides, so an untouched
+ * routine compares equal: absent cap → null, absent overlap → "skip". */
+export function scheduleValue(routine) {
+    return {
+        runOn: routine.runOn,
+        schedule: routine.schedule,
+        durationMinutes: routine.durationMinutes,
+        timeoutMinutes: routine.timeoutMinutes ?? null,
+        overlap: routine.overlap ?? "skip",
+        continuity: routine.continuity === true,
+    };
+}
+export const routineReleaseValues = (routine) => ({
+    name: routine.name,
+    prompt: routine.prompt,
+    schedule: scheduleValue(routine),
+    target: { agent: routine.agent, room: routine.room ?? null },
+});
+export const connectionReleaseValue = (connection) => ({
+    transport: connection.mcp.transport,
+    url: connection.mcp.url,
+    valueNames: [...connection.mcp.valueNames],
+});
+export function connectionLocalValue(server) {
+    const headers = server.headers && typeof server.headers === "object" ? Object.keys(server.headers) : [];
+    return { transport: server.type ?? null, url: server.url ?? null, valueNames: headers.sort() };
+}
+export function pairs(keys, release, written) {
+    return Object.fromEntries(keys.map((key) => [key, pair(release[key], written[key])]));
+}

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

@@ -17,6 +17,15 @@ import { newId } from "./contracts.js";
 import { buildNotification } from "./notify.js";
 import { peerAllowKey } from "./peer-approval-key.js";
 export { peerAllowKey } from "./peer-approval-key.js";
+export function peerApprovalFailure(outcome) {
+    return {
+        error: outcome === "deny" ? "denied by user"
+            : outcome === "expired" ? "the approval card expired without an answer"
+                : "the approval was cancelled before a decision",
+        approvalOutcome: outcome,
+        approvalSource: outcome === "deny" ? "user" : "system",
+    };
+}
 /** 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. */
@@ -102,7 +111,7 @@ function announceCard(bus, from, card, sourceThreadId) {
     bus.notify?.(buildNotification("approval", from, sourceThreadId, detail, { avatarUrl: from.avatarUrl, group }));
 }
 /** Ask the user (in the source task thread) whether `from` may `action` `target`.
- * Resolves with `"allow"` or `"deny"`. If `from.alwaysAllow` already
+ * Distinguishes user denial from expiry and cancellation. 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) {
@@ -116,14 +125,14 @@ export function requestPeerApproval(bus, from, target, message, action, sourceTh
         const card = pushApprovalCard(bus, from, target, message, action, requestId, sourceThreadId);
         announceCard(bus, from, card, sourceThreadId);
         const timer = setTimeout(() => {
-            // 15 minutes without an answer → deny. Keeps an unattended bot from
+            // 15 minutes without an answer → expired. 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");
+            resolve("expired");
         }, APPROVAL_TIMEOUT_MS);
         timer.unref?.(); // a waiting card must never hold the process open
         pendingComms.set(requestId, {
@@ -154,7 +163,7 @@ export function resolvePeerComms(_bus, requestId, behavior) {
     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. */
+ * deleted), cancelling it so the caller's turn doesn't wait out the timeout. */
 export function cancelPeerApprovalsFor(botId) {
     for (const [requestId, pending] of Array.from(pendingComms)) {
         if (pending.fromBotId !== botId && pending.toBotId !== botId)
@@ -162,10 +171,10 @@ export function cancelPeerApprovalsFor(botId) {
         pendingComms.delete(requestId);
         clearTimeout(pending.timer);
         settleCard(pending, "deny", "system");
-        pending.resolve("deny");
+        pending.resolve("cancelled");
     }
 }
-/** Deny every peer-communication approval owned by a thread whose turn was
+/** Cancel 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) {
@@ -175,7 +184,7 @@ export function cancelPeerApprovalsForThread(threadId) {
         pendingComms.delete(requestId);
         clearTimeout(pending.timer);
         settleCard(pending, "deny", "system");
-        pending.resolve("deny");
+        pending.resolve("cancelled");
     }
 }
 /** Every thread a peer card can be raised in. A card lands in the thread

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

@@ -14,6 +14,16 @@ export function canAccessTeam(from, section) {
     return target === sectionKey(from.section) || Boolean(from.chiefOfStaff &&
         Array.isArray(from.managedSections) && from.managedSections.some(value => typeof value === "string" && sectionKey(value) === target));
 }
+/** Returns whether `coordinator` is an authorized Chief of Staff supervising `bot`'s section. */
+export function coordinatorSupervises(coordinator, bot) {
+    if (!coordinator?.chiefOfStaff || !bot)
+        return false;
+    const target = sectionKey(bot.section);
+    if (!target)
+        return false;
+    return Boolean(Array.isArray(coordinator.managedSections) &&
+        coordinator.managedSections.some((value) => typeof value === "string" && sectionKey(value) === target));
+}
 const PEER_STATUS_WORDS = {
     available: "available",
     working: "working right now",