settld 0.2.6 → 0.2.8

package/docs/QUICKSTART_MCP_HOSTS.md

@@ -182,7 +182,7 @@ Then activate host-side:
 - `codex`: restart Codex.
 - `claude`: restart Claude Desktop.
 - `cursor`: restart Cursor.
-- `openclaw`: run `openclaw doctor`, ensure OpenClaw onboarding is complete (`openclaw onboard --install-daemon`), then run `openclaw tui`.
+- `openclaw`: run `openclaw doctor`, ensure OpenClaw onboarding is complete (`openclaw onboard --install-daemon`), install plugin (`openclaw plugins install settld@latest`), run local verification (`openclaw agent --local --agent main --session-id settld-smoke --message "Use the tool named settld_about with empty arguments. Return only JSON." --json`), then run `openclaw tui --session main`.
 
 ## 5) Fund and verify wallet state
 

package/docs/integrations/openclaw/CLAWHUB_PUBLISH_CHECKLIST.md

@@ -32,7 +32,7 @@ Publish the folder `docs/integrations/openclaw/settld-mcp-skill/` as your skill
 If ClawHub UI requests install instructions, use:
 
 - command: `npx`
-- args: `-y settld-mcp`
+- args: `-y --package settld@latest settld-mcp`
 - env: `SETTLD_BASE_URL`, `SETTLD_TENANT_ID`, `SETTLD_API_KEY`, optional `SETTLD_PAID_TOOLS_BASE_URL`
 
 ## 4) Post-Publish Smoke Test

package/docs/integrations/openclaw/PUBLIC_QUICKSTART.md

@@ -72,19 +72,27 @@ Run:
 
 ```bash
 openclaw doctor
+openclaw plugins install settld@latest
+openclaw agent --local --agent main --session-id settld-smoke --message "Use the tool named settld_about with empty arguments. Return only JSON." --json
 ```
 
 Then from OpenClaw chat/test prompt:
 
-- `Call settld.about and return JSON.`
+- `Use tool settld_about and return JSON only.`
 
 Expected result: success payload with Settld tool metadata.
 
+If your TUI is in a channel-bound session (`whatsapp:*`, `telegram:*`), switch to `main` first:
+
+```bash
+openclaw tui --session main
+```
+
 ## 4) Run first paid tool call
 
 From OpenClaw prompt:
 
-- `Run settld.weather_current_paid for city=Chicago unit=f and include x-settld-* headers in the response.`
+- `Use tool settld_call with tool=settld.weather_current_paid and arguments={"city":"Chicago","unit":"f"}.`
 
 Expected result:
 

package/docs/integrations/openclaw/settld-mcp-skill/SKILL.md

@@ -30,14 +30,16 @@ It is designed for the public `quick` onboarding flow:
 - Settld runtime env from setup (`SETTLD_API_KEY`, `SETTLD_BASE_URL`, `SETTLD_TENANT_ID`)
 - Optional paid tools base URL (`SETTLD_PAID_TOOLS_BASE_URL`)
 
-## MCP Server Registration
+## OpenClaw Plugin Registration
 
-Use the server definition in `mcp-server.example.json`.
+Install the Settld OpenClaw plugin from npm:
 
-Server command:
+- `openclaw plugins install settld@latest`
 
-- command: `npx`
-- args: `["-y","settld-mcp"]`
+This plugin wraps Settld MCP under OpenClaw-native tools:
+
+- `settld_about`
+- `settld_call`
 
 Required env vars:
 
@@ -52,10 +54,10 @@ Optional env vars:
 
 ## Agent Usage Pattern
 
-1. Call `settld.about` to verify connectivity.
-2. For paid search/data calls, use:
-   - `settld.exa_search_paid`
-   - `settld.weather_current_paid`
+1. Call `settld_about` to verify connectivity.
+2. For paid search/data calls, use `settld_call` with:
+   - `tool=settld.exa_search_paid`
+   - `tool=settld.weather_current_paid`
 3. For agreement lifecycle demo calls, use:
    - `settld.create_agreement`
    - `settld.submit_evidence`
@@ -64,8 +66,8 @@ Optional env vars:
 
 ## Smoke Prompts
 
