@stdiobus/workers-registry 1.4.14 → 1.5.0-beta.2

package/out/tsc/workers-registry/registry-launcher/src/router/message-router.d.ts

@@ -0,0 +1,770 @@
+/**
+ * Message Router for the Registry Launcher.
+ *
+ * Routes incoming JSON-RPC messages to the appropriate agent based on agentId.
+ * Handles agentId extraction, message transformation, and error response generation.
+ * Integrates with AuthManager for OAuth authentication (Requirements 11.2, 11.4).
+ *
+ * @module router/message-router
+ */
+import { spawn } from 'node:child_process';
+import type { IRegistryIndex } from '../registry/index.js';
+import type { AgentRuntimeManager } from '../runtime/manager.js';
+import type { AuthManager } from '../auth/auth-manager.js';
+import type { AcpAuthMethod, AuthProviderId } from '../auth/types.js';
+/**
+ * JSON-RPC error codes for routing errors.
+ */
+export declare const RoutingErrorCodes: {
+    /** Missing agentId in request */
+    readonly MISSING_AGENT_ID: -32600;
+    /** Agent not found in registry */
+    readonly AGENT_NOT_FOUND: -32001;
+    /** Platform not supported for binary distribution */
+    readonly PLATFORM_NOT_SUPPORTED: -32002;
+    /** Agent spawn failed */
+    readonly SPAWN_FAILED: -32003;
+    /** Authentication required (Requirement 11.2) */
+    readonly AUTH_REQUIRED: -32004;
+};
+/**
+ * Valid auth method types from agent responses.
+ * - 'oauth2': Standard OAuth 2.1 flow (client handles OAuth)
+ * - 'agent': Agent handles OAuth internally (ACP-compliant, default)
+ * - 'terminal': Interactive terminal auth (TUI)
+ * - 'api-key': API key authentication
+ */
+export type AuthMethodType = 'oauth2' | 'agent' | 'terminal' | 'api-key';
+/**
+ * Parsed auth method with validated fields.
+ * Discriminated union for type-safe handling.
+ */
+export type ParsedAuthMethod = {
+    kind: 'oauth2';
+    id: string;
+    providerId: AuthProviderId;
+} | {
+    kind: 'agent';
+    id: string;
+    providerId?: AuthProviderId;
+} | {
+    kind: 'terminal';
+    id: string;
+    args?: string[];
+    env?: Record<string, string>;
+} | {
+    kind: 'api-key';
+    id: string;
+    providerId?: AuthProviderId;
+};
+/**
+ * Explicit mapping from auth method IDs to provider IDs.
+ * Security: Uses explicit allowlist mapping, no substring heuristics.
+ *
+ * Requirement 3.1: Support OAuth authentication with type "agent" or "oauth2"
+ * Requirement 11.2: Map authMethod.id to AuthProviderId
+ */
+export declare const AUTH_METHOD_ID_TO_PROVIDER: Readonly<Record<string, AuthProviderId>>;
+/**
+ * Parse and validate auth methods from agent initialize response.
+ *
+ * Extracts type and providerId from each auth method, using explicit mapping
+ * for id-to-provider resolution. Validates all fields and rejects invalid methods.
+ *
+ * Security considerations:
+ * - Uses explicit allowlist for method types
+ * - Uses explicit mapping for id-to-provider (no substring heuristics)
+ * - Validates providerId against known providers
+ * - Limits number of methods processed (DoS protection)
+ * - Deduplicates by method ID
+ *
+ * Requirement 3.1: Identify methods with type "oauth2" or "agent"
+ * Requirement 11.2: Map authMethod.id to AuthProviderId using explicit mapping
+ *
+ * @param raw - Raw auth methods array from agent response (untrusted input)
+ * @returns Array of validated and parsed auth methods
+ */
+export declare function parseAuthMethods(raw: unknown): ParsedAuthMethod[];
+/**
+ * Filter parsed auth methods to get only OAuth methods.
+ *
+ * Requirement 3.1: Identify methods with type "oauth2" or "agent"
+ *
+ * @param methods - Parsed auth methods
+ * @returns Only OAuth methods (kind: 'oauth2')
+ */
+export declare function getOAuthMethods(methods: ParsedAuthMethod[]): Array<ParsedAuthMethod & {
+    kind: 'oauth2';
+}>;
+/**
+ * Filter parsed auth methods to get only Agent Auth methods.
+ *
+ * AUTH_REQUIREMENTS.md: Agent Auth is the default authentication method
+ * where the agent manages the entire OAuth flow independently.
+ *
+ * @param methods - Parsed auth methods
+ * @returns Only Agent Auth methods (kind: 'agent')
+ */
+export declare function getAgentAuthMethods(methods: ParsedAuthMethod[]): Array<ParsedAuthMethod & {
+    kind: 'agent';
+}>;
+/**
+ * Filter parsed auth methods to get only Terminal Auth methods.
+ *
+ * AUTH_REQUIREMENTS.md: Terminal Auth enables agents to run an interactive
+ * setup experience within a terminal environment.
+ *
+ * @param methods - Parsed auth methods
+ * @returns Only Terminal Auth methods (kind: 'terminal')
+ */
+export declare function getTerminalAuthMethods(methods: ParsedAuthMethod[]): Array<ParsedAuthMethod & {
+    kind: 'terminal';
+}>;
+/**
+ * Filter parsed auth methods to get only API key methods.
+ *
+ * @param methods - Parsed auth methods
+ * @returns Only API key methods (kind: 'api-key')
+ */
+export declare function getApiKeyMethods(methods: ParsedAuthMethod[]): Array<ParsedAuthMethod & {
+    kind: 'api-key';
+}>;
+/**
+ * JSON-RPC error response structure.
+ */
+export interface ErrorResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    error: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+/**
+ * Authentication state for an agent.
+ *
+ * State transitions:
+ * - none → pending: OAuth flow initiated
+ * - pending → authenticated: OAuth flow succeeded
+ * - pending → failed: OAuth flow failed or timed out
+ * - failed → pending: Retry OAuth flow
+ * - authenticated → none: Logout or token invalidation
+ *
+ * Requirement 3.1: Track auth state during OAuth 2.1 Authorization Code flow
+ * Requirement 3.5: Handle timeout transitions to failed state
+ */
+export type AuthState = 'none' | 'pending' | 'authenticated' | 'failed';
+/**
+ * Queued request structure for requests waiting on OAuth authentication.
+ *
+ * When an OAuth flow is pending for an agent, incoming requests are queued
+ * and resumed after successful authentication.
+ *
+ * Requirement 3.1: Queue requests while OAuth flow is in progress
+ */
+export interface QueuedRequest {
+    /** The original message to be routed */
+    message: object;
+    /** Timestamp when the request was queued */
+    queuedAt: number;
+    /** Resolve function to signal completion */
+    resolve: (result: ErrorResponse | undefined) => void;
+}
+/**
+ * Pending authenticate request tracking structure.
+ *
+ * Tracks authenticate JSON-RPC requests sent to agents for Agent Auth flow.
+ * Used to correlate authenticate responses with the original auth flow.
+ *
+ * AUTH_REQUIREMENTS.md: Agent Auth - client calls authenticate method on agent
+ */
+export interface PendingAuthenticateRequest {
+    /** The authenticate request ID */
+    requestId: string;
+    /** The agent ID */
+    agentId: string;
+    /** The auth method ID from authMethods */
+    authMethodId: string;
+    /** Timestamp when the request was sent */
+    sentAt: number;
+    /** Resolve function to signal completion */
+    resolve: (success: boolean, error?: string) => void;
+}
+/**
+ * Callback type for writing responses to stdout.
+ */
+export type WriteCallback = (message: object) => boolean;
+/**
+ * Create a JSON-RPC error response.
+ *
+ * @param id - Request ID (null for notifications or unknown)
+ * @param code - Error code
+ * @param message - Error message
+ * @param data - Optional additional error data
+ * @returns Error response object
+ */
+export declare function createErrorResponse(id: string | number | null, code: number, message: string, data?: unknown): ErrorResponse;
+/**
+ * Extract the agentId field from a message.
+ *
+ * @param message - The message object to extract from
+ * @returns The agentId string or undefined if not present
+ */
+export declare function extractAgentId(message: object): string | undefined;
+/**
+ * Extract the JSON-RPC id field from a message.
+ *
+ * @param message - The message object to extract from
+ * @returns The id (string, number, or null)
+ */
+export declare function extractId(message: object): string | number | null;
+/**
+ * Transform a message for forwarding to an agent.
+ *
+ * Removes the agentId field while preserving all other fields.
+ *
+ * @param message - The original message
+ * @returns A new message object without the agentId field
+ */
+export declare function transformMessage(message: object): object;
+/**
+ * Spawn function type for dependency injection in tests.
+ */
+export type SpawnFn = typeof spawn;
+/**
+ * Optional dependencies for MessageRouter (for testing).
+ */
+export interface MessageRouterDeps {
+    /** Custom spawn function (default: child_process.spawn) */
+    spawnFn?: SpawnFn;
+    /** Custom function to check if stdin is TTY (default: process.stdin.isTTY) */
+    isStdinTTY?: () => boolean;
+    /** Custom function to check if stdout is TTY (default: process.stdout.isTTY) */
+    isStdoutTTY?: () => boolean;
+}
+/**
+ * Message Router implementation.
+ *
+ * Routes incoming JSON-RPC messages to the appropriate agent based on agentId.
+ * Handles message transformation, error generation, and request correlation.
+ * Integrates with AuthManager for OAuth authentication (Requirements 11.2, 11.4).
+ * Implements auth state machine for pending OAuth flows (Task 21.3).
+ */
+export declare class MessageRouter {
+    /** Registry index for agent lookup and resolution */
+    private readonly registry;
+    /** Runtime manager for agent process lifecycle */
+    private readonly runtimeManager;
+    /** Callback for writing responses to stdout */
+    private readonly writeCallback;
+    /** API keys for agent authentication */
+    private readonly apiKeys;
+    /** Spawn function for Terminal Auth (injectable for testing) */
+    private readonly spawnFn;
+    /** Function to check if stdin is TTY (injectable for testing) */
+    private readonly isStdinTTY;
+    /** Function to check if stdout is TTY (injectable for testing) */
+    private readonly isStdoutTTY;
+    /** Optional AuthManager for OAuth authentication (Requirements 11.2, 11.4) */
+    private readonly authManager?;
+    /** Map of request ID to pending request info for correlation */
+    private readonly pendingRequests;
+    /**
+     * Map of agent ID to authentication state.
+     *
+     * State machine (Task 21.3):
+     * - none: No authentication in progress
+     * - pending: OAuth flow in progress, requests are queued
+     * - authenticated: OAuth flow completed successfully
+     * - failed: OAuth flow failed or timed out
+     *
+     * Requirement 3.1: Track auth state during OAuth 2.1 Authorization Code flow
+     */
+    private readonly authState;
+    /**
+     * Map of agent ID to required OAuth provider ID.
+     *
+     * Tracks which agents require OAuth authentication and with which provider.
+     * This is populated when we receive an initialize response with authMethods
+     * containing OAuth methods.
+     *
+     * Requirement 11.2: Track auth requirements to block requests when OAuth
+     * is required but credentials are not available.
+     */
+    private readonly agentOAuthRequirements;
+    /**
+     * Map of agent ID to queued requests waiting for OAuth authentication.
+     *
+     * When an OAuth flow is pending for an agent, incoming requests are queued
+     * here and processed after successful authentication.
+     *
+     * Requirement 3.1: Queue incoming requests while OAuth flow is pending
+     */
+    private readonly requestQueue;
+    /**
+     * Map of authenticate request ID to pending authenticate request info.
+     *
+     * Tracks authenticate JSON-RPC requests sent to agents for Agent Auth flow.
+     * Used to correlate authenticate responses with the original auth flow.
+     *
+     * AUTH_REQUIREMENTS.md: Agent Auth - client calls authenticate method on agent
+     */
+    private readonly pendingAuthenticateRequests;
+    /** Map of agent sessionId to client sessionId for notification routing */
+    private readonly sessionIdMap;
+    /**
+     * Whether to automatically trigger OAuth browser flow when agent requires it.
+     * When false, returns AUTH_REQUIRED error instead of opening browser.
+     * Controlled by AUTH_AUTO_OAUTH environment variable (default: false for safety).
+     */
+    private readonly autoOAuth;
+    /**
+     * Create a new MessageRouter.
+     *
+     * @param registry - Registry index for agent lookup
+     * @param runtimeManager - Runtime manager for agent processes
+     * @param writeCallback - Callback for writing responses to stdout
+     * @param apiKeys - API keys for agent authentication (optional)
+     * @param authManager - AuthManager for OAuth authentication (optional, Requirements 11.2, 11.4)
+     * @param autoOAuth - Whether to auto-trigger OAuth browser flow (default: from AUTH_AUTO_OAUTH env, or false)
+     * @param deps - Optional dependencies for testing (spawnFn, TTY checks)
+     */
+    constructor(registry: IRegistryIndex, runtimeManager: AgentRuntimeManager, writeCallback: WriteCallback, apiKeys?: Record<string, any>, authManager?: AuthManager, autoOAuth?: boolean, deps?: MessageRouterDeps);
+    /**
+     * Get auto-OAuth setting from environment variable.
+     * AUTH_AUTO_OAUTH=true enables auto-OAuth, any other value or unset disables it.
+     */
+    private getAutoOAuthFromEnv;
+    /**
+     * Get supported authentication methods for ACP initialize response.
+     *
+     * Requirement 11.1: WHEN responding to an initialize request, THE Registry_Launcher
+     * SHALL include an `authMethods` array listing supported authentication methods.
+     *
+     * @returns Array of supported authentication methods
+     */
+    getSupportedAuthMethods(): AcpAuthMethod[];
+    /**
+     * Check if authentication is available for an agent.
+     *
+     * Requirement 11.2: WHEN an agent requires authentication and credentials are not available,
+     * THE Registry_Launcher SHALL return an AUTH_REQUIRED error response.
+     *
+     * @param agentId - The agent identifier
+     * @returns True if authentication is available (OAuth or legacy API key)
+     */
+    hasAuthenticationForAgent(agentId: string): Promise<boolean>;
+    /**
+     * Check if api-key credentials are available for an agent.
+     * This is a synchronous check for api-keys.json credentials.
+     *
+     * @param agentId - The agent identifier
+     * @returns True if api-key credentials are available
+     */
+    hasCredentialsForAgent(agentId: string): boolean;
+    /**
+     * Create an AUTH_REQUIRED error response.
+     *
+     * Requirement 11.2: WHEN an agent requires authentication and credentials are not available,
+     * THE Registry_Launcher SHALL return an AUTH_REQUIRED error response with the required
+     * authentication method specified.
+     *
+     * @param id - The request ID
+     * @param agentId - The agent identifier
+     * @param requiredMethod - The required authentication method
+     * @returns AUTH_REQUIRED error response
+     */
+    createAuthRequiredError(id: string | number | null, agentId: string, requiredMethod?: string): ErrorResponse;
+    /**
+     * Inject authentication into a request using AuthManager.
+     *
+     * Requirement 11.4: WHEN authentication is successful, THE Auth_Module SHALL inject
+     * the access token into agent requests according to the provider's token injection method.
+     *
+     * @param agentId - The agent identifier
+     * @param message - The message to inject auth into
+     * @returns The message with authentication injected
+     */
+    injectAuthentication(agentId: string, message: object): Promise<object>;
+    /**
+     * Inject mcpServers from registry into session/new request params.
+     *
+     * If the agent has mcpServers configured in the registry, they are merged
+     * with any mcpServers already present in the request params.
+     * Registry servers are added first, then request servers (request takes precedence for duplicates).
+     *
+     * @param message - The transformed message (without agentId)
+     * @param agentId - The agent ID to look up in registry
+     * @returns Message with mcpServers injected into params
+     */
+    private injectMcpServers;
+    /**
+     * Route an incoming message to the appropriate agent.
+     *
+     * Extracts agentId, resolves spawn command, and forwards message.
+     * If OAuth authentication is pending for the agent, queues the request
+     * and resumes it after successful authentication (Task 21.3).
+     *
+     * Requirement 3.1: Queue incoming requests while OAuth flow is pending
+     * Requirement 11.2: Block requests when OAuth required but not authenticated
+     *
+     * @param message - The incoming JSON-RPC message
+     * @returns Error response if routing fails, undefined on success
+     */
+    route(message: object): Promise<ErrorResponse | undefined>;
+    /**
+     * Check if OAuth credentials are available for an agent.
+     *
+     * Requirement 11.2: Check if credentials are available before routing.
+     *
+     * @param agentId - The agent identifier
+     * @param providerId - The OAuth provider ID
+     * @returns True if OAuth credentials are available
+     */
+    private hasOAuthCredentialsForAgent;
+    /**
+     * Create an AUTH_REQUIRED error response with provider information.
+     *
+     * Requirement 11.2: WHEN an agent requires authentication and credentials are not available,
+     * THE Registry_Launcher SHALL return an AUTH_REQUIRED error response with the required
+     * authentication method specified.
+     *
+     * @param id - The request ID
+     * @param agentId - The agent identifier
+     * @param providerId - The required OAuth provider ID (optional)
+     * @returns AUTH_REQUIRED error response with requiredMethod, supportedMethods, providerId
+     */
+    private createAuthRequiredErrorWithProvider;
+    /**
+     * Internal routing logic after auth state checks.
+     *
+     * @param message - The incoming JSON-RPC message
+     * @param agentId - The agent identifier
+     * @param id - The request ID
+     * @returns Error response if routing fails, undefined on success
+     */
+    private routeInternal;
+    /**
+     * Get the current authentication state for an agent.
+     *
+     * @param agentId - The agent identifier
+     * @returns The current auth state (defaults to 'none')
+     */
+    getAuthState(agentId: string): AuthState;
+    /**
+     * Set the authentication state for an agent.
+     *
+     * Handles state transitions and triggers appropriate actions:
+     * - none → pending: OAuth flow started
+     * - pending → authenticated: Resume queued requests
+     * - pending → failed: Reject queued requests with AUTH_REQUIRED
+     *
+     * Requirement 3.1: Track auth state during OAuth flow
+     * Requirement 3.5: Handle timeout transitions to failed state
+     *
+     * @param agentId - The agent identifier
+     * @param newState - The new auth state
+     */
+    setAuthState(agentId: string, newState: AuthState): void;
+    /**
+     * Queue a request while OAuth authentication is pending.
+     *
+     * Returns a promise that resolves when the request is processed
+     * (either routed successfully or rejected with an error).
+     *
+     * Requirement 3.1: Queue incoming requests while OAuth flow is pending
+     *
+     * @param agentId - The agent identifier
+     * @param message - The message to queue
+     * @returns Promise that resolves with the routing result
+     */
+    private queueRequest;
+    /**
+     * Handle timeout for a queued request.
+     *
+     * If the request is still in the queue when timeout fires,
+     * remove it and resolve with a timeout error.
+     *
+     * Requirement 3.5: Handle timeout for queued requests
+     *
+     * @param agentId - The agent identifier
+     * @param queuedRequest - The queued request that timed out
+     */
+    private handleQueuedRequestTimeout;
+    /**
+     * Process queued requests after successful OAuth authentication.
+     *
+     * Routes all queued requests for the agent now that authentication
+     * is complete.
+     *
+     * Requirement 3.1: Resume queued requests after successful authentication
+     *
+     * @param agentId - The agent identifier
+     */
+    private processQueuedRequests;
+    /**
+     * Reject all queued requests after OAuth authentication failure.
+     *
+     * Returns AUTH_REQUIRED error for all queued requests.
+     *
+     * Requirement 3.5: Handle failed authentication for queued requests
+     *
+     * @param agentId - The agent identifier
+     */
+    private rejectQueuedRequests;
+    /**
+     * Get the number of queued requests for an agent.
+     *
+     * @param agentId - The agent identifier
+     * @returns The number of queued requests
+     */
+    getQueuedRequestCount(agentId: string): number;
+    /**
+     * Get the total number of queued requests across all agents.
+     *
+     * @returns The total number of queued requests
+     */
+    getTotalQueuedRequestCount(): number;
+    /**
+     * Handle a response from an agent process.
+     *
+     * Intercepts initialize responses to trigger automatic authentication and
+     * inject authMethods (Requirement 11.1).
+     * Handles agent-to-client requests (like session/request_permission) by
+     * auto-responding when they cannot be forwarded to the client.
+     * Tracks sessionId mapping for proper notification routing.
+     * Handles authenticate responses for Agent Auth flow (Task 35.2).
+     * Forwards all responses to stdout.
+     *
+     * @param agentId - The agent that sent the response
+     * @param response - The response object from the agent
+     */
+    handleAgentResponse(agentId: string, response: object): void;
+    /**
+     * Handle a request from an agent to the client.
+     *
+     * Agent-to-client requests (JSON-RPC messages with both `id` and `method`)
+     * require a response. Since the Registry Launcher is headless and cannot
+     * forward these to a human, we auto-respond to keep the agent unblocked.
+     *
+     * Known methods:
+     * - session/request_permission: Auto-approve with the first "allow" option
+     *
+     * Unknown methods get a generic success response so the agent continues.
+     *
+     * @param agentId - The agent that sent the request
+     * @param id - The JSON-RPC request id
+     * @param method - The JSON-RPC method name
+     * @param msg - The full message object
+     */
+    private handleAgentRequest;
+    /**
+     * Build an auto-approve result for session/request_permission.
+     *
+     * Picks the first "allow" option from the request, preferring
+     * allow_always > allow_once > first option as fallback.
+     *
+     * @param msg - The request_permission message
+     * @returns The result object for the response
+     */
+    private buildPermissionResponse;
+    /**
+     * Handle an authenticate response from an agent.
+     *
+     * Task 35.2: Handle authenticate response
+     * - On success: resolve the pending authenticate request with success
+     * - On error: resolve with failure and log the error
+     *
+     * AUTH_REQUIREMENTS.md: Agent Auth - after agent completes OAuth flow,
+     * it responds to the authenticate request.
+     *
+     * @param pendingAuth - The pending authenticate request
+     * @param response - The response from the agent
+     */
+    private handleAuthenticateResponse;
+    /**
+     * Send a JSON-RPC message directly to an agent process.
+     *
+     * @param agentId - The agent to send to
+     * @param message - The message to send
+     */
+    private sendToAgent;
+    /**
+     * Attempt automatic authentication for an agent.
+     *
+     * Selects the best authentication method and initiates authentication.
+     * Uses parsed auth methods with validated types and provider IDs.
+     *
+     * Authentication method precedence (AUTH_REQUIREMENTS.md):
+     * 1. Agent Auth (type: "agent" or no type) - agent handles OAuth internally
+     * 2. OAuth methods (type: "oauth2") - client handles browser-based flow
+     * 3. API key methods - only if no OAuth methods are present
+     *
+     * AUTH_REQUIREMENTS.md: Agent Auth is the default authentication method
+     * where the agent manages the entire OAuth flow independently.
+     *
+     * @param agentId - The agent to authenticate
+     * @param authMethods - Parsed and validated authentication methods (Task 21.1)
+     */
+    private attemptAuthentication;
+    /**
+     * Attempt Agent Auth authentication for an agent.
+     *
+     * AUTH_REQUIREMENTS.md: Agent Auth - client calls `authenticate` method on agent,
+     * agent handles: HTTP server, browser launch, OAuth callback, token storage.
+     *
+     * Task 35.1: Call `authenticate` JSON-RPC method on agent
+     * - Send: { jsonrpc: "2.0", method: "authenticate", params: { id: authMethod.id }, id: requestId }
+     * - Wait for response from agent
+     *
+     * Task 35.2: Handle authenticate response
+     * - On success: retry original request (session/new)
+     * - On error: return error to client
+     *
+     * @param agentId - The agent to authenticate
+     * @param agentAuthMethods - Agent Auth methods from agent's authMethods
+     */
+    private attemptAgentAuthentication;
+    /**
+     * Call the `authenticate` JSON-RPC method on an agent.
+     *
+     * AUTH_REQUIREMENTS.md: Agent Auth - client calls authenticate method on agent
+     * Send: { jsonrpc: "2.0", method: "authenticate", params: { id: authMethod.id }, id: requestId }
+     *
+     * Task 35.1: Call `authenticate` JSON-RPC method on agent
+     *
+     * @param agentId - The agent to authenticate
+     * @param authMethodId - The auth method ID from authMethods
+     * @param runtime - The agent runtime
+     * @returns Promise that resolves to true on success, false on failure
+     */
+    private callAgentAuthenticate;
+    /**
+     * Attempt Terminal Auth authentication for an agent.
+     *
+     * AUTH_REQUIREMENTS.md: Terminal Auth - client spawns agent binary with args/env
+     * from authMethod for interactive TUI setup.
+     *
+     * Task 36.1: Parse Terminal Auth from authMethods
+     * Task 36.2: Launch agent binary with args/env
+     * Task 36.3: Retry after Terminal Auth
+     *
+     * Flow:
+     * 1. Stop current agent runtime (if running)
+     * 2. Spawn agent with args/env from authMethod (stdio: 'inherit' for TUI)
+     * 3. Wait for process exit
+     * 4. On exit code 0: restart normal runtime and verify auth
+     * 5. On non-zero exit: mark as failed
+     *
+     * @param agentId - The agent to authenticate
+     * @param terminalAuthMethods - Terminal Auth methods from agent's authMethods
+     */
+    private attemptTerminalAuthentication;
+    /**
+     * Run the Terminal Auth process with inherited stdio for interactive TUI.
+     *
+     * @param command - The command to execute
+     * @param args - Command-line arguments
+     * @param env - Environment variables
+     * @returns Promise that resolves to the exit code
+     */
+    private runTerminalAuthProcess;
+    /**
+     * Verify that Terminal Auth was successful by restarting the agent
+     * and checking if authentication is now available.
+     *
+     * @param agentId - The agent to verify
+     * @returns true if auth is now available, false otherwise
+     */
+    private verifyTerminalAuthSuccess;
+    /**
+     * Attempt OAuth authentication for an agent using browser-based flow.
+     *
+     * Requirement 3.1: WHEN an agent requires OAuth authentication with `type: "agent"`,
+     * THE Auth_Module SHALL initiate the OAuth 2.1 Authorization Code flow with PKCE.
+     *
+     * Requirement 3.2: WHEN initiating the authorization flow, THE Auth_Module SHALL
+     * open the system default browser to the provider's authorization URL.
+     *
+     * @param agentId - The agent to authenticate
+     * @param oauthMethods - OAuth methods from agent's authMethods (already validated)
+     */
+    private attemptOAuthAuthentication;
+    /**
+     * Send OAuth credentials to agent after successful browser-based authentication.
+     *
+     * After the OAuth flow completes successfully, this method retrieves the token
+     * from AuthManager and sends an authenticate request to the agent.
+     *
+     * @param agentId - The agent to send credentials to
+     * @param method - The OAuth method used for authentication
+     */
+    private sendOAuthCredentialsToAgent;
+    /**
+     * Attempt API key authentication for an agent.
+     *
+     * This is the fallback authentication method when no OAuth methods are present.
+     * Uses the legacy api-keys.json configuration.
+     *
+     * @param agentId - The agent to authenticate
+     * @param authMethods - Parsed authentication methods (already validated)
+     */
+    private attemptApiKeyAuthentication;
+    /**
+     * Get the number of pending requests.
+     *
+     * @returns The count of pending requests
+     */
+    get pendingCount(): number;
+    /**
+     * Check if a request ID is pending.
+     *
+     * @param id - The request ID to check
+     * @returns true if the request is pending, false otherwise
+     */
+    isPending(id: string | number): boolean;
+    /**
+     * Clear all pending requests.
+     * Useful for cleanup during shutdown.
+     */
+    clearPending(): void;
+    /**
+     * Clear all queued requests and auth state.
+     * Useful for cleanup during shutdown.
+     *
+     * Rejects all queued requests with a shutdown error.
+     */
+    clearQueues(): void;
+    /**
+     * Reset auth state for an agent.
+     * Useful for retry scenarios or logout.
+     *
+     * @param agentId - The agent identifier
+     */
+    resetAuthState(agentId: string): void;
+    /**
+     * Get the OAuth requirement for an agent.
+     *
+     * Requirement 11.2: Check agent auth requirements.
+     *
+     * @param agentId - The agent identifier
+     * @returns The required OAuth provider ID, or undefined if no OAuth required
+     */
+    getAgentOAuthRequirement(agentId: string): AuthProviderId | undefined;
+    /**
+     * Set the OAuth requirement for an agent.
+     *
+     * Requirement 11.2: Cache auth requirements per agent.
+     *
+     * @param agentId - The agent identifier
+     * @param providerId - The required OAuth provider ID
+     */
+    setAgentOAuthRequirement(agentId: string, providerId: AuthProviderId): void;
+    /**
+     * Clear the OAuth requirement for an agent.
+     *
+     * @param agentId - The agent identifier
+     */
+    clearAgentOAuthRequirement(agentId: string): void;
+}