@aiaiai-pt/martha-cli 0.9.1 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https
 
 ## [Unreleased]
 
+## [0.10.0] — 2026-06-10
+
+### Added — #540 Phase 2.0/2.1 chat copilot + task operator
+- `martha init --agent` provisions a personal **chat copilot** alongside the run-as bootstrap: a `cloud` agent (no extra credentials) linked to your client, with the intent's tools granted to the **agent** surface (where agent grants fire in chat). `--agent-name` names it; `--model` overrides the model (defaults to the platform default). Persists `default_agent` to the profile.
+- `martha chat` now defaults to your bootstrapped client + copilot so its tools work out of the box; `--agent <name>` selects a specific copilot.
+- **Task operator**: with the `tasks` intent, the copilot can `create_task` / `list_tasks` / `get_task` — tasks run on Martha's task pipeline and are scoped to the copilot's own tasks. (Backend platform functions; surfaced through chat.)
+
 ## [0.9.1] — 2026-06-10
 
 ### Fixed

package/dist/index.js

@@ -10295,6 +10295,33 @@ async function statusCommand(ctx) {
 init_token_store();
 import { createServer } from "node:http";
 import { randomBytes, createHash } from "node:crypto";
+
+// src/lib/browser.ts
+async function openBrowser(url) {
+  const { execFile } = await import("node:child_process");
+  const { platform } = await import("node:os");
+  const os3 = platform();
+  return new Promise((resolve, reject) => {
+    if (os3 === "win32") {
+      execFile("cmd", ["/c", "start", "", url], (err) => {
+        if (err)
+          reject(err);
+        else
+          resolve();
+      });
+    } else {
+      const cmd = os3 === "darwin" ? "open" : "xdg-open";
+      execFile(cmd, [url], (err) => {
+        if (err)
+          reject(err);
+        else
+          resolve();
+      });
+    }
+  });
+}
+
+// src/lib/auth/oidc.ts
 function generateCodeVerifier() {
   return randomBytes(32).toString("base64url");
 }
@@ -10413,29 +10440,6 @@ function waitForAuthCode(opts) {
     }, timeoutMs);
   });
 }
-async function openBrowser(url) {
-  const { execFile } = await import("node:child_process");
-  const { platform } = await import("node:os");
-  const os3 = platform();
-  return new Promise((resolve, reject) => {
-    if (os3 === "win32") {
-      execFile("cmd", ["/c", "start", "", url], (err) => {
-        if (err)
-          reject(err);
-        else
-          resolve();
-      });
-    } else {
-      const cmd = os3 === "darwin" ? "open" : "xdg-open";
-      execFile(cmd, [url], (err) => {
-        if (err)
-          reject(err);
-        else
-          resolve();
-      });
-    }
-  });
-}
 async function exchangeCode(opts) {
   const tokenUrl = `${opts.keycloakUrl}/realms/${opts.realm}/protocol/openid-connect/token`;
   const body = new URLSearchParams({
@@ -10817,6 +10821,28 @@ async function confirm(message) {
     });
   });
 }
+async function promptSecret(message) {
+  if (!process.stdin.isTTY)
+    return;
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stderr,
+    terminal: true
+  });
+  const muted = rl;
+  const original = muted._writeToOutput?.bind(rl);
+  process.stderr.write(`${message}: `);
+  muted._writeToOutput = () => {};
+  return new Promise((resolve) => {
+    rl.question("", (answer) => {
+      muted._writeToOutput = original;
+      rl.close();
+      process.stderr.write(`
+`);
+      resolve(answer);
+    });
+  });
+}
 
 // src/commands/definitions.ts
 init_errors();
@@ -11051,7 +11077,7 @@ import { createInterface as createInterface2 } from "node:readline";
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.9.1";
+var CLI_VERSION = "0.14.0";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -11204,8 +11230,13 @@ async function sendMessage(ctx, sessionId, message, opts = {}) {
     signal: opts.signal,
     timeout: opts.timeoutMs ?? DEFAULT_CHAT_TIMEOUT_MS
   };
-  if (opts.clientId) {
-    reqOpts.params = { selected_client: opts.clientId };
+  if (opts.clientId || opts.agentName) {
+    const params = {};
+    if (opts.clientId)
+      params.selected_client = opts.clientId;
+    if (opts.agentName)
+      params.selected_agent = opts.agentName;
+    reqOpts.params = params;
   }
   const res = await ctx.api.postRaw(`/api/chat/${encodeURIComponent(sessionId)}`, { content: message }, reqOpts);
   const contentType = res.headers.get("content-type") ?? "";
@@ -11375,7 +11406,7 @@ async function showHistoryPicker(ctx, rl) {
   }
   return data.items[idx].session_id;
 }
