@hellolynk-ai/workbuddy-mcp 0.0.0-stage → 0.3.97

package/integrations/workbuddy/server/origin-hook.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { recordWorkBuddyModelCall, workBuddyModelHookCall } from "./model-call-origin.mjs";
+// WorkBuddy PreToolUse hook: new sends keep best-effort origin registration.
+// Inbox calls publish request evidence; a missing native source stops that
+// invocation without a prompt. Reply origins are registered after the MCP guard.
+// The installed native-task worker moves each record into the account's
+// reply-route store; this process holds no binding or credentials. Each record
+// carries the account scope the MCP proxy or worker last marked active (a non-secret hash),
+// so a record made under one account is never imported into another.
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Conversation IDs must also be valid WorkBuddy SDK IDs (128 characters).
+const ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{2,127}$/;
+// Some aggregated MCP modes drop the repeated server prefix from tool names.
+const TOOL = /^mcp__hellolynk__(?:hellolynk_)?(send|reply)_authorized_message$/;
+export const WORKBUDDY_ORIGIN_DIRECT_TOOL_MATCHER = "^mcp__hellolynk__(?:hellolynk_)?(?:send_authorized_message|reply_authorized_message|get_unread_count|list_authorized_inbox_messages|read_authorized_inbox_message|list_pending_messages|claim_message)$";
+export const WORKBUDDY_ORIGIN_TOOL_MATCHER = `^(?:DeferExecuteTool|${WORKBUDDY_ORIGIN_DIRECT_TOOL_MATCHER.slice(1, -1)})$`;
+export const WORKBUDDY_ACTIVE_SCOPE_FILE = "active-scope.json";
+const SCOPE = /^[a-f0-9]{64}$/;
+
+export function workBuddyOriginFromHook(payload) {
+  if (!payload || typeof payload !== "object" || payload.hook_event_name !== "PreToolUse") return null;
+  // agent_type is the active agent's name, even in a main conversation.
+  // A different store ID identifies a subagent of the named conversation.
+  // Equal IDs are accepted; no live restored-session payload is assumed here.
+  if (payload.agent_id && payload.agent_id !== payload.session_id) return null;
+  let name = payload.tool_name, input = objectInput(payload.tool_input);
+  // Current WorkBuddy invokes deferred MCP tools through this one wrapper.
+  // Unrelated wrapped calls return before reading or writing any route files.
+  if (name === "DeferExecuteTool") { name = input?.toolName; input = objectInput(input?.params); }
+  const tool = TOOL.exec(typeof name === "string" ? name : "");
+  if (!tool || !input) return null;
+  const reply = tool[1] === "reply", target = reply ? input.conversationKey : input.recipientDelegateId;
+  if (![payload.session_id, input.clientMessageId, target].every((value) => typeof value === "string" && ID.test(value))) return null;
+  return { threadId: payload.session_id, clientMessageId: input.clientMessageId,
+    conversationKey: reply ? target : null, peerDelegateId: reply ? null : target };
+}
+
+function objectInput(value) {
+  if (typeof value === "string") { try { value = JSON.parse(value); } catch { return null; } }
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+
+// Same name for the same record: a repeated hook run is idempotent.
+export function workBuddyOriginDropName(origin) {
+  return `${crypto.createHash("sha256").update(JSON.stringify([origin.scopeHash, origin.clientMessageId, origin.threadId,
+    origin.conversationKey, origin.peerDelegateId])).digest("hex")}.json`;
+}
+
+// Written by the MCP proxy or worker for the connected account. Missing or
+// damaged: the hook records nothing and replies stay in the HelloLynk inbox.
+export async function readWorkBuddyActiveScope(inbox) {
+  try {
+    const file = path.join(inbox, WORKBUDDY_ACTIVE_SCOPE_FILE);
+    const stat = await fs.lstat(file);
+    if (!stat.isFile() || stat.size > 256) return null;
+    const marker = JSON.parse(await fs.readFile(file, "utf8"));
+    return Object.keys(marker || {}).sort().join() === "scopeHash,version" && marker.version === 1
+      && SCOPE.test(marker.scopeHash || "") ? marker.scopeHash : null;
+  } catch { return null; }
+}
+
+export async function writeWorkBuddyOriginDrop(inbox, origin, now = Date.now()) {
+  await fs.mkdir(inbox, { recursive: true });
+  const file = path.join(inbox, workBuddyOriginDropName(origin));
+  const temporary = `${file}.${process.pid}.${crypto.randomBytes(6).toString("hex")}.tmp`;
+  try {
+    await fs.writeFile(temporary, JSON.stringify({ version: 1, ...origin, createdAt: now }), { flag: "wx", mode: 0o600 });
+    await fs.rename(temporary, file);
+  } finally { await fs.rm(temporary, { force: true }); }
+}
+
+export async function runWorkBuddyOriginHook(argv = process.argv.slice(2), input = process.stdin) {
+  const inbox = argv[0] === "--inbox" && argv.length === 2 ? argv[1] : "";
+  if (!path.isAbsolute(inbox)) return false;
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of input) {
+    size += chunk.length;
+    if (size > 1024 * 1024) return false;
+    chunks.push(chunk);
+  }
+  let payload;
+  try { payload = JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch { return false; }
+  const call = workBuddyModelHookCall(payload);
+  if (call) {
+    try { await recordWorkBuddyModelCall(inbox, payload, await readWorkBuddyActiveScope(inbox)); }
+    catch (error) { throw Object.assign(error, { code: "model_inbox_context_unavailable" }); }
+    // A reply registers its origin only after the MCP handler checks ownership.
+    return true;
+  }
+  const origin = workBuddyOriginFromHook(payload);
+  if (!origin) return false;
+  const scopeHash = await readWorkBuddyActiveScope(inbox);
+  if (!scopeHash) return false;
+  await writeWorkBuddyOriginDrop(inbox, { scopeHash, ...origin });
+  return true;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runWorkBuddyOriginHook().catch(error => {
+    if (error?.code === "model_inbox_context_unavailable") process.stdout.write(JSON.stringify({
+      hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny",
+        permissionDecisionReason: "无法确定本次调用所在的对话，尚未查信或处理来信。" },
+    }) + "\n");
+    return false;
+  }).finally(() => { process.exitCode = 0; });
+}

