@aiaiai-pt/martha-cli 0.18.0 → 0.20.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.18.0";
+var CLI_VERSION = "0.20.0";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -13559,27 +13577,6 @@ var workflowsConfig = {
 
 // src/commands/agents.ts
 init_errors();
-
-// src/lib/collections.ts
-init_errors();
-var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-async function resolveCollectionIdForGrant(ctx, ref) {
-  if (UUID_RE.test(ref)) {
-    return ref;
-  }
-  const all = await ctx.api.get("/api/admin/collections", {
-    params: { active_only: "false" }
-  });
-  const bySlug = all.find((c) => c.slug === ref);
-  if (bySlug)
-    return bySlug.id;
-  const byName = all.find((c) => c.name === ref);
-  if (byName)
-    return byName.id;
-  throw new CLIError(`Collection '${ref}' not found (tried UUID, slug, and name).`, 3 /* NotFound */, "Run `martha documents collections --tree` to see available collections.");
-}
-
-// src/commands/agents.ts
 function parseSetFlags(items) {
   const result = {};
   for (const item of items) {
@@ -13756,7 +13753,10 @@ var agentsConfig = {
       console.log(`  Updated:     ${agent.updated_at}`);
   },
   extraCommands: (parentCmd, getCtx, isJson) => {
-    parentCmd.command("add-function <agent> <functionName>").description("Add a function to an agent").option("--set <items...>", "Config overrides (key=value)").option("--collection <slug-or-id>", "Scope the grant to one collection (#372 PR2). " + "Server rejects with 400 if the function is collection-agnostic.").action(async (agent, functionName, opts) => {
+    parentCmd.command("add-function <agent> <functionName>").description("Add a function to an agent").option("--set <items...>", "Config overrides (key=value)").option("--collection <slug-or-id>", "REMOVED (#609) — collection access is managed separately; see error").action(async (agent, functionName, opts) => {
+      if (opts.collection) {
+        throw new CLIError("`--collection` was removed; collection access is managed separately: " + "`martha collections grant <collection> --to agent:<id>`.", 4 /* Validation */);
+      }
       const ctx = getCtx();
       const body = {
         function_name: functionName
@@ -13764,36 +13764,29 @@ var agentsConfig = {
       if (opts.set) {
         body.config_overrides = parseSetFlags(opts.set);
       }
-      if (opts.collection) {
-        body.collection_id = await resolveCollectionIdForGrant(ctx, opts.collection);
-      }
       const result = await ctx.api.post(`${API_PATH}/${encodeURIComponent(agent)}/functions`, body);
       if (isJson()) {
         console.log(JSON.stringify(result, null, 2));
         return;
       }
-      const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
-      console.log(`Added function '${functionName}' to agent '${agent}'${scopeLabel}`);
+      console.log(`Added function '${functionName}' to agent '${agent}'`);
     });
-    parentCmd.command("remove-function <agent> <functionName>").description("Remove a function from an agent").option("--collection <slug-or-id>", "Revoke just the given collection scope (#372 PR2). " + "Omit to revoke the root grant (collection_id IS NULL).").action(async (agent, functionName, opts) => {
-      const ctx = getCtx();
-      let endpoint = `${API_PATH}/${encodeURIComponent(agent)}/functions/${encodeURIComponent(functionName)}`;
+    parentCmd.command("remove-function <agent> <functionName>").description("Remove a function from an agent").option("--collection <slug-or-id>", "REMOVED (#609) — collection access is managed separately; see error").action(async (agent, functionName, opts) => {
       if (opts.collection) {
-        const collId = await resolveCollectionIdForGrant(ctx, opts.collection);
-        endpoint += `?collection_id=${encodeURIComponent(collId)}`;
+        throw new CLIError("`--collection` was removed; collection access is managed separately: " + "`martha collections revoke <collection> --to agent:<id>`.", 4 /* Validation */);
       }
+      const ctx = getCtx();
+      const endpoint = `${API_PATH}/${encodeURIComponent(agent)}/functions/${encodeURIComponent(functionName)}`;
       await ctx.api.del(endpoint);
       if (isJson()) {
         console.log(JSON.stringify({
           agent,
           function_name: functionName,
-          collection: opts.collection ?? null,
           removed: true
         }));
         return;
       }
-      const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
-      console.log(`Removed function '${functionName}' from agent '${agent}'${scopeLabel}`);
+      console.log(`Removed function '${functionName}' from agent '${agent}'`);
     });
     parentCmd.command("provision-auth <agent>").description("Provision, switch, or rotate agent auth credentials").requiredOption("--method <method>", "Auth method: service-account or api-key").action(async (agent, opts) => {
       const ctx = getCtx();
@@ -13875,6 +13868,57 @@ 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)}`;
@@ -17051,7 +17095,10 @@ ${clients.length} client(s)`));
     }
     console.log(`Deleted client '${nameOrId}'`);
   });
-  cmd.command("grant <clientNameOrId> <type> <defName>").description("Grant a client access to a function, workflow, or agent").option("--config <items...>", "Config overrides (key=value, functions/agents only)").option("--collection <slug-or-id>", "Scope the grant to one collection (function grants only; #372 PR2)").action(async (clientNameOrId, type, defName, opts) => {
+  cmd.command("grant <clientNameOrId> <type> <defName>").description("Grant a client access to a function, workflow, or agent").option("--config <items...>", "Config overrides (key=value, functions/agents only)").option("--collection <slug-or-id>", "REMOVED (#609) — collection access is managed separately; see error").action(async (clientNameOrId, type, defName, opts) => {
+    if (opts.collection) {
+      throw new CLIError("`--collection` was removed; collection access is managed separately: " + "`martha collections grant <collection> --to client:<id>`.", 4 /* Validation */);
+    }
     if (!VALID_TYPES.has(type)) {
       throw new CLIError(`Invalid type: '${type}'. Must be function, workflow, or agent.`, 4 /* Validation */);
     }
@@ -17079,30 +17126,23 @@ ${clients.length} client(s)`));
       }
       body.config_overrides = parseSetFlags(opts.config);
     }
-    if (opts.collection) {
-      if (accessType !== "function") {
-        throw new CLIError("--collection only applies to function grants (#372 PR2).", 4 /* Validation */);
-      }
-      body.collection_id = await resolveCollectionIdForGrant(ctx, opts.collection);
-    }
     const result = await ctx.api.post(endpoint, body);
     if (isJson()) {
       console.log(JSON.stringify(result, null, 2));
       return;
     }
-    const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
-    console.log(`Granted ${accessType} '${defName}' to client '${clientNameOrId}'${scopeLabel}`);
+    console.log(`Granted ${accessType} '${defName}' to client '${clientNameOrId}'`);
   });
-  cmd.command("revoke <clientNameOrId> <type> <defName>").description("Revoke a client's access to a function, workflow, or agent").option("--collection <slug-or-id>", "Revoke just the given collection scope (function grants only; #372 PR2). " + "Omit to revoke the root grant (collection_id IS NULL).").action(async (clientNameOrId, type, defName, opts) => {
+  cmd.command("revoke <clientNameOrId> <type> <defName>").description("Revoke a client's access to a function, workflow, or agent").option("--collection <slug-or-id>", "REMOVED (#609) — collection access is managed separately; see error").action(async (clientNameOrId, type, defName, opts) => {
+    if (opts.collection) {
+      throw new CLIError("`--collection` was removed; collection access is managed separately: " + "`martha collections revoke <collection> --to client:<id>`.", 4 /* Validation */);
+    }
     if (!VALID_TYPES.has(type)) {
       throw new CLIError(`Invalid type: '${type}'. Must be function, workflow, or agent.`, 4 /* Validation */);
     }
     const accessType = type;
     const ctx = getCtx();
     const clientId = await resolveClientId(ctx, clientNameOrId);
-    if (opts.collection && accessType !== "function") {
-      throw new CLIError("--collection only applies to function grants (#372 PR2).", 4 /* Validation */);
-    }
     let endpoint;
     if (accessType === "agent") {
       endpoint = `${DEFS_API}/clients/${clientId}/agents/${encodeURIComponent(defName)}`;
@@ -17110,10 +17150,6 @@ ${clients.length} client(s)`));
       const defId = await resolveDefinitionId(ctx, accessType, defName);
       const typePlural = `${accessType}s`;
       endpoint = `${DEFS_API}/clients/${clientId}/${typePlural}/${encodeURIComponent(defId)}`;
-      if (opts.collection) {
-        const collId = await resolveCollectionIdForGrant(ctx, opts.collection);
-        endpoint += `?collection_id=${encodeURIComponent(collId)}`;
-      }
     }
     await ctx.api.del(endpoint);
     if (isJson()) {
@@ -17121,13 +17157,11 @@ ${clients.length} client(s)`));
         client: clientNameOrId,
         type: accessType,
         name: defName,
-        collection: opts.collection ?? null,
         revoked: true
       }));
       return;
     }
-    const scopeLabel = opts.collection ? ` (scope: ${opts.collection})` : "";
-    console.log(`Revoked ${accessType} '${defName}' from client '${clientNameOrId}'${scopeLabel}`);
+    console.log(`Revoked ${accessType} '${defName}' from client '${clientNameOrId}'`);
   });
   const embed = cmd.command("embed").description("Create, configure, and test embeddable chat clients");
   function addEmbedConfigOptions(command) {
@@ -18396,6 +18430,25 @@ function registerPolicyCommands(program2) {
 // src/commands/authz.ts
 init_errors();
 
+// src/lib/collections.ts
+init_errors();
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+async function resolveCollectionIdForGrant(ctx, ref) {
+  if (UUID_RE.test(ref)) {
+    return ref;
+  }
+  const all = await ctx.api.get("/api/admin/collections", {
+    params: { active_only: "false" }
+  });
+  const bySlug = all.find((c) => c.slug === ref);
+  if (bySlug)
+    return bySlug.id;
+  const byName = all.find((c) => c.name === ref);
+  if (byName)
+    return byName.id;
+  throw new CLIError(`Collection '${ref}' not found (tried UUID, slug, and name).`, 3 /* NotFound */, "Run `martha documents collections --tree` to see available collections.");
+}
+
 // src/lib/authz.ts
 init_errors();
 var EX_UNAVAILABLE = 69;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/martha-cli",
-  "version": "0.18.0",
+  "version": "0.20.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