-async function runRepl(ctx, initialSessionId, clientId, showTools, timeoutMs) {
+async function runRepl(ctx, initialSessionId, clientId, agentName, showTools, timeoutMs) {
   let sessionId = initialSessionId;
   process.stderr.write(source_default.dim(`martha v${CLI_VERSION} | session: ${sessionId.slice(0, 8)}...
 `));
@@ -11483,7 +11514,8 @@ async function runRepl(ctx, initialSessionId, clientId, showTools, timeoutMs) {
         onClear: showTools ? () => process.stderr.write(source_default.dim(`  --- tool iteration ---
 `)) : undefined,
         signal: activeAbort.signal,
-        clientId
+        clientId,
+        agentName
       });
       if (!result.aborted) {
         process.stdout.write(`
@@ -11511,7 +11543,7 @@ Error: ${err instanceof Error ? err.message : String(err)}
   process.stderr.write(`
 `);
 }
-async function runOneShot(ctx, sessionId, message, isJson, clientId, showTools, timeoutMs) {
+async function runOneShot(ctx, sessionId, message, isJson, clientId, agentName, showTools, timeoutMs) {
   const toolCalls = [];
   function recordToolStatus(data) {
     try {
@@ -11533,6 +11565,7 @@ async function runOneShot(ctx, sessionId, message, isJson, clientId, showTools,
   }
   const { response } = await sendMessage(ctx, sessionId, message, {
     clientId,
+    agentName,
     timeoutMs,
     onToolStatus: isJson ? recordToolStatus : showTools ? (data) => {
       recordToolStatus(data);
@@ -11557,7 +11590,7 @@ async function runOneShot(ctx, sessionId, message, isJson, clientId, showTools,
   }
 }
 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("--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("--timeout <seconds>", "Per-message HTTP timeout in seconds (default: 600)").action(async (opts) => {
     const ctx = createContext({
       profileOverride: program2.opts().profile,
       verbose: program2.opts().verbose
@@ -11580,6 +11613,10 @@ function registerChatCommand(program2) {
         clientId = String(match.id);
       }
     }
+    if (!clientId && ctx.profile.default_client) {
+      clientId = ctx.profile.default_client;
+    }
+    const agentName = opts.agent ?? ctx.profile.default_agent;
     let sessionId;
     if (opts.session) {
       sessionId = opts.session;
@@ -11589,12 +11626,12 @@ function registerChatCommand(program2) {
     const showTools = !!opts.showTools;
     const timeoutMs = opts.timeout ? parseTimeoutSeconds(opts.timeout) * 1000 : undefined;
     if (opts.message) {
-      await runOneShot(ctx, sessionId, opts.message, isJson, clientId, showTools, timeoutMs);
+      await runOneShot(ctx, sessionId, opts.message, isJson, clientId, agentName, showTools, timeoutMs);
     } 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, showTools, timeoutMs);
+      await runRepl(ctx, sessionId, clientId, agentName, showTools, timeoutMs);
     }
   });
 }
@@ -13270,6 +13307,25 @@ function formatConfig(config) {
   const full = parts.join(", ");
   return full.length > 40 ? full.slice(0, 37) + "..." : full;
 }
+function policyView(a) {
+  return {
+    self_grant_enabled: a.self_grant_enabled === true,
+    max_self_grant_scope: a.max_self_grant_scope ?? "none",
+    self_grant_max_pending: a.self_grant_max_pending ?? 5,
+    self_grant_allowlist: a.self_grant_allowlist ?? [],
+    self_grant_collection_roots: a.self_grant_collection_roots ?? []
+  };
+}
+function printPolicy(a) {
+  const enabled = a.self_grant_enabled === true;
+  const allow = a.self_grant_allowlist ?? [];
+  const roots = a.self_grant_collection_roots ?? [];
+  console.log(`  Self-provisioning: ${enabled ? source_default.green("enabled") : source_default.dim("disabled")}`);
+  console.log(`  Scope ceiling:     ${a.max_self_grant_scope ?? "none"}`);
+  console.log(`  Max pending:       ${a.self_grant_max_pending ?? 5}`);
+  console.log(`  Allow-list:        ${allow.length ? allow.join(", ") : source_default.dim("(none — nothing requestable)")}`);
+  console.log(`  Collection roots:  ${roots.length ? roots.join(", ") : source_default.dim("(none)")}`);
+}
 var API_PATH = "/api/admin/definitions/agents";
 var LLM_CONFIG_KEYS = new Set([
   "model",
@@ -13520,6 +13576,70 @@ Usage:
         ].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 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()) {
+          console.log(JSON.stringify(policyView(current), null, 2));
+          return;
+        }
+        console.log(source_default.bold(`Self-provisioning policy: ${agent}
+`));
+        printPolicy(current);
+        return;
+      }
+      if (opts.enable && opts.disable) {
+        throw new CLIError("Cannot use --enable and --disable together.", 4 /* Validation */);
+      }
+      if (opts.scope !== undefined && !["none", "read_only", "read_write"].includes(opts.scope)) {
+        throw new CLIError(`Invalid --scope "${opts.scope}". Use none | read_only | read_write.`, 4 /* Validation */);
+      }
+      const body = {};
+      if (opts.enable)
+        body.self_grant_enabled = true;
+      if (opts.disable)
+        body.self_grant_enabled = false;
+      if (opts.scope !== undefined)
+        body.max_self_grant_scope = opts.scope;
+      if (opts.maxPending !== undefined) {
+        const n = parseInt(opts.maxPending, 10);
+        if (Number.isNaN(n) || n < 0) {
+          throw new CLIError("--max-pending must be a non-negative integer.", 4 /* Validation */);
+        }
+        body.self_grant_max_pending = n;
+      }
+      if (opts.allow?.length || opts.remove?.length) {
+        const refs = new Set(current.self_grant_allowlist ?? []);
+        for (const r of opts.allow ?? []) {
+          if (!r.includes(":")) {
+            throw new CLIError(`Invalid ref "${r}". Expected function:NAME or mcp:integration/name.`, 4 /* Validation */);
+          }
+          refs.add(r);
+        }
+        for (const r of opts.remove ?? [])
+          refs.delete(r);
+        body.self_grant_allowlist = [...refs];
+      }
+      if (opts.collectionRoot?.length || opts.removeCollectionRoot?.length) {
+        const roots = new Set((current.self_grant_collection_roots ?? []).map(String));
+        for (const c of opts.collectionRoot ?? [])
+          roots.add(c);
+        for (const c of opts.removeCollectionRoot ?? [])
+          roots.delete(c);
+        body.self_grant_collection_roots = [...roots];
+      }
+      const updated = await ctx.api.put(path5, body);
+      if (isJson()) {
+        console.log(JSON.stringify(policyView(updated), null, 2));
+        return;
+      }
+      console.log(source_default.bold(`Updated self-provisioning policy: ${agent}
+`));
+      printPolicy(updated);
+    });
   }
 };
 
@@ -17482,6 +17602,154 @@ function registerMCPCommands(program2) {
       });
     }
   });
+  cmd.command("add [target]").description("Connect an MCP server to your copilot in one step: create-or-adopt the " + "connection, discover its tools, and grant access. [target] is a catalog " + "name (e.g. `github`, `linear` — see `mcp catalog`) or an existing " + "connection (id or name); --url adds a custom server. Catalog/OAuth " + "servers need no credential and no --auth-type.").option("--url <serverUrl>", "Create a connection from a direct MCP URL").option("--name <name>", "Connection name when creating (default: derived)").option("--integration <name>", "Integration name when creating", "mcp").option("--auth-type <type>", "Auth type when creating (bearer|api_key|basic)", "bearer").option("--credential-value <value>", "Secret for a new connection ('-' stdin, '@path' file). Prompted if omitted in a TTY.").option("--agent <name>", "Grant to this agent (default: profile.default_agent)").option("--no-agent", "Do not grant the agent surface (chat)").option("--client <id>", "Also grant this client (workflow-node surface)").option("--tools <list>", "Comma-separated allow-list of tool names").option("--disabled", "Create the grant disabled").option("--no-browser", "For OAuth servers: print the consent URL instead of auto-opening it, " + "then poll (use on headless/SSH/CI where you'll open the URL yourself).").option("--yes", "Assume yes for prompts (required in non-TTY)").action(async (connection, opts) => {
+    const ctx = getCtx();
+    const json = isJson();
+    const conn = await resolveOrCreateConnection(ctx, connection, opts);
+    const toolCount = await discoverOrDriveOAuth(ctx, conn, opts, json);
+    const { agent, client } = resolveTargets(opts, ctx.profile);
+    if (!agent && !client) {
+      throw new CLIError("No grant target. Pass --agent <name>, set profile.default_agent, or --client <id>.", 4 /* Validation */);
+    }
+    const config = buildGrantConfig(opts.tools);
+    const enabled = !opts.disabled;
+    const granted = [];
+    if (agent) {
+      await ctx.api.post(`/api/admin/definitions/agents/${encodeURIComponent(agent)}/mcp`, {
+        connection_id: conn.id,
+        enabled,
+        config
+      });
+      granted.push(`agent '${agent}'`);
+    }
+    if (client) {
+      await ctx.api.post(`/api/admin/definitions/clients/${encodeURIComponent(client)}/mcp`, {
+        connection_id: conn.id,
+        enabled,
+        config
+      });
+      granted.push(`client ${client}`);
+    }
+    if (json) {
+      console.log(JSON.stringify({
+        connection_id: conn.id,
+        connection_name: conn.name,
+        tools: toolCount,
+        granted_to: granted,
+        enabled
+      }, null, 2));
+      return;
+    }
+    console.log(source_default.green(`Connected '${conn.name}' — ${toolCount} tool${toolCount === 1 ? "" : "s"}. ` + `Granted to ${granted.join(", ")}${enabled ? "" : " (disabled)"}.`));
+  });
+  cmd.command("catalog").description("Browse Martha's catalog of known MCP servers. Add one by name with " + "`mcp add <name>` — no URL, no credential for OAuth servers.").option("--search <query>", "Filter by name/description").action(async (opts) => {
+    const ctx = getCtx();
+    const qs = opts.search ? `?search=${encodeURIComponent(opts.search)}` : "";
+    const entries = await ctx.api.get(`/api/admin/mcp/catalog${qs}`);
+    if (isJson()) {
+      console.log(JSON.stringify(entries, null, 2));
+      return;
+    }
+    if (!entries.length) {
+      console.log(source_default.dim("No catalog entries match."));
+      return;
+    }
+    for (const e of entries) {
+      const auth = e.auth_mode === "oauth2" ? source_default.dim("(OAuth)") : source_default.dim(`(${e.auth_mode})`);
+      console.log(`  ${source_default.cyan(e.catalog_key)} ${e.display_name} ${auth} ` + `${source_default.dim(e.trust_tier)}`);
+      if (e.description)
+        console.log(source_default.dim(`    ${e.description}`));
+    }
+    console.log(source_default.dim(`
+Add one: martha mcp add <name> --agent <agent>`));
+  });
+  cmd.command("ls").description("List MCP connections granted to an agent (and optionally a client)").option("--agent <name>", "Agent to inspect (default: profile.default_agent)").option("--client <id>", "Also list this client's grants").action(async (opts) => {
+    const ctx = getCtx();
+    const json = isJson();
+    const agent = opts.agent ?? ctx.profile.default_agent;
+    const out = {};
+    if (agent) {
+      out[`agent:${agent}`] = await ctx.api.get(`/api/admin/definitions/agents/${encodeURIComponent(agent)}/mcp`);
+    }
+    if (opts.client) {
+      out[`client:${opts.client}`] = await ctx.api.get(`/api/admin/definitions/clients/${encodeURIComponent(opts.client)}/mcp`);
+    }
+    if (!agent && !opts.client) {
+      throw new CLIError("Nothing to list. Pass --agent, set profile.default_agent, or --client <id>.", 4 /* Validation */);
+    }
+    if (json) {
+      console.log(JSON.stringify(out, null, 2));
+      return;
+    }
+    for (const [scope, grants] of Object.entries(out)) {
+      console.log(source_default.bold(scope));
+      if (!grants.length) {
+        console.log(source_default.dim("  (none)"));
+        continue;
+      }
+      for (const g of grants) {
+        const allow = g.config?.tools?.length;
+        console.log(`  ${source_default.cyan(g.connection_name ?? g.connection_id)}` + `${g.enabled ? "" : source_default.dim(" [disabled]")}` + `${allow ? source_default.dim(` (${allow} tool allow-list)`) : ""}`);
+      }
+    }
+  });
+  cmd.command("grant <connection>").description("Grant an existing connection to an agent and/or client").option("--agent <name>", "Agent (default: profile.default_agent)").option("--no-agent", "Skip the agent surface").option("--client <id>", "Client (workflow-node surface)").option("--tools <list>", "Comma-separated allow-list").action(async (connection, opts) => {
+    const ctx = getCtx();
+    const conn = await resolveConnection(ctx, connection);
+    const { agent, client } = resolveTargets(opts, ctx.profile);
+    if (!agent && !client) {
+      throw new CLIError("No grant target (--agent / default_agent / --client).", 4 /* Validation */);
+    }
+    const config = buildGrantConfig(opts.tools);
+    if (agent)
+      await ctx.api.post(`/api/admin/definitions/agents/${encodeURIComponent(agent)}/mcp`, {
+        connection_id: conn.id,
+        enabled: true,
+        config
+      });
+    if (client)
+      await ctx.api.post(`/api/admin/definitions/clients/${encodeURIComponent(client)}/mcp`, {
+        connection_id: conn.id,
+        enabled: true,
+        config
+      });
+    if (isJson())
+      console.log(JSON.stringify({ connection_id: conn.id, granted: true }, null, 2));
+    else
+      console.log(source_default.green(`Granted '${conn.name}'.`));
+  });
+  cmd.command("revoke <connection>").description("Revoke a connection from an agent and/or client").option("--agent <name>", "Agent (default: profile.default_agent)").option("--no-agent", "Skip the agent surface").option("--client <id>", "Client").action(async (connection, opts) => {
+    const ctx = getCtx();
+    const conn = await resolveConnection(ctx, connection);
+    const { agent, client } = resolveTargets(opts, ctx.profile);
+    if (agent)
+      await ctx.api.del(`/api/admin/definitions/agents/${encodeURIComponent(agent)}/mcp/${conn.id}`);
+    if (client)
+      await ctx.api.del(`/api/admin/definitions/clients/${encodeURIComponent(client)}/mcp/${conn.id}`);
+    if (isJson())
+      console.log(JSON.stringify({ connection_id: conn.id, revoked: true }, null, 2));
+    else
+      console.log(source_default.green(`Revoked '${conn.name}'.`));
+  });
+  cmd.command("disable <connection>").description("Disable a grant without revoking it (keeps the row, enabled=false)").option("--agent <name>", "Agent (default: profile.default_agent)").option("--no-agent", "Skip the agent surface").option("--client <id>", "Client").action(async (connection, opts) => {
+    const ctx = getCtx();
+    const conn = await resolveConnection(ctx, connection);
+    const { agent, client } = resolveTargets(opts, ctx.profile);
+    if (agent)
+      await ctx.api.post(`/api/admin/definitions/agents/${encodeURIComponent(agent)}/mcp`, {
+        connection_id: conn.id,
+        enabled: false
+      });
+    if (client)
+      await ctx.api.post(`/api/admin/definitions/clients/${encodeURIComponent(client)}/mcp`, {
+        connection_id: conn.id,
+        enabled: false
+      });
+    if (isJson())
+      console.log(JSON.stringify({ connection_id: conn.id, enabled: false }, null, 2));
+    else
+      console.log(source_default.green(`Disabled '${conn.name}'.`));
+  });
 }
 function mcpOAuthAuthorizationUrl(err) {
   if (!(err instanceof MarthaAPIError) || err.status !== 428)
@@ -17497,6 +17765,68 @@ function mcpOAuthAuthorizationUrl(err) {
     return null;
   return typeof nested.authorization_url === "string" ? nested.authorization_url : null;
 }
+async function discoverOrDriveOAuth(ctx, conn, opts, json) {
+  try {
+    const disc = await ctx.api.post("/api/admin/mcp/discover", {
+      connection_id: conn.id
+    });
+    return disc.tools?.length ?? 0;
+  } catch (err) {
+    const authUrl = mcpOAuthAuthorizationUrl(err);
+    if (!authUrl) {
+      throw new CLIError(`Could not reach MCP server for connection '${conn.name}'.`, 1 /* Error */, err instanceof Error ? err.message : undefined);
+    }
+    await driveMcpOAuth(ctx, conn, authUrl, opts, json);
+    const disc = await ctx.api.post("/api/admin/mcp/discover", {
+      connection_id: conn.id
+    });
+    return disc.tools?.length ?? 0;
+  }
+}
+async function driveMcpOAuth(ctx, conn, authUrl, opts, json) {
+  const wantsBrowser = opts.browser !== false;
+  const interactive = process.stdin.isTTY || !wantsBrowser;
+  if (!interactive) {
+    throw new CLIError(`Connection '${conn.name}' needs OAuth, which requires interactive browser consent.`, 4 /* Validation */, `Open this URL in a browser to authorize:
+  ${authUrl}
+
+` + `Then re-run 'martha mcp add ${conn.name} ...' to adopt the now-authorized connection. ` + `In CI, pass --no-browser to print the URL and poll, or pre-create the ` + `connection in the admin UI (Integrations → Connections).`);
+  }
+  const log = (msg) => process.stderr.write(`${msg}
+`);
+  log(source_default.bold(`Authorize '${conn.name}' in your browser:`));
+  log(`  ${authUrl}`);
+  if (process.stdin.isTTY && wantsBrowser) {
+    openBrowser(authUrl).catch(() => {
+      log(source_default.dim("(couldn't open a browser automatically — open the URL above)"));
+    });
+  }
+  log(source_default.dim("Waiting for authorization to complete…"));
+  await pollConnectionActive(ctx, conn.id);
+  if (!json)
+    log(source_default.green("Authorized."));
+}
+async function pollConnectionActive(ctx, connectionId) {
+  const intervalMs = positiveIntEnv("MARTHA_MCP_OAUTH_POLL_MS", 2000);
+  const timeoutMs = positiveIntEnv("MARTHA_MCP_OAUTH_TIMEOUT_MS", 180000);
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    const conn = await ctx.api.get(`/api/admin/connections/${encodeURIComponent(connectionId)}`).catch(() => {
+      return;
+    });
+    if (conn?.status === "active")
+      return;
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+  throw new CLIError(`Timed out waiting for OAuth authorization (${Math.round(timeoutMs / 1000)}s).`, 1 /* Error */, "The browser consent may not have completed. Re-run to try again, or check " + "the connection status in the admin UI.");
+}
+function positiveIntEnv(name, fallback) {
+  const raw = process.env[name];
+  if (!raw)
+    return fallback;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
 function buildLocatorBody(opts) {
   const body = {};
   if (opts.url)
@@ -17564,6 +17894,251 @@ function extractMCPOutput(status) {
   }
   return output;
 }
+function resolveTargets(opts, profile) {
+  let agent;
+  if (opts.agent === false)
+    agent = undefined;
+  else if (typeof opts.agent === "string")
+    agent = opts.agent;
+  else
+    agent = profile.default_agent;
+  return { agent, client: opts.client };
+}
+function buildGrantConfig(tools) {
+  if (!tools)
+    return;
+  const list = tools.split(",").map((t) => t.trim()).filter(Boolean);
+  return list.length ? { tools: list } : undefined;
+}
+async function findConnection(ctx, idOrName) {
+  const conns = await ctx.api.get("/api/admin/connections");
+  const byId = conns.find((c) => c.id === idOrName);
+  if (byId)
+    return byId;
+  const byName = conns.filter((c) => c.name === idOrName);
+  if (byName.length === 1)
+    return byName[0];
+  if (byName.length > 1) {
+    throw new CLIError(`Multiple connections named '${idOrName}'; pass the connection id instead.`, 4 /* Validation */);
+  }
+  return null;
+}
+async function resolveConnection(ctx, idOrName) {
+  const conn = await findConnection(ctx, idOrName);
+  if (!conn) {
+    throw new CLIError(`Connection '${idOrName}' not found.`, 3 /* NotFound */);
+  }
+  return conn;
+}
+async function lookupCatalogEntry(ctx, key) {
+  const entries = await ctx.api.get(`/api/admin/mcp/catalog?search=${encodeURIComponent(key)}`).catch(() => []);
+  return entries.find((e) => e.catalog_key === key) ?? null;
+}
+async function resolveOrCreateConnection(ctx, positional, opts) {
+  if (positional) {
+    const existing = await findConnection(ctx, positional);
+    if (existing)
+      return existing;
+    const entry = await lookupCatalogEntry(ctx, positional);
+    if (entry) {
+      return createConnectionFromSpec(ctx, {
+        name: opts.name ?? entry.catalog_key,
+        integration: opts.integration,
+        serverUrl: entry.server_url,
+        authType: entry.auth_mode,
+        scopes: entry.default_scopes ?? undefined
+      }, opts);
+    }
+    throw new CLIError(`'${positional}' is not a known connection or catalog entry.`, 3 /* NotFound */, "Pass --url to add a custom MCP server, or run `martha mcp catalog` to see known servers.");
+  }
+  if (!opts.url) {
+    throw new CLIError("Provide a catalog name, an existing connection (id or name), or --url.", 4 /* Validation */);
+  }
+  return createConnectionFromSpec(ctx, {
+    name: opts.name ?? deriveConnectionName(opts.url),
+    integration: opts.integration,
+    serverUrl: opts.url,
+    authType: opts.authType
+  }, opts);
+}
+async function createConnectionFromSpec(ctx, spec, opts) {
+  const existing = (await ctx.api.get("/api/admin/connections")).filter((c) => c.name === spec.name);
+  if (existing.length === 1)
+    return existing[0];
+  const body = {
+    integration_name: spec.integration,
+    name: spec.name,
+    auth_type: spec.authType,
+    config: { server_url: spec.serverUrl },
+    scope: "tenant",
+    is_default: true
+  };
+  if (spec.authType === "oauth2") {
+    if (spec.scopes?.length)
+      body.oauth_config = { scopes: spec.scopes };
+    return ctx.api.post("/api/admin/connections", body);
+  }
+  let credential = await resolveCredentialFlag(opts.credentialValue);
+  if (!credential) {
+    credential = await promptSecret(`${spec.authType} secret for '${spec.name}'`);
+  }
+  if (!credential) {
+    throw new CLIError("A credential is required to create a connection (use --credential-value, '-' for stdin, '@path', or run in a TTY to be prompted).", 4 /* Validation */);
+  }
+  body.credential_value = credential;
+  return ctx.api.post("/api/admin/connections", body);
+}
+function deriveConnectionName(url) {
+  try {
+    const host = new URL(url).hostname.replace(/^www\./, "");
+    return `mcp-${host}`.toLowerCase();
+  } catch {
+    return `mcp-${Date.now().toString(36)}`;
+  }
+}
+async function resolveCredentialFlag(value) {
+  if (!value)
+    return;
+  if (value === "-") {
+    const chunks = [];
+    for await (const c of process.stdin)
+      chunks.push(c);
+    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();
+  }
+  return value;
+}
+
+// src/commands/policy.ts
+init_errors();
+var ACTIONS = ["allow", "require_approval", "block"];
+var KINDS = ["risk_tag", "risk_level", "capability"];
+var SCOPES = ["any", "agent", "client"];
+var truncate4 = (s, n) => s.length > n ? s.slice(0, n - 1) + "…" : s;
+function assertOneOf(value, allowed, flag) {
+  if (!allowed.includes(value)) {
+    throw new CLIError(`${flag} must be one of: ${allowed.join(", ")}`, 4 /* Validation */);
+  }
+}
+function registerPolicyCommands(program2) {
+  const cmd = program2.command("policy").description("Manage the tenant's invoke-time capability policy");
+  function getCtx() {
+    const ctx = createContext({
+      profileOverride: program2.opts().profile,
+      verbose: program2.opts().verbose
+    });
+    if (program2.opts().apiUrl)
+      ctx.profile.api_url = program2.opts().apiUrl;
+    return ctx;
+  }
+  const isJson = () => !!program2.opts().json;
+  cmd.command("show").description("Show the current policy: settings + rules").action(async () => {
+    const ctx = getCtx();
+    const cfg = await ctx.api.get("/api/admin/policy");
+    if (isJson()) {
+      console.log(JSON.stringify(cfg, null, 2));
+      return;
+    }
+    const s = cfg.settings;
+    console.log(source_default.bold("Policy settings"));
+    console.log(source_default.dim("-".repeat(40)));
+    console.log(`${source_default.cyan("Default action:")}  ${s.default_action}` + source_default.dim("   (applied when no rule matches)"));
+    const sd = s.safe_default_enabled ? source_default.yellow("on") : source_default.dim("off");
+    console.log(`${source_default.cyan("Safe-default:")}    ${sd}`);
+    console.log(source_default.dim(`   bundle -> require_approval for: ${cfg.safe_default_tags.join(", ")}`));
+    console.log();
+    console.log(source_default.bold(`Rules (${cfg.rules.length})`));
+    console.log(source_default.dim("-".repeat(40)));
+    if (cfg.rules.length === 0) {
+      console.log(source_default.dim("No explicit rules — fully opt-in."));
+      return;
+    }
+    const columns = [
+      {
+        header: "ID",
+        get: (r) => String(r.id ?? "").slice(0, 8)
+      },
+      {
+        header: "KIND",
+        get: (r) => String(r.match_kind ?? "-")
+      },
+      {
+        header: "VALUE",
+        get: (r) => truncate4(String(r.match_value ?? "-"), 28)
+      },
+      {
+        header: "SCOPE",
+        get: (r) => String(r.principal_scope ?? "any")
+      },
+      {
+        header: "ACTION",
+        get: (r) => String(r.action ?? "-")
+      }
+    ];
+    const widths = columns.map((c) => Math.max(c.header.length, ...cfg.rules.map((r) => c.get(r).length)));
+    const head = columns.map((c, i) => c.header.padEnd(widths[i])).join("  ");
+    console.log(source_default.bold(head));
+    console.log(source_default.dim("-".repeat(head.length)));
+    for (const r of cfg.rules) {
+      console.log(columns.map((c, i) => c.get(r).padEnd(widths[i])).join("  "));
+    }
+  });
+  cmd.command("set-default <action>").description(`Set the opt-in default action (${ACTIONS.join("|")})`).action(async (action) => {
+    assertOneOf(action, ACTIONS, "action");
+    const ctx = getCtx();
+    const res = await ctx.api.put("/api/admin/policy/settings", { default_action: action });
+    if (isJson()) {
+      console.log(JSON.stringify(res, null, 2));
+      return;
+    }
+    console.log(`Default action set to ${source_default.cyan(action)}.`);
+  });
+  cmd.command("safe-default <state>").description("Turn the safe-default bundle on|off").action(async (state) => {
+    const normalized = state.toLowerCase();
+    if (!["on", "off", "true", "false"].includes(normalized)) {
+      throw new CLIError("state must be on|off", 4 /* Validation */);
+    }
+    const enabled = normalized === "on" || normalized === "true";
+    const ctx = getCtx();
+    const res = await ctx.api.put("/api/admin/policy/settings", { safe_default_enabled: enabled });
+    if (isJson()) {
+      console.log(JSON.stringify(res, null, 2));
+      return;
+    }
+    console.log(`Safe-default bundle ${enabled ? source_default.yellow("enabled") : source_default.dim("disabled")}.`);
+  });
+  const rule = cmd.command("rule").description("Manage explicit policy rules");
+  rule.command("add").description("Create or update a rule").requiredOption(`--kind <kind>`, `Match kind (${KINDS.join("|")})`).requiredOption("--value <value>", "Match value (a risk tag, level, or capability ref)").requiredOption(`--action <action>`, `Action (${ACTIONS.join("|")})`).option(`--scope <scope>`, `Principal scope (${SCOPES.join("|")})`, "any").option("--note <text>", "Optional human note").action(async (opts) => {
+    assertOneOf(opts.kind, KINDS, "--kind");
+    assertOneOf(opts.action, ACTIONS, "--action");
+    assertOneOf(opts.scope, SCOPES, "--scope");
+    const ctx = getCtx();
+    const res = await ctx.api.post("/api/admin/policy/rules", {
+      match_kind: opts.kind,
+      match_value: opts.value,
+      action: opts.action,
+      principal_scope: opts.scope,
+      ...opts.note ? { note: opts.note } : {}
+    });
+    if (isJson()) {
+      console.log(JSON.stringify(res, null, 2));
+      return;
+    }
+    console.log(`Rule ${source_default.dim(String(res.id).slice(0, 8))}: ` + `${opts.kind}=${source_default.cyan(opts.value)} (${opts.scope}) -> ${source_default.cyan(opts.action)}`);
+  });
+  rule.command("rm <id>").description("Delete a rule by id").action(async (id) => {
+    const ctx = getCtx();
+    await ctx.api.del(`/api/admin/policy/rules/${encodeURIComponent(id)}`);
+    if (isJson()) {
+      console.log(JSON.stringify({ deleted: id }, null, 2));
+      return;
+    }
+    console.log(`Deleted rule ${id}.`);
+  });
+}
 
 // src/commands/init.ts
 import readline from "node:readline/promises";
@@ -17732,26 +18307,36 @@ Provision an access principal now so calls just work?`, true);
   if (intents.length === 0 && workflows.length === 0 && functions.length === 0) {
     throw new CLIError("Nothing to grant: declare at least one --intent (rag/documents/workflows/custom) or a --workflow/--function.", 4 /* Validation */);
   }
+  let wantAgent = mode === "human" && !!opts.agent;
+  if (mode === "human" && !opts.agent && interactive) {
+    wantAgent = await askYesNo(`
+  Also set up a chat copilot you can talk to (martha chat)?`, true);
+  }
   const ctx = createContext({ profileOverride: profileName });
   if (opts.apiUrl)
     ctx.profile.api_url = opts.apiUrl;
   await ensureAuthenticated(ctx, interactive, jsonMode);
   if (!jsonMode) {
     console.log();
-    console.log(source_default.dim(`  Provisioning ${mode === "integration" ? "an integration service account" : "your access principal"}…`));
+    console.log(source_default.dim(`  Provisioning ${mode === "integration" ? "an integration service account" : "your access principal"}${wantAgent ? " + copilot" : ""}…`));
   }
   const body = {
     mode,
     intents,
     workflows,
     functions,
-    ...opts.label ? { label: opts.label } : {}
+    ...opts.label ? { label: opts.label } : {},
+    ...wantAgent ? { agent: true } : {},
+    ...wantAgent && opts.agentName ? { agent_name: opts.agentName } : {},
+    ...wantAgent && opts.model ? { model: opts.model } : {}
   };
   const resp = await ctx.api.post("/api/admin/definitions/principals/bootstrap", body);
   if (mode === "human" && resp.client_key) {
     const cfg = loadConfig();
     if (cfg.profiles[profileName]) {
       cfg.profiles[profileName].default_client = resp.client_key;
+      if (resp.agent)
+        cfg.profiles[profileName].default_agent = resp.agent.name;
       saveConfig(cfg);
     }
   }
@@ -17799,6 +18384,15 @@ function printBootstrapResult(resp, profileName) {
   for (const s of resp.skipped) {
     console.log(source_default.yellow(`  Skipped ${s.name} — ${s.reason}`));
   }
+  if (resp.agent) {
+    const a = resp.agent;
+    console.log();
+    const averb = a.adopted ? "Using existing" : "Created";
+    console.log(source_default.green(`  ${averb} copilot ${source_default.bold(a.name)}.`));
+    if (a.granted_functions.length > 0) {
+      console.log(`    Copilot tools: ${source_default.cyan(a.granted_functions.join(", "))}`);
+    }
+  }
   if (resp.service_account) {
     const sa = resp.service_account;
     console.log();
@@ -17813,6 +18407,9 @@ function printBootstrapResult(resp, profileName) {
     console.log(source_default.dim(`  Profile ${source_default.cyan(profileName)} will now run as this client.`));
     console.log();
     console.log(source_default.dim("  Next:"));
+    if (resp.agent) {
+      console.log(source_default.dim('    martha chat "what can you do?"'));
+    }
     console.log(source_default.dim("    martha workflows list"));
     console.log(source_default.dim("    martha workflows execute <name> --inputs '{}'"));
   }
@@ -17869,7 +18466,7 @@ async function askIntents() {
   return parseIntents(raw);
 }
 function registerInitCommand(program2) {
-  program2.command("init").description("Create or update a profile, and optionally bootstrap an access principal").option("--preset <name>", "Preset: cloud or local", "cloud").option("--name <name>", "Profile name (defaults to preset name)").option("--force", "Overwrite an existing profile").option("--api-url <url>", "Override the API URL").option("--keycloak-url <url>", "Override the Keycloak URL").option("--keycloak-realm <realm>", "Override the Keycloak realm").option("--no-interactive", "Skip prompts; use defaults / overrides only").option("--bootstrap", "Provision an intent-scoped principal + grants after saving the profile").option("--mode <mode>", "Bootstrap mode: 'human' (your own client) or 'integration' (service account)").option("--intent <intents...>", "Usage buckets to grant: rag, documents, workflows, custom").option("--workflow <names...>", "Workflow name(s) to grant (workflows/custom intent)").option("--function <names...>", "Extra function name(s) to grant (custom intent)").option("--label <name>", "Integration mode: label for the SA client id").option("--yes", "Acknowledge non-interactive bootstrap side effects").action(async (opts, command) => {
+  program2.command("init").description("Create or update a profile, and optionally bootstrap an access principal").option("--preset <name>", "Preset: cloud or local", "cloud").option("--name <name>", "Profile name (defaults to preset name)").option("--force", "Overwrite an existing profile").option("--api-url <url>", "Override the API URL").option("--keycloak-url <url>", "Override the Keycloak URL").option("--keycloak-realm <realm>", "Override the Keycloak realm").option("--no-interactive", "Skip prompts; use defaults / overrides only").option("--bootstrap", "Provision an intent-scoped principal + grants after saving the profile").option("--mode <mode>", "Bootstrap mode: 'human' (your own client) or 'integration' (service account)").option("--intent <intents...>", "Usage buckets to grant: rag, documents, workflows, custom").option("--workflow <names...>", "Workflow name(s) to grant (workflows/custom intent)").option("--function <names...>", "Extra function name(s) to grant (custom intent)").option("--label <name>", "Integration mode: label for the SA client id").option("--agent", "Also provision a personal chat copilot (human mode) and set it as the default").option("--agent-name <name>", "Copilot agent name (defaults to copilot-{user})").option("--model <id>", "Copilot LLM model id (defaults to the platform default)").option("--yes", "Acknowledge non-interactive bootstrap side effects").action(async (opts, command) => {
     const globals = command.parent?.opts() ?? {};
     await initCommand({ ...opts, json: !!globals.json });
   });
@@ -18212,6 +18809,7 @@ registerClientCommands(program2);
 registerModelsCommand(program2);
 registerSessionCommands(program2);
 registerMCPCommands(program2);
+registerPolicyCommands(program2);
 registerInitCommand(program2);
 registerDoctorCommand(program2);
 registerSkillCommand(program2);

package/package.json

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