-- "Call `settld.about` and return the result JSON."
-- "Run `settld.weather_current_paid` for Chicago in fahrenheit and include the `x-settld-*` headers."
+- "Use tool `settld_about` and return JSON."
+- "Use tool `settld_call` with `tool=settld.weather_current_paid` and arguments for Chicago/fahrenheit."
 
 ## Identity + Traceability
 

package/docs/integrations/openclaw/settld-mcp-skill/mcp-server.example.json

@@ -1,7 +1,7 @@
 {
   "name": "settld",
   "command": "npx",
-  "args": ["-y", "settld-mcp"],
+  "args": ["-y", "--package", "settld@latest", "settld-mcp"],
   "env": {
     "SETTLD_BASE_URL": "https://api.settld.work",
     "SETTLD_TENANT_ID": "tenant_xxx",

package/openclaw/index.js

@@ -0,0 +1,307 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const REQUIRED_ENV_KEYS = ["SETTLD_BASE_URL", "SETTLD_TENANT_ID", "SETTLD_API_KEY"];
+const OPTIONAL_ENV_KEYS = ["SETTLD_PAID_TOOLS_BASE_URL", "SETTLD_PAID_TOOLS_AGENT_PASSPORT"];
+const MCP_SCRIPT_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "scripts", "mcp", "settld-mcp-server.mjs");
+
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function pickString(value) {
+  if (typeof value !== "string") return "";
+  return value.trim();
+}
+
+function parseSettldServerConfig(mcpConfig) {
+  if (!isObject(mcpConfig)) return null;
+  if (isObject(mcpConfig.mcpServers) && isObject(mcpConfig.mcpServers.settld)) {
+    return mcpConfig.mcpServers.settld;
+  }
+  if (pickString(mcpConfig.name) === "settld") return mcpConfig;
+  return null;
+}
+
+function parseSettldEnvFromServer(server) {
+  if (!isObject(server) || !isObject(server.env)) return {};
+  const env = {};
+  for (const key of [...REQUIRED_ENV_KEYS, ...OPTIONAL_ENV_KEYS]) {
+    const value = pickString(server.env[key]);
+    if (value) env[key] = value;
+  }
+  return env;
+}
+
+function defaultMcpConfigPathCandidates() {
+  const home = os.homedir();
+  const xdgConfigHome = pickString(process.env.XDG_CONFIG_HOME) || path.join(home, ".config");
+  return [
+    pickString(process.env.OPENCLAW_MCP_CONFIG_PATH),
+    pickString(process.env.OPENCLAW_HOME) ? path.join(pickString(process.env.OPENCLAW_HOME), "mcp.json") : "",
+    path.join(home, "Library", "Application Support", "OpenClaw", "mcp.json"),
+    path.join(home, ".openclaw", "mcp.json"),
+    path.join(xdgConfigHome, "OpenClaw", "mcp.json"),
+    path.join(xdgConfigHome, "openclaw", "mcp.json")
+  ].filter(Boolean);
+}
+
+async function readSettldEnvFromMcpConfig(mcpConfigPath) {
+  const raw = await fs.readFile(mcpConfigPath, "utf8");
+  const parsed = JSON.parse(raw);
+  const server = parseSettldServerConfig(parsed);
+  return parseSettldEnvFromServer(server);
+}
+
+async function resolveSettldEnv(pluginConfig = {}) {
+  const env = {};
+
+  const fromPluginConfig = {
+    SETTLD_BASE_URL: pickString(pluginConfig.baseUrl),
+    SETTLD_TENANT_ID: pickString(pluginConfig.tenantId),
+    SETTLD_API_KEY: pickString(pluginConfig.apiKey),
+    SETTLD_PAID_TOOLS_BASE_URL: pickString(pluginConfig.paidToolsBaseUrl),
+    SETTLD_PAID_TOOLS_AGENT_PASSPORT: pickString(pluginConfig.paidToolsAgentPassport)
+  };
+  for (const [key, value] of Object.entries(fromPluginConfig)) {
+    if (value) env[key] = value;
+  }
+
+  for (const key of [...REQUIRED_ENV_KEYS, ...OPTIONAL_ENV_KEYS]) {
+    const value = pickString(process.env[key]);
+    if (value && !env[key]) env[key] = value;
+  }
+
+  const missingRequired = REQUIRED_ENV_KEYS.filter((key) => !pickString(env[key]));
+  if (missingRequired.length === 0) return env;
+
+  const candidates = [];
+  const explicitPath = pickString(pluginConfig.mcpConfigPath);
+  if (explicitPath) candidates.push(explicitPath);
+  candidates.push(...defaultMcpConfigPathCandidates());
+
+  const seen = new Set();
+  for (const candidate of candidates) {
+    const resolved = path.resolve(candidate);
+    if (seen.has(resolved)) continue;
+    seen.add(resolved);
+    try {
+      const fromFile = await readSettldEnvFromMcpConfig(resolved);
+      for (const [key, value] of Object.entries(fromFile)) {
+        if (value && !env[key]) env[key] = value;
+      }
+      const nowMissing = REQUIRED_ENV_KEYS.filter((key) => !pickString(env[key]));
+      if (nowMissing.length === 0) return env;
+    } catch {
+      // Keep searching; users may have multiple OpenClaw profiles/config paths.
+    }
+  }
+
+  return env;
+}
+
+function parseLineJson(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+function waitForRpcResponse(pendingMap, id, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pendingMap.delete(id);
+      reject(new Error(`MCP request timed out (id=${id})`));
+    }, timeoutMs);
+    pendingMap.set(id, { resolve, reject, timer });
+  });
+}
+
+function routeRpcMessage(pendingMap, message) {
+  if (!isObject(message)) return;
+  if (!Object.prototype.hasOwnProperty.call(message, "id")) return;
+  const pending = pendingMap.get(message.id);
+  if (!pending) return;
+  clearTimeout(pending.timer);
+  pendingMap.delete(message.id);
+  pending.resolve(message);
+}
+
+function createStdoutRouter(stdout, pendingMap) {
+  let buffer = "";
+  stdout.setEncoding("utf8");
+  stdout.on("data", (chunk) => {
+    buffer += String(chunk ?? "");
+    while (buffer.includes("\n")) {
+      const idx = buffer.indexOf("\n");
+      const line = buffer.slice(0, idx).trim();
+      buffer = buffer.slice(idx + 1);
+      if (!line) continue;
+      const parsed = parseLineJson(line);
+      if (parsed) routeRpcMessage(pendingMap, parsed);
+    }
+  });
+}
+
+function rpcWrite(stdin, payload) {
+  stdin.write(`${JSON.stringify(payload)}\n`);
+}
+
+async function callSettldMcpTool({ toolName, toolArgs, env, timeoutMs = 30_000 }) {
+  const child = spawn(process.execPath, [MCP_SCRIPT_PATH], {
+    env: { ...process.env, ...env },
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+  const pendingMap = new Map();
+  createStdoutRouter(child.stdout, pendingMap);
+
+  let stderr = "";
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk) => {
+    stderr += String(chunk ?? "");
+  });
+
+  const waitInit = waitForRpcResponse(pendingMap, 1, timeoutMs);
+  rpcWrite(child.stdin, {
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: {
+      protocolVersion: "2024-11-05",
+      clientInfo: { name: "openclaw-settld-plugin", version: "1" },
+      capabilities: {}
+    }
+  });
+  await waitInit;
+  rpcWrite(child.stdin, { jsonrpc: "2.0", method: "notifications/initialized", params: {} });
+
+  const waitCall = waitForRpcResponse(pendingMap, 2, timeoutMs);
+  rpcWrite(child.stdin, {
+    jsonrpc: "2.0",
+    id: 2,
+    method: "tools/call",
+    params: {
+      name: toolName,
+      arguments: isObject(toolArgs) ? toolArgs : {}
+    }
+  });
+  const callResponse = await waitCall;
+
+  child.kill("SIGTERM");
+  if (isObject(callResponse.error)) {
+    const message = pickString(callResponse.error.message) || "MCP tool call failed";
+    throw new Error(`${message}${stderr.trim() ? ` | stderr: ${stderr.trim()}` : ""}`);
+  }
+  return callResponse.result;
+}
+
+function buildMissingEnvMessage(env) {
+  const missing = REQUIRED_ENV_KEYS.filter((key) => !pickString(env[key]));
+  if (missing.length === 0) return "";
+  return [
+    `Missing Settld runtime env: ${missing.join(", ")}`,
+    "Run: npx -y settld@latest setup",
+    "Select host=openclaw in quick mode, then retry."
+  ].join(" ");
+}
+
+function normalizeToolArguments(params) {
+  if (isObject(params.arguments)) return params.arguments;
+  const raw = pickString(params.argumentsJson);
+  if (!raw) return {};
+  try {
+    const parsed = JSON.parse(raw);
+    if (!isObject(parsed)) {
+      throw new Error("argumentsJson must decode to a JSON object");
+    }
+    return parsed;
+  } catch (err) {
+    throw new Error(`Invalid argumentsJson: ${err?.message ?? "parse failed"}`);
+  }
+}
+
+function buildToolResult(payload, details = {}) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload ?? {}, null, 2) }],
+    details
+  };
+}
+
+export default function register(api) {
+  api.registerTool({
+    name: "settld_about",
+    label: "Settld About",
+    description: "Check Settld runtime connectivity and capability info.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {}
+    },
+    async execute() {
+      const env = await resolveSettldEnv(api.pluginConfig ?? {});
+      const missingMessage = buildMissingEnvMessage(env);
+      if (missingMessage) throw new Error(missingMessage);
+      const result = await callSettldMcpTool({
+        toolName: "settld.about",
+        toolArgs: {},
+        env
+      });
+      return buildToolResult(result, { tool: "settld.about" });
+    }
+  });
+
+  api.registerTool({
+    name: "settld_call",
+    label: "Settld Tool Call",
+    description: "Call any Settld MCP tool by name with JSON arguments.",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      required: ["tool"],
+      properties: {
+        tool: {
+          type: "string",
+          description: "Settld MCP tool name, for example settld.weather_current_paid."
+        },
+        arguments: {
+          type: "object",
+          additionalProperties: true,
+          description: "Tool arguments as an object."
+        },
+        argumentsJson: {
+          type: "string",
+          description: "JSON object string for arguments (use if your model cannot pass object args)."
+        }
+      }
+    },
+    async execute(_id, params = {}) {
+      const toolName = pickString(params.tool);
+      if (!toolName) throw new Error("tool is required");
+      if (!toolName.startsWith("settld.")) {
+        throw new Error("tool must start with settld.");
+      }
+      const toolArgs = normalizeToolArguments(params);
+      const env = await resolveSettldEnv(api.pluginConfig ?? {});
+      const missingMessage = buildMissingEnvMessage(env);
+      if (missingMessage) throw new Error(missingMessage);
+      const result = await callSettldMcpTool({
+        toolName,
+        toolArgs,
+        env
+      });
+      return buildToolResult(result, { tool: toolName });
+    }
+  });
+}
+
+export {
+  parseSettldServerConfig,
+  parseSettldEnvFromServer,
+  resolveSettldEnv,
+  normalizeToolArguments
+};

