@threads-weave/openclaw-agentic-weave 0.1.0

package/index.js

@@ -0,0 +1,1258 @@
+import { execFile, spawn } from "node:child_process";
+import fs from "node:fs";
+import { promises as fsp } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PLUGIN_PACKAGE_ROOT = __dirname;
+const BUNDLED_SIDE_CAR_PATH = path.resolve(
+  PLUGIN_PACKAGE_ROOT,
+  "sidecar/threads_weaving_sidecar.cjs",
+);
+const DEFAULT_SIDE_CAR_PATH = BUNDLED_SIDE_CAR_PATH;
+
+const PLUGIN_ID = "openclaw-agentic-weave";
+const SIDE_CAR_CLIENT_TYPE = "threads-weave-sidecar";
+const SIDE_CAR_VERSION = "0.1.0";
+const DEFAULT_PROTOCOL_VERSION = "2025-03-26";
+const MANAGEMENT_COMMAND = "openclaw-agentic-weave";
+const TOOL_NAME_PREFIX = "threads_weave_";
+const DEFAULT_SERVER_URL = "https://threads-weave.com";
+const DEFAULT_OPENCLAW_CONFIG_PATH = path.join(os.homedir(), ".openclaw", "openclaw.json");
+const DEFAULT_PLUGIN_SECRET_STORAGE = "auto";
+const DEFAULT_REQUEST_TIMEOUT_MS = 45000;
+const DEFAULT_STOP_GRACE_PERIOD_MS = 3000;
+const DEFAULT_FORCE_KILL_TIMEOUT_MS = 1000;
+const TOOL_DEFINITIONS = JSON.parse(
+  fs.readFileSync(path.join(__dirname, "tool-definitions.json"), "utf8"),
+);
+
+const WRITE_TOOL_NAMES = new Set([
+  "sidecar.collect_item",
+  "sidecar.record_recommendation_feedback",
+  "sidecar.participate_claim",
+  "sidecar.save_post_draft",
+  "sidecar.create_post",
+  "sidecar.create_thread_node",
+  "sidecar.claim_and_create_thread_node",
+  "sidecar.set_node_content_ttl",
+]);
+
+function createLogger(api) {
+  const logger = api && api.logger ? api.logger : console;
+  return {
+    debug(message, meta) {
+      if (typeof logger.debug === "function") {
+        logger.debug(message, meta);
+      }
+    },
+    info(message, meta) {
+      if (typeof logger.info === "function") {
+        logger.info(message, meta);
+        return;
+      }
+      if (typeof logger.log === "function") {
+        logger.log(message, meta);
+      }
+    },
+    warn(message, meta) {
+      if (typeof logger.warn === "function") {
+        logger.warn(message, meta);
+        return;
+      }
+      if (typeof logger.log === "function") {
+        logger.log(message, meta);
+      }
+    },
+    error(message, meta) {
+      if (typeof logger.error === "function") {
+        logger.error(message, meta);
+        return;
+      }
+      if (typeof logger.log === "function") {
+        logger.log(message, meta);
+      }
+    },
+  };
+}
+
+function getPluginConfig(api) {
+  return (
+    api?.config?.plugins?.entries?.[PLUGIN_ID]?.config
+    ?? api?.config?.plugins?.[PLUGIN_ID]
+    ?? {}
+  );
+}
+
+function getDefaultNodeBin() {
+  return process.execPath;
+}
+
+function isTruthyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function resolveMaybeRelativePath(input, fromDir) {
+  if (!isTruthyString(input)) {
+    return null;
+  }
+  if (path.isAbsolute(input)) {
+    return input;
+  }
+  return path.resolve(fromDir, input);
+}
+
+function resolveSidecarPath(config) {
+  const configuredPath = isTruthyString(config.sidecarPath) ? config.sidecarPath.trim() : null;
+  const candidates = [];
+  if (configuredPath) {
+    if (path.isAbsolute(configuredPath)) {
+      candidates.push(configuredPath);
+    } else {
+      // Keep relative paths anchored to the published plugin package, never the current workspace.
+      candidates.push(resolveMaybeRelativePath(configuredPath, PLUGIN_PACKAGE_ROOT));
+    }
+  }
+  candidates.push(DEFAULT_SIDE_CAR_PATH);
+  for (const candidate of candidates) {
+    if (candidate && fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  if (configuredPath) {
+    return path.isAbsolute(configuredPath)
+      ? configuredPath
+      : path.resolve(PLUGIN_PACKAGE_ROOT, configuredPath);
+  }
+  return DEFAULT_SIDE_CAR_PATH;
+}
+
+function normalizeConfig(api) {
+  const raw = getPluginConfig(api);
+  const secretStorageConfigured = isTruthyString(raw.secretStorage);
+  return {
+    nodeBin: isTruthyString(raw.nodeBin) ? raw.nodeBin : getDefaultNodeBin(),
+    sidecarPath: resolveSidecarPath(raw),
+    serverUrl: isTruthyString(raw.serverUrl) ? raw.serverUrl.trim() : null,
+    profile: isTruthyString(raw.profile) ? raw.profile.trim() : "openclaw",
+    configDir: isTruthyString(raw.configDir) ? raw.configDir.trim() : null,
+    secretStorage: secretStorageConfigured
+      ? raw.secretStorage.trim()
+      : DEFAULT_PLUGIN_SECRET_STORAGE,
+    secretStorageConfigured,
+    agentName: isTruthyString(raw.agentName) ? raw.agentName.trim() : "OpenClaw",
+    agentProvider: isTruthyString(raw.agentProvider) ? raw.agentProvider.trim() : "openclaw",
+    deviceName: isTruthyString(raw.deviceName) ? raw.deviceName.trim() : os.hostname(),
+    autoStart: Boolean(raw.autoStart),
+    persistSession: Boolean(raw.persistSession),
+    startupTimeoutMs: Number.isFinite(raw.startupTimeoutMs) && raw.startupTimeoutMs >= 1000
+      ? Number(raw.startupTimeoutMs)
+      : 15000,
+    requestTimeoutMs: Number.isFinite(raw.requestTimeoutMs) && raw.requestTimeoutMs >= 1000
+      ? Number(raw.requestTimeoutMs)
+      : DEFAULT_REQUEST_TIMEOUT_MS,
+  };
+}
+
+function describeSidecarRequest(method, params) {
+  const normalizedMethod = String(method || "").trim() || "unknown";
+  if (
+    normalizedMethod === "tools/call"
+    && params
+    && typeof params === "object"
+    && isTruthyString(params.name)
+  ) {
+    return `${normalizedMethod} (${params.name.trim()})`;
+  }
+  return normalizedMethod;
+}
+
+function buildSidecarRequestTimeoutError(method, params, timeoutMs) {
+  const requestLabel = describeSidecarRequest(method, params);
+  return `Threads Weave sidecar request timed out after ${timeoutMs}ms while waiting for ${requestLabel}.`;
+}
+
+function hasChildProcessExited(child) {
+  return !child || child.exitCode !== null || child.signalCode !== null;
+}
+
+function toolNameForOpenClaw(sidecarName) {
+  return `${TOOL_NAME_PREFIX}${String(sidecarName || "")
+    .replace(/^sidecar\./, "")
+    .replace(/[^A-Za-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .toLowerCase()}`;
+}
+
+function toolLabelForOpenClaw(sidecarName) {
+  const normalized = String(sidecarName || "")
+    .replace(/^sidecar\./, "")
+    .trim();
+  if (!normalized) {
+    return "Threads Weave Tool";
+  }
+  return normalized
+    .split(/[^A-Za-z0-9]+/g)
+    .filter(Boolean)
+    .map((segment) => segment.charAt(0).toUpperCase() + segment.slice(1).toLowerCase())
+    .join(" ");
+}
+
+function sidecarNameForOpenClaw(openClawName) {
+  const normalized = String(openClawName || "").trim();
+  if (normalized.startsWith(TOOL_NAME_PREFIX)) {
+    return `sidecar.${normalized.slice(TOOL_NAME_PREFIX.length)}`;
+  }
+  return normalized;
+}
+
+function summarizeContentItems(items) {
+  if (!Array.isArray(items)) {
+    return "";
+  }
+  return items
+    .map((item) => {
+      if (!item || typeof item !== "object") {
+        return "";
+      }
+      if (typeof item.text === "string" && item.text.trim()) {
+        return item.text.trim();
+      }
+      if (typeof item.type === "string") {
+        return `[${item.type}]`;
+      }
+      return "";
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+function formatSidecarErrorPayload(payload) {
+  if (!payload || typeof payload !== "object") {
+    return "Threads Weave request failed.";
+  }
+  if (typeof payload.message === "string" && payload.message.trim()) {
+    return payload.message.trim();
+  }
+  if (typeof payload.error === "string" && payload.error.trim()) {
+    return payload.error.trim();
+  }
+  if (payload.structuredContent && typeof payload.structuredContent.error === "string") {
+    return payload.structuredContent.error;
+  }
+  if (payload.content) {
+    const summary = summarizeContentItems(payload.content);
+    if (summary) {
+      return summary;
+    }
+  }
+  return "Threads Weave request failed.";
+}
+
+function formatStructuredContentForOpenClaw(value) {
+  if (value === undefined) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch (error) {
+    return String(value);
+  }
+}
+
+function normalizeToolResultForOpenClaw(result) {
+  if (!result || typeof result !== "object" || result.isError) {
+    return result;
+  }
+  if (!Object.prototype.hasOwnProperty.call(result, "structuredContent")) {
+    return result;
+  }
+  const structuredText = formatStructuredContentForOpenClaw(result.structuredContent);
+  if (!structuredText) {
+    return result;
+  }
+  return {
+    ...result,
+    content: [
+      {
+        type: "text",
+        text: structuredText,
+      },
+    ],
+  };
+}
+
+function buildManagementToolResult(payload, summaryText) {
+  const fallbackText = formatStructuredContentForOpenClaw(payload) || "Threads Weave request completed.";
+  return {
+    content: [
+      {
+        type: "text",
+        text: isTruthyString(summaryText) ? summaryText.trim() : fallbackText,
+      },
+    ],
+    structuredContent: payload,
+  };
+}
+
+function summarizeSidecarStatus(status) {
+  const profile = isTruthyString(status?.profile) ? status.profile.trim() : "unknown";
+  return `Threads Weave profile "${profile}" paired=${String(Boolean(status?.paired))} expired=${String(Boolean(status?.expired))}`;
+}
+
+function summarizePairingAction(payload) {
+  const action = isTruthyString(payload?.action) ? payload.action.trim() : "pair";
+  const status = payload?.status && typeof payload.status === "object" ? payload.status : {};
+  const profile = isTruthyString(status.profile) ? status.profile.trim() : "unknown";
+  return `Threads Weave ${action} completed for profile "${profile}" paired=${String(Boolean(status.paired))} expired=${String(Boolean(status.expired))}`;
+}
+
+function summarizeClearAction(payload) {
+  const profile = isTruthyString(payload?.profile) ? payload.profile.trim() : "unknown";
+  if (payload?.cleared === false) {
+    return `No cached local Threads Weave pairing found for profile "${profile}".`;
+  }
+  return `Threads Weave local pairing cleared for profile "${profile}".`;
+}
+
+function summarizeDoctorResult(payload) {
+  const profile = isTruthyString(payload?.profile) ? payload.profile.trim() : "unknown";
+  const checks = Array.isArray(payload?.checks) ? payload.checks : [];
+  const failedChecks = checks
+    .filter((check) => check && check.ok === false)
+    .map((check) => (isTruthyString(check?.name) ? check.name.trim() : ""))
+    .filter(Boolean);
+  if (failedChecks.length === 0) {
+    return `Threads Weave doctor passed for profile "${profile}" (${checks.length}/${checks.length} checks ok).`;
+  }
+  return `Threads Weave doctor found issues for profile "${profile}": ${failedChecks.join(", ")}.`;
+}
+
+function shouldSuggestFileSecretStorage(errorMessage) {
+  const message = String(errorMessage || "");
+  return (
+    message.includes("Secure secret storage is required for ")
+    || message.includes("Keyring storage is unavailable for ")
+  );
+}
+
+function isSingleUsePairingCommand(command) {
+  const normalized = String(command || "").trim().toLowerCase();
+  return normalized === "pair" || normalized === "renew";
+}
+
+function maybeAugmentSecretStorageError(errorMessage, cfg, attemptedSecretStorage = cfg.secretStorage) {
+  const message = String(errorMessage || "").trim();
+  if (!message || attemptedSecretStorage === "file" || !shouldSuggestFileSecretStorage(message)) {
+    return message;
+  }
+  return `${message} To use the OpenClaw plugin on a headless host, set plugins.entries["${PLUGIN_ID}"].config.secretStorage to "file" in ${DEFAULT_OPENCLAW_CONFIG_PATH}.`;
+}
+
+async function readJsonFileWithTimeout(filePath, timeoutMs, onTimeout, getAbortError) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    try {
+      const raw = await fsp.readFile(filePath, "utf8");
+      return JSON.parse(raw);
+    } catch (error) {
+      if (typeof getAbortError === "function") {
+        const abortError = getAbortError();
+        if (abortError) {
+          throw abortError;
+        }
+      }
+      if (Date.now() >= deadline) {
+        if (typeof onTimeout === "function") {
+          onTimeout();
+        }
+        throw error;
+      }
+    }
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+}
+
+class ThreadsWeaveSidecarManager {
+  constructor(api) {
+    this.api = api;
+    this.log = createLogger(api);
+    this.child = null;
+    this.stdoutInterface = null;
+    this.stderrInterface = null;
+    this.startPromise = null;
+    this.initializePromise = null;
+    this.initialized = false;
+    this.requestCounter = 1;
+    this.pending = new Map();
+    this.readyInfo = null;
+    this.tempReadyDir = null;
+  }
+
+  get config() {
+    return normalizeConfig(this.api);
+  }
+
+  ensureSidecarConfigured() {
+    const cfg = this.config;
+    if (!isTruthyString(cfg.sidecarPath)) {
+      throw new Error(
+        "Threads Weave plugin is missing sidecarPath. Reinstall the package so the bundled sidecar is present, or configure sidecarPath explicitly.",
+      );
+    }
+    if (!fs.existsSync(cfg.sidecarPath)) {
+      throw new Error(
+        `Threads Weave sidecar not found at ${cfg.sidecarPath}. Reinstall the package or point sidecarPath at a valid threads_weaving_sidecar.cjs.`,
+      );
+    }
+    if (!String(cfg.sidecarPath).endsWith(".cjs")) {
+      throw new Error(
+        `Threads Weave sidecar must be a Node.js .cjs entrypoint. Received ${cfg.sidecarPath}.`,
+      );
+    }
+    return cfg;
+  }
+
+  buildBaseArgs(cfg) {
+    const args = [];
+    if (isTruthyString(cfg.configDir)) {
+      args.push("--config-dir", cfg.configDir);
+    }
+    return args;
+  }
+
+  buildProfileArgs(cfg) {
+    return [
+      "--profile",
+      cfg.profile,
+    ];
+  }
+
+  buildAgentRuntimeArgs(cfg, secretStorageOverride = null) {
+    const secretStorage = isTruthyString(secretStorageOverride)
+      ? secretStorageOverride.trim()
+      : cfg.secretStorage;
+    const args = [
+      ...this.buildProfileArgs(cfg),
+      "--device-name",
+      cfg.deviceName,
+      "--client-type",
+      SIDE_CAR_CLIENT_TYPE,
+      "--sidecar-version",
+      SIDE_CAR_VERSION,
+      "--agent-name",
+      cfg.agentName,
+      "--agent-provider",
+      cfg.agentProvider,
+      "--secret-storage",
+      secretStorage,
+      "--non-interactive",
+    ];
+    return args;
+  }
+
+  getSecretStorageCandidates(cfg) {
+    const preferred = isTruthyString(cfg.secretStorage)
+      ? cfg.secretStorage.trim()
+      : DEFAULT_PLUGIN_SECRET_STORAGE;
+    if (preferred === "file") {
+      return ["file"];
+    }
+    if (preferred === "auto") {
+      return ["auto", "file"];
+    }
+    return [preferred];
+  }
+
+  extractCommandErrorMessage(error, command) {
+    const details = [
+      error?.stderr,
+      error?.stdout,
+      error?.message,
+    ]
+      .map((item) => (typeof item === "string" ? item.trim() : ""))
+      .filter(Boolean);
+    return details[0] || `Threads Weave ${command} failed.`;
+  }
+
+  async runOneShotCommand(command, commandArgs = [], { parseJson = true, mode = "basic" } = {}) {
+    const cfg = this.ensureSidecarConfigured();
+    const secretStorageCandidates = mode === "runtime"
+      ? this.getSecretStorageCandidates(cfg)
+      : [null];
+    for (let index = 0; index < secretStorageCandidates.length; index += 1) {
+      const secretStorage = secretStorageCandidates[index];
+      const args = [
+        cfg.sidecarPath,
+        ...this.buildBaseArgs(cfg),
+        command,
+        ...(mode === "runtime"
+          ? this.buildAgentRuntimeArgs(cfg, secretStorage)
+          : this.buildProfileArgs(cfg)),
+        ...commandArgs,
+      ];
+      let result;
+      try {
+        result = await execFileAsync(cfg.nodeBin, args, {
+          cwd: process.cwd(),
+          env: process.env,
+          maxBuffer: 8 * 1024 * 1024,
+        });
+      } catch (error) {
+        const message = this.extractCommandErrorMessage(error, command);
+        const canFallbackToFile = (
+          mode === "runtime"
+          && secretStorage === "auto"
+          && !isSingleUsePairingCommand(command)
+          && secretStorageCandidates.slice(index + 1).includes("file")
+          && shouldSuggestFileSecretStorage(message)
+        );
+        if (canFallbackToFile) {
+          this.log.warn(
+            `Threads Weave sidecar ${command} could not use secretStorage="${secretStorage}". Retrying with file-backed storage.`,
+          );
+          continue;
+        }
+        throw new Error(
+          maybeAugmentSecretStorageError(message, cfg, secretStorage),
+        );
+      }
+      const stdout = String(result.stdout || "").trim();
+      if (!parseJson) {
+        return stdout;
+      }
+      if (!stdout) {
+        throw new Error(`Threads Weave ${command} returned no JSON payload.`);
+      }
+      return JSON.parse(stdout);
+    }
+    throw new Error(`Threads Weave ${command} failed.`);
+  }
+
+  async status() {
+    return this.runOneShotCommand("status", ["--json"]);
+  }
+
+  async doctor(options = {}) {
+    const args = ["--json"];
+    if (options.skipRemoteProbe) {
+      args.unshift("--skip-remote-probe");
+    } else {
+      await this.stop();
+    }
+    return this.runOneShotCommand("doctor", args);
+  }
+
+  resolveServerUrl(serverUrl, { required = false, useBundledDefault = false } = {}) {
+    const candidate = isTruthyString(serverUrl)
+      ? serverUrl.trim()
+      : this.config.serverUrl || (useBundledDefault ? DEFAULT_SERVER_URL : null);
+    if (candidate) {
+      return candidate;
+    }
+    if (required) {
+      throw new Error(
+        `Threads Weave server URL is required for first-time pairing. Pass "--server-url <URL>" or set plugins.entries["${PLUGIN_ID}"].config.serverUrl in ${DEFAULT_OPENCLAW_CONFIG_PATH}. The bundled default is ${DEFAULT_SERVER_URL}.`,
+      );
+    }
+    return null;
+  }
+
+  async pair(pairingCode, options = {}) {
+    if (!isTruthyString(pairingCode)) {
+      throw new Error("Pairing code is required.");
+    }
+    const serverUrl = this.resolveServerUrl(options.serverUrl, {
+      required: true,
+      useBundledDefault: true,
+    });
+    await this.stop();
+    return this.runOneShotCommand(
+      "pair",
+      ["--server-url", serverUrl, "--pairing-code", pairingCode, "--json"],
+      { mode: "runtime" },
+    );
+  }
+
+  async renew(pairingCode, options = {}) {
+    if (!isTruthyString(pairingCode)) {
+      throw new Error("Pairing code is required.");
+    }
+    const serverUrl = this.resolveServerUrl(options.serverUrl);
+    await this.stop();
+    return this.runOneShotCommand(
+      "renew",
+      [
+        ...(serverUrl ? ["--server-url", serverUrl] : []),
+        "--pairing-code",
+        pairingCode,
+        "--json",
+      ],
+      { mode: "runtime" },
+    );
+  }
+
+  async clear() {
+    await this.stop();
+    return this.runOneShotCommand("clear-token", ["--json"]);
+  }
+
+  async ensureStarted() {
+    if (this.startPromise) {
+      return this.startPromise;
+    }
+    if (this.child && !this.child.killed && this.readyInfo) {
+      return this.readyInfo;
+    }
+    const startPromise = this.startInternal();
+    this.startPromise = startPromise;
+    try {
+      return await startPromise;
+    } finally {
+      if (this.startPromise === startPromise) {
+        this.startPromise = null;
+      }
+    }
+  }
+
+  async startInternal() {
+    const cfg = this.ensureSidecarConfigured();
+    const status = await this.status().catch((error) => {
+      throw new Error(`Unable to read Threads Weave sidecar status: ${error.message}`);
+    });
+    if (!status || typeof status !== "object") {
+      throw new Error("Threads Weave sidecar status response was invalid.");
+    }
+    if (status.pairingRequired) {
+      throw new Error(
+        `Threads Weave sidecar profile "${cfg.profile}" is not paired or has expired. Run "openclaw ${MANAGEMENT_COMMAND} pair --code <PAIR_CODE>" first.`,
+      );
+    }
+
+    const readyDir = await fsp.mkdtemp(path.join(os.tmpdir(), "threads-weave-sidecar-"));
+    const readyFile = path.join(readyDir, "ready.json");
+    const args = [
+      cfg.sidecarPath,
+      ...this.buildBaseArgs(cfg),
+      "stdio",
+      ...this.buildAgentRuntimeArgs(cfg),
+      "--ready-file",
+      readyFile,
+    ];
+    if (cfg.serverUrl) {
+      args.push("--server-url", cfg.serverUrl);
+    }
+    if (cfg.persistSession) {
+      args.push("--persist-session");
+    }
+    const child = spawn(cfg.nodeBin, args, {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    this.child = child;
+    this.tempReadyDir = readyDir;
+    this.initialized = false;
+    this.pending.clear();
+    let startupError = null;
+    let startupReady = false;
+
+    child.once("error", (error) => {
+      this.log.error("Threads Weave sidecar failed to start", { error });
+      this.rejectAllPending(new Error(`Threads Weave sidecar failed to start: ${error.message}`));
+      if (!startupReady) {
+        startupError = new Error(`Threads Weave sidecar failed to start: ${error.message}`);
+      }
+    });
+
+    child.once("exit", (code, signal) => {
+      const message = `Threads Weave sidecar exited (code=${String(code)}, signal=${String(signal)}).`;
+      this.log.warn(message);
+      this.child = null;
+      this.initialized = false;
+      this.readyInfo = null;
+      this.rejectAllPending(new Error(message));
+      void this.cleanupTempReadyDir();
+      if (!startupReady) {
+        startupError = new Error(message);
+      }
+    });
+
+    this.stdoutInterface = readline.createInterface({ input: child.stdout });
+    this.stdoutInterface.on("line", (line) => this.handleStdoutLine(line));
+    this.stderrInterface = readline.createInterface({ input: child.stderr });
+    this.stderrInterface.on("line", (line) => {
+      if (line && line.trim()) {
+        this.log.warn(`Threads Weave sidecar: ${line.trim()}`);
+      }
+    });
+
+    let readyPayload;
+    try {
+      readyPayload = await readJsonFileWithTimeout(readyFile, cfg.startupTimeoutMs, () => {
+        if (this.child && !this.child.killed) {
+          this.child.kill();
+        }
+      }, () => startupError);
+      startupReady = true;
+    } catch (error) {
+      await this.stop();
+      if (startupError && error === startupError) {
+        throw error;
+      }
+      throw new Error(`Timed out waiting for Threads Weave sidecar readiness: ${error.message}`);
+    }
+    this.readyInfo = readyPayload;
+    return readyPayload;
+  }
+
+  async initializeIfNeeded() {
+    if (this.initialized) {
+      return;
+    }
+    if (this.initializePromise) {
+      await this.initializePromise;
+      return;
+    }
+    const initializePromise = (async () => {
+      await this.ensureStarted();
+      await this.sendRequest("initialize", {
+        protocolVersion: DEFAULT_PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: {
+          name: PLUGIN_ID,
+          version: SIDE_CAR_VERSION,
+        },
+      });
+      this.sendNotification("notifications/initialized");
+      this.initialized = true;
+    })();
+    this.initializePromise = initializePromise;
+    try {
+      await initializePromise;
+    } finally {
+      if (this.initializePromise === initializePromise) {
+        this.initializePromise = null;
+      }
+    }
+  }
+
+  async callTool(sidecarToolName, argumentsValue) {
+    await this.initializeIfNeeded();
+    const result = await this.sendRequest("tools/call", {
+      name: sidecarToolName,
+      arguments: argumentsValue && typeof argumentsValue === "object" ? argumentsValue : {},
+    });
+    if (result && typeof result === "object" && result.isError) {
+      throw new Error(formatSidecarErrorPayload(result));
+    }
+    return normalizeToolResultForOpenClaw(result);
+  }
+
+  sendNotification(method, params) {
+    if (!this.child || this.child.killed || !this.child.stdin) {
+      return;
+    }
+    const payload = {
+      jsonrpc: "2.0",
+      method,
+    };
+    if (params !== undefined) {
+      payload.params = params;
+    }
+    this.child.stdin.write(`${JSON.stringify(payload)}\n`);
+  }
+
+  sendRequest(method, params, options = {}) {
+    if (!this.child || this.child.killed || !this.child.stdin) {
+      return Promise.reject(new Error("Threads Weave sidecar is not running."));
+    }
+    const timeoutMs = Number.isFinite(options?.timeoutMs) && options.timeoutMs > 0
+      ? Number(options.timeoutMs)
+      : this.config.requestTimeoutMs;
+    const id = this.requestCounter++;
+    const payload = {
+      jsonrpc: "2.0",
+      id,
+      method,
+    };
+    if (params !== undefined) {
+      payload.params = params;
+    }
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (callback, value) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        if (timer) {
+          clearTimeout(timer);
+        }
+        callback(value);
+      };
+      const timer = setTimeout(() => {
+        const pendingId = String(id);
+        if (!this.pending.has(pendingId)) {
+          return;
+        }
+        this.pending.delete(pendingId);
+        this.log.warn("Threads Weave sidecar request timed out", {
+          id,
+          method,
+          params,
+          timeoutMs,
+        });
+        finish(reject, new Error(buildSidecarRequestTimeoutError(method, params, timeoutMs)));
+      }, timeoutMs);
+      timer.unref?.();
+      this.pending.set(String(id), {
+        resolve: (value) => finish(resolve, value),
+        reject: (error) => finish(reject, error),
+      });
+      this.child.stdin.write(`${JSON.stringify(payload)}\n`, (error) => {
+        if (error) {
+          this.pending.delete(String(id));
+          finish(reject, error);
+        }
+      });
+    });
+  }
+
+  handleStdoutLine(line) {
+    if (!line || !line.trim()) {
+      return;
+    }
+    let payload;
+    try {
+      payload = JSON.parse(line);
+    } catch (error) {
+      this.log.warn("Threads Weave sidecar emitted non-JSON stdout", { line });
+      return;
+    }
+    const id = payload && Object.prototype.hasOwnProperty.call(payload, "id")
+      ? String(payload.id)
+      : null;
+    if (!id || !this.pending.has(id)) {
+      this.log.debug("Threads Weave sidecar notification", payload);
+      return;
+    }
+    const entry = this.pending.get(id);
+    this.pending.delete(id);
+    if (payload && typeof payload === "object" && payload.error) {
+      const message = formatSidecarErrorPayload(payload.error);
+      entry.reject(new Error(message));
+      return;
+    }
+    entry.resolve(payload.result);
+  }
+
+  rejectAllPending(error) {
+    for (const [id, entry] of this.pending.entries()) {
+      this.pending.delete(id);
+      entry.reject(error);
+    }
+  }
+
+  async waitForChildExit(child, timeoutMs) {
+    if (hasChildProcessExited(child)) {
+      return true;
+    }
+    const normalizedTimeoutMs = Number.isFinite(timeoutMs) && timeoutMs > 0
+      ? Number(timeoutMs)
+      : DEFAULT_STOP_GRACE_PERIOD_MS;
+    return new Promise((resolve) => {
+      let settled = false;
+      const finish = (didExit) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        if (timer) {
+          clearTimeout(timer);
+        }
+        child?.removeListener?.("exit", onExit);
+        resolve(didExit);
+      };
+      const onExit = () => finish(true);
+      child?.once?.("exit", onExit);
+      const timer = setTimeout(() => finish(hasChildProcessExited(child)), normalizedTimeoutMs);
+      timer.unref?.();
+    });
+  }
+
+  signalChildProcess(child, signal) {
+    if (!child || hasChildProcessExited(child) || typeof child.kill !== "function") {
+      return false;
+    }
+    try {
+      return child.kill(signal);
+    } catch (error) {
+      this.log.warn(`Threads Weave sidecar could not receive ${signal}`, { error });
+      return false;
+    }
+  }
+
+  async terminateChildProcess(
+    child,
+    { gracePeriodMs = DEFAULT_STOP_GRACE_PERIOD_MS, forceKillGracePeriodMs = DEFAULT_FORCE_KILL_TIMEOUT_MS } = {},
+  ) {
+    if (hasChildProcessExited(child)) {
+      return;
+    }
+    this.signalChildProcess(child, "SIGINT");
+    const exitedGracefully = await this.waitForChildExit(child, gracePeriodMs);
+    if (exitedGracefully) {
+      return;
+    }
+    this.log.warn(
+      `Threads Weave sidecar did not exit after ${gracePeriodMs}ms; sending SIGKILL.`,
+    );
+    this.signalChildProcess(child, "SIGKILL");
+    const exitedAfterForceKill = await this.waitForChildExit(child, forceKillGracePeriodMs);
+    if (exitedAfterForceKill) {
+      return;
+    }
+    throw new Error(
+      `Threads Weave sidecar did not exit within ${forceKillGracePeriodMs}ms after SIGKILL.`,
+    );
+  }
+
+  async cleanupTempReadyDir() {
+    if (!this.tempReadyDir) {
+      return;
+    }
+    const target = this.tempReadyDir;
+    this.tempReadyDir = null;
+    await fsp.rm(target, { recursive: true, force: true }).catch(() => {});
+  }
+
+  async stop(options = {}) {
+    const child = this.child;
+    const gracePeriodMs = Number.isFinite(options?.gracePeriodMs) && options.gracePeriodMs > 0
+      ? Number(options.gracePeriodMs)
+      : DEFAULT_STOP_GRACE_PERIOD_MS;
+    const forceKillGracePeriodMs = Number.isFinite(options?.forceKillGracePeriodMs)
+      && options.forceKillGracePeriodMs > 0
+      ? Number(options.forceKillGracePeriodMs)
+      : DEFAULT_FORCE_KILL_TIMEOUT_MS;
+    this.child = null;
+    this.initialized = false;
+    this.initializePromise = null;
+    this.readyInfo = null;
+    if (this.stdoutInterface) {
+      this.stdoutInterface.close();
+      this.stdoutInterface = null;
+    }
+    if (this.stderrInterface) {
+      this.stderrInterface.close();
+      this.stderrInterface = null;
+    }
+    let stopError = null;
+    try {
+      if (child && !hasChildProcessExited(child)) {
+        await this.terminateChildProcess(child, {
+          gracePeriodMs,
+          forceKillGracePeriodMs,
+        });
+      }
+    } catch (error) {
+      stopError = error;
+      this.log.error("Threads Weave sidecar failed to stop cleanly", { error });
+    }
+    this.rejectAllPending(
+      new Error(
+        stopError
+          ? `Threads Weave sidecar stop failed: ${stopError.message}`
+          : "Threads Weave sidecar stopped.",
+      ),
+    );
+    await this.cleanupTempReadyDir();
+    if (stopError) {
+      throw stopError;
+    }
+  }
+}
+
+function formatJsonForCli(payload) {
+  return JSON.stringify(payload, null, 2);
+}
+
+function printCliPayload(payload, options) {
+  if (options?.json) {
+    process.stdout.write(`${formatJsonForCli(payload)}\n`);
+    return;
+  }
+  if (!payload || typeof payload !== "object") {
+    process.stdout.write(`${String(payload)}\n`);
+    return;
+  }
+  if (payload.status && typeof payload.status === "object") {
+    process.stdout.write(`${formatJsonForCli(payload.status)}\n`);
+    return;
+  }
+  process.stdout.write(`${formatJsonForCli(payload)}\n`);
+}
+
+function registerCli(api, manager) {
+  if (typeof api.registerCli !== "function") {
+    return;
+  }
+  api.registerCli(({ program }) => {
+    const root = program
+      .command(MANAGEMENT_COMMAND)
+      .description("Manage the Threads Weave sidecar connection");
+
+    root
+      .command("pair")
+      .requiredOption("--code <pairingCode>", "One-time pairing code from Threads Weave")
+      .option(
+        "--server-url <serverUrl>",
+        `Override the Threads Weave server URL for pairing. Defaults to ${DEFAULT_SERVER_URL}.`,
+      )
+      .option("--json", "Print raw JSON payload")
+      .action(async (options) => {
+        const payload = await manager.pair(options.code, { serverUrl: options.serverUrl });
+        printCliPayload(payload, options);
+      });
+
+    root
+      .command("renew")
+      .requiredOption("--code <pairingCode>", "Fresh one-time pairing code from Threads Weave")
+      .option(
+        "--server-url <serverUrl>",
+        "Optional override for the Threads Weave server URL when renewing the cached token.",
+      )
+      .option("--json", "Print raw JSON payload")
+      .action(async (options) => {
+        const payload = await manager.renew(options.code, { serverUrl: options.serverUrl });
+        printCliPayload(payload, options);
+      });
+
+    root
+      .command("status")
+      .option("--json", "Print raw JSON payload")
+      .action(async (options) => {
+        const payload = await manager.status();
+        printCliPayload(payload, options);
+      });
+
+    root
+      .command("doctor")
+      .option("--skip-remote-probe", "Run only local checks and skip the remote MCP initialize probe")
+      .option("--json", "Print raw JSON payload")
+      .action(async (options) => {
+        const payload = await manager.doctor({
+          skipRemoteProbe: Boolean(options.skipRemoteProbe),
+        });
+        printCliPayload(payload, options);
+      });
+
+    root
+      .command("clear")
+      .option("--json", "Print raw JSON payload")
+      .action(async (options) => {
+        const payload = await manager.clear();
+        printCliPayload(payload, options);
+      });
+  }, { commands: [MANAGEMENT_COMMAND] });
+}
+
+function registerService(api, manager) {
+  if (typeof api.registerService !== "function") {
+    return;
+  }
+  api.registerService({
+    id: "threads-weave-sidecar",
+    start: async () => {
+      if (!manager.config.autoStart) {
+        return;
+      }
+      try {
+        await manager.ensureStarted();
+      } catch (error) {
+        manager.log.warn(`Threads Weave sidecar autostart skipped: ${error.message}`);
+      }
+    },
+    stop: async () => {
+      await manager.stop();
+    },
+  });
+}
+
+function registerTools(api, manager) {
+  if (typeof api.registerTool !== "function") {
+    return;
+  }
+  for (const definition of TOOL_DEFINITIONS) {
+    const openClawName = toolNameForOpenClaw(definition.name);
+    const openClawLabel = toolLabelForOpenClaw(definition.name);
+    api.registerTool(
+      {
+        name: openClawName,
+        label: openClawLabel,
+        description: definition.description,
+        parameters: definition.inputSchema,
+        execute: async (_toolCallId, params) => {
+          return manager.callTool(definition.name, params ?? {});
+        },
+      },
+      {
+        optional: WRITE_TOOL_NAMES.has(definition.name),
+      },
+    );
+  }
+}
+
+function registerManagementTools(api, manager) {
+  if (typeof api.registerTool !== "function") {
+    return;
+  }
+
+  api.registerTool(
+    {
+      name: "threads_weave_pair",
+      label: toolLabelForOpenClaw("pair"),
+      description: "Exchange a one-time Threads Weave pairing code for a cached local sidecar token. This pairs the local sidecar profile and does not create or renew the server-side grant itself. If the profile is already paired, calling pair again with a fresh pairing code replaces the local cached token and profile state; retrying the same one-time code will fail because pairing codes are single-use. Prefer renew when rotating an existing pairing.",
+      parameters: {
+        type: "object",
+        properties: {
+          pairingCode: {
+            type: "string",
+            description: "One-time pairing code from Threads Weave.",
+          },
+          serverUrl: {
+            type: "string",
+            description: `Optional override for the Threads Weave server URL. Defaults to the plugin config value or ${DEFAULT_SERVER_URL}.`,
+          },
+        },
+        required: ["pairingCode"],
+        additionalProperties: false,
+      },
+      execute: async (_toolCallId, params) => {
+        const payload = await manager.pair(params?.pairingCode, { serverUrl: params?.serverUrl });
+        return buildManagementToolResult(payload, summarizePairingAction(payload));
+      },
+    },
+    { optional: true },
+  );
+
+  api.registerTool(
+    {
+      name: "threads_weave_renew",
+      label: toolLabelForOpenClaw("renew"),
+      description: "Replace the cached local sidecar token using a fresh one-time pairing code. This renews local sidecar pairing only and does not extend or renew the server-side grant duration. Use this when the profile is already paired and you want to rotate credentials without relying on pair to overwrite the local state.",
+      parameters: {
+        type: "object",
+        properties: {
+          pairingCode: {
+            type: "string",
+            description: "Fresh one-time pairing code from Threads Weave.",
+          },
+          serverUrl: {
+            type: "string",
+            description: "Optional override for the Threads Weave server URL when renewing the cached token.",
+          },
+        },
+        required: ["pairingCode"],
+        additionalProperties: false,
+      },
+      execute: async (_toolCallId, params) => {
+        const payload = await manager.renew(params?.pairingCode, { serverUrl: params?.serverUrl });
+        return buildManagementToolResult(payload, summarizePairingAction(payload));
+      },
+    },
+    { optional: true },
+  );
+
+  api.registerTool(
+    {
+      name: "threads_weave_doctor",
+      label: toolLabelForOpenClaw("doctor"),
+      description: "Run local Threads Weave sidecar diagnostics for the current profile. By default this includes local checks and a remote MCP initialize/cleanup probe; when a live stdio bridge is running, the plugin stops it first to avoid probing and deleting the active remote session. Set skipRemoteProbe to true to run local-only checks.",
+      parameters: {
+        type: "object",
+        properties: {
+          skipRemoteProbe: {
+            type: "boolean",
+            description: "When true, skip the remote MCP initialize probe and run local-only checks.",
+          },
+        },
+        additionalProperties: false,
+      },
+      execute: async (_toolCallId, params) => {
+        const payload = await manager.doctor({
+          skipRemoteProbe: Boolean(params?.skipRemoteProbe),
+        });
+        return buildManagementToolResult(payload, summarizeDoctorResult(payload));
+      },
+    },
+    { optional: true },
+  );
+
+  api.registerTool(
+    {
+      name: "threads_weave_status",
+      label: toolLabelForOpenClaw("status"),
+      description: "Inspect the local Threads Weave sidecar pairing and profile state. This reports local token and profile status, not the grant-renew lifecycle action.",
+      parameters: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+      },
+      execute: async () => {
+        const status = await manager.status();
+        return buildManagementToolResult(status, summarizeSidecarStatus(status));
+      },
+    },
+    { optional: true },
+  );
+
+  api.registerTool(
+    {
+      name: "threads_weave_unpair",
+      label: toolLabelForOpenClaw("unpair"),
+      description: "Delete the cached local sidecar token and clear local Threads Weave pairing state for the current profile. This unpairs the local sidecar only and does not revoke or renew the server-side grant.",
+      parameters: {
+        type: "object",
+        properties: {},
+        additionalProperties: false,
+      },
+      execute: async () => {
+        const payload = await manager.clear();
+        return buildManagementToolResult(payload, summarizeClearAction(payload));
+      },
+    },
+    { optional: true },
+  );
+}
+
+export default function registerThreadsWeavePlugin(api) {
+  const manager = new ThreadsWeaveSidecarManager(api);
+  registerService(api, manager);
+  registerCli(api, manager);
+  registerTools(api, manager);
+  registerManagementTools(api, manager);
+}
+
+export {
+  BUNDLED_SIDE_CAR_PATH,
+  MANAGEMENT_COMMAND,
+  PLUGIN_ID,
+  DEFAULT_SIDE_CAR_PATH,
+  DEFAULT_SERVER_URL,
+  PLUGIN_PACKAGE_ROOT,
+  sidecarNameForOpenClaw,
+  toolNameForOpenClaw,
+  ThreadsWeaveSidecarManager,
+};