@proletariat/cli 0.3.111 → 0.3.112

package/dist/lib/gateway/channel-factory.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Channel factory (PRLT-1255)
+ *
+ * Single place that knows how to decode a persisted MessagingChannelRecord
+ * into a live MessagingChannel instance. Commands and the gateway daemon
+ * call this so they never import individual adapters directly.
+ *
+ * To add Slack/Discord/WhatsApp later: import the new adapter and add a
+ * case to `buildChannelFromRecord`. No other file needs to change.
+ */
+import type { MessagingChannelRecord } from '../machine-db.js';
+import type { MessagingChannel } from './types.js';
+export declare function buildChannelFromRecord(record: MessagingChannelRecord): MessagingChannel;

package/dist/lib/gateway/channel-factory.js

@@ -0,0 +1,37 @@
+/**
+ * Channel factory (PRLT-1255)
+ *
+ * Single place that knows how to decode a persisted MessagingChannelRecord
+ * into a live MessagingChannel instance. Commands and the gateway daemon
+ * call this so they never import individual adapters directly.
+ *
+ * To add Slack/Discord/WhatsApp later: import the new adapter and add a
+ * case to `buildChannelFromRecord`. No other file needs to change.
+ */
+import { TelegramChannel } from './channels/telegram.js';
+export function buildChannelFromRecord(record) {
+    switch (record.type) {
+        case 'telegram': {
+            const config = parseConfig(record.configJson, record.name);
+            if (!config.token) {
+                throw new Error(`Channel "${record.name}" has no Telegram token configured`);
+            }
+            if (!Array.isArray(config.allowlist)) {
+                throw new TypeError(`Channel "${record.name}" has a malformed allowlist`);
+            }
+            return new TelegramChannel({ config });
+        }
+        default:
+            throw new Error(`Unknown channel type "${record.type}" for "${record.name}"`);
+    }
+}
+function parseConfig(json, channelName) {
+    try {
+        return JSON.parse(json);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Channel "${channelName}" has invalid config JSON: ${msg}`);
+    }
+}
+//# sourceMappingURL=channel-factory.js.map

package/dist/lib/gateway/channel-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel-factory.js","sourceRoot":"","sources":["../../../src/lib/gateway/channel-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAExD,MAAM,UAAU,sBAAsB,CAAC,MAA8B;IACnE,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,UAAU,CAAC,CAAC,CAAC;YAChB,MAAM,MAAM,GAAG,WAAW,CAAwB,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;YACjF,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;gBAClB,MAAM,IAAI,KAAK,CAAC,YAAY,MAAM,CAAC,IAAI,oCAAoC,CAAC,CAAA;YAC9E,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;gBACrC,MAAM,IAAI,SAAS,CAAC,YAAY,MAAM,CAAC,IAAI,6BAA6B,CAAC,CAAA;YAC3E,CAAC;YACD,OAAO,IAAI,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;QACxC,CAAC;QACD;YACE,MAAM,IAAI,KAAK,CAAC,yBAAyB,MAAM,CAAC,IAAI,UAAU,MAAM,CAAC,IAAI,GAAG,CAAC,CAAA;IACjF,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAI,IAAY,EAAE,WAAmB;IACvD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAA;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAC5D,MAAM,IAAI,KAAK,CAAC,YAAY,WAAW,8BAA8B,GAAG,EAAE,CAAC,CAAA;IAC7E,CAAC;AACH,CAAC"}

package/dist/lib/gateway/channels/telegram.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Telegram Channel Adapter (PRLT-1255)
+ *
+ * Polling-mode Telegram bot that implements MessagingChannel.
+ *
+ * Uses Telegram's `getUpdates` long-polling API — no webhook, no server
+ * required. Messages arrive over an outgoing HTTPS request, so the bot
+ * works fine from behind NAT, on a laptop, or in a container.
+ *
+ * This adapter is the ONLY Telegram-aware code in the gateway. To add
+ * Slack/Discord/WhatsApp later: write a new adapter next to this file,
+ * implementing the same interface. The router and commands do not need
+ * to change.
+ *
+ * @see PRLT-1251 (Messaging Gateway epic)
+ */
+import type { ChannelAddress, MessageHandler, MessagingChannel, TelegramChannelConfig } from '../types.js';
+interface TelegramUser {
+    id: number;
+    is_bot?: boolean;
+    first_name?: string;
+    last_name?: string;
+    username?: string;
+}
+interface TelegramChat {
+    id: number;
+    type: 'private' | 'group' | 'supergroup' | 'channel';
+    title?: string;
+    username?: string;
+    first_name?: string;
+}
+interface TelegramMessage {
+    message_id: number;
+    from?: TelegramUser;
+    chat: TelegramChat;
+    date: number;
+    text?: string;
+}
+export interface TelegramUpdate {
+    update_id: number;
+    message?: TelegramMessage;
+    edited_message?: TelegramMessage;
+}
+/**
+ * Minimal Telegram Bot API client. Broken out so tests can substitute a
+ * fake client without touching the network.
+ */
+export interface TelegramClient {
+    getUpdates(options: {
+        offset?: number;
+        timeoutSec?: number;
+    }): Promise<TelegramUpdate[]>;
+    sendMessage(chatId: string | number, text: string): Promise<void>;
+}
+/**
+ * Options for constructing a TelegramChannel.
+ *
+ * - `config`: TelegramChannelConfig loaded from machine.db.
+ * - `client`: optional injectable Telegram client (tests use this).
+ * - `logger`: optional error/info sink. Defaults to console.
+ */
+export interface TelegramChannelOptions {
+    config: TelegramChannelConfig;
+    client?: TelegramClient;
+    logger?: {
+        info?: (msg: string) => void;
+        error?: (msg: string, err?: unknown) => void;
+    };
+    /**
+     * How long to back off after a failed poll. Defaults to 5000ms.
+     * Tests shorten this so they don't have to sit on a 5s sleep.
+     */
+    errorBackoffMs?: number;
+}
+/**
+ * Polling-mode Telegram adapter.
+ *
+ * The read loop is a vanilla `while (running) await getUpdates()`. We
+ * acknowledge updates by advancing the `offset` cursor to the id after
+ * the highest update seen in the batch — this is Telegram's documented
+ * delete semantics for getUpdates.
+ */
+export declare class TelegramChannel implements MessagingChannel {
+    readonly name = "telegram";
+    private handler;
+    private running;
+    private loopPromise;
+    private offset;
+    private readonly client;
+    private readonly config;
+    private readonly logger;
+    private readonly errorBackoffMs;
+    constructor(options: TelegramChannelOptions);
+    onMessage(handler: MessageHandler): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    sendMessage(to: ChannelAddress, text: string): Promise<void>;
+    /**
+     * Main polling loop. Runs until `stop()` flips `running` false.
+     *
+     * Errors are caught, logged, and followed by a small backoff so a
+     * transient network blip doesn't hot-spin the bot against Telegram.
+     *
+     * The awaits are deliberately sequential: Telegram long-poll demands
+     * one outstanding getUpdates at a time per bot, and we must drain
+     * each batch before advancing the cursor.
+     */
+    private runLoop;
+    /**
+     * Normalize a Telegram update into a generic `Message` and hand it to
+     * the router. Drops non-text messages silently (MVP is text-only).
+     */
+    private handleUpdate;
+}
+export {};

package/dist/lib/gateway/channels/telegram.js

@@ -0,0 +1,215 @@
+/**
+ * Telegram Channel Adapter (PRLT-1255)
+ *
+ * Polling-mode Telegram bot that implements MessagingChannel.
+ *
+ * Uses Telegram's `getUpdates` long-polling API — no webhook, no server
+ * required. Messages arrive over an outgoing HTTPS request, so the bot
+ * works fine from behind NAT, on a laptop, or in a container.
+ *
+ * This adapter is the ONLY Telegram-aware code in the gateway. To add
+ * Slack/Discord/WhatsApp later: write a new adapter next to this file,
+ * implementing the same interface. The router and commands do not need
+ * to change.
+ *
+ * @see PRLT-1251 (Messaging Gateway epic)
+ */
+class HttpTelegramClient {
+    token;
+    constructor(token) {
+        this.token = token;
+    }
+    url(method) {
+        return `https://api.telegram.org/bot${this.token}/${method}`;
+    }
+    async getUpdates(options) {
+        const params = new URLSearchParams();
+        if (options.offset !== undefined)
+            params.set('offset', String(options.offset));
+        params.set('timeout', String(options.timeoutSec ?? 25));
+        // Only request message updates — we don't need callback queries, polls, etc.
+        params.set('allowed_updates', JSON.stringify(['message']));
+        // eslint-disable-next-line n/no-unsupported-features/node-builtins -- global fetch is stable in Node 20+
+        const res = await fetch(`${this.url('getUpdates')}?${params.toString()}`);
+        if (!res.ok) {
+            throw new Error(`Telegram getUpdates failed: HTTP ${res.status}`);
+        }
+        const body = (await res.json());
+        if (!body.ok) {
+            throw new Error(`Telegram getUpdates failed: ${body.description ?? 'unknown'}`);
+        }
+        return body.result ?? [];
+    }
+    async sendMessage(chatId, text) {
+        // eslint-disable-next-line n/no-unsupported-features/node-builtins -- global fetch is stable in Node 20+
+        const res = await fetch(this.url('sendMessage'), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ chat_id: chatId, text }),
+        });
+        if (!res.ok) {
+            throw new Error(`Telegram sendMessage failed: HTTP ${res.status}`);
+        }
+        const body = (await res.json());
+        if (!body.ok) {
+            throw new Error(`Telegram sendMessage failed: ${body.description ?? 'unknown'}`);
+        }
+    }
+}
+/**
+ * Polling-mode Telegram adapter.
+ *
+ * The read loop is a vanilla `while (running) await getUpdates()`. We
+ * acknowledge updates by advancing the `offset` cursor to the id after
+ * the highest update seen in the batch — this is Telegram's documented
+ * delete semantics for getUpdates.
+ */
+export class TelegramChannel {
+    name = 'telegram';
+    handler = null;
+    running = false;
+    loopPromise = null;
+    offset;
+    client;
+    config;
+    logger;
+    errorBackoffMs;
+    constructor(options) {
+        this.config = options.config;
+        this.client = options.client ?? new HttpTelegramClient(options.config.token);
+        this.logger = options.logger ?? {};
+        this.errorBackoffMs = options.errorBackoffMs ?? 5000;
+    }
+    onMessage(handler) {
+        this.handler = handler;
+    }
+    async start() {
+        if (this.running)
+            return;
+        if (!this.handler) {
+            throw new Error('TelegramChannel.start() called before onMessage() — no handler registered');
+        }
+        this.running = true;
+        this.loopPromise = this.runLoop();
+    }
+    async stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        if (this.loopPromise) {
+            try {
+                await this.loopPromise;
+            }
+            catch {
+                // Loop errors are already logged; ignore here so stop() is always clean.
+            }
+            this.loopPromise = null;
+        }
+    }
+    async sendMessage(to, text) {
+        if (to.channel !== this.name) {
+            throw new Error(`TelegramChannel cannot send to channel=${to.channel}`);
+        }
+        await this.client.sendMessage(to.id, text);
+    }
+    // ---------------------------------------------------------------------------
+    // Internals
+    // ---------------------------------------------------------------------------
+    /**
+     * Main polling loop. Runs until `stop()` flips `running` false.
+     *
+     * Errors are caught, logged, and followed by a small backoff so a
+     * transient network blip doesn't hot-spin the bot against Telegram.
+     *
+     * The awaits are deliberately sequential: Telegram long-poll demands
+     * one outstanding getUpdates at a time per bot, and we must drain
+     * each batch before advancing the cursor.
+     */
+    /* eslint-disable no-await-in-loop -- polling loop is intentionally sequential */
+    async runLoop() {
+        const pollInterval = this.config.pollIntervalMs ?? 0;
+        while (this.running) {
+            try {
+                const updates = await this.client.getUpdates({
+                    offset: this.offset,
+                    timeoutSec: 25,
+                });
+                for (const update of updates) {
+                    await this.handleUpdate(update);
+                    // Advance cursor past the highest update id we've seen.
+                    this.offset = update.update_id + 1;
+                }
+                if (pollInterval > 0)
+                    await sleep(pollInterval);
+            }
+            catch (err) {
+                this.logger.error?.('telegram: poll loop error', err);
+                // Backoff on errors so we don't hammer the API when the network
+                // is flaky or the token got revoked.
+                await sleep(this.errorBackoffMs);
+            }
+        }
+    }
+    /* eslint-enable no-await-in-loop */
+    /**
+     * Normalize a Telegram update into a generic `Message` and hand it to
+     * the router. Drops non-text messages silently (MVP is text-only).
+     */
+    async handleUpdate(update) {
+        const msg = update.message ?? update.edited_message;
+        if (!msg)
+            return;
+        if (!msg.text)
+            return; // MVP: text-only
+        if (!this.handler)
+            return;
+        // Reject messages from users not on the allowlist. We match on the
+        // sender's user id (falling back to chat id for groups where there
+        // is no `from`). Allowlist is explicit — empty list means "nobody".
+        const senderId = String(msg.from?.id ?? msg.chat.id);
+        if (!this.config.allowlist.includes(senderId)) {
+            this.logger.info?.(`telegram: dropping message from non-allowlisted user ${senderId}`);
+            return;
+        }
+        const address = {
+            channel: this.name,
+            // We always send replies to the chat, not the user — that way
+            // group chats work correctly in a future multi-user mode.
+            id: String(msg.chat.id),
+            displayName: resolveDisplayName(msg),
+        };
+        const normalized = {
+            id: `telegram:${msg.message_id}`,
+            channel: this.name,
+            from: address,
+            text: msg.text,
+            timestamp: new Date(msg.date * 1000),
+        };
+        try {
+            await this.handler(normalized);
+        }
+        catch (err) {
+            this.logger.error?.('telegram: handler failed', err);
+        }
+    }
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function resolveDisplayName(msg) {
+    const from = msg.from;
+    if (from?.username)
+        return `@${from.username}`;
+    if (from?.first_name) {
+        return from.last_name ? `${from.first_name} ${from.last_name}` : from.first_name;
+    }
+    if (msg.chat.title)
+        return msg.chat.title;
+    if (msg.chat.username)
+        return `@${msg.chat.username}`;
+    return undefined;
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=telegram.js.map

package/dist/lib/gateway/channels/telegram.js.map

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

package/dist/lib/gateway/router.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Messaging Gateway Router (PRLT-1255)
+ *
+ * Sits between N `MessagingChannel` adapters and the `prlt session poke`
+ * path. The router is intentionally small — it does four things:
+ *
+ *   1. Look up (or create) the agent mapping for `(channel, user)`.
+ *   2. Forward the user's text to that agent via a `SessionPoker`.
+ *   3. Ship the agent's response back via the channel's `sendMessage`.
+ *   4. Stamp channel + route usage timestamps in machine.db.
+ *
+ * Everything Telegram-specific lives in `channels/telegram.ts`. Everything
+ * storage-specific lives in `MachineDB`. This file owns the glue.
+ */
+import type { MachineDB } from '../machine-db.js';
+import type { MessagingChannel, Message } from './types.js';
+/**
+ * Indirection over `prlt session poke`. The default implementation shells
+ * out to the globally-installed `prlt` binary, but tests and embedders can
+ * inject a custom poker.
+ *
+ * Returning `null` means "message delivered, no response captured".
+ * Throwing means "failed to reach the agent at all".
+ */
+export interface SessionPoker {
+    poke(agent: string, message: string, options?: {
+        waitTimeoutSec?: number;
+    }): Promise<string | null>;
+}
+export interface MessagingGatewayOptions {
+    /** Machine DB handle used for channel/route persistence. */
+    db: MachineDB;
+    /** How to forward messages to an agent. Defaults to the shell poker. */
+    sessionPoker: SessionPoker;
+    /**
+     * Called when there is no existing route for a user. Must return the
+     * agent session id (typically an agent name) that should own this
+     * conversation going forward. Returning `null` rejects the message —
+     * useful for "deny if no mapping" policies.
+     */
+    resolveAgentForNewUser: (msg: Message) => Promise<string | null> | string | null;
+    /** Optional logger sink. Defaults to console. */
+    logger?: {
+        info?: (msg: string) => void;
+        error?: (msg: string, err?: unknown) => void;
+    };
+    /**
+     * How long to wait for an agent response before giving up and sending
+     * a "still working on it" message back. Defaults to 90 seconds.
+     */
+    waitTimeoutSec?: number;
+}
+export declare class MessagingGateway {
+    private channels;
+    private readonly db;
+    private readonly poker;
+    private readonly resolveAgentForNewUser;
+    private readonly logger;
+    private readonly waitTimeoutSec;
+    private started;
+    constructor(options: MessagingGatewayOptions);
+    /**
+     * Register a channel adapter. Wires the inbound handler but does NOT
+     * start the channel — the caller decides when to start() everything.
+     */
+    registerChannel(channel: MessagingChannel): void;
+    /** Get a previously-registered channel by name. */
+    getChannel(name: string): MessagingChannel | undefined;
+    /** List names of all registered channels. */
+    listChannelNames(): string[];
+    /** Start every registered channel in parallel. */
+    start(): Promise<void>;
+    /** Stop every registered channel in parallel. Safe to call multiple times. */
+    stop(): Promise<void>;
+    /**
+     * Route a single inbound message.
+     *
+     * This is exposed (not `private`) so tests can drive it directly
+     * without standing up a real channel adapter.
+     */
+    routeInbound(msg: Message): Promise<void>;
+    private createRouteForNewUser;
+    private safeReply;
+}

package/dist/lib/gateway/router.js

@@ -0,0 +1,140 @@
+/**
+ * Messaging Gateway Router (PRLT-1255)
+ *
+ * Sits between N `MessagingChannel` adapters and the `prlt session poke`
+ * path. The router is intentionally small — it does four things:
+ *
+ *   1. Look up (or create) the agent mapping for `(channel, user)`.
+ *   2. Forward the user's text to that agent via a `SessionPoker`.
+ *   3. Ship the agent's response back via the channel's `sendMessage`.
+ *   4. Stamp channel + route usage timestamps in machine.db.
+ *
+ * Everything Telegram-specific lives in `channels/telegram.ts`. Everything
+ * storage-specific lives in `MachineDB`. This file owns the glue.
+ */
+// =============================================================================
+// MessagingGateway
+// =============================================================================
+export class MessagingGateway {
+    channels = new Map();
+    db;
+    poker;
+    resolveAgentForNewUser;
+    logger;
+    waitTimeoutSec;
+    started = false;
+    constructor(options) {
+        this.db = options.db;
+        this.poker = options.sessionPoker;
+        this.resolveAgentForNewUser = options.resolveAgentForNewUser;
+        this.logger = options.logger ?? {};
+        this.waitTimeoutSec = options.waitTimeoutSec ?? 90;
+    }
+    /**
+     * Register a channel adapter. Wires the inbound handler but does NOT
+     * start the channel — the caller decides when to start() everything.
+     */
+    registerChannel(channel) {
+        if (this.channels.has(channel.name)) {
+            throw new Error(`Channel already registered: ${channel.name}`);
+        }
+        channel.onMessage(msg => this.routeInbound(msg));
+        this.channels.set(channel.name, channel);
+    }
+    /** Get a previously-registered channel by name. */
+    getChannel(name) {
+        return this.channels.get(name);
+    }
+    /** List names of all registered channels. */
+    listChannelNames() {
+        return [...this.channels.keys()];
+    }
+    /** Start every registered channel in parallel. */
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        await Promise.all([...this.channels.values()].map(ch => ch.start()));
+    }
+    /** Stop every registered channel in parallel. Safe to call multiple times. */
+    async stop() {
+        if (!this.started)
+            return;
+        this.started = false;
+        await Promise.all([...this.channels.values()].map(ch => ch.stop()));
+    }
+    // ---------------------------------------------------------------------------
+    // Core routing
+    // ---------------------------------------------------------------------------
+    /**
+     * Route a single inbound message.
+     *
+     * This is exposed (not `private`) so tests can drive it directly
+     * without standing up a real channel adapter.
+     */
+    async routeInbound(msg) {
+        const channel = this.channels.get(msg.channel);
+        if (!channel) {
+            this.logger.error?.(`router: no channel registered for ${msg.channel}`);
+            return;
+        }
+        if (!msg.text || msg.text.trim().length === 0) {
+            // MVP: text-only. Voice notes land in PRLT-1234.
+            this.logger.info?.(`router: dropping empty message ${msg.id}`);
+            return;
+        }
+        // 1. Find or create the route.
+        let route = this.db.getMessagingRoute(msg.channel, msg.from.id);
+        if (!route) {
+            route = await this.createRouteForNewUser(msg);
+            if (!route) {
+                // Denied by policy — silently drop, do not leak whether the user
+                // exists to a possibly-hostile sender.
+                return;
+            }
+        }
+        // 2. Forward to the agent session.
+        let response = null;
+        try {
+            response = await this.poker.poke(route.agentSessionId, msg.text, {
+                waitTimeoutSec: this.waitTimeoutSec,
+            });
+        }
+        catch (err) {
+            this.logger.error?.(`router: poke failed for ${route.agentSessionId}`, err);
+            await this.safeReply(channel, msg, `Sorry, I couldn't reach ${route.agentSessionId}. Try again in a moment.`);
+            return;
+        }
+        // 3. Stamp usage.
+        this.db.touchMessagingRoute(msg.channel, msg.from.id);
+        this.db.touchMessagingChannel(msg.channel);
+        // 4. Reply (if we captured anything).
+        if (response && response.trim().length > 0) {
+            await this.safeReply(channel, msg, response);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Helpers
+    // ---------------------------------------------------------------------------
+    async createRouteForNewUser(msg) {
+        const agentSessionId = await this.resolveAgentForNewUser(msg);
+        if (!agentSessionId) {
+            this.logger.info?.(`router: no agent resolved for ${msg.channel}:${msg.from.id}`);
+            return null;
+        }
+        return this.db.upsertMessagingRoute({
+            channel: msg.channel,
+            userId: msg.from.id,
+            agentSessionId,
+        });
+    }
+    async safeReply(channel, msg, text) {
+        try {
+            await channel.sendMessage(msg.from, text);
+        }
+        catch (err) {
+            this.logger.error?.(`router: sendMessage failed for ${channel.name}`, err);
+        }
+    }
+}
+//# sourceMappingURL=router.js.map

package/dist/lib/gateway/router.js.map

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

package/dist/lib/gateway/session-poker.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Default SessionPoker implementation (PRLT-1255)
+ *
+ * Shells out to `prlt session poke <agent> <message> --wait --timeout N --json`
+ * and extracts the captured response from the JSON output.
+ *
+ * The router code itself is agnostic to this — tests inject a fake
+ * SessionPoker. This file exists so production code can pick up the real
+ * poker with zero wiring.
+ */
+import type { SessionPoker } from './router.js';
+export interface ShellSessionPokerOptions {
+    /**
+     * Name of the binary to exec. Defaults to `prlt` on PATH. Tests can
+     * point this at a shim script.
+     */
+    binary?: string;
+    /**
+     * Working directory for the exec call. Defaults to the current process
+     * cwd — `prlt session poke` resolves workspace context from there.
+     */
+    cwd?: string;
+}
+/**
+ * Shell-based SessionPoker. Uses `execFile` (no shell) so nothing in the
+ * message body can trigger shell expansion or injection.
+ */
+export declare class ShellSessionPoker implements SessionPoker {
+    private readonly binary;
+    private readonly cwd;
+    constructor(options?: ShellSessionPokerOptions);
+    poke(agent: string, message: string, options?: {
+        waitTimeoutSec?: number;
+    }): Promise<string | null>;
+}