@aiaiai-pt/martha-cli 0.54.0 → 0.57.0

package/CHANGELOG.md

@@ -2,6 +2,127 @@
 
 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
+
+Setting up a Martha agent in Buzz Desktop meant pasting `MARTHA_CLIENT_ID` and
+`MARTHA_CLIENT_SECRET` into Edit Agent, while Goose and Claude Code need
+nothing there — because their own CLI already wrote a config file on that
+machine. Martha's CLI has that file too; it just couldn't hold an agent
+credential, only tokens. That was the whole difference, and it was ours to fix.
+
+- `martha principals bootstrap --mode agent --save-profile <name>` writes the
+  minted credential straight into a profile: server, realm and client in
+  `config.yaml`, the secret in `credentials.json` (0600). It prints
+  **"nothing to copy"** instead of a secret to move around by hand.
+- The credential chain uses it: with no `MARTHA_CLIENT_ID`/`SECRET` in the
+  environment, the profile's own service account authenticates. Env still wins,
+  so a one-off override needs no config change, and the same-client guard from
+  0.53.0 still refuses to hand a service-account caller a human token.
+- `martha channels install-harness buzz --use-profile <name>` bakes
+  `MARTHA_PROFILE=<name>` into the harness definition — a profile *name* is not
+  a secret — so **Edit Agent needs nothing at all**. (`--use-profile`, because
+  the global `--profile` selects which profile the command itself talks to.)
+- `martha channels connect --profile <name>` passes it to the adapter it
+  spawns, which is a separate process and would otherwise fall back to the
+  machine's default profile.
+- The preflight's "durable credential" check counts a profile-held credential
+  as one, and names it.
+
 ## [0.54.0] — 2026-08-03
 
 ### Added — `channels` uses the Buzz binaries Desktop already ships

package/dist/index.js

@@ -9271,6 +9271,23 @@ class TokenStore {
     delete creds.profiles[profile];
     this.writeFile(creds);
   }
