@mindbridgeio/muse 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# @mindbridgeio/muse
+
+MindBridge MCP tools and lifecycle hooks for Muse, using durable OAuth.
+
+```sh
+npx -y @mindbridgeio/muse@latest setup
+```
+
+The command writes the `streamable_http` MCP server and native lifecycle hooks
+into `~/.config/muse/settings.json` (or `$XDG_CONFIG_HOME/muse/settings.json`),
+starts Muse's MCP login, then signs lifecycle hooks in through the system
+keychain. It uses `https://memory.ifelse.io` by default; pass
+`--server-url https://…` or set `MINDBRIDGE_MCP_SERVER_URL` for a nonsecret
+server override.
+
+```sh
+npx -y @mindbridgeio/muse@latest auth status
+npx -y @mindbridgeio/muse@latest auth logout
+npx -y @mindbridgeio/muse@latest doctor
+```
+
+No Bearer [REDACTED] is placed in Muse configuration, command arguments, or an
+environment variable. A keychain is required; setup fails safely when one is
+unavailable.
+
+Setup validates the server, Muse CLI, and keychain before changing config. If
+MindBridge is temporarily unavailable, hooks remain non-blocking and replay
+redacted pending events from a bounded local outbox. `doctor --json` reports
+MCP configuration, lifecycle OAuth, and outbox health. The MCP server is
+registered as `optional` so a MindBridge outage can never abort a session.
+
+New sessions are tagged automatically from Muse's working directory. Git
+repositories use a credential-free remote identity; non-Git directories use a
+private install-scoped local identity. Recall prefers the current project and
+then fills from the wider MindBridge workspace.

