Add portable BotMRR Markdown playbooks

electron-builder.yml

@@ -2,6 +2,10 @@ appId: com.openmausbot.app
 productName: OpenMausBot
 artifactName: OpenMausBot-${version}-${arch}.${ext}
 
+protocols:
+  - name: OpenMausBot package install
+    schemes: [openmausbot]
+
 # In-app auto-update reads latest-mac.yml + the .zip (macOS) or latest.yml +
 # the NSIS .exe (Windows) from this PUBLIC releases repo (separate from the
 # source repo). Public → no token on users' machines. Baked into

electron/main.mjs

@@ -18,6 +18,7 @@ import { startUpdater, registerUpdaterIpc } from "./updater.mjs";
 import { buildDiagnosticsReport, decodeLogTail, diagnosticsFileName } from "./diagnostics.mjs";
 import { migrateWorkspaceCredentials, workspaceCredentialEnv } from "./workspace-credentials.mjs";
 import { activateExistingWindow } from "./single-instance.mjs";
+import { packageUrlFromCommandLine, packageUrlFromDeepLink } from "./package-link.mjs";
 import capabilitiesModule from "./capabilities.cjs";
 
 const { desktopCapabilities, nativeDesktopActions } = capabilitiesModule;
@@ -39,6 +40,7 @@ const APP_ICON = path.join(__dirname, "resources/app-icon.png");
 let desktopViewerWindow = null;
 let desktopViewerOwner = null;
 let desktopViewerContextId = null;
+let pendingPackageInstallUrl = packageUrlFromCommandLine(process.argv);
 
 // GNOME groups the window with its installed desktop entry only when both
 // identities match. This must run before Electron becomes ready.
@@ -51,8 +53,34 @@ if (!app.requestSingleInstanceLock()) {
   console.log("[desktop] OpenMausBot is already running — focusing that window");
   process.exit(0);
 }