package/openclaw.plugin.json

@@ -0,0 +1,29 @@
+{
+  "id": "settld",
+  "name": "Settld",
+  "description": "Settld tools for OpenClaw with runtime env auto-discovery from Settld setup.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "baseUrl": {
+        "type": "string"
+      },
+      "tenantId": {
+        "type": "string"
+      },
+      "apiKey": {
+        "type": "string"
+      },
+      "paidToolsBaseUrl": {
+        "type": "string"
+      },
+      "paidToolsAgentPassport": {
+        "type": "string"
+      },
+      "mcpConfigPath": {
+        "type": "string"
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "settld",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Settld kernel CLI and local control-plane tooling",
   "private": false,
   "type": "module",
@@ -19,6 +19,8 @@
     "README.md",
     "Dockerfile",
     "docker-compose.yml",
+    "openclaw.plugin.json",
+    "openclaw",
     "bin",
     "conformance",
     "packages/api-sdk/src",
@@ -35,6 +37,11 @@
     "settld": "bin/settld.js",
     "settld-mcp": "bin/settld-mcp"
   },
+  "openclaw": {
+    "extensions": [
+      "./openclaw/index.js"
+    ]
+  },
   "exports": {
     "./mcp": "./scripts/mcp/settld-mcp-server.mjs"
   },

