@snowyroad/braid 0.72.0 → 0.73.0

package/dist/{chunk-3I4XXMJX.js → chunk-7BBB4CRN.js}

@@ -365,8 +365,14 @@ function decodeInvite(code) {
 }
 
 // src/redeem.ts
+var InviteExpiredError = class extends Error {
+  constructor() {
+    super("This invite has expired or been revoked. Ask an admin to mint a new one.");
+    this.name = "InviteExpiredError";
+  }
+};
 async function redeemInvite(relayHttpUrl, code) {
-  const { boundedJsonFetch: boundedJsonFetch2 } = await import("./http-QJUYOU2D.js");
+  const { boundedJsonFetch: boundedJsonFetch2 } = await import("./http-Y62OCD7R.js");
   const r = await boundedJsonFetch2(`${relayHttpUrl.replace(/\/$/, "")}/invites/redeem`, {
     method: "POST",
     headers: { "content-type": "application/json" },
@@ -375,7 +381,7 @@ async function redeemInvite(relayHttpUrl, code) {
   });
   if (!r.ok) {
     if (r.category === "http" && r.status === 410) {
-      throw new Error("This invite has expired or been revoked. Ask an admin to mint a new one.");
+      throw new InviteExpiredError();
     }
     if (r.category === "http") throw new Error(`Invite redemption failed (HTTP ${r.status}).`);
     throw new Error(`Invite redemption failed (${r.category}).`);
@@ -455,7 +461,7 @@ function validateReplacementToken(newToken, currentToken, nowMs = Date.now()) {
   return { ok: true };
 }
 async function mintAccessToken(relayHttpUrl, agentKey, fetchFn = fetch, dpopProof) {
-  const { boundedJsonFetch: boundedJsonFetch2 } = await import("./http-QJUYOU2D.js");
+  const { boundedJsonFetch: boundedJsonFetch2 } = await import("./http-Y62OCD7R.js");
   const r = await boundedJsonFetch2(`${relayHttpUrl.replace(/\/$/, "")}/agents/token`, {
     method: "POST",
     headers: {
@@ -485,6 +491,7 @@ async function mintAccessToken(relayHttpUrl, agentKey, fetchFn = fetch, dpopProo
 }
 
 // src/exitCodes.ts
+var EXIT_OK = 0;
 var EXIT_NEEDS_HUMAN = 78;
 var EXIT_CRASH = 1;
 var KeystorePermsError = class extends Error {
@@ -2105,13 +2112,19 @@ export {
   hasSubscriptionLogin,
   effectiveAnthropicCredential,
   macKeychainHasClaudeLogin,
+  decodeInvite,
   assertHttpEndpoint,
   snapshotHttpMetrics,
   resetHttpMetricsForTest,
   boundedJsonFetch,
+  InviteExpiredError,
+  redeemInvite,
   RebootstrapError,
   validateReplacementToken,
+  mintAccessToken,
+  EXIT_OK,
   EXIT_NEEDS_HUMAN,
+  EXIT_CRASH,
   KeystorePermsError,
   classifyFatal,
   assertKeystorePerms,
@@ -2138,6 +2151,8 @@ export {
   verifyCardSignature,
   cleanContent,
   resolveAgentSelection,
+  validateRelayWsUrl,
+  wsToHttp,
   resolveConfig,
   redactConfig
 };

package/dist/cli.js

@@ -15,7 +15,10 @@ import {
   utext
 } from "./chunk-LGYVCFGB.js";
 import {
+  EXIT_CRASH,
   EXIT_NEEDS_HUMAN,
+  EXIT_OK,
+  InviteExpiredError,
   KeystorePermsError,
   RebootstrapError,
   acquireAgentLock,
@@ -24,6 +27,7 @@ import {
   classifyFatal,
   cleanContent,
   configDir,
+  decodeInvite,
   effectiveAnthropicCredential,
   evaluateAcpPermission,
   evaluateSdkTool,
@@ -33,6 +37,7 @@ import {
   listAgents,
   loadAgent,
   macKeychainHasClaudeLogin,
+  mintAccessToken,
   narrowestMode,
   narrowestOverride,
   newBeyondFile,
@@ -41,6 +46,7 @@ import {
   pinEndpoint,
   readPathWithFallback,
   redactConfig,
+  redeemInvite,
   relayHostSegment,
   resolveAgentSelection,
   resolveConfig,
@@ -52,9 +58,11 @@ import {
   takeDenialHint,
   toolModeLabel,
   toolStatusLine,
+  validateRelayWsUrl,
   validateReplacementToken,
-  verifyCardSignature
-} from "./chunk-3I4XXMJX.js";
+  verifyCardSignature,
+  wsToHttp
+} from "./chunk-7BBB4CRN.js";
 
 // src/health.ts
 var CEILING_STRIKES_TO_DEAD = 3;
@@ -6780,6 +6788,10 @@ var USAGE = `Usage: braid <command>
 
 Commands:
   join <code>     Join a relay with an invite code (saves the credential)
+  enroll --invite-stdin [--json]
+                  One-shot enrollment: reads the invite from stdin (never as an
+                  argument), redeems it, saves and verifies the credential, then
+                  exits without starting a session (--json for machine output)
   start [name]    Start the bridge from a saved credential
                   (env-driven config like BRAID_INVITE / BRAID_TOKEN is honored)
   list            List saved agents and their tool access
@@ -6919,6 +6931,32 @@ function parseCliArgs(argv) {
   if (first === "version" || first === "--version" || first === "-v") {
     return { kind: "version" };
   }
+  if (first === "enroll") {
+    let inviteStdin = false;
+    let json = false;
+    for (const a of argv.slice(1)) {
+      if (a === "--invite-stdin") {
+        inviteStdin = true;
+        continue;
+      }
+      if (a === "--json") {
+        json = true;
+        continue;
+      }
+      if (a.startsWith("-")) return { kind: "usage", error: `Unknown flag for enroll: ${a}` };
+      return {
+        kind: "usage",
+        error: "enroll does not accept the invite as an argument. Pipe it on stdin: <command that prints the invite> | npx @snowyroad/braid enroll --invite-stdin"
+      };
+    }
+    if (!inviteStdin) {
+      return {
+        kind: "usage",
+        error: "enroll requires --invite-stdin (the invite is read from stdin, never from arguments)."
+      };
+    }
+    return { kind: "enroll", json };
+  }
   if (first === "join" || first === "start") {
     const parsed = parseRunFlags(argv);
     if (!parsed.ok) return { kind: "usage", error: parsed.error };
@@ -6928,6 +6966,114 @@ function parseCliArgs(argv) {
   return { kind: "usage", error: `Unknown command: ${first}` };
 }
 
+// src/enroll.ts
+var ENROLL_STDIN_MAX_BYTES = 16 * 1024;
+function readBoundedStdin(stream, maxBytes) {
+  return new Promise((resolve2, reject) => {
+    const chunks = [];
+    let total = 0;
+    let settled = false;
+    const finish = (fn) => {
+      if (settled) return;
+      settled = true;
+      stream.removeListener("data", onData);
+      stream.removeListener("end", onEnd);
+      stream.removeListener("error", onError);
+      fn();
+    };
+    const onData = (chunk) => {
+      const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      total += buf.length;
+      if (total > maxBytes) {
+        finish(() => reject(new Error(`stdin exceeded the ${maxBytes / 1024}KiB invite limit`)));
+        return;
+      }
+      chunks.push(buf);
+    };
+    const onEnd = () => finish(() => resolve2(Buffer.concat(chunks).toString("utf8").trim()));
+    const onError = (err) => finish(() => reject(err));
+    stream.on("data", onData);
+    stream.on("end", onEnd);
+    stream.on("error", onError);
+  });
+}
+function persistOrNeedsHuman(dir, agent) {
+  try {
+    return saveAgent(dir, agent);
+  } catch (err) {
+    const code = err?.code;
+    if (code === "EACCES" || code === "EPERM") {
+      throw new KeystorePermsError(
+        `cannot write the keystore under ${dir} (${code}). Fix its ownership/permissions (chmod 700 ${dir}) and run enroll again.`
+      );
+    }
+    throw err;
+  }
+}
+async function runEnroll(opts, io, env) {
+  const outLine = (s) => void io.stdout.write(s + "\n");
+  const errLine = (s) => void io.stderr.write(s + "\n");
+  if (io.stdin.isTTY === true) {
+    errLine(
+      "[braid] enroll reads the invite from stdin and nothing is piped in. Run it as: <command that prints the invite> | npx @snowyroad/braid enroll --invite-stdin"
+    );
+    return EXIT_CRASH;
+  }
+  let blob;
+  try {
+    blob = await readBoundedStdin(io.stdin, ENROLL_STDIN_MAX_BYTES);
+  } catch (err) {
+    errLine(`[braid] enroll failed: ${sanitizeForTty(err instanceof Error ? err.message : String(err))}`);
+    return EXIT_CRASH;
+  }
+  if (blob === "") {
+    errLine(
+      "[braid] enroll received an empty stdin. Pipe the invite in: <command that prints the invite> | npx @snowyroad/braid enroll --invite-stdin"
+    );
+    return EXIT_CRASH;
+  }
+  try {
+    const inv = decodeInvite(blob);
+    validateRelayWsUrl(inv.relayUrl, env, "invite");
+    const relayHttpUrl = wsToHttp(inv.relayUrl);
+    const bundle = await redeemInvite(relayHttpUrl, inv.code);
+    const dir = configDir(env);
+    const stored = {
+      relayUrl: inv.relayUrl,
+      agentId: bundle.agentId,
+      agentName: bundle.agentName,
+      agentUuid: bundle.agentUuid,
+      agentKey: bundle.agentKey
+    };
+    const file = persistOrNeedsHuman(dir, stored);
+    assertKeystorePerms(dir, file);
+    const minted = await mintAccessToken(relayHttpUrl, stored.agentKey);
+    persistOrNeedsHuman(dir, { ...stored, agentKey: minted.agentKey });
+    const name = sanitizeForTty(bundle.agentName);
+    const cmdName = isShellSafeName(bundle.agentName) ? bundle.agentName : "<agent-name>";
+    if (opts.json) {
+      outLine(JSON.stringify({
+        ok: true,
+        agentName: bundle.agentName,
+        agentUuid: bundle.agentUuid,
+        relayUrl: inv.relayUrl,
+        keystoreFile: file
+      }));
+    } else {
+      outLine(`[braid] enrolled: ${name}`);
+      outLine(`[braid] relay: ${inv.relayUrl}`);
+      outLine(`[braid] credential saved to ${file} (verified: token mint ok)`);
+      outLine(`[braid] start it with: npx @snowyroad/braid start ${cmdName}`);
+    }
+    return EXIT_OK;
+  } catch (err) {
+    const e = err instanceof Error ? err : new Error(String(err));
+    errLine(`[braid] enroll failed: ${sanitizeForTty(e.message)}`);
+    if (e instanceof InviteExpiredError) return EXIT_NEEDS_HUMAN;
+    return classifyFatal(e);
+  }
+}
+
 // src/connectedBanner.ts
 function connectedBannerLines(opts) {
   const lines = [
@@ -7259,16 +7405,24 @@ async function runHandoff(opts) {
   const label = opts.channelLabel ?? `#${tag}`;
   const sessionId = session.liveSessionId();
   if (!sessionId) {
-    out.write(`
+    out.write(
+      `
 [handoff] no live session yet for ${label} - nothing to call up
-`);
+`
+    );
     return;
   }
-  const spec = (opts.specFor ?? interactiveResumeSpecFor)(provider, sessionId, cwd);
+  const spec = (opts.specFor ?? interactiveResumeSpecFor)(
+    provider,
+    sessionId,
+    cwd
+  );
   if (!spec) {
-    out.write(`
+    out.write(
+      `
 [handoff] not available for this provider yet (verified for Claude Code, Codex, Grok, and opencode so far)
-`);
+`
+    );
     return;
   }
   const spawnFn = opts.spawnFn ?? nodeSpawn;
@@ -7277,34 +7431,38 @@ async function runHandoff(opts) {
     { scope: opts.scope },
     provider
   );
-  out.write(banner("handoff", `TAKING CONTROL of ${label}`, [
-    "pausing the bridge and opening the agent's REAL interactive session",
-    "on this terminal. Quit it (Ctrl-C or /exit) to hand control back.",
-    "",
-    "WARNING: changes you make inside PERSIST after you leave -",
-    "switching model or mode (or compacting/clearing) carries over into",
-    "how this agent serves the channel afterwards.",
-    // BL-173: the natural moment to grab the session is exactly while the agent is
-    // visibly working — tell the owner what taking over does to the in-flight turn.
-    ...session.hasPendingWork?.() === true ? [
+  out.write(
+    banner("handoff", `TAKING CONTROL of ${label}`, [
+      "pausing the bridge and opening the agent's REAL interactive session",
+      "on this terminal. Quit it (Ctrl-C or /exit) to hand control back.",
       "",
-      "NOTE: a reply is being worked on right now; taking control interrupts",
-      "it. The interrupted message will re-run when you hand back."
-    ] : []
-  ]));
+      "WARNING: changes you make inside PERSIST after you leave -",
+      "switching model or mode (or compacting/clearing) carries over into",
+      "how this agent serves the channel afterwards.",
+      // BL-173: the natural moment to grab the session is exactly while the agent is
+      // visibly working — tell the owner what taking over does to the in-flight turn.
+      ...session.hasPendingWork?.() === true ? [
+        "",
+        "NOTE: a reply is being worked on right now; taking control interrupts",
+        "it. The interrupted message will re-run when you hand back."
+      ] : []
+    ])
+  );
   await session.handoffPause();
   try {
     await new Promise((resolve2) => {
       const child = spawnFn(scoped.command, scoped.args, {
         stdio: "inherit",
         cwd: scoped.cwd,
-        env: scoped.env ? { ...process.env, ...scoped.env } : void 0
+        env: buildAcpEnv(process.env, scoped.env ?? void 0)
       });
       child.on("exit", () => resolve2());
       child.on("error", (e) => {
-        out.write(`
+        out.write(
+          `
 [handoff] failed to open the session: ${sanitizeForTty(String(e?.message ?? e))}
-`);
+`
+        );
         resolve2();
       });
     });
@@ -8778,6 +8936,15 @@ async function main() {
     printStatus(invocation.agent, invocation.json);
     return;
   }
+  if (invocation.kind === "enroll") {
+    process.exit(
+      await runEnroll(
+        { json: invocation.json },
+        { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr },
+        process.env
+      )
+    );
+  }
   if (invocation.kind === "service") {
     process.exit(await runServiceVerb(invocation.verb, invocation.agent, invocation.json));
   }

package/dist/{http-QJUYOU2D.js → http-Y62OCD7R.js}

@@ -4,7 +4,7 @@ import {
   boundedJsonFetch,
   resetHttpMetricsForTest,
   snapshotHttpMetrics
-} from "./chunk-3I4XXMJX.js";
+} from "./chunk-7BBB4CRN.js";
 export {
   assertHttpEndpoint,
   boundedJsonFetch,

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@snowyroad/braid",
-  "version": "0.72.0",
+  "version": "0.73.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@snowyroad/braid",
-      "version": "0.72.0",
+      "version": "0.73.0",
       "license": "SEE LICENSE IN LICENSE.md",
       "dependencies": {
         "@agentclientprotocol/sdk": "0.25.1",
@@ -2546,9 +2546,9 @@
       }
     },
     "node_modules/postcss": {
-      "version": "8.5.18",
-      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.18.tgz",
-      "integrity": "sha512-xdB1oSLHbz1vRWgCDalrCqEFTWzFlhqFC5tIHLMOSUIjhm3XXQ1qrFy8S/ESr1JYRRXqM3c1QFiMZUJdUTqyMQ==",
+      "version": "8.5.19",
+      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.19.tgz",
+      "integrity": "sha512-Mz8SaolMd8nB+G13WkORcxQKHZ/NE4xXevtkJHVuG+guo9/wYKlIMTKAqGdEmYOXR2ijPjTYNHssizdaVSUNdQ==",
       "dev": true,
       "funding": [
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snowyroad/braid",
-  "version": "0.72.0",
+  "version": "0.73.0",
   "description": "Braid: connect your own coding agent (Claude Code, Codex, Gemini, Grok) to a Braid channel and collaborate with other agents and humans.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "SnowyRoad",