@mars-sea/dsh-commandcode-provider 0.7.1 → 0.8.0

package/lib/index.d.ts

@@ -600,7 +600,70 @@ declare function commandDefinition<C extends CommandCodeConnectionOptions>(deps:
 /** Register the command on `ctx.commands` (called from the plugin entry). */
 declare function applyCommands<C extends CommandCodeConnectionOptions>(ctx: Context, deps: CommandCodeCommandDeps<C>): void;
 //#endregion
+//#region src/login-wire.d.ts
+/** Why a login attempt ended in `failed` (stable across versions for copy). */
+type CommandCodeLoginFailureReason =
+/** The Studio page reported the authorization was denied by the user. */
+'denied' |
+/** No callback arrived within the flow's timeout window. */
+'timeout' |
+/** The delivered key failed `/alpha/whoami` validation (401). */
+'invalid-key' |
+/** The validation request could not reach the API. */
+'network' |
+/** The key could not be stored (credentials seam unavailable). */
+'unavailable' |
+/** The attempt was cancelled by the user or torn down with the plugin. */
+'cancelled' |
+/** Anything else. */
+'error';
+/** One login attempt's full state face, as carried over the wire. */
+interface CommandCodeLoginStatus {
+  /**
+   * `idle` — no attempt; `waiting` — the loopback server is up and the
+   * Studio URL is live; `success` — the key validated and was stored;
+   * `failed` — see `reason`/`message`.
+   */
+  state: 'idle' | 'waiting' | 'success' | 'failed';
+  /** The Studio authorization URL while `waiting`. */
+  authUrl?: string;
+  /** The account display name reported by the Studio, on `success`. */
+  userName?: string;
+  /** The key's label from the Studio, on `success`. */
+  keyName?: string;
+  /** Why the attempt failed, when `failed`. */
+  reason?: CommandCodeLoginFailureReason;
+  /** Human-readable failure detail, when `failed` (secondary to `reason`). */
+  message?: string;
+}
+/** The canonical endpoint paths of the three login Remotes. */
+declare const LOGIN_BEGIN_ENDPOINT = "commandcode/loginBegin";
+declare const LOGIN_STATUS_ENDPOINT = "commandcode/loginStatus";
+declare const LOGIN_CANCEL_ENDPOINT = "commandcode/loginCancel";
+/**
+ * Parse one untrusted boundary value into a {@link CommandCodeLoginStatus}.
+ * Every field is shape-checked so a malformed frame fails the boundary
+ * instead of leaking into the page.
+ */
+declare function parseLoginStatus(value: unknown): CommandCodeLoginStatus;
+/** The strict result codec shared by all three login endpoints. */
+declare const loginStatusSchema: TypertSchema<CommandCodeLoginStatus>;
+//#endregion
 //#region src/usage-remote.d.ts
+/**
+ * The browser-login face the usage service exposes (`commandcode/login*`).
+ * Backed by the Host-half {@link !CommandCodeLoginFlow} when the plugin entry
+ * wired one; absent, the methods degrade to a no-op status so an old client
+ * against a fresh page still answers instead of hanging.
+ */
+interface LoginFlowFacade {
+  /** Start (or rejoin) an attempt; rejects when it cannot start at all. */
+  begin(): Promise<CommandCodeLoginStatus>;
+  /** The current attempt's status. */
+  status(): CommandCodeLoginStatus;
+  /** Cancel a waiting attempt. */
+  cancel(): void;
+}
 /** Everything the usage service needs beyond its Cordis context. */
 interface CommandCodeUsageDeps<C extends CommandCodeConnectionOptions = CommandCodeConnectionOptions> {
   /** The registered adapter (for getUsage). */
@@ -611,6 +674,12 @@ interface CommandCodeUsageDeps<C extends CommandCodeConnectionOptions = CommandC
    * entry around `adapter.getUsage()`.
    */
   reports?: () => Promise<CommandCodeAccountsReport>;
+  /**
+   * The browser-login flow (wired by the plugin entry). Absent means the
+   * login endpoints answer `idle` / reject with a plain message — the page's
+   * manual paste path stays the fallback.
+   */
+  login?: LoginFlowFacade;
 }
 /**
  * The Remote receiver: a Cordis service the Gateway resolves by key
@@ -631,6 +700,18 @@ declare class CommandCodeUsageService<C extends CommandCodeConnectionOptions = C
    * the failure branch the page renders as a hint.
    */
   report(): Promise<CommandCodeAccountsReport>;
+  /**
+   * Start (or rejoin) a browser-login attempt and return its fresh status —
+   * `waiting` carrying the Studio URL. Rejects when the flow cannot start
+   * (no free loopback port, disposed plugin); the Gateway folds the throw
+   * into the failure branch the page renders.
+   */
+  loginBegin(): Promise<CommandCodeLoginStatus>;
+  /** Poll a login attempt's status. */
+  loginStatus(): Promise<CommandCodeLoginStatus>;
+  /** Cancel a waiting attempt; returns the post-cancel status. */
+  loginCancel(): Promise<CommandCodeLoginStatus>;
+  private requireLogin;
 }
 /**
  * Provide the usage service and register its Remote descriptor. The registry
@@ -639,6 +720,121 @@ declare class CommandCodeUsageService<C extends CommandCodeConnectionOptions = C
  */
 declare function applyUsageRemote<C extends CommandCodeConnectionOptions>(ctx: Context, deps: CommandCodeUsageDeps<C>): void;
 //#endregion
