@aiaiai-pt/martha-cli 0.19.0 → 0.22.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https
 
 ## [Unreleased]
 
+## [0.20.0] — 2026-06-21
+
+### Added — #649 agent→agent delegation surfaces
+- `martha agents add-agent <coordinator> <sub-agent> [--set k=v]` grants a coordinator the ability to delegate to a sub-agent; `martha agents remove-agent <coordinator> <sub-agent>` revokes it; `martha agents agents <coordinator>` lists the granted sub-agents. All support `--json`. Backed by the existing `/api/admin/definitions/agents/{name}/agents` routes (#648). Self-delegation surfaces the API's 400 (`an agent cannot delegate to itself`); an unknown sub-agent returns 404.
+
+<!-- NOTE: package.json was already at 0.19.0 on main while this CHANGELOG's latest entry was 0.16.1 — versions 0.17.0–0.19.0 shipped without CHANGELOG sections (pre-existing drift). This 0.20.0 bump is the MINOR bump for #649 off the real 0.19.0 base; the 0.17–0.19 gap is not reconstructed here. -->
+
 ## [0.16.1] — 2026-06-14
 
 ### Fixed

package/dist/index.js

@@ -5,25 +5,43 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: () => mod[key],
+        get: __accessProp.bind(mod, key),
         enumerable: true
       });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -1001,7 +1019,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
         this._exitCallback = (err) => {
           if (err.code !== "commander.executeSubCommandAsync") {
             throw err;
-          } else {}
+          }
         };
       }
       return this;
@@ -11059,7 +11077,7 @@ import { createInterface as createInterface2 } from "node:readline";
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.19.0";
+var CLI_VERSION = "0.22.0";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -11331,7 +11349,302 @@ function createApprovalTagStripper() {
   };
 }
 
+// src/lib/local-exec.ts
+import { spawn } from "node:child_process";
+import { closeSync, openSync, promises as fs5 } from "node:fs";
+import * as path4 from "node:path";
+var DEFAULT_TIMEOUT_MS = 20000;
+var MAX_OUTPUT = 256 * 1024;
+function runnerDir(cwd) {
+  return path4.join(cwd, ".martha-runner");
+}
+async function runHostCommand(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 "";
+    }
+  };
+  return await new Promise((resolve, reject) => {
+    let settled = false;
+    const child = spawn(command, {
+      shell: true,
+      cwd: opts.cwd,
+      detached: true,
+      stdio: ["ignore", fd, fd]
+    });
+    closeSync(fd);
+    const timer = setTimeout(async () => {
+      if (settled)
+        return;
+      settled = true;
+      child.unref();
+      resolve({
+        stdout: await readLog(),
+        stderr: "",
+        exit_code: 0,
+        backgrounded: true,
+        pid: child.pid
+      });
+    }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    child.on("error", (e) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      reject(e);
+    });
+    child.on("close", async (code) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ stdout: await readLog(), stderr: "", exit_code: code ?? -1 });
+    });
+  });
+}
+function safeName(s) {
+  return s.replace(/[^a-zA-Z0-9_.-]/g, "_").slice(0, 120) || "task";
+}
+
+class Journal {
+  cwd;
+  constructor(cwd) {
+    this.cwd = cwd;
+  }
+  file() {
+    return path4.join(runnerDir(this.cwd), "journal.json");
+  }
+  async load() {
+    try {
+      return JSON.parse(await fs5.readFile(this.file(), "utf8"));
+    } catch {
+      return {};
+    }
+  }
+  async save(data) {
+    await fs5.mkdir(runnerDir(this.cwd), { recursive: true });
+    await fs5.writeFile(this.file(), JSON.stringify(data, null, 2));
+  }
+  static key(sessionId, toolCallId) {
+    return `${sessionId}:${toolCallId}`;
+  }
+  async lookup(sessionId, toolCallId) {
+    return (await this.load())[Journal.key(sessionId, toolCallId)];
+  }
+  async recordRunning(sessionId, toolCallId, command, now) {
+    const data = await this.load();
+    data[Journal.key(sessionId, toolCallId)] = {
+      state: "running",
+      command,
+      started_at: now
+    };
+    await this.save(data);
+  }
+  async recordDone(sessionId, toolCallId, result) {
+    const data = await this.load();
+    const k = Journal.key(sessionId, toolCallId);
+    const prev = data[k];
+    data[k] = {
+      state: "done",
+      command: prev?.command ?? "",
+      started_at: prev?.started_at ?? "",
+      result
+    };
+    await this.save(data);
+  }
+}
+function decideFromJournal(entry) {
+  if (!entry)
+    return { kind: "fresh" };
+  if (entry.state === "done" && entry.result)
+    return { kind: "replay", result: entry.result };
+  return { kind: "crashed", command: entry.command };
+}
+function parseHostExecRequests(data) {
+  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 !== "host_exec" || t.status !== "awaiting_input")
+      continue;
+    if (!t.tool_call_id)
+      continue;
+    out.push({ toolCallId: t.tool_call_id, command: t.args?.command ?? "" });
+  }
+  return out;
+}
+
+// src/lib/host-screenshot.ts
+async function captureScreenshot(url, opts) {
+  const moduleName = "playwright";
+  let chromium;
+  try {
+    ({ chromium } = await import(moduleName));
+  } catch {
+    throw new Error("playwright is not installed on the runner. Install it to use host_screenshot: `npm i -D playwright && npx playwright install chromium`");
+  }
+  const browser = await chromium.launch({ headless: true });
+  try {
+    const page = await browser.newPage();
+    await page.goto(url, { waitUntil: "load", timeout: 30000 });
+    if (opts.waitMs > 0)
+      await page.waitForTimeout(opts.waitMs);
+    const buf = await page.screenshot({
+      fullPage: opts.fullPage,
+      type: "png"
+    });
+    return buf;
+  } finally {
+    await browser.close();
+  }
+}
+function parseHostScreenshotRequests(data) {
+  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 !== "host_screenshot" || t.status !== "awaiting_input")
+      continue;
+    if (!t.tool_call_id || !t.args?.url)
+      continue;
+    out.push({
+      toolCallId: t.tool_call_id,
+      url: t.args.url,
+      fullPage: t.args.full_page !== false,
+      waitMs: typeof t.args.wait_ms === "number" ? t.args.wait_ms : 500
+    });
+  }
+  return out;
+}
+
 // src/commands/chat.ts
