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

package/integrations/workbuddy/server/native-task-debug-startup.mjs

@@ -0,0 +1,117 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import { withHelloLynkLocalMutationLock } from "../../../clients/core/hellolynk-local-messaging.mjs";
+
+const exec = promisify(execFile);
+const failure = code => Object.assign(new Error(code), { code });
+
+// Transfer only our existing restore receipt. Never recreate or change the
+// user's environment variable during a normal package update.
+export async function transferWorkBuddyDebugStartupOwner({ storeRoot, previousInstallationId, installationId }) {
+  if (!path.isAbsolute(storeRoot || "") || ![previousInstallationId, installationId].every(value => /^[a-f0-9]{64}$/.test(value || ""))) throw failure("workbuddy_native_debug_startup_invalid");
+  await assertSafeParents(storeRoot);
+  const filename = path.join(storeRoot, "workbuddy-native-debug-startup.json");
+  return withHelloLynkLocalMutationLock(filename, async () => {
+    const state = await readState(filename);
+    if (!state) return;
+    if (state.phase !== "applied") throw failure("workbuddy_native_debug_startup_outcome_uncertain");
+    if (state.owner === installationId) return;
+    if (state.owner !== previousInstallationId) throw failure("workbuddy_native_debug_startup_conflict");
+    await writeState(filename, { ...state, owner: installationId });
+  });
+}
+
+// The vendor reads this user environment variable on normal cold startup.
+// No shortcut, vendor file, current window or login trigger is changed.
+export async function configureWorkBuddyDebugStartup({ storeRoot, debugEndpoint, installationId, enableDebugStartup = false, environment = windowsEnvironment } = {}, operation = "Install") {
+  if (!["Install", "Uninstall"].includes(operation)) return { status: "unchanged" };
+  if (operation === "Install" && enableDebugStartup !== true) return { status: "not_selected" };
+  const endpoint = new URL(debugEndpoint || "http://127.0.0.1:9337");
+  if (endpoint.protocol !== "http:" || endpoint.hostname !== "127.0.0.1" || !endpoint.port || endpoint.pathname !== "/" || endpoint.search || endpoint.hash || endpoint.username || endpoint.password || !path.isAbsolute(storeRoot || "") || !/^[a-f0-9]{64}$/.test(installationId || "")) throw failure("workbuddy_native_debug_startup_invalid");
+  const filename = path.join(storeRoot, "workbuddy-native-debug-startup.json");
+  await assertSafeParents(storeRoot);
+  return withHelloLynkLocalMutationLock(filename, async () => {
+    const state = await readState(filename);
+    if (operation === "Uninstall" && (!state || state.owner !== installationId)) return { status: "not_owned" };
+    const current = await environment.read();
+    if (operation === "Install") {
+      // First installation reuses a user-selected local port. Explicit callers
+      // still require their requested endpoint and never silently switch it.
+      if (!debugEndpoint && current !== null) {
+        if (!/^[1-9]\d{0,4}$/.test(current) || Number(current) > 65535) throw failure("workbuddy_native_debug_startup_conflict");
+        endpoint.port = current;
+        if (!endpoint.port) throw failure("workbuddy_native_debug_startup_conflict");
+      }
+      if (state && state.applied !== endpoint.port || current !== null && current !== endpoint.port) throw failure("workbuddy_native_debug_startup_conflict");
+      if (current === endpoint.port) {
+        if (state?.phase === "preparing") throw failure("workbuddy_native_debug_startup_outcome_uncertain");
+        // The replacement release takes over the existing original-value record.
+        if (state && state.owner !== installationId) await writeState(filename, { ...state, owner: installationId });
+        return { status: state ? "enabled" : "already_configured", debugEndpoint: endpoint.origin, coldStartRequired: true };
+      }
+      const next = { version: 1, variable: "WORKBUDDY_REMOTE_DEBUGGING_PORT", previous: null, applied: endpoint.port, owner: installationId, phase: "preparing" };
+      await writeState(filename, next);
+      const result = await environment.compareExchange(null, endpoint.port);
+      if (!result.exchanged) {
+        await fs.rm(filename);
+        throw failure("workbuddy_native_debug_startup_conflict");
+      }
+      await writeState(filename, { ...next, phase: "applied" });
+      return { status: "enabled", debugEndpoint: endpoint.origin, coldStartRequired: true, broadcastDelivered: result.broadcastDelivered };
+    }
+    if (state.phase !== "applied") return { status: "unconfirmed_not_restored" };
+    if (current !== state.applied) {
+      await fs.rm(filename);
+      return { status: "preserved_user_change" };
+    }
+    const result = await environment.compareExchange(state.applied, state.previous);
+    await fs.rm(filename);
+    return { status: result.exchanged ? "restored" : "preserved_user_change", broadcastDelivered: result.broadcastDelivered };
+  });
+}
+
+const windowsEnvironment = {
+  async read() { return (await callWindows("Read")).value; },
+  async compareExchange(expected, value) { return callWindows("CompareExchange", expected, value); },
+};
+async function callWindows(operation, expected, value) {
+  if (process.platform !== "win32") throw failure("workbuddy_native_debug_startup_windows_required");
+  try {
+    const args = ["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File",
+      fileURLToPath(new URL("./native-task-debug-startup.ps1", import.meta.url)), "-Operation", operation];
+    if (operation === "CompareExchange") args.push("-Expected", expected ?? "absent", "-Value", value ?? "absent");
+    const { stdout } = await exec("powershell.exe", args, { windowsHide: true, timeout: 15_000, maxBuffer: 4096 });
+    const result = JSON.parse(stdout);
+    if (result?.ok !== true || operation === "Read" && result.value !== null && typeof result.value !== "string" || operation === "CompareExchange" && typeof result.exchanged !== "boolean") throw failure("workbuddy_native_debug_startup_failed");
+    return result;
+  } catch { throw failure("workbuddy_native_debug_startup_failed"); }
+}
+async function assertSafeParents(target) {
+  const root = path.parse(path.resolve(target)).root;
+  let current = root;
+  for (const part of path.relative(root, path.resolve(target)).split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    const stat = await fs.lstat(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw failure("workbuddy_native_debug_startup_state_invalid");
+  }
+}
+async function readState(filename) {
+  try {
+    const stat = await fs.lstat(filename);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 2048) throw failure("workbuddy_native_debug_startup_state_invalid");
+    const state = JSON.parse(await fs.readFile(filename, "utf8"));
+    if (state?.version !== 1 || state.variable !== "WORKBUDDY_REMOTE_DEBUGGING_PORT" || state.previous !== null || !/^[a-f0-9]{64}$/.test(state.owner || "") || !["preparing", "applied"].includes(state.phase) || !/^\d{1,5}$/.test(state.applied) || Number(state.applied) < 1 || Number(state.applied) > 65535) throw failure("workbuddy_native_debug_startup_state_invalid");
+    return state;
+  } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+}
+async function writeState(filename, state) {
+  const temporary = `${filename}.${crypto.randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temporary, JSON.stringify(state), { flag: "wx", mode: 0o600 });
+    await fs.rename(temporary, filename);
+  } finally { await fs.rm(temporary, { force: true }); }
+}

package/integrations/workbuddy/server/native-task-debug-startup.ps1

@@ -0,0 +1,40 @@
+param(
+  [Parameter(Mandatory=$true)][ValidateSet('Read','CompareExchange')][string]$Operation,
+  [ValidatePattern('^(absent|[0-9]{1,5})$')][string]$Expected = 'absent',
+  [ValidatePattern('^(absent|[0-9]{1,5})$')][string]$Value = 'absent'
+)
+$ErrorActionPreference = 'Stop'
+try {
+  $variable = 'WORKBUDDY_REMOTE_DEBUGGING_PORT'
+  $current = [Environment]::GetEnvironmentVariable($variable, 'User')
+  if ($Operation -eq 'Read') {
+    [pscustomobject]@{ok=$true;value=$current} | ConvertTo-Json -Compress
+    exit 0
+  }
+  $expectedValue = $null
+  if ($Expected -ne 'absent') { $expectedValue = $Expected }
+  if ($current -cne $expectedValue) {
+    [pscustomobject]@{ok=$true;exchanged=$false} | ConvertTo-Json -Compress
+    exit 0
+  }
+  $nextValue = $null
+  if ($Value -ne 'absent') {
+    if ([int]$Value -lt 1 -or [int]$Value -gt 65535) { throw 'invalid_port' }
+    $nextValue = $Value
+  }
+  [Environment]::SetEnvironmentVariable($variable, $nextValue, 'User')
+  Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+public static class HelloLynkWorkBuddyEnvironmentBroadcast {
+  [DllImport("user32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+  public static extern IntPtr SendMessageTimeout(IntPtr window, uint message, IntPtr wParam, string lParam, uint flags, uint timeout, out UIntPtr result);
+}
+'@
+  $result = [UIntPtr]::Zero
+  $delivered = [HelloLynkWorkBuddyEnvironmentBroadcast]::SendMessageTimeout([IntPtr]0xffff, 0x001a, [IntPtr]::Zero, 'Environment', 2, 3000, [ref]$result) -ne [IntPtr]::Zero
+  [pscustomobject]@{ok=$true;exchanged=$true;broadcastDelivered=$delivered} | ConvertTo-Json -Compress
+} catch {
+  [Console]::Error.WriteLine('workbuddy_native_debug_startup_failed')
+  exit 1
+}

package/integrations/workbuddy/server/native-task-mcp-registration.mjs

@@ -0,0 +1,30 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import { loadPinnedWorkBuddyProxy } from "./package-bootstrap.mjs";
+import { createWorkBuddyNativeTaskClient } from "./native-task-cdp.mjs";
+
+// Call during explicit HelloLynk installation/repair, after writing mcp.json.
+// Normal WorkBuddy UI approval is configuration-hash-specific and therefore
+// must be repeated for an installed package update that changes its command.
+export async function registerWorkBuddyNativeMcp({ debugEndpoint, command, releaseRoot, expectedManifestSha256, storeRoot } = {}) {
+  const expected = workBuddyMcpExpectedConfig({ command, releaseRoot, expectedManifestSha256, storeRoot });
+  const stat = await fs.lstat(expected.command);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw failure("workbuddy_native_mcp_node_invalid");
+  await loadPinnedWorkBuddyProxy({ root: expected.args[3], expectedManifestSha256 });
+  const result = await createWorkBuddyNativeTaskClient({ debugEndpoint }).approveHelloLynkMcp(expected);
+  // Approved, but WorkBuddy may still be starting the server; the native
+  // service connects it on its next check.
+  if (result.trusted && result.enabled && result.status !== "ready") return result;
+  const toolNames = new Set((result.tools || []).filter(tool=>tool.enabled).map(tool=>tool.name));
+  if (!result.trusted || !result.enabled || result.status !== "ready" || !["hellolynk_claim_message", "hellolynk_send_authorized_message", "hellolynk_reply_authorized_message"].every(name=>toolNames.has(name))) throw failure("workbuddy_native_mcp_registration_failed");
+  return result;
+}
+
+// The exact mcp.json entry an installer writes for this release. Paths are
+// canonical, so a differently spelled path does not fail the exact match.
+export function workBuddyMcpExpectedConfig({ command, releaseRoot, expectedManifestSha256, storeRoot } = {}) {
+  if (![command, releaseRoot, storeRoot].every(v=>typeof v==='string'&&path.isAbsolute(v)) || !/^node(?:\.exe)?$/i.test(path.basename(command)) || !/^[a-f0-9]{64}$/.test(expectedManifestSha256 || "")) throw failure("workbuddy_native_mcp_installation_invalid");
+  const root = path.resolve(releaseRoot);
+  return { command: path.resolve(command), args: [path.join(root, "integrations", "workbuddy", "server", "package-bootstrap.mjs"), "run", "--root", root, "--expected-manifest-sha256", expectedManifestSha256], storeRoot: path.resolve(storeRoot) };
+}
+function failure(code) { return Object.assign(new Error(code), { code }); }

package/integrations/workbuddy/server/native-task-service-registration.mjs

@@ -0,0 +1,115 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import { withHelloLynkLocalMutationLock } from "../../../clients/core/hellolynk-local-messaging.mjs";
+import { defaultNeutralHostStoreRoot } from "../../../clients/core/hellolynk-neutral-host-installation-store.mjs";
+import { loadPinnedWorkBuddyProxy } from "./package-bootstrap.mjs";
+import { workBuddyMcpExpectedConfig } from "./native-task-mcp-registration.mjs";
+
+const failure = code => Object.assign(new Error(code), { code });
+const sameRelease = (left, right) => left.root.toLowerCase() === path.resolve(right.root).toLowerCase() && left.expectedManifestSha256 === right.expectedManifestSha256;
+
+// This record only identifies an explicitly installed, on-demand native task.
+// The same short lock covers record changes and Verify/Start, so Uninstall can
+// withdraw the record before stopping the task without a late MCP restarting it.
+export async function withWorkBuddyNativeServiceRecord(storeRoot, operation) {
+  const configured = storeRoot || defaultNeutralHostStoreRoot();
+  if (!path.isAbsolute(configured)) throw failure("workbuddy_native_service_record_invalid");
+  const directory = path.resolve(configured);
+  const filename = path.join(directory, "workbuddy-native-service.json");
+  try { await safeParents(directory); }
+  catch (error) { if (error.code === "ENOENT") return operation(null); throw error; }
+  const write = async record => {
+    const temporary = `${filename}.${crypto.randomUUID()}.tmp`;
+    try {
+      await fs.writeFile(temporary, JSON.stringify(record), { flag: "wx", mode: 0o600 });
+      await fs.rename(temporary, filename);
+    } finally { await fs.rm(temporary, { force: true }); }
+  };
+  return withHelloLynkLocalMutationLock(filename, async () => operation({
+    async read() {
+      try {
+        const stat = await fs.lstat(filename);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 8192) throw failure("workbuddy_native_service_record_invalid");
+        const record = JSON.parse(await fs.readFile(filename, "utf8"));
+        validate(record);
+        return record;
+      } catch (error) { if (error.code === "ENOENT") return null; throw error; }
+    },
+    async save(options, taskName) {
+      const record = { version: 1, root: path.resolve(options.root), expectedManifestSha256: options.expectedManifestSha256,
+        nodePath: options.nodePath || process.execPath, debugEndpoint: new URL(options.debugEndpoint).origin, taskName,
+        ...(options.pendingMcpTrust ? { pendingMcpTrust: { command: options.pendingMcpTrust.command } } : {}) };
+      validate(record);
+      await safeParents(record.root);
+      await loadPinnedWorkBuddyProxy(record);
+      await write(record);
+    },
+    // Same release and task; only the trust request is dropped.
+    async clearMcpTrustRequest(record) {
+      const { pendingMcpTrust, ...kept } = record;
+      validate(kept);
+      await write(kept);
+    },
+    async removeOwned(options) {
+      const record = await this.read();
+      if (record && sameRelease(record, options)) await fs.rm(filename);
+    },
+    storeRoot: directory,
+  }));
+}
+
+export async function startRecordedWorkBuddyNativeService({ storeRoot, loadProxy = loadPinnedWorkBuddyProxy } = {}) {
+  return withWorkBuddyNativeServiceRecord(storeRoot, async registry => {
+    const record = await registry?.read();
+    if (!record) return { configured: false, status: "not_installed" };
+    await safeParents(record.root);
+    const node = await fs.lstat(record.nodePath);
+    if (!node.isFile() || node.isSymbolicLink()) throw failure("workbuddy_native_service_record_invalid");
+    const proxy = await loadProxy(record);
+    if (typeof proxy.configureWorkBuddyNativeTaskService !== "function") throw failure("workbuddy_native_service_entry_unavailable");
+    const options = { ...record, storeRoot: registry.storeRoot };
+    const verified = await proxy.configureWorkBuddyNativeTaskService(options, "Verify");
+    if (verified?.ok !== true || verified.taskName !== record.taskName) throw failure("workbuddy_native_service_record_mismatch");
+    const started = await proxy.configureWorkBuddyNativeTaskService(options, "Start");
+    if (started?.ok !== true || started.taskName !== record.taskName) throw failure("workbuddy_native_service_record_mismatch");
+    // This is a Scheduler handoff, never a child process owned by the MCP Job.
+    return { configured: true, status: "service_started" };
+  });
+}
+
+// A package update changes the MCP command, so WorkBuddy asks for trust
+// again. The update leaves one request in the record; the service of that
+// same release approves exactly that configuration once, then clears it.
+// Approval runs outside the lock: connecting starts an MCP that takes it.
+export function workBuddyMcpTrustRequests(release) {
+  const pending = (record) => record?.pendingMcpTrust && sameRelease(record, release) ? record : null;
+  return Object.freeze({
+    take: () => withWorkBuddyNativeServiceRecord(release.storeRoot, async registry => {
+      const record = pending(await registry?.read());
+      return record && workBuddyMcpExpectedConfig({ command: record.pendingMcpTrust.command, releaseRoot: record.root,
+        expectedManifestSha256: record.expectedManifestSha256, storeRoot: registry.storeRoot });
+    }),
+    settle: () => withWorkBuddyNativeServiceRecord(release.storeRoot, async registry => {
+      const record = pending(await registry?.read());
+      if (record) await registry.clearMcpTrustRequest(record);
+    }),
+  });
+}
+
+function validate(record) {
+  const trust = record?.pendingMcpTrust;
+  if (trust !== undefined && (!trust || typeof trust !== "object" || Object.keys(trust).join() !== "command" || !path.isAbsolute(trust.command || "") || !/^node(?:\.exe)?$/i.test(path.basename(trust.command)))) throw failure("workbuddy_native_service_record_invalid");
+  if (record?.version !== 1|| !path.isAbsolute(record.root || "") || path.resolve(record.root) !== record.root || !/^[a-f0-9]{64}$/.test(record.expectedManifestSha256 || "") || !path.isAbsolute(record.nodePath || "") || !/^node(?:\.exe)?$/i.test(path.basename(record.nodePath)) || !/^HelloLynk WorkBuddy Native - [A-F0-9]{20} - [A-F0-9]{16}$/.test(record.taskName || "")) throw failure("workbuddy_native_service_record_invalid");
+  const endpoint = new URL(record.debugEndpoint);
+  if (endpoint.protocol !== "http:" || endpoint.hostname !== "127.0.0.1" || !endpoint.port || endpoint.pathname !== "/" || endpoint.search || endpoint.hash || endpoint.username || endpoint.password || endpoint.origin !== record.debugEndpoint) throw failure("workbuddy_native_service_record_invalid");
+}
+async function safeParents(target) {
+  const root = path.parse(target).root;
+  let current = root;
+  for (const part of path.relative(root, target).split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    const stat = await fs.lstat(current);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw failure("workbuddy_native_service_record_invalid");
+  }
+}

package/integrations/workbuddy/server/native-task-worker.mjs

@@ -0,0 +1,127 @@
+import crypto from "node:crypto";
+import nativeTaskIndex from "../../../clients/core/hellolynk-native-task-index.cjs";
+import { createNativeInboxRuntime } from "../../../clients/core/hellolynk-native-inbox-runtime.mjs";
+import { readNativeReplyRoute } from "../../../clients/core/hellolynk-native-reply-routes.mjs";
+import { createWorkBuddyNativeTaskClient } from "./native-task-cdp.mjs";
+import { createWorkBuddyOriginLedger, importWorkBuddyOriginDrops, markWorkBuddyActiveScope } from "./origin-routes.mjs";
+
+const { createNativeTaskIndex } = nativeTaskIndex;
+const digest = value => crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const failure = code => Object.assign(new Error(code), { code });
+const REFUSED_TRUST = new Set(["workbuddy_native_mcp_config_mismatch", "workbuddy_native_mcp_disabled", "workbuddy_native_mcp_approval_failed"]);
+const unsent = () => Object.assign(failure("workbuddy_native_not_submitted"), { nativeDispatchStarted: false });
+const uuidFor = batchId => { const h = digest(batchId); return `${h.slice(0,8)}-${h.slice(8,12)}-${h.slice(12,16)}-${h.slice(16,20)}-${h.slice(20,32)}`; };
+
+// The shared receiver owns batching, immediate delivery receipts and the one
+// recovery retry. This bridge retains WorkBuddy's native trust and chat APIs.
+export function startWorkBuddyNativeTaskWorker({ adapter, debugEndpoint = process.env.HELLOLYNK_WORKBUDDY_DEBUG_ENDPOINT || "http://127.0.0.1:9337", recoveryMs = 5_000,
+  acquireLease, readNoticeLocale, clientFactory = createWorkBuddyNativeTaskClient, storeFactory = openNativeTaskStore,
+  originInbox = null, readRoute = readNativeReplyRoute, importOrigins = importWorkBuddyOriginDrops, markScope = markWorkBuddyActiveScope, mcpTrust = null } = {}) {
+  if (!adapter || !Number.isSafeInteger(recoveryMs) || recoveryMs < 10) throw failure("workbuddy_native_worker_options_invalid");
+  let stopped = false, store, ledger, client, trustSettled = false, status = { status: "starting" };
+  // Settle the request once per service process (a new release starts a new
+  // one). Approval checks WorkBuddy's exact current entry and approves only
+  // if still untrusted, so trust the person gave first also settles it. A
+  // refusal (changed, disabled, declined) leaves trust to the person; trust
+  // the person withdraws afterwards is never reopened.
+  async function settleRequestedTrust(registration) {
+    const expected = await mcpTrust.take();
+    if (!expected) { trustSettled = true; return registration; }
+    if (stopped) return registration;
+    let approved;
+    try { approved = await client.approveHelloLynkMcp(expected); }
+    catch (error) {
+      if (REFUSED_TRUST.has(error?.code)) { trustSettled = true; await mcpTrust.settle(); }
+      throw error;
+    }
+    if (approved?.trusted === true) { trustSettled = true; await mcpTrust.settle(); }
+    return approved || registration;
+  }
+
+  const native = {
+    async beforeTick() {
+      client ||= clientFactory({ debugEndpoint, ownedSessionIds: [] });
+      if ((await client.probe())?.available !== true) throw failure("workbuddy_native_preload_unavailable");
+    },
+    async configureScope(scope) {
+      store = await storeFactory(scope); ledger = createWorkBuddyOriginLedger(scope);
+      if (originInbox) await markScope(originInbox, scope).catch(() => {});
+    },
+    async releaseScope() { await store?.close(); store = ledger = client = null; },
+    async legacyDelivery(item) {
+      const old = item.replyToClientMessageId ? await ledger.get(item.localMessageId) : store.getDelivery(digest(item.conversationKey), item.localMessageId);
+      return old ? /unknown|dispatching|creating/.test(old.status) ? "unknown" : "sent" : null;
+    },
+    legacyCarrier(key) { const old = store.getConversation(digest(key)); return old?.status === "created" ? old.nativeSessionId : null; },
+    async prepare(scope, state) {
+      client = clientFactory({ debugEndpoint, ownedSessionIds: [...new Set([...store.listSessions("created"), ...Object.values(state.carriers)])] });
+      let registration = await client.mcpRegistrationStatus({ connect: true });
+      if (mcpTrust && !trustSettled) registration = await settleRequestedTrust(registration);
+      const available = new Set((registration.tools || []).filter(t => t.enabled).map(t => t.name));
+      const allowed = registration.trusted === true && registration.enabled === true;
+      if (!allowed || !["hellolynk_claim_message", "hellolynk_send_authorized_message", "hellolynk_reply_authorized_message"].every(name => available.has(name)))
+        throw failure(allowed && registration.status != null && registration.status !== "ready" ? "workbuddy_native_mcp_not_ready" : "workbuddy_native_mcp_registration_required");
+    },
+    async listConversations(query = {}) {
+      if (query.targetConversationId) {
+        const id = query.targetConversationId, valid = /^[A-Za-z0-9][A-Za-z0-9_.:-]{2,127}$/.test(id);
+        const current = valid ? await client.inspectOrigin(id).catch(() => null) : null;
+        const state = !valid ? 'deleted' : !current ? 'unavailable' : !current.present ? 'deleted' : current.archived ? 'archived' : current.busy ? 'active' : 'idle';
+        return { conversations: [{ targetConversationId: id, title: id, project: '', state }], coverage: 'partial', exactTargetSupported: true };
+      }
+      return client.listConversations();
+    },
+    async inspectThread(id) {
+      const current = await client.inspectOrigin(id);
+      if (typeof current?.present !== "boolean" || typeof current?.busy !== "boolean") throw failure("workbuddy_native_lifecycle_unknown");
+      return { state: !current.present ? "deleted" : current.archived ? "archived" : "present", thread: { status: current.busy ? "active" : "idle" } };
+    },
+    canNotifyOrigin(value) { return value?.state === "present" && value.thread?.status === "idle"; },
+    async call(operation, args, context) {
+      if (operation === "list_threads") { if ((await client.probe())?.available !== true) throw failure("workbuddy_native_preload_unavailable"); return {}; }
+      let id = args.threadId;
+      // All preparation precedes prompt submission. A failed create or route
+      // save may leave a carrier, but must not consume a native send attempt.
+      try {
+        if (operation === "create_thread") {
+          // WorkBuddy accepts a caller-chosen conversation ID. Recover a lost
+          // create receipt by checking this exact ID, without opening a window.
+          id = uuidFor(context.batchId);
+          let existing;
+          try { existing = await client.inspectOrigin(id); } catch { throw unsent(); }
+          if (!await context.stillCurrent()) throw unsent();
+          if (existing?.present !== true) await client.create({ nativeSessionId: id, title: "HelloLynk" });
+          else if (existing.archived) throw Object.assign(failure("workbuddy_native_carrier_closed"),
+            { nativeDispatchStarted: false, nativeCarrierClosedBeforeDispatch: true });
+          await context.rememberThread(id);
+        }
+        if (!await context.stillCurrent()) throw unsent();
+      } catch (error) {
+        if (error?.nativeDispatchStarted === false) throw error;
+        throw Object.assign(failure(error?.code || "workbuddy_native_not_submitted"), { nativeDispatchStarted: false });
+      }
+      const result = await client.sendToIdle({ nativeSessionId: id, clientRequestId: `hellolynk-${context.batchId}`, text: args.prompt });
+      if (["busy", "missing", "archived", "lifecycle_unknown"].includes(result?.status)) throw unsent();
+      if (!["queued_unconfirmed", "submitted_unconfirmed"].includes(result?.status)) throw failure("workbuddy_native_dispatch_unknown");
+      status = { status: "delivered", nativeSessionId: id };
+      return { ok: true, threadId: id };
+    },
+  };
+  const runtime = createNativeInboxRuntime({ adapterId: "workbuddy", native, acquireLease, readNoticeLocale, pollMs: recoveryMs,
+    adapter: { nativeTaskScope: () => adapter.getNativeTaskScope(), inboxBatch: (...args) => adapter.inboxBatch(...args),
+      async listPendingMessages(input) {
+        // Import the send-origin hook before grouping replies by destination.
+        if (originInbox) await importOrigins(originInbox, await adapter.getNativeTaskScope()).catch(() => {});
+        return adapter.listPendingMessages(input);
+      } }, readReplyRoute: readRoute, onError: e => { if (e.operation !== "directory") status = { status: "unavailable", errorCode: e.code }; } });
+  const tick = () => runtime.tick().catch(error => { status = { status: "unavailable", errorCode: error.code || error.message }; });
+  const ready = tick();
+  runtime.start();
+  return Object.freeze({ ready, tick, get status() { return { ...status }; }, async open(id) {
+    if (!client) throw failure("workbuddy_native_task_not_owned"); return client.open(id);
+  }, async close() { stopped = true; await runtime.close(); } });
+}
+export async function openNativeTaskStore(scope) {
+  if (scope?.adapterId !== "workbuddy") throw failure("workbuddy_native_scope_invalid");
+  return createNativeTaskIndex(scope);
+}