@consiliency/agent-board-cli 1.9.0 → 1.11.0

package/dist/cli.d.ts

@@ -1,5 +1,6 @@
 import { Command } from "commander";
-import { type EnrollKeystore, type EnrollmentIntent, type PendingEnrollmentStore, type OAuthFetchLike, type FetchLike, type AgentJoinDeployment, type AgentJoinInstructions, type DeviceAuthorizationPrompt } from "@consiliency/agent-board-client";
+import { type EnrollKeystore, type EnrollmentIntent, type FleetOnboardingIntent, type PendingEnrollmentStore, type OAuthFetchLike, type FetchLike, type AgentJoinDeployment, type AgentJoinInstructions, type DeviceAuthorizationPrompt } from "@consiliency/agent-board-client";
+import { DevicePendingEnrollmentStore } from "./enroll_runtime.js";
 type JsonObject = Record<string, unknown>;
 export interface CliIo {
     writeStdout(message: string): void;
@@ -38,6 +39,20 @@ interface ClientLike {
     grantBoardRole(input: JsonObject): Promise<unknown>;
     setBoardRoleGate(input: JsonObject): Promise<unknown>;
     createInviteLink(input: JsonObject): Promise<unknown>;
+    createFleetOnboardingInvite?(input: {
+        boardId: string;
+        machineId: string;
+        harnessKind: string;
+        harnessLabel: string;
+        repoSlug: string;
+        repoFingerprint: string;
+        repoScopeRole: "worker" | "reviewer";
+        agentRole: "phase_worker" | "reviewer";
+        expectedAgentHandle: string;
+        maxUses?: number;
+        expiresAt?: string;
+        createdByAgentId?: string;
+    }): Promise<unknown>;
     createInviteLinkWithInstructions(input: JsonObject, deployment: AgentJoinDeployment, board?: {
         boardSlug?: string;
         boardName?: string;
@@ -145,10 +160,37 @@ export interface EnrollmentCommandRunner {
         requestedBoardScopes?: string[];
         onDeviceAuthorization: (prompt: DeviceAuthorizationPrompt) => void | Promise<void>;
     }): Promise<unknown>;
+    deviceBegin?(input: {
+        /** Optional caller-generated ID used to bind a companion non-secret continuation first. */
+        enrollmentId?: string;
+        slug: string;
+        intent: EnrollmentIntent;
+        agentKind?: string;
+        requestedScopes?: string[];
+        requestedBoardScopes?: string[];
+    }): Promise<{
+        enrollmentId: string;
+        prompt: DeviceAuthorizationPrompt;
+    }>;
+    deviceComplete?(input: {
+        enrollmentId: string;
+        expectedFleet?: {
+            intent: Omit<FleetOnboardingIntent, "inviteCode">;
+            keyReference: string;
+            slug: string;
+        };
+        /** Keep the secret continuation for a caller that must finish local materialization first. */
+        deletePending?: boolean;
+    }): Promise<unknown>;
+    deviceDeletePending?(input: {
+        enrollmentId: string;
+    }): Promise<void>;
 }
 export interface DefaultEnrollmentRunnerDeps {
     /** Pending store bridging begin→complete. Default: FilePendingEnrollmentStore(env). */
     store?: PendingEnrollmentStore;
+    /** Device-code state bridging deviceBegin→deviceComplete across CLI processes. */
+    deviceStore?: DevicePendingEnrollmentStore;
     /** OAuth/enroll fetch. Default: nodeFetchAdapter over globalThis.fetch. */
     fetch?: OAuthFetchLike;
     /** Board-native fetch for the post-enroll SessionClient. Default: nodeFetchAdapter. */
@@ -179,6 +221,86 @@ export interface DefaultEnrollmentRunnerDeps {
     };
 }
 export declare function defaultEnrollmentRunner(env?: NodeJS.ProcessEnv, deps?: DefaultEnrollmentRunnerDeps): EnrollmentCommandRunner;
+/**
+ * How each field of a `FleetOnboardingIntent` is turned from an argv string into the value
+ * that goes on the wire and into the template (Consiliency/message-board#254).
+ *
+ * This map exists because the previous shape — nine literal `.trim()` calls repeated at two
+ * call sites — is the completeness failure CLAUDE.md rule 1 targets: #254 itself enumerated
+ * six of the nine, and got one of the six wrong. The map is TOTAL over the intent's string
+ * fields by construction, so a field added to `FleetOnboardingIntent` does not compile until
+ * someone dispositions it, and both call sites read their verb from here rather than
+ * restating it.
+ *
+ * Three dispositions, because there are three real behaviours and collapsing them is what
+ * hid the defect:
+ *
+ * - `gated` — the library REFUSES a prohibited character in this value rather than
+ *   rewriting it, because the value is carried byte-exact into a template that runs on
+ *   ANOTHER machine. A bare `.trim()` here deleted an edge-placed member of the refuse
+ *   classes before `required()` could see it, so the library's raw-operand ordering (#215)
+ *   was unreachable from the CLI. The verb is the library's own, imported.
+ * - `normalized` — the value is NOT carried verbatim: it is folded, or it is pinned by
+ *   equality against a value derived from folded atoms. Trimming is right here, and
+ *   removing it would regress an ordinary trailing space into a hard failure for no
+ *   byte-exactness gain. Each one's claim is asserted positively in `cli.test.ts`, on the
+ *   intent the runner RECEIVES — `expectedAgentHandle` and `inviteCode` are copied verbatim
+ *   into the /enroll body, so "the output is clean" would not be evidence about them.
+ * - `vocabulary` — a closed set. A poisoned value cannot match a member, so it is refused
+ *   by the existing pair check rather than by a presentation class.
+ *
+ * Each entry also states what a PROHIBITED character in that field does to the /enroll
+ * request — `wire`, which is the property `cli.test.ts` measures. It is stated per field
+ * rather than as one blanket claim because the blanket claim is false: an invite code is a
+ * bearer secret the server matches, so the refuse class is not policed on it.
+ *
+ * `verbatim` means exactly that — THE REFUSE CLASS IS NOT POLICED ON THIS FIELD — and not
+ * "untouched". Edges are still trimmed here as on every field (AC-6), so a prohibited
+ * character placed at an edge is erased and only an INTERIOR one survives to the wire. The
+ * label is worth stating precisely because the looser reading ("it travels as the operator
+ * typed it") stood in this comment and in three places in the plan, and was false at the
+ * edges in all four. `cli.test.ts` asserts the arm per PLACEMENT, which is the form that
+ * cannot be read two ways.
+ *
+ * Asserting a field's real arm is what makes an exemption evidence instead of prose.
+ */
+type FleetTupleDisposition = {
+    readonly kind: "gated";
+    readonly flag: string;
+    readonly label: string;
+    readonly wire: "refused";
+} | {
+    readonly kind: "normalized";
+    readonly flag: string;
+    readonly why: string;
+    readonly wire: "clean" | "verbatim";
+    readonly normalize: (value: string) => string;
+} | {
+    readonly kind: "vocabulary";
+    readonly flag?: string;
+    readonly why: string;
+    readonly wire: "refused";
+};
+/**
+ * The string-valued keys of `T` — the operator the totality claim above rests on, and the
+ * reason it is named and exported rather than written inline.
+ *
+ * `NonNullable` is load-bearing. `-?` strips optionality from the PRODUCED property, but
+ * the conditional tests the original indexed access, and for `field?: string` that is
+ * `string | undefined`, which does not extend `string`. Written without `NonNullable` this
+ * operator answers `never` for every optional member — so an optional string field added to
+ * the intent would vanish from the disposition map, from the census, and from the wire
+ * matrix, WITHOUT a compile error. Fail-open, and invisible until someone adds such a field.
+ *
+ * Latent rather than live today (`FleetOnboardingIntent` has no optional string members),
+ * which is exactly why it is pinned by a type-level probe in `cli.test.ts` — a guard whose
+ * failure mode is silence has to be tested against a shape that would trigger it.
+ */
+export type StringFieldsOf<T> = {
+    [K in keyof T]-?: NonNullable<T[K]> extends string ? K : never;
+}[keyof T];
+type FleetTupleField = StringFieldsOf<FleetOnboardingIntent>;
+export declare const FLEET_TUPLE_DISPOSITION: Readonly<Record<FleetTupleField, FleetTupleDisposition>>;
 export declare function createProgram(client: ClientLike, io: CliIo, enrollment?: EnrollmentCommandRunner): Command;
 export declare function runCli(argv: string[], io?: CliIo, client?: ClientLike, enrollment?: EnrollmentCommandRunner): Promise<void>;
 export {};