@hellolynk-ai/trae-work-mcp 0.0.0-stage → 0.4.95

package/integrations/trae-work/runtime/neutral-host-bootstrap.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadNeutralHostRelease } from "./neutral-host-release-loader.mjs";
+
+export async function runNeutralHostBootstrap(argv = process.argv.slice(2)) {
+  const options = parse(argv);
+  const release = await loadNeutralHostRelease();
+  if (typeof release?.run !== "function") throw codeError("neutral_trae_work_runner_integrity_invalid");
+  return release.run({ root: options.root });
+}
+function parse(argv) { if (argv.length !== 3 || argv[0] !== "run" || argv[1] !== "--root" || !path.isAbsolute(String(argv[2] || ""))) throw codeError("neutral_trae_work_launch_configuration_required"); return { root: path.resolve(argv[2]) }; }
+function codeError(code) { const error = new Error(code); error.code = code; return error; }
+// Start failures and a failed Host both end here. A failed Host keeps its lock until this
+// process exits on its own: a closed stderr pipe (the detached launcher may be gone) must
+// not crash it before admitted work finishes.
+function exitWithFailure(code) { process.stderr.on("error", () => {}); process.stderr.write(`${JSON.stringify({ ok: false, code })}\n`); process.exitCode = 1; }
+
+// A stray rejection must not take the Host down: log a stable code and keep serving. A synchronous
+// uncaught exception leaves state unknown: stop the Host (releases its lock), then exit; 15 s bounds a stuck stop.
+function guardHostProcess(result) {
+  process.on("unhandledRejection", (reason) => writeFailure("neutral_trae_work_unhandled_rejection", reason));
+  process.on("uncaughtException", (error) => {
+    writeFailure("neutral_trae_work_uncaught_exception", error);
+    process.exitCode = 1;
+    const exit = () => process.exit(1);
+    setTimeout(exit, 15_000).unref?.();
+    Promise.resolve().then(() => result?.stop?.("uncaught_exception")).then(exit, exit);
+  });
+  return result;
+}
+
+function writeFailure(code, cause) {
+  if (!process.stderr.listenerCount("error")) process.stderr.on("error", () => {});
+  process.stderr.write(`${JSON.stringify({ ok: false, code, cause: String(cause?.code || cause?.name || "").slice(0, 80) })}\n`);
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1] || "").href) runNeutralHostBootstrap().then((result) => guardHostProcess(result)?.waitUntilStopped?.() || new Promise(() => {})).catch((error) => exitWithFailure(String(error?.code || "neutral_trae_work_launch_failed")));

package/integrations/trae-work/runtime/neutral-host-release-entry.mjs

@@ -0,0 +1,16 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createHostProtectedStore } from "../../../clients/core/hellolynk-host-protected-store.mjs";
+import { createNeutralHostInstallationStore, defaultNeutralHostStoreRoot } from "../../../clients/core/hellolynk-neutral-host-installation-store.mjs";
+import { startHelloLynkNeutralHostAssembly } from "../../../clients/core/hellolynk-neutral-host-assembly.mjs";
+
+export async function createNeutralHostReleaseRuntime() { return Object.freeze({ defaultStoreRoot: (env) => defaultNeutralHostStoreRoot("win32", env), createInstallationStore: (options) => createNeutralHostInstallationStore(options), createProtectedStore: (options) => createHostProtectedStore(options), run: async ({ root }) => runProductionHost(root) }); }
+async function runProductionHost(rootInput) {
+  const root = path.resolve(String(rootInput || "")); if (!path.isAbsolute(root) || root.length < 4) throw codeError("neutral_trae_work_launch_configuration_required");
+  const installationStore = createNeutralHostInstallationStore({ root }); const protectedStore = createHostProtectedStore({ root, installationStore }); const binding = await protectedStore.resolveTraeWorkNeutralBinding();
+  const profiles = await readProfileManifest(binding.profileManifestPath); const assembly = await startHelloLynkNeutralHostAssembly({ root, runtimeRoot: binding.runtimeRoot, profiles: profiles.map((profileFile) => ({ profileFile })) }, { installationStore, protectedStore });
+  // A failed Host never reaches "stopped"; end the wait so the bootstrap exits with its code.
+  return Object.freeze({ stop: assembly.stop, waitUntilStopped: async () => { while (assembly.host.status !== "stopped") { if (assembly.host.status === "failed") throw codeError(assembly.host.failureCode || "neutral_host_stop_failed"); await new Promise((resolve) => setTimeout(resolve, 50)); } } });
+}
+async function readProfileManifest(input) { const manifestPath = path.resolve(String(input || "")); if (!path.isAbsolute(manifestPath)) throw codeError("neutral_trae_work_launch_manifest_invalid"); let manifest; try { manifest = JSON.parse(await fs.readFile(manifestPath, "utf8")); } catch { throw codeError("neutral_trae_work_launch_manifest_invalid"); } if (!manifest || manifest.contract !== "hellolynk-neutral-host-profile-manifest-v1" || !Array.isArray(manifest.profiles) || !manifest.profiles.length || manifest.profiles.length > 16 || Object.keys(manifest).sort().join(",") !== "contract,profiles") throw codeError("neutral_trae_work_launch_manifest_invalid"); const profiles = manifest.profiles.map((value) => path.resolve(String(value || ""))); if (profiles.some((value, index) => !path.isAbsolute(value) || profiles.indexOf(value) !== index)) throw codeError("neutral_trae_work_launch_manifest_invalid"); return Object.freeze(profiles); }
+function codeError(code) { const error = new Error(code); error.code = code; return error; }

