@agentick/gateway 0.0.1

package/dist/protocol.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Gateway Protocol Types
+ *
+ * Defines the WebSocket message protocol between clients and the gateway.
+ */
+export interface ConnectMessage {
+    type: "connect";
+    clientId: string;
+    token?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface RequestMessage {
+    type: "req";
+    id: string;
+    method: GatewayMethod;
+    params: Record<string, unknown>;
+}
+export interface PingMessage {
+    type: "ping";
+    timestamp: number;
+}
+export type ClientMessage = ConnectMessage | RequestMessage | PingMessage;
+export interface ConnectedMessage {
+    type: "connected";
+    gatewayId: string;
+    apps: string[];
+    sessions: string[];
+}
+export interface ResponseMessage {
+    type: "res";
+    id: string;
+    ok: boolean;
+    payload?: unknown;
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+}
+export interface EventMessage {
+    type: "event";
+    event: GatewayEventType;
+    sessionId: string;
+    data: unknown;
+}
+export interface PongMessage {
+    type: "pong";
+    timestamp: number;
+}
+export interface ErrorMessage {
+    type: "error";
+    code: string;
+    message: string;
+}
+export type GatewayMessage = ConnectedMessage | ResponseMessage | EventMessage | PongMessage | ErrorMessage;
+/**
+ * Built-in gateway methods with autocomplete support.
+ */
+export type BuiltInMethod = "send" | "abort" | "status" | "history" | "reset" | "close" | "apps" | "sessions" | "subscribe" | "unsubscribe";
+/**
+ * Gateway method - built-in methods or custom method strings.
+ * The (string & {}) allows any string while preserving autocomplete for built-in methods.
+ */
+export type GatewayMethod = BuiltInMethod | (string & {});
+export type GatewayEventType = "content_delta" | "content_block_start" | "content_block_end" | "tool_call_start" | "tool_call_delta" | "tool_result" | "message_start" | "message_end" | "error";
+export interface SendParams {
+    sessionId: string;
+    message: string;
+    attachments?: Array<{
+        type: "image" | "file";
+        data: string;
+        mimeType: string;
+        name?: string;
+    }>;
+}
+export interface AbortParams {
+    sessionId: string;
+}
+export interface StatusParams {
+    sessionId?: string;
+}
+export interface HistoryParams {
+    sessionId: string;
+    limit?: number;
+    before?: string;
+}
+export interface ResetParams {
+    sessionId: string;
+}
+export interface CloseParams {
+    sessionId: string;
+}
+export interface SubscribeParams {
+    sessionId: string;
+}
+export interface UnsubscribeParams {
+    sessionId: string;
+}
+export interface StatusPayload {
+    gateway: {
+        id: string;
+        uptime: number;
+        clients: number;
+        sessions: number;
+        apps: string[];
+    };
+    session?: {
+        id: string;
+        appId: string;
+        messageCount: number;
+        createdAt: string;
+        lastActivityAt: string;
+        isActive: boolean;
+    };
+}
+export interface HistoryPayload {
+    messages: Array<{
+        id: string;
+        role: "user" | "assistant" | "system";
+        content: string;
+        timestamp: string;
+        toolCalls?: Array<{
+            name: string;
+            input: unknown;
+            output?: unknown;
+        }>;
+    }>;
+    hasMore: boolean;
+}
+export interface AppsPayload {
+    apps: Array<{
+        id: string;
+        name: string;
+        description?: string;
+        isDefault: boolean;
+    }>;
+}
+export interface SessionsPayload {
+    sessions: Array<{
+        id: string;
+        appId: string;
+        createdAt: string;
+        lastActivityAt: string;
+        messageCount: number;
+    }>;
+}
+/**
+ * Session keys follow the format: [app:]name
+ *
+ * Examples:
+ * - "main" → default app, "main" session
+ * - "chat:main" → "chat" app, "main" session
+ * - "research:task-123" → "research" app, "task-123" session
+ * - "whatsapp:+1234567890" → WhatsApp channel session
+ */
+export interface SessionKey {
+    appId: string;
+    sessionName: string;
+}
+export declare function parseSessionKey(key: string, defaultApp: string): SessionKey;
+export declare function formatSessionKey(key: SessionKey): string;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/protocol.js

@@ -0,0 +1,16 @@
+/**
+ * Gateway Protocol Types
+ *
+ * Defines the WebSocket message protocol between clients and the gateway.
+ */
+export function parseSessionKey(key, defaultApp) {
+    const parts = key.split(":");
+    if (parts.length === 1) {
+        return { appId: defaultApp, sessionName: parts[0] };
+    }
+    return { appId: parts[0], sessionName: parts.slice(1).join(":") };
+}
+export function formatSessionKey(key) {
+    return `${key.appId}:${key.sessionName}`;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0OH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,UAAkB;IAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IACtD,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,GAAe;IAC9C,OAAO,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;AAC3C,CAAC"}

package/dist/session-manager.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Session Manager
+ *
+ * Manages persistent sessions across apps.
+ */
+import type { Session } from "@agentick/core";
+import type { AppRegistry, AppInfo } from "./app-registry.js";
+import type { SessionState } from "./types.js";
+interface ManagedSession {
+    state: SessionState;
+    coreSession: Session | null;
+    appInfo: AppInfo;
+    /** The session name without app prefix - used when creating App sessions */
+    sessionName: string;
+}
+/**
+ * SessionManager configuration
+ */
+export interface SessionManagerConfig {
+    /** Gateway ID for DevTools events */
+    gatewayId: string;
+}
+export declare class SessionManager {
+    private sessions;
+    private registry;
+    private gatewayId;
+    private devToolsSequence;
+    constructor(registry: AppRegistry, config?: SessionManagerConfig);
+    /**
+     * Normalize a session key to the canonical format (appId:sessionName).
+     * This ensures consistent lookups regardless of input format.
+     */
+    private normalizeKey;
+    /**
+     * Emit a DevTools session event
+     */
+    private emitDevToolsEvent;
+    /**
+     * Get or create a session
+     */
+    getOrCreate(sessionKey: string, clientId?: string): Promise<ManagedSession>;
+    /**
+     * Get an existing session
+     */
+    get(sessionKey: string): ManagedSession | undefined;
+    /**
+     * Check if a session exists
+     */
+    has(sessionKey: string): boolean;
+    /**
+     * Close a session
+     */
+    close(sessionKey: string): Promise<void>;
+    /**
+     * Reset a session (clear history but keep session)
+     */
+    reset(sessionKey: string): Promise<void>;
+    /**
+     * Get all session IDs
+     */
+    ids(): string[];
+    /**
+     * Get all sessions
+     */
+    all(): ManagedSession[];
+    /**
+     * Get sessions for a specific app
+     */
+    forApp(appId: string): ManagedSession[];
+    /**
+     * Get session count
+     */
+    get size(): number;
+    /**
+     * Add a subscriber to a session.
+     * Creates the session if it doesn't exist (ensures subscription is never lost).
+     */
+    subscribe(sessionKey: string, clientId: string): Promise<void>;
+    /**
+     * Remove a subscriber from a session
+     */
+    unsubscribe(sessionKey: string, clientId: string): void;
+    /**
+     * Remove a client from all subscriptions
+     */
+    unsubscribeAll(clientId: string): void;
+    /**
+     * Get subscribers for a session
+     */
+    getSubscribers(sessionKey: string): Set<string>;
+    /**
+     * Update message count for a session
+     */
+    incrementMessageCount(sessionKey: string, clientId?: string): void;
+    /**
+     * Set session active state
+     */
+    setActive(sessionKey: string, isActive: boolean): void;
+}
+export {};
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C,UAAU,cAAc;IACtB,KAAK,EAAE,YAAY,CAAC;IACpB,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,QAAQ,CAAc;IAC9B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAK;gBAEjB,QAAQ,EAAE,WAAW,EAAE,MAAM,CAAC,EAAE,oBAAoB;IAKhE;;;OAGG;IACH,OAAO,CAAC,YAAY;IAKpB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAsBzB;;OAEG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA4CjF;;OAEG;IACH,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAInD;;OAEG;IACH,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAIhC;;OAEG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB9C;;OAEG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB9C;;OAEG;IACH,GAAG,IAAI,MAAM,EAAE;IAIf;;OAEG;IACH,GAAG,IAAI,cAAc,EAAE;IAIvB;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE;IAIvC;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpE;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAOvD;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAMtC;;OAEG;IACH,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAK/C;;OAEG;IACH,qBAAqB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI;IAiBlE;;OAEG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI;CAMvD"}

package/dist/session-manager.js

@@ -0,0 +1,208 @@
+/**
+ * Session Manager
+ *
+ * Manages persistent sessions across apps.
+ */
+import { devToolsEmitter } from "@agentick/shared";
+import { parseSessionKey, formatSessionKey } from "./transport-protocol.js";
+export class SessionManager {
+    sessions = new Map();
+    registry;
+    gatewayId;
+    devToolsSequence = 0;
+    constructor(registry, config) {
+        this.registry = registry;
+        this.gatewayId = config?.gatewayId ?? "gateway";
+    }
+    /**
+     * Normalize a session key to the canonical format (appId:sessionName).
+     * This ensures consistent lookups regardless of input format.
+     */
+    normalizeKey(sessionKey) {
+        const { appId, sessionName } = parseSessionKey(sessionKey, this.registry.defaultId);
+        return formatSessionKey({ appId, sessionName });
+    }
+    /**
+     * Emit a DevTools session event
+     */
+    emitDevToolsEvent(action, sessionId, appId, messageCount, clientId) {
+        if (!devToolsEmitter.hasSubscribers())
+            return;
+        devToolsEmitter.emitEvent({
+            type: "gateway_session",
+            executionId: this.gatewayId,
+            action,
+            sessionId,
+            appId,
+            messageCount,
+            clientId,
+            sequence: this.devToolsSequence++,
+            timestamp: Date.now(),
+        });
+    }
+    /**
+     * Get or create a session
+     */
+    async getOrCreate(sessionKey, clientId) {
+        const normalizedKey = this.normalizeKey(sessionKey);
+        // Check if session exists
+        let session = this.sessions.get(normalizedKey);
+        if (session) {
+            session.state.lastActivityAt = new Date();
+            return session;
+        }
+        // Parse session key to get app and name
+        const { appId, sessionName } = parseSessionKey(sessionKey, this.registry.defaultId);
+        // Get the app
+        const appInfo = this.registry.resolve(appId);
+        // Create session state
+        const state = {
+            id: formatSessionKey({ appId, sessionName }),
+            appId,
+            createdAt: new Date(),
+            lastActivityAt: new Date(),
+            messageCount: 0,
+            isActive: false,
+            subscribers: new Set(),
+        };
+        // Create the managed session
+        // Note: sessionName is the name WITHOUT app prefix - used when creating App sessions
+        session = {
+            state,
+            coreSession: null,
+            appInfo,
+            sessionName,
+        };
+        this.sessions.set(state.id, session);
+        // Emit DevTools event for session creation
+        this.emitDevToolsEvent("created", state.id, appId, 0, clientId);
+        return session;
+    }
+    /**
+     * Get an existing session
+     */
+    get(sessionKey) {
+        return this.sessions.get(this.normalizeKey(sessionKey));
+    }
+    /**
+     * Check if a session exists
+     */
+    has(sessionKey) {
+        return this.sessions.has(this.normalizeKey(sessionKey));
+    }
+    /**
+     * Close a session
+     */
+    async close(sessionKey) {
+        const normalizedKey = this.normalizeKey(sessionKey);
+        const session = this.sessions.get(normalizedKey);
+        if (!session)
+            return;
+        const { id, appId, messageCount } = session.state;
+        // Clean up session if active
+        if (session.coreSession) {
+            session.coreSession.close();
+            session.coreSession = null;
+        }
+        this.sessions.delete(normalizedKey);
+        // Emit DevTools event for session closure
+        this.emitDevToolsEvent("closed", id, appId, messageCount);
+    }
+    /**
+     * Reset a session (clear history but keep session)
+     */
+    async reset(sessionKey) {
+        const normalizedKey = this.normalizeKey(sessionKey);
+        const session = this.sessions.get(normalizedKey);
+        if (!session)
+            return;
+        const { id, appId, messageCount } = session.state;
+        // Reset session state
+        session.state.messageCount = 0;
+        session.state.lastActivityAt = new Date();
+        if (session.coreSession) {
+            session.coreSession.close();
+            session.coreSession = null;
+        }
+        // Emit DevTools event for session reset (treated as closed + recreated)
+        this.emitDevToolsEvent("closed", id, appId, messageCount);
+    }
+    /**
+     * Get all session IDs
+     */
+    ids() {
+        return Array.from(this.sessions.keys());
+    }
+    /**
+     * Get all sessions
+     */
+    all() {
+        return Array.from(this.sessions.values());
+    }
+    /**
+     * Get sessions for a specific app
+     */
+    forApp(appId) {
+        return this.all().filter((s) => s.state.appId === appId);
+    }
+    /**
+     * Get session count
+     */
+    get size() {
+        return this.sessions.size;
+    }
+    /**
+     * Add a subscriber to a session.
+     * Creates the session if it doesn't exist (ensures subscription is never lost).
+     */
+    async subscribe(sessionKey, clientId) {
+        const session = await this.getOrCreate(sessionKey, clientId);
+        session.state.subscribers.add(clientId);
+    }
+    /**
+     * Remove a subscriber from a session
+     */
+    unsubscribe(sessionKey, clientId) {
+        const session = this.sessions.get(this.normalizeKey(sessionKey));
+        if (session) {
+            session.state.subscribers.delete(clientId);
+        }
+    }
+    /**
+     * Remove a client from all subscriptions
+     */
+    unsubscribeAll(clientId) {
+        for (const session of this.sessions.values()) {
+            session.state.subscribers.delete(clientId);
+        }
+    }
+    /**
+     * Get subscribers for a session
+     */
+    getSubscribers(sessionKey) {
+        const session = this.sessions.get(this.normalizeKey(sessionKey));
+        return session?.state.subscribers ?? new Set();
+    }
+    /**
+     * Update message count for a session
+     */
+    incrementMessageCount(sessionKey, clientId) {
+        const session = this.sessions.get(this.normalizeKey(sessionKey));
+        if (session) {
+            session.state.messageCount++;
+            session.state.lastActivityAt = new Date();
+            // Emit DevTools event for session message
+            this.emitDevToolsEvent("message", session.state.id, session.state.appId, session.state.messageCount, clientId);
+        }
+    }
+    /**
+     * Set session active state
+     */
+    setActive(sessionKey, isActive) {
+        const session = this.sessions.get(this.normalizeKey(sessionKey));
+        if (session) {
+            session.state.isActive = isActive;
+        }
+    }
+}
+//# sourceMappingURL=session-manager.js.map

package/dist/session-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.js","sourceRoot":"","sources":["../src/session-manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,eAAe,EAA8B,MAAM,kBAAkB,CAAC;AAG/E,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAkB5E,MAAM,OAAO,cAAc;IACjB,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;IAC7C,QAAQ,CAAc;IACtB,SAAS,CAAS;IAClB,gBAAgB,GAAG,CAAC,CAAC;IAE7B,YAAY,QAAqB,EAAE,MAA6B;QAC9D,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,SAAS,GAAG,MAAM,EAAE,SAAS,IAAI,SAAS,CAAC;IAClD,CAAC;IAED;;;OAGG;IACK,YAAY,CAAC,UAAkB;QACrC,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,eAAe,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QACpF,OAAO,gBAAgB,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;IAClD,CAAC;IAED;;OAEG;IACK,iBAAiB,CACvB,MAAuC,EACvC,SAAiB,EACjB,KAAa,EACb,YAAqB,EACrB,QAAiB;QAEjB,IAAI,CAAC,eAAe,CAAC,cAAc,EAAE;YAAE,OAAO;QAE9C,eAAe,CAAC,SAAS,CAAC;YACxB,IAAI,EAAE,iBAAiB;YACvB,WAAW,EAAE,IAAI,CAAC,SAAS;YAC3B,MAAM;YACN,SAAS;YACT,KAAK;YACL,YAAY;YACZ,QAAQ;YACR,QAAQ,EAAE,IAAI,CAAC,gBAAgB,EAAE;YACjC,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;SACG,CAAC,CAAC;IAC9B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,WAAW,CAAC,UAAkB,EAAE,QAAiB;QACrD,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;QAEpD,0BAA0B;QAC1B,IAAI,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QAC/C,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,KAAK,CAAC,cAAc,GAAG,IAAI,IAAI,EAAE,CAAC;YAC1C,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,wCAAwC;QACxC,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,GAAG,eAAe,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QAEpF,cAAc;QACd,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAE7C,uBAAuB;QACvB,MAAM,KAAK,GAAiB;YAC1B,EAAE,EAAE,gBAAgB,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;YAC5C,KAAK;YACL,SAAS,EAAE,IAAI,IAAI,EAAE;YACrB,cAAc,EAAE,IAAI,IAAI,EAAE;YAC1B,YAAY,EAAE,CAAC;YACf,QAAQ,EAAE,KAAK;YACf,WAAW,EAAE,IAAI,GAAG,EAAE;SACvB,CAAC;QAEF,6BAA6B;QAC7B,qFAAqF;QACrF,OAAO,GAAG;YACR,KAAK;YACL,WAAW,EAAE,IAAI;YACjB,OAAO;YACP,WAAW;SACZ,CAAC;QAEF,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAErC,2CAA2C;QAC3C,IAAI,CAAC,iBAAiB,CAAC,SAAS,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC;QAEhE,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,UAAkB;QACpB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,UAAkB;QACpB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK,CAAC,UAAkB;QAC5B,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;QACpD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;QAElD,6BAA6B;QAC7B,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YACxB,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;YAC5B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;QAC7B,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QAEpC,0CAA0C;QAC1C,IAAI,CAAC,iBAAiB,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IAC5D,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK,CAAC,UAAkB;QAC5B,MAAM,aAAa,GAAG,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;QACpD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC;QAElD,sBAAsB;QACtB,OAAO,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,CAAC;QAC/B,OAAO,CAAC,KAAK,CAAC,cAAc,GAAG,IAAI,IAAI,EAAE,CAAC;QAC1C,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;YACxB,OAAO,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;YAC5B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;QAC7B,CAAC;QAED,wEAAwE;QACxE,IAAI,CAAC,iBAAiB,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IAC5D,CAAC;IAED;;OAEG;IACH,GAAG;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED;;OAEG;IACH,GAAG;QACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACH,MAAM,CAAC,KAAa;QAClB,OAAO,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;IAC3D,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,SAAS,CAAC,UAAkB,EAAE,QAAgB;QAClD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;QAC7D,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC1C,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,UAAkB,EAAE,QAAgB;QAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC;QACjE,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,QAAgB;QAC7B,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;YAC7C,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC7C,CAAC;IACH,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,UAAkB;QAC/B,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC;QACjE,OAAO,OAAO,EAAE,KAAK,CAAC,WAAW,IAAI,IAAI,GAAG,EAAE,CAAC;IACjD,CAAC;IAED;;OAEG;IACH,qBAAqB,CAAC,UAAkB,EAAE,QAAiB;QACzD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC;QACjE,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;YAC7B,OAAO,CAAC,KAAK,CAAC,cAAc,GAAG,IAAI,IAAI,EAAE,CAAC;YAE1C,0CAA0C;YAC1C,IAAI,CAAC,iBAAiB,CACpB,SAAS,EACT,OAAO,CAAC,KAAK,CAAC,EAAE,EAChB,OAAO,CAAC,KAAK,CAAC,KAAK,EACnB,OAAO,CAAC,KAAK,CAAC,YAAY,EAC1B,QAAQ,CACT,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,UAAkB,EAAE,QAAiB;QAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC;QACjE,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACpC,CAAC;IACH,CAAC;CACF"}

package/dist/testing.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Gateway Testing Utilities
+ *
+ * Provides helpers for testing gateway interactions.
+ *
+ * @example
+ * ```typescript
+ * import { createTestGateway, createMockApp } from '@agentick/gateway/testing';
+ *
+ * test('gateway handles messages', async () => {
+ *   const mockApp = createMockApp({
+ *     response: 'Hello!',
+ *   });
+ *
+ *   const { gateway, client, cleanup } = await createTestGateway({
+ *     agents: { chat: mockApp },
+ *     defaultAgent: 'chat',
+ *   });
+ *
+ *   try {
+ *     const response = await client.send('main', 'Hi there');
+ *     expect(response.payload.messageId).toBeDefined();
+ *   } finally {
+ *     await cleanup();
+ *   }
+ * });
+ * ```
+ *
+ * @module @agentick/gateway/testing
+ */
+import WebSocket from "ws";
+import type { Gateway } from "./gateway.js";
+import type { GatewayConfig, GatewayEvents } from "./types.js";
+export { createMockApp, createMockSession, createMockExecutionHandle, createTestProcedure, type MockAppOptions, type MockSessionOptions, type MockSession, type MockApp, type MockSessionExecutionHandle, type MockExecutionHandleOptions, type TestProcedure, type TestProcedureOptions, } from "@agentick/core/testing";
+export interface TestGatewayOptions extends Omit<GatewayConfig, "port" | "host"> {
+    /** Custom port (default: random available port) */
+    port?: number;
+}
+export interface TestGatewayClient {
+    /** Send a request to the gateway */
+    request<T = unknown>(method: string, params?: Record<string, unknown>): Promise<{
+        ok: boolean;
+        payload?: T;
+        error?: {
+            code: string;
+            message: string;
+        };
+    }>;
+    /** Send a message to a session */
+    send(sessionId: string, message: string): Promise<{
+        ok: boolean;
+        payload?: {
+            messageId: string;
+        };
+        error?: {
+            code: string;
+            message: string;
+        };
+    }>;
+    /** Collect events for a session */
+    collectEvents(sessionId: string, timeout?: number): Promise<Array<{
+        type: string;
+        data: unknown;
+    }>>;
+    /** Close the client connection */
+    close(): void;
+    /** The raw WebSocket */
+    ws: WebSocket;
+}
+export interface TestGatewayResult {
+    /** The gateway instance */
+    gateway: Gateway;
+    /** A connected test client */
+    client: TestGatewayClient;
+    /** Gateway URL */
+    url: string;
+    /** Port the gateway is running on */
+    port: number;
+    /** Clean up resources */
+    cleanup: () => Promise<void>;
+}
+/**
+ * Create a test gateway with a connected client.
+ *
+ * Automatically handles port allocation, client connection, and cleanup.
+ */
+export declare function createTestGateway(options: TestGatewayOptions): Promise<TestGatewayResult>;
+/**
+ * Wait for a specific gateway event.
+ */
+export declare function waitForGatewayEvent<K extends keyof GatewayEvents>(gateway: Gateway, event: K, timeout?: number): Promise<GatewayEvents[K]>;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,SAAS,MAAM,IAAI,CAAC;AAC3B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG/D,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,yBAAyB,EACzB,mBAAmB,EACnB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,0BAA0B,EAC/B,KAAK,0BAA0B,EAC/B,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,wBAAwB,CAAC;AAMhC,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9E,mDAAmD;IACnD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,OAAO,CAAC,CAAC,GAAG,OAAO,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC;QACT,EAAE,EAAE,OAAO,CAAC;QACZ,OAAO,CAAC,EAAE,CAAC,CAAC;QACZ,KAAK,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC;KAC3C,CAAC,CAAC;IAEH,kCAAkC;IAClC,IAAI,CACF,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;QACT,EAAE,EAAE,OAAO,CAAC;QACZ,OAAO,CAAC,EAAE;YAAE,SAAS,EAAE,MAAM,CAAA;SAAE,CAAC;QAChC,KAAK,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC;KAC3C,CAAC,CAAC;IAEH,mCAAmC;IACnC,aAAa,CACX,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC,CAAC;IAEnD,kCAAkC;IAClC,KAAK,IAAI,IAAI,CAAC;IAEd,wBAAwB;IACxB,EAAE,EAAE,SAAS,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,2BAA2B;IAC3B,OAAO,EAAE,OAAO,CAAC;IAEjB,8BAA8B;IAC9B,MAAM,EAAE,iBAAiB,CAAC;IAE1B,kBAAkB;IAClB,GAAG,EAAE,MAAM,CAAC;IAEZ,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IAEb,yBAAyB;IACzB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA8F/F;AAMD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,aAAa,EAC/D,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,CAAC,EACR,OAAO,SAAO,GACb,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAW3B"}