@homespunapps/cli 1.6.33 → 1.6.35

package/dist/argv.js

@@ -47,6 +47,12 @@ export const BOOLEAN_FLAGS = new Set([
     // `homespun agent register --no-device`: skip the browser device-authorization
     // flow and register directly (unowned agent), the pre-device-flow behavior.
     "no-device",
+    // `homespun agent register --start` / `--resume`: the two halves of the device
+    // flow for a caller that cannot hold a blocking command open (an agent whose
+    // harness times the call out). --start prints the link and exits; --resume
+    // redeems the approval afterwards.
+    "start",
+    "resume",
     // `homespun data ... import --emit-effects`: opt a silent bulk import back into
     // firing notify/webhooks (import defaults to silent).
     "emit-effects",

package/dist/commands/register.js

@@ -22,7 +22,8 @@ import { registerAgent, HomespunApiError } from "@homespunapps/core";
 import { assertKnownFlags } from "../argv.js";
 import { specFor } from "../help-catalog.js";
 import { DEFAULT_RELAY_URL } from "../config.js";
-import { runDeviceFlow } from "../device-flow.js";
+import { runDeviceFlow, startDeviceFlow, pollDeviceToken, } from "../device-flow.js";
+import { readPendingDevice, writePendingDevice, clearPendingDevice, isPendingExpired, } from "../pending-device.js";
 import { printJson, fail, failUpgradeRequired } from "../output.js";
 import { isValidProfileName, DEFAULT_PROFILE_NAME, readStore, resolveProfile, upsertProfile, } from "../store.js";
 import { VERSION } from "../version.js";
@@ -47,6 +48,131 @@ export function defaultDeviceAgentName(host = hostname()) {
 function apiKeyPrefix(key) {
     return key.startsWith("hs_") ? key.slice(0, 9) : key.slice(0, 8);
 }
+/**
+ * `--start`: ask the relay for a code pair, park it, and get out of the way.
+ *
+ * Prints the JSON envelope with the link and code ON STDOUT as well as the
+ * human block on stderr, because the caller here is usually an agent relaying
+ * the link into a conversation, and stdout is the channel it parses.
+ */
+async function runRegisterStart(opts) {
+    const agentName = opts.name ?? defaultDeviceAgentName();
+    let started;
+    try {
+        started = await startDeviceFlow({
+            url: opts.url,
+            name: agentName,
+            cliVersion: VERSION,
+        });
+    }
+    catch (e) {
+        failFromDeviceError(e, "device authorization");
+    }
+    if (!started.supported) {
+        fail("this relay does not support browser approval (older relay) - run 'homespun agent register --no-device' and claim the agent afterwards", "device_flow_unsupported");
+    }
+    const code = started.code;
+    const expiresAt = new Date(Date.now() + (code.expires_in ?? 900) * 1000).toISOString();
+    const savedTo = writePendingDevice({
+        device_code: code.device_code,
+        user_code: code.user_code,
+        verification_uri_complete: code.verification_uri_complete,
+        url: opts.url,
+        name: agentName,
+        profile: opts.profileName,
+        expires_at: expiresAt,
+    });
+    printJson({
+        state: "pending_approval",
+        verification_uri_complete: code.verification_uri_complete,
+        user_code: code.user_code,
+        expires_in: code.expires_in ?? 900,
+        expires_at: expiresAt,
+        name: agentName,
+        profile: opts.profileName,
+        pending_saved_to: savedTo,
+        next: "show the link and code to your human, then run 'homespun agent register --resume' once they say they approved it",
+    });
+}
+/**
+ * `--resume`: one poll, then a definite answer.
+ *
+ * Deliberately does NOT loop. The caller is an agent in a conversation: it
+ * should ask the human whether they approved and try again, not hold a tool
+ * call open, which is the failure this whole flag pair exists to remove.
+ */
+async function runRegisterResume(opts) {
+    const pending = readPendingDevice();
+    if (pending === null) {
+        fail("no registration is waiting for approval - run 'homespun agent register --start' first", "no_pending_registration");
+    }
+    // An explicit --url pointing somewhere else is a mistake worth naming: the
+    // device_code is only valid on the relay that issued it, so polling another
+    // would answer expired_token and read as "the code died" instead of "you
+    // aimed at the wrong relay".
+    if (opts.urlFlagGiven && opts.url !== pending.url) {
+        fail(`the pending registration belongs to ${pending.url}, not ${opts.url} - drop --url, or run --start against this relay`, "invalid_args");
+    }
+    if (isPendingExpired(pending)) {
+        clearPendingDevice();
+        fail("the approval link expired before it was approved - run 'homespun agent register --start' again", "device_flow_expired");
+    }
+    let outcome;
+    try {
+        outcome = await pollDeviceToken({
+            url: pending.url,
+            deviceCode: pending.device_code,
+            cliVersion: VERSION,
+        });
+    }
+    catch (e) {
+        // A denial or expiry is terminal: drop the parked flow so the next
+        // --resume says "nothing to resume" rather than re-reporting a dead code.
+        if (e instanceof HomespunApiError &&
+            (e.code === "device_flow_denied" || e.code === "device_flow_expired")) {
+            clearPendingDevice();
+        }
+        failFromDeviceError(e, "device authorization");
+    }
+    if (outcome.state !== "approved") {
+        // Not an error in the flow's terms, but a non-zero exit so a script that
+        // ignores the payload does not sail on believing it is registered.
+        fail(`not approved yet - open ${pending.verification_uri_complete} and confirm the code ${pending.user_code}, then run 'homespun agent register --resume' again`, "not_approved_yet", undefined, { retryable: true });
+    }
+    const savedTo = upsertProfile(pending.profile, { url: pending.url, apiKey: outcome.agent_key }, true);
+    clearPendingDevice();
+    const out = {
+        agent_id: outcome.agent_id,
+        key_prefix: apiKeyPrefix(outcome.agent_key),
+        profile: pending.profile,
+        saved_to: savedTo,
+        registered_via: "device",
+    };
+    if (opts.printKey)
+        out["api_key"] = outcome.agent_key;
+    printJson(out);
+}
+/** Shared error mapping for both halves: same codes the blocking path uses. */
+function failFromDeviceError(e, what) {
+    if (e instanceof HomespunApiError) {
+        if (e.status === 426 && e.code === "cli_upgrade_required") {
+            failUpgradeRequired(e);
+        }
+        if (e.status === 429) {
+            fail(`${what} rate limit exceeded - try again later`, "rate_limited", undefined, {
+                hint: e.hint,
+                retryable: true,
+                docs_url: e.docsUrl,
+            });
+        }
+        fail(e.message, e.code, e.details, {
+            hint: e.hint,
+            retryable: e.retryable,
+            docs_url: e.docsUrl,
+        });
+    }
+    fail(e instanceof Error ? e.message : String(e), "internal");
+}
 export async function runRegister(args) {
     assertKnownFlags(args, ...specFor("agent", "register"));
     // Profile selection for the WRITE side: --profile flag → HOMESPUN_PROFILE env
@@ -84,6 +210,35 @@ export async function runRegister(args) {
     const secret = args.flags.get("secret") ??
         process.env.HOMESPUN_REGISTER_SECRET ??
         undefined;
+    // ---- Two-phase device flow (--start / --resume) -------------------------
+    //
+    // For callers that CANNOT hold a blocking command open: a coding agent runs
+    // register as one tool call, and the harness kills it long before a human
+    // finds their phone. --start prints the link and exits; --resume collects the
+    // key afterwards. See pending-device.ts for why this is not merely nicer.
+    const wantStart = args.bools.has("start");
+    const wantResume = args.bools.has("resume");
+    if (wantStart && wantResume) {
+        fail("--start and --resume are the two halves of one flow; run --start, get the link approved, then run --resume", "invalid_args");
+    }
+    if ((wantStart || wantResume) && args.bools.has("no-device")) {
+        fail("--no-device registers directly and has no approval step, so there is nothing to --start or --resume", "invalid_args");
+    }
+    if ((wantStart || wantResume) && secret !== undefined && secret !== "") {
+        fail("a registration secret uses the direct path, which has no approval step to --start or --resume", "invalid_args");
+    }
+    if (wantStart) {
+        await runRegisterStart({ url, name, profileName, printKey: false });
+        return;
+    }
+    if (wantResume) {
+        await runRegisterResume({
+            urlFlagGiven: args.flags.has("url"),
+            url,
+            printKey: args.bools.has("print-key"),
+        });
+        return;
+    }
     // The device flow is the default. A registration secret implies a
     // REGISTRATION_MODE=secret relay whose operator hands out direct access,
     // and --no-device is the explicit opt-out (CI, headless-with-no-human).

package/dist/device-flow.js

@@ -67,20 +67,17 @@ function rfcErrorCode(body) {
     return typeof err === "string" ? err : null;
 }
 /**
- * Run the device-authorization flow end to end. Returns `supported: false`
- * when the relay 404s the code request (an older relay - the caller falls
- * back to plain POST /v1/register). Throws HomespunApiError on every other
- * failure, including denial and expiry, with actionable codes:
+ * Request a device_code + user_code pair and PRINT the human's instructions.
+ * Does not poll, so it returns as fast as one HTTP round trip.
  *
- *   device_flow_denied    the human clicked Deny
- *   device_flow_expired   nobody approved within the code's lifetime
+ * Split out of runDeviceFlow so `agent register --start` can hand a coding
+ * agent the link and exit, rather than holding the terminal for up to 15
+ * minutes while a human finds their phone. See pending-device.ts.
  */
-export async function runDeviceFlow(opts) {
+export async function startDeviceFlow(opts) {
     const base = opts.url.replace(/\/$/, "");
     const fetchImpl = opts.fetchImpl ?? fetch;
-    const sleep = opts.sleepImpl ?? defaultSleep;
     const print = opts.print ?? defaultPrint;
-    // ---- 1. Request the code pair -----------------------------------------
     const start = await postJson(fetchImpl, `${base}/v1/device/code`, { name: opts.name }, opts.cliVersion);
     if (start.status === 404) {
         // Older relay without the device flow - signal the caller to fall back.
@@ -97,7 +94,6 @@ export async function runDeviceFlow(opts) {
         typeof code.verification_uri_complete !== "string") {
         throw new HomespunApiError(200, "invalid_response", "relay returned an unexpected /v1/device/code body");
     }
-    // ---- 2. Hand the human their marching orders ---------------------------
     const expiresMin = Math.max(1, Math.round((code.expires_in ?? 900) / 60));
     print("");
     print("To approve this agent, open:");
@@ -107,8 +103,78 @@ export async function runDeviceFlow(opts) {
     print(`and confirm the code:  ${code.user_code}`);
     print("");
     print("You can open the link on any device (phone or laptop) and sign in there.");
-    print(`Waiting for approval... (expires in ${expiresMin} min; Ctrl-C to abort)`);
-    // ---- 3. Poll until a terminal answer -----------------------------------
+    print(`The code expires in ${expiresMin} min.`);
+    return { supported: true, code };
+}
+/**
+ * Poll /v1/device/token ONCE.
+ *
+ * Returns rather than loops, so the caller decides whether to wait: the
+ * blocking `runDeviceFlow` loops on it, and `agent register --resume` calls it
+ * exactly once and reports back to the agent. Throws HomespunApiError with an
+ * actionable code on every terminal failure:
+ *
+ *   device_flow_denied    the human clicked Deny
+ *   device_flow_expired   the code died before anyone approved it
+ */
+export async function pollDeviceToken(opts) {
+    const base = opts.url.replace(/\/$/, "");
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const poll = await postJson(fetchImpl, `${base}/v1/device/token`, { device_code: opts.deviceCode }, opts.cliVersion);
+    if (poll.status === 200) {
+        const body = poll.body;
+        if (typeof body?.agent_key !== "string" ||
+            typeof body?.agent_id !== "string") {
+            throw new HomespunApiError(200, "invalid_response", "relay returned an unexpected /v1/device/token body");
+        }
+        return {
+            state: "approved",
+            agent_id: body.agent_id,
+            agent_key: body.agent_key,
+            name: typeof body.name === "string" ? body.name : "",
+        };
+    }
+    const rfc = rfcErrorCode(poll.body);
+    if (poll.status === 400 && rfc !== null) {
+        switch (rfc) {
+            case "authorization_pending":
+                return { state: "pending" };
+            case "slow_down":
+                return { state: "slow_down" };
+            case "access_denied":
+                throw new HomespunApiError(400, "device_flow_denied", "the approval request was denied in the browser");
+            case "expired_token":
+                throw new HomespunApiError(400, "device_flow_expired", "the device code expired before it was approved - run 'homespun agent register' again");
+            default:
+                throw new HomespunApiError(400, rfc, `relay rejected the poll (${rfc})`);
+        }
+    }
+    if (poll.status === 429) {
+        // Transient general rate limit - back off like a slow_down and retry.
+        return { state: "slow_down" };
+    }
+    // 426 cli_upgrade_required and anything else: surface the envelope.
+    const env = envelopeError(poll.body);
+    throw new HomespunApiError(poll.status, env?.code ?? "relay_error", env?.message ?? `relay returned ${poll.status} for /v1/device/token`, poll.body?.error?.details);
+}
+/**
+ * Run the device-authorization flow end to end, blocking until the human
+ * answers. Returns `supported: false` when the relay 404s the code request (an
+ * older relay - the caller falls back to plain POST /v1/register).
+ *
+ * This is the path a HUMAN at their own terminal wants: they can see the link
+ * appear and approve it without running a second command. An agent should use
+ * startDeviceFlow + pollDeviceToken instead, because a blocking call cannot
+ * hand the link to anyone until it returns.
+ */
+export async function runDeviceFlow(opts) {
+    const sleep = opts.sleepImpl ?? defaultSleep;
+    const print = opts.print ?? defaultPrint;
+    const started = await startDeviceFlow(opts);
+    if (!started.supported)
+        return { supported: false };
+    const code = started.code;
+    print(`Waiting for approval... (Ctrl-C to abort)`);
     let intervalSeconds = typeof code.interval === "number" && code.interval > 0 ? code.interval : 5;
     const deadline = Date.now() + (code.expires_in ?? 900) * 1000;
     while (Date.now() < deadline) {
@@ -117,46 +183,23 @@ export async function runDeviceFlow(opts) {
         // the code's lifetime (the relay would just answer expired_token).
         if (Date.now() >= deadline)
             break;
-        const poll = await postJson(fetchImpl, `${base}/v1/device/token`, { device_code: code.device_code }, opts.cliVersion);
-        if (poll.status === 200) {
-            const body = poll.body;
-            if (typeof body?.agent_key !== "string" ||
-                typeof body?.agent_id !== "string") {
-                throw new HomespunApiError(200, "invalid_response", "relay returned an unexpected /v1/device/token body");
-            }
+        const outcome = await pollDeviceToken({
+            url: opts.url,
+            deviceCode: code.device_code,
+            ...(opts.cliVersion !== undefined ? { cliVersion: opts.cliVersion } : {}),
+            ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+        });
+        if (outcome.state === "approved") {
             print("Approved.");
             return {
                 supported: true,
-                agent_id: body.agent_id,
-                agent_key: body.agent_key,
-                name: typeof body.name === "string" ? body.name : opts.name,
+                agent_id: outcome.agent_id,
+                agent_key: outcome.agent_key,
+                name: outcome.name !== "" ? outcome.name : opts.name,
             };
         }
-        const rfc = rfcErrorCode(poll.body);
-        if (poll.status === 400 && rfc !== null) {
-            switch (rfc) {
-                case "authorization_pending":
-                    continue;
-                case "slow_down":
-                    // RFC 8628 §3.5: add 5 seconds to the interval and keep going.
-                    intervalSeconds += 5;
-                    continue;
-                case "access_denied":
-                    throw new HomespunApiError(400, "device_flow_denied", "the approval request was denied in the browser");
-                case "expired_token":
-                    throw new HomespunApiError(400, "device_flow_expired", "the device code expired before it was approved - run 'homespun agent register' again");
-                default:
-                    throw new HomespunApiError(400, rfc, `relay rejected the poll (${rfc})`);
-            }
-        }
-        if (poll.status === 429) {
-            // Transient general rate limit - back off like a slow_down and retry.
+        if (outcome.state === "slow_down")
             intervalSeconds += 5;
-            continue;
-        }
-        // 426 cli_upgrade_required and anything else: surface the envelope.
-        const env = envelopeError(poll.body);
-        throw new HomespunApiError(poll.status, env?.code ?? "relay_error", env?.message ?? `relay returned ${poll.status} for /v1/device/token`, poll.body?.error?.details);
     }
     throw new HomespunApiError(400, "device_flow_expired", "the device code expired before it was approved - run 'homespun agent register' again");
 }

package/dist/help-catalog.js

@@ -956,6 +956,14 @@ const AGENT = {
                     name: "no-device",
                     description: "Skip the browser approval and register directly via POST /v1/register",
                 },
+                {
+                    name: "start",
+                    description: "Print the approval link and code, then exit immediately instead of waiting",
+                },
+                {
+                    name: "resume",
+                    description: "Collect the key for a link started with --start, once the human has approved it",
+                },
             ],
         },
         {
@@ -981,6 +989,7 @@ const AGENT = {
     ],
     notes: [
         "register runs the browser device-authorization flow by default: it prints a link and a short code, the account owner opens the link on any device, signs in and approves, and the agent comes out already linked to that account. Older relays without the flow fall back to plain POST /v1/register automatically, as do --no-device and a supplied registration secret; agents registered that way are unowned until 'homespun agent claim' runs.",
+        "--start and --resume split that wait in two, for a caller that cannot hold a command open. An agent runs register as one blocking tool call, and its harness kills the call long before a human finds their phone; the relay issues the key only to the poller that consumes the approved flow, so the human approves, sees success, and no key is ever written. --start prints the link and code and exits at once, parking the device code in pending-device.json beside the config file (mode 0600, since until it is redeemed that code is what collects the key). --resume polls once and either saves the key or exits not_approved_yet, so the agent can ask its human and try again. The approval waits on the relay for the code's full lifetime, so any gap between the two is fine.",
         "The API key and relay URL are saved under a named profile in the CLI config file (mode 0600), so later commands work with only HOMESPUN_URL set, or with nothing set. The key is never printed unless --print-key is passed. Without --profile the key goes under the currently active profile, or under default on a fresh install; use --profile <name> to keep several environments side by side and switch with 'homespun config use <name>'.",
         "claim is one-way. The human generates a one-shot code (it begins with cc_) in their settings UI, hands it to the agent out of band, and the relay binds the agent to that human and migrates app ownership. There is no unclaim in v1: to rotate the owner, revoke the agent with 'homespun key revoke' and register a new one.",
         "set-key makes no relay round-trip. It is the companion to regenerating a key in the relay's my-agents UI: paste the new key here so later commands authenticate as the same agent. Setting HOMESPUN_API_KEY on the agent process instead works just as well.",

package/dist/pending-device.js

@@ -0,0 +1,101 @@
+// The half-finished device-authorization flow, parked on disk between
+// `homespun agent register --start` and `homespun agent register --resume`.
+//
+// WHY THIS FILE EXISTS. The blocking `homespun agent register` holds the
+// device_code in memory and polls until the human approves. That is right for
+// a human at their own terminal and wrong for a coding agent, which runs the
+// command as one blocking tool call: the harness kills it on a timeout (Claude
+// Code's default is 2 minutes against a 15-minute code lifetime), and the relay
+// issues the agent key ONLY to the poller that consumes the approved flow. So
+// the human approves, sees success in the browser, and no key is ever written.
+//
+// Parking the device_code here breaks that coupling. `--start` returns as soon
+// as it has the link, the agent shows it to the human, and `--resume` collects
+// the key whenever the human says they are done. The relay needs no change: an
+// approved flow waits, unconsumed, for its full TTL.
+//
+// MODE 0600, and that is not decoration. Until it is consumed, the device_code
+// is a bearer credential: whoever holds it collects the key the human just
+// approved. It lives beside config.json (which holds API keys under the same
+// mode) rather than in /tmp, where a world-readable default would hand the
+// approval to any other account on the machine.
+//
+// One pending flow at a time. A second --start overwrites the first, which is
+// what someone re-running it after a mistake means; the abandoned flow expires
+// on the relay by itself.
+import { readFileSync, writeFileSync, unlinkSync, mkdirSync, chmodSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { storePath } from "./store.js";
+/** Absolute path to the pending-flow file, beside the config file. */
+export function pendingDevicePath() {
+    return join(dirname(storePath()), "pending-device.json");
+}
+/** Persist the in-flight flow. Creates the config dir if this is a fresh
+ *  install, and forces 0600 even when the file already existed looser. */
+export function writePendingDevice(pending) {
+    const path = pendingDevicePath();
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(pending, null, 2) + "\n", { mode: 0o600 });
+    chmodSync(path, 0o600);
+    return path;
+}
+/**
+ * Read the parked flow, or null when there is none.
+ *
+ * Returns null rather than throwing for a missing, unreadable, unparseable or
+ * structurally wrong file: every one of those means the same thing to the
+ * caller ("nothing to resume, run --start"), and a JSON parse error is a
+ * worse way to say it.
+ */
+export function readPendingDevice() {
+    let text;
+    try {
+        text = readFileSync(pendingDevicePath(), "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return null;
+    const p = parsed;
+    if (typeof p.device_code !== "string" ||
+        typeof p.url !== "string" ||
+        typeof p.profile !== "string") {
+        return null;
+    }
+    return {
+        device_code: p.device_code,
+        user_code: typeof p.user_code === "string" ? p.user_code : "",
+        verification_uri_complete: typeof p.verification_uri_complete === "string"
+            ? p.verification_uri_complete
+            : "",
+        url: p.url,
+        name: typeof p.name === "string" ? p.name : "",
+        profile: p.profile,
+        expires_at: typeof p.expires_at === "string" ? p.expires_at : "",
+    };
+}
+/** Whether the parked flow is past its expiry. An unparseable or absent
+ *  timestamp counts as NOT expired: let the relay be the judge rather than
+ *  refusing to poll a flow that might still be good. */
+export function isPendingExpired(pending, now = Date.now()) {
+    const at = Date.parse(pending.expires_at);
+    return Number.isFinite(at) && at <= now;
+}
+/** Delete the parked flow. Idempotent: a missing file is success, since the
+ *  post-condition ("no pending flow on disk") already holds. */
+export function clearPendingDevice() {
+    try {
+        unlinkSync(pendingDevicePath());
+    }
+    catch {
+        // Already gone.
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homespunapps/cli",
-  "version": "1.6.33",
+  "version": "1.6.35",
   "description": "Command-line client for the Homespun relay: deploy a real multi-user web app from your agent, then keep reading and writing its data.",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
     "test:unit": "vitest run"
   },
   "dependencies": {
-    "@homespunapps/core": "^1.6.33",
+    "@homespunapps/core": "^1.6.35",
     "qrcode-terminal": "^0.12.0"
   },
   "devDependencies": {