package/integrations/trae-work/runtime/trae-work-bootstrap.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { isWorkbenchConnectionRequired } from "../../../clients/core/hellolynk-workbench-connection.mjs";
+import { resolveClientAccountRoot } from "../../../clients/core/hellolynk-client-account.mjs";
+import { createHostProtectedStore } from "../../../clients/core/hellolynk-host-protected-store.mjs";
+import { createNeutralHostInstallationStore, defaultNeutralHostStoreRoot } from "../../../clients/core/hellolynk-neutral-host-installation-store.mjs";
+import { verifyPinnedBootstrap } from "../server/host-lifecycle.mjs";
+
+const RELEASE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..");
+export async function runTraeWorkBootstrap(argv = process.argv.slice(2), options = {}) {
+  const expected = parse(argv); const root = resolveClientAccountRoot("trae-work", options.storeRoot || defaultNeutralHostStoreRoot("win32", options.env || process.env));
+  const installationStore = createNeutralHostInstallationStore({ root }); const store = createHostProtectedStore({ root, installationStore });
+  let binding;
+  try { binding = await store.resolveTraeWorkNeutralBinding(); }
+  catch (error) { if (!isWorkbenchConnectionRequired(error)) throw error; }
+  const verification = binding || {
+    adapterId: "trae-work", profileId: "hellolynk-host-trae-work-v2", version: 2, scopes: [],
+    region: "intl", principalId: "connection-preflight", delegateId: "connection-preflight", hostInstallationId: "connection-preflight",
+    releaseRoot: RELEASE_ROOT, releaseManifestSha256: expected, runnerRelativePath: "runtime/neutral-host-bootstrap.mjs",
+    runtimeRoot: path.join(root, "runtime"), profileManifestPath: path.join(root, "profile-manifest-v1.json"),
+  };
+  if (path.resolve(verification.releaseRoot || "") !== RELEASE_ROOT || verification.releaseManifestSha256 !== expected) throw codeError("neutral_trae_work_runner_integrity_invalid");
+  await verifyPinnedBootstrap(verification, { storeRoot: root });
+  const proxy = await import(pathToFileURL(path.join(RELEASE_ROOT, "integrations", "trae-work", "server", "mcp-proxy.mjs")).href);
+  return proxy.runTraeWorkMcpProxy({ storeRoot: root });
+}
+function parse(argv) { if (argv.length !== 3 || argv[0] !== "run" || argv[1] !== "--expected-manifest-sha256" || !/^[a-f0-9]{64}$/.test(String(argv[2] || ""))) throw codeError("trae_work_bootstrap_arguments_invalid"); return argv[2]; }
+function codeError(code) { const error = new Error(code); error.code = code; return error; }
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) runTraeWorkBootstrap().catch((error) => { process.stderr.write(`${JSON.stringify({ ok: false, error: error.code || "trae_work_bootstrap_failed" })}\n`); process.exitCode = 1; });

package/integrations/trae-work/server/dynamic-ui-contract.mjs

