@phnx-labs/agents-cli 1.22.84 → 1.22.86

package/dist/lib/accounts/add.d.ts

@@ -0,0 +1,138 @@
+import type { AgentId, Meta } from '../types.js';
+import { type NativeAccount } from '../account-registry.js';
+import { LOGIN_INVOCATIONS, type LoginInvocation } from '../harness-auth-capabilities.js';
+export type { LoginInvocation };
+export { LOGIN_INVOCATIONS };
+/** The env var an api-key worker credential injects as, from HARNESS_AUTH. */
+export declare function workerApiKeyEnv(agent: AgentId): string | null;
+/** Whether `accounts add` can drive this harness (nameable, version-scoped, a real login command). */
+export declare function addSupported(agent: AgentId): boolean;
+/** One-line description of how a harness's workers get their credential. */
+export declare function workerProvisioningHint(agent: AgentId): string;
+/**
+ * Named reason `accounts add` refuses a harness, or null when supported.
+ * Distinguishes "cannot isolate/name this login" (capability) from "no finite
+ * native login command" so the message is honest about which limit was hit.
+ */
+export declare function addRefusal(agent: AgentId): string | null;
+export declare function supportedAddHarnesses(): AgentId[];
+export declare function assertAddSupported(agent: AgentId): void;
+/**
+ * Named reason add/login refuses on a non-headed device, or null when this box
+ * may run an interactive login. Workers never mint a native OAuth login
+ * (credential-management.md invariant 7 + Provisioning model).
+ */
+export declare function addWorkerRefusal(agent: AgentId, name?: string): string | null;
+/**
+ * Refuse to mint a Claude setup-token while an ambient CLAUDE_CODE_OAUTH_TOKEN
+ * is set in this shell — the ambient token is ONE account, so minting under it
+ * would collapse every slot to that account (signin-badge.ts `ambientClaudeToken`).
+ */
+export declare function ambientTokenRefusal(agent: AgentId, env?: NodeJS.ProcessEnv): string | null;
+export declare function loginInvocation(agent: AgentId): LoginInvocation;
+/** The observed identity of a completed login. */
+export interface ObservedIdentity {
+    identityKey: string | null;
+    email: string | null;
+    releaseVersion: string | null;
+    /** Live credential presence — proof of sign-in, not just a metadata identity claim. */
+    signedIn: boolean;
+}
+/**
+ * Fail-closed identity check after the login completes (pure).
+ *
+ * - Not signed in (no live credential) → the login did not complete; a metadata
+ *   identity key alone is NOT proof, so `signedIn` is required.
+ * - A re-auth (`existing`) whose completed identity differs from the account's
+ *   → REFUSE: the account keeps pointing at its original identity.
+ * A new add accepts whatever identity signed in (that is the account being
+ * created); the caller registers it.
+ */
+export declare function verifyConnectedIdentity(ctx: {
+    agent: AgentId;
+    home: string;
+    existing?: NativeAccount | null;
+}, observed: Pick<ObservedIdentity, 'identityKey' | 'signedIn'>): void;
+/** Resolve the existing native account a name refers to for a harness. */
+export declare function findAddAccount(agent: AgentId, name: string | undefined, meta: Pick<Meta, 'accounts' | 'deviceAccounts'>): NativeAccount | null;
+/**
+ * Side-effecting operations add/login need, injected so the planning and
+ * verification path is unit-testable with real meta on a real filesystem
+ * without a network install, a browser, or a TTY.
+ */
+export interface AddRunners {
+    /** Ensure the harness's ONE managed installation exists; resolves with its label. */
+    ensureInstallation(agent: AgentId, onProgress?: (m: string) => void): Promise<{
+        label: string;
+    }>;
+    /** Launch the harness's native login with HOME = `home` (+ slotEnv); resolves on exit. */
+    launchLogin(agent: AgentId, ctx: {
+        home: string;
+        args: string[];
+        email?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        code: number | null;
+    }>;
+    observeIdentity(agent: AgentId, home: string): Promise<ObservedIdentity>;
+    /** Claude: drive `claude setup-token` in the slot and return the captured token. */
+    mintSetupToken?(agent: AgentId, ctx: {
+        home: string;
+    }): Promise<string>;
+    /** Interactive api-key collection; null = user cancelled. Absent = non-interactive. */
+    promptApiKey?(agent: AgentId, env: string): Promise<string | null>;
+    /** Ask the daemon for one auth-sync reconcile (the daemon owns the tick). */
+    requestReconcile?(): void | Promise<void>;
+}
+export interface AddOptions {
+    meta: Pick<Meta, 'accounts' | 'deviceAccounts'>;
+    onProgress?: (m: string) => void;
+    /** Test-only: override the runtime-state dir for the auth-operation mutex. */
+    stateDir?: string;
+    /** Worker credential for api-key harnesses; otherwise prompted interactively. */
+    apiKey?: string;
+    /** Skip the worker-credential step (doctor-style warning is printed). */
+    noWorkerToken?: boolean;
+    /** codex: a ChatGPT-plan account — no API key; workers log in per box. */
+    perDevice?: boolean;
+    /** Overridable env for the ambient-token guard (tests). */
+    env?: NodeJS.ProcessEnv;
+}
+export type WorkerCredentialOutcome = 'minted' | 'stored' | 'kept' | 'per-device' | 'skipped';
+export interface AddResult {
+    mode: 'new' | 'reconnect';
+    agent: AgentId;
+    accountId: string;
+    name: string;
+    identityKey: string;
+    email: string | null;
+    slotDir: string;
+    releaseVersion: string | null;
+    /** True when this add became the harness's default (only set if none was configured). */
+    becameDefault: boolean;
+    provisioning: 'portable' | 'per-device';
+    workerCredential: WorkerCredentialOutcome;
+    workerCredentialRef?: {
+        bundle: string;
+        key: string;
+    };
+    warnings: string[];
+}
+/**
+ * Drive one `agents accounts add <harness> [name]`: headed gate → one managed
+ * installation → fresh slot → native login in the slot → register the row →
+ * mint/collect the worker credential → request a daemon reconcile.
+ */
+export declare function runAdd(agent: AgentId, name: string | undefined, opts: AddOptions, runners?: AddRunners): Promise<AddResult>;
+/**
+ * Drive one `agents accounts login <harness>#<name>`: re-auth into the SAME
+ * slot (re-running add's steps 4–8), re-minting the worker credential and
+ * re-syncing. On a per-device harness (worker `none`) any box may run it —
+ * that IS how such a box logs in.
+ */
+export declare function runLogin(agent: AgentId, name: string, opts: AddOptions, runners?: AddRunners): Promise<AddResult>;
+/** Back-compat alias for the retired `connect` module surface (one release). */
+export declare const runConnect: typeof runAdd;
+export declare const connectSupported: typeof addSupported;
+export declare const connectRefusal: typeof addRefusal;
+export declare const connectWorkerRefusal: typeof addWorkerRefusal;