@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/agents/providers/cursor.js

@@ -0,0 +1,24 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Cursor provider.
+ *
+ * Cursor is detected for `interf init` so the listing shows it, but
+ * Interf cannot drive automated Build runs through Cursor today.
+ * `buildArgs` therefore throws.
+ */
+export const cursorProvider = {
+    name: "cursor",
+    displayName: "Cursor",
+    command: "cursor",
+    homeDir: join(homedir(), ".cursor"),
+    skillsDir: join(homedir(), ".cursor", "skills"),
+    supportsAutomatedRuns: false,
+    noiseFilters: [],
+    buildArgs() {
+        throw new Error('Cursor is not yet supported for automated Build runs.');
+    },
+    buildEnv(baseEnv) {
+        return { ...baseEnv };
+    },
+};

package/dist/packages/runtime/agents/providers/index.d.ts

@@ -0,0 +1,9 @@
+import type { AgentProvider } from "./types.js";
+export type { AgentProvider } from "./types.js";
+export declare const BUILT_IN_PROVIDERS: ReadonlyArray<AgentProvider>;
+/** Look up a built-in provider by name. Returns undefined for custom agents. */
+export declare function getBuiltInProvider(name: string): AgentProvider | undefined;
+/** True when `name` matches a built-in provider. */
+export declare function isBuiltInProviderName(name: string): boolean;
+/** All providers that support automated Build runs. */
+export declare function automatableBuiltInProviders(): AgentProvider[];

package/dist/packages/runtime/agents/providers/index.js

@@ -0,0 +1,31 @@
+/**
+ * Agent provider registry.
+ *
+ * The full set of built-in agent providers Interf knows about. Engine
+ * code consumes this list as data — there are no name comparisons or
+ * `if (agent === "codex")` branches outside the provider files.
+ *
+ * User-registered custom agents (`source: "user"` in the registry) flow
+ * through a separate generic provider that builds spawn args from a
+ * stored command template; that path lives outside this list.
+ */
+import { claudeCodeProvider } from "./claude-code.js";
+import { codexProvider } from "./codex.js";
+import { cursorProvider } from "./cursor.js";
+export const BUILT_IN_PROVIDERS = [
+    claudeCodeProvider,
+    codexProvider,
+    cursorProvider,
+];
+/** Look up a built-in provider by name. Returns undefined for custom agents. */
+export function getBuiltInProvider(name) {
+    return BUILT_IN_PROVIDERS.find((provider) => provider.name === name);
+}
+/** True when `name` matches a built-in provider. */
+export function isBuiltInProviderName(name) {
+    return BUILT_IN_PROVIDERS.some((provider) => provider.name === name);
+}
+/** All providers that support automated Build runs. */
+export function automatableBuiltInProviders() {
+    return BUILT_IN_PROVIDERS.filter((provider) => provider.supportsAutomatedRuns);
+}

