@amodalai/runtime 0.2.0 → 0.2.2

package/dist/src/api/types.d.ts

@@ -41,11 +41,7 @@ export interface AgentConfig {
 /** A running agent instance. */
 export interface Agent {
     /** Create a new chat session. */
-    createSession(opts?: {
-        tenantId?: string;
-        userId?: string;
-        userRoles?: string[];
-    }): AgentSession;
+    createSession(): AgentSession;
     /** Resume an existing session by ID. Returns null if not found. */
     resumeSession(sessionId: string): Promise<AgentSession | null>;
     /** Get the agent's compiled system prompt. */

package/dist/src/channels/bootstrap.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Shared channel bootstrap sequence.
+ *
+ * Used by local-server.ts, snapshot-server.ts, and available for
+ * hosting layers that call createServer(). Loads channel plugins,
+ * wires the session mapper, and creates the Express router.
+ */
+import type { Router } from 'express';
+import type { ChannelAdapter, ChannelSessionMapper } from '@amodalai/types';
+import type { StandaloneSessionManager } from '../session/manager.js';
+import type { SessionComponents } from '../session/session-builder.js';
+import type { RuntimeEventBus } from '../events/event-bus.js';
+import type { Logger } from '../logger.js';
+import type { CreateChannelSession } from './channel-session-mapper.js';
+/** A discovered channel from the bundle (matches AgentBundle['channels'][n]). */
+interface BundleChannel {
+    channelType: string;
+    packageName: string;
+    packageDir: string;
+    config: Record<string, unknown>;
+}
+export interface BootstrapChannelsOptions {
+    /** Discovered channel plugins from the bundle. */
+    channels: BundleChannel[];
+    /** Repo path for local channel discovery + node_modules resolution. */
+    repoPath: string;
+    /** The `packages` array from amodal.json. */
+    packages?: string[];
+    /**
+     * Pre-wired session mapper. The caller chooses the implementation:
+     * - DrizzleChannelSessionMapper (local-server, hosted with DB)
+     * - InMemoryChannelSessionMapper (snapshot-server, testing)
+     */
+    sessionMapper: ChannelSessionMapper & {
+        setSessionFactory(f: CreateChannelSession): void;
+    };
+    sessionManager: StandaloneSessionManager;
+    /** Factory that builds session components for new channel sessions. */
+    buildSessionComponents: () => SessionComponents;
+    /** App ID for sessions created by channels (e.g. 'local'). */
+    appId?: string;
+    eventBus: RuntimeEventBus;
+    logger: Logger;
+}
+export interface BootstrapChannelsResult {
+    adapters: Map<string, ChannelAdapter>;
+    router: Router;
+}
+/**
+ * Load channel plugins, wire the session factory, and create the
+ * Express router. Returns null if loading fails (error is logged).
+ */
+export declare function bootstrapChannels(opts: BootstrapChannelsOptions): Promise<BootstrapChannelsResult | null>;
+export {};

package/dist/src/channels/bootstrap.js

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { loadChannelPlugins } from './plugin-loader.js';
+import { createChannelsRouter } from './routes.js';
+import { MessageDedupCache } from './dedup-cache.js';
+import { resolveEnvRef } from '../env-ref.js';
+/**
+ * Load channel plugins, wire the session factory, and create the
+ * Express router. Returns null if loading fails (error is logged).
+ */
+export async function bootstrapChannels(opts) {
+    const { channels, repoPath, sessionMapper, sessionManager, buildSessionComponents, eventBus, logger } = opts;
+    const appId = opts.appId ?? 'local';
+    if (channels.length === 0) {
+        return null;
+    }
+    try {
+        // Build and resolve env:VAR refs in channel config values
+        const channelsConfig = {};
+        for (const ch of channels) {
+            channelsConfig[ch.channelType] = resolveChannelConfig(ch.config);
+        }
+        // Load and validate plugins
+        const adapters = await loadChannelPlugins({ channelsConfig, repoPath, packages: opts.packages, logger });
+        logger.info('channels_loaded', { channels: [...adapters.keys()] });
+        // Wire session factory — creates chat sessions for channel users
+        sessionMapper.setSessionFactory((origin) => {
+            const components = buildSessionComponents();
+            const channelNote = `\n\n[Channel context: This user is messaging you via ${origin.channelType}. Keep responses concise and conversational. User: ${origin.channelUserDisplay ?? origin.channelUserId}.]`;
+            const session = sessionManager.create({
+                provider: components.provider,
+                toolRegistry: components.toolRegistry,
+                permissionChecker: components.permissionChecker,
+                systemPrompt: components.systemPrompt + channelNote,
+                toolContextFactory: components.toolContextFactory,
+                appId,
+                metadata: { channelOrigin: origin },
+            });
+            return { sessionId: session.id };
+        });
+        // Build the router
+        const router = createChannelsRouter({
+            adapters,
+            sessionMapper,
+            sessionManager,
+            dedupCache: new MessageDedupCache(),
+            eventBus,
+            logger,
+        });
+        return { adapters, router };
+    }
+    catch (err) {
+        logger.warn('channels_load_failed', {
+            error: err instanceof Error ? err.message : String(err),
+            hint: 'Server will start without messaging channels',
+        });
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve `env:VAR_NAME` references in a channel config block.
+ */
+function resolveChannelConfig(config) {
+    const resolved = {};
+    for (const [k, v] of Object.entries(config)) {
+        if (typeof v === 'string') {
+            resolved[k] = resolveEnvRef(v) ?? v;
+        }
+        else if (Array.isArray(v)) {
+            resolved[k] = v.map((item) => typeof item === 'string' ? (resolveEnvRef(item) ?? item) : item);
+        }
+        else {
+            resolved[k] = v;
+        }
+    }
+    return resolved;
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/src/channels/bootstrap.js.map

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

package/dist/src/channels/channel-session-mapper.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import type { ChannelSessionMapper, ChannelSessionMapResult, ChannelOrigin } from '@amodalai/types';
+import type { Logger } from '../logger.js';
+type AnyPgDatabase = PgDatabase<PgQueryResultHKT, Record<string, unknown>>;
+export interface ChannelSessionMapperOptions {
+    db: AnyPgDatabase;
+    logger: Logger;
+    eventBus?: {
+        emit(payload: {
+            type: string;
+            [key: string]: unknown;
+        }): unknown;
+    };
+}
+/**
+ * Create a new session for a channel user. The caller provides the
+ * session factory so the mapper stays decoupled from session creation
+ * details (provider selection, tool registration, etc.).
+ */
+export type CreateChannelSession = (channelOrigin: ChannelOrigin) => {
+    sessionId: string;
+};
+export declare class DrizzleChannelSessionMapper implements ChannelSessionMapper {
+    private readonly db;
+    private readonly logger;
+    private readonly eventBus?;
+    private createSession;
+    constructor(opts: ChannelSessionMapperOptions);
+    /**
+     * Wire the session factory after construction. Called by the local-server
+     * wiring code once all session components are available.
+     */
+    setSessionFactory(factory: CreateChannelSession): void;
+    findOrCreateSession(channelType: string, channelUserId: string, displayName?: string): Promise<ChannelSessionMapResult>;
+    resetSession(channelType: string, channelUserId: string): Promise<void>;
+}
+export {};

package/dist/src/channels/channel-session-mapper.js

@@ -0,0 +1,91 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * Drizzle-based channel session mapper.
+ *
+ * Maps (channelType, channelUserId) → sessionId using the
+ * `channel_sessions` table. Shares the same database connection pool
+ * as the session store to avoid opening a second connection.
+ */
+import { eq, and, sql } from 'drizzle-orm';
+import { channelSessions } from '../stores/schema.js';
+export class DrizzleChannelSessionMapper {
+    db;
+    logger;
+    eventBus;
+    createSession = null;
+    constructor(opts) {
+        this.db = opts.db;
+        this.logger = opts.logger;
+        this.eventBus = opts.eventBus;
+    }
+    /**
+     * Wire the session factory after construction. Called by the local-server
+     * wiring code once all session components are available.
+     */
+    setSessionFactory(factory) {
+        this.createSession = factory;
+    }
+    async findOrCreateSession(channelType, channelUserId, displayName) {
+        // Try to find an existing mapping and touch last_active_at in one query
+        const rows = await this.db
+            .update(channelSessions)
+            .set({ lastActiveAt: sql `NOW()` })
+            .where(and(eq(channelSessions.channelType, channelType), eq(channelSessions.channelUserId, channelUserId)))
+            .returning({ sessionId: channelSessions.sessionId });
+        if (rows.length > 0) {
+            const { sessionId } = rows[0];
+            this.logger.debug('channel_session_found', { channelType, channelUserId, sessionId });
+            return { sessionId, isNew: false };
+        }
+        // Create new session
+        if (!this.createSession) {
+            throw new Error('Channel session mapper: session factory not set. Call setSessionFactory() first.');
+        }
+        const channelOrigin = {
+            channelType,
+            channelUserId,
+            channelUserDisplay: displayName,
+        };
+        const { sessionId } = this.createSession(channelOrigin);
+        // Atomic upsert — if a concurrent request inserted first, return the existing row
+        const inserted = await this.db
+            .insert(channelSessions)
+            .values({
+            channelType,
+            channelUserId,
+            sessionId,
+            metadata: { channelUserDisplay: displayName },
+        })
+            .onConflictDoUpdate({
+            target: [channelSessions.channelType, channelSessions.channelUserId],
+            set: { lastActiveAt: sql `NOW()` },
+        })
+            .returning({ sessionId: channelSessions.sessionId });
+        const finalSessionId = inserted[0].sessionId;
+        const isNew = finalSessionId === sessionId;
+        if (isNew) {
+            this.logger.info('channel_session_created', { channelType, channelUserId, sessionId: finalSessionId });
+            this.eventBus?.emit({
+                type: 'channel_session_created',
+                channelType,
+                channelUserId,
+                sessionId: finalSessionId,
+            });
+        }
+        else {
+            this.logger.debug('channel_session_found', { channelType, channelUserId, sessionId: finalSessionId });
+        }
+        return { sessionId: finalSessionId, isNew };
+    }
+    async resetSession(channelType, channelUserId) {
+        await this.db
+            .delete(channelSessions)
+            .where(and(eq(channelSessions.channelType, channelType), eq(channelSessions.channelUserId, channelUserId)));
+        this.logger.info('channel_session_reset', { channelType, channelUserId });
+    }
+}
+//# sourceMappingURL=channel-session-mapper.js.map

package/dist/src/channels/channel-session-mapper.js.map

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

package/dist/src/channels/dedup-cache.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export declare class MessageDedupCache {
+    private readonly seen;
+    private readonly ttlMs;
+    constructor(ttlMs?: number);
+    /**
+     * Returns `true` if this message was already seen (duplicate).
+     * Returns `false` and records the message if it's new.
+     */
+    isDuplicate(channelType: string, messageId: string): boolean;
+    get size(): number;
+    private evict;
+}

package/dist/src/channels/dedup-cache.js

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * In-memory dedup cache for channel webhook retries.
+ *
+ * Messaging platforms may resend webhook payloads when the server
+ * doesn't respond with 200 quickly enough. This cache prevents the same
+ * message from being processed twice.
+ *
+ * Keyed by `${channelType}:${messageId}`, with a configurable TTL.
+ * Lazy eviction keeps the fast path allocation-free.
+ */
+const DEFAULT_TTL_MS = 60_000;
+const EVICTION_THRESHOLD = 1000;
+export class MessageDedupCache {
+    seen = new Map();
+    ttlMs;
+    constructor(ttlMs = DEFAULT_TTL_MS) {
+        this.ttlMs = ttlMs;
+    }
+    /**
+     * Returns `true` if this message was already seen (duplicate).
+     * Returns `false` and records the message if it's new.
+     */
+    isDuplicate(channelType, messageId) {
+        const key = `${channelType}:${messageId}`;
+        const now = Date.now();
+        if (this.seen.size > EVICTION_THRESHOLD) {
+            this.evict(now);
+        }
+        if (this.seen.has(key)) {
+            return true;
+        }
+        this.seen.set(key, now);
+        return false;
+    }
+    get size() {
+        return this.seen.size;
+    }
+    evict(now) {
+        for (const [k, ts] of this.seen) {
+            if (now - ts > this.ttlMs) {
+                this.seen.delete(k);
+            }
+        }
+    }
+}
+//# sourceMappingURL=dedup-cache.js.map

package/dist/src/channels/dedup-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup-cache.js","sourceRoot":"","sources":["../../../src/channels/dedup-cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;GASG;AAEH,MAAM,cAAc,GAAG,MAAM,CAAC;AAC9B,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC,MAAM,OAAO,iBAAiB;IACX,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACjC,KAAK,CAAS;IAE/B,YAAY,KAAK,GAAG,cAAc;QAChC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED;;;OAGG;IACH,WAAW,CAAC,WAAmB,EAAE,SAAiB;QAChD,MAAM,GAAG,GAAG,GAAG,WAAW,IAAI,SAAS,EAAE,CAAC;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEvB,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,kBAAkB,EAAE,CAAC;YACxC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAClB,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACxB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;IAEO,KAAK,CAAC,GAAW;QACvB,KAAK,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YAChC,IAAI,GAAG,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;gBAC1B,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/src/channels/dedup-cache.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export {};

package/dist/src/channels/dedup-cache.test.js

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { MessageDedupCache } from './dedup-cache.js';
+describe('MessageDedupCache', () => {
+    let cache;
+    beforeEach(() => {
+        cache = new MessageDedupCache();
+    });
+    it('returns false for new messages', () => {
+        expect(cache.isDuplicate('telegram', '123')).toBe(false);
+    });
+    it('returns true for duplicate messages', () => {
+        cache.isDuplicate('telegram', '123');
+        expect(cache.isDuplicate('telegram', '123')).toBe(true);
+    });
+    it('treats different message IDs as distinct', () => {
+        cache.isDuplicate('telegram', '123');
+        expect(cache.isDuplicate('telegram', '456')).toBe(false);
+    });
+    it('treats different channel types as distinct', () => {
+        cache.isDuplicate('telegram', '123');
+        expect(cache.isDuplicate('slack', '123')).toBe(false);
+    });
+    it('tracks cache size', () => {
+        cache.isDuplicate('telegram', '1');
+        cache.isDuplicate('telegram', '2');
+        expect(cache.size).toBe(2);
+    });
+    it('evicts stale entries when threshold is exceeded', () => {
+        // Use a very short TTL for testing
+        const shortCache = new MessageDedupCache(1); // 1ms TTL
+        // Fill past eviction threshold
+        for (let i = 0; i < 1001; i++) {
+            shortCache.isDuplicate('telegram', String(i));
+        }
+        // Wait a tick for TTL to expire
+        const start = Date.now();
+        while (Date.now() - start < 5) {
+            // busy wait
+        }
+        // Next isDuplicate should trigger eviction
+        shortCache.isDuplicate('telegram', 'trigger');
+        // Stale entries should be gone (only 'trigger' remains)
+        expect(shortCache.size).toBeLessThanOrEqual(2);
+    });
+});
+//# sourceMappingURL=dedup-cache.test.js.map

package/dist/src/channels/dedup-cache.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup-cache.test.js","sourceRoot":"","sources":["../../../src/channels/dedup-cache.test.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAC,MAAM,QAAQ,CAAC;AACxD,OAAO,EAAC,iBAAiB,EAAC,MAAM,kBAAkB,CAAC;AAEnD,QAAQ,CAAC,mBAAmB,EAAE,GAAG,EAAE;IACjC,IAAI,KAAwB,CAAC;IAE7B,UAAU,CAAC,GAAG,EAAE;QACd,KAAK,GAAG,IAAI,iBAAiB,EAAE,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;QACxC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,KAAK,CAAC,WAAW,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QACrC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,KAAK,CAAC,WAAW,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QACrC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,KAAK,CAAC,WAAW,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QACrC,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mBAAmB,EAAE,GAAG,EAAE;QAC3B,KAAK,CAAC,WAAW,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QACnC,KAAK,CAAC,WAAW,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QACnC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,mCAAmC;QACnC,MAAM,UAAU,GAAG,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU;QAEvD,+BAA+B;QAC/B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;YAC9B,UAAU,CAAC,WAAW,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAChD,CAAC;QAED,gCAAgC;QAChC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC;YAC9B,YAAY;QACd,CAAC;QAED,2CAA2C;QAC3C,UAAU,CAAC,WAAW,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;QAC9C,wDAAwD;QACxD,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/src/channels/errors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { AmodalError } from '../errors.js';
+/**
+ * Error loading a channel plugin package (missing, invalid export shape).
+ */
+export declare class ChannelPluginError extends AmodalError {
+    readonly channelType: string;
+    constructor(message: string, options: {
+        channelType: string;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+/**
+ * Error validating a channel's config block against its plugin schema.
+ */
+export declare class ChannelConfigError extends AmodalError {
+    readonly channelType: string;
+    constructor(message: string, options: {
+        channelType: string;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}

package/dist/src/channels/errors.js

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import { AmodalError } from '../errors.js';
+// ---------------------------------------------------------------------------
+// Channel plugin errors
+// ---------------------------------------------------------------------------
+/**
+ * Error loading a channel plugin package (missing, invalid export shape).
+ */
+export class ChannelPluginError extends AmodalError {
+    channelType;
+    constructor(message, options) {
+        super('CHANNEL_PLUGIN_ERROR', message, {
+            channelType: options.channelType,
+            ...options.context,
+        }, options.cause);
+        this.name = 'ChannelPluginError';
+        this.channelType = options.channelType;
+    }
+}
+/**
+ * Error validating a channel's config block against its plugin schema.
+ */
+export class ChannelConfigError extends AmodalError {
+    channelType;
+    constructor(message, options) {
+        super('CHANNEL_CONFIG_ERROR', message, {
+            channelType: options.channelType,
+            ...options.context,
+        }, options.cause);
+        this.name = 'ChannelConfigError';
+        this.channelType = options.channelType;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/src/channels/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../src/channels/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAC,WAAW,EAAC,MAAM,cAAc,CAAC;AAEzC,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IACxC,WAAW,CAAS;IAE7B,YACE,OAAe,EACf,OAIC;QAED,KAAK,CAAC,sBAAsB,EAAE,OAAO,EAAE;YACrC,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,GAAG,OAAO,CAAC,OAAO;SACnB,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAClB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACzC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,kBAAmB,SAAQ,WAAW;IACxC,WAAW,CAAS;IAE7B,YACE,OAAe,EACf,OAIC;QAED,KAAK,CAAC,sBAAsB,EAAE,OAAO,EAAE;YACrC,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,GAAG,OAAO,CAAC,OAAO;SACnB,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;QAClB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IACzC,CAAC;CACF"}

package/dist/src/channels/in-memory-session-mapper.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+/**
+ * In-memory channel session mapper.
+ *
+ * Simple Map-backed implementation for environments without a database
+ * (snapshot preview server, testing). Sessions are not persisted across
+ * restarts — that's fine for preview and test use cases.
+ */
+import type { ChannelSessionMapper, ChannelSessionMapResult } from '@amodalai/types';
+import type { CreateChannelSession } from './channel-session-mapper.js';
+import type { Logger } from '../logger.js';
+export interface InMemoryChannelSessionMapperOptions {
+    logger: Logger;
+    eventBus?: {
+        emit(payload: {
+            type: string;
+            [key: string]: unknown;
+        }): unknown;
+    };
+}
+export declare class InMemoryChannelSessionMapper implements ChannelSessionMapper {
+    private readonly sessions;
+    private readonly logger;
+    private readonly eventBus?;
+    private createSession;
+    constructor(opts: InMemoryChannelSessionMapperOptions);
+    setSessionFactory(factory: CreateChannelSession): void;
+    findOrCreateSession(channelType: string, channelUserId: string, displayName?: string): Promise<ChannelSessionMapResult>;
+    resetSession(channelType: string, channelUserId: string): Promise<void>;
+}

package/dist/src/channels/in-memory-session-mapper.js

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+export class InMemoryChannelSessionMapper {
+    sessions = new Map();
+    logger;
+    eventBus;
+    createSession = null;
+    constructor(opts) {
+        this.logger = opts.logger;
+        this.eventBus = opts.eventBus;
+    }
+    setSessionFactory(factory) {
+        this.createSession = factory;
+    }
+    async findOrCreateSession(channelType, channelUserId, displayName) {
+        const key = `${channelType}:${channelUserId}`;
+        const existing = this.sessions.get(key);
+        if (existing) {
+            this.logger.debug('channel_session_found', { channelType, channelUserId, sessionId: existing });
+            return { sessionId: existing, isNew: false };
+        }
+        if (!this.createSession) {
+            throw new Error('Channel session mapper: session factory not set. Call setSessionFactory() first.');
+        }
+        const channelOrigin = {
+            channelType,
+            channelUserId,
+            channelUserDisplay: displayName,
+        };
+        const { sessionId } = this.createSession(channelOrigin);
+        this.sessions.set(key, sessionId);
+        this.logger.info('channel_session_created', { channelType, channelUserId, sessionId });
+        this.eventBus?.emit({
+            type: 'channel_session_created',
+            channelType,
+            channelUserId,
+            sessionId,
+        });
+        return { sessionId, isNew: true };
+    }
+    async resetSession(channelType, channelUserId) {
+        const key = `${channelType}:${channelUserId}`;
+        this.sessions.delete(key);
+        this.logger.info('channel_session_reset', { channelType, channelUserId });
+    }
+}
+//# sourceMappingURL=in-memory-session-mapper.js.map

package/dist/src/channels/in-memory-session-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-session-mapper.js","sourceRoot":"","sources":["../../../src/channels/in-memory-session-mapper.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqBH,MAAM,OAAO,4BAA4B;IACtB,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IACrC,MAAM,CAAS;IACf,QAAQ,CAAmD;IACpE,aAAa,GAAgC,IAAI,CAAC;IAE1D,YAAY,IAAyC;QACnD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;IAChC,CAAC;IAED,iBAAiB,CAAC,OAA6B;QAC7C,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;IAC/B,CAAC;IAED,KAAK,CAAC,mBAAmB,CACvB,WAAmB,EACnB,aAAqB,EACrB,WAAoB;QAEpB,MAAM,GAAG,GAAG,GAAG,WAAW,IAAI,aAAa,EAAE,CAAC;QAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAExC,IAAI,QAAQ,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,EAAE,EAAC,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,QAAQ,EAAC,CAAC,CAAC;YAC9F,OAAO,EAAC,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAC,CAAC;QAC7C,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,kFAAkF,CAAC,CAAC;QACtG,CAAC;QAED,MAAM,aAAa,GAAkB;YACnC,WAAW;YACX,aAAa;YACb,kBAAkB,EAAE,WAAW;SAChC,CAAC;QACF,MAAM,EAAC,SAAS,EAAC,GAAG,IAAI,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC;QACtD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAElC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,yBAAyB,EAAE,EAAC,WAAW,EAAE,aAAa,EAAE,SAAS,EAAC,CAAC,CAAC;QACrF,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC;YAClB,IAAI,EAAE,yBAAyB;YAC/B,WAAW;YACX,aAAa;YACb,SAAS;SACV,CAAC,CAAC;QAEH,OAAO,EAAC,SAAS,EAAE,KAAK,EAAE,IAAI,EAAC,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,YAAY,CAChB,WAAmB,EACnB,aAAqB;QAErB,MAAM,GAAG,GAAG,GAAG,WAAW,IAAI,aAAa,EAAE,CAAC;QAC9C,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,uBAAuB,EAAE,EAAC,WAAW,EAAE,aAAa,EAAC,CAAC,CAAC;IAC1E,CAAC;CACF"}

package/dist/src/channels/plugin-loader.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2026 Amodal Labs, Inc.
+ * SPDX-License-Identifier: MIT
+ */
+import type { ChannelAdapter } from '@amodalai/types';
+import type { Logger } from '../logger.js';
+export interface LoadChannelPluginsOptions {
+    /** The `channels` block from amodal.json (env refs already resolved). */
+    channelsConfig: Record<string, unknown>;
+    /** Absolute path to the repo root (for local channel discovery + node_modules). */
+    repoPath: string;
+    /** The `packages` array from amodal.json — used to find channel packages. */
+    packages?: string[];
+    logger: Logger;
+}
+/**
+ * Load and initialize channel adapters for all configured channels.
+ */
+export declare function loadChannelPlugins(opts: LoadChannelPluginsOptions): Promise<Map<string, ChannelAdapter>>;