+async function resolveHostExec(sessionId, toolCallId, command, state) {
+  const decision = decideFromJournal(await state.journal.lookup(sessionId, toolCallId));
+  if (decision.kind === "replay")
+    return decision.result;
+  if (decision.kind === "crashed") {
+    return {
+      error: true,
+      exit_code: -1,
+      message: `A previous run did not complete; not re-running: ${decision.command}`
+    };
+  }
+  if (!state.autoYes) {
+    process.stderr.write(source_default.yellow(`
+[host_exec] refused (re-run with --yes to allow): ${command}
+`));
+    return {
+      declined: true,
+      exit_code: -1,
+      message: "Host execution declined; re-run with --yes to allow."
+    };
+  }
+  process.stderr.write(source_default.dim(`
+[host_exec] $ ${command}
+  (cwd: ${state.cwd})
+`));
+  await state.journal.recordRunning(sessionId, toolCallId, command, new Date().toISOString());
+  let result;
+  try {
+    result = await runHostCommand(command, toolCallId, { cwd: state.cwd });
+  } catch (e) {
+    result = { stdout: "", stderr: String(e), exit_code: -1 };
+  }
+  await state.journal.recordDone(sessionId, toolCallId, result);
+  return result;
+}
+async function resolveHostScreenshot(ctx, sessionId, req, state) {
+  if (!state.autoYes) {
+    process.stderr.write(source_default.yellow(`
+[host_screenshot] refused (re-run with --yes to allow): ${req.url}
+`));
+    return {
+      declined: true,
+      message: "Host screenshot declined; re-run with --yes to allow."
+    };
+  }
+  process.stderr.write(source_default.dim(`
+[host_screenshot] ${req.url}
+`));
+  let png;
+  try {
+    png = await captureScreenshot(req.url, {
+      fullPage: req.fullPage,
+      waitMs: req.waitMs
+    });
+  } catch (e) {
+    return { error: true, message: `screenshot failed: ${String(e)}` };
+  }
+  try {
+    const mint = await ctx.api.post(`/api/chat/${encodeURIComponent(sessionId)}/local-artifact-upload`, {
+      content_type: "image/png"
+    });
+    const put = await fetch(mint.upload_url, {
+      method: "PUT",
+      headers: { "Content-Type": "image/png" },
+      body: new Uint8Array(png)
+    });
+    if (!put.ok) {
+      return {
+        error: true,
+        message: `image upload failed: HTTP ${put.status}`
+      };
+    }
+    return {
+      text: `Screenshot of ${req.url} captured (${png.length} bytes).`,
+      _images: [{ storage_key: mint.storage_key }]
+    };
+  } catch (e) {
+    return { error: true, message: `image upload failed: ${String(e)}` };
+  }
+}
+async function _postToolResult(ctx, sessionId, toolCallId, result, label) {
+  try {
+    await ctx.api.post(`/api/chat/${encodeURIComponent(sessionId)}/tool-result`, { tool_call_id: toolCallId, result });
+  } catch (e) {
+    process.stderr.write(source_default.red(`[${label}] failed to POST result: ${String(e)}
+`));
+  }
+}
+async function handleHostExecFrame(ctx, sessionId, data, state) {
+  for (const req of parseHostExecRequests(data)) {
+    const id = req.toolCallId;
+    if (state.handled.has(id))
+      continue;
+    state.handled.add(id);
+    const result = await resolveHostExec(sessionId, id, req.command, state);
+    await _postToolResult(ctx, sessionId, id, result, "host_exec");
+  }
+  for (const req of parseHostScreenshotRequests(data)) {
+    const id = req.toolCallId;
+    if (state.handled.has(id))
+      continue;
+    state.handled.add(id);
+    const result = await resolveHostScreenshot(ctx, sessionId, req, state);
+    await _postToolResult(ctx, sessionId, id, result, "host_screenshot");
+  }
+}
 function parseSlashCommand(input) {
   const trimmed = input.trim();
   if (!trimmed.startsWith("/"))
@@ -11382,7 +11695,16 @@ async function sendMessage(ctx, sessionId, message, opts = {}) {
       params.selected_agent = opts.agentName;
     reqOpts.params = params;
   }
-  const res = await ctx.api.postRaw(`/api/chat/${encodeURIComponent(sessionId)}`, { content: message }, reqOpts);
+  const localExecState = opts.localExec ? {
+    cwd: opts.localExec.cwd,
+    autoYes: opts.localExec.autoYes,
+    handled: new Set,
+    journal: new Journal(opts.localExec.cwd)
+  } : null;
+  const reqBody = { content: message };
+  if (opts.localExec)
+    reqBody.capability_keys = ["local_exec"];
+  const res = await ctx.api.postRaw(`/api/chat/${encodeURIComponent(sessionId)}`, reqBody, reqOpts);
   const contentType = res.headers.get("content-type") ?? "";
   let fullResponse = "";
   if (contentType.includes("application/json")) {
@@ -11430,6 +11752,9 @@ async function sendMessage(ctx, sessionId, message, opts = {}) {
           case "tool_status":
             if (opts.onToolStatus)
               opts.onToolStatus(event.data);
+            if (localExecState) {
+              await handleHostExecFrame(ctx, sessionId, event.data, localExecState);
+            }
             break;
           case "clear":
             fullResponse = "";
@@ -11650,7 +11975,7 @@ async function showHistoryPicker(ctx, rl) {
   }
   return data.items[idx].session_id;
 }
-async function runRepl(ctx, initialSessionId, clientId, agentName, showTools, timeoutMs) {
+async function runRepl(ctx, initialSessionId, clientId, agentName, showTools, timeoutMs, localExec) {
   let sessionId = initialSessionId;
   process.stderr.write(source_default.dim(`martha v${CLI_VERSION} | session: ${sessionId.slice(0, 8)}...
 `));
@@ -11787,6 +12112,7 @@ Cancelled.
     try {
       const result = await sendMessage(ctx, sessionId, input, {
         timeoutMs,
+        localExec,
         onToken: (token) => process.stdout.write(stripper.push(token)),
         onToolCall: showTools ? (data) => process.stderr.write(formatToolCall(data)) : undefined,
         onToolResult: (data) => {
@@ -11842,7 +12168,7 @@ Error: ${err instanceof Error ? err.message : String(err)}
   process.stderr.write(`
 `);
 }
-async function runOneShot(ctx, sessionId, message, isJson, clientId, agentName, showTools, timeoutMs) {
+async function runOneShot(ctx, sessionId, message, isJson, clientId, agentName, showTools, timeoutMs, localExec) {
   const toolCalls = [];
   function recordToolStatus(data) {
     try {
@@ -11866,6 +12192,7 @@ async function runOneShot(ctx, sessionId, message, isJson, clientId, agentName,
     clientId,
     agentName,
     timeoutMs,
+    localExec,
     onToolStatus: isJson ? recordToolStatus : showTools ? (data) => {
       recordToolStatus(data);
       process.stderr.write(formatToolStatus(data));
@@ -11889,7 +12216,7 @@ async function runOneShot(ctx, sessionId, message, isJson, clientId, agentName,
   }
 }
 function registerChatCommand(program2) {
-  program2.command("chat").description("Chat with a Martha agent").option("--session <id>", "Resume an existing session").option("--client <nameOrId>", "Use a specific client (name or ID)").option("--agent <name>", "Drive the chat with a specific copilot agent (defaults to profile.default_agent)").option("--message <text>", "Send a single message (non-interactive)").option("--show-tools", "Show tool calls and results during chat").option("--timeout <seconds>", "Per-message HTTP timeout in seconds (default: 600)").action(async (opts) => {
+  program2.command("chat").description("Chat with a Martha agent").option("--session <id>", "Resume an existing session").option("--client <nameOrId>", "Use a specific client (name or ID)").option("--agent <name>", "Drive the chat with a specific copilot agent (defaults to profile.default_agent)").option("--message <text>", "Send a single message (non-interactive)").option("--show-tools", "Show tool calls and results during chat").option("--local-exec", "Allow the agent to run host tools on THIS machine (#568). Requires the server to have LOCAL_EXEC_ENABLED=1.").option("--yes", "Auto-approve host tool execution (required with --local-exec for non-interactive runs).").option("--timeout <seconds>", "Per-message HTTP timeout in seconds (default: 600)").action(async (opts) => {
     const ctx = createContext({
       profileOverride: program2.opts().profile,
       verbose: program2.opts().verbose
@@ -11924,13 +12251,14 @@ function registerChatCommand(program2) {
     }
     const showTools = !!opts.showTools;
     const timeoutMs = opts.timeout ? parseTimeoutSeconds(opts.timeout) * 1000 : undefined;
+    const localExec = opts.localExec ? { cwd: process.cwd(), autoYes: !!opts.yes } : undefined;
     if (opts.message) {
-      await runOneShot(ctx, sessionId, opts.message, isJson, clientId, agentName, showTools, timeoutMs);
+      await runOneShot(ctx, sessionId, opts.message, isJson, clientId, agentName, showTools, timeoutMs, localExec);
     } else {
       if (isJson) {
         throw new CLIError("The --json flag requires --message for non-interactive mode.", 4 /* Validation */, 'Example: martha --json chat --message "hello"');
       }
-      await runRepl(ctx, sessionId, clientId, agentName, showTools, timeoutMs);
+      await runRepl(ctx, sessionId, clientId, agentName, showTools, timeoutMs, localExec);
     }
   });
 }
@@ -12276,20 +12604,27 @@ function registerConfigCommand(program2) {
 }
 
 // src/commands/definitions-apply.ts
-import fs5 from "node:fs";
-import path4 from "node:path";
+import fs6 from "node:fs";
+import path5 from "node:path";
 init_dist();
 init_errors();
-var VALID_KINDS = new Set(["Function", "Workflow", "Agent"]);
+var VALID_KINDS = new Set([
+  "Function",
+  "Workflow",
+  "Agent",
+  "Trigger"
+]);
 var KIND_TO_API_PATH = {
   Function: "/api/admin/definitions/functions",
   Workflow: "/api/admin/definitions/workflows",
-  Agent: "/api/admin/definitions/agents"
+  Agent: "/api/admin/definitions/agents",
+  Trigger: "/api/admin/triggers"
 };
 var KIND_TO_PLURAL = {
   Function: "Functions",
   Workflow: "Workflows",
-  Agent: "Agents"
+  Agent: "Agents",
+  Trigger: "Triggers"
 };
 var SERVER_GENERATED_FIELDS = new Set([
   "id",
@@ -12312,20 +12647,20 @@ var SERVER_GENERATED_FIELDS = new Set([
 ]);
 var AGENT_MANAGED_FIELDS = new Set(["functions", "workflows"]);
 function loadDefinitions(inputPath) {
-  const resolved = path4.resolve(inputPath);
-  if (!fs5.existsSync(resolved)) {
+  const resolved = path5.resolve(inputPath);
+  if (!fs6.existsSync(resolved)) {
     throw new CLIError(`Path not found: ${inputPath}`, 1 /* Error */);
   }
-  const stat = fs5.statSync(resolved);
+  const stat = fs6.statSync(resolved);
   if (stat.isDirectory()) {
     return loadDirectory(resolved);
   }
   return loadFile(resolved);
 }
 function loadDirectory(dirPath) {
-  const entries = fs5.readdirSync(dirPath).sort();
+  const entries = fs6.readdirSync(dirPath).sort();
   const validExts = new Set([".yaml", ".yml", ".json"]);
-  const files = entries.filter((e) => validExts.has(path4.extname(e).toLowerCase())).map((e) => path4.join(dirPath, e));
+  const files = entries.filter((e) => validExts.has(path5.extname(e).toLowerCase())).map((e) => path5.join(dirPath, e));
   if (files.length === 0) {
     throw new CLIError(`No YAML or JSON files found in ${dirPath}`, 4 /* Validation */);
   }
@@ -12336,8 +12671,8 @@ function loadDirectory(dirPath) {
   return results;
 }
 function loadFile(filePath) {
-  const content = fs5.readFileSync(filePath, "utf-8");
-  const ext = path4.extname(filePath).toLowerCase();
+  const content = fs6.readFileSync(filePath, "utf-8");
+  const ext = path5.extname(filePath).toLowerCase();
   if (ext === ".json") {
     const parsed = parseJsonFile(content, filePath);
     return [toLocalDefinition(parsed, filePath)];
@@ -12759,7 +13094,7 @@ Examples:
 }
 
 // src/commands/definitions-export.ts
-import fs6 from "node:fs";
+import fs7 from "node:fs";
 init_errors();
 async function exportDefinitions(ctx, opts, isJsonMode) {
   const params = {};
@@ -12775,7 +13110,7 @@ async function exportDefinitions(ctx, opts, isJsonMode) {
   const text = await res.text();
   if (opts.output) {
     try {
-      fs6.writeFileSync(opts.output, text);
+      fs7.writeFileSync(opts.output, text);
     } catch (err) {
       throw new CLIError(`Failed to write ${opts.output}: ${err instanceof Error ? err.message : String(err)}`, 1 /* Error */);
     }
@@ -13495,8 +13830,8 @@ function registerProjectionCommands(parentCmd, getCtx, isJson) {
       } catch {}
     }
     if (opts.output) {
-      const fs7 = await import("node:fs/promises");
-      await fs7.writeFile(opts.output, toWrite, "utf-8");
+      const fs8 = await import("node:fs/promises");
+      await fs8.writeFile(opts.output, toWrite, "utf-8");
       if (!isJson()) {
         console.error(source_default.dim(`Wrote ${format} projection of '${name}' to ${opts.output}`));
       }
@@ -13850,10 +14185,61 @@ Usage:
         ].join("  "));
       }
     });
+    parentCmd.command("add-agent <coordinator> <subAgent>").description("Grant a coordinator agent the ability to delegate to a sub-agent").option("--set <items...>", "Config overrides (key=value)").action(async (coordinator, subAgent, opts) => {
+      const ctx = getCtx();
+      const body = {
+        sub_agent_name: subAgent
+      };
+      if (opts.set) {
+        body.config_overrides = parseSetFlags(opts.set);
+      }
+      const result = await ctx.api.post(`${API_PATH}/${encodeURIComponent(coordinator)}/agents`, body);
+      if (isJson()) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+      }
+      console.log(`Agent '${coordinator}' may now delegate to '${subAgent}'`);
+    });
+    parentCmd.command("remove-agent <coordinator> <subAgent>").description("Revoke a coordinator's delegation grant to a sub-agent").action(async (coordinator, subAgent) => {
+      const ctx = getCtx();
+      const endpoint = `${API_PATH}/${encodeURIComponent(coordinator)}/agents/${encodeURIComponent(subAgent)}`;
+      await ctx.api.del(endpoint);
+      if (isJson()) {
+        console.log(JSON.stringify({
+          coordinator,
+          sub_agent_name: subAgent,
+          removed: true
+        }));
+        return;
+      }
+      console.log(`Revoked sub-agent '${subAgent}' from coordinator '${coordinator}'`);
+    });
+    parentCmd.command("agents <coordinator>").description("List the sub-agents a coordinator may delegate to").action(async (coordinator) => {
+      const ctx = getCtx();
+      const items = await ctx.api.get(`${API_PATH}/${encodeURIComponent(coordinator)}/agents`);
+      if (isJson()) {
+        console.log(JSON.stringify(items, null, 2));
+        return;
+      }
+      if (items.length === 0) {
+        console.log(source_default.dim("No sub-agents granted."));
+        return;
+      }
+      const nameW = Math.max(8, ...items.map((s) => String(s.name ?? "").length));
+      const header = ["SUB-AGENT", "DESCRIPTION"].map((h, i) => h.padEnd([nameW, 40][i])).join("  ");
+      console.log(source_default.bold(header));
+      console.log(source_default.dim("-".repeat(header.length)));
+      for (const s of items) {
+        console.log([
+          String(s.name ?? "").padEnd(nameW),
+          String(s.description ?? "-")
+        ].join("  "));
+      }
+    });
     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 path5 = `${API_PATH}/${encodeURIComponent(agent)}`;
-      const current = await ctx.api.get(path5);
+      const path6 = `${API_PATH}/${encodeURIComponent(agent)}`;
+      const current = await ctx.api.get(path6);
       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()) {
@@ -13905,7 +14291,7 @@ Usage:
           roots.delete(c);
         body.self_grant_collection_roots = [...roots];
       }
-      const updated = await ctx.api.put(path5, body);
+      const updated = await ctx.api.put(path6, body);
       if (isJson()) {
         console.log(JSON.stringify(policyView(updated), null, 2));
         return;
@@ -13917,8 +14303,120 @@ Usage:
   }
 };
 
+// src/commands/triggers.ts
+init_errors();
+function triggerKind(item) {
+  if (item.schedule_config)
+    return "schedule";
+  if (item.deadman_config)
+    return "deadman";
+  return "event";
+}
+function scheduleSummary(sched) {
+  return String(sched.cron ?? sched.interval ?? sched.spec ?? "schedule");
+}
+var triggersConfig = {
+  typeName: "trigger",
+  typeNamePlural: "triggers",
+  apiPath: "/api/admin/triggers",
+  extractList: (data) => {
+    if (!Array.isArray(data)) {
+      throw new Error("Unexpected API response shape for triggers list");
+    }
+    return data;
+  },
+  listColumns: [
+    { header: "NAME", accessor: (item) => String(item.name ?? "") },
+    { header: "KIND", accessor: (item) => triggerKind(item) },
+    {
+      header: "EVENT / SCHEDULE",
+      accessor: (item) => {
+        const sched = item.schedule_config;
+        if (sched)
+          return scheduleSummary(sched);
+        return String(item.event_type ?? "-");
+      }
+    },
+    { header: "TARGET", accessor: (item) => String(item.target_name ?? "-") },
+    {
+      header: "STATUS",
+      accessor: (item) => item.is_active !== false ? "active" : "inactive"
+    }
+  ],
+  renderDetail: (t) => {
+    console.log(source_default.bold(`Trigger: ${t.name}
+`));
+    if (t.description)
+      console.log(`  ${t.description}
+`);
+    console.log(`  Kind:        ${triggerKind(t)}`);
+    console.log(`  Status:      ${t.is_active !== false ? source_default.green("active") : source_default.dim("inactive")}`);
+    if (t.event_type)
+      console.log(`  Event type:  ${t.event_type}`);
+    const filter = t.event_filter;
+    if (filter && Object.keys(filter).length)
+      console.log(`  Event filter: ${JSON.stringify(filter)}`);
+    const sched = t.schedule_config;
+    if (sched)
+      console.log(`  Schedule:    ${scheduleSummary(sched)}  ${source_default.dim(JSON.stringify(sched))}`);
+    const deadman = t.deadman_config;
+    if (deadman)
+      console.log(`  Deadman:     ${JSON.stringify(deadman)}`);
+    console.log(`  Target:      ${t.target_type ?? "workflow"} → ${t.target_name ?? "-"}`);
+    const mapping = t.input_mapping;
+    if (mapping && Object.keys(mapping).length) {
+      console.log(`
+  ${source_default.bold("Input mapping:")}`);
+      for (const [k, v] of Object.entries(mapping)) {
+        console.log(`    ${k.padEnd(20)} ${source_default.dim(String(v))}`);
+      }
+    }
+    if (t.dedup_key)
+      console.log(`
+  Dedup key:   ${t.dedup_key}`);
+    if (t.version)
+      console.log(`  Version:     ${t.version}`);
+    if (t.updated_at)
+      console.log(`  Updated:     ${t.updated_at}`);
+  },
+  extraListOptions: (cmd) => {
+    cmd.option("--active", "Only active triggers");
+  },
+  buildListParams: (opts) => {
+    const params = {};
+    if (opts.active)
+      params.active = "true";
+    return params;
+  },
+  extraCommands: (parentCmd, getCtx, isJson) => {
+    parentCmd.command("test <name>").description("Dry-run a trigger against a sample event (no workflow started)").requiredOption("--event <json>", "Sample CloudEvent JSON to match against").action(async (name, opts) => {
+      let event;
+      try {
+        event = JSON.parse(opts.event);
+      } catch {
+        throw new CLIError("--event must be valid JSON", 4 /* Validation */, `Example: martha triggers test ${name} --event '{"type":"facility_booking.booking.created","data":{}}'`);
+      }
+      const ctx = getCtx();
+      const res = await ctx.api.post(`/api/admin/triggers/${encodeURIComponent(name)}/test`, { event });
+      if (isJson()) {
+        console.log(JSON.stringify(res, null, 2));
+        return;
+      }
+      console.log(res.matched ? source_default.green(`✓ trigger '${name}' WOULD fire for this event`) : source_default.yellow(`✗ trigger '${name}' would NOT fire for this event`));
+      console.log(`  Event-type / filter match: ${res.filter_result ? source_default.green("yes") : source_default.red("no")}`);
+      if (res.input_mapping_result) {
+        console.log(`
+  ${source_default.bold("Resolved input mapping:")}`);
+        for (const [k, v] of Object.entries(res.input_mapping_result)) {
+          console.log(`    ${k.padEnd(20)} ${source_default.dim(JSON.stringify(v))}`);
+        }
+      }
+    });
+  }
+};
+
 // src/commands/documents.ts
-import fs7 from "node:fs";
+import fs8 from "node:fs";
 init_errors();
 var TERMINAL_STATUSES2 = new Set(["ready", "error"]);
 var SPINNER_FRAMES2 = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
@@ -14220,7 +14718,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 (!fs7.existsSync(filePath)) {
+    if (!fs8.existsSync(filePath)) {
       throw new CLIError(`File not found: ${filePath}`, 4 /* Validation */);
     }
     const result = await ctx.api.upload(`/api/admin/collections/${encodeURIComponent(collectionId)}/documents`, filePath);
@@ -15797,8 +16295,8 @@ ${data.length} spec(s)`));
 Resources:
 `));
       for (const r of resources) {
-        const path5 = r.path || `/${r.name}`;
-        console.log(`  ${source_default.cyan(r.label || r.name)}` + source_default.dim(` → ${path5}`));
+        const path6 = r.path || `/${r.name}`;
+        console.log(`  ${source_default.cyan(r.label || r.name)}` + source_default.dim(` → ${path6}`));
       }
     }
     try {
@@ -15818,14 +16316,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, path5, 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, path6, 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 = path5.startsWith("/") ? path5.slice(1) : path5;
+    const cleanPath = path6.startsWith("/") ? path6.slice(1) : path6;
     const proxyUrl = `/api/admin/plugins/${encodeURIComponent(name)}/${cleanPath}`;
     const params = {};
     if (opts.query) {
@@ -16035,8 +16533,8 @@ async function resolveCredentialValue(value) {
   if (value === "-")
     return readStdin();
   if (value.startsWith("@")) {
-    const fs8 = await import("node:fs/promises");
-    return (await fs8.readFile(value.slice(1), "utf-8")).trim();
+    const fs9 = await import("node:fs/promises");
+    return (await fs9.readFile(value.slice(1), "utf-8")).trim();
   }
   return value;
 }
@@ -16151,8 +16649,8 @@ Notification connections`));
     if (credentialValue === "-") {
       credentialValue = await readStdin2();
     } else if (credentialValue?.startsWith("@")) {
-      const fs8 = await import("node:fs/promises");
-      credentialValue = await fs8.readFile(credentialValue.slice(1), "utf-8");
+      const fs9 = await import("node:fs/promises");
+      credentialValue = await fs9.readFile(credentialValue.slice(1), "utf-8");
     }
     if (!credentialValue) {
       throw new Error("--credential-value is required (use '-' for stdin or '@path' for file).");
@@ -16202,11 +16700,11 @@ async function readStdin2() {
 
 // src/commands/messaging.ts
 init_errors();
-async function messagingFetch(baseUrl, path5, opts) {
-  if (/^(https?:)?\/\//i.test(path5)) {
+async function messagingFetch(baseUrl, path6, opts) {
+  if (/^(https?:)?\/\//i.test(path6)) {
     throw new CLIError("Absolute URL paths are not allowed", 1 /* Error */);
   }
-  const url = new URL(path5, baseUrl);
+  const url = new URL(path6, baseUrl);
   const headers = {
     "Content-Type": "application/json"
   };
@@ -17486,7 +17984,7 @@ ${models.length} models`));
 }
 
 // src/commands/wiki.ts
-import fs8 from "node:fs";
+import fs9 from "node:fs";
 init_errors();
 function registerWikiCommands(program2) {
   const cmd = program2.command("wiki").description("Manage tenant wiki pages, settings, schema, recompile (#245 D5.4)");
@@ -17533,14 +18031,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 (path5, 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 (path6, opts) => {
     const ctx = getCtx();
-    const safe = path5.split("/").map(encodeURIComponent).join("/");
+    const safe = path6.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: ${path5}`, 3 /* NotFound */);
+      throw new CLIError(`page not found: ${path6}`, 3 /* NotFound */);
     }
     if (!resp.ok) {
       const detail = await resp.text();
@@ -17548,16 +18046,16 @@ ${pages.length} pages`));
     }
     const body = await resp.text();
     if (opts.out) {
-      fs8.writeFileSync(opts.out, body);
+      fs9.writeFileSync(opts.out, body);
       if (!isJson()) {
         console.log(source_default.dim(`wrote ${body.length} bytes to ${opts.out}`));
       } else {
-        console.log(JSON.stringify({ path: path5, bytes: body.length, file: opts.out }));
+        console.log(JSON.stringify({ path: path6, bytes: body.length, file: opts.out }));
       }
       return;
     }
     if (isJson()) {
-      console.log(JSON.stringify({ path: path5, body, etag: resp.headers.get("ETag") }));
+      console.log(JSON.stringify({ path: path6, body, etag: resp.headers.get("ETag") }));
     } else {
       process.stdout.write(body);
     }
@@ -17652,10 +18150,10 @@ ${pages.length} pages`));
     }
     if (opts.compilePromptOverrideFile) {
       const file = String(opts.compilePromptOverrideFile);
-      if (!fs8.existsSync(file)) {
+      if (!fs9.existsSync(file)) {
         throw new CLIError(`override file not found: ${file}`, 3 /* NotFound */);
       }
-      const content = fs8.readFileSync(file, "utf8");
+      const content = fs9.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 */);
@@ -17679,7 +18177,7 @@ ${pages.length} pages`));
     const ctx = getCtx();
     const resp = await ctx.api.get("/api/wiki/schema");
     if (opts.out) {
-      fs8.writeFileSync(opts.out, resp.body);
+      fs9.writeFileSync(opts.out, resp.body);
       if (!isJson()) {
         console.log(source_default.dim(`wrote ${resp.body.length} bytes to ${opts.out}`));
       } else {
@@ -17695,10 +18193,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 (!fs8.existsSync(opts.file)) {
+    if (!fs9.existsSync(opts.file)) {
       throw new CLIError(`schema file not found: ${opts.file}`, 3 /* NotFound */);
     }
-    const body = fs8.readFileSync(opts.file, "utf8");
+    const body = fs9.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 */);
@@ -18224,8 +18722,8 @@ async function resolveCredentialFlag(value) {
     return Buffer.concat(chunks).toString("utf-8").trim();
   }
   if (value.startsWith("@")) {
-    const fs9 = await import("node:fs/promises");
-    return (await fs9.readFile(value.slice(1), "utf-8")).trim();
+    const fs10 = await import("node:fs/promises");
+    return (await fs10.readFile(value.slice(1), "utf-8")).trim();
   }
   return value;
 }
@@ -19411,19 +19909,19 @@ function registerDoctorCommand(program2) {
 
 // src/commands/skill.ts
 init_errors();
-import fs9 from "node:fs";
-import path5 from "node:path";
+import fs10 from "node:fs";
+import path6 from "node:path";
 import { fileURLToPath } from "node:url";
 function locateSkill() {
-  const here = path5.dirname(fileURLToPath(import.meta.url));
+  const here = path6.dirname(fileURLToPath(import.meta.url));
   const candidates = [
-    path5.join(here, "skills", "martha-cli", "SKILL.md"),
-    path5.join(here, "..", "skills", "martha-cli", "SKILL.md"),
-    path5.join(here, "..", "..", "..", "skills", "martha-cli", "SKILL.md"),
-    path5.join(here, "..", "..", "skills", "martha-cli", "SKILL.md")
+    path6.join(here, "skills", "martha-cli", "SKILL.md"),
+    path6.join(here, "..", "skills", "martha-cli", "SKILL.md"),
+    path6.join(here, "..", "..", "..", "skills", "martha-cli", "SKILL.md"),
+    path6.join(here, "..", "..", "skills", "martha-cli", "SKILL.md")
   ];
   for (const p of candidates) {
-    if (fs9.existsSync(p))
+    if (fs10.existsSync(p))
       return p;
   }
   return null;
@@ -19433,7 +19931,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 = fs9.readFileSync(skillPath, "utf-8");
+  const body = fs10.readFileSync(skillPath, "utf-8");
   process.stdout.write(body);
 }
 function registerSkillCommand(program2) {
@@ -19618,6 +20116,7 @@ registerConfigCommand(program2);
 registerDefinitionCommands(program2, functionsConfig);
 registerDefinitionCommands(program2, workflowsConfig);
 registerDefinitionCommands(program2, agentsConfig);
+registerDefinitionCommands(program2, triggersConfig);
 registerDefinitionsApply(program2);
 registerDefinitionsExport(program2);
 registerDocumentCommands(program2);

package/package.json

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

package/skills/martha-cli/SKILL.md

@@ -279,6 +279,16 @@ martha agents functions <agent>                                     # List grant
 
 `--collection` scopes the grant to one collection per the #372 PR2 cascade. Omit it to grant at the root (tenant-wide); pass it on `remove-function` to revoke just that scope. Server returns 400 if the function is collection-agnostic (e.g. `recall`).
 
+**Sub-agent grants (agent→agent delegation):**
+
+```bash
+martha agents add-agent <coordinator> <sub-agent> [--set key=value]  # Let <coordinator> delegate to <sub-agent>
+martha agents remove-agent <coordinator> <sub-agent>                 # Revoke the delegation grant
+martha agents agents <coordinator>                                   # List the sub-agents <coordinator> may delegate to
+```
+
+A grant means the coordinator agent *may* delegate to the sub-agent at invoke time (the sub-agent loads as an `_is_agent` delegate tool); the sub-agent's own tool calls still pass the policy gate under its own grants. `--set key=value` records `config_overrides` for the delegation. Self-delegation is rejected with a clear 400 (`an agent cannot delegate to itself`), and granting an unknown sub-agent returns 404. All three commands support `--json`.
+
 ---
 
 ## Tasks: queue + executor lifecycle