openmausbot 0.1.55

package/dist-server/server/surface.js

@@ -0,0 +1,107 @@
+// Where a bot's hands land — and therefore where the person goes when it
+// needs them. A turn can mount two places at once (a computer plus the
+// built-in browser), which is exactly what confused people: "do this on the
+// web" landed in the cloud box's Chrome one turn and in the Browser tab the
+// next, and the "needs your hands" plea never said which. Everything that
+// decides or describes a surface lives here, so the picker, the dispatch,
+// the system prompt and the notification cannot drift apart.
+const SURFACES = new Set(["cloud", "vm", "local", "browser"]);
+/** Parse a surface arriving over the wire; anything else is "not said". */
+export function parseSurface(value) {
+    // SAFETY: the set membership check is the narrowing — only the four
+    // literal strings pass, and the assertion just names that fact to the type.
+    return typeof value === "string" && SURFACES.has(value) ? value : undefined;
+}
+/** The per-turn computer kinds the dispatch tracks, folded to a surface. */
+export function surfaceOfComputerKind(kind) {
+    if (kind === "box" || kind === "vps")
+        return "cloud";
+    return kind;
+}
+const NO_BROWSER_NOTE = " This bot is set to work in the built-in browser, but the built-in browser is switched off in App Settings, so you have no browser and no computer this turn — say so instead of guessing.";
+/** Decide what a turn mounts from the bot's destination, the task's pin
+ * and what is actually reachable. Explicit choices are strict: a computer
+ * destination keeps whatever browser the bot has (the prompt tells the
+ * model which to use), a browser destination mounts only the browser. Auto
+ * follows the task's pin while the pinned place still exists, and otherwise
+ * re-resolves the way it always has. */
+export function resolveSurface(input) {
+    const { destination, browserOn } = input;
+    if (destination === "browser") {
+        return browserOn
+            ? { computer: "off", browser: true, pinned: null, clearPin: false, note: "" }
+            : { computer: "off", browser: false, pinned: null, clearPin: false, note: NO_BROWSER_NOTE };
+    }
+    if (destination !== undefined) {
+        return { computer: destination, browser: browserOn, pinned: null, clearPin: false, note: "" };
+    }
+    const pin = input.pinnedSurface ?? null;
+    if (pin === null) {
+        return { computer: undefined, browser: browserOn, pinned: null, clearPin: false, note: "" };
+    }
+    const reachable = pin === "browser" ? browserOn : input.available?.[pin] === true;
+    if (!reachable) {
+        return { computer: undefined, browser: browserOn, pinned: null, clearPin: true, note: "" };
+    }
+    return pin === "browser"
+        ? { computer: "off", browser: true, pinned: "browser", clearPin: false, note: "" }
+        : { computer: pin, browser: false, pinned: pin, clearPin: false, note: "" };
+}
+/** How the prompt and the app name a surface. Deliberately the same words
+ * the panel uses, so "tell them it is on the cloud computer" points at a
+ * label the person can find. */
+export function surfaceLabel(surface) {
+    switch (surface) {
+        case "cloud":
+            return "the cloud computer";
+        case "vm":
+            return "the Local VM";
+        case "local":
+            return "this computer";
+        case "browser":
+            return "the built-in browser";
+    }
+}
+/** The one paragraph that says where this turn's work happens. Assembled
+ * from what was actually mounted, never from the setting, so the model is
+ * only ever told about tools it can call. */
+export function surfacePrompt(mounted, opts = {}) {
+    const computer = mounted.computer ? surfaceLabel(mounted.computer) : null;
+    let text = "";
+    if (computer && mounted.browser) {
+        text =
+            ` Two surfaces are mounted this turn: the built-in browser (the browser server's browser_navigate, browser_snapshot, browser_click, browser_fill and friends) and ${computer} (the computer server's tools). Web tasks → the built-in browser. Desktop apps, files and shell → ${computer} tools. Pick one surface for a task and stay on it; if you need the user to sign in, say which surface — the Browser tab or ${computer}.`;
+    }
+    else if (computer) {
+        text =
+            ` Everything you do on screen happens on ${computer}, web pages included, through its own browser; there is no separate built-in browser this turn. If you need the user to sign in, tell them it is on ${computer}.`;
+    }
+    else if (mounted.browser) {
+        text =
+            " Everything you do on screen happens in the built-in browser tab; there is no desktop, file or shell computer this turn. If you need the user to sign in, tell them it is in the Browser tab of the Computer panel.";
+    }
+    if (opts.pinned) {
+        text += ` This task has been running on ${surfaceLabel(opts.pinned)}; keep using it unless the user says otherwise.`;
+    }
+    return text + (opts.note ?? "");
+}
+/** Tool names that touch a screen, for engines that report bare names.
+ * Mirrors the screen-poller regex in the harness. */
+const SCREEN_TOOL = /^(?:screenshot|click|type_text|press_key|scroll|open_url|wait_for|computer_|browser_)/i;
+/** Which surface a completed tool call landed on, or null when it cannot
+ * be told apart. The Claude driver namespaces MCP tools by server, which
+ * is the only fully reliable signal; a bare name is trusted only when one
+ * surface was mounted, because both servers expose `browser_snapshot`. */
+export function surfaceForTool(toolName, mounted) {
+    if (toolName.startsWith("mcp__browser__"))
+        return mounted.browser ? "browser" : null;
+    if (toolName.startsWith("mcp__computer__"))
+        return mounted.computer;
+    if (!SCREEN_TOOL.test(toolName))
+        return null;
+    if (mounted.computer && !mounted.browser)
+        return mounted.computer;
+    if (!mounted.computer && mounted.browser && /^browser_/i.test(toolName))
+        return "browser";
+    return null;
+}

