@aiaiai-pt/martha-cli 0.26.0 → 0.27.1

package/dist/index.js

@@ -11081,7 +11081,7 @@ init_config();
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.26.0";
+var CLI_VERSION = "0.27.1";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -11358,6 +11358,9 @@ import { spawn } from "node:child_process";
 import { randomBytes as randomBytes2 } from "node:crypto";
 import { closeSync, openSync, promises as fs5 } from "node:fs";
 import * as path4 from "node:path";
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
 var DEFAULT_TIMEOUT_MS = 20000;
 var MAX_OUTPUT = 256 * 1024;
 function runnerDir(cwd) {
@@ -11452,16 +11455,87 @@ class Journal {
     try {
       const raw = JSON.parse(await fs5.readFile(this.file(), "utf8"));
       if (raw["entries"] !== undefined) {
-        return raw;
+        const f = raw;
+        if (!f.secrets)
+          f.secrets = {};
+        if (!f.jobs)
+          f.jobs = {};
+        return f;
       }
-      return { entries: raw, secrets: {} };
+      return {
+        entries: raw,
+        secrets: {},
+        jobs: {}
+      };
     } catch {
-      return { entries: {}, secrets: {} };
+      return { entries: {}, secrets: {}, jobs: {} };
     }
   }
   async save(data) {
     await fs5.mkdir(runnerDir(this.cwd), { recursive: true });
-    await fs5.writeFile(this.file(), JSON.stringify(data, null, 2));
+    const tmp = `${this.file()}.${randomBytes2(6).toString("hex")}.tmp`;
+    await fs5.writeFile(tmp, JSON.stringify(data, null, 2));
+    await fs5.rename(tmp, this.file());
+  }
+  chain = Promise.resolve();
+  async acquireFileLock() {
+    const lockPath = path4.join(runnerDir(this.cwd), "journal.lock");
+    await fs5.mkdir(runnerDir(this.cwd), { recursive: true });
+    const deadline = Date.now() + 5000;
+    for (;; ) {
+      try {
+        const fh = await fs5.open(lockPath, "wx");
+        await fh.write(String(process.pid));
+        await fh.close();
+        return async () => {
+          await fs5.rm(lockPath, { force: true });
+        };
+      } catch (e) {
+        if (e.code !== "EEXIST")
+          throw e;
+        try {
+          const st = await fs5.stat(lockPath);
+          if (Date.now() - st.mtimeMs > 1e4) {
+            await fs5.rm(lockPath, { force: true });
+            continue;
+          }
+        } catch {
+          continue;
+        }
+        if (Date.now() > deadline) {
+          return async () => {};
+        }
+        await sleep(15 + Math.floor(Math.random() * 25));
+      }
+    }
+  }
+  async transact(fn) {
+    const run = async () => {
+      const release = await this.acquireFileLock();
+      try {
+        const data = await this.load();
+        const out = await fn(data);
+        await this.save(data);
+        return out;
+      } finally {
+        await release();
+      }
+    };
+    const result = this.chain.then(run, run);
+    this.chain = result.then(() => {
+      return;
+    }, () => {
+      return;
+    });
+    return result;
+  }
+  async recordJob(job) {
+    await this.transact((data) => {
+      data.jobs[job.job_id] = job;
+    });
+  }
+  async lookupJob(jobId) {
+    return this.transact((data) => data.jobs[jobId]);
   }
   static key(sessionId, toolCallId) {
     return `${sessionId}:${toolCallId}`;
@@ -11521,7 +11595,12 @@ function parseHostExecRequests(data) {
       continue;
     if (!t.tool_call_id)
       continue;
-    out.push({ toolCallId: t.tool_call_id, command: t.args?.command ?? "" });
+    out.push({
+      toolCallId: t.tool_call_id,
+      command: t.args?.command ?? "",
+      background: t.args?.background === true,
+      cwd: typeof t.args?.cwd === "string" ? t.args.cwd : undefined
+    });
   }
   return out;
 }
@@ -11917,12 +11996,247 @@ function parseLocalAgentRequests(data) {
     out.push({
       toolCallId: t.tool_call_id,
       task: t.args.task,
-      cwd: typeof t.args.cwd === "string" ? t.args.cwd : undefined
+      cwd: typeof t.args.cwd === "string" ? t.args.cwd : undefined,
+      background: t.args.background === true
     });
   }
   return out;
 }
 