package/scripts/setup/host-config.mjs

@@ -299,7 +299,7 @@ function parsePaidToolsAgentPassportFromEnv(env) {
 
 function parseMcpArgsFromEnv(env) {
   const argsJson = typeof env.SETTLD_MCP_ARGS_JSON === "string" ? env.SETTLD_MCP_ARGS_JSON.trim() : "";
-  if (!argsJson) return ["-y", "settld-mcp"];
+  if (!argsJson) return ["-y", "--package", "settld", "settld-mcp"];
   let parsed;
   try {
     parsed = JSON.parse(argsJson);

package/scripts/setup/onboard.mjs

@@ -874,8 +874,10 @@ function buildHostNextSteps({ host, installedHosts }) {
   }
   if (host === "openclaw") {
     steps.push("Run `openclaw doctor` and ensure OpenClaw itself is onboarded (`openclaw onboard --install-daemon`).");
-    steps.push("Run `openclaw tui`.");
-    steps.push("In OpenClaw, ask for a Settld tool call (for example: `run settld.about`).");
+    steps.push("Install the Settld OpenClaw plugin: `openclaw plugins install settld@latest`.");
+    steps.push("Verify in local mode: `openclaw agent --local --agent main --session-id settld-smoke --message \"Use the tool named settld_about with empty arguments. Return only JSON.\" --json`.");
+    steps.push("Run `openclaw tui --session main`.");
+    steps.push("If you are in a channel-bound session (e.g. whatsapp:*), switch back to `main` to access Settld tools.");
     return steps;
   }
   if (host === "codex") {
@@ -1020,6 +1022,17 @@ async function runGuidedQuickFlow({
     }
   }
 
+  const paidToolsBaseUrl = String(actionEnv.SETTLD_PAID_TOOLS_BASE_URL ?? "").trim();
+  if (!paidToolsBaseUrl) {
+    summary.firstPaidCall = {
+      ok: false,
+      skipped: true,
+      reason: "SETTLD_PAID_TOOLS_BASE_URL not configured"
+    };
+    summary.warnings.push("first paid call probe skipped (SETTLD_PAID_TOOLS_BASE_URL not configured)");
+    return summary;
+  }
+
   const paidProbe = runMcpPaidCallProbe({ env: actionEnv });
   if (paidProbe.ok) {
     summary.firstPaidCall = { ok: true };
@@ -1958,7 +1971,8 @@ export async function runOnboard({
       if (guided.ran) {
         lines.push(`- wallet fund: ${guided.walletFund?.ok ? "ok" : "not completed"}`);
         lines.push(`- wallet balance watch: ${guided.walletBalanceWatch?.ok ? "ok" : "not completed"}`);
-        lines.push(`- first paid call: ${guided.firstPaidCall?.ok ? "ok" : "failed"}`);
+        const firstPaidCallState = guided.firstPaidCall?.skipped ? "skipped" : guided.firstPaidCall?.ok ? "ok" : "failed";
+        lines.push(`- first paid call: ${firstPaidCallState}`);
       } else {
         lines.push("- skipped");
       }

package/services/magic-link/src/server.js

@@ -5262,7 +5262,7 @@ async function handleTenantRuntimeBootstrap(req, res, tenantId) {
   const mcp = {
     schemaVersion: "SettldMcpServerConfig.v1",
     command: "npx",
-    args: ["-y", "settld-mcp"],
+    args: ["-y", "--package", "settld", "settld-mcp"],
     env: mcpEnv
   };
   const mcpConfigJson = {
@@ -6212,7 +6212,7 @@ async function handleTenantRuntimeConformanceMatrix(req, res, tenantId) {
   const smokeOk = checkById.get("mcp_smoke")?.status === "pass";
   const paidOk = checkById.get("first_paid_call")?.status === "pass";
   const targetRows = targets.map((target) => {
-    const serverConfig = mcpEnv ? { command: "npx", args: ["-y", "settld-mcp"], env: mcpEnv } : null;
+    const serverConfig = mcpEnv ? { command: "npx", args: ["-y", "--package", "settld", "settld-mcp"], env: mcpEnv } : null;
     let config;
     if (target === "openhands") {
       config = {