Socket gateways

export interface BrowserGatewayOptions {
    /** Named BrowserAgent instances. Clients select one via agentName. */
    agents: Record<string, BrowserAgentLike>;
    /** Socket.IO server instance */
    io: any;
    /** Socket.IO namespace. Default: "/agentium-browser" */
    namespace?: string;
    /** Optional auth middleware applied to the namespace */
    authMiddleware?: (socket: any, next: (err?: Error) => void) => void;
    /**
     * Stream screenshots to the client in real-time.
     * Default: true. Disable for bandwidth-constrained clients.
     */
    streamScreenshots?: boolean;
}

export declare function createAgentGateway(options: GatewayOptions): void;

/**
 * Create a Socket.IO gateway that streams BrowserAgent execution in real-time.
 *
 * ## Client → Server events
 * - `browser.start` — kick off a browser task
 * - `browser.stop`  — cancel a running task
 *
 * ## Server → Client events
 * - `browser.started`    — task accepted
 * - `browser.screenshot` — live screenshot (base64 PNG)
 * - `browser.action`     — action about to execute
 * - `browser.step`       — full step with screenshot + DOM
 * - `browser.done`       — task finished (result, success, duration, video)
 * - `browser.error`      — error occurred
 * - `browser.stopped`    — task was cancelled
 */
export declare function createBrowserGateway(opts: BrowserGatewayOptions): void;

export declare function createVisionGateway(opts: VisionGatewayOptions): void;

/** Bounded per-connection audio delivery; each output frame must be acknowledged by the client. */
export declare function createVoiceGateway(opts: VoiceGatewayOptions): void;

export interface GatewayOptions {
    security: GatewaySecurityOptions;
    /** Bounds apply per socket; outgoing frames use the Engine.IO drain contract. */
    textStream?: TextStreamLimits;
    maxConcurrentRuns?: number;
    /** Maximum collected final Agent text bytes. Default 256 KiB. */
    maxOutputBytes?: number;
    /**
     * Use a Registry for live auto-discovery. The gateway resolves agents/teams
     * at event time — any instance created after the gateway starts is automatically
     * reachable.
     *
     * When omitted, falls back to the global registry from `@agentium/core`.
     * Pass `false` to disable registry-based lookup (use explicit maps only).
     *
     * @example
     * createAgentGateway({ io, security: { mode: "local" } });
     * new Agent({ name: "bot", model: openai("gpt-4o") }); // immediately reachable
     */
    registry?: Registry | false;
    /**
     * Auto-discover agents and teams from a mixed array.
     * Each item is classified by its `.kind` and keyed by `.name`.
     */
    serve?: Servable[];
    agents?: Record<string, Agent | ServableAgent>;
    teams?: Record<string, Team>;
    io: any;
    namespace?: string;
    /** Must call next; thrown/rejected errors deny access. Returned promises settle before admission. */
    authMiddleware?: (socket: any, next: (err?: Error) => void) => void | Promise<void>;
    /** Max requests per minute per socket. Default: 60 */
    maxRequestsPerMinute?: number;
    /** Named tool library exposed via tools.list event. */
    toolLibrary?: Record<string, ToolDef>;
    /** Toolkit instances whose tools are exposed via tools.list. Merged with toolLibrary. */
    toolkits?: Toolkit[];
}

export interface GatewayResourceRequest {
    identity: Readonly<HostedIdentity>;
    operation: "discover" | "execute" | "session:create" | "session:use" | "run:cancel";
    resource: {
        kind: "agent" | "team" | "workflow" | "tool" | "session" | "run";
        id: string;
        target?: string;
    };
}

export type GatewaySecurityOptions = {
    mode: "local";
} | {
    mode: "authenticated";
    /** Read only host-verified socket.data, never handshake payload claims. */
    resolveIdentity: (verifiedState: unknown) => HostedIdentity | null | Promise<HostedIdentity | null>;
    /** session:create must atomically bind the generated ID; deny unknown session:use. */
    authorizeResource: (request: GatewayResourceRequest) => boolean | Promise<boolean>;
};

export interface VisionGatewayOptions {
    agents: Record<string, VisionAgent>;
    io: any;
    namespace?: string;
    authMiddleware?: (socket: any, next: (err?: Error) => void) => void;
}

export interface VoiceGatewayOptions {
    agents: Record<string, VoiceAgent>;
    io: any;
    namespace?: string;
    /** Establish trusted identity in socket.data.auth {userId,tenantId,sessionId}. */
    authMiddleware?: (socket: any, next: (err?: Error) => void) => void;
    maxAudioFrameBytes?: number;
    maxPendingAudioBytes?: number;
    playbackAckTimeoutMs?: number;
}

/**
 * Minimal interface for a BrowserAgent — avoids a hard dependency on @agentium/browser.
 * Any object that matches this shape (e.g. a real BrowserAgent) works.
 */
interface BrowserAgentLike {
    name: string;
    eventBus: EventBus;
    run(task: string, opts?: {
        startUrl?: string;
        apiKey?: string;
        sessionId?: string;
    }): Promise<{
        result: string;
        success: boolean;
        finalUrl: string;
        durationMs: number;
        videoPath?: string;
        steps: Array<{
            index: number;
            action: unknown;
            screenshot: Buffer;
            pageUrl: string;
            pageTitle: string;
            dom?: string;
        }>;
    }>;
}