@aiaiai-pt/martha-cli 0.54.0 → 0.55.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 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.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.55.0";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -14558,6 +14578,7 @@ 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) {
@@ -14631,7 +14652,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 +14679,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("--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,
@@ -14675,6 +14722,7 @@ function registerPrincipalCommands(program2) {
           prompt: opts.prompt,
           intents: opts.intents
         });
+        const savedProfile = opts.saveProfile ? saveAgentProfile(ctx, opts.saveProfile, result) : null;
         if (isJson) {
           console.log(JSON.stringify({
             mode: "agent",
@@ -14683,13 +14731,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 +14793,10 @@ 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",
+      ...opts.profile ? { MARTHA_PROFILE: opts.profile } : {}
+    },
     installInstructionsUrl: "https://docs.martha.nomadriver.co/cli/buzz",
     installHint: "npm i -g @aiaiai-pt/martha-cli"
   };
@@ -14834,7 +14886,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 +15045,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 +15217,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, 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) => {
     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 +15291,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,11 +15375,19 @@ 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.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(`Desktop owns the rest: the Nostr keypair in your keyring, the NIP-OA
 ` + "attestation, spawning buzz-acp, and attaching the agent to channels."),

package/package.json

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