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

package/integrations/workbuddy/server/workbench-hidden-launcher.vbs

@@ -0,0 +1,46 @@
+Option Explicit
+
+If WScript.Arguments.Count <> 5 And WScript.Arguments.Count <> 7 Then WScript.Quit 2
+
+Dim shell, fso, command, exitCode, nodePath, entryPath, rootPath, manifest, storeRoot, expectedLauncher, expectedEntry, serviceMode, debugEndpoint, endpointPattern
+Set shell = CreateObject("WScript.Shell")
+Set fso = CreateObject("Scripting.FileSystemObject")
+
+Function QuoteArgument(value)
+  QuoteArgument = Chr(34) & Replace(value, Chr(34), Chr(34) & Chr(34)) & Chr(34)
+End Function
+
+Function IsSha256(value)
+  Dim index, valueChar
+  IsSha256 = Len(value) = 64
+  For index = 1 To Len(value)
+    valueChar = Mid(value, index, 1)
+    If InStr("0123456789abcdef", valueChar) = 0 Then IsSha256 = False
+  Next
+End Function
+
+nodePath = WScript.Arguments(0)
+entryPath = WScript.Arguments(1)
+rootPath = WScript.Arguments(2)
+manifest = WScript.Arguments(3)
+storeRoot = WScript.Arguments(4)
+If StrComp(fso.GetAbsolutePathName(rootPath), rootPath, 1) <> 0 Then WScript.Quit 3
+If StrComp(fso.GetAbsolutePathName(storeRoot), storeRoot, 1) <> 0 Or LCase(fso.GetFileName(storeRoot)) <> "host" Then WScript.Quit 3
+expectedLauncher = fso.BuildPath(rootPath, "integrations\workbuddy\server\workbench-hidden-launcher.vbs")
+expectedEntry = fso.BuildPath(rootPath, "integrations\workbuddy\server\package-bootstrap.mjs")
+If StrComp(fso.GetAbsolutePathName(WScript.ScriptFullName), expectedLauncher, 1) <> 0 Then WScript.Quit 3
+If StrComp(fso.GetAbsolutePathName(nodePath), nodePath, 1) <> 0 Or StrComp(fso.GetAbsolutePathName(entryPath), expectedEntry, 1) <> 0 Or Not fso.FileExists(entryPath) Or Not fso.FileExists(nodePath) Or Not IsSha256(manifest) Then WScript.Quit 3
+shell.Environment("Process")("HELLOLYNK_NEUTRAL_STORE_ROOT") = storeRoot
+serviceMode = "workbench-service"
+If WScript.Arguments.Count = 7 Then
+  serviceMode = WScript.Arguments(5)
+  debugEndpoint = WScript.Arguments(6)
+  Set endpointPattern = New RegExp
+  endpointPattern.Pattern = "^http://127\.0\.0\.1:[0-9]{1,5}$"
+  If serviceMode <> "native-task-service" Or Not endpointPattern.Test(debugEndpoint) Then WScript.Quit 3
+  shell.Environment("Process")("HELLOLYNK_WORKBUDDY_DEBUG_ENDPOINT") = debugEndpoint
+End If
+command = QuoteArgument(nodePath) & " " & QuoteArgument(entryPath) & " " & serviceMode & " --root " & QuoteArgument(rootPath) & _
+  " --expected-manifest-sha256 " & manifest
+exitCode = shell.Run(command, 0, True)
+WScript.Quit exitCode

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