@@ -0,0 +1,376 @@
+import crypto from "node:crypto";
+
+export const TRAE_DYNAMIC_UI_CONTRACT = "hellolynk-trae-dynamic-ui-v1";
+export const TRAE_DYNAMIC_UI_VERSION = 1;
+export const TRAE_DYNAMIC_UI_RENDERER = "HelloLynkTraeLocalWebV18";
+
+const VIEWS = new Set([
+  "status", "inbox", "message", "contacts", "contact", "outbox", "send", "action", "error",
+]);
+const STATES = new Set(["ready", "empty", "pending", "blocked"]);
+const EXPOSURES = new Set(["aggregate-only", "metadata-only", "selected-record", "selected-content"]);
+const ID = /^[A-Za-z0-9][A-Za-z0-9_.:-]{2,198}$/;
+const HELLOLYNK_ID = /^hellolynk:(intl|cn):[a-z0-9][a-z0-9._-]{2,179}$/;
+const ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype", "html", "innerHTML", "script"]);
+
+export function createDynamicUiEnvelope(view, state, data, options = {}) {
+  if (!VIEWS.has(view)) throw codeError("trae_dynamic_ui_view_invalid");
+  if (!STATES.has(state)) throw codeError("trae_dynamic_ui_state_invalid");
+  const exposure = options.exposure || "metadata-only";
+  if (!EXPOSURES.has(exposure)) throw codeError("trae_dynamic_ui_exposure_invalid");
+  const envelope = {
+    contract: TRAE_DYNAMIC_UI_CONTRACT,
+    version: TRAE_DYNAMIC_UI_VERSION,
+    renderer: TRAE_DYNAMIC_UI_RENDERER,
+    view,
+    state,
+    exposure,
+    component: componentFor(view),
+    data: sanitizeWidgetValue({ ...data, actions: componentActions(view) }, widgetLimits(view, data, options.privateText !== true)),
+  };
+  return Object.freeze(envelope);
+}
+
+export function validateDynamicUiEnvelope(value) {
+  if (!isPlainObject(value)) throw codeError("trae_dynamic_ui_envelope_invalid");
+  assertExactKeys(value, ["contract", "version", "renderer", "view", "state", "exposure", "component", "data"]);
+  if (value.contract !== TRAE_DYNAMIC_UI_CONTRACT || value.version !== TRAE_DYNAMIC_UI_VERSION
+    || value.renderer !== TRAE_DYNAMIC_UI_RENDERER || !VIEWS.has(value.view)
+    || !STATES.has(value.state) || !EXPOSURES.has(value.exposure)) {
+    throw codeError("trae_dynamic_ui_envelope_invalid");
+  }
+  validateComponent(value.component, value.view);
+  sanitizeWidgetValue(value.data, widgetLimits(value.view, value.data));
+  return value;
+}
+
+export function sanitizeWidgetText(value, maximumBytes = 20_000) {
+  return normalizeWidgetText(value, maximumBytes)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+export function maskHelloLynkId(value) {
+  const hellolynkId = safeHelloLynkId(value);
+  const region = hellolynkId.split(":")[1];
+  const digest = crypto.createHash("sha256").update(hellolynkId).digest("hex").slice(0, 8);
+  return `hellolynk:${region}:masked-${digest}`;
+}
+
+export function projectInboxView(raw) {
+  const messages = safeArray(raw?.messages, "trae_inbox_contract_invalid");
+  const items = messages.map((message) => {
+    const item = plain(message, "trae_inbox_contract_invalid");
+    return {
+      localMessageId: safeId(item.localMessageId, "trae_inbox_contract_invalid"),
+      senderPrincipalDisplayName: optionalWidgetText(item.senderPrincipalDisplayName, 320),
+      senderDelegateDisplayName: optionalWidgetText(item.senderDelegateDisplayName, 320),
+      peerHelloLynkIdMasked: item.peerHelloLynkId == null ? null : maskHelloLynkId(item.peerHelloLynkId),
+      messageType: safeId(item.messageType, "trae_inbox_contract_invalid"),
+      unread: boolean(item.unread, "trae_inbox_contract_invalid"),
+      createdAt: safeTimestamp(item.createdAt, "trae_inbox_contract_invalid"),
+      updatedAt: safeTimestamp(item.updatedAt, "trae_inbox_contract_invalid"),
+      bodyAvailable: true,
+    };
+  });
+  const unreadCount = items.filter((item) => item.unread).length;
+  return createDynamicUiEnvelope("inbox", items.length ? "ready" : "empty", {
+    counts: { total: items.length, unread: unreadCount },
+    items,
+    controls: {
+      readMessageTool: "hellolynk_read_inbox_message",
+      markReadTool: "hellolynk_mark_inbox_message_read",
+      deleteReadTool: "hellolynk_delete_read_inbox_messages",
+    },
+  }, { exposure: "metadata-only" });
+}
+
+function componentFor(view) {
+  return view === "send" ? "message-form" : view === "action" ? "message-confirm"
+    : view === "status" || view === "error" ? "status-card" : "messenger-inbox";
+}
+function componentActions(view) {
+  if (view === "inbox") return [{ id: "refresh", label: "刷新消息", type: "tool-call", tool: "hellolynk_render_inbox", params: {} }, { id: "open-detail", label: "打开消息", type: "tool-call", tool: "hellolynk_read_inbox_message", params: {} }];
+  if (view === "contacts") return [{ id: "refresh-contacts", label: "刷新联系人", type: "tool-call", tool: "hellolynk_render_contacts", params: {} }];
+  if (view === "outbox") return [{ id: "refresh-outbox", label: "刷新发出记录", type: "tool-call", tool: "hellolynk_render_outbox", params: {} }];
+  return [];
+}
+function validateComponent(value, view) {
+  if (value !== componentFor(view)) throw codeError("trae_dynamic_ui_envelope_invalid");
+}
+
+// Private-only dashboard payload. It is deliberately never used as
+// structuredContent: internal contract tests use this model-safe projection.
+// Production TRAE exposes only open/status tools; the fixed local Web UI reads
+// private data directly from the neutral Host adapter over the loopback server.
+export function projectPrivateInboxDashboard(inboxRaw, contactsRaw, requestsRaw, outboxRaw) {
+  const messages = safeArray(inboxRaw?.messages, "trae_inbox_contract_invalid").map((item) => ({
+    localMessageId: safeId(item?.localMessageId, "trae_inbox_contract_invalid"),
+    peerHelloLynkId: safeHelloLynkId(item?.peerHelloLynkId),
+    senderPrincipalDisplayName: optionalWidgetText(item?.senderPrincipalDisplayName, 320),
+    senderDelegateDisplayName: optionalWidgetText(item?.senderDelegateDisplayName, 320),
+    messageType: safeId(item?.messageType, "trae_inbox_contract_invalid"),
+    text: checkedWidgetText(item?.text, 64 * 1024), unread: boolean(item?.unread, "trae_inbox_contract_invalid"),
+    createdAt: safeTimestamp(item?.createdAt, "trae_inbox_contract_invalid"),
+  }));
+  const contacts = safeArray(contactsRaw?.contacts, "trae_contacts_contract_invalid").map((item) => ({
+    contactId: safeId(item?.contactId, "trae_contacts_contract_invalid"), hellolynkId: safeHelloLynkId(item?.hellolynkId),
+    displayName: checkedWidgetText(item?.displayName, 320),
+    updatedAt: safeTimestamp(item?.updatedAt, "trae_contacts_contract_invalid"),
+  }));
+  const contactRequests = safeArray(requestsRaw?.requests, "trae_contact_requests_contract_invalid").map((item) => {
+    if (item?.humanOnly !== true || item?.modelVisibility !== "none") throw codeError("trae_contact_requests_contract_invalid");
+    return {
+      localRecordId: safeId(item?.localRecordId, "trae_contact_requests_contract_invalid"),
+      state: safeId(item?.state, "trae_contact_requests_contract_invalid"),
+      introText: item?.introText == null ? null : checkedWidgetText(item.introText, 20_000),
+      senderHelloLynkId: item?.sender?.hellolynkId == null ? null : safeHelloLynkId(item.sender.hellolynkId),
+      senderDisplayName: item?.sender?.verifiedDisplayName == null ? null : checkedWidgetText(item.sender.verifiedDisplayName, 320),
+    };
+  });
+  const outbox = safeArray(outboxRaw?.messages, "trae_outbox_contract_invalid").map((item) => ({
+    clientMessageId: safeId(item?.clientMessageId, "trae_outbox_contract_invalid"), recipientHelloLynkId: safeHelloLynkId(item?.recipientHelloLynkId),
+    text: checkedWidgetText(item?.text, 64 * 1024), status: safeId(item?.status, "trae_outbox_contract_invalid"),
+    retryAllowed: boolean(item?.retryAllowed, "trae_outbox_contract_invalid"), createdAt: safeTimestamp(item?.createdAt, "trae_outbox_contract_invalid"),
+  }));
+  return createDynamicUiEnvelope("inbox", messages.length ? "ready" : "empty", {
+    dashboard: { messages, contacts, contactRequests, outbox },
+    controls: { markReadTool: "hellolynk_mark_inbox_message_read", deleteReadTool: "hellolynk_delete_read_inbox_messages", retryTool: "hellolynk_retry_outbox_message", submitTool: "hellolynk_request_human_send", saveContactTool: "hellolynk_save_contact", deleteContactTool: "hellolynk_delete_contact" },
+  }, { exposure: "selected-content", privateText: true });
+}
+
+export function projectSelectedMessage(raw, localMessageId) {
+  const messages = safeArray(raw?.messages, "trae_inbox_contract_invalid");
+  const selected = messages.find((item) => item?.localMessageId === localMessageId);
+  if (!selected) throw codeError("host_app_record_not_found");
+  return createDynamicUiEnvelope("message", "ready", {
+    localMessageId: safeId(selected.localMessageId, "trae_inbox_contract_invalid"),
+    senderPrincipalDisplayName: optionalWidgetText(selected.senderPrincipalDisplayName, 320),
+    senderDelegateDisplayName: optionalWidgetText(selected.senderDelegateDisplayName, 320),
+    peerHelloLynkIdMasked: selected.peerHelloLynkId == null ? null : maskHelloLynkId(selected.peerHelloLynkId),
+    messageType: safeId(selected.messageType, "trae_inbox_contract_invalid"),
+    text: checkedWidgetText(selected.text, 64 * 1024),
+    unread: boolean(selected.unread, "trae_inbox_contract_invalid"),
+    createdAt: safeTimestamp(selected.createdAt, "trae_inbox_contract_invalid"),
+    controls: { markReadTool: "hellolynk_mark_inbox_message_read" },
+  }, { exposure: "selected-content", privateText: true });
+}
+
+export function projectSelectedMessageMetadata(raw, localMessageId) {
+  const messages = safeArray(raw?.messages, "trae_inbox_contract_invalid");
+  const selected = messages.find((item) => item?.localMessageId === localMessageId);
+  if (!selected) throw codeError("host_app_record_not_found");
+  return createDynamicUiEnvelope("message", "ready", {
+    localMessageId: safeId(selected.localMessageId, "trae_inbox_contract_invalid"),
+    senderPrincipalDisplayName: optionalWidgetText(selected.senderPrincipalDisplayName, 320),
+    senderDelegateDisplayName: optionalWidgetText(selected.senderDelegateDisplayName, 320),
+    peerHelloLynkIdMasked: selected.peerHelloLynkId == null ? null : maskHelloLynkId(selected.peerHelloLynkId),
+    messageType: safeId(selected.messageType, "trae_inbox_contract_invalid"),
+    unread: boolean(selected.unread, "trae_inbox_contract_invalid"),
+    createdAt: safeTimestamp(selected.createdAt, "trae_inbox_contract_invalid"),
+    bodyAvailableInPrivateUi: true,
+    bodyExcludedFromModelResult: true,
+  }, { exposure: "selected-record" });
+}
+
+export function projectContactsView(contactsRaw, requestsRaw) {
+  const contacts = safeArray(contactsRaw?.contacts, "trae_contacts_contract_invalid").map((contact) => ({
+    contactId: safeId(contact?.contactId, "trae_contacts_contract_invalid"),
+    displayName: checkedWidgetText(contact?.displayName, 320),
+    hellolynkIdMasked: maskHelloLynkId(contact?.hellolynkId),
+    updatedAt: safeTimestamp(contact?.updatedAt, "trae_contacts_contract_invalid"),
+  }));
+  const requests = safeArray(requestsRaw?.requests, "trae_contact_requests_contract_invalid");
+  const requestCounts = Object.create(null);
+  for (const request of requests) {
+    if (request?.modelVisibility !== "none" || request?.humanOnly !== true) {
+      throw codeError("trae_contact_requests_contract_invalid");
+    }
+    const state = safeId(request.state, "trae_contact_requests_contract_invalid");
+    requestCounts[state] = (requestCounts[state] || 0) + 1;
+  }
+  return createDynamicUiEnvelope("contacts", contacts.length || requests.length ? "ready" : "empty", {
+    counts: { contacts: contacts.length, contactRequests: requests.length },
+    contacts,
+    contactRequests: {
+      countsByState: requestCounts,
+      detailsWithheld: true,
+      reason: "host_model_visibility_none",
+    },
+    controls: {
+      contactDetailTool: "hellolynk_get_contact_detail",
+      saveContactTool: "hellolynk_save_contact",
+      deleteContactTool: "hellolynk_delete_contact",
+    },
+  }, { exposure: "metadata-only" });
+}
+
+export function projectContactDetail(raw, contactId) {
+  const contact = safeArray(raw?.contacts, "trae_contacts_contract_invalid")
+    .find((item) => item?.contactId === contactId);
+  if (!contact) throw codeError("host_app_record_not_found");
+  return createDynamicUiEnvelope("contact", "ready", {
+    contactId: safeId(contact.contactId, "trae_contacts_contract_invalid"),
+    displayName: checkedWidgetText(contact.displayName, 320),
+    hellolynkId: safeHelloLynkId(contact.hellolynkId),
+    updatedAt: safeTimestamp(contact.updatedAt, "trae_contacts_contract_invalid"),
+    controls: { saveContactTool: "hellolynk_save_contact", deleteContactTool: "hellolynk_delete_contact" },
+  }, { exposure: "selected-record" });
+}
+
+export function projectOutboxView(raw) {
+  const messages = safeArray(raw?.messages, "trae_outbox_contract_invalid").map((message) => ({
+    clientMessageId: safeId(message?.clientMessageId, "trae_outbox_contract_invalid"),
+    recipientHelloLynkIdMasked: maskHelloLynkId(message?.recipientHelloLynkId),
+    messageType: safeId(message?.messageType, "trae_outbox_contract_invalid"),
+    status: safeId(message?.status, "trae_outbox_contract_invalid"),
+    retryAllowed: boolean(message?.retryAllowed, "trae_outbox_contract_invalid"),
+    createdAt: safeTimestamp(message?.createdAt, "trae_outbox_contract_invalid"),
+    updatedAt: safeTimestamp(message?.updatedAt, "trae_outbox_contract_invalid"),
+  }));
+  return createDynamicUiEnvelope("outbox", messages.length ? "ready" : "empty", {
+    counts: {
+      total: messages.length,
+      retryable: messages.filter((item) => item.retryAllowed).length,
+    },
+    items: messages,
+    controls: { retryTool: "hellolynk_retry_outbox_message" },
+  }, { exposure: "metadata-only" });
+}
+
+export function projectSendForm(contactsRaw) {
+  const contacts = safeArray(contactsRaw?.contacts, "trae_contacts_contract_invalid").map((contact) => ({
+    contactId: safeId(contact?.contactId, "trae_contacts_contract_invalid"),
+    displayName: checkedWidgetText(contact?.displayName, 320),
+    hellolynkIdMasked: maskHelloLynkId(contact?.hellolynkId),
+  }));
+  return createDynamicUiEnvelope("send", "ready", {
+    contacts,
+    fields: [
+      { name: "contactId", type: "contact-select", required: false },
+      { name: "recipientHelloLynkId", type: "hellolynk-id", required: false },
+      { name: "text", type: "multiline-text", required: true, maximumLength: 20_000 },
+    ],
+    controls: {
+      submitTool: "hellolynk_request_human_send",
+      submitRequiresExplicitConfirmation: true,
+      hostNativeConfirmationStillRequired: true,
+    },
+  }, { exposure: "metadata-only" });
+}
+
+export function projectActionView(value, message) {
+  const state = String(value?.state || "");
+  if (!/^(pending|approved|cancelled|consuming|expired|failed|invalidated)$/.test(state)) {
+    throw codeError("human_action_status_invalid");
+  }
+  const createdAtMs = safeInteger(value?.createdAtMs, "human_action_status_invalid");
+  const expiresAtMs = safeInteger(value?.expiresAtMs, "human_action_status_invalid");
+  if (expiresAtMs < createdAtMs || (value?.code != null
+    && !/^human_confirmation_[a-z0-9_]{1,100}$/.test(String(value.code)))) {
+    throw codeError("human_action_status_invalid");
+  }
+  return createDynamicUiEnvelope("action", state === "pending" ? "pending" : "ready", {
+    message: checkedWidgetText(message, 500),
+    actionId: safeId(value?.actionId, "human_action_status_invalid"),
+    state,
+    createdAtMs,
+    expiresAtMs,
+    ...(typeof value?.idempotent === "boolean" ? { idempotent: value.idempotent } : {}),
+    ...(value?.code == null ? {} : { code: value.code }),
+  }, { exposure: "aggregate-only" });
+}
+
+export function projectErrorView(errorCode) {
+  return createDynamicUiEnvelope("error", "blocked", {
+    errorCode: safeId(errorCode, "trae_dynamic_ui_error_invalid"),
+  }, { exposure: "aggregate-only" });
+}
+
+function widgetLimits(view, data, escapeHtml = false) {
+  return {
+    maximumDepth: 8, maximumItems: 500, escapeHtml,
+    // The Host contract counts authorized instance routes, not unique contacts.
+    // Only this root array gets its 1,000-row budget, in both encode and validate.
+    maximumAuthorizedContacts: view === "status" && Array.isArray(data?.authorizedContacts) ? 1_000 : 500,
+  };
+}
+
+function sanitizeWidgetValue(value, limits, depth = 0, seen = new Set(), field = "") {
+  if (value == null || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value)) throw codeError("trae_dynamic_ui_value_invalid");
+    return value;
+  }
+  if (typeof value === "string") return limits.escapeHtml
+    ? sanitizeWidgetText(value, 64 * 1024)
+    : normalizeWidgetText(value, 64 * 1024);
+  if (typeof value !== "object" || seen.has(value) || depth >= limits.maximumDepth) {
+    throw codeError("trae_dynamic_ui_value_invalid");
+  }
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const maximum = depth === 1 && field === "authorizedContacts" ? limits.maximumAuthorizedContacts : limits.maximumItems;
+      if (value.length > maximum) throw codeError("trae_dynamic_ui_value_invalid");
+      return value.map((item) => sanitizeWidgetValue(item, limits, depth + 1, seen));
+    }
+    if (!isPlainObject(value)) throw codeError("trae_dynamic_ui_value_invalid");
+    const entries = Object.entries(value);
+    if (entries.length > limits.maximumItems) throw codeError("trae_dynamic_ui_value_invalid");
+    const result = {};
+    for (const [key, nested] of entries) {
+      if (!/^[A-Za-z][A-Za-z0-9_]{0,79}$/.test(key) || FORBIDDEN_KEYS.has(key)) {
+        throw codeError("trae_dynamic_ui_key_invalid");
+      }
+      result[key] = sanitizeWidgetValue(nested, limits, depth + 1, seen, key);
+    }
+    return result;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+function normalizeWidgetText(value, maximumBytes) {
+  if (typeof value !== "string" || Buffer.byteLength(value, "utf8") > maximumBytes || value.includes("\0")) {
+    throw codeError("trae_dynamic_ui_text_invalid");
+  }
+  return value.replace(/[\u0001-\u0008\u000B\u000C\u000E-\u001F\u007F\u202A-\u202E\u2066-\u2069]/g, "");
+}
+
+function safeArray(value, code) {
+  if (!Array.isArray(value) || value.length > 1_000) throw codeError(code);
+  return value;
+}
+function plain(value, code) { if (!isPlainObject(value)) throw codeError(code); return value; }
+function safeId(value, code) { const text = String(value || ""); if (!ID.test(text)) throw codeError(code); return text; }
+function safeHelloLynkId(value) { const text = String(value || ""); if (!HELLOLYNK_ID.test(text)) throw codeError("trae_hellolynk_id_invalid"); return text; }
+function safeTimestamp(value, code) {
+  const text = String(value || "");
+  if (!ISO_TIMESTAMP.test(text) || new Date(text).toISOString() !== text) throw codeError(code);
+  return text;
+}
+function safeInteger(value, code) { const number = Number(value); if (!Number.isSafeInteger(number) || number < 0) throw codeError(code); return number; }
+function boolean(value, code) { if (typeof value !== "boolean") throw codeError(code); return value; }
+function checkedWidgetText(value, maximumBytes) {
+  if (typeof value !== "string" || Buffer.byteLength(value, "utf8") > maximumBytes || value.includes("\0")) {
+    throw codeError("trae_dynamic_ui_text_invalid");
+  }
+  return value;
+}
+function optionalWidgetText(value, maximumBytes) { return value == null ? null : checkedWidgetText(value, maximumBytes); }
+function assertExactKeys(value, expected) {
+  const actual = Object.keys(value).sort(); const wanted = [...expected].sort();
+  if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+    throw codeError("trae_dynamic_ui_envelope_invalid");
+  }
+}
+function isPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value); return proto === Object.prototype || proto === null;
+}
+function codeError(code) { const error = new Error(code); error.code = code; return error; }