package/dist-server/server/tailscale.js

@@ -0,0 +1,103 @@
+// Serving over a tailnet: find the Tailscale CLI, read this machine's
+// MagicDNS name, and ask Tailscale to terminate HTTPS for the server.
+// Nothing here logs Tailscale's raw stderr: it can contain auth keys and
+// node names, so failures are classified into a closed set of reasons.
+import { execFile } from "node:child_process";
+import { searchPath, tailscaleCandidates } from "../companion/src/listener.js";
+/** Turn Tailscale's stderr into a reason without repeating it. */
+export function classifyTailscaleStderr(text) {
+    const t = text.toLowerCase();
+    if (/not logged in|logged out|needs login|please log in/.test(t))
+        return "not-logged-in";
+    if (/is tailscale running|tailscaled is not running|connection refused|failed to connect to local tailscaled/.test(t))
+        return "not-running";
+    if (/access denied|permission denied|operator|must be root|not permitted/.test(t))
+        return "needs-operator";
+    if (/https is not enabled|enable https|cert|tls certs/.test(t))
+        return "https-not-enabled";
+    if (/magicdns/.test(t))
+        return "no-magicdns";
+    return "unknown";
+}
+/** What to do about it, for a person. */
+export function explainTailscaleFailure(reason) {
+    switch (reason) {
+        case "not-installed":
+            return "Tailscale is not installed: https://tailscale.com/download";
+        case "not-logged-in":
+            return "Tailscale is installed but not signed in: run `tailscale up` (or sign in from the Tailscale app)";
+        case "not-running":
+            return "Tailscale is not running: start it, then try again";
+        case "no-magicdns":
+            return "this machine has no MagicDNS name: enable MagicDNS in the tailnet's DNS settings";
+        case "needs-operator":
+            return "Tailscale refused: on Linux run `sudo tailscale set --operator=$USER` once, then try again";
+        case "https-not-enabled":
+            return "HTTPS certificates are off for this tailnet: enable them in the admin console (DNS → HTTPS Certificates)";
+        default:
+            return "Tailscale reported an error; run `tailscale status` and `tailscale serve status` to see it";
+    }
+}
+function run(cli, args, timeoutMs) {
+    return new Promise((resolve) => {
+        execFile(cli, args, { timeout: timeoutMs, killSignal: "SIGKILL", maxBuffer: 16 * 1024 * 1024, env: { ...process.env, PATH: searchPath() } }, (error, stdout, stderr) => {
+            const code = error && "code" in error && typeof error.code === "number" ? error.code : error ? null : 0;
+            resolve({ ok: !error, stdout: String(stdout ?? ""), stderr: String(stderr ?? ""), code });
+        });
+    });
+}
+/** Parse `tailscale status --json`. Exported for tests. */
+export function parseTailscaleStatus(cli, stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+    const self = Reflect.get(Object(parsed), "Self");
+    const dns = Reflect.get(Object(self), "DNSName");
+    const ips = Reflect.get(Object(self), "TailscaleIPs");
+    const state = Reflect.get(Object(parsed), "BackendState");
+    return {
+        cli,
+        dnsName: typeof dns === "string" && dns ? dns.replace(/\.$/, "") : null,
+        addresses: Array.isArray(ips) ? ips.filter((v) => typeof v === "string") : [],
+        backendState: typeof state === "string" ? state : "unknown",
+    };
+}
+/** Find a working Tailscale CLI and read its status. */
+export async function tailscaleStatus() {
+    let sawCli = false;
+    for (const cli of tailscaleCandidates()) {
+        const result = await run(cli, ["status", "--json"], 5_000);
+        if (!result.ok && !result.stdout && result.code === null)
+            continue; // not found or timed out
+        sawCli = true;
+        const status = parseTailscaleStatus(cli, result.stdout);
+        if (status) {
+            if (status.backendState === "NeedsLogin")
+                return { failure: "not-logged-in" };
+            if (status.backendState !== "Running")
+                return { failure: "not-running" };
+            return { status };
+        }
+        if (result.stderr)
+            return { failure: classifyTailscaleStderr(result.stderr) };
+    }
+    return { failure: sawCli ? "unknown" : "not-installed" };
+}
+/** `tailscale serve --bg --https=<httpsPort> http://127.0.0.1:<localPort>`:
+ * Tailscale terminates TLS with its own certificate and forwards with the
+ * forwarded headers the server expects. Returns the public origin. */
+export async function tailscaleServe(status, localPort, httpsPort = 443) {
+    if (!status.dnsName)
+        return { failure: "no-magicdns" };
+    const result = await run(status.cli, ["serve", "--bg", `--https=${httpsPort}`, `http://127.0.0.1:${localPort}`], 20_000);
+    if (!result.ok)
+        return { failure: classifyTailscaleStderr(result.stderr || result.stdout) };
+    return { origin: httpsPort === 443 ? `https://${status.dnsName}` : `https://${status.dnsName}:${httpsPort}` };
+}
+export async function tailscaleServeOff(status, httpsPort = 443) {
+    await run(status.cli, ["serve", `--https=${httpsPort}`, "off"], 10_000);
+}