@@ -0,0 +1,373 @@
+import { execFile, spawn } from "node:child_process";
+import path from "node:path";
+import crypto from "node:crypto";
+import net from "node:net";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import runtimeSafety from "../../../clients/core/hellolynk-runtime-safety.cjs";
+import { defaultNeutralHostStoreRoot } from "../../../clients/core/hellolynk-neutral-host-installation-store.mjs";
+import { bootstrapWorkBuddyWorkbenchCandidate } from "./workbench-candidate.mjs";
+import { registerWorkBuddyNativeMcp } from "./native-task-mcp-registration.mjs";
+import { configureWorkBuddyDebugStartup, transferWorkBuddyDebugStartupOwner } from "./native-task-debug-startup.mjs";
+import { withWorkBuddyNativeServiceRecord } from "./native-task-service-registration.mjs";
+import { removeWorkBuddyOriginHook, workBuddyOriginHookCommand, workBuddyOriginInbox } from "./origin-routes.mjs";
+import { loadPinnedWorkBuddyProxy } from "./package-bootstrap.mjs";
+
+const exec = promisify(execFile);
+const STARTUP_TIMEOUT_MS = 90_000;
+
+// WorkBuddy may replace its conversation worker after a normal turn. Windows
+// uses the installed on-demand page service; other platforms use a detached
+// handoff. Both run only the pinned package.
+export async function launchDetachedWorkBuddyWorkbench(options) {
+  const args = bootstrapArgs("handoff-workbench", options);
+  if ((options.platform || process.platform) === "win32") return launchScheduledWorkbench(options);
+  const executable = await runtimeSafety.resolveHelloLynkStandaloneNode({ preferredExecutable: options.nodePath });
+  let stdout;
+  try {
+    ({ stdout } = await (options.exec || exec)(executable, args, {
+      cwd: options.root,
+      env: runtimeSafety.standaloneHelloLynkNodeEnvironment(process.env),
+      windowsHide: true,
+      timeout: STARTUP_TIMEOUT_MS + 5_000,
+      maxBuffer: 4096,
+    }));
+  } catch (error) {
+    // Only bounded, known diagnostic codes cross the subprocess boundary.
+    // Never return the command line, stderr or native exception to the client.
+    if (error?.killed === true && error?.signal === "SIGTERM"
+      && error?.code !== "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+      throw failure("workbuddy_local_web_launch_timeout");
+    }
+    let reported;
+    try { reported = JSON.parse(String(error?.stderr || "").slice(0, 4096)); } catch {}
+    const known = ["workbuddy_local_web_launch_timeout", "workbuddy_local_web_launch_failed",
+      "workbuddy_local_web_launch_invalid", "workbuddy_local_web_launch_handoff_missing"];
+    throw failure(reported?.ok === false && known.includes(reported.error)
+      ? reported.error : "workbuddy_local_web_launch_failed");
+  }
+  try { return validateReady(JSON.parse(stdout)); }
+  catch { throw failure("workbuddy_local_web_launch_invalid"); }
+}
+
+// Installed once by setup. The on-demand task owns the page, so a client's
+// Windows Job cleanup cannot terminate an active browser session.
+export async function configureWorkBuddyWorkbenchTask(options, operation = "Install") {
+  bootstrapArgs("workbench-service", options);
+  if (!["Install", "Verify", "Start", "Uninstall"].includes(operation)) throw failure("workbuddy_page_task_operation_invalid");
+  try {
+    const driverRoot = operation === "Verify" ? path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..") : options.root;
+    const { stdout } = await exec("powershell.exe", ["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File",
+      path.join(driverRoot, "integrations/workbuddy/server/workbench-task.ps1"),
+      "-Command", operation, "-Root", options.root, "-Manifest", options.expectedManifestSha256,
+      "-DriverRoot", driverRoot,
+      "-NodePath", options.nodePath || process.execPath,
+      "-StoreRoot", options.storeRoot || defaultNeutralHostStoreRoot()], {
+      windowsHide: true, timeout: 30_000, maxBuffer: 4096,
+      env: runtimeSafety.sanitizeHelloLynkChildEnvironment(process.env),
+    });
+    const result = JSON.parse(stdout);
+    if (result?.ok !== true) throw failure("workbuddy_page_task_failed");
+    return result;
+  } catch (error) {
+    const code = String(error?.stderr || "").trim();
+    throw failure(/^workbuddy_[a-z_]+$/.test(code) ? code : "workbuddy_page_task_failed");
+  }
+}
+
+// Uses the same installed, hidden launcher and pinned verifier as the page
+// service, with a separate task identity and explicit loopback CDP opt-in.
+export async function configureWorkBuddyNativeTaskService(options, operation = "Install") {
+  if (!["Install", "Uninstall"].includes(operation)) return configureNativeTaskService(options, operation);
+  bootstrapArgs("native-task-service", options);
+  const endpoint = new URL(options.debugEndpoint || "");
+  if (endpoint.protocol !== "http:" || endpoint.hostname !== "127.0.0.1" || !endpoint.port || endpoint.pathname !== "/" || endpoint.search || endpoint.hash || endpoint.username || endpoint.password) throw failure("workbuddy_native_debug_endpoint_invalid");
+  // MCP connection can initialize a new proxy which reads the service record.
+  // Complete that handshake before taking the record/Start lock.
+  const debugStartup = operation === "Install" ? await prepareNativeTaskServiceInstall(options, endpoint) : undefined;
+  return withWorkBuddyNativeServiceRecord(options.storeRoot, async registry => {
+    if (!registry && operation === "Install") throw failure("workbuddy_native_service_store_missing");
+    // Withdraw before stopping, under the same lock used by MCP Verify/Start.
+    if (operation === "Uninstall") await registry?.removeOwned(options);
+    const result = await configureNativeTaskService(options, operation, debugStartup);
+    if (operation === "Install") await registry.save(options, result.taskName);
+    // Without the service nobody imports hook records; leave WorkBuddy's
+    // other hooks and settings untouched.
+    if (operation === "Uninstall") result.originHook = await removeWorkBuddyOriginHook({ settingsPath: options.workBuddySettingsPath,
+      command: workBuddyOriginHookCommand({ nodePath: options.nodePath || process.execPath,
+        hookPath: path.join(options.root, "integrations/workbuddy/server/origin-hook.mjs"),
+        inbox: workBuddyOriginInbox(options.storeRoot || defaultNeutralHostStoreRoot()) }) })
+      .catch(() => ({ changed: false, status: "unavailable" }));
+    return result;
+  });
+}
+
+// An ordinary package upgrade must carry forward an existing listener even
+// while WorkBuddy is closed. First customer install explicitly enables it. The
+// new release's MCP command needs WorkBuddy's trust again: leave one request,
+// which that release's own service approves once WorkBuddy is open.
+export async function updateRecordedWorkBuddyNativeTaskService(options, operation = "Install") {
+  if (!["Install", "Verify"].includes(operation)) throw failure("workbuddy_page_task_operation_invalid");
+  let pendingService = null;
+  const updated = await withWorkBuddyNativeServiceRecord(options.storeRoot, async registry => {
+    const record = await registry?.read();
+    if (!record) {
+      if (operation !== "Install" || options.installIfMissing !== true) return { configured: false, status: "not_installed" };
+      if (!registry) throw failure("workbuddy_native_service_store_missing");
+      const target = { ...options, nodePath: options.nodePath || process.execPath };
+      await loadPinnedWorkBuddyProxy(target);
+      const startupOptions = { storeRoot: registry.storeRoot, debugEndpoint: target.debugEndpoint,
+        installationId: nativeDebugStartupOwner(target), enableDebugStartup: true,
+        ...(options.debugStartupEnvironment ? { environment: options.debugStartupEnvironment } : {}) };
+      const debugStartup = await configureWorkBuddyDebugStartup(startupOptions, "Install");
+      target.debugEndpoint = debugStartup.debugEndpoint;
+      try {
+        const result = await configureNativeTaskService(target, "Install", debugStartup);
+        // Trust is completed by this receiver after the client reopens. Setup
+        // does not require or attach to a running WorkBuddy window.
+        await registry.save({ ...target, pendingMcpTrust: { command: target.nodePath } }, result.taskName);
+        pendingService = target;
+        return { ...result, configured: true, restartRequired: true };
+      } catch (error) {
+        let rollbackError;
+        // Each cleanup is independent: a Scheduler failure must not leave our
+        // newly enabled startup setting behind. Preserve any user change.
+        for (const undo of [() => registry.removeOwned(target),
+          () => configureNativeTaskService({ ...target, debugStartupEnvironment: options.debugStartupEnvironment }, "Uninstall"),
+          () => configureWorkBuddyDebugStartup(startupOptions, "Uninstall")]) {
+          try { await undo(); } catch (cause) { rollbackError ||= cause; }
+        }
+        if (rollbackError) {
+          throw Object.assign(failure("local_configuration_outcome_uncertain"), { cause: rollbackError, configurationCause: error });
+        }
+        throw error;
+      }
+    }
+    const target = { ...options, nodePath: record.nodePath, debugEndpoint: record.debugEndpoint };
+    const sameRelease = path.resolve(record.root).toLowerCase() === path.resolve(target.root).toLowerCase()
+      && record.expectedManifestSha256 === target.expectedManifestSha256;
+    if (operation === "Verify" && !sameRelease) throw failure("workbuddy_native_service_record_mismatch");
+    await loadPinnedWorkBuddyProxy(target);
+    const result = await configureNativeTaskService(target, operation);
+    if (operation === "Install") {
+      await transferWorkBuddyDebugStartupOwner({ storeRoot: registry.storeRoot,
+        previousInstallationId: nativeDebugStartupOwner(record), installationId: nativeDebugStartupOwner(target) });
+      // The installer wrote mcp.json with this process's node.
+      const pendingMcpTrust = sameRelease ? record.pendingMcpTrust : { command: process.execPath };
+      await registry.save({ ...target, pendingMcpTrust }, result.taskName);
+      if (pendingMcpTrust) pendingService = target;
+    }
+    return { ...result, configured: true };
+  });
+  // After the lock: the MCP that approval connects takes it to Verify/Start.
+  if (pendingService) updated.serviceStarted = await (options.startNativeService || (target => configureNativeTaskService(target, "Start")))(pendingService)
+    .then(() => true, () => false);
+  return updated;
+}
+
+async function prepareNativeTaskServiceInstall(options, endpoint) {
+  // Explicit opt-in only. Persist ownership before configuring the task so a
+  // later repair/uninstall can recover a partially completed installation.
+  const debugStartup = await configureWorkBuddyDebugStartup({
+    storeRoot: options.storeRoot || defaultNeutralHostStoreRoot(), debugEndpoint: endpoint.origin,
+    installationId: nativeDebugStartupOwner(options),
+    enableDebugStartup: options.enableDebugStartup === true,
+  }, "Install");
+  await registerWorkBuddyNativeMcp({
+    debugEndpoint: endpoint.origin,
+    command: options.nodePath || process.execPath,
+    releaseRoot: options.mcpRegistration?.releaseRoot || options.root,
+    expectedManifestSha256: options.mcpRegistration?.expectedManifestSha256 || options.expectedManifestSha256,
+    storeRoot: options.storeRoot || defaultNeutralHostStoreRoot(),
+  });
+  return debugStartup;
+}
+
+async function configureNativeTaskService(options, operation, debugStartup) {
+  bootstrapArgs("native-task-service", options);
+  const endpoint = new URL(options.debugEndpoint || "");
+  if (endpoint.protocol !== "http:" || endpoint.hostname !== "127.0.0.1" || !endpoint.port || endpoint.pathname !== "/" || endpoint.search || endpoint.hash || endpoint.username || endpoint.password) throw failure("workbuddy_native_debug_endpoint_invalid");
+  if (!["Install", "Verify", "Start", "Uninstall"].includes(operation)) throw failure("workbuddy_page_task_operation_invalid");
+  try {
+    const { stdout } = await exec("powershell.exe", ["-NoLogo", "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-File",
+      path.join(options.root, "integrations/workbuddy/server/workbench-task.ps1"), "-Command", operation,
+      "-Root", options.root, "-Manifest", options.expectedManifestSha256, "-NodePath", options.nodePath || process.execPath,
+      "-StoreRoot", options.storeRoot || defaultNeutralHostStoreRoot(), "-Mode", "native-task-service", "-DebugEndpoint", endpoint.origin], {
+      windowsHide: true, timeout: 30_000, maxBuffer: 4096, env: runtimeSafety.sanitizeHelloLynkChildEnvironment(process.env),
+    });
+    const result = JSON.parse(stdout); if (result?.ok !== true) throw failure("workbuddy_page_task_failed");
+    if (operation === "Uninstall") result.debugStartup = await configureWorkBuddyDebugStartup({
+      storeRoot: options.storeRoot || defaultNeutralHostStoreRoot(), debugEndpoint: endpoint.origin,
+      installationId: nativeDebugStartupOwner(options),
+      ...(options.debugStartupEnvironment ? { environment: options.debugStartupEnvironment } : {}),
+    }, operation);
+    else if (debugStartup) result.debugStartup = debugStartup;
+    return result;
+  } catch { throw failure("workbuddy_native_service_configuration_failed"); }
+}
+
+function nativeDebugStartupOwner(options) {
+  return crypto.createHash("sha256").update(`${path.resolve(options.root).toLowerCase()}|${options.expectedManifestSha256}`).digest("hex");
+}
+
+function controlPipe(options) {
+  const key = crypto.createHash("sha256").update(`${options.root.toLowerCase()}|${options.expectedManifestSha256}`).digest("hex");
+  return `\\\\.\\pipe\\hellolynk-workbuddy-${key}`;
+}
+
+async function requestExistingWorkbench(options) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect(controlPipe(options));
+    let text = "";
+    socket.setTimeout(3000, () => socket.destroy(failure("workbuddy_page_service_timeout")));
+    socket.on("error", reject);
+    socket.on("connect", () => socket.write("open\n"));
+    socket.on("data", (chunk) => {
+      text += chunk.toString("utf8");
+      if (text.length > 4096) socket.destroy(failure("workbuddy_local_web_launch_invalid"));
+    });
+    socket.on("end", () => {
+      try { resolve(validateReady(JSON.parse(text))); }
+      catch { reject(failure("workbuddy_local_web_launch_invalid")); }
+    });
+  });
+}
+
+async function launchScheduledWorkbench(options) {
+  try { return await requestExistingWorkbench(options); }
+  catch (error) { if (!["ENOENT", "ECONNREFUSED"].includes(error?.code)) throw error; }
+  await configureWorkBuddyWorkbenchTask(options, "Start");
+  const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+  do {
+    await delay(200);
+    try { return await requestExistingWorkbench(options); }
+    catch (error) { if (!["ENOENT", "ECONNREFUSED"].includes(error?.code)) throw error; }
+  } while (Date.now() < deadline);
+  throw failure("workbuddy_local_web_launch_timeout");
+}
+
+export async function serveWorkBuddyWorkbenchService(options) {
+  let server;
+  const sockets = new Set();
+  try {
+    await serveWorkBuddyWorkbench({ ...options, async publishReady(value, surface) {
+      server = net.createServer((socket) => {
+        sockets.add(socket);
+        socket.on("close", () => sockets.delete(socket));
+        socket.on("error", () => {});
+        socket.setTimeout(3000, () => socket.destroy());
+        let text = "";
+        socket.on("data", (chunk) => {
+          text += chunk.toString("utf8");
+          if (text === "open\n") { surface.armNavigation(); socket.end(`${JSON.stringify(validateReady(value))}\n`); }
+          else if (text.length >= 5) socket.destroy();
+        });
+      });
+      await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(controlPipe(options), () => { server.off("error", reject); resolve(); });
+      });
+    } });
+  } finally {
+    for (const socket of sockets) socket.destroy();
+    if (server?.listening) await new Promise((resolve) => server.close(resolve));
+  }
+}
+
+export async function handoffWorkBuddyWorkbench(options) {
+  const executable = await runtimeSafety.resolveHelloLynkStandaloneNode();
+  const child = spawn(executable, bootstrapArgs("workbench", options), {
+    cwd: options.root,
+    env: runtimeSafety.standaloneHelloLynkNodeEnvironment(process.env),
+    detached: true,
+    windowsHide: true,
+    stdio: ["ignore", "ignore", "ignore", "ipc"],
+  });
+  try {
+    const ready = await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => done(failure("workbuddy_local_web_launch_timeout")), STARTUP_TIMEOUT_MS);
+      const failed = () => done(failure("workbuddy_local_web_launch_failed"));
+      const message = (value) => {
+        try { done(null, validateReady(value)); }
+        catch { failed(); }
+      };
+      const done = (error, value) => {
+        clearTimeout(timer);
+        child.off("message", message);
+        child.off("error", failed);
+        child.off("exit", failed);
+        if (error) reject(error); else resolve(value);
+      };
+      child.once("error", failed);
+      child.once("exit", failed);
+      child.once("message", message);
+    });
+    child.disconnect();
+    child.unref();
+    return ready;
+  } catch (error) {
+    child.kill();
+    throw error;
+  }
+}
+
+export async function serveWorkBuddyWorkbench(options) {
+  const { adapter, signal, publishReady = sendReady } = options;
+  let page;
+  try {
+    page = await bootstrapWorkBuddyWorkbenchCandidate({
+      adapter, pagePath: "/inbox",
+      ...(options.bootstrapWorkbenchCandidate ? {
+        bootstrapWorkbenchCandidate: options.bootstrapWorkbenchCandidate,
+        workbenchContract: options.workbenchContract,
+      } : {}),
+    });
+    if (signal?.aborted) return;
+    await publishReady({ cleanUrl: page.cleanUrl }, page.surface);
+    while (!signal?.aborted) {
+      const state = page.surface.status();
+      // Reuse the existing navigation and session expiry rules. Keeping a
+      // browser page alive does not grant any extra Host or message access.
+      if (!state.navigationArmed && state.liveSessionCount === 0) return;
+      try { await delay(options.checkIntervalMs ?? 1000, undefined, { signal }); }
+      catch (error) { if (!signal?.aborted) throw error; }
+    }
+  } finally {
+    try { await page?.close(); }
+    finally { await adapter.close(); }
+  }
+}
+
+function bootstrapArgs(mode, options) {
+  if (!path.isAbsolute(options?.root || "")
+    || path.resolve(options.root) !== options.root
+    || !/^[a-f0-9]{64}$/.test(options?.expectedManifestSha256 || "")) {
+    throw failure("workbuddy_local_web_launch_configuration_invalid");
+  }
+  return [path.join(options.root, "integrations/workbuddy/server/package-bootstrap.mjs"),
+    mode, "--root", options.root, "--expected-manifest-sha256", options.expectedManifestSha256];
+}
+
+function validateReady(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).length !== 1 || typeof value.cleanUrl !== "string"
+    || !/^http:\/\/127\.0\.0\.1:\d{1,5}\/inbox$/.test(value.cleanUrl)) {
+    throw failure("workbuddy_local_web_launch_invalid");
+  }
+  const port = Number(new URL(value.cleanUrl).port);
+  if (port < 1 || port > 65535) throw failure("workbuddy_local_web_launch_invalid");
+  return Object.freeze({ cleanUrl: value.cleanUrl });
+}
+
+function sendReady(value) {
+  return new Promise((resolve, reject) => {
+    if (!process.connected || typeof process.send !== "function") {
+      reject(failure("workbuddy_local_web_launch_handoff_missing"));
+      return;
+    }
+    process.send(validateReady(value), (error) => error ? reject(error) : resolve());
+  });
+}
+
+function failure(code) { return Object.assign(new Error(code), { code }); }

