@termhub/agent 0.3.0 → 0.4.0

package/dist/cli.js

@@ -93,6 +93,8 @@ var PROTOCOL_VERSION = 1;
 var CLOSE = { UNAUTHORIZED: 4401, CONFLICT: 4409, VIOLATION: 1008 };
 var channel = z2.number().int().min(1).max(4294967295);
 var rpcId = z2.string().min(1).max(64);
+var closedReason = z2.enum(["cli_missing", "run_failed", "killed", "missing_session", "cli_rejected"]);
+var CAPABILITY_CLAUDE = "claude";
 var helloMessage = z2.object({
   type: z2.literal("hello"),
   protocol: z2.number().int().min(1),
@@ -105,19 +107,44 @@ var helloMessage = z2.object({
   /** `status`/`doctor` reachability check: the server validates the token and protocol as
    *  usual but does not attach — it answers by closing 1000 `probe-ok`, so a probe never
    *  replaces the machine's live session. */
-  probe: z2.boolean().optional()
+  probe: z2.boolean().optional(),
+  // What this agent understands beyond the baseline `pty` channel (e.g. `claude`, for a
+  // headless Claude run). Optional, defaulting to [] — every agent already in the field sent
+  // `hello` before this field existed, so it must keep parsing, reading as "no capabilities"
+  // rather than failing validation or coming back `undefined`. The server decides whether it
+  // may open a `claude` channel from this list, before it ever tries.
+  capabilities: z2.array(z2.string().max(64)).max(32).default([])
 });
 var agentMessage = z2.discriminatedUnion("type", [
   helloMessage,
   z2.object({ type: z2.literal("rpc_result"), id: rpcId, ok: z2.boolean(), result: z2.unknown().optional(), error: rpcErrorSchema.optional() }),
   z2.object({ type: z2.literal("opened"), ch: channel }),
   z2.object({ type: z2.literal("open_error"), ch: channel, error: rpcErrorSchema }),
-  z2.object({ type: z2.literal("closed"), ch: channel, code: z2.number().int().nullable() })
+  // `reason` is absent for a clean exit and for every pty close today; a headless claude run
+  // (task 3) sets it so the server can render the same failure the same way every time.
+  z2.object({ type: z2.literal("closed"), ch: channel, code: z2.number().int().nullable(), reason: closedReason.optional() })
 ]);
 var ptyOpenParams = z2.object({ session: sessionName, cwd: machinePath, cols: z2.number().int().min(2).max(500), rows: z2.number().int().min(2).max(200) });
-var serverMessage = z2.discriminatedUnion("type", [
+var claudeOpenParams = z2.object({
+  session_id: z2.string(),
+  resume: z2.boolean(),
+  // null selects the machine's default Claude account; a path names a specific one.
+  config_dir: z2.string().nullable(),
+  mcp_url: z2.string(),
+  // The user's own token for this run, minted by the server per run and revoked the moment
+  // the next one starts. It travels here, in the frame that opens the channel, rather than
+  // over the channel itself, because the channel doesn't exist yet when the agent needs it —
+  // opening a channel to the user's own machine is exactly the trust boundary this grant
+  // belongs at, so there is no separate, later place to hand it over.
+  token: z2.string(),
+  model: z2.string().nullable().optional()
+});
+var openPty = z2.object({ type: z2.literal("open"), ch: channel, kind: z2.literal("pty"), params: ptyOpenParams });
+var openClaude = z2.object({ type: z2.literal("open"), ch: channel, kind: z2.literal("claude"), params: claudeOpenParams });
+var serverMessage = z2.union([
   z2.object({ type: z2.literal("rpc"), id: rpcId, method: rpcMethod, params: z2.unknown() }),
-  z2.object({ type: z2.literal("open"), ch: channel, kind: z2.literal("pty"), params: ptyOpenParams }),
+  openPty,
+  openClaude,
   z2.object({ type: z2.literal("resize"), ch: channel, cols: z2.number().int().min(2).max(500), rows: z2.number().int().min(2).max(200) }),
   z2.object({ type: z2.literal("close"), ch: channel })
 ]);
@@ -766,8 +793,8 @@ import { execFile } from "child_process";
 import os2 from "os";
 var DEFAULT_TIMEOUT_MS = 8e3;
 var RpcFailure = class extends Error {
-  constructor(code, message, path12) {
-    super(message);
+  constructor(code, message2, path12) {
+    super(message2);
     this.code = code;
     this.path = path12;
   }
@@ -863,8 +890,8 @@ async function install(params, home = os3.homedir()) {
     try {
       merged.push({ target, body: mergeClaudeSettings(await readOrEmpty2(target.file), scriptPath) });
     } catch (err) {
-      const message = err instanceof SyntaxError || err instanceof Error && err.message.includes("n\xE3o \xE9 um objeto JSON") ? `${target.shown} n\xE3o \xE9 JSON v\xE1lido` : err instanceof Error ? err.message : String(err);
-      throw new RpcFailure("failed", message, relPath(target.shown));
+      const message2 = err instanceof SyntaxError || err instanceof Error && err.message.includes("n\xE3o \xE9 um objeto JSON") ? `${target.shown} n\xE3o \xE9 JSON v\xE1lido` : err instanceof Error ? err.message : String(err);
+      throw new RpcFailure("failed", message2, relPath(target.shown));
     }
   }
   const hasCodex = await isDir2(path3.join(home, CODEX_DIR_REL));
@@ -946,6 +973,252 @@ async function uninstall(params, home = os3.homedir()) {
   return { removed: true };
 }
 
+// ../../packages/claude-cli/dist/index.js
+var DISALLOWED_TOOLS = "Bash,Read,Write,Edit,WebFetch,WebSearch";
+function buildClaudeArgs(spec) {
+  return [
+    "-p",
+    // Exactly one of the two, never both: the CLI answers "--session-id can only be used with
+    // --continue or --resume if --fork-session is also specified" and exits 1 before doing any
+    // work, which broke every message after the first. --session-id is how the server names a new
+    // session; --resume is how it continues one it already named.
+    ...spec.resume ? ["--resume", spec.session_id] : ["--session-id", spec.session_id],
+    "--output-format",
+    "stream-json",
+    // required by the CLI: with --print, --output-format=stream-json refuses to run without it
+    // ("Error: When using --print, --output-format=stream-json requires --verbose"). It only
+    // changes what the CLI writes to stdout, never logging the prompt.
+    "--verbose",
+    "--include-partial-messages",
+    "--mcp-config",
+    spec.mcp_config_path,
+    "--strict-mcp-config",
+    "--allowed-tools",
+    "mcp__termhub__*",
+    "--disallowed-tools",
+    DISALLOWED_TOOLS,
+    ...spec.model ? ["--model", spec.model] : []
+  ];
+}
+function mcpConfig(url, token) {
+  return JSON.stringify({ mcpServers: { termhub: { type: "http", url, headers: { Authorization: `Bearer ${token}` } } } });
+}
+function classifyFailure(stderr) {
+  if (/No conversation found/i.test(stderr))
+    return "missing_session";
+  if (/^Error: --/m.test(stderr))
+    return "cli_rejected";
+  return "run_failed";
+}
+
+// src/claude/run.ts
+import { spawn } from "child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+var DEFAULT_TIMEOUT_MS2 = 10 * 60 * 1e3;
+var KILL_GRACE_MS = 2e3;
+var PROMPT_TIMEOUT_MS = 3e4;
+var MAX_LINE_BYTES = MAX_FRAME - HEADER_BYTES - 1;
+var STDERR_TAIL_BYTES = 4e3;
+var CLI = "claude";
+function message(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function createClaudeManager(deps) {
+  const runs = /* @__PURE__ */ new Map();
+  return {
+    // Synchronous from end to end (the promise is for symmetry with the PTY manager), so no
+    // `close` for this channel can interleave before the run is in `runs` and killable.
+    async open(ch, params, socket) {
+      if (runs.has(ch)) {
+        socket.sendControl({ type: "open_error", ch, error: { code: "invalid", message: "channel in use" } });
+        return;
+      }
+      let dir;
+      let mcpConfigPath;
+      try {
+        dir = mkdtempSync(join(deps.tmpDir ?? tmpdir(), "termhub-claude-"));
+        mcpConfigPath = join(dir, "termhub-mcp.json");
+        writeFileSync(mcpConfigPath, mcpConfig(params.mcp_url, params.token), { mode: 384 });
+      } catch (err) {
+        deps.log("claude run could not prepare its mcp config", { ch, error: message(err) });
+        if (dir) rmSync(dir, { recursive: true, force: true });
+        socket.sendControl({ type: "open_error", ch, error: { code: "internal", message: "failed to prepare the claude run" } });
+        return;
+      }
+      const runDir = dir;
+      socket.sendControl({ type: "opened", ch });
+      deps.log("claude run starting", { ch, resume: params.resume, model: params.model ?? null });
+      const env = { ...deps.env ?? agentEnv() };
+      if (params.config_dir === null) delete env.CLAUDE_CONFIG_DIR;
+      else env.CLAUDE_CONFIG_DIR = params.config_dir;
+      const args = buildClaudeArgs({
+        session_id: params.session_id,
+        resume: params.resume,
+        mcp_config_path: mcpConfigPath,
+        model: params.model ?? null
+      });
+      let child;
+      try {
+        child = spawn(CLI, args, { env, stdio: ["pipe", "pipe", "pipe"], detached: true });
+      } catch (err) {
+        deps.log("claude run could not be started", { ch, cli: CLI, error: message(err) });
+        rmSync(runDir, { recursive: true, force: true });
+        socket.sendControl({ type: "closed", ch, code: null, reason: "run_failed" });
+        return;
+      }
+      let settled = false;
+      let escalation;
+      let stderr = "";
+      let stderrBytes = 0;
+      let buffer = "";
+      let overlong = false;
+      let droppedLines = 0;
+      function signalRun(signal) {
+        try {
+          if (child.pid) process.kill(-child.pid, signal);
+          else child.kill(signal);
+        } catch {
+          try {
+            child.kill(signal);
+          } catch {
+          }
+        }
+      }
+      function killRun(hard = false) {
+        if (child.exitCode !== null || child.signalCode !== null) return;
+        signalRun("SIGTERM");
+        if (hard) {
+          signalRun("SIGKILL");
+          return;
+        }
+        if (escalation) return;
+        escalation = setTimeout(() => signalRun("SIGKILL"), KILL_GRACE_MS);
+        escalation.unref();
+      }
+      function settle(code, reason, notify = true) {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        clearTimeout(promptTimer);
+        if (runs.get(ch) === run2) runs.delete(ch);
+        try {
+          rmSync(runDir, { recursive: true, force: true });
+        } catch (err) {
+          deps.log("claude run dir could not be removed", { ch, error: message(err) });
+        }
+        if (!notify) return;
+        try {
+          socket.sendControl(reason ? { type: "closed", ch, code, reason } : { type: "closed", ch, code });
+        } catch (err) {
+          deps.log("claude closed send failed", { ch, error: message(err) });
+        }
+      }
+      function emitLine(line) {
+        if (!line.trim()) return;
+        if (Buffer.byteLength(line, "utf8") > MAX_LINE_BYTES) {
+          droppedLines += 1;
+          deps.log("claude stdout line too large to frame, dropped", { ch, bytes: Buffer.byteLength(line, "utf8") });
+          return;
+        }
+        sendLine(line);
+      }
+      function sendLine(line) {
+        if (settled) return;
+        try {
+          socket.sendStream(ch, Buffer.from(`${line}
+`, "utf8"));
+        } catch (err) {
+          deps.log("claude stream send failed", { ch, error: message(err) });
+        }
+      }
+      const timer = setTimeout(() => {
+        deps.log("claude run timed out", { ch, timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS2 });
+        killRun();
+      }, deps.timeoutMs ?? DEFAULT_TIMEOUT_MS2);
+      timer.unref();
+      const promptTimer = setTimeout(() => {
+        deps.log("claude run got no prompt", { ch, promptTimeoutMs: deps.promptTimeoutMs ?? PROMPT_TIMEOUT_MS });
+        killRun();
+        settle(null, "run_failed");
+      }, deps.promptTimeoutMs ?? PROMPT_TIMEOUT_MS);
+      promptTimer.unref();
+      const run2 = {
+        child,
+        promptSent: false,
+        kill: killRun,
+        promptArrived: () => clearTimeout(promptTimer),
+        settle
+      };
+      runs.set(ch, run2);
+      child.stdin?.on("error", () => {
+      });
+      child.stdout?.setEncoding("utf8");
+      child.stdout?.on("data", (chunk) => {
+        buffer += chunk;
+        for (; ; ) {
+          const nl = buffer.indexOf("\n");
+          if (nl === -1) break;
+          const line = buffer.slice(0, nl);
+          buffer = buffer.slice(nl + 1);
+          if (overlong) overlong = false;
+          else emitLine(line);
+        }
+        if (Buffer.byteLength(buffer, "utf8") <= MAX_LINE_BYTES) return;
+        if (!overlong) {
+          overlong = true;
+          droppedLines += 1;
+          deps.log("claude stdout line too large to frame, dropped", { ch, bytes: Buffer.byteLength(buffer, "utf8") });
+        }
+        buffer = "";
+      });
+      child.stderr?.on("data", (data) => {
+        stderrBytes += data.length;
+        stderr = (stderr + data.toString("utf8")).slice(-STDERR_TAIL_BYTES);
+      });
+      child.on("error", (err) => {
+        const missing = err.code === "ENOENT";
+        deps.log(missing ? `claude cli not found on this machine (${CLI})` : "claude run failed to start", { ch, cli: CLI, error: err.message });
+        killRun();
+        settle(null, missing ? "cli_missing" : "run_failed");
+      });
+      child.on("close", (code) => {
+        if (escalation) clearTimeout(escalation);
+        if (!overlong) emitLine(buffer);
+        buffer = "";
+        deps.log("claude run ended", { ch, code, stderrBytes, droppedLines });
+        if (code === 0) settle(0);
+        else settle(code, classifyFailure(stderr));
+      });
+    },
+    write(ch, data) {
+      const run2 = runs.get(ch);
+      if (!run2) return false;
+      if (run2.promptSent) {
+        deps.log("extra data on a claude channel ignored", { ch, bytes: data.length });
+        return true;
+      }
+      run2.promptSent = true;
+      run2.promptArrived();
+      run2.child.stdin?.end(data);
+      return true;
+    },
+    close(ch) {
+      const run2 = runs.get(ch);
+      if (!run2) return;
+      run2.kill();
+      run2.settle(null, "killed");
+    },
+    closeAll() {
+      for (const run2 of [...runs.values()]) {
+        run2.kill(true);
+        run2.settle(null, "killed", false);
+      }
+    }
+  };
+}
+
 // src/dispatch.ts
 async function handleRpc(msg, socket, handlers2, log2) {
   const method = msg.method;
@@ -986,16 +1259,19 @@ function createDispatcher(deps) {
       case "rpc":
         void handleRpc(msg, socket, deps.handlers, deps.log);
         break;
-      case "open":
-        deps.pty.open(msg.ch, msg.params, socket).catch((err) => {
-          deps.log("pty.open rejected unexpectedly", { ch: msg.ch, error: err instanceof Error ? err.message : String(err) });
+      case "open": {
+        const opened = msg.kind === "claude" ? deps.claude.open(msg.ch, msg.params, socket) : deps.pty.open(msg.ch, msg.params, socket);
+        opened.catch((err) => {
+          deps.log(`${msg.kind}.open rejected unexpectedly`, { ch: msg.ch, error: err instanceof Error ? err.message : String(err) });
         });
         break;
+      }
       case "resize":
         deps.pty.resize(msg.ch, msg.cols, msg.rows);
         break;
       case "close":
         deps.pty.close(msg.ch);
+        deps.claude.close(msg.ch);
         break;
     }
   };
@@ -1060,8 +1336,8 @@ function isSpawnHelperFailure(err) {
 function isEnoent2(err) {
   const e = err;
   if (e?.code === "ENOENT") return true;
-  const message = e instanceof Error ? e.message : String(err);
-  return /ENOENT/.test(message);
+  const message2 = e instanceof Error ? e.message : String(err);
+  return /ENOENT/.test(message2);
 }
 function createPtyManager(deps) {
   const procs = /* @__PURE__ */ new Map();
@@ -1092,8 +1368,8 @@ function createPtyManager(deps) {
           TERMHUB_TAB_ID: params.session,
           TERMHUB_SESSION: params.session
         };
-        const spawn = await resolveSpawn();
-        const spawnTmux = () => spawn(tmux, ["-u", "new-session", "-A", "-s", params.session, "-c", cwd], { name: "xterm-256color", cols, rows, cwd, env });
+        const spawn2 = await resolveSpawn();
+        const spawnTmux = () => spawn2(tmux, ["-u", "new-session", "-A", "-s", params.session, "-c", cwd], { name: "xterm-256color", cols, rows, cwd, env });
         try {
           proc = spawnTmux();
         } catch (err) {
@@ -1557,7 +1833,7 @@ async function status3() {
 }
 
 // src/version.ts
-var AGENT_VERSION = "0.3.0";
+var AGENT_VERSION = "0.4.0";
 
 // src/rpc/update.ts
 var PACKAGE = "@termhub/agent";
@@ -1646,6 +1922,7 @@ function detectOs(platform = process.platform) {
   if (platform === "linux") return "linux";
   return null;
 }
+var CAPABILITIES = [CAPABILITY_CLAUDE];
 async function buildHello(osName) {
   let tools = [];
   try {
@@ -1660,7 +1937,8 @@ async function buildHello(osName) {
     arch: process.arch,
     hostname: os6.hostname(),
     tmux: tools.includes("tmux"),
-    tools
+    tools,
+    capabilities: CAPABILITIES
   };
 }
 var REVOKED_MESSAGE = "Token inv\xE1lido ou revogado";
@@ -1678,7 +1956,7 @@ async function checkServerConnection(config, timeoutMs = 5e3) {
       {
         url: config.url,
         token: config.token,
-        hello: { agent_version: AGENT_VERSION, os: osName, arch: process.arch, hostname: os6.hostname(), tmux: false, tools: [], probe: true },
+        hello: { agent_version: AGENT_VERSION, os: osName, arch: process.arch, hostname: os6.hostname(), tmux: false, tools: [], capabilities: CAPABILITIES, probe: true },
         onServerMessage: () => {
         },
         onStream: () => {
@@ -1704,8 +1982,8 @@ async function checkServerConnection(config, timeoutMs = 5e3) {
     controller.abort();
   }
 }
-async function exitWithoutRestart(message) {
-  console.error(message);
+async function exitWithoutRestart(message2) {
+  console.error(message2);
   await stopRestartLoop();
   process.exit(78);
 }
@@ -1720,7 +1998,8 @@ async function runAgent(config, opts) {
   if (helper.repaired) opts.log("spawn-helper exec bit repaired", { path: helper.path });
   else if (!helper.executable) opts.log("spawn-helper is not executable and could not be fixed", { path: helper.path, error: helper.error });
   const pty = createPtyManager({ log: opts.log });
-  const dispatch = createDispatcher({ handlers, pty, log: opts.log });
+  const claude = createClaudeManager({ log: opts.log });
+  const dispatch = createDispatcher({ handlers, pty, claude, log: opts.log });
   const healHooks = () => {
     heal().then((dirs) => {
       if (dirs.length) opts.log("monitor hooks repaired", { dirs: dirs.length });
@@ -1734,9 +2013,16 @@ async function runAgent(config, opts) {
         token: config.token,
         hello,
         onServerMessage: dispatch,
-        onStream: (ch, data) => pty.write(ch, data),
+        // A frame belongs to whichever manager holds that channel: the claude one says so, and
+        // anything it does not own is a terminal's.
+        onStream: (ch, data) => {
+          if (!claude.write(ch, data)) pty.write(ch, data);
+        },
         onConnect: healHooks,
-        onDisconnect: () => pty.closeAll(),
+        onDisconnect: () => {
+          pty.closeAll();
+          claude.closeAll();
+        },
         log: opts.log
       },
       opts.signal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@termhub/agent",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Agente do termhub: conecta esta máquina ao servidor por WebSocket de saída (sem SSH) e expõe os terminais tmux no navegador.",
   "license": "MIT",
   "private": false,
@@ -34,6 +34,7 @@
   },
   "devDependencies": {
     "@termhub/agent-protocol": "*",
+    "@termhub/claude-cli": "*",
     "@termhub/machine-ops": "*",
     "@types/node": "^22.10.5",
     "@types/ws": "^8.5.13",