package/integrations/workbuddy/server/origin-routes.mjs

@@ -0,0 +1,211 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { nativeReplyRouteLocation, rememberNativeReplyRoute } from "../../../clients/core/hellolynk-native-reply-routes.mjs";
+import { WORKBUDDY_ACTIVE_SCOPE_FILE, WORKBUDDY_ORIGIN_DIRECT_TOOL_MATCHER, WORKBUDDY_ORIGIN_TOOL_MATCHER, readWorkBuddyActiveScope } from "./origin-hook.mjs";
+
+const ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{2,198}$/;
+const THREAD = /^[A-Za-z0-9][A-Za-z0-9_.:-]{2,127}$/;
+const DROP = /^[a-f0-9]{64}\.json$/;
+const SCOPE = /^[a-f0-9]{64}$/;
+const TEMPORARY = /^[a-f0-9]{64}\.json\.\d+\.[a-f0-9]{12}\.tmp$/;
+const STATUS = /^[a-z][a-z0-9_]{0,79}$/;
+const hash = (value) => crypto.createHash("sha256").update(value).digest("hex");
+const failure = (code) => Object.assign(new Error(code), { code });
+
+export function workBuddyOriginInbox(storeRoot) {
+  if (typeof storeRoot !== "string" || !path.isAbsolute(storeRoot)) throw failure("workbuddy_origin_inbox_invalid");
+  return path.join(storeRoot, "workbuddy-origin-inbox");
+}
+
+// Tells the hook which account the MCP proxy or worker is connected to. Rewritten only
+// when the account changes; the hash names no person and holds no secret.
+export async function markWorkBuddyActiveScope(inbox, scope) {
+  const { scopeHash } = nativeReplyRouteLocation(scope);
+  if (await readWorkBuddyActiveScope(inbox) === scopeHash) return false;
+  await fs.mkdir(inbox, { recursive: true });
+  const file = path.join(inbox, WORKBUDDY_ACTIVE_SCOPE_FILE), temporary = `${file}.${crypto.randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temporary, JSON.stringify({ version: 1, scopeHash }), { flag: "wx", mode: 0o600 });
+    await fs.rename(temporary, file);
+  } finally { await fs.rm(temporary, { force: true }); }
+  return true;
+}
+
+// Moves hook records into the current account's reply-route store. Records
+// made under another account, invalid or conflicting records are dropped (the
+// first route wins); a temporary file error keeps the record for the next tick.
+export async function importWorkBuddyOriginDrops(inbox, scope, { remember = rememberNativeReplyRoute, now = Date.now, limit = 200 } = {}) {
+  const { scopeHash } = nativeReplyRouteLocation(scope);
+  let names;
+  try { names = await fs.readdir(inbox); }
+  catch (error) { if (error.code === "ENOENT") return 0; throw error; }
+  const drops = [];
+  for (const name of names) {
+    const file = path.join(inbox, name);
+    if (TEMPORARY.test(name)) {
+      // Left by an interrupted hook; a live hook renames within milliseconds.
+      const stat = await fs.lstat(file).catch(() => null);
+      if (stat && now() - stat.mtimeMs > 60 * 60 * 1000) await fs.rm(file, { force: true });
+    } else if (DROP.test(name) && drops.length < limit) {
+      // A file that cannot be read right now (busy, or removed meanwhile) waits for the next tick.
+      try { drops.push({ file, record: await readDrop(file) }); } catch {}
+    }
+  }
+  drops.sort((a, b) => (a.record?.createdAt ?? 0) - (b.record?.createdAt ?? 0) || a.file.localeCompare(b.file));
+  let imported = 0;
+  for (const { file, record } of drops) {
+    if (record?.scopeHash === scopeHash) {
+      try { await remember(scope, record); imported += 1; }
+      catch (error) { if (!["native_reply_route_conflict", "native_reply_route_invalid"].includes(error?.message)) continue; }
+    }
+    await fs.rm(file, { force: true });
+  }
+  return imported;
+}
+
+// null marks a file that is not a valid record, which is deleted. A file
+// error is thrown instead, so the caller keeps the file.
+async function readDrop(file) {
+  const stat = await fs.lstat(file);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4096) return null;
+  const text = await fs.readFile(file, "utf8");
+  let record;
+  try { record = JSON.parse(text); } catch { return null; }
+  const keys = Object.keys(record || {}).sort().join();
+  if (keys !== "clientMessageId,conversationKey,createdAt,peerDelegateId,scopeHash,threadId,version" || record.version !== 1
+    || !SCOPE.test(record.scopeHash || "") || !THREAD.test(record.threadId || "") || !ID.test(record.clientMessageId || "")
+    || !Number.isSafeInteger(record.createdAt) || (record.conversationKey === null) === (record.peerDelegateId === null)
+    || ![record.conversationKey, record.peerDelegateId].every((value) => value === null || ID.test(value))) return null;
+  return { scopeHash: record.scopeHash, threadId: record.threadId, clientMessageId: record.clientMessageId,
+    conversationKey: record.conversationKey, peerDelegateId: record.peerDelegateId, createdAt: record.createdAt };
+}
+
+// One file per reply delivered to an original conversation. It is written
+// before the desktop call, so a crash or unknown result is never repeated.
+export function createWorkBuddyOriginLedger(scope) {
+  const { scopeHash } = nativeReplyRouteLocation(scope);
+  const directory = path.join(path.resolve(scope.runtimeRoot), "native-origin-deliveries", scopeHash);
+  const file = (id) => { if (!ID.test(id || "")) throw failure("workbuddy_native_pending_invalid"); return path.join(directory, `${hash(id)}.json`); };
+  return Object.freeze({
+    async get(localMessageId) {
+      let text;
+      try { text = await fs.readFile(file(localMessageId), "utf8"); }
+      catch (error) { if (error.code === "ENOENT") return null; throw error; }
+      // An unreadable record still means a native write may have started.
+      try { return JSON.parse(text); } catch { return { status: "dispatch_unknown" }; }
+    },
+    async begin(localMessageId, threadId) {
+      const target = file(localMessageId);
+      await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+      let handle;
+      try {
+        handle = await fs.open(target, "wx", 0o600);
+        await handle.writeFile(JSON.stringify({ localMessageId, threadId, status: "dispatching" }));
+        await handle.sync();
+        return true;
+      } catch (error) { if (error.code === "EEXIST") return false; throw error; }
+      finally { await handle?.close(); }
+    },
+    async finish(localMessageId, threadId, status) {
+      if (!STATUS.test(status || "")) throw failure("workbuddy_native_dispatch_unavailable");
+      const target = file(localMessageId), temporary = `${target}.${crypto.randomUUID()}.tmp`;
+      try {
+        await fs.writeFile(temporary, JSON.stringify({ localMessageId, threadId, status }), { flag: "wx", mode: 0o600 });
+        await fs.rename(temporary, target);
+      } finally { await fs.rm(temporary, { force: true }); }
+    },
+    // Only for a record whose desktop call has not started.
+    async undo(localMessageId) { await fs.rm(file(localMessageId), { force: true }); },
+  });
+}
+
+export function workBuddySettingsPath(env = process.env) {
+  return path.join(env.WORKBUDDY_CONFIG_DIR || path.join(os.homedir(), ".workbuddy"), "settings.json");
+}
+
+// WorkBuddy runs a command whose program is powershell.exe directly, with or
+// without Git Bash. The hook inherits stdin, so the payload stays byte-exact;
+// piping it through PowerShell would re-encode non-ASCII text.
+export function workBuddyOriginHookCommand({ nodePath, hookPath, inbox,
+  powershellPath = path.join(process.env.SystemRoot || "C:\\Windows", "System32", "WindowsPowerShell", "v1.0", "powershell.exe") }) {
+  for (const value of [powershellPath, nodePath, hookPath, inbox]) {
+    if (typeof value !== "string" || !path.win32.isAbsolute(value) || /["\r\n\0`]|\$\{/.test(value)) throw failure("workbuddy_origin_hook_path_invalid");
+  }
+  const quote = (value) => `'${value.replace(/'/g, "''")}'`;
+  return `"${powershellPath}" -NoProfile -Command "$ErrorActionPreference='SilentlyContinue'; & ${quote(nodePath)} ${quote(hookPath)} --inbox ${quote(inbox)} 2>$null; exit 0"`;
+}
+
+// Called when the installed native-task service starts, so the hook always
+// runs this release's file. A failed registration never stops delivery;
+// replies to sends it missed stay in the HelloLynk inbox.
+export async function prepareWorkBuddyOriginHook({ storeRoot, settingsPath, nodePath = process.execPath,
+  hookPath = fileURLToPath(new URL("./origin-hook.mjs", import.meta.url)), platform = process.platform } = {}) {
+  const inbox = workBuddyOriginInbox(storeRoot);
+  let hook = { changed: false, status: "unsupported_platform" };
+  if (platform === "win32") {
+    try { hook = await ensureWorkBuddyOriginHook({ settingsPath, command: workBuddyOriginHookCommand({ nodePath, hookPath, inbox }) }); }
+    catch (error) { hook = { changed: false, status: "unavailable", errorCode: /^workbuddy_[a-z_]{1,80}$/.test(error?.code || "") ? error.code : "workbuddy_origin_hook_unavailable" }; }
+  }
+  return { inbox, hook };
+}
+
+// Adds or replaces the one HelloLynk entry; other hooks and settings stay as they are.
+export async function ensureWorkBuddyOriginHook({ command, settingsPath = workBuddySettingsPath() } = {}) {
+  if (typeof command !== "string" || !command.includes("origin-hook.mjs")) throw failure("workbuddy_origin_hook_command_invalid");
+  const ours = { matcher: WORKBUDDY_ORIGIN_TOOL_MATCHER, hooks: [{ type: "command", command, timeout: 30 }] };
+  return updatePreToolUse(settingsPath, (entries) => {
+    const index = entries.findIndex(isOriginHook);
+    return index < 0 ? [...entries, ours] : entries.flatMap((entry, at) => at === index ? [ours] : isOriginHook(entry) ? [] : [entry]);
+  });
+}
+
+export async function removeWorkBuddyOriginHook({ command, settingsPath = workBuddySettingsPath() } = {}) {
+  if (typeof command !== "string" || !command.includes("origin-hook.mjs")) throw failure("workbuddy_origin_hook_command_invalid");
+  // An old release or isolated task must not remove the active installation's hook.
+  return updatePreToolUse(settingsPath, (entries) => entries.flatMap((entry) => {
+    if (!isOriginHook(entry)) return [entry];
+    const hooks = entry.hooks.filter((hook) => hook.command !== command);
+    return hooks.length ? [{ ...entry, hooks }] : [];
+  }));
+}
+
+function isOriginHook(entry) {
+  // Recognize installed B248 matchers only to replace/remove their old hook.
+  const previous = '^mcp__hellolynk__(?:hellolynk_)?(send|reply)_authorized_message$';
+  return [WORKBUDDY_ORIGIN_DIRECT_TOOL_MATCHER, WORKBUDDY_ORIGIN_TOOL_MATCHER,
+    previous, `^(?:DeferExecuteTool|${previous.slice(1, -1)})$`].includes(entry?.matcher) && Array.isArray(entry.hooks)
+    && entry.hooks.some((hook) => typeof hook?.command === "string" && hook.command.includes("origin-hook.mjs"));
+}
+
+async function updatePreToolUse(settingsPath, change) {
+  let text;
+  // A missing file means WorkBuddy is not set up for this user; never create its directory.
+  try { text = await fs.readFile(settingsPath, "utf8"); }
+  catch (error) { if (error.code === "ENOENT") return { changed: false, status: "settings_missing" }; throw error; }
+  let settings;
+  try { settings = JSON.parse(text.replace(/^\uFEFF/, "")); } catch { throw failure("workbuddy_settings_invalid"); }
+  const hooks = settings?.hooks ?? {};
+  const entries = hooks?.PreToolUse ?? [];
+  if (!plain(settings) || !plain(hooks) || !Array.isArray(entries)) throw failure("workbuddy_settings_invalid");
+  const next = change(entries);
+  if (JSON.stringify(next) === JSON.stringify(entries)) return { changed: false, status: "unchanged" };
+  const nextHooks = { ...hooks, PreToolUse: next };
+  if (!next.length) delete nextHooks.PreToolUse;
+  const nextSettings = { ...settings, hooks: nextHooks };
+  if (!Object.keys(nextHooks).length) delete nextSettings.hooks;
+  const temporary = `${settingsPath}.${crypto.randomUUID()}.tmp`;
+  try {
+    // Same layout as WorkBuddy's own settings writes.
+    await fs.writeFile(temporary, JSON.stringify(nextSettings, null, 2), { flag: "wx" });
+    // Replace only the version read above. If the person or WorkBuddy changed
+    // it meanwhile, keep theirs; the next service start registers again.
+    if (await fs.readFile(settingsPath, "utf8").catch(() => null) !== text) return { changed: false, status: "settings_changed" };
+    await fs.rename(temporary, settingsPath);
+  } finally { await fs.rm(temporary, { force: true }); }
+  return { changed: true, status: "updated" };
+}
+
+function plain(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value); }

