@warble/claude-agent-sdk 0.15.3 → 0.16.0

package/README.md

@@ -93,6 +93,29 @@ over turn. `--stream-json` streams one `WarbleChatEvent` NDJSON line per event
 `{"t":"answer",…}` line; every turn also emits a `{"t":"session","id":…}` line — on success **and**
 on a failed turn — so a caller can resume that conversation with `--resume <session-id>`.
 
+`chat --host-mcp-config <absolute path>` lets a host give the agent its own tools through one stdio
+MCP server ([`src/hostMcp.ts`](./src/hostMcp.ts)). The file is a closed JSON object:
+
+```json
+{
+  "name": "host_tools",
+  "command": "/absolute/path/to/server",
+  "args": ["--token-file", "/absolute/path/to/token"],
+  "tools": ["query"],
+  "instruction": "Optional single line appended to the system prompt."
+}
+```
+
+It must be an absolute path to a regular file (opened with `O_NOFOLLOW`, so a symlink is refused),
+owned by the current user, with no group or other permission bits (`chmod 600`). `name` matches
+`[a-z0-9_]{1,32}`, `tools` is a non-empty list of `[a-z0-9_]{1,64}`, `instruction` is one line of at
+most 300 characters, and unknown keys are rejected. The server is passed to `query()` as a stdio
+`mcpServers` entry; the read-only guardrail then allows exactly `mcp__<name>__<tool>` for the listed
+tools and still refuses every other `mcp__*` tool, and the `wren`-only Bash rule is unchanged. Keep
+secrets out of this file — pass a token file path in `args` instead; the CLI never prints the file,
+its `args`, or the environment. Hybrid-staged plans refuse the flag. Without it, `chat` behaves
+exactly as before.
+
 `list-models` emits exactly one versioned JSON object for the currently authenticated Claude
 subscription. It exposes only model ID, display name, and description; unavailable authentication,
 runtime, timeout, or protocol states are returned as sanitized JSON. It uses an empty SDK input and

package/dist/{chunk-XH2CFK2E.js → chunk-6GZGHFX7.js}

@@ -299,6 +299,98 @@ function emitAgentModule(prepared, opts = {}) {
   ].join("\n");
 }
 