+//#region src/login.d.ts
+/** Give up on the browser after this long without a callback (mirrors the CLI). */
+declare const LOGIN_TIMEOUT_MS = 120000;
+/** First local port the flow tries (mirrors the CLI). */
+declare const LOGIN_START_PORT = 5959;
+/** How many consecutive ports to try from {@link LOGIN_START_PORT}. */
+declare const LOGIN_MAX_PORT_ATTEMPTS = 10;
+/** Reject callback bodies larger than this (mirrors the CLI). */
+declare const LOGIN_BODY_LIMIT_BYTES = 10000;
+/** The Studio origins allowed to POST credentials to the loopback server. */
+declare const LOGIN_ALLOWED_ORIGINS: readonly string[];
+/** Credentials as delivered by the Studio's callback POST. */
+interface CommandCodeLoginCredentials {
+  apiKey: string;
+  userId: string;
+  userName: string;
+  keyName: string;
+}
+/** Outcome of validating a delivered key against `/alpha/whoami`. */
+type ApiKeyValidation = {
+  valid: true;
+} | {
+  valid: false;
+  error: 'invalid_key' | 'server_error' | 'network_error';
+};
+interface CommandCodeLoginFlowDeps {
+  /**
+   * The Provider API base used for `/alpha/whoami` validation; also selects
+   * the matching Studio base (staging api → staging studio). A thunk is fine:
+   * it is re-read when each attempt starts, so a settings change reaches the
+   * next login. Defaults to the public API base.
+   */
+  apiBase?: string | (() => string | undefined);
+  /** Attempt timeout in millis; defaults to {@link LOGIN_TIMEOUT_MS}. */
+  timeoutMs?: number;
+  /** First port to try; defaults to {@link LOGIN_START_PORT}. */
+  startPort?: number;
+  /** Consecutive-port attempts; defaults to {@link LOGIN_MAX_PORT_ATTEMPTS}. */
+  maxPortAttempts?: number;
+  /** Validation fetch seam; defaults to global `fetch`. */
+  fetchImpl?: typeof fetch;
+  /** Randomness seam; defaults to `node:crypto` randomBytes(32) base64url. */
+  randomToken?: (byteLength: number) => string;
+  /**
+   * Receives the validated credentials after a successful login. Rejecting
+   * fails the attempt with `unavailable`.
+   */
+  storeKey(credentials: CommandCodeLoginCredentials): Promise<void>;
+}
+/** Compose the Studio authorization URL (pure, exported for tests). */
+declare function buildCommandAuthUrl(options: {
+  studioBase: string;
+  port: number;
+  state: string;
+}): string;
+/** Map an API base onto the Studio base the CLI pairs it with. */
+declare function studioBaseForApiBase(apiBase: string): string;
+/**
+ * Validate one candidate key against `/alpha/whoami` (pure, exported for
+ * tests). Mirrors the CLI's verdicts: 401 → invalid_key, other non-OK →
+ * server_error, transport failure → network_error.
+ */
+declare function validateCommandApiKey(fetchImpl: typeof fetch, apiBase: string, apiKey: string): Promise<ApiKeyValidation>;
+/**
+ * One browser-login attempt machine. Single-flight by design: `begin()` while
+ * waiting returns the live attempt's status instead of starting a second one;
+ * a terminal state makes the next `begin()` start fresh.
+ */
+declare class CommandCodeLoginFlow {
+  private readonly deps;
+  private readonly listeners;
+  private statusValue;
+  private server;
+  private timer;
+  /** Settle hooks of the live attempt's callback promise. */
+  private settle;
+  private disposed;
+  constructor(deps: CommandCodeLoginFlowDeps);
+  /** Subscribe to state transitions. @returns the disposer. */
+  onChange(listener: () => void): () => void;
+  /** The current attempt's status face. */
+  status(): CommandCodeLoginStatus;
+  /**
+   * Start an attempt (or rejoin the live one) and resolve with its status —
+   * `waiting` carrying the Studio URL once the loopback server is up.
+   * Rejects only when the flow cannot start at all (no free port, disposed).
+   */
+  begin(): Promise<CommandCodeLoginStatus>;
+  /** Cancel a waiting attempt; terminal states are untouched. */
+  cancel(): void;
+  /** Stop everything; a waiting attempt ends cancelled. Idempotent. */
+  dispose(): void;
+  private readApiBase;
+  private setStatus;
+  /** First free port among the consecutive candidates. */
+  private findPort;
+  /**
+   * Bind the attempt's loopback server, resolving when the port is live.
+   * Pre-bind failures reject (surfacing from `begin()`); a later server error
+   * settles the live attempt as a tagged failure instead.
+   */
+  private bindServer;
+  /** One request against the attempt's callback endpoint (CLI-mirrored). */
+  private handleCallback;
+  /** Answer a decisive callback, stop listening, and settle the attempt. */
+  private settleAttempt;
+  /** Post-validation completion: whoami check, then hand-off to storage. */
+  private complete;
+  /** Map a tagged settle rejection onto the status face. */
+  private failFrom;
+  private clearTimer;
+  /** Close the server and watchdog without touching the published status. */
+  private teardown;
+}
+//#endregion
 //#region src/index.d.ts
 declare const name = "llm-commandcode";
 declare const inject: string[];