package/integrations/workbuddy/server/workbench-task.ps1

@@ -0,0 +1,196 @@
+param(
+  [Parameter(Mandatory=$true)][ValidateSet('Install','Verify','Start','Run','Uninstall')][string]$Command,
+  [Parameter(Mandatory=$true)][string]$Root,
+  [Parameter(Mandatory=$true)][ValidatePattern('^[a-f0-9]{64}$')][string]$Manifest,
+  [Parameter(Mandatory=$true)][string]$NodePath,
+  [Parameter(Mandatory=$true)][string]$StoreRoot,
+  [string]$DriverRoot = '',
+  [ValidateSet('workbench-service','native-task-service')][string]$Mode = 'workbench-service',
+  [string]$DebugEndpoint = ''
+)
+$ErrorActionPreference = 'Stop'
+try {
+  $nativeService = $Mode -eq 'native-task-service'
+  if (-not $DriverRoot) { $DriverRoot = $Root }
+  # A new, verified installer may check an older immutable release with its
+  # current task driver. It may not mutate that release through this path.
+  if ($DriverRoot -ne $Root -and $Command -ne 'Verify') { throw 'workbuddy_page_task_path_invalid' }
+  if ($nativeService -and ($DebugEndpoint -notmatch '^http://127\.0\.0\.1:[0-9]{1,5}$' -or ([uri]$DebugEndpoint).Port -lt 1)) { throw 'workbuddy_native_debug_endpoint_invalid' }
+  if (-not $nativeService -and $DebugEndpoint) { throw 'workbuddy_native_debug_endpoint_invalid' }
+  if (-not [IO.Path]::IsPathRooted($Root) -or $Root -match '["\r\n]' -or
+    -not [IO.Path]::IsPathRooted($NodePath) -or $NodePath -match '["\r\n]' -or
+    -not [IO.Path]::IsPathRooted($StoreRoot) -or $StoreRoot -match '["\r\n]' -or
+    [IO.Path]::GetFileName($StoreRoot) -ne 'host') { throw 'workbuddy_page_task_path_invalid' }
+  $entry = Join-Path $Root 'integrations\workbuddy\server\package-bootstrap.mjs'
+  $script = Join-Path $DriverRoot 'integrations\workbuddy\server\workbench-task.ps1'
+  $launcher = Join-Path $Root 'integrations\workbuddy\server\workbench-hidden-launcher.vbs'
+  $wscript = Join-Path $env:SystemRoot 'System32\wscript.exe'
+  if (-not (Test-Path -LiteralPath $entry -PathType Leaf) -or -not (Test-Path -LiteralPath $launcher -PathType Leaf) -or
+    -not (Test-Path -LiteralPath $wscript -PathType Leaf) -or -not (Test-Path -LiteralPath $NodePath -PathType Leaf) -or
+    [IO.Path]::GetFullPath($PSCommandPath) -ne [IO.Path]::GetFullPath($script)) { throw 'workbuddy_page_task_entry_invalid' }
+  if ($Command -eq 'Run') {
+    $arguments = '//B //NoLogo "{0}" "{1}" "{2}" "{3}" {4} "{5}"' -f $launcher,$NodePath,$entry,$Root,$Manifest,$StoreRoot
+    if ($nativeService) { $arguments += ' native-task-service "{0}"' -f $DebugEndpoint }
+    $worker = Start-Process -FilePath $wscript -ArgumentList $arguments -WindowStyle Hidden -PassThru -Wait
+    exit $worker.ExitCode
+  }
+  $sid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+  $namespaceRoot = [IO.Path]::GetDirectoryName($Root)
+  if ([IO.Path]::GetFileName($namespaceRoot) -ne 'releases') { $namespaceRoot = $Root }
+  $namespace = $sid + '|' + [IO.Path]::GetFullPath($namespaceRoot).ToLowerInvariant()
+  $hash = [Security.Cryptography.SHA256]::Create()
+  try {
+    $suffix = ([BitConverter]::ToString($hash.ComputeHash([Text.Encoding]::UTF8.GetBytes($namespace)))).Replace('-','').Substring(0,20)
+    $releaseIdentity = [IO.Path]::GetFullPath($Root).ToLowerInvariant() + '|' + $Manifest
+    $releaseSuffix = ([BitConverter]::ToString($hash.ComputeHash([Text.Encoding]::UTF8.GetBytes($releaseIdentity)))).Replace('-','').Substring(0,16)
+  }
+  finally { $hash.Dispose() }
+  $taskBase = "HelloLynk WorkBuddy - $suffix"
+  if ($nativeService) { $taskBase = "HelloLynk WorkBuddy Native - $suffix" }
+  $taskName = "$taskBase - $releaseSuffix"
+  $description = 'HelloLynk WorkBuddy page service; starts on demand and stops when browser sessions expire.'
+  if ($nativeService) { $description = 'HelloLynk WorkBuddy native inbox listener; explicit loopback desktop bridge; no model polling.' }
+  $executable = $wscript
+  $arguments = '//B //NoLogo "{0}" "{1}" "{2}" "{3}" {4} "{5}"' -f $launcher,$NodePath,$entry,$Root,$Manifest,$StoreRoot
+  if ($nativeService) { $arguments += ' native-task-service "{0}"' -f $DebugEndpoint }
+  # The native listener also resumes at this user's logon with normal rights,
+  # so an update's trust request survives a restart before WorkBuddy opens.
+  # One instance per release. The page task stays on demand.
+  $instances = 0; $installedTrigger = 'none'
+  if ($nativeService) { $instances = 2; $installedTrigger = 'logon' }
+  # Use the Scheduler API directly; its CIM wrapper can time out while the
+  # registered task and on-demand service are both healthy.
+  $scheduler = New-Object -ComObject 'Schedule.Service'; $scheduler.Connect()
+  $folder = $scheduler.GetFolder('\')
+  function Read-Task($registered) {
+    $d = $registered.Definition
+    [pscustomobject]@{ TaskName=$registered.Name; Description=$d.RegistrationInfo.Description; Principal=$d.Principal; Settings=$d.Settings
+      Triggers=@($d.Triggers); Actions=@($d.Actions | ForEach-Object { [pscustomobject]@{Execute=$_.Path; Arguments=$_.Arguments; WorkingDirectory=$_.WorkingDirectory; Type=$_.Type} })
+      State=$registered.State; Registered=$registered }
+  }
+  # 'none', 'logon' (this user's logon trigger), 'logon_disabled' or 'other'.
+  function Get-TriggerState($triggers) {
+    $list = @($triggers | Where-Object { $null -ne $_ })
+    if ($list.Count -eq 0) { return 'none' }
+    if (-not $nativeService -or $list.Count -ne 1 -or $list[0].Type -ne 9) { return 'other' }
+    $user = [string]$list[0].UserId
+    if ($user -notmatch '^S-1-') { $user = (New-Object Security.Principal.NTAccount($user)).Translate([Security.Principal.SecurityIdentifier]).Value }
+    if ($user -ne $sid) { return 'other' }
+    if ($list[0].Enabled) { return 'logon' }
+    return 'logon_disabled'
+  }
+  $task = $null
+  try { $task = Read-Task ($folder.GetTask($taskName)) }
+  catch { if ($_.Exception.HResult -ne -2147024894) { throw } }
+  if ($task) {
+    $taskSid = [string]$task.Principal.UserId
+    if ($taskSid -notmatch '^S-1-') { $taskSid = (New-Object Security.Principal.NTAccount($taskSid)).Translate([Security.Principal.SecurityIdentifier]).Value }
+    if ($task.Description -ne $description -or $taskSid -ne $sid) { throw 'workbuddy_page_task_conflict' }
+  }
+  $namespaceTasks = @($folder.GetTasks(1) | Where-Object { $_.Name -eq $taskBase -or $_.Name.StartsWith($taskBase + ' - ') } | ForEach-Object { Read-Task $_ })
+  foreach ($candidate in $namespaceTasks) {
+    $candidateSid = [string]$candidate.Principal.UserId
+    if ($candidateSid -notmatch '^S-1-') { $candidateSid = (New-Object Security.Principal.NTAccount($candidateSid)).Translate([Security.Principal.SecurityIdentifier]).Value }
+    if ($candidate.Description -ne $description -or $candidateSid -ne $sid) { throw 'workbuddy_page_task_conflict' }
+  }
+  function Stop-VerifiedNativeTaskProcesses($candidate) {
+    # Task Scheduler can stop wscript while leaving its shell.Run child alive.
+    # Match the entire verified native command, never a generic node process.
+    if (@($candidate.Actions).Count -ne 1 -or $candidate.Actions[0].Execute -ne $wscript) { throw 'workbuddy_native_service_identity_invalid' }
+    $pattern = '^//B //NoLogo "([^"\r\n]+)" "([^"\r\n]+)" "([^"\r\n]+)" "([^"\r\n]+)" ([a-f0-9]{64}) "([^"\r\n]+)" native-task-service "(http://127\.0\.0\.1:[0-9]{1,5})"$'
+    $match = [regex]::Match([string]$candidate.Actions[0].Arguments, $pattern)
+    if (-not $match.Success) { throw 'workbuddy_native_service_identity_invalid' }
+    $oldLauncher = $match.Groups[1].Value; $oldNode = $match.Groups[2].Value
+    $oldEntry = $match.Groups[3].Value; $oldRoot = $match.Groups[4].Value
+    $oldManifest = $match.Groups[5].Value; $oldStore = $match.Groups[6].Value
+    if (-not [IO.Path]::IsPathRooted($oldRoot) -or $oldNode -ne $NodePath -or $oldStore -ne $StoreRoot -or
+      $oldLauncher -ne (Join-Path $oldRoot 'integrations\workbuddy\server\workbench-hidden-launcher.vbs') -or
+      $oldEntry -ne (Join-Path $oldRoot 'integrations\workbuddy\server\package-bootstrap.mjs')) { throw 'workbuddy_native_service_identity_invalid' }
+    $oldNamespace = [IO.Path]::GetDirectoryName($oldRoot)
+    if ([IO.Path]::GetFileName($oldNamespace) -ne 'releases') { $oldNamespace = $oldRoot }
+    if ([IO.Path]::GetFullPath($oldNamespace) -ne [IO.Path]::GetFullPath($namespaceRoot)) { throw 'workbuddy_native_service_identity_invalid' }
+    $identityHash = [Security.Cryptography.SHA256]::Create()
+    try { $oldSuffix = ([BitConverter]::ToString($identityHash.ComputeHash([Text.Encoding]::UTF8.GetBytes([IO.Path]::GetFullPath($oldRoot).ToLowerInvariant() + '|' + $oldManifest)))).Replace('-','').Substring(0,16) }
+    finally { $identityHash.Dispose() }
+    if ($candidate.TaskName -ne "$taskBase - $oldSuffix") { throw 'workbuddy_native_service_identity_invalid' }
+    $nodeTail = '"{0}" native-task-service --root "{1}" --expected-manifest-sha256 {2}' -f $oldEntry,$oldRoot,$oldManifest
+    # WScript.Shell.Run can add a second space after the executable. Only
+    # that argv separator varies; all paths, mode and manifest remain exact.
+    $nodeCommandPattern = '^(?:"' + [regex]::Escape($oldNode) + '"|' + [regex]::Escape($oldNode) + ')[ \t]+' + [regex]::Escape($nodeTail) + '$'
+    $helperCommandPattern = '^(?:"' + [regex]::Escape($wscript) + '"|' + [regex]::Escape($wscript) + ')[ \t]+' + [regex]::Escape([string]$candidate.Actions[0].Arguments) + '$'
+    foreach ($observed in @(Get-CimInstance Win32_Process -Filter "Name = 'node.exe' OR Name = 'wscript.exe'")) {
+      $observedCommand = ([string]$observed.CommandLine).Trim()
+      if (-not (($observed.ExecutablePath -eq $oldNode -and $observedCommand -match $nodeCommandPattern) -or
+        ($observed.ExecutablePath -eq $wscript -and $observedCommand -match $helperCommandPattern))) { continue }
+      if ((Invoke-CimMethod -InputObject $observed -MethodName GetOwnerSid).Sid -ne $sid) { continue }
+      $process = $null
+      try {
+        $process = Get-Process -Id $observed.ProcessId -ErrorAction SilentlyContinue
+        if (-not $process) { continue }
+        $openedHandle = $process.Handle
+        $current = Get-CimInstance Win32_Process -Filter "ProcessId = $($observed.ProcessId)"
+        if (-not $current -or $current.CreationDate -ne $observed.CreationDate -or $current.CommandLine -ne $observed.CommandLine -or $current.ExecutablePath -ne $observed.ExecutablePath) { continue }
+        $process.Kill()
+        if (-not $process.WaitForExit(5000)) { throw 'workbuddy_native_service_stop_timeout' }
+      } finally { if ($process) { $process.Dispose() } }
+    }
+  }
+  if ($Command -eq 'Uninstall') {
+    foreach ($candidate in $namespaceTasks) {
+      # An obsolete release may be uninstalled after its replacement is active.
+      # Its manifest/root identity only owns this exact task, not the namespace.
+      if ($candidate.TaskName -ne $taskName) { continue }
+      if ($nativeService) { Stop-VerifiedNativeTaskProcesses $candidate }
+      $candidate.Registered.Stop(0)
+      $folder.DeleteTask($candidate.TaskName, 0)
+    }
+  } elseif ($Command -eq 'Install') {
+    if ($task -and @($task.Actions).Count -eq 1 -and $task.Actions[0].Type -eq 0 -and $task.Actions[0].Execute -eq $executable -and $task.Actions[0].Arguments -eq $arguments -and $task.Actions[0].WorkingDirectory -eq $Root -and
+      (Get-TriggerState $task.Triggers) -eq $installedTrigger -and $task.Principal.RunLevel -eq 0 -and $task.Principal.LogonType -eq 3 -and
+      $task.Settings.MultipleInstances -eq $instances -and $task.Settings.ExecutionTimeLimit -eq 'PT0S' -and $task.Settings.AllowDemandStart) {
+      # The exact current package is already registered; leave its page alone.
+    } else {
+      # Registering a new immutable release must not terminate a page that a
+      # user already has open. Different releases use different control pipes;
+      # Parallel lets the new release start while the old page drains. Calls
+      # for the same release still reuse its existing pipe before task start.
+      $definition = $scheduler.NewTask(0); $definition.RegistrationInfo.Description = $description
+      $definition.Principal.UserId = $sid; $definition.Principal.LogonType = 3; $definition.Principal.RunLevel = 0
+      $definition.Settings.MultipleInstances = $instances; $definition.Settings.ExecutionTimeLimit = 'PT0S'; $definition.Settings.AllowDemandStart = $true
+      $definition.Settings.DisallowStartIfOnBatteries = $false; $definition.Settings.StopIfGoingOnBatteries = $false
+      if ($nativeService) { $logon = $definition.Triggers.Create(9); $logon.UserId = $sid }
+      $action = $definition.Actions.Create(0); $action.Path = $executable; $action.Arguments = $arguments; $action.WorkingDirectory = $Root
+      $null = $folder.RegisterTaskDefinition($taskName, $definition, 6, $sid, $null, 3)
+    }
+    foreach ($candidate in $namespaceTasks) {
+      if ($nativeService -and $candidate.TaskName -ne $taskName) {
+        Stop-VerifiedNativeTaskProcesses $candidate
+        $candidate.Registered.Stop(0)
+      }
+      if ($candidate.TaskName -ne $taskName -and ($nativeService -or $candidate.State -ne 4)) {
+        $folder.DeleteTask($candidate.TaskName, 0)
+      }
+    }
+  } else {
+    if (-not $task) { throw 'workbuddy_page_task_missing' }
+    # A logon trigger the user removed or disabled still leaves on-demand start.
+    if (@($task.Actions).Count -ne 1 -or $task.Actions[0].Type -ne 0 -or $task.Actions[0].Execute -ne $executable -or $task.Actions[0].Arguments -ne $arguments -or $task.Actions[0].WorkingDirectory -ne $Root -or
+      (Get-TriggerState $task.Triggers) -eq 'other' -or $task.Principal.RunLevel -ne 0 -or $task.Principal.LogonType -ne 3 -or
+      $task.Settings.MultipleInstances -ne $instances -or $task.Settings.ExecutionTimeLimit -ne 'PT0S' -or -not $task.Settings.AllowDemandStart) { throw 'workbuddy_page_task_configuration_invalid' }
+    if ($Command -eq 'Start' -and $task.State -ne 4) {
+      for ($attempt = 0; $attempt -lt 3; $attempt += 1) {
+        try { $null = $task.Registered.Run($null); break }
+        catch {
+          if ($attempt -eq 2) { throw }
+          Start-Sleep -Milliseconds (100 * ($attempt + 1))
+        }
+      }
+    }
+  }
+  [pscustomobject]@{ok=$true;operation=$Command;taskName=$taskName} | ConvertTo-Json -Compress
+} catch {
+  $code = [string]$_.Exception.Message
+  if ($code -notmatch '^workbuddy_[a-z_]+$') { $code = 'workbuddy_page_task_failed' }
+  [Console]::Error.WriteLine($code)
+  exit 1
+}

package/integrations/workbuddy/skills/hellolynk-inbox/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: hellolynk-inbox
+description: 在 WorkBuddy 中打开和使用 HelloLynk 通讯；不用于邮件。
+---
+# HelloLynk 通讯
+HelloLynk 是本人授权的 AI 通讯。接着已有来往用 hellolynk_reply_authorized_message，沿用来信的 localMessageId 和 conversationKey；发起新通信用 hellolynk_send_authorized_message，contact 填对方名字。每条新消息用新的 clientMessageId；发送失败或结果未知时保留编号并停止，不重发；参数无效时改正后重新调用。收到本聊天的 HelloLynk 自动提醒时，用 hellolynk_claim_message 按 batchId 读一次。没有本聊天的提醒或本人查信要求时，不主动查信。用户要看全部来信时，打开本客户端的 HelloLynk 界面供本人查看。
+## 打开
+1. 调用 hellolynk_open_inbox（空参数）一次。
+2. 用内置浏览器打开返回的地址。

package/integrations/workbuddy/skills/hellolynk-inbox/workbuddy.json

@@ -0,0 +1,6 @@
+{
+  "display_name": "HelloLynk 通讯",
+  "display_name_en": "HelloLynk Messaging",
+  "description_zh": "在 WorkBuddy 中打开和使用 HelloLynk 通讯。",
+  "description_en": "Open and use HelloLynk Messaging in WorkBuddy."
+}