package/bin/mindbridge-muse.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+import { realpathSync } from "node:fs";
+import { cp, mkdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  agentHookStateRoot,
+  createOAuthClient,
+  copyKeyringRuntime,
+  oauthReason,
+  outboxStatus,
+  preflightServer,
+  readServerConfig,
+  resolveServerURL,
+  saveServerConfig,
+} from "../dist/agent-oauth.mjs";
+import { atomicWrite, phase, readJSON, runCommand, withoutManagedHooks } from "../dist/agent-install.mjs";
+
+const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const MANAGED_HOOK_STATUSES = ["loading mindbridge memory", "recording mindbridge context", "recording mindbridge response", "finalizing mindbridge context"];
+
+export function defaultMuseHome(env = process.env) {
+  if (env.MUSE_CONFIG_DIR) return env.MUSE_CONFIG_DIR;
+  if (env.XDG_CONFIG_HOME) return join(env.XDG_CONFIG_HOME, "muse");
+  return join(homedir(), ".config", "muse");
+}
+
+export function installSettings(existing, hookPath, serverURL) {
+  const hooks = { ...(existing?.hooks && typeof existing.hooks === "object" ? existing.hooks : {}) };
+  const specs = {
+    SessionStart: ["Loading MindBridge memory", 30],
+    UserPromptSubmit: ["Recording MindBridge context", 10],
+    Stop: ["Recording MindBridge response", 10],
+    SessionEnd: ["Finalizing MindBridge context", 30],
+  };
+  for (const [event, [statusMessage, timeout]] of Object.entries(specs)) {
+    hooks[event] = [
+      ...withoutManagedHooks(hooks[event], MANAGED_HOOK_STATUSES),
+      { hooks: [{ type: "command", command: `node ${JSON.stringify(hookPath)} muse`, timeout, statusMessage }] },
+    ];
+  }
+  // Muse has no `mcp add` command; the server entry is written directly. It
+  // stays optional so a memory-server outage can never abort a session.
+  const mcpServers = { ...(existing?.mcpServers && typeof existing.mcpServers === "object" ? existing.mcpServers : {}) };
+  mcpServers.mindbridge = { transport: "streamable_http", url: `${serverURL}/mcp`, mode: "optional" };
+  return { ...existing, schema_version: 1, hooks, mcpServers };
+}
+
+function unavailable(error) {
+  return error?.code === "ENOENT";
+}
+
+async function hostLogin(commandRunner) {
+  try {
+    await commandRunner("muse", ["mcp", "login", "mindbridge"]);
+    return "started";
+  } catch (error) {
+    if (unavailable(error)) return "unavailable";
+    throw error;
+  }
+}
+
+export async function setup({
+  museHome = defaultMuseHome(),
+  packageRoot = PACKAGE_ROOT,
+  env = process.env,
+  serverURL,
+  configRoot,
+  commandRunner = runCommand,
+  copyRuntime = copyKeyringRuntime,
+  preflight = preflightServer,
+  oauthClientFactory = (url) => createOAuthClient({ host: "muse", serverURL: url, env, configRoot }),
+} = {}) {
+  const resolvedServerURL = await resolveServerURL({ host: "muse", serverURL, env, configRoot });
+  const oauth = oauthClientFactory(resolvedServerURL);
+  await phase("server OAuth discovery", () => preflight(resolvedServerURL));
+  await phase("Muse CLI preflight", () => commandRunner("muse", ["mcp", "--help"]));
+  await phase("lifecycle keychain preflight", () => oauth.status());
+  const installRoot = join(museHome, "mindbridge");
+  const distSource = join(packageRoot, "dist");
+  const distTarget = join(installRoot, "dist");
+  const hookPath = join(distTarget, "oauth-hook.mjs");
+  await mkdir(installRoot, { recursive: true, mode: 0o700 });
+  await cp(distSource, distTarget, { recursive: true, force: true });
+  await copyRuntime({ targetRoot: installRoot });
+
+  const settingsPath = join(museHome, "settings.json");
+  await atomicWrite(settingsPath, `${JSON.stringify(installSettings(await readJSON(settingsPath, {}), hookPath, resolvedServerURL), null, 2)}\n`);
+  await saveServerConfig("muse", resolvedServerURL, { configRoot, env });
+  const mcpLogin = await phase("Muse MCP authorization", () => hostLogin(commandRunner));
+  await phase("lifecycle-hook authorization", () => oauth.authenticate());
+  return { museHome, settingsPath, hookPath, serverURL: resolvedServerURL, mcpLogin };
+}
+
+export const install = setup;
+
+export async function authStatus({ env = process.env, serverURL, configRoot, oauthClientFactory } = {}) {
+  const resolvedServerURL = await resolveServerURL({ host: "muse", serverURL, env, configRoot });
+  const client = (oauthClientFactory || ((url) => createOAuthClient({ host: "muse", serverURL: url, env, configRoot })))(resolvedServerURL);
+  const stored = await client.status();
+  if (!stored.authenticated || !client.check) return { serverURL: resolvedServerURL, ...stored };
+  try {
+    await client.check();
+    return { serverURL: resolvedServerURL, ...stored, healthy: true };
+  } catch (error) {
+    return { serverURL: resolvedServerURL, ...stored, healthy: false, reason: oauthReason(error) };
+  }
+}
+
+export async function doctor({
+  museHome = defaultMuseHome(),
+  env = process.env,
+  serverURL,
+  configRoot,
+  commandRunner = runCommand,
+  preflight = preflightServer,
+  oauthClientFactory = (url) => createOAuthClient({ host: "muse", serverURL: url, env, configRoot }),
+} = {}) {
+  const resolvedServerURL = await resolveServerURL({ host: "muse", serverURL, env, configRoot });
+  const checks = {};
+  try { await preflight(resolvedServerURL); checks.server = "pass"; } catch (error) { checks.server = oauthReason(error); }
+  try { await commandRunner("muse", ["--version"]); checks.host = "pass"; } catch { checks.host = "muse_unavailable"; }
+  try {
+    const settings = JSON.parse(await readFile(join(museHome, "settings.json"), "utf8"));
+    const serialized = JSON.stringify(settings.hooks || {});
+    checks.installation = serialized.includes("mindbridge") && settings.mcpServers?.mindbridge?.url === `${resolvedServerURL}/mcp` ? "pass" : "stale";
+  } catch { checks.installation = "missing"; }
+  try { await oauthClientFactory(resolvedServerURL).check(); checks.lifecycleAuth = "pass"; } catch (error) { checks.lifecycleAuth = oauthReason(error); }
+  const outbox = await outboxStatus(agentHookStateRoot({ env }));
+  return {
+    ok: Object.values(checks).every((value) => value === "pass") && outbox.losses === 0,
+    serverURL: resolvedServerURL,
+    checks,
+    outbox,
+  };
+}
+
+export async function authLogout({ env = process.env, serverURL, configRoot, oauthClientFactory } = {}) {
+  const resolvedServerURL = await resolveServerURL({ host: "muse", serverURL, env, configRoot });
+  const client = (oauthClientFactory || ((url) => createOAuthClient({ host: "muse", serverURL: url, env, configRoot })))(resolvedServerURL);
+  return { serverURL: resolvedServerURL, loggedOut: await client.logout() };
+}
+
+function parseArgs(args) {
+  let serverURL;
+  const rest = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--server-url" && args[index + 1]) {
+      serverURL = args[index + 1];
+      index += 1;
+    } else rest.push(args[index]);
+  }
+  return { serverURL, rest };
+}
+
+async function main() {
+  const { serverURL, rest } = parseArgs(process.argv.slice(2));
+  if (rest[0] === "setup" || rest[0] === "install") {
+    const result = await setup({ serverURL });
+    console.log(`MindBridge setup complete for Muse (${result.serverURL}).`);
+    return;
+  }
+  if (rest[0] === "auth" && rest[1] === "status") {
+    const result = await authStatus({ serverURL });
+    const status = !result.authenticated
+      ? "signed out"
+      : result.healthy
+        ? "signed in (healthy)"
+        : `signed in but needs repair (${result.reason || "health_check_failed"})`;
+    console.log(`MindBridge lifecycle OAuth: ${status}`);
+    if (!result.authenticated || !result.healthy) process.exitCode = 1;
+    return;
+  }
+  if (rest[0] === "auth" && rest[1] === "logout") {
+    await authLogout({ serverURL });
+    console.log("MindBridge lifecycle OAuth: signed out");
+    return;
+  }
+  if (rest[0] === "doctor") {
+    const result = await doctor({ serverURL });
+    if (rest.includes("--json")) console.log(JSON.stringify(result));
+    else {
+      console.log(`MindBridge Muse doctor: ${result.ok ? "healthy" : "needs attention"}`);
+      for (const [name, status] of Object.entries(result.checks)) console.log(`${status === "pass" ? "PASS" : "FAIL"} ${name}: ${status}`);
+      console.log(`Outbox: ${result.outbox.pending} pending across ${result.outbox.sessions} sessions`);
+    }
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  console.error("Usage: mindbridge-muse setup [--server-url URL] | doctor [--json] | auth <status|logout>");
+  process.exitCode = 2;
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  main().catch((error) => {
+    const detail = error?.phase || oauthReason(error);
+    console.error(`MindBridge Muse setup failed (${detail}). Run mindbridge-muse setup in an interactive desktop session.`);
+    process.exitCode = 1;
+  });
+}

package/dist/agent-hooks.mjs

@@ -0,0 +1,233 @@
+import {
+  agentHookStateRoot,
+  createOAuthClient,
+  createOAuthSessionClient,
+  oauthReason,
+  resolveServerURL,
+} from "./agent-oauth.mjs";
+import { resolveProjectMetadata } from "./project-metadata.mjs";
+
+const HOOK_START_AUTH_TIMEOUT_MS = 25_000;
+const HOOK_EVENT_AUTH_TIMEOUT_MS = 8_000;
+
+function text(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+const SECRET_PATTERNS = [
+  /\b(?:api[\s_-]?key|access[\s_-]?token|auth[\s_-]?token|password|passwd|secret|token)\b\s*[:=]\s*\S{8,}/gi,
+  /\bsk-[A-Za-z0-9_-]{16,}\b/g,
+  /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /-----BEGIN PRIVATE KEY-----/gi,
+];
+
+function redact(content) {
+  return SECRET_PATTERNS.reduce((value, pattern) => value.replace(pattern, "[REDACTED]"), content);
+}
+
+function hookExternalRef(host, event) {
+  const sessionID = text(event.session_id) || text(event.sessionId);
+  return sessionID ? `${host}:session=${encodeURIComponent(sessionID)}` : "";
+}
+
+function hookNotice(event, reason, reinjected) {
+  if (reinjected.has(text(event.source))) return undefined;
+  return {
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: `MindBridge: this session is not being recorded (${reason}).`,
+    },
+  };
+}
+
+function hookFailure(reason, executable) {
+  if ([
+    "authentication_required",
+    "authorization_cancelled",
+    "authorization_denied",
+    "authorization_timed_out",
+    "browser_unavailable",
+    "keychain_unavailable",
+    "refresh_rejected",
+    "unauthorized",
+  ].includes(reason)) return `run ${executable} setup`;
+  return reason;
+}
+
+function logProjectMetadataOmitted(options, host) {
+  try {
+    (options.logger || ((record) => process.stderr.write(`${JSON.stringify(record)}\n`)))({
+      component: "mindbridge-agent-hook",
+      event: "project_metadata_omitted",
+      host,
+      reason: "detection_failed",
+    });
+  } catch {
+    // Diagnostics must not affect the host runtime.
+  }
+}
+
+function createOAuthHookRuntime({ host, adapterName, endEvent, endReason, reinjected, executable, ...options }) {
+  let remote;
+  const stateRoot = agentHookStateRoot(options);
+  async function client(authorizationTimeoutMs) {
+    remote ??= (async () => {
+      const serverURL = await resolveServerURL({ host, env: options.env, configRoot: options.configRoot, home: options.home });
+      const oauth = options.oauth || createOAuthClient({
+        host,
+        serverURL,
+        env: options.env,
+        configRoot: options.configRoot,
+        stateRoot: options.stateRoot,
+        keyring: options.keyring,
+        keyringLoader: options.keyringLoader,
+        fetchImpl: options.fetchImpl,
+        browser: options.browser,
+        authorizationTimeoutMs,
+        requestTimeoutMs: Math.max(1_000, Math.min(6_000, Math.floor(authorizationTimeoutMs / 2) - 250)),
+      });
+      return createOAuthSessionClient({ serverURL, oauth, stateRoot });
+    })();
+    return remote;
+  }
+  async function startPayload(event, externalRef) {
+    const payload = {
+      externalRef,
+      host,
+      userName: "MindBridge User",
+      agentName: adapterName,
+      adapterName,
+      adapterRef: `${host}:hook`,
+    };
+    try {
+      const metadata = await (options.projectMetadataResolver || resolveProjectMetadata)({
+        cwd: text(event.cwd),
+        projectRoot: host === "claude" ? text((options.env || process.env).CLAUDE_PROJECT_DIR) : "",
+        stateRoot,
+        runGit: options.runGit,
+      });
+      if (metadata) payload.metadata = metadata;
+      else logProjectMetadataOmitted(options, host);
+    } catch {
+      logProjectMetadataOmitted(options, host);
+    }
+    return payload;
+  }
+  async function invoke(operation, payload, authorizationTimeoutMs) {
+    try {
+      return await (await client(authorizationTimeoutMs))[operation](payload);
+    } catch (error) {
+      return { error: oauthReason(error), status: error?.status };
+    }
+  }
+  async function appendMessage(event, externalRef, role, content, prefix, authorizationTimeoutMs) {
+    const turn = text(event.turn_id) || text(event.turnId);
+    const append = () => invoke("append", {
+      externalRef,
+      role,
+      eventType: "message",
+      content: redact(content),
+      messageRef: turn ? `${prefix}:${turn}` : "",
+    }, authorizationTimeoutMs);
+    let result = await append();
+    if (result?.error === "missing_session_state") {
+      const started = await invoke("start", await startPayload(event, externalRef), authorizationTimeoutMs);
+      if (!started?.error) result = await append();
+    } else if (result?.error === "session_ended" || result?.status === 409) {
+      const appendWasQueued = result.status === 409;
+      result = await invoke("reopen", { externalRef }, authorizationTimeoutMs);
+      if (!appendWasQueued && !result?.error) result = await append();
+    }
+    return result;
+  }
+  return {
+    async handle(event = {}) {
+      const externalRef = hookExternalRef(host, event);
+      const name = text(event.hook_event_name) || text(event.hookEventName);
+      if (!externalRef) return undefined;
+      const authorizationTimeoutMs = options.authorizationTimeoutMs ?? (name === "SessionStart" ? HOOK_START_AUTH_TIMEOUT_MS : HOOK_EVENT_AUTH_TIMEOUT_MS);
+      if (name === "SessionStart") {
+        await (await client(authorizationTimeoutMs)).flushAll({ excludeExternalRef: externalRef, limit: 1 });
+        const result = await invoke("start", await startPayload(event, externalRef), authorizationTimeoutMs);
+        if (!result || result.error) return hookNotice(event, hookFailure(result?.error, executable), reinjected);
+        if (!result.prompt_block || reinjected.has(text(event.source))) return undefined;
+        return { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: result.prompt_block } };
+      }
+      if (name === "UserPromptSubmit") {
+        const content = text(event.prompt);
+        if (!content) return undefined;
+        await appendMessage(event, externalRef, "user", content, "in", authorizationTimeoutMs);
+        return undefined;
+      }
+      let appendSucceeded = true;
+      if (name === "Stop") {
+        const content = text(event.last_assistant_message) || text(event.lastAssistantMessage);
+        if (content) {
+          const result = await appendMessage(event, externalRef, "assistant", content, "out", authorizationTimeoutMs);
+          appendSucceeded = Boolean(result && !result.error);
+        }
+      }
+      if (name === endEvent && appendSucceeded) await invoke("end", { externalRef, reason: endReason(event) }, authorizationTimeoutMs);
+      return undefined;
+    },
+  };
+}
+
+export function createCodexOAuthRuntime(options = {}) {
+  return createOAuthHookRuntime({
+    ...options,
+    host: "codex",
+    adapterName: "Codex",
+    executable: "npx -y @mindbridgeio/codex@latest",
+    endEvent: "Stop",
+    endReason: () => "stop",
+    reinjected: new Set(["compact"]),
+  });
+}
+
+export function createClaudeOAuthRuntime(options = {}) {
+  return createOAuthHookRuntime({
+    ...options,
+    host: "claude",
+    adapterName: "Claude",
+    executable: "npx -y @mindbridgeio/claude@latest",
+    endEvent: "SessionEnd",
+    endReason: (event) => text(event.reason) || "session_end",
+    reinjected: new Set(["compact", "resume"]),
+  });
+}
+
+export function createMuseOAuthRuntime(options = {}) {
+  return createOAuthHookRuntime({
+    ...options,
+    host: "muse",
+    adapterName: "Muse",
+    executable: "npx -y @mindbridgeio/muse@latest",
+    endEvent: "SessionEnd",
+    endReason: (event) => text(event.reason) || "session_end",
+    reinjected: new Set(["compact", "resume"]),
+  });
+}
+
+/** Shared stdin/stdout runner. Hooks always fail safely and never block a host. */
+export async function runOAuthHook(createRuntime) {
+  let event = {};
+  try {
+    let raw = "";
+    process.stdin.setEncoding("utf8");
+    for await (const chunk of process.stdin) raw += chunk;
+    if (raw.trim()) event = JSON.parse(raw);
+  } catch {
+    event = {};
+  }
+  let output;
+  try {
+    output = await createRuntime().handle(event);
+  } catch {
+    output = undefined;
+  }
+  process.stdout.on("error", () => process.exit(0));
+  if (output) process.stdout.write(JSON.stringify(output), () => process.exit(0));
+  else process.exit(0);
+}