+// src/lib/local-jobs.ts
+import { execFileSync, spawn as spawn2 } from "node:child_process";
+import { randomBytes as randomBytes3 } from "node:crypto";
+import { closeSync as closeSync2, openSync as openSync2, readFileSync, promises as fs7 } from "node:fs";
+import * as path6 from "node:path";
+var POLL_CAP = 64 * 1024;
+function mintJobId() {
+  return `job_${randomBytes3(6).toString("hex")}`;
+}
+var SENTINEL_TAIL = `
+__martha_ec=$?
+printf '%s' "$__martha_ec" > "$MARTHA_JOB_SENTINEL.tmp" 2>/dev/null
+mv -f "$MARTHA_JOB_SENTINEL.tmp" "$MARTHA_JOB_SENTINEL" 2>/dev/null
+exit $__martha_ec`;
+function runnerDir2(cwd) {
+  return path6.join(cwd, ".martha-runner");
+}
+function getProcessStartTime(pid) {
+  try {
+    if (process.platform === "linux") {
+      const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+      const tail = stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/);
+      return tail[19] ?? null;
+    }
+    const out = execFileSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+      encoding: "utf8"
+    }).trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+function isProcessAlive(pid) {
+  if (pid <= 0)
+    return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === "EPERM";
+  }
+}
+async function readSentinel(p) {
+  try {
+    const raw = (await fs7.readFile(p, "utf8")).trim();
+    if (raw === "")
+      return { present: true };
+    const n = parseInt(raw, 10);
+    return { present: true, code: Number.isNaN(n) ? undefined : n };
+  } catch {
+    return { present: false };
+  }
+}
+async function readLogOrNull(p) {
+  try {
+    return await fs7.readFile(p);
+  } catch {
+    return null;
+  }
+}
+async function writeSentinelAtomic(p, content) {
+  const tmp = `${p}.${randomBytes3(4).toString("hex")}.tmp`;
+  await fs7.writeFile(tmp, content);
+  await fs7.rename(tmp, p);
+}
+async function dispatchBackgroundJob(command, jobId, journal, opts) {
+  if (process.platform === "win32") {
+    throw new Error("background jobs are not supported on Windows (POSIX-only: /bin/sh + " + "process groups). Run this command in the foreground instead.");
+  }
+  const dir = runnerDir2(opts.cwd);
+  await fs7.mkdir(dir, { recursive: true });
+  const logPath = path6.join(dir, `${jobId}.log`);
+  const sentinelPath = path6.join(dir, `${jobId}.exit`);
+  await fs7.writeFile(logPath, "");
+  const fd = openSync2(logPath, "a");
+  const env2 = { ...process.env, MARTHA_JOB_SENTINEL: sentinelPath };
+  const stdin = opts.stdinData != null ? "pipe" : "ignore";
+  const child = opts.argv ? spawn2("/bin/sh", ["-c", `"$@"${SENTINEL_TAIL}`, "martha-job", ...opts.argv], {
+    shell: false,
+    cwd: opts.cwd,
+    detached: true,
+    env: env2,
+    stdio: [stdin, fd, fd]
+  }) : spawn2("/bin/sh", ["-c", `( ${command} )${SENTINEL_TAIL}`], {
+    shell: false,
+    cwd: opts.cwd,
+    detached: true,
+    env: env2,
+    stdio: [stdin, fd, fd]
+  });
+  closeSync2(fd);
+  if (opts.stdinData != null && child.stdin) {
+    child.stdin.on("error", () => {});
+    child.stdin.write(opts.stdinData);
+    child.stdin.end();
+  }
+  const pid = child.pid ?? -1;
+  const start_time = pid > 0 ? getProcessStartTime(pid) : null;
+  child.unref();
+  const record = {
+    job_id: jobId,
+    command,
+    pid,
+    start_time,
+    started_at: new Date().toISOString(),
+    log_path: logPath,
+    sentinel_path: sentinelPath,
+    offset: 0,
+    status: "running"
+  };
+  await journal.recordJob(record);
+  return { job_id: jobId, status: "running", log_path: logPath, pid };
+}
+function startTimeMatches(job) {
+  if (!job.start_time)
+    return true;
+  const live = getProcessStartTime(job.pid);
+  if (live == null)
+    return true;
+  return live === job.start_time;
+}
+async function classifyAndRead(job) {
+  const sentinel = await readSentinel(job.sentinel_path);
+  const logBuf = await readLogOrNull(job.log_path);
+  let status;
+  let done;
+  let exit_code;
+  if (sentinel.present) {
+    done = true;
+    exit_code = sentinel.code;
+    status = job.status === "killed" ? "killed" : "done";
+    job.status = status;
+  } else if (isProcessAlive(job.pid) && startTimeMatches(job)) {
+    status = "running";
+    done = false;
+  } else if (logBuf == null) {
+    status = "expired";
+    done = true;
+  } else {
+    status = "crashed";
+    done = true;
+    job.status = "crashed";
+  }
+  let new_output = "";
+  let bytes_remaining = 0;
+  if (logBuf != null) {
+    const slice = logBuf.subarray(job.offset, job.offset + POLL_CAP);
+    new_output = slice.toString("utf8");
+    job.offset += slice.length;
+    bytes_remaining = Math.max(0, logBuf.length - job.offset);
+  }
+  return {
+    job_id: job.job_id,
+    status,
+    exit_code,
+    new_output,
+    done,
+    bytes_remaining
+  };
+}
+async function pollJob(journal, jobId) {
+  return journal.transact(async (data) => {
+    const job = data.jobs[jobId];
+    if (!job) {
+      return {
+        job_id: jobId,
+        status: "unknown",
+        new_output: "",
+        done: true,
+        bytes_remaining: 0,
+        message: `No background job with id ${jobId} is known on this machine.`
+      };
+    }
+    return classifyAndRead(job);
+  });
+}
+async function killJob(journal, jobId) {
+  return journal.transact(async (data) => {
+    const job = data.jobs[jobId];
+    if (!job) {
+      return {
+        job_id: jobId,
+        status: "unknown",
+        new_output: "",
+        done: true,
+        bytes_remaining: 0,
+        message: `No background job with id ${jobId} is known on this machine.`
+      };
+    }
+    const sentinel = await readSentinel(job.sentinel_path);
+    if (!sentinel.present) {
+      for (const sig of ["SIGTERM", "SIGKILL"]) {
+        try {
+          if (job.pid > 0)
+            process.kill(-job.pid, sig);
+        } catch {}
+      }
+      job.status = "killed";
+      await writeSentinelAtomic(job.sentinel_path, "137");
+    }
+    const result = await classifyAndRead(job);
+    if (result.status === "done" && job.status === "killed") {
+      result.status = "killed";
+    }
+    result.message = "Background job stopped.";
+    return result;
+  });
+}
+function parseHostOutputRequests(data) {
+  return parseJobToolRequests(data, "host_output");
+}
+function parseHostKillRequests(data) {
+  return parseJobToolRequests(data, "host_kill");
+}
+function parseJobToolRequests(data, toolName) {
+  let tools;
+  try {
+    tools = JSON.parse(data);
+  } catch {
+    return [];
+  }
+  if (!Array.isArray(tools))
+    return [];
+  const out = [];
+  for (const t of tools) {
+    if (t.tool_name !== toolName || t.status !== "awaiting_input")
+      continue;
+    if (!t.tool_call_id || !t.args?.job_id)
+      continue;
+    out.push({ toolCallId: t.tool_call_id, jobId: t.args.job_id });
+  }
+  return out;
+}
+
 // src/commands/chat.ts
 async function uploadImageArtifact(ctx, sessionId, png) {
   try {
@@ -11941,7 +12255,8 @@ async function uploadImageArtifact(ctx, sessionId, png) {
     return { error: `image upload failed: ${String(e)}` };
   }
 }
-async function resolveHostExec(sessionId, toolCallId, command, state) {
+async function resolveHostExec(sessionId, toolCallId, req, state) {
+  const command = req.command;
   const decision = decideFromJournal(await state.journal.lookup(sessionId, toolCallId));
   if (decision.kind === "replay")
     return decision.result;
@@ -11962,20 +12277,65 @@ async function resolveHostExec(sessionId, toolCallId, command, state) {
       message: "Host execution declined; re-run with --yes to allow."
     };
   }
+  const cwd = req.cwd ? `${state.cwd}/${req.cwd}` : state.cwd;
+  if (req.background) {
+    const jobId = mintJobId();
+    process.stderr.write(source_default.dim(`
+[host_exec:bg] $ ${command}
+  (job ${jobId}, cwd: ${cwd})
+`));
+    try {
+      const handle = await dispatchBackgroundJob(command, jobId, state.journal, {
+        cwd
+      });
+      return {
+        job_id: handle.job_id,
+        status: "running",
+        pid: handle.pid,
+        log_path: handle.log_path,
+        message: `Dispatched in the background as ${handle.job_id}. Poll host_output(` + `{job_id:"${handle.job_id}"}) for new output + status; host_kill to stop it.`
+      };
+    } catch (e) {
+      return {
+        error: true,
+        message: `failed to dispatch background job: ${String(e)}`
+      };
+    }
+  }
   process.stderr.write(source_default.dim(`
 [host_exec] $ ${command}
-  (cwd: ${state.cwd})
+  (cwd: ${cwd})
 `));
   await state.journal.recordRunning(sessionId, toolCallId, command, new Date().toISOString());
   let result;
   try {
-    result = await runHostCommand(command, toolCallId, { cwd: state.cwd });
+    result = await runHostCommand(command, toolCallId, { cwd });
   } catch (e) {
     result = { stdout: "", stderr: String(e), exit_code: -1 };
   }
   await state.journal.recordDone(sessionId, toolCallId, result);
   return result;
 }
+async function resolveHostOutput(req, state) {
+  process.stderr.write(source_default.dim(`
+[host_output] ${req.jobId}
+`));
+  try {
+    return await pollJob(state.journal, req.jobId);
+  } catch (e) {
+    return { error: true, message: `host_output failed: ${String(e)}` };
+  }
+}
+async function resolveHostKill(req, state) {
+  process.stderr.write(source_default.dim(`
+[host_kill] ${req.jobId}
+`));
+  try {
+    return await killJob(state.journal, req.jobId);
+  } catch (e) {
+    return { error: true, message: `host_kill failed: ${String(e)}` };
+  }
+}
 async function resolveHostScreenshot(ctx, sessionId, req, state) {
   if (!state.autoYes) {
     process.stderr.write(source_default.yellow(`
@@ -12082,6 +12442,27 @@ async function resolveLocalAgent(sessionId, toolCallId, req, state) {
   }
   const cwd = req.cwd ? `${state.cwd}/${req.cwd}` : state.cwd;
   const { bin, args, stdin } = buildSpawn(invocation, req.task);
+  if (req.background) {
+    const jobId = mintJobId();
+    process.stderr.write(source_default.dim(`
+[local_agent:bg] (${invocation.source}) ${req.task.slice(0, 80)} (job ${jobId})
+`));
+    try {
+      const handle = await dispatchBackgroundJob(`local_agent:${invocation.source}`, jobId, state.journal, { cwd, argv: [bin, ...args], stdinData: stdin ?? undefined });
+      return {
+        job_id: handle.job_id,
+        status: "running",
+        pid: handle.pid,
+        log_path: handle.log_path,
+        message: `Delegated to ${invocation.source} in the background as ${handle.job_id}. ` + `Poll host_output({job_id:"${handle.job_id}"}) for its progress + final ` + `result; host_kill to stop it.`
+      };
+    } catch (e) {
+      return {
+        error: true,
+        message: `local agent failed to start (${invocation.source}): ${String(e)}. ` + `Pick an installed agent with --local-agent <claude|codex|cursor-agent>.`
+      };
+    }
+  }
   process.stderr.write(source_default.dim(`
 [local_agent] (${invocation.source}) ${req.task.slice(0, 100)}
 `));
@@ -12157,9 +12538,27 @@ async function handleHostExecFrame(ctx, sessionId, data, state) {
       continue;
     state.handled.add(id);
     await claimGate(ctx, sessionId, id, state);
-    const result = await resolveHostExec(sessionId, id, req.command, state);
+    const result = await resolveHostExec(sessionId, id, req, state);
     await _postToolResult(ctx, sessionId, id, result, "host_exec", state.secrets.get(id));
   }
+  for (const req of parseHostOutputRequests(data)) {
+    const id = req.toolCallId;
+    if (state.handled.has(id))
+      continue;
+    state.handled.add(id);
+    await claimGate(ctx, sessionId, id, state);
+    const result = await resolveHostOutput(req, state);
+    await _postToolResult(ctx, sessionId, id, result, "host_output", state.secrets.get(id));
+  }
+  for (const req of parseHostKillRequests(data)) {
+    const id = req.toolCallId;
+    if (state.handled.has(id))
+      continue;
+    state.handled.add(id);
+    await claimGate(ctx, sessionId, id, state);
+    const result = await resolveHostKill(req, state);
+    await _postToolResult(ctx, sessionId, id, result, "host_kill", state.secrets.get(id));
+  }
   for (const req of parseHostScreenshotRequests(data)) {
     const id = req.toolCallId;
     if (state.handled.has(id))
@@ -13166,8 +13565,8 @@ function registerConfigCommand(program2) {
 }
 
 // src/commands/definitions-apply.ts
-import fs7 from "node:fs";
-import path6 from "node:path";
+import fs8 from "node:fs";
+import path7 from "node:path";
 init_dist();
 init_errors();
 var VALID_KINDS = new Set([
@@ -13209,20 +13608,20 @@ var SERVER_GENERATED_FIELDS = new Set([
 ]);
 var AGENT_MANAGED_FIELDS = new Set(["functions", "workflows"]);
 function loadDefinitions(inputPath) {
-  const resolved = path6.resolve(inputPath);
-  if (!fs7.existsSync(resolved)) {
+  const resolved = path7.resolve(inputPath);
+  if (!fs8.existsSync(resolved)) {
     throw new CLIError(`Path not found: ${inputPath}`, 1 /* Error */);
   }
-  const stat = fs7.statSync(resolved);
+  const stat = fs8.statSync(resolved);
   if (stat.isDirectory()) {
     return loadDirectory(resolved);
   }
   return loadFile(resolved);
 }
 function loadDirectory(dirPath) {
-  const entries = fs7.readdirSync(dirPath).sort();
+  const entries = fs8.readdirSync(dirPath).sort();
   const validExts = new Set([".yaml", ".yml", ".json"]);
-  const files = entries.filter((e) => validExts.has(path6.extname(e).toLowerCase())).map((e) => path6.join(dirPath, e));
+  const files = entries.filter((e) => validExts.has(path7.extname(e).toLowerCase())).map((e) => path7.join(dirPath, e));
   if (files.length === 0) {
     throw new CLIError(`No YAML or JSON files found in ${dirPath}`, 4 /* Validation */);
   }
@@ -13233,8 +13632,8 @@ function loadDirectory(dirPath) {
   return results;
 }
 function loadFile(filePath) {
-  const content = fs7.readFileSync(filePath, "utf-8");
-  const ext = path6.extname(filePath).toLowerCase();
+  const content = fs8.readFileSync(filePath, "utf-8");
+  const ext = path7.extname(filePath).toLowerCase();
   if (ext === ".json") {
     const parsed = parseJsonFile(content, filePath);
     return [toLocalDefinition(parsed, filePath)];
@@ -13656,7 +14055,7 @@ Examples:
 }
 
 // src/commands/definitions-export.ts
-import fs8 from "node:fs";
+import fs9 from "node:fs";
 init_errors();
 async function exportDefinitions(ctx, opts, isJsonMode) {
   const params = {};
@@ -13672,7 +14071,7 @@ async function exportDefinitions(ctx, opts, isJsonMode) {
   const text = await res.text();
   if (opts.output) {
     try {
-      fs8.writeFileSync(opts.output, text);
+      fs9.writeFileSync(opts.output, text);
     } catch (err) {
       throw new CLIError(`Failed to write ${opts.output}: ${err instanceof Error ? err.message : String(err)}`, 1 /* Error */);
     }
@@ -13980,7 +14379,7 @@ function colorStatus(status) {
   const fn = STATUS_COLORS[status] ?? source_default.white;
   return fn(status);
 }
-function sleep(ms) {
+function sleep2(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 async function pollUntilDone(ctx, executionId, intervalMs = 2000, timeoutMs = 300000) {
@@ -13990,7 +14389,7 @@ async function pollUntilDone(ctx, executionId, intervalMs = 2000, timeoutMs = 30
     if (TERMINAL_STATUSES.has(status.status)) {
       return status;
     }
-    await sleep(intervalMs);
+    await sleep2(intervalMs);
   }
   throw new CLIError(`Timed out waiting for execution ${executionId}`, 1 /* Error */);
 }
@@ -14061,7 +14460,7 @@ Detached. Reattach with: martha workflows execution ${executionId} --follow`));
         }
         return;
       }
-      await sleep(1000);
+      await sleep2(1000);
       current = await ctx.api.get(`/api/admin/executions/${encodeURIComponent(executionId)}`);
     }
   } finally {
@@ -14392,8 +14791,8 @@ function registerProjectionCommands(parentCmd, getCtx, isJson) {
       } catch {}
     }
     if (opts.output) {
-      const fs9 = await import("node:fs/promises");
-      await fs9.writeFile(opts.output, toWrite, "utf-8");
+      const fs10 = await import("node:fs/promises");
+      await fs10.writeFile(opts.output, toWrite, "utf-8");
       if (!isJson()) {
         console.error(source_default.dim(`Wrote ${format} projection of '${name}' to ${opts.output}`));
       }
@@ -14800,8 +15199,8 @@ Usage:
     });
     parentCmd.command("self-grant <agent>").description("View or configure an agent's self-provisioning policy (request-then-approve). " + "With no flags, prints the current policy.").option("--enable", "Allow the agent to REQUEST capability grants").option("--disable", "Disallow self-provisioning").option("--scope <scope>", "Scope ceiling: none | read_only | read_write").option("--allow <ref...>", "Add allow-list refs (function:NAME or mcp:integration/name)").option("--remove <ref...>", "Remove allow-list refs").option("--collection-root <id...>", "Add collection-subtree roots the agent may self-grant collection-scoped functions into").option("--remove-collection-root <id...>", "Remove collection roots").option("--max-pending <n>", "Max concurrently-pending requests").action(async (agent, opts) => {
       const ctx = getCtx();
-      const path7 = `${API_PATH}/${encodeURIComponent(agent)}`;
-      const current = await ctx.api.get(path7);
+      const path8 = `${API_PATH}/${encodeURIComponent(agent)}`;
+      const current = await ctx.api.get(path8);
       const mutating = opts.enable || opts.disable || opts.scope !== undefined || (opts.allow?.length ?? 0) > 0 || (opts.remove?.length ?? 0) > 0 || (opts.collectionRoot?.length ?? 0) > 0 || (opts.removeCollectionRoot?.length ?? 0) > 0 || opts.maxPending !== undefined;
       if (!mutating) {
         if (isJson()) {
@@ -14853,7 +15252,7 @@ Usage:
           roots.delete(c);
         body.self_grant_collection_roots = [...roots];
       }
-      const updated = await ctx.api.put(path7, body);
+      const updated = await ctx.api.put(path8, body);
       if (isJson()) {
         console.log(JSON.stringify(policyView(updated), null, 2));
         return;
@@ -15100,7 +15499,7 @@ var triggersConfig = {
 };
 
 // src/commands/documents.ts
-import fs9 from "node:fs";
+import fs10 from "node:fs";
 init_errors();
 var TERMINAL_STATUSES2 = new Set(["ready", "error"]);
 var SPINNER_FRAMES2 = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
@@ -15110,7 +15509,7 @@ function nextSpinner() {
   spinnerIdx++;
   return frame;
 }
-function sleep2(ms) {
+function sleep3(ms) {
   return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 function formatBytes(bytes) {
@@ -15170,7 +15569,7 @@ async function pollIngestionUntilDone(ctx, documentId, intervalMs = 2000, timeou
     if (TERMINAL_STATUSES2.has(status.ingestion_status)) {
       return status;
     }
-    await sleep2(intervalMs);
+    await sleep3(intervalMs);
   }
   throw new CLIError(`Timed out waiting for ingestion of document ${documentId}`, 1 /* Error */);
 }
@@ -15245,7 +15644,7 @@ Detached. Check status with: martha documents status ${documentId}`));
         }
         return;
       }
-      await sleep2(1000);
+      await sleep3(1000);
     }
   } finally {
     process.removeListener("SIGINT", sigintHandler);
@@ -15461,7 +15860,7 @@ ${items.length} collections`));
   });
   cmd.command("upload <collection-id> <file>").description("Upload a document to a collection").option("--wait", "Wait for ingestion to complete").option("--follow", "Follow ingestion progress in real time").action(async (collectionId, filePath, opts) => {
     const ctx = getCtx();
-    if (!fs9.existsSync(filePath)) {
+    if (!fs10.existsSync(filePath)) {
       throw new CLIError(`File not found: ${filePath}`, 4 /* Validation */);
     }
     const result = await ctx.api.upload(`/api/admin/collections/${encodeURIComponent(collectionId)}/documents`, filePath);
@@ -16090,10 +16489,10 @@ function registerApprovalCommands(program2) {
 }
 
 // src/commands/tasks.ts
-import { readFileSync } from "node:fs";
+import { readFileSync as readFileSync2 } from "node:fs";
 init_errors();
 var truncate2 = (s, n) => s.length > n ? s.slice(0, n - 1) + "…" : s;
-var sleep3 = (ms, signal) => new Promise((resolve2) => {
+var sleep4 = (ms, signal) => new Promise((resolve2) => {
   if (signal?.aborted) {
     resolve2();
     return;
@@ -16231,7 +16630,7 @@ ${items.length} task(s)`));
     }
     console.log(`Open: ${source_default.yellow(data.open ?? 0)}  ` + `Running: ${source_default.blue(data.running ?? 0)}  ` + `Claimed: ${source_default.magenta(data.claimed ?? 0)}  ` + `Completed: ${source_default.green(data.completed ?? 0)}  ` + `Failed: ${source_default.red(data.failed ?? 0)}  ` + `Cancelled: ${source_default.dim(data.cancelled ?? 0)}`);
   });
-  cmd.command("create").description("Create a new task").requiredOption("--agent <name-or-id>", "Agent definition ID").requiredOption("--goal <text>", "Goal / instruction for the agent").option("--title <text>", "Short title for the task").option("--priority <priority>", "Priority (low, medium, high, urgent)", "medium").option("--context <json>", "Structured context as JSON string").option("--team <team-id>", "Assign task to a team").option("--assigned-agent <agent-id>", "Assign task to a specific agent").option("--sticky", "Keep assignment even if agent goes offline").action(async (opts) => {
+  cmd.command("create").description("Create a new task").requiredOption("--agent <name-or-id>", "Agent definition ID").requiredOption("--goal <text>", "Goal / instruction for the agent").option("--title <text>", "Short title for the task").option("--priority <priority>", "Priority (low, medium, high, urgent)", "medium").option("--context <json>", "Structured context as JSON string").option("--team <team-id>", "Assign task to a team").option("--assigned-agent <agent-id>", "Assign task to a specific agent").option("--sticky", "Keep assignment even if agent goes offline").option("--no-auto-execute", "Create the task as claimable (open) for an external runner to pull, instead of auto-running it via the cloud workflow").action(async (opts) => {
     const ctx = getCtx();
     const body = {
       agent_definition_id: opts.agent,
@@ -16253,6 +16652,8 @@ ${items.length} task(s)`));
       body.assigned_agent_id = opts.assignedAgent;
     if (opts.sticky)
       body.sticky_assignment = true;
+    if (opts.autoExecute === false)
+      body.auto_execute = false;
     const result = await ctx.api.post("/api/admin/tasks", body);
     if (isJson()) {
       console.log(JSON.stringify(result, null, 2));
@@ -16459,7 +16860,7 @@ ${items.length} task(s) available`));
           if (reconnects > maxReconnects) {
             throw new CLIError(`Exceeded --max-reconnects (${maxReconnects})`, 1 /* Error */);
           }
-          await sleep3(backoffMs, abort.signal);
+          await sleep4(backoffMs, abort.signal);
           backoffMs = Math.min(backoffMs * 2, maxBackoff);
           continue;
         }
@@ -16523,7 +16924,7 @@ ${items.length} task(s) available`));
         if (reconnects > maxReconnects) {
           throw new CLIError(`Exceeded --max-reconnects (${maxReconnects})`, 1 /* Error */);
         }
-        await sleep3(backoffMs, abort.signal);
+        await sleep4(backoffMs, abort.signal);
         backoffMs = Math.min(backoffMs * 2, maxBackoff);
       }
     } finally {
@@ -16536,7 +16937,7 @@ ${items.length} task(s) available`));
     let rawOutcome;
     if (opts.outcomeFile) {
       try {
-        rawOutcome = readFileSync(opts.outcomeFile, "utf-8");
+        rawOutcome = readFileSync2(opts.outcomeFile, "utf-8");
       } catch {
         throw new CLIError(`--outcome-file could not be read: ${opts.outcomeFile}`, 4 /* Validation */);
       }
@@ -16562,6 +16963,101 @@ ${items.length} task(s) available`));
   });
 }
 
+// src/commands/runner.ts
+init_errors();
+function sleep5(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+async function runOnce(ctx, opts, handled) {
+  const tasks = await ctx.api.get("/api/tasks/poll", {
+    params: { agent_id: opts.agent, limit: String(opts.pollLimit ?? 5) }
+  });
+  const candidates = Array.isArray(tasks) ? tasks : [];
+  const task = candidates.find((t) => (t.status ?? "open") === "open" && !handled?.has(t.id));
+  if (!task)
+    return { ran: false };
+  if (!opts.autoYes) {
+    process.stderr.write(source_default.yellow(`
+[runner] refused task ${task.id} — re-run with --yes 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 ?? "";
+  process.stderr.write(source_default.dim(`
+[runner] claimed ${task.id} — running: ${goal}
+`));
+  let result;
+  try {
+    result = await runHostCommand(goal, `task-${task.id}`, { cwd: opts.cwd });
+  } catch (e) {
+    result = { stdout: "", stderr: String(e), exit_code: -1 };
+  }
+  const exit_code = result.exit_code;
+  const stdout = result.stdout || result.stderr || "";
+  const status = exit_code === 0 ? "completed" : "failed";
+  await ctx.api.post(`/api/tasks/${encodeURIComponent(task.id)}/complete`, {
+    outcome: { 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 registerRunnerCommand(program2) {
+  program2.command("runner").description("Run as an external agent's executor: claim tasks and run them on this host.").requiredOption("--agent <id>", "Agent definition id this runner serves").option("--once", "Claim + run a single task, then exit").option("--poll-interval <ms>", "Poll interval when idle (ms)", "3000").option("--cwd <dir>", "Scoped workspace for task execution", process.cwd()).option("--yes", "Consent to run host commands (required to execute)").action(async (opts) => {
+    const ctx = createContext({
+      profileOverride: program2.opts().profile,
+      verbose: program2.opts().verbose
+    });
+    if (program2.opts().apiUrl)
+      ctx.profile.api_url = 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 */);
+    }
+    const runOpts = {
+      agent: opts.agent,
+      cwd: opts.cwd,
+      autoYes: !!opts.yes
+    };
+    process.stderr.write(source_default.dim(`[runner] serving agent ${opts.agent} (cwd ${opts.cwd})${opts.once ? " — once" : ""}
+`));
+    if (opts.once) {
+      await runOnce(ctx, runOpts);
+      return;
+    }
+    let stop = false;
+    const onSignal = () => {
+      stop = true;
+      process.stderr.write(`
+[runner] stopping…
+`);
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    const handled = new Set;
+    try {
+      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);
+      }
+    } finally {
+      process.off("SIGINT", onSignal);
+      process.off("SIGTERM", onSignal);
+    }
+  });
+}
+
 // src/commands/teams.ts
 init_errors();
 var API_PATH3 = "/api/admin/teams";
@@ -17038,8 +17534,8 @@ ${data.length} spec(s)`));
 Resources:
 `));
       for (const r of resources) {
-        const path7 = r.path || `/${r.name}`;
-        console.log(`  ${source_default.cyan(r.label || r.name)}` + source_default.dim(` → ${path7}`));
+        const path8 = r.path || `/${r.name}`;
+        console.log(`  ${source_default.cyan(r.label || r.name)}` + source_default.dim(` → ${path8}`));
       }
     }
     try {
@@ -17059,14 +17555,14 @@ Functions:
     console.log(source_default.dim(`
 Proxy: martha integrations proxy ${name} GET /<path>`));
   });
-  cmd.command("proxy <name> <method> <path>").description("Send a request through the plugin proxy").option("--data <json>", "JSON request body").option("--query <params>", "Query params as key=val&key=val").action(async (name, method, path7, opts) => {
+  cmd.command("proxy <name> <method> <path>").description("Send a request through the plugin proxy").option("--data <json>", "JSON request body").option("--query <params>", "Query params as key=val&key=val").action(async (name, method, path8, opts) => {
     const ctx = getCtx();
     const upperMethod = method.toUpperCase();
     const allowed = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
     if (!allowed.has(upperMethod)) {
       throw new CLIError(`Invalid method: ${method}`, 4 /* Validation */, "Allowed: GET, POST, PUT, PATCH, DELETE");
     }
-    const cleanPath = path7.startsWith("/") ? path7.slice(1) : path7;
+    const cleanPath = path8.startsWith("/") ? path8.slice(1) : path8;
     const proxyUrl = `/api/admin/plugins/${encodeURIComponent(name)}/${cleanPath}`;
     const params = {};
     if (opts.query) {
@@ -17276,8 +17772,8 @@ async function resolveCredentialValue(value) {
   if (value === "-")
     return readStdin();
   if (value.startsWith("@")) {
-    const fs10 = await import("node:fs/promises");
-    return (await fs10.readFile(value.slice(1), "utf-8")).trim();
+    const fs11 = await import("node:fs/promises");
+    return (await fs11.readFile(value.slice(1), "utf-8")).trim();
   }
   return value;
 }
@@ -17392,8 +17888,8 @@ Notification connections`));
     if (credentialValue === "-") {
       credentialValue = await readStdin2();
     } else if (credentialValue?.startsWith("@")) {
-      const fs10 = await import("node:fs/promises");
-      credentialValue = await fs10.readFile(credentialValue.slice(1), "utf-8");
+      const fs11 = await import("node:fs/promises");
+      credentialValue = await fs11.readFile(credentialValue.slice(1), "utf-8");
     }
     if (!credentialValue) {
       throw new Error("--credential-value is required (use '-' for stdin or '@path' for file).");
@@ -17443,11 +17939,11 @@ async function readStdin2() {
 
 // src/commands/messaging.ts
 init_errors();
-async function messagingFetch(baseUrl, path7, opts) {
-  if (/^(https?:)?\/\//i.test(path7)) {
+async function messagingFetch(baseUrl, path8, opts) {
+  if (/^(https?:)?\/\//i.test(path8)) {
     throw new CLIError("Absolute URL paths are not allowed", 1 /* Error */);
   }
-  const url = new URL(path7, baseUrl);
+  const url = new URL(path8, baseUrl);
   const headers = {
     "Content-Type": "application/json"
   };
@@ -18727,7 +19223,7 @@ ${models.length} models`));
 }
 
 // src/commands/wiki.ts
-import fs10 from "node:fs";
+import fs11 from "node:fs";
 init_errors();
 function registerWikiCommands(program2) {
   const cmd = program2.command("wiki").description("Manage tenant wiki pages, settings, schema, recompile (#245 D5.4)");
@@ -18774,14 +19270,14 @@ function registerWikiCommands(program2) {
     console.log(source_default.dim(`
 ${pages.length} pages`));
   });
-  cmd.command("get <path>").description("Fetch the raw markdown body of a wiki page").option("--out <file>", "Write body to file instead of stdout").action(async (path7, opts) => {
+  cmd.command("get <path>").description("Fetch the raw markdown body of a wiki page").option("--out <file>", "Write body to file instead of stdout").action(async (path8, opts) => {
     const ctx = getCtx();
-    const safe = path7.split("/").map(encodeURIComponent).join("/");
+    const safe = path8.split("/").map(encodeURIComponent).join("/");
     const resp = await ctx.api.getRaw(`/api/wiki/pages/${safe}`, {
       headers: { Accept: "text/markdown,*/*" }
     });
     if (resp.status === 404) {
-      throw new CLIError(`page not found: ${path7}`, 3 /* NotFound */);
+      throw new CLIError(`page not found: ${path8}`, 3 /* NotFound */);
     }
     if (!resp.ok) {
       const detail = await resp.text();
@@ -18789,16 +19285,16 @@ ${pages.length} pages`));
     }
     const body = await resp.text();
     if (opts.out) {
-      fs10.writeFileSync(opts.out, body);
+      fs11.writeFileSync(opts.out, body);
       if (!isJson()) {
         console.log(source_default.dim(`wrote ${body.length} bytes to ${opts.out}`));
       } else {
-        console.log(JSON.stringify({ path: path7, bytes: body.length, file: opts.out }));
+        console.log(JSON.stringify({ path: path8, bytes: body.length, file: opts.out }));
       }
       return;
     }
     if (isJson()) {
-      console.log(JSON.stringify({ path: path7, body, etag: resp.headers.get("ETag") }));
+      console.log(JSON.stringify({ path: path8, body, etag: resp.headers.get("ETag") }));
     } else {
       process.stdout.write(body);
     }
@@ -18893,10 +19389,10 @@ ${pages.length} pages`));
     }
     if (opts.compilePromptOverrideFile) {
       const file = String(opts.compilePromptOverrideFile);
-      if (!fs10.existsSync(file)) {
+      if (!fs11.existsSync(file)) {
         throw new CLIError(`override file not found: ${file}`, 3 /* NotFound */);
       }
-      const content = fs10.readFileSync(file, "utf8");
+      const content = fs11.readFileSync(file, "utf8");
       const bytes = Buffer.byteLength(content, "utf8");
       if (bytes > 16 * 1024) {
         throw new CLIError(`compile prompt override exceeds 16 KB (${bytes} bytes)`, 4 /* Validation */);
@@ -18920,7 +19416,7 @@ ${pages.length} pages`));
     const ctx = getCtx();
     const resp = await ctx.api.get("/api/wiki/schema");
     if (opts.out) {
-      fs10.writeFileSync(opts.out, resp.body);
+      fs11.writeFileSync(opts.out, resp.body);
       if (!isJson()) {
         console.log(source_default.dim(`wrote ${resp.body.length} bytes to ${opts.out}`));
       } else {
@@ -18936,10 +19432,10 @@ ${pages.length} pages`));
   });
   schemaCmd.command("set").description("Replace the tenant wiki schema with the contents of <file>").requiredOption("--file <file>", "Path to schema markdown file").action(async (opts) => {
     const ctx = getCtx();
-    if (!fs10.existsSync(opts.file)) {
+    if (!fs11.existsSync(opts.file)) {
       throw new CLIError(`schema file not found: ${opts.file}`, 3 /* NotFound */);
     }
-    const body = fs10.readFileSync(opts.file, "utf8");
+    const body = fs11.readFileSync(opts.file, "utf8");
     const bytes = Buffer.byteLength(body, "utf8");
     if (bytes > 64 * 1024) {
       throw new CLIError(`schema body exceeds 64 KB (${bytes} bytes)`, 4 /* Validation */);
@@ -19465,8 +19961,8 @@ async function resolveCredentialFlag(value) {
     return Buffer.concat(chunks).toString("utf-8").trim();
   }
   if (value.startsWith("@")) {
-    const fs11 = await import("node:fs/promises");
-    return (await fs11.readFile(value.slice(1), "utf-8")).trim();
+    const fs12 = await import("node:fs/promises");
+    return (await fs12.readFile(value.slice(1), "utf-8")).trim();
   }
   return value;
 }
@@ -20652,19 +21148,19 @@ function registerDoctorCommand(program2) {
 
 // src/commands/skill.ts
 init_errors();
-import fs11 from "node:fs";
-import path7 from "node:path";
+import fs12 from "node:fs";
+import path8 from "node:path";
 import { fileURLToPath } from "node:url";
 function locateSkill() {
-  const here = path7.dirname(fileURLToPath(import.meta.url));
+  const here = path8.dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    path7.join(here, "skills", "martha-cli", "SKILL.md"),
-    path7.join(here, "..", "skills", "martha-cli", "SKILL.md"),
-    path7.join(here, "..", "..", "..", "skills", "martha-cli", "SKILL.md"),
-    path7.join(here, "..", "..", "skills", "martha-cli", "SKILL.md")
+    path8.join(here, "skills", "martha-cli", "SKILL.md"),
+    path8.join(here, "..", "skills", "martha-cli", "SKILL.md"),
+    path8.join(here, "..", "..", "..", "skills", "martha-cli", "SKILL.md"),
+    path8.join(here, "..", "..", "skills", "martha-cli", "SKILL.md")
   ];
   for (const p of candidates) {
-    if (fs11.existsSync(p))
+    if (fs12.existsSync(p))
       return p;
   }
   return null;
@@ -20674,7 +21170,7 @@ async function skillCommand() {
   if (!skillPath) {
     throw new CLIError("SKILL.md not found in the installed package. Reinstall via `npm i -g @aiaiai-pt/martha-cli` or `npx -y @aiaiai-pt/martha-cli@latest skill`.", 1 /* Error */);
   }
-  const body = fs11.readFileSync(skillPath, "utf-8");
+  const body = fs12.readFileSync(skillPath, "utf-8");
   process.stdout.write(body);
 }
 function registerSkillCommand(program2) {
@@ -20868,6 +21364,7 @@ registerDocumentSyncCommands(program2);
 registerWikiCommands(program2);
 registerApprovalCommands(program2);
 registerTaskCommands(program2);
+registerRunnerCommand(program2);
 registerTeamCommands(program2);
 registerIntegrationCommands(program2);
 registerConnectionCommands(program2);

package/package.json

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