package/integrations/trae-work/server/host-lifecycle.mjs

@@ -0,0 +1,128 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { launchPinnedNeutralHostBootstrap } from "../../../runtime/core/hellolynk-neutral-host-launcher.mjs";
+
+const RUNNER_RELATIVE = "runtime/neutral-host-bootstrap.mjs";
+const LOCK_STALE_MS = 10_000;
+const SAFE_RELATIVE = /^(?:[A-Za-z0-9][A-Za-z0-9._-]*\/)*[A-Za-z0-9][A-Za-z0-9._-]*\.(?:cjs|mjs|ps1)$/;
+// The TRAE server entry points are part of the pinned closure. Shared Workbench
+// runtime modules are pinned separately by REQUIRED_RUNTIME_RECORDS below.
+const REQUIRED_RELEASE_RECORDS = Object.freeze([
+  "release/integrations/trae-work/package.json",
+  "release/integrations/trae-work/server/trae-neutral-production.mjs", "release/integrations/trae-work/server/mcp-proxy.mjs",
+  "release/integrations/trae-work/server/mcp-server.mjs", "release/integrations/trae-work/server/neutral-host-adapter.mjs",
+  "release/integrations/trae-work/server/dynamic-ui-contract.mjs",
+  "release/integrations/trae-work/server/ui-action-gate.mjs", "release/integrations/trae-work/server/host-lifecycle.mjs",
+  "release/integrations/trae-work/server/trae-ui-launch.mjs",
+  "release/integrations/trae-work/server/native-task-cdp.mjs", "release/integrations/trae-work/server/native-task-worker.mjs",
+  "release/integrations/trae-work/skills/hellolynk-inbox/SKILL.md",
+]);
+const REQUIRED_RUNTIME_RECORDS = Object.freeze([
+  "neutral-host-bootstrap.mjs", "neutral-host-release-loader.mjs", "neutral-host-release-entry.mjs",
+  "bootstrap/core/hellolynk-host-protected-store.mjs", "bootstrap/core/hellolynk-neutral-host-installation-store.mjs",
+  "bootstrap/core/hellolynk-host-auth.mjs", "bootstrap/core/hellolynk-client-profile.mjs",
+  "bootstrap/core/hellolynk-platform-credential-store.mjs", "bootstrap/core/hellolynk-client-core.mjs",
+  "bootstrap/platform/windows/hellolynk-host-protected-store.ps1",
+  "core/hellolynk-local-data-migration.mjs", "core/hellolynk-local-data-protection.mjs",
+  "core/hellolynk-local-identity-trust.mjs",
+  "core/hellolynk-neutral-host-workbench-read-model.mjs",
+  "core/hellolynk-native-worker-lease.mjs",
+  "core/hellolynk-workbench-action-grants.mjs",
+  "platform/windows/hellolynk-local-data-key.ps1", "workbench/contract.mjs",
+  "workbench/candidate-bootstrap.mjs",
+]);
+
+export async function launchTraeWorkNeutralHost(binding, options = {}) {
+  const launch = normalizeLaunchBinding(binding, options);
+  await verifyPinnedBootstrap(launch);
+  const lockPath = path.join(launch.runtimeRoot, "neutral-host", `${tupleDigest(launch)}.trae-work-launch.lock`);
+  await ensureSafeDirectory(launch.runtimeRoot, true); await ensureSafeDirectory(path.dirname(lockPath), true);
+  const wait = options.wait || delay; const deadline = Date.now() + bounded(options.lockTimeoutMs, 15_000, 500, 60_000);
+  let ownsLock = false;
+  while (Date.now() < deadline) {
+    try {
+      await fs.mkdir(lockPath, { mode: 0o700 });
+      await fs.writeFile(path.join(lockPath, "owner.json"), `${JSON.stringify({ contract: "hellolynk-trae-work-host-launch-lock-v1", pid: process.pid, createdAtMs: Date.now() })}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+      ownsLock = true; break;
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw codeError("neutral_trae_work_launch_failed");
+      await ensureSafeDirectory(lockPath, false); await reclaimDeadLock(lockPath).catch(() => false); await wait(50);
+    }
+  }
+  if (!ownsLock) throw codeError("neutral_trae_work_launch_lock_timeout");
+  try {
+    await launchPinnedNeutralHostBootstrap(launch, {
+      storeRoot: launch.storeRoot,
+      ...(options.spawnRunner ? { spawnRunner: options.spawnRunner } : {}),
+      ...(options.bootstrapObservationMs !== undefined ? { bootstrapObservationMs: options.bootstrapObservationMs } : {}),
+      ...(options.bootstrapFailureObservationMs !== undefined ? { bootstrapFailureObservationMs: options.bootstrapFailureObservationMs } : {}),
+      ...(options.bootstrapFailureDeadlineMs !== undefined ? { bootstrapFailureDeadlineMs: options.bootstrapFailureDeadlineMs } : {}),
+      env: options.env || process.env,
+    });
+    return Object.freeze({ started: true, owner: "trae_work_mcp_process" });
+  } finally {
+    await fs.rm(path.join(lockPath, "owner.json"), { force: true }).catch(() => {}); await fs.rmdir(lockPath).catch(() => {});
+  }
+}
+
+export async function verifyPinnedBootstrap(binding, options = {}) {
+  const launch = normalizeLaunchBinding(binding, options);
+  const [pinBytes, manifestBytes] = await Promise.all([
+    readSafeFile(path.join(launch.releaseRoot, "runtime", "neutral-host-release-pin.json"), 16 * 1024),
+    readSafeFile(path.join(launch.releaseRoot, "runtime", "neutral-host-release-manifest.json"), 256 * 1024),
+  ]);
+  const pin = parseJson(pinBytes); const manifest = parseJson(manifestBytes);
+  if (!plain(pin) || !exactKeys(pin, ["contract", "manifestSha256"]) || pin.contract !== "hellolynk-neutral-host-release-pin-v1"
+    || pin.manifestSha256 !== launch.releaseManifestSha256 || sha256(manifestBytes) !== launch.releaseManifestSha256
+    || !plain(manifest) || !exactKeys(manifest, ["contract", "entry", "files"])
+    || manifest.contract !== "hellolynk-neutral-host-release-manifest-v1" || manifest.entry !== "neutral-host-release-entry.mjs"
+    || !Array.isArray(manifest.files) || manifest.files.length < 39 || manifest.files.length > 256) fail();
+  const records = new Map(); const resolvedPaths = new Map();
+  for (const item of manifest.files) {
+    if (!plain(item) || !exactKeys(item, ["path", "sha256"]) || !/^[a-f0-9]{64}$/.test(String(item.sha256 || ""))) fail();
+    const recordPath = String(item.path || ""); const file = resolveManifestFile(launch, recordPath); const canonical = canonicalPath(file);
+    if (records.has(recordPath) || resolvedPaths.has(canonical)) fail();
+    const bytes = await readSafeFile(file, 2 * 1024 * 1024).catch(() => fail()); if (sha256(bytes) !== item.sha256) fail();
+    const record = Object.freeze({ recordPath, file, bytes }); records.set(recordPath, record); resolvedPaths.set(canonical, record);
+  }
+  for (const required of [...REQUIRED_RUNTIME_RECORDS, ...REQUIRED_RELEASE_RECORDS]) if (!records.has(required)) fail();
+  if (!samePath(records.get("neutral-host-bootstrap.mjs").file, launch.bootstrapPath) || !records.has(manifest.entry)) fail();
+  verifyStaticImportClosure(records, resolvedPaths, launch.releaseRoot);
+  return Object.freeze({ ok: true, bootstrapPath: launch.bootstrapPath, verifiedFileCount: records.size });
+}
+
+function resolveManifestFile(launch, recordPath) {
+  if (recordPath.startsWith("release/")) {
+    if (!REQUIRED_RELEASE_RECORDS.includes(recordPath)) fail();
+    return insideRoot(launch.releaseRoot, recordPath.slice(8));
+  }
+  if (!SAFE_RELATIVE.test(recordPath) || recordPath.split("/").includes("..")) fail(); return insideRoot(path.join(launch.releaseRoot, "runtime"), recordPath);
+}
+function verifyStaticImportClosure(records, resolvedPaths, releaseRoot) {
+  const pattern = /(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+)["'](\.{1,2}\/[^"']+)["']/g;
+  for (const record of records.values()) {
+    if (!record.file.endsWith(".mjs")) continue; const source = record.bytes.toString("utf8"); pattern.lastIndex = 0;
+    for (let match = pattern.exec(source); match; match = pattern.exec(source)) {
+      const imported = path.resolve(path.dirname(record.file), ...match[1].split("/"));
+      if (!inside(releaseRoot, imported) || !resolvedPaths.has(canonicalPath(imported))) fail();
+    }
+  }
+}
+function normalizeLaunchBinding(value, options) {
+  if (!plain(value)) throw codeError("neutral_trae_work_launch_configuration_required");
+  const runtimeRoot = absolute(value.runtimeRoot); const releaseRoot = absolute(value.releaseRoot); const profileManifestPath = absolute(value.profileManifestPath);
+  const releaseManifestSha256 = String(value.releaseManifestSha256 || "");
+  if (value.runnerRelativePath !== RUNNER_RELATIVE || !/^[a-f0-9]{64}$/.test(releaseManifestSha256) || path.basename(runtimeRoot).toLowerCase() !== "runtime") throw codeError("neutral_trae_work_launch_configuration_required");
+  const derivedStoreRoot = path.dirname(runtimeRoot); const storeRoot = options.storeRoot ? absolute(options.storeRoot) : derivedStoreRoot;
+  if (!samePath(storeRoot, derivedStoreRoot)) throw codeError("neutral_trae_work_launch_configuration_required");
+  return Object.freeze({ runtimeRoot, releaseRoot, profileManifestPath, releaseManifestSha256, storeRoot, runnerRelativePath: RUNNER_RELATIVE,
+    bootstrapPath: path.join(releaseRoot, ...RUNNER_RELATIVE.split("/")), region: safeId(value.region), principalId: safeId(value.principalId), delegateId: safeId(value.delegateId), hostInstallationId: safeId(value.hostInstallationId), profileId: safeId(value.profileId), adapterId: value.adapterId === "trae-work" ? "trae-work" : fail(), version: Number(value.version), scopes: Object.freeze([...(value.scopes || [])].map(String)) });
+}
+async function readSafeFile(file, maximum) { await assertNoReparseAncestors(file); let handle; try { handle = await fs.open(file, "r"); } catch { throw codeError("neutral_trae_work_runner_unavailable"); } try { const before = await handle.stat({ bigint: true }); if (!before.isFile() || before.nlink !== 1n || before.size > BigInt(maximum)) fail(); const bytes = await handle.readFile(); const after = await handle.stat({ bigint: true }); if (!sameIdentity(before, after)) fail(); return bytes; } catch (error) { if (/^neutral_trae_work_/.test(String(error?.code || ""))) throw error; throw codeError("neutral_trae_work_runner_integrity_invalid"); } finally { await handle.close().catch(() => {}); } }
+async function assertNoReparseAncestors(target) { const resolved = path.resolve(target); const parsed = path.parse(resolved); let cursor = parsed.root; for (const segment of path.relative(parsed.root, resolved).split(path.sep).filter(Boolean)) { cursor = path.join(cursor, segment); const metadata = await fs.lstat(cursor).catch(() => { throw codeError("neutral_trae_work_runner_unavailable"); }); if (metadata.isSymbolicLink()) throw codeError("neutral_trae_work_runner_integrity_invalid"); } }
+async function ensureSafeDirectory(target, create) { if (create) await fs.mkdir(target, { recursive: true, mode: 0o700 }); const metadata = await fs.lstat(target).catch(() => null); if (!metadata?.isDirectory() || metadata.isSymbolicLink()) throw codeError("neutral_trae_work_launch_configuration_required"); }
+async function reclaimDeadLock(lockPath) { const metadata = await fs.lstat(lockPath); let owner; try { owner = JSON.parse(await fs.readFile(path.join(lockPath, "owner.json"), "utf8")); } catch { return false; } const pid = Number(owner?.pid); if (Date.now() - metadata.mtimeMs <= LOCK_STALE_MS || (Number.isSafeInteger(pid) && pid > 0 && processAlive(pid))) return false; await fs.rm(path.join(lockPath, "owner.json"), { force: true }); await fs.rmdir(lockPath).catch(() => {}); return true; }
+function insideRoot(root, relative) { const result = path.resolve(root, ...relative.split("/")); if (!inside(root, result)) fail(); return result; }
+function inside(root, target) { const relative = path.relative(path.resolve(root), path.resolve(target)); return Boolean(relative) && !relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative); }
+function tupleDigest(value) { return sha256(`${value.region}\0${value.principalId}\0${value.hostInstallationId}`); } function sha256(value) { return crypto.createHash("sha256").update(value).digest("hex"); } function parseJson(value) { try { return JSON.parse(value); } catch { fail(); } } function sameIdentity(left, right) { return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeNs === right.mtimeNs && left.nlink === right.nlink; } function processAlive(pid) { try { process.kill(pid, 0); return true; } catch (error) { return error?.code === "EPERM"; } } function safeId(value) { const result = String(value || ""); if (!/^[A-Za-z0-9][A-Za-z0-9_.:-]{2,198}$/.test(result)) fail(); return result; } function absolute(value) { const result = String(value || ""); if (!path.isAbsolute(result) || path.resolve(result) !== result) fail(); return result; } function samePath(left, right) { return process.platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right; } function canonicalPath(value) { const result = path.resolve(value); return process.platform === "win32" ? result.toLowerCase() : result; } function exactKeys(value, expected) { const actual = Object.keys(value).sort(); const wanted = [...expected].sort(); return actual.length === wanted.length && actual.every((item, index) => item === wanted[index]); } function bounded(value, fallback, minimum, maximum) { const result = Number(value ?? fallback); return Number.isSafeInteger(result) && result >= minimum && result <= maximum ? result : fallback; } function plain(value) { return Boolean(value) && typeof value === "object" && !Array.isArray(value); } function delay(ms) { return new Promise((resolve) => setTimeout(resolve, ms)); } function fail() { throw codeError("neutral_trae_work_runner_integrity_invalid"); } function codeError(code) { const error = new Error(code); error.code = code; return error; }