package/dist/agent-install.mjs

@@ -0,0 +1,62 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+export async function readJSON(path, fallback) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return fallback;
+    throw new Error(`cannot read ${path}`);
+  }
+}
+
+export async function atomicWrite(path, content) {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = join(dirname(path), `.${basename(path)}.${process.pid}.tmp`);
+  try {
+    await writeFile(temp, content, { mode: 0o600 });
+    await rename(temp, path);
+  } finally {
+    await unlink(temp).catch(() => {});
+  }
+}
+
+function managedHook(hook, statuses) {
+  const command = typeof hook?.command === "string" ? hook.command.toLowerCase() : "";
+  const status = typeof hook?.statusMessage === "string" ? hook.statusMessage.toLowerCase() : "";
+  return (command.includes("mindbridge") && command.includes("hook.mjs")) || statuses.includes(status);
+}
+
+export function withoutManagedHooks(groups, statuses) {
+  if (!Array.isArray(groups)) return [];
+  return groups.flatMap((group) => {
+    if (!Array.isArray(group?.hooks)) return [group];
+    const hooks = group.hooks.filter((hook) => !managedHook(hook, statuses));
+    return hooks.length ? [{ ...group, hooks }] : [];
+  });
+}
+
+export function runCommand(command, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: "inherit", shell: false, windowsHide: true });
+    child.once("error", reject);
+    child.once("close", (code) => {
+      if (code === 0) resolve();
+      else {
+        const error = new Error("host command failed");
+        error.exitCode = code;
+        reject(error);
+      }
+    });
+  });
+}
+
+export async function phase(name, operation) {
+  try {
+    return await operation();
+  } catch (error) {
+    error.phase = name;
+    throw error;
+  }
+}