+  getServiceAccount(profile) {
+    return this.readFile().service_accounts?.[profile] ?? null;
+  }
+  saveServiceAccount(profile, sa) {
+    const creds = this.readFile();
+    creds.service_accounts = {
+      ...creds.service_accounts ?? {},
+      [profile]: sa
+    };
+    this.writeFile(creds);
+  }
+  clearServiceAccount(profile) {
+    const creds = this.readFile();
+    if (creds.service_accounts)
+      delete creds.service_accounts[profile];
+    this.writeFile(creds);
+  }
   isExpired(profile) {
     const tokens = this.getTokens(profile);
     if (!tokens)
@@ -9306,7 +9323,9 @@ class TokenStore {
     if (!fs2.existsSync(dir)) {
       fs2.mkdirSync(dir, { recursive: true, mode: 448 });
     }
-    fs2.writeFileSync(this.credentialsPath, JSON.stringify(creds, null, 2), { mode: 384 });
+    fs2.writeFileSync(this.credentialsPath, JSON.stringify(creds, null, 2), {
+      mode: 384
+    });
   }
 }
 function decodeJwtPayload(token) {
@@ -10746,12 +10765,13 @@ function createContext(opts) {
     const envToken = process.env.MARTHA_TOKEN;
     if (envToken)
       return envToken;
-    const envClientId = process.env.MARTHA_CLIENT_ID;
-    const envSecret = process.env.MARTHA_CLIENT_SECRET;
-    if (envClientId && envSecret) {
+    const stored = tokenStore.getServiceAccount(profileName);
+    const clientId = process.env.MARTHA_CLIENT_ID ?? stored?.client_id;
+    const clientSecret = process.env.MARTHA_CLIENT_SECRET ?? stored?.client_secret;
+    if (clientId && clientSecret) {
       if (!tokenStore.needsRefresh(profileName)) {
         const existing = tokenStore.getTokens(profileName);
-        if (existing && belongsToClient(existing, envClientId)) {
+        if (existing && belongsToClient(existing, clientId)) {
           return existing.access_token;
         }
       }
@@ -10759,8 +10779,8 @@ function createContext(opts) {
       const tokens2 = await loginClientCredentials2({
         keycloakUrl: profile.keycloak_url,
         realm: profile.keycloak_realm,
-        clientId: envClientId,
-        clientSecret: envSecret
+        clientId,
+        clientSecret
       });
       tokenStore.saveTokens(profileName, tokens2);
       return tokens2.access_token;
@@ -10772,12 +10792,12 @@ function createContext(opts) {
     }
     const tokens = tokenStore.getTokens(profileName);
     if (tokens?.refresh_token && !tokenStore.isRefreshExpired(profileName)) {
-      const clientId = tokens.auth_type === "client_credentials" ? profile.client_id : "martha-cli";
+      const clientId2 = tokens.auth_type === "client_credentials" ? profile.client_id : "martha-cli";
       const refreshed = await refreshAccessToken({
         keycloakUrl: profile.keycloak_url,
         realm: profile.keycloak_realm,
         refreshToken: tokens.refresh_token,
-        clientId
+        clientId: clientId2
       });
       tokenStore.saveTokens(profileName, refreshed);
       return refreshed.access_token;
@@ -11129,7 +11149,7 @@ init_config();
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.54.0";
+var CLI_VERSION = "0.57.0";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -14558,67 +14578,72 @@ function registerAcpServeCommand(program2) {
 
 // src/commands/principals.ts
 init_errors();
+init_config();
 var AGENTS_PATH = "/api/admin/definitions/agents";
 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.");
   }
-  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.`);
+  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>"}`);
+  }
+  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,
@@ -14631,7 +14656,25 @@ When a message asks you to reply in a channel, reply with the ` + "message conte
     warnings
   };
 }
-function printAgentPrincipalReady(r) {
+function saveAgentProfile(ctx, name, r) {
+  const config = loadConfig(ctx.configDir);
+  config.profiles[name] = {
+    api_url: ctx.profile.api_url,
+    keycloak_url: ctx.profile.keycloak_url,
+    keycloak_realm: ctx.profile.keycloak_realm,
+    auth_type: "client_credentials",
+    client_id: r.saClientId,
+    default_agent: r.agent
+  };
+  saveConfig(config, ctx.configDir);
+  ctx.tokenStore.saveServiceAccount(name, {
+    client_id: r.saClientId,
+    client_secret: r.saClientSecret,
+    agent: r.agent
+  });
+  return name;
+}
+function printAgentPrincipalReady(r, savedProfile) {
   console.log(source_default.bold.green(`
 ✓ agent principal ready — the credential acts as '${r.agent}'
 `));
@@ -14640,25 +14683,33 @@ function printAgentPrincipalReady(r) {
   for (const w of r.warnings)
     console.log(source_default.yellow(`  ! ${w}`));
   console.log();
-  console.log(source_default.bold("Service-account secret (shown once — store it like one):"));
-  console.log(source_default.cyan(`  export MARTHA_CLIENT_ID=${r.saClientId}
+  if (savedProfile) {
+    console.log(source_default.bold(`Saved as profile '${savedProfile}' — nothing to copy.`));
+    console.log(source_default.dim(`  ~/.martha/config.yaml + credentials.json (0600) now carry the server,
+` + `  the realm and this credential. Anything that should act as '${r.agent}'
+` + `  needs one variable:`));
+    console.log(source_default.cyan(`  MARTHA_PROFILE=${savedProfile}`));
+  } else {
+    console.log(source_default.bold("Service-account secret (shown once — store it like one):"));
+    console.log(source_default.cyan(`  export MARTHA_CLIENT_ID=${r.saClientId}
 ` + `  export MARTHA_CLIENT_SECRET=${r.saClientSecret}`));
-  console.log(source_default.dim("  The host also needs a Martha profile (api_url + keycloak): run `martha init` once."));
+    console.log(source_default.dim("  The host also needs a Martha profile (api_url + keycloak): run `martha init` once,\n" + "  or re-run this with --save-profile <name> to keep both in one place."));
+  }
   console.log();
   console.log("Any ACP client can now drive the agent via `martha acp-serve`. For Buzz,\n" + "let the CLI check the preconditions and start the adapter for you:");
   console.log(source_default.cyan(`  export BUZZ_PRIVATE_KEY=<agent nsec>        # buzz-admin generate-key
-` + `  martha channels connect buzz --agent ${r.agent} --relay ws://<relay>:<port>`));
+` + `  martha channels connect buzz --agent ${r.agent} --relay ws://<relay>:<port>` + (savedProfile ? ` --profile ${savedProfile}` : "")));
   console.log(source_default.dim(`
   It names anything missing (buzz-acp, the buzz CLI, membership, …) and
 ` + `  exits rather than half-starting. Starting from Buzz Desktop instead?
-` + "  `martha channels install-harness buzz`, then pick Martha in New agent."));
+` + `  \`martha channels install-harness buzz${savedProfile ? ` --profile ${savedProfile}` : ""}\`, then pick Martha in New agent.`));
   console.log(source_default.dim(`
   Then: buzz channels add-member --channel <id> --pubkey <agent pubkey> --role member
 ` + "  and @mention the agent in the channel."));
 }
 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)").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,
@@ -14673,8 +14724,10 @@ 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) {
           console.log(JSON.stringify({
             mode: "agent",
@@ -14683,13 +14736,14 @@ function registerPrincipalCommands(program2) {
             client_key: result.clientKey,
             martha_client_id: result.saClientId,
             martha_client_secret: result.saClientSecret,
+            saved_profile: savedProfile,
             token_endpoint: result.tokenEndpoint,
             steps: result.steps,
             warnings: result.warnings
           }, null, 2));
           return;
         }
-        printAgentPrincipalReady(result);
+        printAgentPrincipalReady(result, savedProfile);
         break;
       }
       case "integration":