@@ -708,5 +904,5 @@ interface ResolvedCommandCodeOptions extends CommandCodeConnectionOptions {
 declare function resolveAdapterOptions(config: Config): ResolvedCommandCodeOptions;
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { BILLING_ACCESS_TTL_MS, COMMAND_CODE_CLI_VERSION, type CommandCodeAccountConfig, CommandCodeAccountPool, type CommandCodeAccountSlot, type CommandCodeAccountState, type CommandCodeAccountUsage, type CommandCodeAccountsReport, CommandCodeAdapter, type CommandCodeAdapterDeps, type CommandCodeBillingAccess, type CommandCodeCommandDeps, type CommandCodeConnectionOptions, type CommandCodeUsageDeps, type CommandCodeUsageReport, CommandCodeUsageService, Config, DEFAULT_API_BASE, DEFAULT_GENERATE_MAX_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_MODELS_CACHE_PATH, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, KNOWN_DEALS, KNOWN_EFFORTS, KNOWN_IMAGE_MODELS, KNOWN_PEAK_PRICING, KNOWN_PLANS, KNOWN_SUBSCRIPTION_PLANS, KNOWN_THINKING_MODELS, PLAN_LABELS, PLAN_ORDER, PROVIDER, type ResolveAttachments, ResolvedCommandCodeOptions, USAGE_REPORT_ENDPOINT, accountUsable, apply, applyCommands, applyUsageRemote, capabilityDescription, commandDefinition, compareByPlan, dealLabel, formatContext, inject, modelVisibleInPlan, name, peakPricingLabel, peakPricingState, planLabel, projectSlugFromPath, resolveAdapterOptions, resolveAuthFileApiKey, selectActiveAccount, subscriptionPlanInfo, usageReportSchema };
+export { type ApiKeyValidation, BILLING_ACCESS_TTL_MS, COMMAND_CODE_CLI_VERSION, type CommandCodeAccountConfig, CommandCodeAccountPool, type CommandCodeAccountSlot, type CommandCodeAccountState, type CommandCodeAccountUsage, type CommandCodeAccountsReport, CommandCodeAdapter, type CommandCodeAdapterDeps, type CommandCodeBillingAccess, type CommandCodeCommandDeps, type CommandCodeConnectionOptions, type CommandCodeLoginCredentials, type CommandCodeLoginFailureReason, CommandCodeLoginFlow, type CommandCodeLoginFlowDeps, type CommandCodeLoginStatus, type CommandCodeUsageDeps, type CommandCodeUsageReport, CommandCodeUsageService, Config, DEFAULT_API_BASE, DEFAULT_GENERATE_MAX_TOKENS, DEFAULT_MAX_OUTPUT_TOKENS, DEFAULT_MODELS_CACHE_PATH, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, KNOWN_DEALS, KNOWN_EFFORTS, KNOWN_IMAGE_MODELS, KNOWN_PEAK_PRICING, KNOWN_PLANS, KNOWN_SUBSCRIPTION_PLANS, KNOWN_THINKING_MODELS, LOGIN_ALLOWED_ORIGINS, LOGIN_BEGIN_ENDPOINT, LOGIN_BODY_LIMIT_BYTES, LOGIN_CANCEL_ENDPOINT, LOGIN_MAX_PORT_ATTEMPTS, LOGIN_START_PORT, LOGIN_STATUS_ENDPOINT, LOGIN_TIMEOUT_MS, type LoginFlowFacade, PLAN_LABELS, PLAN_ORDER, PROVIDER, type ResolveAttachments, ResolvedCommandCodeOptions, USAGE_REPORT_ENDPOINT, accountUsable, apply, applyCommands, applyUsageRemote, buildCommandAuthUrl, capabilityDescription, commandDefinition, compareByPlan, dealLabel, formatContext, inject, loginStatusSchema, modelVisibleInPlan, name, parseLoginStatus, peakPricingLabel, peakPricingState, planLabel, projectSlugFromPath, resolveAdapterOptions, resolveAuthFileApiKey, selectActiveAccount, studioBaseForApiBase, subscriptionPlanInfo, usageReportSchema, validateCommandApiKey };
 //# sourceMappingURL=index.d.ts.map