@consiliency/agent-board-cli 1.7.0 → 1.9.0

package/dist/cli.d.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { type EnrollKeystore, type EnrollmentIntent, type PendingEnrollmentStore, type OAuthFetchLike, type FetchLike } from "@consiliency/agent-board-client";
+import { type EnrollKeystore, type EnrollmentIntent, type PendingEnrollmentStore, type OAuthFetchLike, type FetchLike, type AgentJoinDeployment, type AgentJoinInstructions, type DeviceAuthorizationPrompt } from "@consiliency/agent-board-client";
 type JsonObject = Record<string, unknown>;
 export interface CliIo {
     writeStdout(message: string): void;
@@ -38,7 +38,15 @@ interface ClientLike {
     grantBoardRole(input: JsonObject): Promise<unknown>;
     setBoardRoleGate(input: JsonObject): Promise<unknown>;
     createInviteLink(input: JsonObject): Promise<unknown>;
+    createInviteLinkWithInstructions(input: JsonObject, deployment: AgentJoinDeployment, board?: {
+        boardSlug?: string;
+        boardName?: string;
+    }): Promise<{
+        result: unknown;
+        instructions: AgentJoinInstructions;
+    }>;
     revokeInviteLink(input: JsonObject): Promise<unknown>;
+    redeemInviteLink(input: JsonObject): Promise<unknown>;
     listBoardPendingMemberships(input: JsonObject): Promise<unknown>;
     resolveAgentHandle(input: JsonObject): Promise<unknown>;
     updateInboxItemState(input: JsonObject): Promise<unknown>;
@@ -129,6 +137,14 @@ export interface EnrollmentCommandRunner {
         redirectResponse?: string;
         slug?: string;
     }): Promise<unknown>;
+    device?(input: {
+        slug: string;
+        intent: EnrollmentIntent;
+        agentKind?: string;
+        requestedScopes?: string[];
+        requestedBoardScopes?: string[];
+        onDeviceAuthorization: (prompt: DeviceAuthorizationPrompt) => void | Promise<void>;
+    }): Promise<unknown>;
 }
 export interface DefaultEnrollmentRunnerDeps {
     /** Pending store bridging begin→complete. Default: FilePendingEnrollmentStore(env). */
@@ -149,6 +165,13 @@ export interface DefaultEnrollmentRunnerDeps {
     publishableKey?: string;
     /** Clock (tests). Default: wall clock. */
     now?: () => number;
+    /**
+     * Poll delay for the device-authorization grant (tests inject a no-op so the e2e
+     * does not incur a real RFC 8628 backoff sleep). Default: the real timer inside
+     * `acquireAccessTokenViaDeviceCode`. Only the `device` flow polls; run/begin/complete
+     * ignore it.
+     */
+    sleep?: (ms: number) => Promise<void>;
     /** Writer for the default browser opener's printed URL. Default: process std streams. */
     io?: {
         writeStdout(message: string): void;

package/dist/cli.js

@@ -1,5 +1,5 @@
 import { Command, Option } from "commander";
-import { createAgentBoardClient, toOperationFailure, beginEnrollment, completeEnrollment, runEnrollment, resolveEnrollmentDescriptor, resolveEnrollEndpoint, resolveEnrollSessionUrl, resolveEnrollPublishableKey, nodeFetchAdapter, buildEnrollKeystore, } from "@consiliency/agent-board-client";
+import { createAgentBoardClient, toOperationFailure, beginEnrollment, completeEnrollment, runEnrollment, runDeviceEnrollment, resolveEnrollmentDescriptor, EnrollmentDescriptorError, resolveEnrollEndpoint, resolveEnrollSessionUrl, resolveEnrollPublishableKey, resolveJoinDeployment, nodeFetchAdapter, buildEnrollKeystore, } from "@consiliency/agent-board-client";
 import { FilePendingEnrollmentStore, makeBrowserOpener } from "./enroll_runtime.js";
 function isRuntimeStatus(value) {
     return Boolean(value && typeof value === "object" && "runtime" in value);
@@ -1246,6 +1246,40 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
                 now: deps.now,
             });
         },
+        async device(input) {
+            const descriptor = resolveEnrollmentDescriptor(env);
+            // Fail CLEAN and actionable when the host descriptor carries no device
+            // endpoint — otherwise the shared flow throws a bare `no_device_endpoint`.
+            // The endpoint is optional in resolveEnrollmentDescriptor (it is not required
+            // for the auth-code paths), so a headless operator must set it explicitly.
+            if (!descriptor.issuer.deviceAuthorizationEndpoint) {
+                throw new EnrollmentDescriptorError("missing_device_endpoint", "device enrollment needs a device authorization endpoint (set MESSAGE_BOARD_ENROLL_DEVICE_AUTHORIZATION_ENDPOINT, e.g. https://portal.consiliency.io/api/oauth/device_authorization)");
+            }
+            // Post-token deps are reconstructed EXACTLY as `run` does (rule #1): keystore,
+            // keystoreBackends, boardFetch, enrollEndpoint, sessionUrl, publishableKey. A
+            // dropped sessionUrl/publishableKey breaks the post-enroll board op on a raw-
+            // Supabase board — pinned by the device analogue of the `run` e2e (drop either
+            // and the sessionUrl-override / anon-apikey assertion fails).
+            const enrollEndpoint = deps.enrollEndpoint ?? resolveEnrollEndpoint(env);
+            const keystore = deps.keystore ?? buildEnrollKeystore(descriptor, env);
+            return runDeviceEnrollment(descriptor, input.intent, {
+                slug: input.slug,
+                agentKind: input.agentKind,
+                requestedScopes: input.requestedScopes,
+                requestedBoardScopes: input.requestedBoardScopes,
+            }, {
+                fetch,
+                enrollEndpoint,
+                keystore,
+                boardFetch,
+                keystoreBackends: keystore.backends,
+                sessionUrl,
+                publishableKey,
+                onDeviceAuthorization: input.onDeviceAuthorization,
+                sleep: deps.sleep,
+                now: deps.now,
+            });
+        },
         async begin(input) {
             // Force OOB: a loopback receiver cannot bridge two separate CLI processes, so
             // the two-step path is always out-of-band paste (no redirectUri ⇒ OOB).
@@ -1259,7 +1293,15 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
                 requestedScopes: input.requestedScopes,
                 requestedBoardScopes: input.requestedBoardScopes,
                 redirectMode: "oob",
-            }, store, { fetch, clientId: descriptor.issuer.clientId, now: deps.now });
+            }, store, {
+                fetch,
+                clientId: descriptor.issuer.clientId,
+                // #173 — pass the provisioning config so begin refuses a doomed raw-Supabase
+                // enrollment BEFORE the human is asked to approve anything.
+                sessionUrl,
+                publishableKey,
+                now: deps.now,
+            });
         },
         async complete(input) {
             const descriptor = resolveEnrollmentDescriptor(env);
@@ -1285,6 +1327,9 @@ export function defaultEnrollmentRunner(env = process.env, deps = {}) {
     };
 }
 function intentFromOptions(options) {
+    if (options.board === false) {
+        return { kind: "none" };
+    }
     if (options.joinBoard) {
         return { kind: "join_board", boardId: options.joinBoard };
     }
@@ -1324,6 +1369,7 @@ function addEnrollCommands(program, io, enrollment) {
         .option("--join-board <boardId>", "join-board intent board id")
         .option("--requested-scopes <csv>", "requested scopes (comma-separated)")
         .option("--requested-board-scopes <csv>", "requested board scopes (comma-separated)")
+        .option("--no-board", "enroll WITHOUT provisioning any board (no create, no join)")
         .action((options) => runHandler(io, "agent_board.enroll", () => enrollment.run({
         slug: options.slug,
         agentKind: options.agentKind,
@@ -1343,6 +1389,7 @@ function addEnrollCommands(program, io, enrollment) {
         .option("--join-board <boardId>", "join-board intent board id")
         .option("--requested-scopes <csv>", "requested scopes (comma-separated)")
         .option("--requested-board-scopes <csv>", "requested board scopes (comma-separated)")
+        .option("--no-board", "enroll WITHOUT provisioning any board (no create, no join)")
         // A6: `begin` is ALWAYS out-of-band (a loopback receiver cannot bridge the two
         // separate begin/complete CLI processes), so this flag is a vestigial no-op kept
         // only for backward compatibility. Use `enroll run` for the loopback flow.
@@ -1376,6 +1423,66 @@ function addEnrollCommands(program, io, enrollment) {
             slug: options.slug,
         }));
     });
+    // RFC 8628 device authorization — the correct flow for a HEADLESS host. `run`'s
+    // loopback receiver binds the SERVER's localhost (useless when the human's browser
+    // is elsewhere) and `begin`/`complete`'s OOB redirect is not registered for the
+    // Portal client; the device grant prints a user_code + URL the human approves on
+    // ANY device, then polls to completion. Same options as `run` where they apply.
+    enroll
+        .command("device")
+        .description("headless enrollment via the RFC 8628 device authorization grant (approve on any device)")
+        .requiredOption("--slug <slug>", "desired agent slug")
+        .option("--agent-kind <kind>", "agent kind (default 'agent')")
+        .option("--create-board <slug>", "create-board intent slug")
+        .option("--board-name <name>", "board name for create-board")
+        .option("--board-description <description>", "board description")
+        .option("--visibility <visibility>", "board visibility")
+        .option("--join-board <boardId>", "join-board intent board id")
+        .option("--requested-scopes <csv>", "requested scopes (comma-separated)")
+        .option("--requested-board-scopes <csv>", "requested board scopes (comma-separated)")
+        .option("--no-board", "enroll WITHOUT provisioning any board (no create, no join)")
+        .action((options) => runHandler(io, "agent_board.enroll_device", () => {
+        // `device` is an OPTIONAL member of EnrollmentCommandRunner (added after the
+        // interface shipped). The default runner always provides it; a custom runner
+        // that predates it gets a clean error instead of a `undefined is not a function`.
+        if (!enrollment.device) {
+            throw new Error("device-authorization enrollment is not supported by this runner (EnrollmentCommandRunner.device is not implemented)");
+        }
+        return enrollment.device({
+            slug: options.slug,
+            agentKind: options.agentKind,
+            intent: intentFromOptions(options),
+            requestedScopes: csv(options.requestedScopes),
+            requestedBoardScopes: csv(options.requestedBoardScopes),
+            // Print the human-facing prompt PROMINENTLY to stderr (stdout is reserved
+            // for the final JSON outcome). The device_code secret is never surfaced.
+            onDeviceAuthorization: (prompt) => io.writeStderr(renderDevicePrompt(prompt)),
+        });
+    }));
+}
+/**
+ * Render the human-facing device-authorization prompt. Written to be pasted to a
+ * human: the user_code and verification URI are the two things they act on. Never
+ * carries the device_code (the shared flow does not expose it here).
+ */
+function renderDevicePrompt(prompt) {
+    const lines = [
+        "",
+        "=== Approve this agent on any device (RFC 8628 device authorization) ===",
+        `  1. Open:  ${prompt.verificationUri}`,
+        `  2. Enter code:  ${prompt.userCode}`,
+    ];
+    if (prompt.verificationUriComplete) {
+        lines.push(`  (or open this pre-filled link directly:  ${prompt.verificationUriComplete})`);
+    }
+    if (prompt.expiresIn) {
+        lines.push(`  This code expires in ${prompt.expiresIn} seconds. Waiting for approval...`);
+    }
+    else {
+        lines.push("  Waiting for approval...");
+    }
+    lines.push("");
+    return `${lines.join("\n")}\n`;
 }
 /** Read a single-line auth code from a piped stdin (A5). Returns undefined on a TTY. */
 async function readCodeFromStdin() {
@@ -1494,18 +1601,72 @@ function addRoomsCommands(program, client, io) {
         .addOption(numberOption("--max-uses <n>", "maximum redemptions"))
         .option("--expires <iso>")
         .option("--created-by-agent-id <agentId>")
-        .action((o) => runHandler(io, "agent_board.create_invite_link", () => client.createInviteLink({
-        p_board_id: o.boardId,
-        p_preset_role: o.role,
-        p_max_uses: o.maxUses,
-        p_expires_at: o.expires,
-        p_created_by_agent_id: o.createdByAgentId,
-    })));
+        .option("--with-instructions", "also print the canonical, paste-able agent-join instructions block (embeds the invite code — treat the output as secret)")
+        .option("--board-slug <slug>", "board slug for the instructions label (the RPC does not return it)")
+        .option("--board-name <name>", "board name for the instructions label (the RPC does not return it)")
+        .action(async (o) => {
+        const rpcInput = {
+            p_board_id: o.boardId,
+            p_preset_role: o.role,
+            p_max_uses: o.maxUses,
+            p_expires_at: o.expires,
+            p_created_by_agent_id: o.createdByAgentId,
+        };
+        if (!o.withInstructions) {
+            return runHandler(io, "agent_board.create_invite_link", () => client.createInviteLink(rpcInput));
+        }
+        // Opt-in instructions path. Resolve deployment facts FIRST so a config gap
+        // fails cleanly WITHOUT minting an orphan link; the plain path above is
+        // untouched, so a missing descriptor never breaks ordinary invite creation.
+        try {
+            const deployment = resolveJoinDeployment();
+            const { result, instructions } = await client.createInviteLinkWithInstructions(rpcInput, deployment, {
+                boardSlug: o.boardSlug,
+                boardName: o.boardName,
+            });
+            io.writeStdout(`${JSON.stringify(result, null, 2)}\n`);
+            // Rendered block printed raw (not JSON-escaped) so it is paste-able. The
+            // invite code lives here; this is the operator's own terminal, the same
+            // place the JSON result already prints it.
+            io.writeStdout(`\n--- agent join instructions (hand this to your agent) ---\n${instructions.renderedText}\n`);
+        }
+        catch (error) {
+            io.writeStdout(`${JSON.stringify(toOperationFailure("agent_board.create_invite_link", error), null, 2)}\n`);
+            process.exitCode = 1;
+        }
+    });
     rooms
         .command("link-revoke")
         .description("Revoke an invite link by code")
         .requiredOption("--code <code>")
         .action((o) => runHandler(io, "agent_board.revoke_invite_link", () => client.revokeInviteLink({ p_code: o.code })));
+    // Joiner-side redeem: an already-enrolled agent redeems an invite AS ITSELF from
+    // its OWN env-resolved credentials (the same resolution every other CLI command
+    // uses) — the clean path for a host whose MCP session carries a different/shared
+    // identity, without hand-rolling an SDK script. The code is a BEARER SECRET.
+    //
+    // A5 (mirrors `enroll complete`, cli.ts): PREFER stdin. A bearer code on argv leaks
+    // via /proc/<pid>/cmdline and the shell's history file, so `--code` is optional and
+    // documented as leaky; when it is absent and stdin is piped, the code is read from
+    // stdin (e.g. a quoted heredoc — the form the rendered join instructions emit, which
+    // keeps the code out of any executable shell string). The command never writes the
+    // code to a log, and neither the success result nor the failure object echoes it.
+    rooms
+        .command("link-redeem")
+        .description("Redeem an invite link by code, joining as the agent identity resolved from this host's env credentials. The code is a BEARER SECRET — prefer piping it on stdin.")
+        .option("--code <code>", "the invite code (prefer stdin; argv leaks via /proc/<pid>/cmdline and shell history)")
+        .action(async (o) => {
+        let code = o.code;
+        if (!code) {
+            code = await readCodeFromStdin();
+        }
+        if (!code) {
+            io.writeStderr("link-redeem needs an invite code: pipe it on stdin (e.g. `agent-board rooms link-redeem <<'MB_INVITE_CODE'` ... `MB_INVITE_CODE`) or pass --code (which leaks the bearer code via /proc and shell history).\n");
+            process.exitCode = 1;
+            return;
+        }
+        return runHandler(io, "agent_board.redeem_invite_link", () => client.redeemInviteLink({ p_code: code }));
+    });
 }
 export function createProgram(client, io, enrollment = defaultEnrollmentRunner()) {
     const program = new Command()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-cli",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "repository": "https://github.com/Consiliency/message-board.git",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,7 +31,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "@consiliency/agent-board-client": "1.13.0",
+    "@consiliency/agent-board-client": "1.15.0",
     "commander": "^14.0.1"
   },
   "license": "Apache-2.0"