@aiaiai-pt/martha-cli 0.55.0 → 0.57.0

package/CHANGELOG.md

@@ -2,6 +2,99 @@
 
 All notable changes to `@aiaiai-pt/martha-cli`. Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This project adheres to semver — `0.x` releases may include breaking changes between minor versions.
 
+## [0.57.0] — 2026-08-03
+
+### Fixed — `bootstrap --mode agent` produced an agent that could not do anything
+
+Provisioned from scratch, the agent came back `✓ ready` and then, asked a
+question in a channel, invented shell commands and fabricated four collections
+that do not exist. Three separate holes, all of them ours:
+
+- **No tools.** `--intents rag` granted the CLIENT functions and never the
+  agent's, because agent mode was composed client-side while the server's own
+  `agent` block — adopt-or-create with chat takeover, bind to the principal,
+  grant the intent's AGENT functions — was gated to human mode. That gate is
+  now open to integration mode (`agent_name` required: a service account is not
+  a person, so the name is never defaulted), and the CLI makes **one** call
+  instead of re-implementing it.
+- **Nothing to read.** Intents grant retrieval *verbs*; the *nouns* are a
+  separate UMS grant. New `--collections <list>` grants the agent read on them
+  by name, slug or id — and when it is omitted, provisioning now says
+  `granted NO collections — its retrieval tools will return nothing`, because
+  "ready" must never mean "ready and blind".
+- **A prompt the harness overrode.** buzz-acp tells agents they can run shell
+  commands; our default said only "don't emit `buzz messages send`". The
+  prompt for a newly created agent now states it has no shell and must never
+  write output it did not receive from a tool.
+
+Also: the agent's system prompt applies to sessions created *after* it — an
+adapter holding open sessions keeps the old one until restarted.
+
+### Server
+
+`POST /principals/bootstrap` accepts `agent` + `agent_name` in integration
+mode, plus `agent_system_prompt` (applied only on create — never overwrites a
+persona someone has edited) and `collections`. The response's `agent` block
+gains `granted_collections`. Collection grants are issued after commit as UMS
+`application` grantees with `agent_<uuid>` ids — UMS has no `agent` grantee
+type and 422s the bare uuid, which is invisible unless you read the skip list.
+
+## [0.56.0] — 2026-08-03
+
+### Changed — Martha agents follow the conversation by default
+
+The harness definition now pins `BUZZ_ACP_SUBSCRIBE=all` with
+`BUZZ_ACP_KINDS=9,46010,40007,7`.
+
+Buzz's default is `subscribe=mentions`, which filters every message that does
+not `#p`-tag the agent — so a **DM got no reply**, and neither did a thread
+reply or a follow-up question. The previous release left the pair out of the
+definition on the reasoning that overriding Buzz's default would be
+surprising; the actual result was that every single agent needed both
+variables typed into Edit Agent by hand. Runtime-wide behaviour is exactly
+what a runtime definition is for.
+
+The two values are pinned together because `all` without kinds is a wildcard
+subscription — typing indicators and presence updates arrive as prompts. The
+set is buzz-acp's own mentions-mode set (chat, approval, reminder) plus
+reactions, which `acp-serve` classifies as feedback and answers with silence.
+
+For an agent that should only speak when named, set
+`BUZZ_ACP_SUBSCRIBE=mentions` on that agent — per-agent env overrides the
+definition. Existing agents pick this up after
+`martha channels install-harness buzz --force` and a restart.
+
+## [0.55.2] — 2026-08-03
+
+### Fixed — a baked `MARTHA_PROFILE` is a default, and we didn't say so
+
+0.55.0 let `install-harness --use-profile` put `MARTHA_PROFILE` in the harness
+definition, and the output read as though that bound the Buzz agent to a Martha
+agent. It doesn't: the definition is shared by **every** agent on the Martha
+runtime, so a second Buzz agent would answer as the first one's Martha agent —
+its own name and Nostr key in front of one brain, which is the opposite of what
+a second agent is for.
+
+Nothing to change in the mechanism, which already supports the right model:
+per-agent env (Buzz's Stack A layer 3b) overrides definition env (layer 2b), so
+`MARTHA_PROFILE=<its own profile>` in Edit Agent gives each Buzz agent its own
+Martha agent — still one variable, still no secrets. `install-harness` now says
+this after a successful write, `--use-profile --help` says it, and the guide has
+it as a warning box.
+
+## [0.55.1] — 2026-08-03
+
+### Fixed — `definitions apply` no longer reports success on writes that don't land (#1147)
+
+`kind: Agent` payloads are validated at load time against the server's
+persisted-field set: a wrongly-nested `definition:` wrapper or any unknown
+top-level field now fails with a validation error naming the field and the
+expected level — instead of `updated → vN` while the server silently
+discards the value. `--dry-run` surfaces the same rejection. And applying a
+definition against a soft-deleted target now reactivates it (`is_active:
+true`) instead of reporting `1 unchanged`, unless the local file explicitly
+declares `is_active: false`.
+
 ## [0.55.0] — 2026-08-03
 
 ### Added — a profile can carry the agent's credential, so nothing is typed by hand

package/dist/index.js

@@ -11149,7 +11149,7 @@ init_config();
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.55.0";
+var CLI_VERSION = "0.57.0";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -14584,62 +14584,66 @@ var BOOTSTRAP_PATH = "/api/admin/definitions/principals/bootstrap";
 function parseIntents(raw) {
   return (raw ?? "").split(",").map((s) => s.trim()).filter(Boolean);
 }
+var CHANNEL_AGENT_PROMPT_SUFFIX = `
+
+TOOLS
+You have no shell and no terminal. Your tools are function calls, and they ` + "are the only way you can learn anything. Never write `<bash>`, shell commands, or code " + "fences pretending to run one, and never write output you did not receive from a tool. " + "If a tool returns nothing, say it returned nothing." + `
+
+DELIVERY
+Reply with the message content ONLY — delivery is handled for you. Never ` + "output delivery commands (e.g. `buzz messages send`).";
 async function bootstrapAgentPrincipal(ctx, agent, opts = {}) {
   const A = `${AGENTS_PATH}/${encodeURIComponent(agent)}`;
   const steps = [];
   const warnings = [];
-  let def = null;
+  let existing = null;
   try {
-    def = await ctx.api.get(A);
+    existing = await ctx.api.get(A);
   } catch (e) {
     if (!(e instanceof MarthaAPIError && e.status === 404))
       throw e;
   }
-  if (!def) {
-    if (!opts.prompt) {
-      throw new CLIError(`Agent '${agent}' not found.`, 3 /* NotFound */, `Pass --prompt "<system prompt>" to create it, or create it first with: martha agents create --name ${agent} --reasoning martha --prompt "..."`);
-    }
-    const deliveryNote = `
-
-When a message asks you to reply in a channel, reply with the ` + "message content ONLY — delivery is handled for you. Never output " + "delivery commands (e.g. `buzz messages send`).";
-    def = await ctx.api.post(AGENTS_PATH, {
-      name: agent,
-      system_prompt: opts.prompt + deliveryNote,
-      agent_type: "cloud",
-      runs_as_chat: true,
-      description: "Agent principal for external drivers (#1117)"
-    });
-    steps.push(`created Martha-hosted agent '${agent}' (runs_as_chat)`);
-  } else {
-    if (String(def.agent_type ?? "") === "external") {
-      throw new CLIError(`Agent '${agent}' is self-hosted (reasoning runs in your own service). ` + `An agent principal drives a Martha-hosted agent — recreate it with --reasoning martha.`, 4 /* Validation */);
-    }
-    if (def.runs_as_chat !== true) {
-      await ctx.api.put(A, { runs_as_chat: true });
-      steps.push("enabled chat takeover (runs_as_chat)");
-    }
+  if (existing && String(existing.agent_type ?? "") === "external") {
+    throw new CLIError(`Agent '${agent}' is self-hosted (reasoning runs in your own service). ` + `An agent principal drives a Martha-hosted agent — recreate it with --reasoning martha.`, 4 /* Validation */);
+  }
+  if (!existing && !opts.prompt) {
+    throw new CLIError(`Agent '${agent}' not found.`, 3 /* NotFound */, `Pass --prompt "<system prompt>" to create it, or create it first with: martha agents create --name ${agent} --reasoning martha --prompt "..."`);
   }
-  const agentName = String(def?.name ?? agent);
   const boot = await ctx.api.post(BOOTSTRAP_PATH, {
     mode: "integration",
-    label: opts.label ?? agentName,
-    intents: parseIntents(opts.intents)
+    label: opts.label ?? agent,
+    intents: parseIntents(opts.intents),
+    agent: true,
+    agent_name: agent,
+    agent_system_prompt: opts.prompt ? opts.prompt + CHANNEL_AGENT_PROMPT_SUFFIX : undefined,
+    collections: parseIntents(opts.collections)
   });
   if (!boot.service_account || boot.client_id == null) {
     throw new CLIError("Bootstrap did not return service-account credentials.", 1 /* Error */, "Check that your user has the admin realm role (integration mode requires it).");
   }
+  const agentName = boot.agent?.name ?? agent;
   steps.push(boot.adopted ? `reusing principal '${boot.service_account.client_id}' (same secret — recovery, not rotation)` : `provisioned principal '${boot.service_account.client_id}'`);
-  const granted = await ctx.api.get(`/api/admin/definitions/clients/${boot.client_id}/agents`);
-  const names = granted.map((g) => String(g.name ?? g.agent_name ?? ""));
-  if (!names.includes(agentName)) {
-    await ctx.api.post(`/api/admin/definitions/clients/${boot.client_id}/agents`, { agent_name: agentName });
-    steps.push(`bound '${agentName}' to client ${boot.client_id}`);
-  } else {
-    steps.push(`'${agentName}' already bound to client ${boot.client_id}`);
+  steps.push(boot.agent?.adopted ? `bound existing agent '${agentName}' to client ${boot.client_id}` : `created agent '${agentName}' (runs_as_chat) and bound it to client ${boot.client_id}`);
+  const fns = boot.agent?.granted_functions ?? [];
+  steps.push(fns.length ? `granted its tools: ${fns.join(", ")}` : "granted NO tools — pass --intents rag (or documents/tasks) or it can do nothing");
+  const cols = boot.agent?.granted_collections ?? [];
+  steps.push(cols.length ? `granted it read on: ${cols.join(", ")}` : "granted NO collections — its retrieval tools will return nothing until you pass --collections");
+  if (!fns.length) {
+    warnings.push("no tools: this agent will answer from the model alone.");
+  }
+  if (fns.length && !cols.length) {
+    warnings.push(`it can call list_collections and will get an empty list — grant one: martha collections grant <name> --to agent:${boot.agent?.agent_id ?? "<id>"}`);
   }
-  const others = names.filter((n) => n && n !== agentName);
-  if (others.length) {
-    warnings.push(`client ${boot.client_id} also has agent(s) ${others.join(", ")} — chat takeover requires exactly ONE bound agent; revoke the others or use a fresh --label.`);
+  for (const s of boot.skipped ?? []) {
+    warnings.push(`skipped ${s.name}: ${s.reason}`);
+  }
+  try {
+    const bound = await ctx.api.get(`/api/admin/definitions/clients/${boot.client_id}/agents`);
+    const others = (Array.isArray(bound) ? bound : []).map((g) => String(g.name ?? g.agent_name ?? "")).filter((n) => n && n !== agentName);
+    if (others.length) {
+      warnings.push(`client ${boot.client_id} also has agent(s) ${others.join(", ")} — chat takeover requires exactly ONE bound agent; revoke the others or use a fresh --label.`);
+    }
+  } catch {
+    warnings.push(`could not read back client ${boot.client_id}'s agents — verify with: martha agents doctor ${agentName}`);
   }
   return {
     agent: agentName,
@@ -14705,7 +14709,7 @@ function printAgentPrincipalReady(r, savedProfile) {
 }
 function registerPrincipalCommands(program2) {
   const principals = program2.command("principals").description("Provision principals — who may act, with what credential (mirrors the API's principals/bootstrap)");
-  principals.command("bootstrap").description("Provision a principal. --mode human: your run-as client (what `martha init` wraps). " + "--mode integration: headless service account. --mode agent: service account bound " + "to ONE Martha-hosted agent (chat takeover) so the credential acts as the agent — " + "the shape an external ACP driver (Buzz, Zed) needs.").requiredOption("--mode <mode>", "human | integration | agent").option("--agent <name>", "Agent to bind (agent mode)").option("--prompt <text>", "System prompt — creates the agent when it doesn't exist yet (agent mode)").option("--label <label>", "Label for the service-account client id (default: the agent name in agent mode)").option("--intents <list>", "Comma-separated tool intents to grant (rag, documents, workflows, tasks)").option("--save-profile <name>", "Save the minted credential as a Martha profile, so anything that runs as this agent needs only MARTHA_PROFILE=<name> — no secret to copy").action(async (opts) => {
+  principals.command("bootstrap").description("Provision a principal. --mode human: your run-as client (what `martha init` wraps). " + "--mode integration: headless service account. --mode agent: service account bound " + "to ONE Martha-hosted agent (chat takeover) so the credential acts as the agent — " + "the shape an external ACP driver (Buzz, Zed) needs.").requiredOption("--mode <mode>", "human | integration | agent").option("--agent <name>", "Agent to bind (agent mode)").option("--prompt <text>", "System prompt — creates the agent when it doesn't exist yet (agent mode)").option("--label <label>", "Label for the service-account client id (default: the agent name in agent mode)").option("--intents <list>", "Comma-separated tool intents to grant (rag, documents, workflows, tasks)").option("--collections <list>", "Comma-separated collections (name, slug or id) the agent may read. Intents grant the retrieval TOOLS; without this they return nothing").option("--save-profile <name>", "Save the minted credential as a Martha profile, so anything that runs as this agent needs only MARTHA_PROFILE=<name> — no secret to copy").action(async (opts) => {
     const ctx = createContext({
       profileOverride: program2.opts().profile,
       apiUrlOverride: program2.opts().apiUrl,
@@ -14720,7 +14724,8 @@ function registerPrincipalCommands(program2) {
         const result = await bootstrapAgentPrincipal(ctx, opts.agent, {
           label: opts.label,
           prompt: opts.prompt,
-          intents: opts.intents
+          intents: opts.intents,
+          collections: opts.collections
         });
         const savedProfile = opts.saveProfile ? saveAgentProfile(ctx, opts.saveProfile, result) : null;
         if (isJson) {
@@ -14795,6 +14800,8 @@ function buzzHarnessDefinition(opts = {}) {
     args: ["acp-serve", "--post-reply"],
     env: {
       BUZZ_ACP_MULTIPLE_EVENT_HANDLING: "queue",
+      BUZZ_ACP_SUBSCRIBE: "all",
+      BUZZ_ACP_KINDS: DEFAULT_BUZZ_KINDS,
       ...opts.profile ? { MARTHA_PROFILE: opts.profile } : {}
     },
     installInstructionsUrl: "https://docs.martha.nomadriver.co/cli/buzz",
@@ -15217,7 +15224,7 @@ function assertSupportedChannel(kind) {
 }
 function registerChannelCommands(program2) {
   const channels = program2.command("channels").description("Put a Martha agent in an external conversation channel — from Buzz (install-harness) or from Martha (connect)");
-  channels.command("install-harness <type>").description("Register Martha as a runtime in Buzz Desktop (a tier-3 custom harness definition). " + "Desktop then owns the agent's keypair, attestation and lifecycle — we only declare how to start the adapter.").option("--app-data <dir>", "Buzz Desktop app-data dir (default: auto-detect)").option("--id <id>", "Harness id", BUZZ_HARNESS_ID).option("--label <label>", "Name shown in Buzz's runtime picker", "Martha").option("--command <bin>", "Executable Buzz should spawn", "martha").option("--use-profile <name>", "Bake MARTHA_PROFILE into the definition, so Buzz's Edit Agent needs no credentials at all (mint one with: martha principals bootstrap --mode agent --agent <n> --save-profile <name>). Named --use-profile because the global --profile picks which profile this COMMAND talks to.").option("--print", "Print the definition instead of writing it").option("--force", "Overwrite an existing definition").action(async (type, opts) => {
+  channels.command("install-harness <type>").description("Register Martha as a runtime in Buzz Desktop (a tier-3 custom harness definition). " + "Desktop then owns the agent's keypair, attestation and lifecycle — we only declare how to start the adapter.").option("--app-data <dir>", "Buzz Desktop app-data dir (default: auto-detect)").option("--id <id>", "Harness id", BUZZ_HARNESS_ID).option("--label <label>", "Name shown in Buzz's runtime picker", "Martha").option("--command <bin>", "Executable Buzz should spawn", "martha").option("--use-profile <name>", "Bake MARTHA_PROFILE into the definition as the DEFAULT for every agent on this runtime, so Edit Agent needs nothing. A per-agent MARTHA_PROFILE in Edit Agent overrides it — that is how two Buzz agents become two different Martha agents. Named --use-profile because the global --profile picks which profile this COMMAND talks to.").option("--print", "Print the definition instead of writing it").option("--force", "Overwrite an existing definition").action(async (type, opts) => {
     assertSupportedChannel(type);
     const def = buzzHarnessDefinition({
       id: opts.id,
@@ -15382,19 +15389,30 @@ function installHarnessNotes(def) {
     ...profile ? [
       source_default.cyan("  2. …that's it."),
       source_default.dim(`     The definition names profile '${profile}'; the credential behind it
-` + `     stays in this machine's credentials file. Nothing to type in Buzz.`)
+` + `     stays in this machine's credentials file. Nothing to type in Buzz.`),
+      "",
+      source_default.dim(`A second Martha agent? '${profile}' is the DEFAULT for every agent on
+` + `this runtime — the definition is shared. Give the next one its own
+` + `Martha agent by setting ONE env var on it in Edit Agent, which wins
+` + `over the definition:`),
+      source_default.cyan(`  MARTHA_PROFILE=<its own profile>`),
+      source_default.dim(`  (mint that profile with: martha principals bootstrap --mode agent
+` + "   --agent <name> --save-profile <name>)")
     ] : [
       source_default.cyan("  2. Edit Agent → env vars → MARTHA_CLIENT_ID / MARTHA_CLIENT_SECRET"),
       source_default.dim("     (a definition file is shared config, not a secret store)"),
-      source_default.dim("     Skip this step next time: mint with `martha principals bootstrap\n" + "     --mode agent --agent <n> --save-profile <name>`, then re-run this\n" + "     with --use-profile <name>.")
+      source_default.dim("     One variable instead of two secrets: mint with `martha principals\n" + "     bootstrap --mode agent --agent <n> --save-profile <name>`, then set\n" + `     MARTHA_PROFILE=<name> here — per agent, so each Buzz agent can be a
+` + `     different Martha agent. Re-run this with --use-profile <name> to make
+` + "     one of them the default for the runtime.")
     ],
     "",
     source_default.dim(`Desktop owns the rest: the Nostr keypair in your keyring, the NIP-OA
 ` + "attestation, spawning buzz-acp, and attaching the agent to channels."),
     "",
-    source_default.dim(`If you set BUZZ_ACP_SUBSCRIBE=all on the agent, you MUST also set
-` + `BUZZ_ACP_KINDS=${DEFAULT_BUZZ_KINDS} — 'all' with no kinds is a wildcard
-` + "subscription and turns typing and presence events into prompts.")
+    source_default.dim(`Every agent on this runtime follows the conversation: subscribe=all with
+` + `kinds ${DEFAULT_BUZZ_KINDS} pinned, so DMs, thread replies and follow-ups
+` + `reach it without being re-@mentioned. Want one that only answers when
+` + `named? Set BUZZ_ACP_SUBSCRIBE=mentions on that agent in Edit Agent.`)
   ];
 }
 
@@ -15996,6 +16014,37 @@ var SERVER_GENERATED_FIELDS = new Set([
   "tenant_id"
 ]);
 var AGENT_MANAGED_FIELDS = new Set(["functions", "workflows"]);
+var AGENT_WRITE_FIELDS = new Set([
+  "name",
+  "display_name",
+  "description",
+  "agent_type",
+  "system_prompt",
+  "llm_config",
+  "loop_config",
+  "runs_as_chat",
+  "agent_metadata",
+  "auth_method",
+  "webhook_url",
+  "webhook_secret",
+  "webhook_timeout_s",
+  "is_active",
+  "self_grant_enabled",
+  "self_grant_allowlist",
+  "max_self_grant_scope",
+  "self_grant_max_pending",
+  "self_grant_collection_roots",
+  ...AGENT_MANAGED_FIELDS
+]);
+function validateAgentWriteBody(body, source) {
+  if ("definition" in body) {
+    throw new CLIError(`'definition:' wrapper in ${source} is not supported for kind: Agent — ` + `Agent fields live at the top level. Move the nested keys ` + `(${Object.keys(body.definition ?? {}).join(", ") || "…"}) ` + `up one level.`, 4 /* Validation */);
+  }
+  const unknown = Object.keys(body).filter((k) => !AGENT_WRITE_FIELDS.has(k));
+  if (unknown.length > 0) {
+    throw new CLIError(`Unknown Agent field${unknown.length > 1 ? "s" : ""} in ${source}: ` + `${unknown.map((k) => `'${k}'`).join(", ")} — the server would ` + `silently discard ${unknown.length > 1 ? "them" : "it"}. ` + `Supported top-level fields: ${[...AGENT_WRITE_FIELDS].sort().join(", ")}.`, 4 /* Validation */);
+  }
+}
 function loadDefinitions(inputPath) {
   const resolved = path8.resolve(inputPath);
   if (!fs8.existsSync(resolved)) {
@@ -16084,6 +16133,9 @@ function toLocalDefinition(raw, source) {
   }
   const typedKind = kind;
   const normalizedBody = typedKind === "Function" || typedKind === "Workflow" ? normalizeDefinitionWriteBody(typedKind, body) : body;
+  if (typedKind === "Agent") {
+    validateAgentWriteBody(normalizedBody, source);
+  }
   return { kind: typedKind, name, body: normalizedBody, source };
 }
 async function computeOperations(defs, api) {
@@ -16110,6 +16162,10 @@ async function computeOperations(defs, api) {
       continue;
     }
     const changedFields = diffFields(def.body, remote);
+    const needsReactivation = remote.is_active === false && def.body.is_active !== false;
+    if (needsReactivation && !changedFields.includes("is_active")) {
+      changedFields.push("is_active");
+    }
     if (changedFields.length === 0) {
       ops.push({
         kind: def.kind,
@@ -16123,7 +16179,8 @@ async function computeOperations(defs, api) {
         name: def.name,
         action: "update",
         changedFields,
-        source: def.source
+        source: def.source,
+        reactivate: needsReactivation || undefined
       });
     }
   }
@@ -16204,7 +16261,12 @@ function renderPlan(ops) {
     grouped.get(op.kind).push(op);
   }
   const nameW = Math.max(16, ...ops.map((o) => o.name.length)) + 2;
-  for (const kind of ["Function", "Workflow", "Agent", "Trigger"]) {
+  for (const kind of [
+    "Function",
+    "Workflow",
+    "Agent",
+    "Trigger"
+  ]) {
     const kindOps = grouped.get(kind);
     if (!kindOps)
       continue;
@@ -16285,6 +16347,9 @@ async function executeApply(api, ops, defs, warnings) {
           port_warnings: portWarnings.length > 0 ? portWarnings : undefined
         });
       } else {
+        if (op.reactivate) {
+          body.is_active = true;
+        }
         const res = await api.put(`${apiPath}/${encodeURIComponent(op.name)}`, body);
         if (op.kind === "Function" || op.kind === "Workflow") {
           verifyDefinitionUpdateResponse(op.kind, body, res);

package/package.json

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