package/dist-server/server/team-backup.js

@@ -0,0 +1,183 @@
+import { newId } from "./contracts.js";
+import { botMascotBody } from "../shared/mascot-bodies.js";
+import { takeImportName } from "../shared/import-name.js";
+import { MAX_TEAM_BACKUP_BYTES, parseTeamBackup } from "../shared/team-backup.js";
+/** Preserve readable history without importing executable cards, live queue
+ * entries, approval requests, local paths or provider session handles. */
+function messageText(message) {
+    const parts = [message.text ?? ""];
+    if (message.card)
+        parts.push(message.card.title, message.card.subtitle, ...message.card.options, message.card.answered ?? "");
+    if (message.tool)
+        parts.push(`[${message.tool.name}${message.tool.ok === false ? ": failed" : ""}]`);
+    if (message.kind === "connector")
+        parts.push("[Connection card — reconnect in Settings]");
+    if (message.kind === "secret")
+        parts.push("[Secret request — not restored]");
+    if (message.routineRun)
+        parts.push(`[Routine: ${message.routineRun.routineName} — ${message.routineRun.status}]`, message.routineRun.summary ?? "", message.routineRun.error ?? "");
+    if (message.goalRun)
+        parts.push(`[Room goal: ${message.goalRun.status}]`, message.goalRun.goal, message.goalRun.detail ?? "");
+    if (message.kind === "screen" || message.attachments?.length)
+        parts.push("[Image or attachment — file not included in this backup]");
+    return parts.filter(Boolean).join("\n");
+}
+export function createTeamBackup(store, routines, name) {
+    const botIds = new Set(store.bots.map((bot) => bot.id));
+    const warnings = [];
+    const history = (record) => {
+        const tasks = record.tasks?.length ? record.tasks : [{ threadId: record.threadId, title: "Conversation", createdAt: record.createdAt }];
+        return tasks.map((task) => ({
+            key: task.threadId, title: task.title, createdAt: task.createdAt,
+            activeLeafId: store.activeLeaf(task.threadId),
+            messages: store.messagesFor(task.threadId).map((message) => ({
+                id: message.id, role: message.role, text: messageText(message), at: message.at,
+                parentId: message.parentId ?? null, replyToId: message.replyToId,
+                from: message.from, peerPost: message.peerPost,
+            })),
+        }));
+    };
+    const groups = store.groups.map((group) => {
+        const memberIds = group.memberIds.filter((id) => botIds.has(id));
+        if (memberIds.length !== group.memberIds.length)
+            warnings.push(`Room “${group.name}” contains deleted bots. Its conversation is included with the remaining members.`);
+        return {
+            key: group.id, name: group.name, section: group.section, dm: Boolean(group.dm) && memberIds.length === 2,
+            bulletin: group.bulletin, memberIds,
+            defaultResponder: group.defaultResponder.kind === "member" && !memberIds.includes(group.defaultResponder.botId)
+                ? { kind: "mentions" } : group.defaultResponder,
+            activeTask: group.threadId, tasks: history(group),
+        };
+    });
+    const validRoutines = routines.filter((routine) => {
+        const room = groups.find((group) => group.key === routine.groupId);
+        const valid = botIds.has(routine.botId) && (routine.target !== "room-goal" || (room && !room.dm && room.memberIds.includes(routine.botId)));
+        if (!valid)
+            warnings.push(`Routine “${routine.name}” is not included because its bot, room or coordinator was deleted.`);
+        return valid;
+    });
+    const document = parseTeamBackup({
+        format: "openmaus.backup", version: 1, name, exportedAt: Date.now(),
+        warnings,
+        bots: store.bots.map((bot) => ({
+            key: bot.id, name: bot.name, title: bot.title, description: bot.description,
+            section: bot.section, color: bot.color,
+            mascotExpression: bot.mascotExpression ?? undefined, mascotBody: bot.mascotBody ?? undefined,
+            chiefOfStaff: Boolean(bot.chiefOfStaff), hidden: Boolean(bot.hidden), playbooks: bot.playbooks ?? [],
+            activeTask: bot.threadId, tasks: history(bot),
+        })),
+        groups,
+        routines: validRoutines.map((routine) => ({
+            name: routine.name, prompt: routine.prompt, target: routine.target, botId: routine.botId,
+            groupId: routine.groupId, runOn: routine.runOn, schedule: routine.schedule,
+            durationMinutes: routine.durationMinutes, timeoutMinutes: routine.timeoutMinutes,
+        })),
+    });
+    // Never download a file our own importer cannot read; never truncate history.
+    if (Buffer.byteLength(JSON.stringify(document)) > MAX_TEAM_BACKUP_BYTES) {
+        throw new Error("This backup exceeds the 50 MB portable-backup limit. Nothing was exported or changed.");
+    }
+    return document;
+}
+/** Import is always additive, including sections and Chiefs. Rollback owns
+ * only the fresh records below and cannot touch any pre-existing bot/chat. */
+export function importTeamBackup(store, routines, input, selection) {
+    const backup = parseTeamBackup(input);
+    const bots = [];
+    const groups = [];
+    const createdRoutines = [];
+    const existingBotIds = new Set(store.bots.map((bot) => bot.id));
+    const existingGroupIds = new Set(store.groups.map((group) => group.id));
+    const botIds = new Map();
+    const groupIds = new Map();
+    const takenNames = new Set(store.bots.map((bot) => bot.name.trim().toLowerCase()));
+    const takenGroups = new Set(store.groups.map((group) => group.name.trim().toLowerCase()));
+    const takenSections = new Set([...store.bots, ...store.groups].map((record) => record.section?.trim().toLowerCase() ?? ""));
+    const sections = new Map();
+    const sectionFor = (section) => {
+        const key = section?.trim() ?? "";
+        if (!sections.has(key))
+            sections.set(key, takeImportName(section?.trim() || "Imported bots", takenSections, 60));
+        return sections.get(key);
+    };
+    const restore = (task, threadId) => {
+        const ids = new Map(task.messages.map((message) => [message.id, newId()]));
+        const messages = task.messages.map((message) => ({
+            id: ids.get(message.id), kind: "text", role: message.role, text: message.text, at: message.at,
+            parentId: message.parentId ? ids.get(message.parentId) : null,
+            replyToId: message.replyToId ? ids.get(message.replyToId) : undefined,
+            // Removed historical senders retain their name in the text, never a
+            // link to an unrelated local bot with a colliding file key.
+            ...(message.from && botIds.has(message.from.botId)
+                ? { from: { ...message.from, botId: botIds.get(message.from.botId) } }
+                : message.from ? { text: `${message.from.name}:\n${message.text}` } : {}),
+            peerPost: message.peerPost,
+        }));
+        store.importTranscript(threadId, messages, task.activeLeafId ? ids.get(task.activeLeafId) : null);
+    };
+    try {
+        // Allocate all bot IDs before remapping any conversation participants.
+        for (const source of backup.bots) {
+            const bot = store.createBot({
+                name: takeImportName(source.name, takenNames), title: source.title, description: source.description,
+                color: source.color, mascotExpression: source.mascotExpression,
+                mascotBody: botMascotBody(source.mascotBody),
+                modelSelection: selection, section: sectionFor(source.section),
+            }, { seedMessages: false });
+            bots.push(bot);
+            botIds.set(source.key, bot.id);
+            store.patchBot(bot.id, { composio: false, computer: "off", browser: false, approvalMode: "ask", autoApprove: false,
+                hidden: source.hidden, chiefOfStaff: source.chiefOfStaff, playbooks: source.playbooks });
+        }
+        for (const source of backup.bots) {
+            const bot = store.bot(botIds.get(source.key));
+            const tasks = source.tasks.map((task, i) => ({
+                threadId: i === 0 ? bot.threadId : newId(), title: task.title, createdAt: task.createdAt, resumeCursors: {},
+            }));
+            // Own the task IDs before writing their transcripts, so rollback also
+            // removes partially imported history if persistence fails midway.
+            store.patchBot(bot.id, { tasks, threadId: tasks[source.tasks.findIndex((task) => task.key === source.activeTask)].threadId });
+            source.tasks.forEach((task, i) => restore(task, tasks[i].threadId));
+        }
+        for (const source of backup.groups) {
+            const group = store.createGroup(takeImportName(source.name, takenGroups), source.memberIds.map((id) => botIds.get(id)), source.dm, sectionFor(source.section));
+            groups.push(group);
+            groupIds.set(source.key, group.id);
+            const responder = source.defaultResponder;
+            store.patchGroup(group.id, { bulletin: source.bulletin, setupCompletedAt: Date.now(), defaultResponder: responder.kind === "member" ? { kind: "member", botId: botIds.get(responder.botId) } : responder });
+            // Use the existing task APIs for rooms; direct-message rooms have one.
+            const threads = source.tasks.map((task, i) => {
+                if (i === 0) {
+                    if (!source.dm)
+                        store.renameGroupTask(group.id, group.threadId, task.title);
+                    return group.threadId;
+                }
+                return store.createGroupTask(group.id, task.title, false).threadId;
+            });
+            source.tasks.forEach((task, i) => restore(task, threads[i]));
+            if (!source.dm) {
+                group.tasks = source.tasks.map((task, i) => ({ threadId: threads[i], title: task.title, createdAt: task.createdAt }));
+                store.switchGroupTask(group.id, threads[source.tasks.findIndex((task) => task.key === source.activeTask)]);
+            }
+        }
+        for (const source of backup.routines) {
+            createdRoutines.push(routines.create({ ...source, botId: botIds.get(source.botId),
+                groupId: source.target === "room-goal" ? groupIds.get(source.groupId) : undefined, enabled: false }));
+        }
+        return { name: backup.name, bots, groups, routines: createdRoutines };
+    }
+    catch (error) {
+        for (const routine of createdRoutines)
+            routines.remove(routine.id);
+        // createBot/createGroup can throw during persistence before returning.
+        // This synchronous import cannot interleave another writer, so include
+        // every fresh ID, even a record that never reached the result arrays.
+        for (const group of store.groups)
+            if (!existingGroupIds.has(group.id))
+                store.deleteGroup(group.id);
+        for (const bot of store.bots)
+            if (!existingBotIds.has(bot.id))
+                store.deleteBot(bot.id);
+        throw error;
+    }
+}