package/dist/packages/runtime/agents/providers/types.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Agent provider contract.
+ *
+ * Every built-in agent (Claude Code, Codex, …) and every user-registered
+ * custom agent is exposed as an `AgentProvider`. The engine talks to
+ * providers through this interface — no `if (name === "codex")` branches
+ * anywhere outside `providers/<name>.ts`.
+ *
+ * The `Agent` interface in `../types.ts` remains a structural subset of
+ * `AgentProvider` so existing callers keep working while we migrate.
+ */
+import type { AgentExecutionProfile } from "../lib/executors.js";
+export interface AgentProvider {
+    /** Stable agent identifier. Engine code never branches on this value. */
+    name: string;
+    /** User-facing label. */
+    displayName: string;
+    /** Default command (first whitespace-separated token must resolve on PATH). */
+    command: string;
+    /** Where this agent stores its skills (used by detection + scaffolds). */
+    skillsDir: string;
+    /** Marker dir whose existence indicates the agent is installed locally. */
+    homeDir: string;
+    /**
+     * Whether Interf can drive this agent for automated Build runs today.
+     * Detection + the role-router consult this flag.
+     */
+    supportsAutomatedRuns: boolean;
+    /**
+     * Internal-acceptance defaults — the model + effort this provider uses
+     * when no explicit override is supplied during maintainer test runs.
+     * Normal user runs do not consume these unless they opt in.
+     */
+    defaultModel?: string;
+    defaultEffort?: string;
+    /**
+     * Stderr lines matching any of these regexps are treated as expected
+     * noise and suppressed from preflight failures + run logs.
+     */
+    noiseFilters: ReadonlyArray<RegExp>;
+    /** Build the spawn args for a `prompt` + execution profile. */
+    buildArgs(prompt: string, profile: AgentExecutionProfile): string[];
+    /** Build the spawn env from a base env (defaults to identity). */
+    buildEnv(baseEnv: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+    /**
+     * Optional. Return true when a preflight failure is transient and the
+     * caller should retry. Defaults to false when the method is absent.
+     */
+    isTransientPreflightFailure?(stderr: string, errorMessage: string): boolean;
+}

package/dist/packages/{engine → runtime}/agents/registry.d.ts

@@ -1,4 +1,4 @@
-import { type AgentRecord, type AgentsRegistry, type RoleMap } from "../../contracts/lib/schema.js";
+import { type AgentPrefs, type AgentPrefsMap, type AgentRecord, type AgentsRegistry, type RoleMap } from "../../contracts/lib/schema.js";
 export declare const AGENTS_REGISTRY_FILENAME = "agents.json";
 /** `~/.interf/agents.json` — persisted custom agents + role-map. */
 export declare function agentsRegistryPath(): string;
@@ -10,8 +10,19 @@ export declare function agentsRegistryPath(): string;
  * unreadable; persisted custom agents always have `source: "user"`.
  */
 export declare function loadPersistedRegistry(): AgentsRegistry;
-/** Persist the on-disk part of the registry (custom agents + role-map). */
+/** Persist the on-disk part of the registry (custom agents + role-map + prefs). */
 export declare function savePersistedRegistry(registry: AgentsRegistry): void;
+/**
+ * Read the prefs map without merging anything else. Used by callers that
+ * only need the per-agent overrides (e.g. the run-time spawn merger).
+ */
+export declare function loadAgentPrefs(): AgentPrefsMap;
+/**
+ * Update one agent's prefs. Pass an empty object (or nullable fields set
+ * to null) to clear a specific value; pass a fully empty record to remove
+ * that agent's entry entirely. Built-in or custom agent — same code path.
+ */
+export declare function setAgentPrefs(name: string, prefs: AgentPrefs): void;
 /**
  * Detect built-in agents present on this machine. Filtered to agents
  * whose marker home directory exists; we do NOT require the command

package/dist/packages/{engine → runtime}/agents/registry.js

@@ -6,7 +6,7 @@
  * are detected dynamically at read time and merged with the persisted
  * custom agents. The role-map IS persisted.
  *
- * 0.15 contract:
+ * contract:
  *   {
  *     "agents": [
  *       { "name": "opencode", "display_name": "OpenCode", "command": "opencode --prompt", "source": "user" }
@@ -22,9 +22,9 @@
  */
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { AgentRecordSchema, AgentsRegistrySchema, CANONICAL_ROLES, } from "../../contracts/lib/schema.js";
+import { AgentPrefsSchema, AgentRecordSchema, AgentsRegistrySchema, CANONICAL_ROLES, } from "../../contracts/lib/schema.js";
+import { interfHomeRoot } from "../../contracts/lib/project-paths.js";
 import { readJsonFileWithSchema } from "../../contracts/utils/parse.js";
-import { interfHomeRoot } from "../instance-paths.js";
 import { agentCommandAvailable, detectAgents, supportsAutomatedRuns } from "./lib/detection.js";
 import { AGENTS } from "./lib/constants.js";
 export const AGENTS_REGISTRY_FILENAME = "agents.json";
@@ -47,16 +47,44 @@ export function loadPersistedRegistry() {
     const value = readJsonFileWithSchema(path, "agents registry", AgentsRegistrySchema);
     return value ?? AgentsRegistrySchema.parse({});
 }
-/** Persist the on-disk part of the registry (custom agents + role-map). */
+/** Persist the on-disk part of the registry (custom agents + role-map + prefs). */
 export function savePersistedRegistry(registry) {
     const home = interfHomeRoot();
     mkdirSync(home, { recursive: true });
     const sanitized = {
-        agents: registry.agents.map(({ available: _available, ...agent }) => AgentRecordSchema.parse({ ...agent, source: "user" })),
+        agents: registry.agents.map(({ available: _available, prefs: _prefs, ...agent }) => AgentRecordSchema.parse({ ...agent, source: "user" })),
         role_map: { ...registry.role_map },
+        agent_prefs: { ...(registry.agent_prefs ?? {}) },
     };
     writeFileSync(agentsRegistryPath(), `${JSON.stringify(sanitized, null, 2)}\n`);
 }
+/**
+ * Read the prefs map without merging anything else. Used by callers that
+ * only need the per-agent overrides (e.g. the run-time spawn merger).
+ */
+export function loadAgentPrefs() {
+    return loadPersistedRegistry().agent_prefs ?? {};
+}
+/**
+ * Update one agent's prefs. Pass an empty object (or nullable fields set
+ * to null) to clear a specific value; pass a fully empty record to remove
+ * that agent's entry entirely. Built-in or custom agent — same code path.
+ */
+export function setAgentPrefs(name, prefs) {
+    const persisted = loadPersistedRegistry();
+    const next = { ...(persisted.agent_prefs ?? {}) };
+    const sanitized = AgentPrefsSchema.parse(prefs);
+    const empty = !sanitized.env_vars
+        && (sanitized.model === undefined || sanitized.model === null)
+        && (sanitized.effort === undefined || sanitized.effort === null);
+    if (empty) {
+        delete next[name];
+    }
+    else {
+        next[name] = sanitized;
+    }
+    savePersistedRegistry({ ...persisted, agent_prefs: next });
+}
 /**
  * Detect built-in agents present on this machine. Filtered to agents
  * whose marker home directory exists; we do NOT require the command
@@ -112,9 +140,13 @@ export function listKnownBuiltinAgents() {
  * against `which` so a stale `~/.interf/agents.json` entry does not
  * appear as a usable choice.
  */
-function mergeAgents(builtin, persisted) {
+function mergeAgents(builtin, persisted, prefsMap) {
     const seen = new Set(builtin.map((agent) => agent.name));
-    const merged = builtin.map((agent) => ({ ...agent, available: true }));
+    const merged = builtin.map((agent) => ({
+        ...agent,
+        available: true,
+        ...(prefsMap[agent.name] ? { prefs: prefsMap[agent.name] } : {}),
+    }));
     for (const agent of persisted) {
         if (seen.has(agent.name))
             continue;
@@ -123,6 +155,7 @@ function mergeAgents(builtin, persisted) {
             ...agent,
             source: "user",
             available: agentCommandAvailable(agent.command),
+            ...(prefsMap[agent.name] ? { prefs: prefsMap[agent.name] } : {}),
         });
     }
     return merged;
@@ -161,7 +194,7 @@ function buildDefaultRoleMap(agents) {
 export function loadAgentsRegistry() {
     const persisted = loadPersistedRegistry();
     const builtinDetected = detectAutomatableBuiltinAgentRecords();
-    const agents = mergeAgents(builtinDetected, persisted.agents);
+    const agents = mergeAgents(builtinDetected, persisted.agents, persisted.agent_prefs ?? {});
     // Seed the default role-map on first read when the persisted file
     // has no role-map entries AND we have at least one detectable agent.
     // (We do not write to disk yet; the seeded map is computed on the
@@ -180,7 +213,7 @@ export function loadAgentsRegistry() {
 }
 /** Pure helper — like `loadAgentsRegistry()` but works off in-memory data. */
 export function resolveRegistry(persisted, builtinDetected) {
-    const agents = mergeAgents(builtinDetected, persisted.agents);
+    const agents = mergeAgents(builtinDetected, persisted.agents, persisted.agent_prefs ?? {});
     const hasPersistedEntries = Object.keys(persisted.role_map).length > 0;
     const roleMap = hasPersistedEntries
         ? { ...persisted.role_map }
@@ -197,6 +230,7 @@ export function updateRoleMap(nextRoleMap) {
     const next = {
         agents: current.agents,
         role_map: { ...nextRoleMap },
+        agent_prefs: { ...(current.agent_prefs ?? {}) },
     };
     savePersistedRegistry(next);
     return next;
@@ -218,6 +252,7 @@ export function patchRoleMap(patch) {
     const updated = {
         agents: current.agents,
         role_map: next,
+        agent_prefs: { ...(current.agent_prefs ?? {}) },
     };
     savePersistedRegistry(updated);
     return updated;
@@ -252,6 +287,7 @@ export function registerCustomAgent(input) {
     const next = {
         agents: [...current.agents, record],
         role_map: { ...current.role_map },
+        agent_prefs: { ...(current.agent_prefs ?? {}) },
     };
     savePersistedRegistry(next);
     return next;
@@ -280,6 +316,7 @@ export function unregisterCustomAgent(name) {
     const next = {
         agents: remaining,
         role_map: trimmedRoleMap,
+        agent_prefs: { ...(current.agent_prefs ?? {}) },
     };
     savePersistedRegistry(next);
     return next;
@@ -298,7 +335,7 @@ export function setActiveAgent(name) {
         throw new Error("Agent name is required.");
     const persisted = loadPersistedRegistry();
     const builtinDetected = detectAutomatableBuiltinAgentRecords();
-    const agents = mergeAgents(builtinDetected, persisted.agents);
+    const agents = mergeAgents(builtinDetected, persisted.agents, persisted.agent_prefs ?? {});
     if (!agents.some((agent) => agent.name === trimmedName)) {
         throw new Error(`Agent "${trimmedName}" is not detected or registered. Install or register it before making it active.`);
     }
@@ -315,6 +352,7 @@ export function setActiveAgent(name) {
     const next = {
         agents: persisted.agents,
         role_map: nextRoleMap,
+        agent_prefs: { ...(persisted.agent_prefs ?? {}) },
     };
     savePersistedRegistry(next);
     return next;

package/dist/packages/{engine → runtime}/agents/role-executors.d.ts

@@ -27,7 +27,7 @@ export interface BuildRoleExecutorBundleInput {
     executionProfile?: AgentExecutionProfile;
 }
 /**
- * Build a per-role executor bundle from a registry snapshot. The
+ * Build a per-role executor bundle from registry state. The
  * `defaultExecutor` is what the pipeline already passes for the
  * single-active-agent case (so role lookups that fall through to
  * `fallback-active` resolve to the same executor).

package/dist/packages/{engine → runtime}/agents/role-executors.js

@@ -2,9 +2,9 @@
  * Role-aware executor factory.
  *
  * Bridges the registry layer (`AgentRecord` / `RoleMap`) to the runtime
- * layer (`AgentExecutor`). Builds a per-agent-name `AgentExecutor`
+ * layer (`AgentExecutor`). Creates a per-agent-name `AgentExecutor`
  * map up front and exposes a `resolveExecutorForRole(role)` helper that
- * the build / readiness-check pipelines can call per-stage.
+ * the build / benchmark pipelines can call per-stage.
  *
  * Falls back gracefully: when a role isn't mapped, or the mapped agent
  * is missing, we fall through to `general` and ultimately to the
@@ -33,20 +33,21 @@ function agentRecordToAgent(record) {
     };
 }
 /**
- * Build a per-role executor bundle from a registry snapshot. The
+ * Build a per-role executor bundle from registry state. The
  * `defaultExecutor` is what the pipeline already passes for the
  * single-active-agent case (so role lookups that fall through to
  * `fallback-active` resolve to the same executor).
  */
 export function buildRoleExecutorBundle(input) {
     const executors = new Map();
+    const executionProfile = input.executionProfile ?? input.defaultExecutor.executionProfile;
     for (const record of input.agents) {
         const agent = agentRecordToAgent(record);
-        executors.set(record.name, createLocalAgentExecutor(agent, input.executionProfile));
+        executors.set(record.name, createLocalAgentExecutor(agent, executionProfile));
     }
     // Make sure the active / default executor is reachable by name
     // even when the active agent isn't formally in the registry yet
-    // (e.g. legacy single-active setups during the 0.14 → 0.15 transition).
+    // (e.g. previous single-active setups inherited from older configs).
     if (input.activeAgent && !executors.has(input.activeAgent.name)) {
         executors.set(input.activeAgent.name, input.defaultExecutor);
     }
@@ -63,8 +64,9 @@ export function buildRoleExecutorBundle(input) {
             const result = resolveAgentForRole(role, context);
             if ("error" in result) {
                 // Role-router refused — fall back to the default executor and
-                // synthesize a `fallback-active` resolution. This keeps prepare
-                // runs alive when the registry is empty / mid-edit.
+                // synthesize a `fallback-active` resolution. This is the explicit
+                // single-active-agent compatibility path; callers surface the
+                // fallback source in run logs.
                 const synthetic = {
                     agent: input.activeAgent
                         ?? {

package/dist/packages/{engine → runtime}/agents/role-router.js

@@ -4,7 +4,9 @@
  * failure.
  */
 export function resolveAgentForRole(role, context) {
-    if (context.agents.length === 0) {
+    const availableAgents = context.agents.filter((agent) => agent.available !== false);
+    const activeAgent = context.activeAgent?.available === false ? null : context.activeAgent;
+    if (availableAgents.length === 0) {
         return {
             error: "no-agents",
             detail: "No agents are available. Install Claude Code, Codex, or another agent CLI, " +
@@ -15,7 +17,7 @@ export function resolveAgentForRole(role, context) {
     // 1. Explicit role-map entry for the requested role.
     const explicitName = context.roleMap[trimmedRole];
     if (explicitName) {
-        const found = context.agents.find((agent) => agent.name === explicitName);
+        const found = availableAgents.find((agent) => agent.name === explicitName);
         if (found) {
             return { agent: found, role: trimmedRole, source: "explicit" };
         }
@@ -29,16 +31,16 @@ export function resolveAgentForRole(role, context) {
     if (trimmedRole !== "general") {
         const generalName = context.roleMap["general"];
         if (generalName) {
-            const found = context.agents.find((agent) => agent.name === generalName);
+            const found = availableAgents.find((agent) => agent.name === generalName);
             if (found) {
                 return { agent: found, role: trimmedRole, source: "fallback-general" };
             }
         }
     }
     // 3. Active agent.
-    if (context.activeAgent) {
+    if (activeAgent) {
         return {
-            agent: context.activeAgent,
+            agent: activeAgent,
             role: trimmedRole,
             source: "fallback-active",
         };

package/dist/packages/runtime/auth/account-context.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Account context types.
+ *
+ * The current account is a small projection of the WorkOS user identity +
+ * Stripe subscription state that the engine and CLI carry around for the
+ * lifetime of a session. It is populated at engine boot from
+ * `~/.interf/auth/session.json`, when present, and is null for unauthenticated
+ * (loopback-only, free-tier) sessions.
+ *
+ * No vendor types are imported here — the engine treats this as a stable
+ * shape and providers (WorkOS today, future swaps) map their domain into it.
+ */
+export type AccountPlan = "free" | "pro" | "enterprise" | "anonymous";
+export interface AccountEntitlements {
+    /** Maximum number of active Projects this account may create. */
+    max_active_projects: number;
+    /** Pro features unlocked by the current plan. */
+    pro_features: ReadonlyArray<string>;
+}
+export interface CurrentAccount {
+    /** Stable account / user identifier (WorkOS user id, e.g. `user_01H...`). */
+    user_id: string;
+    /** Display email captured at last login. */
+    email: string;
+    /** Display name (optional; falls back to the email local-part in the UI). */
+    display_name: string | null;
+    /** Subscription tier. */
+    plan: AccountPlan;
+    /** Computed entitlements for the current plan. */
+    entitlements: AccountEntitlements;
+    /** ISO timestamp the session was last refreshed (used for TTL checks). */
+    refreshed_at: string;
+}
+/**
+ * Tier defaults — feature-based, not usage-based.
+ *
+ * Three tiers ship; Teams is a "coming soon" marketing surface, not a real
+ * plan, so it has no entry here. The Free cap is the conversion lever;
+ * Pro removes it. Enterprise is structurally different from Pro — not a
+ * bigger Pro bundle but a separate self-hosted deployment with SSO + audit
+ * log + governance + custom support.
+ *
+ * Pro features carry through the locked strategy:
+ *   - benchmarks (Pro: unlimited; Free: one run)
+ *   - self-improving Build Plans
+ *   - multi-source per Project
+ *   - scheduled resyncs
+ *   - export bundles
+ *   - API access
+ */
+export declare const TIER_ENTITLEMENTS: Record<AccountPlan, AccountEntitlements>;
+export declare function entitlementsForPlan(plan: AccountPlan): AccountEntitlements;

package/dist/packages/runtime/auth/account-context.js

@@ -0,0 +1,68 @@
+/**
+ * Account context types.
+ *
+ * The current account is a small projection of the WorkOS user identity +
+ * Stripe subscription state that the engine and CLI carry around for the
+ * lifetime of a session. It is populated at engine boot from
+ * `~/.interf/auth/session.json`, when present, and is null for unauthenticated
+ * (loopback-only, free-tier) sessions.
+ *
+ * No vendor types are imported here — the engine treats this as a stable
+ * shape and providers (WorkOS today, future swaps) map their domain into it.
+ */
+/**
+ * Tier defaults — feature-based, not usage-based.
+ *
+ * Three tiers ship; Teams is a "coming soon" marketing surface, not a real
+ * plan, so it has no entry here. The Free cap is the conversion lever;
+ * Pro removes it. Enterprise is structurally different from Pro — not a
+ * bigger Pro bundle but a separate self-hosted deployment with SSO + audit
+ * log + governance + custom support.
+ *
+ * Pro features carry through the locked strategy:
+ *   - benchmarks (Pro: unlimited; Free: one run)
+ *   - self-improving Build Plans
+ *   - multi-source per Project
+ *   - scheduled resyncs
+ *   - export bundles
+ *   - API access
+ */
+export const TIER_ENTITLEMENTS = {
+    anonymous: {
+        max_active_projects: 10,
+        pro_features: [],
+    },
+    free: {
+        max_active_projects: 10,
+        pro_features: [],
+    },
+    pro: {
+        max_active_projects: Number.POSITIVE_INFINITY,
+        pro_features: [
+            "benchmarking-unlimited",
+            "self-improving-build-plans",
+            "multi-source-per-project",
+            "scheduled-resyncs",
+            "flow-export",
+            "api-access",
+        ],
+    },
+    enterprise: {
+        max_active_projects: Number.POSITIVE_INFINITY,
+        pro_features: [
+            "benchmarking-unlimited",
+            "self-improving-build-plans",
+            "multi-source-per-project",
+            "scheduled-resyncs",
+            "flow-export",
+            "api-access",
+            "sso",
+            "audit-log",
+            "governance",
+            "self-hosted",
+        ],
+    },
+};
+export function entitlementsForPlan(plan) {
+    return TIER_ENTITLEMENTS[plan] ?? TIER_ENTITLEMENTS.anonymous;
+}

package/dist/packages/runtime/auth/auth-flow.d.ts

@@ -0,0 +1,73 @@
+/**
+ * PKCE auth flow orchestration.
+ *
+ * Drives the public-client OAuth dance: spawns a loopback HTTP server on
+ * 127.0.0.1, asks WorkOS for an authorize URL bound to that server's
+ * dynamic port, opens the user's browser at AuthKit, and waits for the
+ * callback. On callback, the returned `state` is checked against the SDK-
+ * generated value and the `code` is exchanged for `{ user, accessToken,
+ * refreshToken }` via `authenticateWithCode` with the stored `codeVerifier`.
+ *
+ * No part of this module touches `~/.interf/auth/*`. Callers (CLI today,
+ * desktop shell later) take the returned tokens and decide what to persist.
+ *
+ * The `transport` seam lets tests stand in for the WorkOS SDK without env
+ * config or live HTTP. Production callers use `defaultPkceTransport()`.
+ */
+/** Shape we need from the WorkOS SDK. Narrowed so the seam is small. */
+export interface PkceTransport {
+    getAuthorizationUrlWithPKCE(input: {
+        provider: "authkit";
+        redirectUri: string;
+        clientId: string;
+        loginHint?: string;
+    }): Promise<{
+        url: string;
+        state: string;
+        codeVerifier: string;
+    }>;
+    authenticateWithCode(input: {
+        code: string;
+        codeVerifier: string;
+        clientId: string;
+    }): Promise<AuthenticationResult>;
+}
+/** Minimum AuthenticationResponse fields we care about. */
+export interface AuthenticationResult {
+    user: {
+        id: string;
+        email: string;
+        firstName?: string | null;
+        lastName?: string | null;
+    };
+    accessToken: string;
+    refreshToken: string;
+}
+export interface PkceFlowOptions {
+    /** Loopback host to bind. Default 127.0.0.1. */
+    callbackHost?: string;
+    /** Loopback port to bind. Default 0 (OS-assigned). */
+    callbackPort?: number;
+    /** Open the user's browser automatically. Default true. */
+    autoOpenBrowser?: boolean;
+    /** Prefill the AuthKit email field. */
+    loginHint?: string;
+    /** Hard timeout waiting for callback. Default 5 min. */
+    timeoutMs?: number;
+    /** Test hook fired after authorize URL is built. Receives `(url, redirectUri)`. */
+    onAuthorizeUrl?: (url: string, redirectUri: string) => Promise<void> | void;
+}
+export declare class AuthFlowError extends Error {
+    constructor(message: string);
+}
+/**
+ * Default transport — proxies to the real WorkOS SDK. Lazy-loads the
+ * singleton client on first call so importing this module does not require
+ * env config.
+ */
+export declare function defaultPkceTransport(): PkceTransport;
+/**
+ * Run the full PKCE flow end-to-end. Returns the WorkOS tokens + user.
+ * Always closes the loopback server before returning, even on error.
+ */
+export declare function runPkceFlow(transport: PkceTransport, options?: PkceFlowOptions): Promise<AuthenticationResult>;