@aiaiai-pt/martha-cli 0.45.0 → 0.48.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https
 
 ## [Unreleased]
 
+## [0.48.0] — 2026-07-13
+
+### Changed — BREAKING: `martha runner` means ONE thing (#714 runner-journey unification)
+- Bare `martha runner` now attaches this machine as a **cloud agent's hands** (the
+  previous `--tools` mode): it holds the per-agent channel open and executes
+  `tool.invoke` host-tool calls the agent's Martha-hosted reasoning loop parks on
+  (chat gates and assigned-task parks, #910). `--tools` is kept as an accepted
+  no-op so printed `setup-host-runner` commands stay valid.
+- The startup line now states the model plainly ("this machine is the agent's
+  hands … the agent reasons in Martha's cloud loop") — the old "reasoning stays
+  Martha-hosted regardless" line was false for the removed task mode.
+
+### Removed — the goal-as-`bash -c` task-executor mode
+- `--tasks` (and the pre-#822 `--channel` alias), `--once`, `--team`, `--agent`,
+  and `--poll-interval` are **removed**. They ran a claimed task's goal as a raw
+  `bash -c` — the runner impersonating an external agent. Invoking any of them
+  now fails with migration guidance. **Nothing is stranded:** a self-hosted
+  agent is your own program driving the task REST — `martha tasks
+  poll/claim/heartbeat/complete` are unchanged.
+
 ## [0.30.0] — 2026-07-03
 
 ### Added — #761 runner heartbeat + poll-based cancel

package/dist/index.js

@@ -11119,7 +11119,7 @@ init_config();
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.45.0";
+var CLI_VERSION = "0.48.0";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -12249,6 +12249,7 @@ function parseLocalAgentRequests(data) {
 
 // src/lib/local-tool-runner.ts
 import { createHash as createHash2 } from "node:crypto";
+init_errors();
 
 // src/lib/local-exec.ts
 import { spawn } from "node:child_process";
@@ -12336,68 +12337,6 @@ async function runHostCommand(command, toolCallId, opts) {
 function safeName(s) {
   return s.replace(/[^a-zA-Z0-9_.-]/g, "_").slice(0, 120) || "task";
 }
-async function startHostCommand(command, toolCallId, opts) {
-  const dir = runnerDir(opts.cwd);
-  await fs5.mkdir(dir, { recursive: true });
-  const logPath = path4.join(dir, `${safeName(toolCallId)}.log`);
-  await fs5.writeFile(logPath, "");
-  const fd = openSync(logPath, "a");
-  const cap = opts.maxOutputBytes ?? MAX_OUTPUT;
-  const readLog = async () => {
-    try {
-      const buf = await fs5.readFile(logPath);
-      return buf.subarray(-cap).toString("utf8");
-    } catch {
-      return "";
-    }
-  };
-  const child = spawn(command, {
-    shell: true,
-    cwd: opts.cwd,
-    detached: true,
-    stdio: ["ignore", fd, fd]
-  });
-  closeSync(fd);
-  let exited = false;
-  const done = new Promise((resolve, reject) => {
-    let settled = false;
-    child.on("error", (e) => {
-      if (settled)
-        return;
-      settled = true;
-      exited = true;
-      reject(e);
-    });
-    child.on("close", async (code) => {
-      if (settled)
-        return;
-      settled = true;
-      exited = true;
-      resolve({
-        stdout: await readLog(),
-        stderr: "",
-        exit_code: code ?? -1,
-        log_path: logPath
-      });
-    });
-  });
-  const kill = (graceMs = 5000) => {
-    if (exited || !child.pid)
-      return;
-    try {
-      process.kill(-child.pid, "SIGTERM");
-    } catch {}
-    const escalate = setTimeout(() => {
-      if (exited || !child.pid)
-        return;
-      try {
-        process.kill(-child.pid, "SIGKILL");
-      } catch {}
-    }, graceMs);
-    escalate.unref?.();
-  };
-  return { pid: child.pid, done, kill };
-}
 function mintExecSecret() {
   return randomBytes2(32).toString("hex");
 }
@@ -13393,7 +13332,7 @@ async function resolveLocalAgent(sessionId, toolCallId, req, state) {
 }
 async function claimGate(sessionId, toolCallId, state, transport) {
   if (state.claimed.has(toolCallId))
-    return;
+    return true;
   const secret = state.secrets.get(toolCallId) ?? mintExecSecret();
   const secretHash = createHash2("sha256").update(secret).digest("hex");
   state.secrets.set(toolCallId, secret);
@@ -13401,9 +13340,16 @@ async function claimGate(sessionId, toolCallId, state, transport) {
   try {
     await transport.claim(toolCallId, secretHash);
     state.claimed.add(toolCallId);
+    return true;
   } catch (e) {
+    if (e instanceof MarthaAPIError && e.status === 409) {
+      process.stderr.write(source_default.yellow(`[local-exec] gate ${toolCallId} is not pending (already resolved or timed out) — skipping execution
+`));
+      return false;
+    }
     process.stderr.write(source_default.yellow(`[local-exec] failed to claim gate for ${toolCallId}: ${String(e)}
 `));
+    return true;
   }
 }
 async function postToolResult(toolCallId, result, label, transport, execSecret) {
@@ -13420,7 +13366,8 @@ async function handleToolStatusData(ctx, sessionId, data, state, transport) {
     if (state.handled.has(id))
       continue;
     state.handled.add(id);
-    await claimGate(sessionId, id, state, transport);
+    if (!await claimGate(sessionId, id, state, transport))
+      continue;
     const result = await resolveHostExec(sessionId, id, req, state);
     await postToolResult(id, result, "host_exec", transport, state.secrets.get(id));
   }
@@ -13429,7 +13376,8 @@ async function handleToolStatusData(ctx, sessionId, data, state, transport) {
     if (state.handled.has(id))
       continue;
     state.handled.add(id);
-    await claimGate(sessionId, id, state, transport);
+    if (!await claimGate(sessionId, id, state, transport))
+      continue;
     const result = await resolveHostOutput(req, state);
     await postToolResult(id, result, "host_output", transport, state.secrets.get(id));
   }
@@ -13438,7 +13386,8 @@ async function handleToolStatusData(ctx, sessionId, data, state, transport) {
     if (state.handled.has(id))
       continue;
     state.handled.add(id);
-    await claimGate(sessionId, id, state, transport);
+    if (!await claimGate(sessionId, id, state, transport))
+      continue;
     const result = await resolveHostKill(req, state);
     await postToolResult(id, result, "host_kill", transport, state.secrets.get(id));
   }
@@ -13447,7 +13396,8 @@ async function handleToolStatusData(ctx, sessionId, data, state, transport) {
     if (state.handled.has(id))
       continue;
     state.handled.add(id);
-    await claimGate(sessionId, id, state, transport);
+    if (!await claimGate(sessionId, id, state, transport))
+      continue;
     const result = await resolveHostScreenshot(ctx, sessionId, req, state);
     await postToolResult(id, result, "host_screenshot", transport, state.secrets.get(id));
   }
@@ -13456,7 +13406,8 @@ async function handleToolStatusData(ctx, sessionId, data, state, transport) {
     if (state.handled.has(id))
       continue;
     state.handled.add(id);
-    await claimGate(sessionId, id, state, transport);
+    if (!await claimGate(sessionId, id, state, transport))
+      continue;
     const result = await resolveHostBrowser(ctx, sessionId, req, state);
     await postToolResult(id, result, "host_browser", transport, state.secrets.get(id));
   }
@@ -13465,7 +13416,8 @@ async function handleToolStatusData(ctx, sessionId, data, state, transport) {
     if (state.handled.has(id))
       continue;
     state.handled.add(id);
-    await claimGate(sessionId, id, state, transport);
+    if (!await claimGate(sessionId, id, state, transport))
+      continue;
     const result = await resolveHostFile(req, state);
     await postToolResult(id, result, req.action, transport, state.secrets.get(id));
   }
@@ -13474,7 +13426,8 @@ async function handleToolStatusData(ctx, sessionId, data, state, transport) {
     if (state.handled.has(id))
       continue;
     state.handled.add(id);
-    await claimGate(sessionId, id, state, transport);
+    if (!await claimGate(sessionId, id, state, transport))
+      continue;
     const result = await resolveLocalAgent(sessionId, id, req, state);
     await postToolResult(id, result, "local_agent", transport, state.secrets.get(id));
   }
@@ -17718,9 +17671,6 @@ ${items.length} task(s) available`));
 // src/commands/runner.ts
 import os3 from "node:os";
 init_errors();
-function sleep5(ms) {
-  return new Promise((r) => setTimeout(r, ms));
-}
 function hostLabel() {
   try {
     return os3.hostname() || undefined;
@@ -17734,92 +17684,24 @@ function sleepUnref(ms) {
     t.unref?.();
   });
 }
-var DEFAULT_LEASE_S = 300;
 var ACK_INTERVAL_MS = 5000;
-function heartbeatIntervalMs(leaseTimeoutS) {
-  const lease = typeof leaseTimeoutS === "number" && leaseTimeoutS > 0 ? leaseTimeoutS : DEFAULT_LEASE_S;
-  return Math.min(lease / 3, 60) * 1000;
-}
-async function runOnce(ctx, opts, handled) {
-  const params = { limit: String(opts.pollLimit ?? 5) };
-  if (opts.team)
-    params.team_id = opts.team;
-  const tasks = await ctx.api.get("/api/tasks/poll", { params });
-  const candidates = Array.isArray(tasks) ? tasks : [];
-  const matchesAgent = (t) => !opts.agent || t.assigned_agent_id === opts.agent || t.agent_definition_id === opts.agent;
-  const task = candidates.find((t) => (t.status ?? "open") === "open" && !handled?.has(t.id) && matchesAgent(t));
-  if (!task)
-    return { ran: false };
-  if (!opts.allowHostExec) {
-    process.stderr.write(source_default.yellow(`
-[runner] refused task ${task.id} — re-run with --allow-host-exec to allow host execution
-`));
-    return { ran: false, taskId: task.id, status: "refused" };
-  }
-  handled?.add(task.id);
-  const claimed = await ctx.api.post(`/api/tasks/${encodeURIComponent(task.id)}/claim`, {});
-  const goal = claimed.goal ?? task.goal ?? "";
-  const intervalMs = heartbeatIntervalMs(claimed.lease_timeout_s ?? DEFAULT_LEASE_S);
-  process.stderr.write(source_default.dim(`
-[runner] claimed ${task.id} — running: ${goal} (heartbeat every ${Math.round(intervalMs / 1000)}s)
-`));
-  let result;
-  let cancelled = false;
-  try {
-    const handle = await startHostCommand(goal, `task-${task.id}`, {
-      cwd: opts.cwd
-    });
-    const done = handle.done.catch((e) => ({
-      stdout: "",
-      stderr: String(e),
-      exit_code: -1
-    }));
-    for (;; ) {
-      const raced = await Promise.race([
-        done,
-        sleepUnref(intervalMs).then(() => null)
-      ]);
-      if (raced !== null) {
-        result = raced;
-        break;
-      }
-      let reply;
-      try {
-        reply = await ctx.api.post(`/api/tasks/${encodeURIComponent(task.id)}/heartbeat`, {});
-      } catch (e) {
-        process.stderr.write(source_default.yellow(`[runner] heartbeat failed for ${task.id} (job unaffected): ${String(e)}
-`));
-        continue;
-      }
-      if (reply && reply.signal === "cancel") {
-        process.stderr.write(source_default.yellow(`[runner] cancel signal for ${task.id} — killing process tree
-`));
-        handle.kill();
-        result = await done;
-        cancelled = true;
-        break;
-      }
-    }
-  } catch (e) {
-    result = { stdout: "", stderr: String(e), exit_code: -1 };
-  }
-  const exit_code = result.exit_code;
-  const stdout = result.stdout || result.stderr || "";
-  const status = cancelled ? "cancelled" : exit_code === 0 ? "completed" : "failed";
-  await ctx.api.post(`/api/tasks/${encodeURIComponent(task.id)}/complete`, {
-    outcome: cancelled ? { stdout, exit_code, cancelled: true } : { stdout, exit_code },
-    status
-  });
-  process.stderr.write(source_default.dim(`[runner] completed ${task.id} — ${status} (exit ${exit_code})
-`));
-  return { ran: true, taskId: task.id, status, exitCode: exit_code };
-}
 function startupEchoLine(who, opts) {
   const identity2 = who ? who.kind === "agent" ? `agent ${who.agent_name ?? "?"} (${(who.agent_id ?? "").slice(0, 8)}…)` : `${who.kind} ${who.sub ?? ""}`.trim() : "identity unknown (whoami unavailable)";
-  const scope = opts.team ? `team:${opts.team}` : "direct";
   const exec = opts.allowHostExec ? "host exec allowed" : "host exec refused (pass --allow-host-exec)";
-  const modePart = opts.mode ? `, mode ${opts.mode}` : "";
-  return `[runner] attached as ${identity2}${modePart}, scope ${scope}, cwd ${opts.cwd}, ${exec}${opts.once ? " — once" : ""}`;
+  return `[runner] attached as ${identity2} — this machine is the agent's hands (host executor; the agent reasons in Martha's cloud loop), cwd ${opts.cwd}, ${exec}`;
+}
+function rejectRemovedTaskModeFlags(opts) {
+  const used = [
+    opts.tasks && "--tasks",
+    opts.channel && "--channel",
+    opts.once && "--once",
+    opts.team && "--team",
+    opts.agent && "--agent",
+    opts.pollInterval && "--poll-interval"
+  ].filter(Boolean);
+  if (used.length === 0)
+    return;
+  throw new CLIError(`${used.join(", ")} ${used.length > 1 ? "were" : "was"} removed: ` + "`martha runner` now means ONE thing — attach this machine as a cloud " + "agent's hands (host executor). It no longer polls or runs tasks. A " + "self-hosted agent is your own program driving the task REST " + "(`martha tasks poll/claim/heartbeat/complete`) and the peer channel.", 4 /* Validation */);
 }
 function shouldFlushAck(pendingAckId, lastAckedId, lastAckAt, now, force, intervalMs) {
   if (!pendingAckId || pendingAckId === lastAckedId)
@@ -17879,7 +17761,7 @@ async function runChannelLoop(ctx, state, abort) {
       if (abort.signal.aborted)
         break;
       if (err instanceof MarthaAPIError && err.status === 404) {
-        process.stderr.write(source_default.dim(`[runner] channel unavailable (server flag off) — task polling continues
+        process.stderr.write(source_default.dim(`[runner] channel unavailable (server CHANNEL_ENABLED off, or old server) — nothing to attach to; exiting
 `));
         return;
       }
@@ -17945,59 +17827,25 @@ async function runChannelLoop(ctx, state, abort) {
   }
 }
 function registerRunnerCommand(program2) {
-  program2.command("runner").description("Attach this machine as an agent's host executor (#822). Two modes: " + "--tools executes host-tool calls pushed over the channel (a Martha-hosted " + "agent's host runner); --tasks claims and runs tasks (a self-hosted agent's " + "executor). Identity comes from the API token.").option("--tools", "Host-runner mode: execute host-tool calls pushed over the per-agent channel. " + "Never polls task queues. Requires --allow-host-exec.").option("--tasks", "Task-executor mode: poll/claim/run tasks assigned to this agent.").option("--agent <id>", "Deprecated: identity comes from the API token; applied as a client-side filter only").option("--team <name>", "Poll this team's queue (name or UUID) instead of direct-only (task mode)").option("--once", "Claim + run a single task, then exit (task mode)").option("--poll-interval <ms>", "Poll interval when idle (ms)", "3000").option("--cwd <dir>", "Scoped workspace for host execution", process.cwd()).option("--allow-host-exec", "Consent to run host commands (required to execute)").option("--yes", "Deprecated alias for --allow-host-exec").option("--channel", "Deprecated alias for --tools alongside task polling (pre-#822 behaviour).").option("--local-agent <name>", "Local coding agent for local_agent delegation over the channel", DEFAULT_LOCAL_AGENT).action(async (opts) => {
+  program2.command("runner").description("Attach this machine as a cloud agent's hands (#714): hold the per-agent " + "channel open and execute host-tool calls the agent's Martha-hosted " + "reasoning loop parks on (chat gates and assigned-task parks). Identity " + "comes from the API token (the agent's runner key). The runner never " + "reasons and never runs tasks — self-hosted agents drive the task REST " + "(`martha tasks poll/claim/complete`) with their own code.").option("--tools", "Accepted no-op: hands mode is the only mode (kept so printed " + "setup-host-runner commands stay valid).").option("--cwd <dir>", "Scoped workspace for host execution", process.cwd()).option("--allow-host-exec", "Consent to run host commands (required to execute)").option("--yes", "Deprecated alias for --allow-host-exec").option("--local-agent <name>", "Local coding agent for local_agent delegation over the channel", DEFAULT_LOCAL_AGENT).option("--tasks", "REMOVED (#714): the runner no longer runs tasks").option("--channel", "REMOVED (#714): deprecated pre-#822 alias").option("--once", "REMOVED (#714): belonged to the task-executor mode").option("--team <name>", "REMOVED (#714): belonged to the task-executor mode").option("--agent <id>", "REMOVED (#714): identity comes from the API token").option("--poll-interval <ms>", "REMOVED (#714): the runner no longer polls").action(async (opts) => {
+    rejectRemovedTaskModeFlags(opts);
     const ctx = createContext({
       profileOverride: program2.opts().profile,
       verbose: program2.opts().verbose,
       apiUrlOverride: program2.opts().apiUrl
     });
-    const pollInterval = parseInt(opts.pollInterval, 10);
-    if (isNaN(pollInterval) || pollInterval < 250) {
-      throw new CLIError("--poll-interval must be >= 250 (ms)", 4 /* Validation */);
-    }
-    if (opts.agent) {
-      process.stderr.write(source_default.yellow(`[runner] --agent is deprecated — identity comes from the API token; the value is applied as a client-side filter only
-`));
-    }
-    const runOpts = {
-      agent: opts.agent,
-      team: opts.team,
-      cwd: opts.cwd,
-      allowHostExec: !!(opts.allowHostExec || opts.yes)
-    };
-    let runTasks;
-    let runChannel;
-    if (opts.tools || opts.tasks) {
-      runTasks = !!opts.tasks;
-      runChannel = !!opts.tools;
-    } else if (opts.channel) {
-      runTasks = true;
-      runChannel = true;
-    } else {
-      runTasks = true;
-      runChannel = false;
-    }
-    const mode = runTasks && runChannel ? "tools+tasks" : runChannel ? "tools" : "tasks";
+    const allowHostExec = !!(opts.allowHostExec || opts.yes);
     let who;
     try {
       who = await ctx.api.get("/api/tasks/whoami");
     } catch {}
-    process.stderr.write(source_default.dim(`${startupEchoLine(who, { team: opts.team, cwd: opts.cwd, allowHostExec: runOpts.allowHostExec, once: !!opts.once, mode })}
+    process.stderr.write(source_default.dim(`${startupEchoLine(who, { cwd: opts.cwd, allowHostExec })}
 `));
-    if (runChannel && !runOpts.allowHostExec) {
-      throw new CLIError("--tools executes host-tool calls; re-run with --allow-host-exec to consent", 4 /* Validation */);
+    if (!allowHostExec) {
+      throw new CLIError("the runner executes host-tool calls; re-run with --allow-host-exec to consent", 4 /* Validation */);
     }
-    if (opts.once) {
-      if (!runTasks) {
-        throw new CLIError("--once runs a single TASK; it has no meaning in --tools (host-runner) mode", 4 /* Validation */);
-      }
-      await runOnce(ctx, runOpts);
-      return;
-    }
-    let stop = false;
     const abort = new AbortController;
     const onSignal = () => {
-      stop = true;
       abort.abort();
       process.stderr.write(`
 [runner] stopping…
@@ -18005,34 +17853,13 @@ function registerRunnerCommand(program2) {
     };
     process.on("SIGINT", onSignal);
     process.on("SIGTERM", onSignal);
-    const pollLoop = async () => {
-      const handled = new Set;
-      while (!stop) {
-        let r;
-        try {
-          r = await runOnce(ctx, runOpts, handled);
-        } catch (e) {
-          process.stderr.write(source_default.red(`[runner] error: ${String(e)}
-`));
-          r = { ran: false };
-        }
-        if (!r.ran)
-          await sleep5(pollInterval);
-      }
-    };
-    const loops = [];
-    if (runTasks)
-      loops.push(pollLoop());
-    if (runChannel) {
-      const state = createLocalExecState({
-        cwd: opts.cwd,
-        autoYes: runOpts.allowHostExec,
-        localAgent: opts.localAgent ?? DEFAULT_LOCAL_AGENT
-      });
-      loops.push(runChannelLoop(ctx, state, abort));
-    }
+    const state = createLocalExecState({
+      cwd: opts.cwd,
+      autoYes: allowHostExec,
+      localAgent: opts.localAgent ?? DEFAULT_LOCAL_AGENT
+    });
     try {
-      await Promise.all(loops);
+      await runChannelLoop(ctx, state, abort);
     } finally {
       process.off("SIGINT", onSignal);
       process.off("SIGTERM", onSignal);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/martha-cli",
-  "version": "0.45.0",
+  "version": "0.48.0",
   "description": "Terminal-first client for the Martha AI platform",
   "homepage": "https://docs.martha.nomadriver.co",
   "repository": {