+// src/hostMcp.ts
+import { closeSync, constants, fstatSync, openSync, readFileSync } from "fs";
+import { isAbsolute } from "path";
+var NAME_RE = /^[a-z0-9_]{1,32}$/;
+var TOOL_RE = /^[a-z0-9_]{1,64}$/;
+var LINE_BREAK_RE = /[\r\n\u2028\u2029]/;
+var MAX_INSTRUCTION = 300;
+var ALLOWED_KEYS = /* @__PURE__ */ new Set(["name", "command", "args", "tools", "instruction"]);
+function reject(reason) {
+  throw new DispatchError(`--host-mcp-config: ${reason}`);
+}
+function readTrustedFile(path) {
+  if (!isAbsolute(path)) reject("the path must be absolute");
+  const uid = typeof process.getuid === "function" ? process.getuid() : void 0;
+  if (uid === void 0) reject("file ownership cannot be verified on this platform");
+  let fd;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  } catch (e) {
+    const code = e.code;
+    if (code === "ELOOP") reject("the path must not be a symbolic link");
+    reject(`the file cannot be opened (${code ?? "unknown error"})`);
+  }
+  try {
+    const st = fstatSync(fd);
+    if (!st.isFile()) reject("the path must be a regular file");
+    if (st.uid !== uid) reject("the file must be owned by the current user");
+    if ((st.mode & 63) !== 0) {
+      reject("the file must not be accessible by group or others (chmod 600)");
+    }
+    return readFileSync(fd, "utf8");
+  } finally {
+    closeSync(fd);
+  }
+}
+function parseHostMcpConfig(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    reject("the file must contain a JSON object");
+  }
+  const obj = value;
+  for (const key of Object.keys(obj)) {
+    if (!ALLOWED_KEYS.has(key)) reject(`unknown key '${key.slice(0, 64)}'`);
+  }
+  const { name, command, args, tools, instruction } = obj;
+  if (typeof name !== "string" || !NAME_RE.test(name)) reject("'name' must match [a-z0-9_]{1,32}");
+  if (typeof command !== "string" || !isAbsolute(command)) {
+    reject("'command' must be an absolute path");
+  }
+  if (!Array.isArray(args) || !args.every((a) => typeof a === "string")) {
+    reject("'args' must be an array of strings");
+  }
+  if (!Array.isArray(tools) || tools.length === 0) reject("'tools' must be a non-empty array");
+  for (const t of tools) {
+    if (typeof t !== "string" || !TOOL_RE.test(t)) {
+      reject("each of 'tools' must match [a-z0-9_]{1,64}");
+    }
+  }
+  if (new Set(tools).size !== tools.length) reject("'tools' must not repeat a tool");
+  if (instruction !== void 0) {
+    if (typeof instruction !== "string" || instruction.trim().length === 0) {
+      reject("'instruction' must be a non-empty string");
+    }
+    if (instruction.length > MAX_INSTRUCTION) {
+      reject(`'instruction' must be at most ${MAX_INSTRUCTION} characters`);
+    }
+    if (LINE_BREAK_RE.test(instruction)) reject("'instruction' must be a single line");
+  }
+  return {
+    name,
+    command,
+    args: [...args],
+    tools: [...tools],
+    ...instruction !== void 0 ? { instruction } : {}
+  };
+}
+function loadHostMcpConfig(path) {
+  const raw = readTrustedFile(path);
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    reject("the file is not valid JSON");
+  }
+  return parseHostMcpConfig(parsed);
+}
+function hostMcpToolNames(cfg) {
+  return cfg.tools.map((tool3) => `mcp__${cfg.name}__${tool3}`);
+}
+function hostMcpServerEntry(cfg) {
+  return { type: "stdio", command: cfg.command, args: [...cfg.args] };
+}
+
 // src/closure.ts
 function freezeArray(values) {
   return Object.freeze(values);
@@ -1902,12 +1994,12 @@ import {
   existsSync,
   lstatSync,
   mkdirSync,
-  readFileSync,
+  readFileSync as readFileSync2,
   realpathSync,
   statSync,
   writeFileSync
 } from "fs";
-import { dirname, isAbsolute, join, parse, resolve, sep } from "path";
+import { dirname, isAbsolute as isAbsolute2, join, parse, resolve, sep } from "path";
 function assetDirForIr(irPath) {
   const { dir, name } = parse(resolve(irPath));
   return join(dir, `${name}.assets`);
@@ -1932,7 +2024,7 @@ function prepareAssetLanding(ir, irPath, cwd) {
           `asset '${asset.path}' of component '${node.id}' is not a regular file. Reading a pipe or device would block the dispatch indefinitely instead of failing, so anything that is not a plain file is refused.`
         );
       }
-      const data = readFileSync(source);
+      const data = readFileSync2(source);
       const actual = `sha256:${createHash("sha256").update(data).digest("hex")}`;
       if (actual !== asset.hash) {
         throw new DispatchError(
@@ -1959,7 +2051,7 @@ function landAssets(ir, irPath, cwd) {
 }
 function assertContainedRelativePath(relative, componentId) {
   const climbs = relative.split(/[\\/]/).includes("..");
-  if (isAbsolute(relative) || climbs || relative.startsWith(sep)) {
+  if (isAbsolute2(relative) || climbs || relative.startsWith(sep)) {
     throw new DispatchError(
       `asset path '${relative}' of component '${componentId}' must be a relative path with no '..' segments. A manifest naming a path outside the directory it lands in would be an arbitrary file write, so it is refused rather than resolved.`
     );
@@ -2162,6 +2254,9 @@ function makeReadOnlyGuard(cfg) {
       denials.push({ tool: toolName, reason: reason2 });
       return deny(reason2);
     }
+    if (cfg.hostMcpTools?.includes(toolName)) {
+      return allow(input);
+    }
     const reason = `tool '${toolName}' is not permitted for this component.`;
     denials.push({ tool: toolName, reason });
     return deny(reason);
@@ -2603,6 +2698,27 @@ function aggregateTrace(messages, meta, denials) {
     denials
   };
 }
+function applyHostMcp(options, hostMcp) {
+  if (options.mcpServers && hostMcp.name in options.mcpServers) {
+    throw new DispatchError(
+      `--host-mcp-config: MCP server name '${hostMcp.name}' is already used by this plan`
+    );
+  }
+  const next = {
+    ...options,
+    mcpServers: { ...options.mcpServers, [hostMcp.name]: hostMcpServerEntry(hostMcp) }
+  };
+  if (hostMcp.instruction !== void 0) {
+    if (typeof options.systemPrompt !== "string") {
+      throw new DispatchError(
+        "--host-mcp-config: 'instruction' needs a plain-string system prompt, which this plan does not have"
+      );
+    }
+    next.systemPrompt = `${options.systemPrompt}
+${hostMcp.instruction}`;
+  }
+  return next;
+}
 var DispatchSessionError = class extends DispatchError {
   constructor(message, sessionId) {
     super(message);
@@ -2642,6 +2758,11 @@ async function runDispatch(plan, cfg) {
     );
   }
   if (plan.meta.mode === "hybrid-staged") {
+    if (cfg.hostMcp) {
+      throw new DispatchError(
+        "--host-mcp-config is not supported for a hybrid-staged plan (steps span providers)"
+      );
+    }
     return process.env["WARBLE_HYBRID_MODE"] === "tool" ? runHybridTool(plan, cfg) : runHybridStaged(plan, cfg);
   }
   mkdirSync3(cfg.outDir, { recursive: true });
@@ -2652,12 +2773,13 @@ async function runDispatch(plan, cfg) {
     readOnly: plan.meta.readOnly,
     writeScope,
     cwd,
-    setupScope: plan.meta.setupScope
+    setupScope: plan.meta.setupScope,
+    ...cfg.hostMcp ? { hostMcpTools: hostMcpToolNames(cfg.hostMcp) } : {}
   });
   const venvBin = join4(cwd, ".venv", "bin");
   const pathEnv = existsSync3(venvBin) ? `${venvBin}:${process.env.PATH ?? ""}` : process.env.PATH ?? "";
   const env = { ...process.env, PATH: pathEnv };
-  const options = {
+  const baseOptions = {
     ...plan.options,
     canUseTool: composeCanUseTool(plan.options.canUseTool, canUseTool),
     // Read never reaches `canUseTool` for an in-cwd path in the real SDK (see guardrails.ts); this
@@ -2666,6 +2788,7 @@ async function runDispatch(plan, cfg) {
     env,
     ...cfg.resume ? { resume: cfg.resume } : {}
   };
+  const options = cfg.hostMcp ? applyHostMcp(baseOptions, cfg.hostMcp) : baseOptions;
   if (cfg.assets) landAssets(cfg.assets.ir, cfg.assets.irPath, cwd);
   reportPromptFingerprint(cfg, options);
   const mapper = new ChatEventMapper(plan.meta.verb);
@@ -3797,7 +3920,7 @@ async function runComposedDispatch(plan, cfg) {
 }
 
 // src/dispatch.ts
-import { dirname as dirname2, isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
+import { dirname as dirname2, isAbsolute as isAbsolute3, resolve as resolve2 } from "path";
 var UNAVAILABLE_COMPONENT_REASON = "component is unavailable on the configured runtime";
 function deepFreeze(value) {
   if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
@@ -3842,7 +3965,7 @@ function assertInvocationRealization(closure, reports, target) {
 function resolveProjectCwd(node, opts) {
   if (opts.project) return resolve2(opts.project);
   const p = node.context_binding.project;
-  if (isAbsolute2(p)) return p;
+  if (isAbsolute3(p)) return p;
   const baseDir = opts.irPath ? dirname2(resolve2(opts.irPath)) : process.cwd();
   return resolve2(baseDir, p);
 }
@@ -4285,10 +4408,10 @@ async function withinTimeout(operation, timeoutMs, abortController) {
   try {
     return await Promise.race([
       operation,
-      new Promise((_, reject) => {
+      new Promise((_, reject2) => {
         timer = setTimeout(() => {
           abortController.abort();
-          reject(new Error("model catalog timed out"));
+          reject2(new Error("model catalog timed out"));
         }, timeoutMs);
       })
     ]);
@@ -4450,6 +4573,9 @@ function createChatSession(plan, runCfg, initialResumeSessionId) {
 export {
   DispatchError,
   emitAgentModule,
+  parseHostMcpConfig,
+  loadHostMcpConfig,
+  hostMcpToolNames,
   componentDependencies,
   resolveComponentClosure,
   REALIZATION_KINDS,
@@ -4533,4 +4659,4 @@ export {
   ChatSession,
   createChatSession
 };
-//# sourceMappingURL=chunk-XH2CFK2E.js.map
+//# sourceMappingURL=chunk-6GZGHFX7.js.map