@homespunapps/cli 1.0.0

package/dist/commands/skill.js

@@ -0,0 +1,145 @@
+// `homespun skill` — fetch the relay's SKILL.md, or just its version.
+//
+// The relay serves its skill at GET /skills/homespun/SKILL.md and its version
+// at GET /skills/homespun/SKILL.md/version (see
+// packages/relay/src/http/routes/skill.ts). The skill is auto-updating:
+// the relay's deployed image owns both the body and the version, so the
+// agent always reads what the relay it's actually talking to wants it
+// to read.
+//
+// Two verbs:
+//   `homespun skill show`      — print the full markdown to stdout (the
+//                            install / refresh path; pipe to a file).
+//   `homespun skill version`   — print just the relay's skill version (the
+//                            "is my local copy stale?" probe). The agent
+//                            compares this to the `<!-- homespun skill v… -->`
+//                            comment in its local skill file and re-runs
+//                            `homespun skill show > <path>` when they differ.
+//
+// Both are unauthenticated — the skill route is public on the relay and
+// an agent on a too-old CLI must be able to read the upgrade instructions
+// even before it has registered (or before its key was minted).
+import { assertKnownFlags } from "../argv.js";
+import { resolveRelayUrl } from "../config.js";
+import { fail } from "../output.js";
+const NO_FLAGS = [];
+const NO_BOOLS = [];
+const VERSION_BOOLS = ["plain"];
+import { VERSION } from "../version.js";
+export const skillHelp = `homespun skill — fetch the relay's SKILL.md (or its version)
+
+Usage:
+  homespun skill show                     Print the full skill to stdout.
+  homespun skill version [--plain]        Print just the relay's skill version.
+
+The skill is auto-updating: the relay's deployed image owns the version,
+so this is always the skill that matches the relay you are talking to.
+
+Unauthenticated — no API key needed. An agent can call either form
+before 'homespun agent register' to bootstrap or refresh its local skill copy.
+
+Verbs:
+  show                Fetch GET /skills/homespun/SKILL.md and write the raw
+                      markdown to stdout. Pipe to your local skill path:
+                          homespun skill show > ~/.claude/skills/homespun/SKILL.md
+  version             Fetch GET /skills/homespun/SKILL.md/version and print
+                      the relay's skill version. Default output is the
+                      JSON envelope; --plain prints just the version
+                      string so an agent can compare it inline in shell.
+
+Options:
+  --plain             (with 'version' only) print the bare version
+                      string on stdout, no JSON envelope. Useful inside
+                      a shell pipeline: \`if [ "$(homespun skill version
+                      --plain)" != "$LOCAL" ]; then ...\`.
+  --url <url>         Relay base URL (overrides HOMESPUN_URL).
+  -h, --help          Show this help.
+
+Output (stdout):
+  (bare)              Raw markdown, as served by the relay.
+  version             { "version": "1.0.0" } — or '1.0.0\\n' with --plain.
+
+Errors (stderr): { "error": { "code", "message" } } and non-zero exit.`;
+// Shared fetch with the consistent x-homespun-cli-version header (the skill
+// routes are exempt from the version-skew middleware, but sending it lets
+// access logs see which CLI versions are reading the skill).
+async function fetchOrFail(url) {
+    try {
+        return await fetch(url, {
+            headers: { "x-homespun-cli-version": VERSION },
+        });
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        fail(`could not reach ${url}: ${msg}`, "fetch_error");
+    }
+}
+async function failOnNon2xx(res, target) {
+    if (res.ok)
+        return;
+    // 404 if the operator stripped the route, 5xx on a static-read failure.
+    // Surface the body inline — it may carry a useful message.
+    const body = await res.text().catch(() => "");
+    fail(`relay returned ${res.status} for ${target}${body ? ": " + body.slice(0, 200) : ""}`, "relay_error");
+}
+// `homespun skill show` — print the full skill.
+async function runSkillFetch(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "homespun skill show");
+    const url = resolveRelayUrl(args);
+    const target = url + "/skills/homespun/SKILL.md";
+    const res = await fetchOrFail(target);
+    await failOnNon2xx(res, target);
+    const text = await res.text();
+    process.stdout.write(text);
+    // Ensure the markdown ends with a newline so a pipe-reader (cat | xargs |
+    // claude) sees a clean line-terminated boundary even if the relay served
+    // a file without a trailing newline.
+    if (!text.endsWith("\n"))
+        process.stdout.write("\n");
+}
+// `homespun skill version [--plain]` — print just the version.
+async function runSkillVersion(args) {
+    assertKnownFlags(args, NO_FLAGS, VERSION_BOOLS, "homespun skill version");
+    const url = resolveRelayUrl(args);
+    const target = url + "/skills/homespun/SKILL.md/version";
+    const res = await fetchOrFail(target);
+    await failOnNon2xx(res, target);
+    // The relay returns { version: "x.y.z" }. We tolerate a missing/
+    // malformed body so a misbehaving relay can't crash this probe — fall
+    // through to "0.0.0" the same way the relay does when its own SKILL.md
+    // lacks a version comment.
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        body = null;
+    }
+    const version = body !== null &&
+        typeof body === "object" &&
+        typeof body.version === "string"
+        ? body.version
+        : "0.0.0";
+    if (args.bools.has("plain")) {
+        process.stdout.write(version + "\n");
+    }
+    else {
+        process.stdout.write(JSON.stringify({ version }) + "\n");
+    }
+}
+export async function runSkill(args) {
+    const sub = args.positionals[0];
+    switch (sub) {
+        case "show":
+            await runSkillFetch(args);
+            break;
+        case "version":
+            await runSkillVersion(args);
+            break;
+        case undefined:
+            fail("missing verb — usage: homespun skill <show|version> (run 'homespun skill --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown skill verb '${sub}' — expected show|version (run 'homespun skill --help')`, "invalid_args");
+    }
+}

package/dist/commands/taste.js

@@ -0,0 +1,165 @@
+// `homespun taste` — read / write / clear the calling agent's freeform "taste
+// notes" markdown attachment.
+//
+// Taste notes are presentation preferences the agent has learned from human
+// feedback ("denser layout", "no rounded corners", "use a dark header") — the
+// kind of guidance that should outlive a single app. The intended loop:
+//
+//   1. Before generating an app template, run `homespun taste get` and feed the
+//      `taste` field into the prompt so prior preferences shape the output.
+//   2. When the human gives new presentation feedback, run `homespun taste get`,
+//      merge the feedback into the existing notes IN THE PROMPT, then call
+//      `homespun taste set` with the WHOLE new attachment (the relay does whole-attachment
+//      replace, not append — that's deliberate, so the notes can't grow
+//      unbounded into noise).
+//
+// Keep taste notes about *presentation/UI taste only* — colours, density,
+// component preferences. Project context, todos, and per-app state belong
+// somewhere else. Today the attachment is keyed by the agent's API key (per-agent);
+// when app gains first-class humans, this may move to per-human.
+import { readFileSync } from "node:fs";
+import { assertKnownFlags } from "../argv.js";
+import { makeClient } from "../config.js";
+import { printJson, fail, failFromError } from "../output.js";
+const NO_FLAGS = [];
+const NO_BOOLS = [];
+const SET_FLAGS = ["file"];
+const CLEAR_BOOLS = ["yes"];
+export const tasteHelp = `homespun taste — read / write / clear YOUR agent's UI taste notes
+
+Taste notes are a small markdown attachment storing presentation preferences your
+agent has picked up from human feedback ("denser table", "no rounded corners",
+"use a dark header"). Read them before generating an app template so prior
+feedback shapes the output; rewrite them whenever the human gives new
+presentation feedback. Keep entries about UI/presentation taste only — not
+project context, todos, or homespun state.
+
+Usage:
+  homespun taste <subcommand> [options]
+
+Subcommands:
+  get        Print the current notes attachment:
+             { taste: string|null, updated_at: string|null, bytes: number }.
+             taste is null and bytes is 0 when notes have never been written.
+
+  set        Whole-attachment replace. Source the markdown via --file <path>,
+             --file - (read stdin), or by piping into 'homespun taste set' with
+             no flag. The relay rejects empty/whitespace-only payloads and
+             caps the attachment at MAX_TASTE_BYTES (utf8). To clear the notes,
+             use 'homespun taste clear', not 'set' with an empty body.
+
+  clear      Delete the notes. Requires --yes (it is destructive). Prints
+             { cleared: true }.
+
+Options:
+  --file <path|->     Source for 'set' — a file path, or '-' to read stdin
+                      explicitly. Omit to fall back to piped stdin.
+  --yes               Confirm 'clear'.
+  --url <url>         Relay base URL (overrides HOMESPUN_URL).
+  --api-key <key>     Agent API key (overrides HOMESPUN_API_KEY).
+  -h, --help          Show this help.
+
+Examples:
+  homespun taste get
+  homespun taste set --file ./taste.md
+  homespun taste set --file -            # explicit stdin
+  echo "- denser layout" | homespun taste set
+  homespun taste clear --yes
+
+Output: stdout is machine-readable JSON.`;
+// Drain process.stdin to a utf8 string. The caller is responsible for
+// deciding that stdin should be read (e.g. an explicit `--file -`, or a
+// non-TTY stdin where data is actually piped). In a TTY this would block
+// waiting for ^D, so the caller MUST gate on `process.stdin.isTTY` first.
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function runTasteGet(args) {
+    assertKnownFlags(args, NO_FLAGS, NO_BOOLS, "homespun taste get");
+    const client = makeClient(args);
+    try {
+        const info = await client.getTaste();
+        printJson(info);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runTasteSet(args) {
+    assertKnownFlags(args, SET_FLAGS, NO_BOOLS, "homespun taste set");
+    const filePath = args.flags.get("file");
+    // Source the attachment deterministically — no isTTY-flag fusing, because
+    // `!process.stdin.isTTY` is true under every non-interactive caller
+    // (pipes, redirects, closed fd, CI, agent harnesses) and would wrongly
+    // reject `--file` for the entire target audience. See issue #148.
+    //
+    //   --file -        → explicit stdin sentinel
+    //   --file <path>   → read that path (works in TTY and non-TTY alike)
+    //   (no --file)     → fall back to stdin IF non-TTY; error in a TTY
+    let taste;
+    if (filePath === "-") {
+        taste = await readStdin();
+    }
+    else if (filePath !== undefined) {
+        try {
+            taste = readFileSync(filePath, "utf8");
+        }
+        catch (e) {
+            fail(`failed to read --file '${filePath}': ${e instanceof Error ? e.message : String(e)}`, "invalid_args");
+        }
+    }
+    else if (!process.stdin.isTTY) {
+        taste = await readStdin();
+    }
+    else {
+        fail("'homespun taste set' needs input — pass --file <path>, pipe markdown on stdin, or use --file -", "invalid_args");
+    }
+    if (taste.trim().length === 0) {
+        fail("'homespun taste set' refuses an empty or whitespace-only attachment — use 'homespun taste clear --yes' to delete the notes", "invalid_args");
+    }
+    const client = makeClient(args);
+    try {
+        const info = await client.setTaste(taste);
+        printJson(info);
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+async function runTasteClear(args) {
+    assertKnownFlags(args, NO_FLAGS, CLEAR_BOOLS, "homespun taste clear");
+    if (!args.bools.has("yes")) {
+        fail("'homespun taste clear' deletes YOUR agent's taste notes — it is destructive. Pass --yes to confirm.", "confirmation_required");
+    }
+    const client = makeClient(args);
+    try {
+        await client.clearTaste();
+        printJson({ cleared: true });
+    }
+    catch (e) {
+        failFromError(e);
+    }
+}
+export async function runTaste(args) {
+    const sub = args.positionals[0];
+    switch (sub) {
+        case "get":
+            await runTasteGet(args);
+            break;
+        case "set":
+            await runTasteSet(args);
+            break;
+        case "clear":
+            await runTasteClear(args);
+            break;
+        case undefined:
+            fail("missing subcommand — usage: homespun taste <get|set|clear> (run 'homespun taste --help')", "invalid_args");
+            break;
+        default:
+            fail(`unknown taste subcommand '${sub}' — expected get|set|clear (run 'homespun taste --help')`, "invalid_args");
+    }
+}

package/dist/config.js

@@ -0,0 +1,165 @@
+// Relay connection config: HOMESPUN_URL / HOMESPUN_API_KEY from the environment,
+// overridable per-invocation with --url / --api-key. Profile selection via
+// --profile / HOMESPUN_PROFILE picks WHICH (url, api_key) pair to load from
+// the saved store. See store.ts for the on-disk layout.
+import { HomespunClient } from "@homespunapps/core";
+import { fail } from "./output.js";
+import { readStore, resolveProfile, storePath } from "./store.js";
+import { VERSION } from "./version.js";
+/**
+ * The hosted Homespun relay. Used as the relay-URL fallback so a fresh user only
+ * needs an API key — `homespun agent register` against the hosted relay, then go. A
+ * self-hoster overrides it with `--url` / `HOMESPUN_URL` / `homespun agent register --url`.
+ */
+export const DEFAULT_RELAY_URL = "https://homespun.dev";
+/**
+ * Pick the profile-selector source — explicit flag wins over env, env wins
+ * over the store's `current_profile`. Returns both the selector value and
+ * where it came from so `describeConfig` can report it.
+ */
+function pickProfileSelector(args) {
+    const flag = args.flags.get("profile");
+    if (flag !== undefined && flag !== "") {
+        return { selector: flag, source: "flag" };
+    }
+    const env = process.env.HOMESPUN_PROFILE;
+    if (env !== undefined && env !== "") {
+        return { selector: env, source: "env" };
+    }
+    return { selector: undefined, source: "none" };
+}
+/**
+ * Resolve url + apiKey and report the SOURCE of each, WITHOUT making a network
+ * call and WITHOUT failing on a missing value (unlike `resolveConfig`). The
+ * full API key is never returned — only a short, masked prefix.
+ *
+ * Resolution model:
+ *   - `--url` / `HOMESPUN_URL` and `--api-key` / `HOMESPUN_API_KEY` are DIRECT values:
+ *     they override everything, including any active profile. CI scripts that
+ *     set those env vars never need to think about profiles.
+ *   - Otherwise the profile selector (`--profile` flag → `HOMESPUN_PROFILE` env →
+ *     store's `current_profile`) picks one profile out of the store; the
+ *     selected profile's `url` and `api_key` are used.
+ *   - Final fallback for URL is `DEFAULT_RELAY_URL`.
+ */
+export function describeConfig(args) {
+    const store = readStore();
+    const { selector, source: selectorSource } = pickProfileSelector(args);
+    // The store gets visited only if --profile flag is set (explicit
+    // selector) and the store has a matching profile, OR the store has a
+    // current_profile and no explicit selector overrides it. `resolveProfile`
+    // throws on a typo'd selector; we swallow that here so describeConfig
+    // can't crash a `homespun config show` — resolveConfig() is the one that
+    // surfaces the error when the caller actually needs a key.
+    let active;
+    try {
+        active = resolveProfile(store, selector);
+    }
+    catch {
+        active = null;
+    }
+    // URL precedence: --url flag > HOMESPUN_URL env > active profile's url.
+    // The default URL is shown only when nothing else is set.
+    let url = null;
+    let urlSource = "none";
+    if (args.flags.get("url")) {
+        url = args.flags.get("url");
+        urlSource = "flag";
+    }
+    else if (process.env.HOMESPUN_URL) {
+        url = process.env.HOMESPUN_URL;
+        urlSource = "env";
+    }
+    else if (active && active.profile.url) {
+        url = active.profile.url;
+        urlSource = "profile";
+    }
+    // API key precedence: --api-key flag > HOMESPUN_API_KEY env > active profile's api_key.
+    let apiKey = null;
+    let keySource = "none";
+    if (args.flags.get("api-key")) {
+        apiKey = args.flags.get("api-key");
+        keySource = "flag";
+    }
+    else if (process.env.HOMESPUN_API_KEY) {
+        apiKey = process.env.HOMESPUN_API_KEY;
+        keySource = "env";
+    }
+    else if (active && active.profile.apiKey) {
+        apiKey = active.profile.apiKey;
+        keySource = "profile";
+    }
+    return {
+        url: url ? url.replace(/\/$/, "") : null,
+        url_source: urlSource,
+        key_prefix: apiKey ? apiKey.slice(0, 10) + "…" : null,
+        key_source: keySource,
+        profile: active ? active.name : null,
+        profile_source: selectorSource,
+        config_path: storePath(),
+    };
+}
+/**
+ * Resolve relay URL + API key. Precedence (highest first):
+ *   url:    --url flag  → HOMESPUN_URL env  → active profile's url   → DEFAULT_RELAY_URL
+ *   apiKey: --api-key   → HOMESPUN_API_KEY  → active profile's api_key
+ * "Active profile" is chosen by `--profile` / `HOMESPUN_PROFILE` / the store's
+ * `current_profile`. A typo'd `--profile dev` fails fast with `config_error`
+ * — we never silently fall back to a different relay.
+ */
+export function resolveConfig(args) {
+    const store = readStore();
+    const { selector } = pickProfileSelector(args);
+    let active;
+    try {
+        active = resolveProfile(store, selector);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), "config_error");
+    }
+    const url = args.flags.get("url") ??
+        process.env.HOMESPUN_URL ??
+        active?.profile.url ??
+        DEFAULT_RELAY_URL;
+    const apiKey = args.flags.get("api-key") ??
+        process.env.HOMESPUN_API_KEY ??
+        active?.profile.apiKey ??
+        "";
+    if (!apiKey) {
+        fail("missing API key: set HOMESPUN_API_KEY, pass --api-key <key>, or run 'homespun agent register'", "config_error");
+    }
+    return { url: url.replace(/\/$/, ""), apiKey };
+}
+/** Build a HomespunClient from resolved config. */
+export function makeClient(args) {
+    const cfg = resolveConfig(args);
+    return new HomespunClient({
+        url: cfg.url,
+        apiKey: cfg.apiKey,
+        // Sent as `x-homespun-cli-version` on every relay request so the relay can
+        // return 426 cli_upgrade_required when this CLI is too old. Single
+        // source: ./version.ts.
+        cliVersion: VERSION,
+    });
+}
+/**
+ * Resolve just the relay URL — same precedence as `resolveConfig` but
+ * without insisting on an API key. For commands that hit unauthenticated
+ * relay routes (e.g. `homespun skill` → GET /skills/homespun/SKILL.md).
+ */
+export function resolveRelayUrl(args) {
+    const store = readStore();
+    const { selector } = pickProfileSelector(args);
+    let active;
+    try {
+        active = resolveProfile(store, selector);
+    }
+    catch (e) {
+        fail(e instanceof Error ? e.message : String(e), "config_error");
+    }
+    const url = args.flags.get("url") ??
+        process.env.HOMESPUN_URL ??
+        active?.profile.url ??
+        DEFAULT_RELAY_URL;
+    return url.replace(/\/$/, "");
+}

package/dist/format.js

@@ -0,0 +1,133 @@
+// Human-readable formatter for `homespun create` output.
+//
+// The CLI is JSON-first — that's how agents call it. But humans run it too:
+// the agent dev iterating on a template, the operator smoke-testing a relay,
+// the developer who fires `homespun create` once a day to grab a URL and hand
+// it to themselves on their phone. Dumping `{ app_id, urls, tokens, ... }`
+// at them is a downgrade in every case where the next step is "open the
+// URL in a browser".
+//
+// In a TTY (and without `--json` on the CLI), this module renders:
+//   - the title prominently
+//   - each human URL on its own line, copy-friendly
+//   - a QR code for the first human URL, scannable from a phone
+//   - the expiry as a countdown ("in 1h 0m") + ISO timestamp
+//   - the agent stream URL on a dim line (less important for humans)
+//
+// Trust boundary: every interpolated value is a server response or a string
+// the caller asked us to render. No HTML escaping needed — terminal output.
+// We DO neutralise stray ANSI escape characters (a malicious title could
+// otherwise inject colour codes); see stripAnsi.
+import qrcode from "qrcode-terminal";
+/** ANSI helpers. Only applied when writing to a TTY; harmless characters
+ *  otherwise. We deliberately don't pull in a colour library — the CLI has
+ *  one runtime dep today (qrcode-terminal) and we'd like to keep the
+ *  app area tight. */
+const ANSI = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    cyan: "\x1b[36m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+};
+// Strip control chars from interpolated strings. Defends against a relay
+// response (or, more realistically, an echoed title in some future field)
+// carrying ANSI escapes that would otherwise change the user's terminal
+// colour after our output ends.
+// eslint-disable-next-line no-control-regex
+const CTRL_RX = /[\x00-\x08\x0b-\x1f\x7f]/g;
+function safe(s) {
+    return s.replace(CTRL_RX, "");
+}
+/** Generate the QR-code string for `text` using qrcode-terminal's `small`
+ *  rendering (one terminal char per QR module, ~half the height of the
+ *  default). Returns the multi-line string, ready to write to stdout. */
+function qrToString(text) {
+    let out = "";
+    qrcode.generate(text, { small: true }, (s) => {
+        out = s;
+    });
+    return out;
+}
+/** Human-friendly countdown from now to `iso`. Returns "in 1h 0m" /
+ *  "in 45m" / "in 30s" / "expired". Stable enough to test as a string. */
+export function humanCountdown(iso, nowMs = Date.now()) {
+    const delta = new Date(iso).getTime() - nowMs;
+    if (!Number.isFinite(delta) || delta <= 0)
+        return "expired";
+    const totalSec = Math.floor(delta / 1000);
+    const days = Math.floor(totalSec / 86400);
+    const hours = Math.floor((totalSec % 86400) / 3600);
+    const mins = Math.floor((totalSec % 3600) / 60);
+    const secs = totalSec % 60;
+    if (days > 0)
+        return `in ${days}d ${hours}h`;
+    if (hours > 0)
+        return `in ${hours}h ${mins}m`;
+    if (mins > 0)
+        return `in ${mins}m`;
+    return `in ${secs}s`;
+}
+/** Render the homespun-created response for a human reader. Returns the
+ *  full multi-line string; the caller writes it to stdout. */
+export function formatAppCreated(res, opts = {}) {
+    const c = opts.color ?? false;
+    const b = c ? ANSI.bold : "";
+    const d = c ? ANSI.dim : "";
+    const cy = c ? ANSI.cyan : "";
+    const g = c ? ANSI.green : "";
+    const r = c ? ANSI.reset : "";
+    const title = safe(res.title);
+    const appId = safe(res.app_id);
+    const expiresIn = humanCountdown(res.expires_at);
+    const expiresAt = safe(res.expires_at);
+    const humanUrls = res.urls.humans.map(safe);
+    const agentStream = safe(res.urls.agent_stream);
+    const lines = [];
+    // Header — "App created" vs. "Existing app reused" if `created`
+    // is explicitly false. Dedup hits from #262 carry created=false and the
+    // human shouldn't think they made a fresh row.
+    const headline = res.created === false
+        ? `${b}${cy}Existing app reused${r}`
+        : `${b}${g}App created${r}`;
+    lines.push(headline);
+    lines.push("");
+    lines.push(`  ${d}Title:${r}    ${title}`);
+    lines.push(`  ${d}App:${r}      ${appId}`);
+    lines.push(`  ${d}Expires:${r}  ${expiresIn} ${d}(${expiresAt})${r}`);
+    if (res.context_key) {
+        lines.push(`  ${d}Key:${r}      ${safe(res.context_key)}`);
+    }
+    lines.push("");
+    if (humanUrls.length === 0) {
+        // Dedup-on-existing-app path doesn't re-mint human URLs. Note
+        // the situation explicitly rather than rendering a blank section.
+        lines.push(`${d}No human URLs minted on this response — fetch them with ` +
+            `\`homespun participants ${appId}\`.${r}`);
+    }
+    else {
+        const label = humanUrls.length === 1 ? "Open this link" : "Open these links";
+        lines.push(`${label} in a browser:`);
+        lines.push("");
+        for (const u of humanUrls) {
+            lines.push(`  ${b}${u}${r}`);
+        }
+        lines.push("");
+        // Show a QR for the first URL — scannable from a phone. The other
+        // URLs (if any) are visible above; one QR keeps the output compact.
+        lines.push(`Or scan this QR code with your phone:`);
+        lines.push("");
+        const qr = qrToString(humanUrls[0]);
+        // Indent each QR line by two spaces so it sits inside the same gutter
+        // as the rest of the body.
+        for (const ln of qr.split("\n")) {
+            if (ln.length === 0)
+                continue;
+            lines.push(`  ${ln}`);
+        }
+        lines.push("");
+    }
+    lines.push(`${d}Agent stream:${r}  ${agentStream}`);
+    return lines.join("\n") + "\n";
+}