@@ -14744,7 +14798,12 @@ function buzzHarnessDefinition(opts = {}) {
     label: opts.label ?? "Martha",
     command: opts.command ?? "martha",
     args: ["acp-serve", "--post-reply"],
-    env: { BUZZ_ACP_MULTIPLE_EVENT_HANDLING: "queue" },
+    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",
     installHint: "npm i -g @aiaiai-pt/martha-cli"
   };
@@ -14834,7 +14893,8 @@ function buzzAcpEnv(opts) {
     BUZZ_ACP_AGENT_ARGS: "acp-serve,--post-reply",
     BUZZ_ACP_SUBSCRIBE: opts.subscribe,
     BUZZ_ACP_MULTIPLE_EVENT_HANDLING: opts.multipleEventHandling,
-    BUZZ_ACP_RESPOND_TO: opts.respondTo
+    BUZZ_ACP_RESPOND_TO: opts.respondTo,
+    ...opts.profile ? { MARTHA_PROFILE: opts.profile } : {}
   };
   if (opts.subscribe === "all")
     env2.BUZZ_ACP_KINDS = opts.kinds;
@@ -14992,11 +15052,12 @@ async function preflightBuzz(ctx, opts) {
   checks.push(await checkAgentPrincipal(ctx, opts.agent, def));
   const hasSa = !!(process.env.MARTHA_CLIENT_ID && process.env.MARTHA_CLIENT_SECRET);
   const hasToken = !!process.env.MARTHA_TOKEN;
+  const profileSa = ctx.tokenStore.getServiceAccount(ctx.profileName);
   checks.push({
-    ok: hasSa || hasToken ? true : null,
-    label: "durable credential in env",
-    detail: hasSa ? `MARTHA_CLIENT_ID=${process.env.MARTHA_CLIENT_ID}` : hasToken ? "MARTHA_TOKEN" : "none — the adapter will fall back to the profile's stored token",
-    fix: hasSa || hasToken ? undefined : `mint one: martha principals bootstrap --mode agent --agent ${opts.agent}`
+    ok: hasSa || hasToken || profileSa ? true : null,
+    label: "durable credential",
+    detail: hasSa ? `MARTHA_CLIENT_ID=${process.env.MARTHA_CLIENT_ID} (env)` : hasToken ? "MARTHA_TOKEN (env)" : profileSa ? `profile '${ctx.profileName}' carries ${profileSa.client_id}${profileSa.agent ? ` (acts as ${profileSa.agent})` : ""}` : "none — the adapter would fall back to whatever token this profile has, which expires",
+    fix: hasSa || hasToken || profileSa ? undefined : `mint one that lives in a profile: martha principals bootstrap --mode agent --agent ${opts.agent} --save-profile <name>`
   });
   const relayProbe = await reachable(relayHttpUrl(opts.relayUrl));
   checks.push({
@@ -15163,12 +15224,13 @@ 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("--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,
       label: opts.label,
-      command: opts.command
+      command: opts.command,
+      profile: opts.useProfile
     });
     if (!isValidHarnessId(def.id)) {
       throw new CLIError(`Harness id '${def.id}' is invalid.`, 4 /* Validation */, "Buzz requires [a-z0-9_][a-z0-9_-]* — a file with any other id is skipped by their loader.");
@@ -15236,7 +15298,8 @@ function registerChannelCommands(program2) {
       kinds: opts.kinds,
       multipleEventHandling: "queue",
       respondTo: opts.respondTo,
-      marthaBin: opts.marthaBin
+      marthaBin: opts.marthaBin,
+      profile: program2.opts().profile
     });
     if (opts.emit) {
       if (!["docker", "compose", "k8s"].includes(opts.emit)) {
@@ -15319,18 +15382,37 @@ function reportPreflight(type, agent, checks, stream = "stdout") {
   }
 }
 function installHarnessNotes(def) {
+  const profile = def.env.MARTHA_PROFILE;
   return [
     "In Buzz Desktop:",
     source_default.cyan(`  1. New agent → runtime "${def.label}"`),
-    source_default.cyan("  2. Edit Agent → env vars → MARTHA_CLIENT_ID / MARTHA_CLIENT_SECRET"),
-    source_default.dim("     (credentials belong per-agent, never in the shared definition file)"),
+    ...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.`),
+      "",
+      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("     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.`)
   ];
 }
 
@@ -15932,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)) {
@@ -16020,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) {
@@ -16046,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,
@@ -16059,7 +16179,8 @@ async function computeOperations(defs, api) {
         name: def.name,
         action: "update",
         changedFields,
-        source: def.source
+        source: def.source,
+        reactivate: needsReactivation || undefined
       });
     }
   }
@@ -16140,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;
@@ -16221,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.54.0",
+  "version": "0.57.0",
   "description": "Terminal-first client for the Martha AI platform",
   "homepage": "https://docs.martha.nomadriver.co",
   "repository": {