package/integrations/workbuddy/server/package-bootstrap.mjs

@@ -0,0 +1,111 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const ENTRY = "integrations/workbuddy/server/mcp-proxy.mjs";
+const REQUIRED = new Set([
+  ENTRY,
+  "integrations/workbuddy/package.json",
+  "integrations/workbuddy/server/mcp-server.mjs",
+  "integrations/workbuddy/server/neutral-host-adapter.mjs",
+  "integrations/workbuddy/server/workbench-candidate.mjs",
+  "integrations/workbuddy/server/workbench-process.mjs",
+  "integrations/workbuddy/server/workbench-task.ps1",
+  "integrations/workbuddy/server/workbench-hidden-launcher.vbs",
+  "clients/core/hellolynk-runtime-safety.cjs",
+  "integrations/workbuddy/server/package-bootstrap.mjs",
+  "integrations/workbuddy/skills/hellolynk-inbox/SKILL.md",
+  "integrations/workbuddy/skills/hellolynk-inbox/workbuddy.json",
+  "clients/core/hellolynk-local-data-migration.mjs",
+  "clients/core/hellolynk-local-data-protection.mjs",
+  "clients/core/hellolynk-local-identity-trust.mjs",
+  "clients/core/hellolynk-neutral-host-workbench-read-model.mjs",
+  "clients/workbench/contract.mjs",
+  "clients/platform/windows/credential-store.ps1",
+  "clients/platform/windows/hellolynk-host-protected-store.ps1",
+  "clients/platform/windows/hellolynk-local-data-key.ps1",
+  "clients/platform/windows/hellolynk-human-confirmation-ledger.ps1",
+  "clients/platform/windows/hellolynk-native-human-confirmation-broker.ps1",
+  "runtime/neutral-host-bootstrap.mjs",
+  "runtime/neutral-host-release-loader.mjs",
+  "runtime/neutral-host-release-entry.mjs",
+  "runtime/neutral-host-release-manifest.json",
+  "runtime/neutral-host-release-pin.json",
+  "runtime/core/hellolynk-host-protected-store.mjs",
+  "runtime/core/hellolynk-local-data-migration.mjs",
+  "runtime/core/hellolynk-local-data-protection.mjs",
+  "runtime/core/hellolynk-local-identity-trust.mjs",
+  "runtime/core/hellolynk-neutral-host-assembly.mjs",
+  "runtime/core/hellolynk-neutral-host-workbench-read-model.mjs",
+  "runtime/core/hellolynk-workbench-action-grants.mjs",
+  "runtime/workbench/contract.mjs",
+  "runtime/workbench/candidate-bootstrap.mjs",
+  "runtime/platform/windows/hellolynk-local-data-key.ps1",
+]);
+export async function loadPinnedWorkBuddyProxy(options={}) {
+  const root=absolute(options.root), expected=hash(options.expectedManifestSha256);
+  const [mb,pb]=await Promise.all([safeRead(root,"workbuddy-package-manifest.json"),safeRead(root,"workbuddy-package-pin.json")]);
+  if(sha(mb)!==expected)throw code("workbuddy_package_manifest_mismatch"); const manifest=parse(mb),pin=parse(pb);
+  if(!plain(pin)||!exact(pin,["contract","manifestSha256"])||pin.contract!=="hellolynk-workbuddy-immutable-package-pin-v1"||pin.manifestSha256!==expected)throw code("workbuddy_package_pin_invalid");
+  if(!plain(manifest)||!exact(manifest,["contract","entry","files"])||manifest.contract!=="hellolynk-workbuddy-immutable-package-v1"||manifest.entry!==ENTRY||!Array.isArray(manifest.files))throw code("workbuddy_package_manifest_invalid");
+  const required=new Set(REQUIRED),seen=new Set(); for(const record of manifest.files){if(!plain(record)||!exact(record,["path","sha256"])||!safeRelative(record.path)||!/^[a-f0-9]{64}$/.test(String(record.sha256||""))||seen.has(record.path))throw code("workbuddy_package_manifest_invalid");seen.add(record.path);required.delete(record.path);if(sha(await safeRead(root,record.path))!==record.sha256)throw code("workbuddy_package_file_integrity_invalid");}
+  if(required.size)throw code("workbuddy_package_closure_incomplete"); return import(pathToFileURL(path.join(root,...ENTRY.split("/"))).href);
+}
+export async function runWorkBuddyPackageBootstrap(args = process.argv.slice(2)) {
+  if (!["run", "--wait-for-pending", "handoff-workbench", "workbench", "workbench-service", "native-task-service"].includes(args[0])
+    || args.length !== 5 || args[1] !== "--root" || args[3] !== "--expected-manifest-sha256") {
+    throw code("workbuddy_package_arguments_invalid");
+  }
+  const options = { root: args[2], expectedManifestSha256: args[4] };
+  // Every entry, including the detached page, verifies the immutable closure
+  // before importing adapter or UI code.
+  const proxy = await loadPinnedWorkBuddyProxy(options);
+  if (args[0] === "--wait-for-pending") {
+    const stop = new AbortController();
+    const terminate = () => stop.abort();
+    process.once("SIGTERM", terminate);
+    process.once("SIGINT", terminate);
+    try { await proxy.waitForWorkBuddyPending({ signal: stop.signal }); }
+    finally { process.off("SIGTERM", terminate); process.off("SIGINT", terminate); }
+  } else if (args[0] === "run") {
+    await proxy.runWorkBuddyMcpProxy({ openLocalWeb: () => proxy.launchDetachedWorkBuddyWorkbench(options) });
+  } else if (args[0] === "handoff-workbench") {
+    process.stdout.write(`${JSON.stringify(await proxy.handoffWorkBuddyWorkbench(options))}\n`);
+  } else if (["workbench-service", "native-task-service"].includes(args[0])) {
+    const stop = new AbortController();
+    const terminate = () => stop.abort();
+    process.once("SIGTERM", terminate);
+    process.once("SIGINT", terminate);
+    try {
+      if (args[0] === "native-task-service") await proxy.runWorkBuddyNativeTaskService({ ...options, originHook: true, signal: stop.signal });
+      else await proxy.runWorkBuddyWorkbenchService({ ...options, signal: stop.signal });
+    }
+    finally { process.off("SIGTERM", terminate); process.off("SIGINT", terminate); }
+  } else {
+    const stop = new AbortController();
+    const terminate = () => stop.abort();
+    process.once("SIGTERM", terminate);
+    process.once("SIGINT", terminate);
+    // A launch abandoned before readiness must not leave an idle worker.
+    const deadline = setTimeout(() => process.exit(1), 90_000);
+    deadline.unref();
+    try {
+      await proxy.runWorkBuddyWorkbenchProcess({
+        signal: stop.signal,
+        publishReady: (value) => new Promise((resolve, reject) => {
+          if (!process.connected) return reject(code("workbuddy_local_web_launch_handoff_missing"));
+          process.send(value, (error) => {
+            if (error) reject(error);
+            else { clearTimeout(deadline); resolve(); }
+          });
+        }),
+      });
+    } finally {
+      clearTimeout(deadline);
+      process.off("SIGTERM", terminate);
+      process.off("SIGINT", terminate);
+    }
+  }
+}
+function absolute(v){const r=String(v||"");if(!path.isAbsolute(r)||path.resolve(r)!==r)throw code("workbuddy_package_root_required");return r}function hash(v){const r=String(v||"");if(!/^[a-f0-9]{64}$/.test(r))throw code("workbuddy_package_expected_manifest_required");return r}function safeRelative(v){return typeof v==="string"&&/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(v)&&!v.includes("..")&&!v.startsWith("/")}async function safeRead(root,relative){const f=path.resolve(root,...relative.split("/"));if(!f.startsWith(`${root}${path.sep}`))throw code("workbuddy_package_path_invalid");try{const s=await fs.lstat(f);if(!s.isFile()||s.isSymbolicLink()||s.size>4*1024*1024)throw 0;return await fs.readFile(f)}catch{throw code("workbuddy_package_file_unavailable")}}function parse(v){try{return JSON.parse(v)}catch{throw code("workbuddy_package_manifest_invalid")}}function exact(v,k){const a=Object.keys(v).sort(),b=[...k].sort();return a.length===b.length&&a.every((x,i)=>x===b[i])}function sha(v){return crypto.createHash("sha256").update(v).digest("hex")}function plain(v){return Boolean(v)&&typeof v==="object"&&!Array.isArray(v)}function code(v){const e=new Error(v);e.code=v;return e}
+if(process.argv[1]&&path.resolve(process.argv[1])===fileURLToPath(import.meta.url))runWorkBuddyPackageBootstrap().catch(e=>{process.stderr.write(`${JSON.stringify({ok:false,error:/^(?:workbuddy|neutral|host)_[a-z0-9_]{1,100}$/.test(e?.code||"")?e.code:"workbuddy_package_failed"})}\n`);process.exitCode=1});