package/dist-server/server/team-library.js

@@ -0,0 +1,205 @@
+import { parseJson } from "./schema.js";
+import { isBotPackage, parseBotPackage } from "./bot-package.js";
+import { parseTeamManifest } from "./team-manifest.js";
+export const TEAM_LIBRARY_REPOSITORY = "https://github.com/milind-soni/openmausbot-teams";
+export const TEAM_LIBRARY_RAW_ROOT = "https://raw.githubusercontent.com/milind-soni/openmausbot-teams/main";
+export const TEAM_LIBRARY_CATALOG_URL = `${TEAM_LIBRARY_RAW_ROOT}/catalog.json`;
+const MAX_CATALOG_BYTES = 256_000;
+const MAX_MANIFEST_BYTES = 1_000_000;
+const isRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+function text(value, field, max) {
+    if (typeof value !== "string" || !value.trim())
+        throw new Error(`${field} is required`);
+    const normalized = value.trim();
+    if (normalized.length > max)
+        throw new Error(`${field} is too long`);
+    return normalized;
+}
+function relativeFile(value, field, suffix, prefix) {
+    const path = text(value, field, 300);
+    if (path.startsWith("/") ||
+        path.includes("\\") ||
+        path.split("/").some((part) => !part || part === "." || part === "..") ||
+        !path.startsWith(prefix) ||
+        !path.endsWith(suffix)) {
+        throw new Error(`${field} is not a safe catalog path`);
+    }
+    return path;
+}
+function stringList(value, field, maxItems) {
+    if (!Array.isArray(value) || value.length > maxItems)
+        throw new Error(`${field} is invalid`);
+    return value.map((item, index) => text(item, `${field}[${index}]`, 100));
+}
+/** Validate the remotely maintained index before any of it reaches the renderer. */
+export function parseTeamCatalog(value) {
+    if (!isRecord(value) || value.format !== "openmaus.catalog" || value.version !== 1) {
+        throw new Error("The team library catalog is not supported");
+    }
+    if (!Array.isArray(value.teams) || value.teams.length > 100) {
+        throw new Error("The team library catalog is invalid");
+    }
+    const slugs = new Set();
+    const teams = value.teams.map((raw, index) => {
+        const field = `teams[${index}]`;
+        if (!isRecord(raw))
+            throw new Error(`${field} is invalid`);
+        const slug = text(raw.slug, `${field}.slug`, 80);
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(slug) || slugs.has(slug)) {
+            throw new Error(`${field}.slug is invalid`);
+        }
+        slugs.add(slug);
+        const prefix = `teams/${slug}/`;
+        const requires = isRecord(raw.requires) ? raw.requires : {};
+        return {
+            slug,
+            name: text(raw.name, `${field}.name`, 100),
+            summary: text(raw.summary, `${field}.summary`, 300),
+            category: text(raw.category, `${field}.category`, 80),
+            ...(typeof raw.outcome === "string" ? { outcome: text(raw.outcome, `${field}.outcome`, 300) } : {}),
+            ...(typeof raw.setupMinutes === "number" && Number.isSafeInteger(raw.setupMinutes) && raw.setupMinutes > 0 && raw.setupMinutes <= 240
+                ? { setupMinutes: raw.setupMinutes }
+                : {}),
+            ...(typeof raw.featured === "boolean" ? { featured: raw.featured } : {}),
+            ...(raw.package !== undefined
+                ? { package: relativeFile(raw.package, `${field}.package`, ".md", "packages/") }
+                : {}),
+            manifest: relativeFile(raw.manifest, `${field}.manifest`, ".mausteam.json", prefix),
+            readme: relativeFile(raw.readme, `${field}.readme`, "README.md", prefix),
+            members: typeof raw.members === "number" && Number.isSafeInteger(raw.members) && raw.members > 0 && raw.members <= 200
+                ? raw.members
+                : (() => { throw new Error(`${field}.members is invalid`); })(),
+            skills: Array.isArray(raw.skills)
+                ? raw.skills.map((skill, skillIndex) => relativeFile(skill, `${field}.skills[${skillIndex}]`, "SKILL.md", `${prefix}skills/`))
+                : (() => { throw new Error(`${field}.skills is invalid`); })(),
+            requires: { apps: stringList(requires.apps ?? [], `${field}.requires.apps`, 30) },
+        };
+    });
+    return {
+        format: "openmaus.catalog",
+        version: 1,
+        repositoryUrl: TEAM_LIBRARY_REPOSITORY,
+        teams,
+    };
+}
+async function fetchJson(url, maxBytes, fetcher) {
+    const response = await fetcher(url, {
+        headers: { accept: "application/json, text/plain;q=0.9" },
+        redirect: "error",
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) {
+        const error = Object.assign(new Error(`GitHub returned HTTP ${response.status}`), { status: response.status });
+        throw error;
+    }
+    const announced = Number(response.headers.get("content-length") ?? 0);
+    if (announced > maxBytes)
+        throw new Error("The remote team file is too large");
+    const raw = await response.text();
+    if (Buffer.byteLength(raw) > maxBytes)
+        throw new Error("The remote team file is too large");
+    try {
+        return parseJson(raw);
+    }
+    catch {
+        throw new Error("GitHub did not return valid JSON");
+    }
+}
+async function fetchText(url, maxBytes, fetcher) {
+    const response = await fetcher(url, {
+        headers: { accept: "text/markdown, text/plain;q=0.9" },
+        redirect: "error",
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok)
+        throw Object.assign(new Error(`GitHub returned HTTP ${response.status}`), { status: response.status });
+    const announced = Number(response.headers.get("content-length") ?? 0);
+    if (announced > maxBytes)
+        throw new Error("The remote team file is too large");
+    const raw = await response.text();
+    if (Buffer.byteLength(raw) > maxBytes)
+        throw new Error("The remote team file is too large");
+    return raw;
+}
+export async function fetchTeamCatalog(fetcher = fetch) {
+    return parseTeamCatalog(await fetchJson(TEAM_LIBRARY_CATALOG_URL, MAX_CATALOG_BYTES, fetcher));
+}
+function parseShareable(value) {
+    if (typeof value === "string")
+        return parseBotPackage(value);
+    return isBotPackage(value) ? parseBotPackage(value) : parseTeamManifest(value);
+}
+async function fetchShareable(url, fetcher) {
+    return url.endsWith(".md")
+        ? parseBotPackage(await fetchText(url, MAX_MANIFEST_BYTES, fetcher))
+        : parseShareable(await fetchJson(url, MAX_MANIFEST_BYTES, fetcher));
+}
+export async function fetchLibraryTeam(slug, fetcher = fetch) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(slug))
+        throw new Error("That team name is invalid");
+    const catalog = await fetchTeamCatalog(fetcher);
+    const entry = catalog.teams.find((team) => team.slug === slug);
+    if (!entry)
+        throw Object.assign(new Error("That library team was not found"), { status: 404 });
+    return fetchShareable(`${TEAM_LIBRARY_RAW_ROOT}/${entry.package ?? entry.manifest}`, fetcher);
+}
+function safeSegment(value) {
+    return /^[A-Za-z0-9._-]+$/.test(value) && value !== "." && value !== "..";
+}
+/** Resolve only public GitHub Markdown playbooks and legacy JSON team files.
+ * Other hosts never reach server fetch. */
+export function githubManifestUrls(input) {
+    let url;
+    try {
+        url = new URL(input.trim());
+    }
+    catch {
+        throw new Error("Enter a valid GitHub URL");
+    }
+    if (url.protocol !== "https:" || url.username || url.password || url.port) {
+        throw new Error("Only public HTTPS GitHub links are supported");
+    }
+    const parts = url.pathname.split("/").filter(Boolean).map((part) => decodeURIComponent(part));
+    if (!parts.every(safeSegment))
+        throw new Error("That GitHub path is not supported");
+    if (url.hostname === "github.com" || url.hostname === "www.github.com") {
+        if (parts.length === 2) {
+            const [owner, repo] = parts;
+            return [
+                `https://raw.githubusercontent.com/${owner}/${repo}/main/botmrr.md`,
+                `https://raw.githubusercontent.com/${owner}/${repo}/main/team.md`,
+                `https://raw.githubusercontent.com/${owner}/${repo}/main/team.mausteam.json`,
+                `https://raw.githubusercontent.com/${owner}/${repo}/master/botmrr.md`,
+                `https://raw.githubusercontent.com/${owner}/${repo}/master/team.md`,
+                `https://raw.githubusercontent.com/${owner}/${repo}/master/team.mausteam.json`,
+            ];
+        }
+        if (parts.length >= 5 && (parts[2] === "blob" || parts[2] === "raw")) {
+            const [owner, repo, , ref, ...file] = parts;
+            if (!file.at(-1)?.match(/\.(?:md|json)$/))
+                throw new Error("The GitHub link must point to a Markdown playbook or JSON team file");
+            return [`https://raw.githubusercontent.com/${owner}/${repo}/${ref}/${file.join("/")}`];
+        }
+    }
+    if (url.hostname === "raw.githubusercontent.com" && parts.length >= 4) {
+        if (!parts.at(-1)?.match(/\.(?:md|json)$/))
+            throw new Error("The GitHub link must point to a Markdown playbook or JSON team file");
+        return [`https://raw.githubusercontent.com/${parts.join("/")}`];
+    }
+    throw new Error("Paste a GitHub repository, Markdown playbook, or legacy JSON team link");
+}
+export async function fetchGithubTeam(input, fetcher = fetch) {
+    const urls = githubManifestUrls(input);
+    let lastError;
+    for (const url of urls) {
+        try {
+            return await fetchShareable(url, fetcher);
+        }
+        catch (error) {
+            lastError = error;
+            if (error.status !== 404)
+                throw error;
+        }
+    }
+    throw lastError ?? new Error("No botmrr.md, team.md, or legacy team file was found in that repository");
+}