@aiaiai-pt/martha-cli 0.57.0 → 0.58.1

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.58.1] — 2026-08-04
+
+### Fixed — provisioning called an existing agent blind when it wasn't
+
+0.57.0 taught `bootstrap --mode agent` to say `granted NO collections — its
+retrieval tools will return nothing`. True for an agent created by that call;
+false for one that already existed, whose grants predate it. The honest
+statement for an adopted agent is that this call granted nothing *new* and left
+its access alone, so that is what it says now — and the "will get an empty
+list" warning is limited to agents we just created and therefore know are
+empty. Reporting a false alarm is the same failure as reporting nothing, in the
+other direction.
+
+## [0.58.0] — 2026-08-04
+
+### Fixed — the harness pointed strangers at a 404
+
+Buzz shows a runtime's `installInstructionsUrl` exactly when its binary is not
+on PATH — to someone who has just picked Martha and has nothing installed. Ours
+pointed at `docs.martha.nomadriver.co/cli/buzz`, which has never existed. It now
+points at **`/buzz`**, a page written for that arrival, and `installHint` is the
+`npx` one-liner rather than `npm i -g`: a hint that requires a prior install is
+no hint for someone who has installed nothing.
+
+`--print` now writes a short header to **stderr** saying what the JSON is and
+where it goes, so `--print > martha.json` still produces a clean file while a
+paste into a Settings form or a gist carries its own context.
+
 ## [0.57.0] — 2026-08-03
 
 ### Fixed — `bootstrap --mode agent` produced an agent that could not do anything

package/README.md

@@ -90,6 +90,27 @@ martha agents list --json | jq '.[] | {name, status}'
 
 Exit codes: `0` success · `1` generic error · `2` auth failure · `3` not found · `4` validation · `5` conflict (409).
 
+## Put an agent in a Buzz channel
+
+One command, no install of its own:
+
+```bash
+npx -y @aiaiai-pt/martha-cli channels install-harness buzz
+```
+
+Then in [Buzz](https://github.com/block/buzz) Desktop: **New agent → runtime "Martha"**. The command registers Martha as an ACP runtime by writing a definition into Buzz's own app-data directory — the supported route for any ACP agent, no PR and no plugin.
+
+To have an agent for it to be, and leave Buzz's **Edit Agent** empty:
+
+```bash
+martha principals bootstrap --mode agent --agent support \
+  --prompt "You answer support questions from our handbook." \
+  --intents rag --collections "Handbook" --save-profile support
+martha channels install-harness buzz --use-profile support
+```
+
+The profile *name* goes in the definition; the credential stays in `~/.martha/credentials.json` (0600). Check everything before trusting it with `martha channels preflight buzz --agent support --relay wss://…`, which names each missing precondition and exits non-zero. Full guide: <https://docs.martha.nomadriver.co/buzz>.
+
 ## Agent integration
 
 This package ships an agent-facing skill reference at `skills/martha-cli/SKILL.md` describing every command, JSON contract, and conceptual primitive (tenant, agent, function, task, etc.). Agent harnesses can pull it directly:

package/dist/index.js

@@ -11149,7 +11149,7 @@ init_config();
 init_errors();
 
 // src/version.ts
-var CLI_VERSION = "0.57.0";
+var CLI_VERSION = "0.58.1";
 
 // src/commands/sessions.ts
 function relativeTime(iso) {
@@ -14621,16 +14621,17 @@ async function bootstrapAgentPrincipal(ctx, agent, opts = {}) {
     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;
+  const agentAdopted = boot.agent?.adopted === true;
   steps.push(boot.adopted ? `reusing principal '${boot.service_account.client_id}' (same secret — recovery, not rotation)` : `provisioned principal '${boot.service_account.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");
+  steps.push(cols.length ? `granted it read on: ${cols.join(", ")}` : agentAdopted ? "granted no new collections (existing access unchanged)" : "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) {
+  if (fns.length && !cols.length && !agentAdopted) {
     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 ?? []) {
@@ -14792,6 +14793,7 @@ init_errors();
 var AGENTS_PATH2 = "/api/admin/definitions/agents";
 var SUPPORTED_CHANNELS = ["buzz"];
 var BUZZ_HARNESS_ID = "martha";
+var BUZZ_INSTALL_DOCS_URL = "https://docs.martha.nomadriver.co/buzz";
 function buzzHarnessDefinition(opts = {}) {
   return {
     id: opts.id ?? BUZZ_HARNESS_ID,
@@ -14804,8 +14806,8 @@ function buzzHarnessDefinition(opts = {}) {
       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"
+    installInstructionsUrl: BUZZ_INSTALL_DOCS_URL,
+    installHint: "npx -y @aiaiai-pt/martha-cli channels install-harness buzz"
   };
 }
 function isValidHarnessId(id) {
@@ -15238,6 +15240,11 @@ function registerChannelCommands(program2) {
     const json = JSON.stringify(def, null, 2) + `
 `;
     if (opts.print) {
+      process.stderr.write(`# Buzz custom harness definition — save as ${def.id}.json in Buzz's
+` + `# custom_harnesses directory, or let the CLI place it:
+` + `#   npx -y @aiaiai-pt/martha-cli channels install-harness buzz
+` + `# ${BUZZ_INSTALL_DOCS_URL}
+`);
       console.log(json);
       return;
     }

package/package.json

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