package/integrations/workbuddy/server/workbench-candidate.mjs

@@ -0,0 +1,202 @@
+import { createWorkbenchAccountOpener, createWorkbenchConnection, workbenchConnectionError, isWorkbenchConnectionRequired } from "../../../clients/core/hellolynk-workbench-connection.mjs";
+import path from "node:path";
+import { lstat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+let active = null;
+const PACKAGED_WORKBENCH = new URL("../../../runtime/workbench/candidate-bootstrap.mjs", import.meta.url);
+const SOURCE_WORKBENCH = new URL("../../../clients/workbench/candidate-bootstrap.mjs", import.meta.url);
+const ACTION_GRANT = /^[A-Za-z0-9._~-]{32,512}$/;
+
+export async function bootstrapWorkBuddyWorkbenchCandidate(options = {}) {
+  const sharedWorkbench = options.bootstrapWorkbenchCandidate
+    ? injectedSharedWorkbench(options)
+    : await loadSharedWorkbench();
+  const {
+    bootstrapWorkbenchCandidate: _ignored,
+    workbenchContract: _ignoredContract,
+    adapter,
+    ...candidateOptions
+  } = options;
+  requireReadAdapter(adapter);
+  if (typeof adapter.start === "function") await adapter.start().catch((error) => { if (!isWorkbenchConnectionRequired(error)) throw error; });
+  return sharedWorkbench.bootstrapWorkbenchCandidate("workbuddy", {
+    openAccount: options.openAccount || createWorkbenchAccountOpener(),
+    connectAccount: options.connectAccount || createWorkbenchConnection({ client: "workbuddy", releaseRoot: path.resolve(fileURLToPath(new URL("../../../", import.meta.url))) }),
+    ...candidateOptions,
+    adapter: createWorkBuddyWorkbenchAdapterFacade(adapter, sharedWorkbench.contract),
+  });
+}
+
+export async function launchWorkBuddyWorkbench(options = {}) {
+  const adapter = options.adapter;
+  requireReadAdapter(adapter);
+  if (typeof adapter.start === "function") await adapter.start().catch((error) => { if (!isWorkbenchConnectionRequired(error)) throw error; });
+  if (active && active.adapter === adapter) {
+    active.candidate.surface.armNavigation();
+    return active.result;
+  }
+  if (active) await closeWorkBuddyWorkbench();
+  const sharedWorkbench = options.bootstrapWorkbenchCandidate
+    ? injectedSharedWorkbench(options)
+    : await loadSharedWorkbench();
+  const workbenchAdapter = createWorkBuddyWorkbenchAdapterFacade(adapter, sharedWorkbench.contract);
+  const candidate = await sharedWorkbench.bootstrapWorkbenchCandidate("workbuddy", {
+    openAccount: options.openAccount || createWorkbenchAccountOpener(),
+    connectAccount: options.connectAccount || createWorkbenchConnection({ client: "workbuddy", releaseRoot: path.resolve(fileURLToPath(new URL("../../../", import.meta.url))) }),
+    adapter: workbenchAdapter,
+    ...(options.port == null ? {} : { port: options.port }),
+    pagePath: "/inbox",
+  });
+  const result = Object.freeze({
+    ok: true,
+    host: candidate.surface,
+    cleanUrl: candidate.cleanUrl,
+    status: "ready_for_browser_navigation",
+  });
+  active = { adapter, candidate, result };
+  return result;
+}
+
+export async function closeWorkBuddyWorkbench() {
+  if (!active) return;
+  const current = active;
+  active = null;
+  await current.candidate.close();
+}
+
+export function createWorkBuddyWorkbenchAdapterFacade(adapter, contract) {
+  requireReadAdapter(adapter);
+  const facade = {
+    readSnapshot: (input) => Promise.resolve().then(() => adapter.readWorkbenchSnapshot(input)).catch((error) => { throw workbenchConnectionError(error); }),
+  };
+  if (typeof adapter.readWorkbenchChanges === "function") {
+    facade.readChanges = (input) => adapter.readWorkbenchChanges(input);
+  }
+  if (supportsF3Contract(contract) && hasHostActionGrantPair(adapter)) {
+    const issueWorkbenchActionGrant = adapter.issueWorkbenchActionGrant.bind(adapter);
+    const executeWorkbenchCommand = adapter.executeWorkbenchCommand.bind(adapter);
+    facade.issueActionGrant = async (command) => requireIssuedActionGrant(
+      await issueWorkbenchActionGrant(contract.validateWorkbenchCommand(command)),
+      "workbuddy_workbench_action_grant_invalid",
+    );
+    facade.executeCommand = async (command, context) => {
+      const validated = contract.validateWorkbenchCommand(command);
+      const normalizedContext = validated.command === "message.send-status"
+        ? requireEmptyContext(context, "workbuddy_workbench_action_grant_invalid")
+        : requireActionGrantContext(context, "workbuddy_workbench_action_grant_required");
+      return contract.validateWorkbenchCommandResult(
+        await executeWorkbenchCommand(validated, normalizedContext),
+        validated.command,
+      );
+    };
+  }
+  return Object.freeze(facade);
+}
+
+async function loadSharedWorkbench() {
+  const moduleUrl = await selectWorkbenchModule();
+  let loaded;
+  let contract;
+  try {
+    [loaded, contract] = await Promise.all([
+      import(moduleUrl.href),
+      import(new URL("./contract.mjs", moduleUrl).href),
+    ]);
+  } catch {
+    throw codeError("workbuddy_shared_workbench_unavailable");
+  }
+  if (typeof loaded.bootstrapWorkbenchCandidate !== "function") {
+    throw codeError("workbuddy_shared_workbench_unavailable");
+  }
+  return Object.freeze({ bootstrapWorkbenchCandidate: loaded.bootstrapWorkbenchCandidate, contract });
+}
+
+function injectedSharedWorkbench(options) {
+  if (typeof options.bootstrapWorkbenchCandidate !== "function") {
+    throw codeError("workbuddy_shared_workbench_unavailable");
+  }
+  return Object.freeze({
+    bootstrapWorkbenchCandidate: options.bootstrapWorkbenchCandidate,
+    contract: options.workbenchContract || null,
+  });
+}
+
+async function selectWorkbenchModule() {
+  const packaged = await regularFile(PACKAGED_WORKBENCH);
+  if (packaged) return PACKAGED_WORKBENCH;
+  if (await regularFile(SOURCE_WORKBENCH)) return SOURCE_WORKBENCH;
+  throw codeError("workbuddy_shared_workbench_unavailable");
+}
+
+async function regularFile(url) {
+  try {
+    const metadata = await lstat(fileURLToPath(url));
+    if (metadata.isSymbolicLink() || !metadata.isFile()) {
+      throw codeError("workbuddy_shared_workbench_unavailable");
+    }
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function requireReadAdapter(adapter) {
+  if (!adapter || typeof adapter.readWorkbenchSnapshot !== "function") {
+    throw codeError("workbuddy_shared_workbench_adapter_required");
+  }
+}
+
+function supportsF3Contract(value) {
+  return Boolean(value)
+    && value.HELLOLYNK_WORKBENCH_SNAPSHOT_CONTRACT === "hellolynk-workbench-snapshot-v12"
+    && value.HELLOLYNK_WORKBENCH_SNAPSHOT_SCHEMA_VERSION === 12
+    && value.HELLOLYNK_WORKBENCH_COMMAND_CONTRACT === "hellolynk-workbench-command-v6"
+    && value.HELLOLYNK_WORKBENCH_RESULT_CONTRACT === "hellolynk-workbench-command-result-v6"
+    && value.HELLOLYNK_WORKBENCH_SCHEMA_VERSION === 6
+    && typeof value.validateWorkbenchCommand === "function"
+    && typeof value.validateWorkbenchCommandResult === "function";
+}
+
+function hasHostActionGrantPair(adapter) {
+  return typeof adapter.issueWorkbenchActionGrant === "function"
+    && adapter.issueWorkbenchActionGrant.length >= 1
+    && typeof adapter.executeWorkbenchCommand === "function"
+    && adapter.executeWorkbenchCommand.length >= 2;
+}
+
+function requireActionGrantContext(value, errorCode) {
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+    || Object.keys(value).length !== 1 || !Object.hasOwn(value, "actionGrant")
+    || typeof value.actionGrant !== "string" || !ACTION_GRANT.test(value.actionGrant)) {
+    throw codeError(errorCode);
+  }
+  return value;
+}
+
+function requireEmptyContext(value, errorCode) {
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+    || Object.keys(value).length !== 0) {
+    throw codeError(errorCode);
+  }
+  return value;
+}
+
+function requireIssuedActionGrant(value, errorCode) {
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+    || Object.keys(value).length !== 1 || !Object.hasOwn(value, "actionGrant")
+    || typeof value.actionGrant !== "string" || !ACTION_GRANT.test(value.actionGrant)) {
+    throw codeError(errorCode);
+  }
+  return value;
+}
+
+function codeError(code) {
+  const error = new Error(code);
+  error.code = code;
+  return error;
+}