-app.on("second-instance", () => {
+function deliverPackageInstall(win) {
+  if (!pendingPackageInstallUrl || !win || win.isDestroyed()) return;
+  if (win.webContents.isLoadingMainFrame()) return;
+  win.webContents.send("package:install", pendingPackageInstallUrl);
+  pendingPackageInstallUrl = null;
+}
+
+function queuePackageInstall(rawLink) {
+  const packageUrl = packageUrlFromDeepLink(rawLink);
+  if (!packageUrl) return false;
+  pendingPackageInstallUrl = packageUrl;
+  activateExistingWindow(BrowserWindow.getAllWindows());
+  const target = BrowserWindow.getAllWindows().find((win) => !win.isDestroyed());
+  deliverPackageInstall(target);
+  return true;
+}
+
+app.on("open-url", (event, url) => {
+  if (!queuePackageInstall(url)) return;
+  event.preventDefault();
+});
+
+app.on("second-instance", (_event, commandLine) => {
+  const packageUrl = packageUrlFromCommandLine(commandLine);
+  if (packageUrl) pendingPackageInstallUrl = packageUrl;
   activateExistingWindow(BrowserWindow.getAllWindows());
+  const target = BrowserWindow.getAllWindows().find((win) => !win.isDestroyed());
+  deliverPackageInstall(target);
 });
 
 // Packaged: the harness server ships in Resources (compiled JS, zero deps)
@@ -551,6 +579,7 @@ function createWindow() {
     shell.openExternal(url);
     return { action: "deny" };
   });
+  win.webContents.on("did-finish-load", () => deliverPackageInstall(win));
 
   // Packaged CI smoke hook. It validates the real renderer/preload bridge and
   // same-origin embedded server, then follows the normal window-close path.
@@ -962,6 +991,7 @@ setCuaStateListener((connection) => {
 });
 
 app.whenReady().then(async () => {
+  if (app.isPackaged) app.setAsDefaultProtocolClient("openmausbot");
   if (process.platform === "darwin") app.dock.setIcon(APP_ICON);
   secureCredentials = await loadSecureCredentials();
   if (app.isPackaged) {

electron/package-link.mjs

@@ -0,0 +1,36 @@
+const ALLOWED_PACKAGE_HOSTS = new Set(["github.com", "www.github.com", "raw.githubusercontent.com"]);
+
+export function packageUrlFromDeepLink(rawValue) {
+  let link;
+  try {
+    link = new URL(String(rawValue));
+  } catch {
+    return null;
+  }
+  if (link.protocol !== "openmausbot:" || link.hostname !== "install") return null;
+  const rawPackage = link.searchParams.get("url");
+  if (!rawPackage) return null;
+  let packageUrl;
+  try {
+    packageUrl = new URL(rawPackage);
+  } catch {
+    return null;
+  }
+  if (
+    packageUrl.protocol !== "https:" ||
+    packageUrl.username ||
+    packageUrl.password ||
+    packageUrl.port ||
+    !ALLOWED_PACKAGE_HOSTS.has(packageUrl.hostname) ||
+    !packageUrl.pathname.endsWith(".json")
+  ) return null;
+  return packageUrl.toString();
+}
+
+export function packageUrlFromCommandLine(argv) {
+  for (const value of argv) {
+    const parsed = packageUrlFromDeepLink(value);
+    if (parsed) return parsed;
+  }
+  return null;
+}

electron/package-link.test.mjs

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+import { packageUrlFromCommandLine, packageUrlFromDeepLink } from "./package-link.mjs";
+
+describe("BotMRR package deep links", () => {
+  it("accepts a public GitHub package URL", () => {
+    const target = "https://raw.githubusercontent.com/acme/bots/main/package.mauspack.json";
+    assert.equal(packageUrlFromDeepLink(`openmausbot://install?url=${encodeURIComponent(target)}`), target);
+    assert.equal(packageUrlFromCommandLine(["OpenMausBot", "--flag", `openmausbot://install?url=${encodeURIComponent(target)}`]), target);
+  });
+
+  it("rejects other commands, hosts, protocols, credentials, and non-JSON files", () => {
+    assert.equal(packageUrlFromDeepLink("openmausbot://settings"), null);
+    assert.equal(packageUrlFromDeepLink("openmausbot://install?url=https://evil.example/bot.json"), null);
+    assert.equal(packageUrlFromDeepLink("openmausbot://install?url=http://raw.githubusercontent.com/a/b/main/bot.json"), null);
+    assert.equal(packageUrlFromDeepLink("openmausbot://install?url=https://user@example.com/bot.json"), null);
+    assert.equal(packageUrlFromDeepLink("openmausbot://install?url=https://github.com/acme/bot/run.sh"), null);
+  });
+});

electron/preload.cjs

@@ -2,6 +2,14 @@
 // this narrow surface (window.ogb), never Node or ipcRenderer itself.
 const { contextBridge, ipcRenderer, webUtils } = require("electron");
 
+let pendingPackageInstallUrl = null;
+const packageInstallListeners = new Set();
+ipcRenderer.on("package:install", (_event, url) => {
+  if (typeof url !== "string") return;
+  pendingPackageInstallUrl = url;
+  for (const listener of packageInstallListeners) listener(url);
+});
+
 contextBridge.exposeInMainWorld("ogb", {
   /** Host platform ("darwin" | "win32" | "linux") — for platform-aware UI. */
   platform: process.platform,
@@ -100,6 +108,12 @@ contextBridge.exposeInMainWorld("ogb", {
   /** Open a web link in the default browser. Unlike renderer window.open,
    * this remains reliable after an asynchronous API request. */
   openExternal: (url) => ipcRenderer.invoke("desktop:open-external", url),
+  /** A reviewed BotMRR package opened through openmausbot://install. */
+  onPackageInstall: (cb) => {
+    packageInstallListeners.add(cb);
+    if (pendingPackageInstallUrl) cb(pendingPackageInstallUrl);
+    return () => packageInstallListeners.delete(cb);
+  },
   /** Live VNC/noVNC in a sandboxed window owned by the app window. */
   desktopViewer: {
     open: (url, title, contextId) => ipcRenderer.invoke("desktop-viewer:open", url, title, contextId),

package.json

@@ -33,9 +33,10 @@
     "dev:desktop": "electron .",
     "build": "tsc -b && tsc -p tsconfig.server.json && vite build",
     "typecheck": "tsc -b && tsc -p tsconfig.server.json",
-    "test": "node scripts/test-floor.mjs && pnpm broker:test && pnpm test:updater && pnpm test:desktop-viewer && pnpm test:packaged-server",
+    "test": "node scripts/test-floor.mjs && pnpm broker:test && pnpm test:updater && pnpm test:desktop-viewer && pnpm test:package-link && pnpm test:packaged-server",
     "test:updater": "node --test electron/updater-coordinator.node-test.mjs",
     "test:desktop-viewer": "node --test electron/desktop-viewer.node-test.mjs",
+    "test:package-link": "node --test electron/package-link.test.mjs",
     "bench:observation": "node --experimental-strip-types scripts/bench-observation.ts",
     "test:watch": "vitest",
     "test:cua": "pnpm build:cua && node scripts/smoke-cua.mjs",

server/bot-package.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from "vitest";
+
+import { packageAgentAsMember, parseBotPackage } from "./bot-package.ts";
+
+const validPackage: any = {
+  format: "openmaus.package",
+  version: 1,
+  package: {
+    id: "research-desk",
+    release: "1.0.0",
+    name: "Research Desk",
+    tagline: "Turn a question into a sourced brief.",
+    summary: "A small research team.",
+    category: "Research",
+    author: { name: "OpenMausBot" },
+    license: "MIT",
+    outcomes: ["Produce a sourced brief."],
+    setupMinutes: 3,
+    requirements: { apps: [], capabilities: [] },
+    agents: [
+      {
+        key: "lead",
+        name: "Ada",
+        title: "Research Lead",
+        description: "Own the brief.",
+        appearance: { color: "purple" },
+        playbooks: ["source-check"],
+        autoApprove: true,
+      },
+    ],
+    chiefOfStaff: "lead",
+    rooms: [
+      {
+        key: "desk",
+        name: "Research Desk",
+        members: ["lead"],
+        bulletin: "Cite sources.",
+        defaultResponder: { kind: "agent", agent: "lead" },
+      },
+    ],
+    playbooks: [
+      {
+        key: "source-check",
+        name: "Source Check",
+        summary: "Verify sources.",
+        triggers: ["research brief"],
+        instructions: "Separate facts from inference.",
+      },
+    ],
+  },
+};
+
+describe("bot packages", () => {
+  it("parses the complete portable structure and strips authority fields", () => {
+    const parsed = parseBotPackage(validPackage);
+    expect(parsed.package.rooms![0]?.defaultResponder).toEqual({ kind: "agent", agent: "lead" });
+    expect(parsed.package.agents[0]).not.toHaveProperty("autoApprove");
+    expect(packageAgentAsMember(parsed.package.agents[0]!)).toEqual({
+      key: "lead",
+      name: "Ada",
+      title: "Research Lead",
+      description: "Own the brief.",
+      appearance: { color: "purple" },
+    });
+  });
+
+  it("rejects dangling agent, room, playbook, chief, and routine references", () => {
+    expect(() => parseBotPackage({
+      ...validPackage,
+      package: { ...validPackage.package, chiefOfStaff: "missing" },
+    })).toThrow("Unknown Chief of Staff");
+    expect(() => parseBotPackage({
+      ...validPackage,
+      package: {
+        ...validPackage.package,
+        agents: [{ ...validPackage.package.agents[0], playbooks: ["missing"] }],
+      },
+    })).toThrow("unknown playbook");
+  });
+});