@proletariat/cli 0.3.110 → 0.3.112

package/dist/lib/gateway/session-poker.js

@@ -0,0 +1,85 @@
+/**
+ * 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 { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+/**
+ * Shell-based SessionPoker. Uses `execFile` (no shell) so nothing in the
+ * message body can trigger shell expansion or injection.
+ */
+export class ShellSessionPoker {
+    binary;
+    cwd;
+    constructor(options = {}) {
+        this.binary = options.binary ?? 'prlt';
+        this.cwd = options.cwd;
+    }
+    async poke(agent, message, options) {
+        const timeoutSec = options?.waitTimeoutSec ?? 90;
+        const args = [
+            'session',
+            'poke',
+            agent,
+            message,
+            '--wait',
+            '--timeout',
+            String(timeoutSec),
+            '--json',
+        ];
+        const { stdout } = await execFileAsync(this.binary, args, {
+            cwd: this.cwd,
+            // Give the child a little longer than the internal wait so we
+            // don't race the --timeout.
+            timeout: (timeoutSec + 15) * 1000,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        // `prlt session poke --json` emits a single JSON object on success.
+        const parsed = parseFirstJsonObject(stdout);
+        if (!parsed)
+            return null;
+        if (typeof parsed.response === 'string')
+            return parsed.response;
+        return null;
+    }
+}
+/**
+ * Pull the first JSON object out of a mixed stdout stream. Needed because
+ * some oclif commands still emit human banners alongside `--json` output
+ * depending on terminal state.
+ */
+function parseFirstJsonObject(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed)
+        return null;
+    // Fast path: whole payload is JSON.
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed && typeof parsed === 'object')
+            return parsed;
+    }
+    catch {
+        // Fall through to scan.
+    }
+    const start = trimmed.indexOf('{');
+    const end = trimmed.lastIndexOf('}');
+    if (start === -1 || end === -1 || end < start)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed.slice(start, end + 1));
+        if (parsed && typeof parsed === 'object')
+            return parsed;
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+//# sourceMappingURL=session-poker.js.map

package/dist/lib/gateway/session-poker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-poker.js","sourceRoot":"","sources":["../../../src/lib/gateway/session-poker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAGrC,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAA;AAezC;;;GAGG;AACH,MAAM,OAAO,iBAAiB;IACX,MAAM,CAAQ;IACd,GAAG,CAAoB;IAExC,YAAY,UAAoC,EAAE;QAChD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAA;QACtC,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,CAAA;IACxB,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAa,EAAE,OAAe,EAAE,OAAqC;QAC9E,MAAM,UAAU,GAAG,OAAO,EAAE,cAAc,IAAI,EAAE,CAAA;QAChD,MAAM,IAAI,GAAG;YACX,SAAS;YACT,MAAM;YACN,KAAK;YACL,OAAO;YACP,QAAQ;YACR,WAAW;YACX,MAAM,CAAC,UAAU,CAAC;YAClB,QAAQ;SACT,CAAA;QAED,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE;YACxD,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,8DAA8D;YAC9D,4BAA4B;YAC5B,OAAO,EAAE,CAAC,UAAU,GAAG,EAAE,CAAC,GAAG,IAAI;YACjC,SAAS,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI;SAC3B,CAAC,CAAA;QAEF,oEAAoE;QACpE,MAAM,MAAM,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAA;QAC3C,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAA;QACxB,IAAI,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;YAAE,OAAO,MAAM,CAAC,QAAQ,CAAA;QAC/D,OAAO,IAAI,CAAA;IACb,CAAC;CACF;AAED;;;;GAIG;AACH,SAAS,oBAAoB,CAAC,MAAc;IAC1C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,EAAE,CAAA;IAC7B,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAA;IAEzB,oCAAoC;IACpC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QAClC,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,MAAiC,CAAA;IACpF,CAAC;IAAC,MAAM,CAAC;QACP,wBAAwB;IAC1B,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAClC,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,CAAC,CAAA;IACpC,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,GAAG,GAAG,KAAK;QAAE,OAAO,IAAI,CAAA;IAE1D,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAA;QACxD,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,MAAiC,CAAA;IACpF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

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

@@ -0,0 +1,124 @@
+/**
+ * Messaging Gateway Types
+ *
+ * Defines the channel-agnostic abstraction that sits between external
+ * messaging platforms (Telegram, Slack, Discord, WhatsApp, ...) and the
+ * internal `prlt session poke` path that forwards user input to agent
+ * sessions.
+ *
+ * The gateway is designed so adding a new platform is a new adapter that
+ * implements `MessagingChannel` — zero changes to the router, storage,
+ * or commands.
+ *
+ * Epic: PRLT-1251 (Messaging Gateway)
+ * Ticket: PRLT-1255 (Telegram bot MVP)
+ */
+/**
+ * A platform-specific identifier for a user or conversation on a channel.
+ *
+ * `channel` is the channel name (e.g. "telegram", "slack"), and `id` is the
+ * platform's own identifier. For Telegram, `id` is the numeric chat id
+ * encoded as a string (e.g. `"123456789"`).
+ *
+ * `displayName` is a best-effort human-readable label for logs/UI. It must
+ * never be used for routing.
+ */
+export interface ChannelAddress {
+    channel: string;
+    id: string;
+    displayName?: string;
+}
+/**
+ * A normalized inbound message from any channel.
+ *
+ * Adapters convert platform payloads into this shape before handing them
+ * to the router. Adapters are responsible for idempotency via `id` — the
+ * router uses it to de-duplicate re-delivered messages.
+ */
+export interface Message {
+    /** Stable per-channel message id (platform's id, stringified). */
+    id: string;
+    /** Channel name (matches MessagingChannel.name). */
+    channel: string;
+    /** Who sent the message. */
+    from: ChannelAddress;
+    /** Optional text body. Either `text` or `audio` should be set. */
+    text?: string;
+    /** Optional raw audio payload (voice note / audio message). */
+    audio?: Buffer;
+    /** Server-side timestamp of the message. */
+    timestamp: Date;
+}
+/**
+ * Handler signature used by channels to deliver inbound messages to the
+ * router. Channels call this from their read loop.
+ */
+export type MessageHandler = (msg: Message) => Promise<void>;
+/**
+ * A bidirectional adapter to an external messaging platform.
+ *
+ * Implementations MUST:
+ * - Normalize their inbound payloads into `Message` objects.
+ * - Deliver inbound messages by invoking the handler registered via
+ *   `onMessage`.
+ * - Honor `start()` / `stop()` lifecycle cleanly so the gateway can shut
+ *   down without leaking sockets, timers, or worker threads.
+ *
+ * Adapters MUST NOT touch the database, the session system, or the
+ * router directly. Their only public entry points are the methods
+ * defined here.
+ */
+export interface MessagingChannel {
+    /** Stable channel name (e.g. "telegram"). Used as a primary key. */
+    readonly name: string;
+    /** Begin reading messages (e.g. open socket, start polling loop). */
+    start(): Promise<void>;
+    /** Stop reading and release all resources. Must be idempotent. */
+    stop(): Promise<void>;
+    /** Register the inbound-message handler. Called before `start()`. */
+    onMessage(handler: MessageHandler): void;
+    /** Send an outbound text message to a ChannelAddress. */
+    sendMessage(to: ChannelAddress, text: string): Promise<void>;
+    /** Optional: send an outbound voice note (PRLT-1234 territory). */
+    sendVoiceNote?(to: ChannelAddress, audio: Buffer): Promise<void>;
+}
+/**
+ * Persisted configuration for a registered channel.
+ *
+ * Stored in `machine.db` → `messaging_channels`. `configJson` is an
+ * adapter-specific blob — for Telegram it contains the bot token and
+ * allowlist of permitted user ids.
+ */
+export interface MessagingChannelRecord {
+    name: string;
+    type: string;
+    configJson: string;
+    active: boolean;
+    lastMessageAt: Date | undefined;
+}
+/**
+ * A user → agent routing binding. The router creates one on first
+ * contact and reuses it for all subsequent messages.
+ */
+export interface MessagingRouteRecord {
+    channel: string;
+    userId: string;
+    agentSessionId: string;
+    createdAt: Date;
+    lastUsedAt: Date | undefined;
+}
+/**
+ * Shape of `messaging_channels.config_json` when `type === "telegram"`.
+ *
+ * - `token`: Telegram Bot API token from @BotFather.
+ * - `allowlist`: numeric Telegram user ids (stringified) that are allowed
+ *   to poke agents. Messages from non-allowlisted users are rejected at
+ *   the router boundary.
+ * - `pollIntervalMs`: how often to long-poll getUpdates. Defaults to 0
+ *   (use Telegram's long-poll timeout of 25 seconds).
+ */
+export interface TelegramChannelConfig {
+    token: string;
+    allowlist: string[];
+    pollIntervalMs?: number;
+}

package/dist/lib/gateway/types.js

@@ -0,0 +1,17 @@
+/**
+ * Messaging Gateway Types
+ *
+ * Defines the channel-agnostic abstraction that sits between external
+ * messaging platforms (Telegram, Slack, Discord, WhatsApp, ...) and the
+ * internal `prlt session poke` path that forwards user input to agent
+ * sessions.
+ *
+ * The gateway is designed so adding a new platform is a new adapter that
+ * implements `MessagingChannel` — zero changes to the router, storage,
+ * or commands.
+ *
+ * Epic: PRLT-1251 (Messaging Gateway)
+ * Ticket: PRLT-1255 (Telegram bot MVP)
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/gateway/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/lib/machine-db-mirror.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Machine DB Mirror — bridges workspace.db executions to machine.db.
+ *
+ * `prlt work run` and `prlt orchestrate machine` write directly to machine.db.
+ * `prlt work start` and `prlt orchestrator start` write to workspace.db for
+ * ticket-linked state, but also need to mirror those executions to machine.db
+ * so that:
+ *
+ *   - `prlt session list` from outside an HQ sees them
+ *   - `prlt orchestrator status` from `/tmp` sees orchestrators in every HQ
+ *   - The machine-level supervision story (PRLT-1249) actually works
+ *
+ * Machine.db writes are always best-effort. workspace.db is still authoritative
+ * for ticketed work; if mirroring fails we silently swallow the error and keep
+ * the primary flow running.
+ */
+import { MachineDB, type MachineExecution, type MachineExecutionStatus } from './machine-db.js';
+export interface MirrorCreateInput {
+    /** Ticket ID (e.g. TKT-123, PRLT-456). Use 'ORCH' / 'prlt' for orchestrators. */
+    ticketId: string;
+    /** Agent name. For orchestrators use `orchestrator-{name}`. */
+    agentName: string;
+    executor: string;
+    environment: string;
+    /** Working directory — repo path for work, HQ path for orchestrators. */
+    repoPath: string;
+    branch?: string;
+    persistent?: boolean;
+    /** Optional human-readable prompt. Falls back to "ticketId agentName". */
+    prompt?: string;
+    /**
+     * Optional override for the machine.db path. When omitted, uses
+     * `~/.proletariat/machine.db`. Used by tests to avoid colliding with the
+     * user's real machine DB.
+     */
+    machineDbPath?: string;
+}
+export interface MirrorHandle {
+    machineDb: MachineDB;
+    execution: MachineExecution;
+}
+/**
+ * Create a machine.db execution row mirroring a workspace.db execution.
+ *
+ * Returns a handle for later status/process-info updates, or `null` if the
+ * machine DB could not be opened or the row could not be inserted.
+ *
+ * Callers MUST pass the handle to {@link closeMirrorExecution} when done.
+ */
+export declare function createMirrorExecution(input: MirrorCreateInput): MirrorHandle | null;
+/**
+ * Update a mirrored execution with new status and/or process info. All errors
+ * are swallowed: machine.db is the secondary store and must never break the
+ * primary flow.
+ */
+export declare function updateMirrorExecution(handle: MirrorHandle | null, update: {
+    status?: MachineExecutionStatus;
+    sessionId?: string;
+    containerId?: string;
+    branch?: string;
+    errorMessage?: string;
+}): void;
+/** Close the underlying machine DB. Safe to call with a `null` handle. */
+export declare function closeMirrorExecution(handle: MirrorHandle | null): void;

package/dist/lib/machine-db-mirror.js

@@ -0,0 +1,82 @@
+/**
+ * Machine DB Mirror — bridges workspace.db executions to machine.db.
+ *
+ * `prlt work run` and `prlt orchestrate machine` write directly to machine.db.
+ * `prlt work start` and `prlt orchestrator start` write to workspace.db for
+ * ticket-linked state, but also need to mirror those executions to machine.db
+ * so that:
+ *
+ *   - `prlt session list` from outside an HQ sees them
+ *   - `prlt orchestrator status` from `/tmp` sees orchestrators in every HQ
+ *   - The machine-level supervision story (PRLT-1249) actually works
+ *
+ * Machine.db writes are always best-effort. workspace.db is still authoritative
+ * for ticketed work; if mirroring fails we silently swallow the error and keep
+ * the primary flow running.
+ */
+import { MachineDB } from './machine-db.js';
+/**
+ * Create a machine.db execution row mirroring a workspace.db execution.
+ *
+ * Returns a handle for later status/process-info updates, or `null` if the
+ * machine DB could not be opened or the row could not be inserted.
+ *
+ * Callers MUST pass the handle to {@link closeMirrorExecution} when done.
+ */
+export function createMirrorExecution(input) {
+    try {
+        const machineDb = new MachineDB(input.machineDbPath);
+        const execution = machineDb.createExecution({
+            prompt: input.prompt ?? `${input.ticketId} ${input.agentName}`.trim(),
+            repoPath: input.repoPath,
+            agentName: input.agentName,
+            executor: input.executor,
+            environment: input.environment,
+            branch: input.branch,
+            ticketId: input.ticketId,
+            persistent: input.persistent ?? false,
+        });
+        return { machineDb, execution };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Update a mirrored execution with new status and/or process info. All errors
+ * are swallowed: machine.db is the secondary store and must never break the
+ * primary flow.
+ */
+export function updateMirrorExecution(handle, update) {
+    if (!handle)
+        return;
+    try {
+        if (update.status) {
+            handle.machineDb.updateStatus(handle.execution.id, update.status, undefined, update.errorMessage);
+        }
+        if (update.sessionId !== undefined ||
+            update.containerId !== undefined ||
+            update.branch !== undefined) {
+            handle.machineDb.updateProcessInfo(handle.execution.id, {
+                sessionId: update.sessionId,
+                containerId: update.containerId,
+                branch: update.branch,
+            });
+        }
+    }
+    catch {
+        // Non-fatal — machine.db is secondary.
+    }
+}
+/** Close the underlying machine DB. Safe to call with a `null` handle. */
+export function closeMirrorExecution(handle) {
+    if (!handle)
+        return;
+    try {
+        handle.machineDb.close();
+    }
+    catch {
+        // ignore
+    }
+}
+//# sourceMappingURL=machine-db-mirror.js.map

package/dist/lib/machine-db-mirror.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"machine-db-mirror.js","sourceRoot":"","sources":["../../src/lib/machine-db-mirror.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,SAAS,EAAsD,MAAM,iBAAiB,CAAA;AA4B/F;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAwB;IAC5D,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,IAAI,SAAS,CAAC,KAAK,CAAC,aAAa,CAAC,CAAA;QACpD,MAAM,SAAS,GAAG,SAAS,CAAC,eAAe,CAAC;YAC1C,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE;YACrE,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,KAAK;SACtC,CAAC,CAAA;QACF,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAA;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAA2B,EAC3B,MAMC;IAED,IAAI,CAAC,MAAM;QAAE,OAAM;IACnB,IAAI,CAAC;QACH,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClB,MAAM,CAAC,SAAS,CAAC,YAAY,CAC3B,MAAM,CAAC,SAAS,CAAC,EAAE,EACnB,MAAM,CAAC,MAAM,EACb,SAAS,EACT,MAAM,CAAC,YAAY,CACpB,CAAA;QACH,CAAC;QACD,IACE,MAAM,CAAC,SAAS,KAAK,SAAS;YAC9B,MAAM,CAAC,WAAW,KAAK,SAAS;YAChC,MAAM,CAAC,MAAM,KAAK,SAAS,EAC3B,CAAC;YACD,MAAM,CAAC,SAAS,CAAC,iBAAiB,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,EAAE;gBACtD,SAAS,EAAE,MAAM,CAAC,SAAS;gBAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,MAAM,EAAE,MAAM,CAAC,MAAM;aACtB,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,uCAAuC;IACzC,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,oBAAoB,CAAC,MAA2B;IAC9D,IAAI,CAAC,MAAM;QAAE,OAAM;IACnB,IAAI,CAAC;QACH,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,CAAA;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,SAAS;IACX,CAAC;AACH,CAAC"}

package/dist/lib/machine-db.d.ts

@@ -16,6 +16,43 @@
 export type MachineExecutionStatus = 'starting' | 'running' | 'completed' | 'failed' | 'stopped';
 export type MachineLifecycleState = 'healthy' | 'idle' | 'died' | 'completed';
 export type MachineCleanupPolicy = 'on-exit' | 'persistent' | 'on-error-keep';
+/**
+ * A registered messaging channel (Telegram, Slack, Discord, ...).
+ * `configJson` is an adapter-specific blob stored as text.
+ */
+export interface MessagingChannelRow {
+    name: string;
+    type: string;
+    config_json: string;
+    active: number;
+    last_message_at: number | null;
+}
+export interface MessagingChannelRecord {
+    name: string;
+    type: string;
+    configJson: string;
+    active: boolean;
+    lastMessageAt: Date | undefined;
+}
+/**
+ * A persistent binding of `(channel, userId)` to an agent session.
+ * The router looks this up on every inbound message so a given user
+ * always lands on the same agent.
+ */
+export interface MessagingRouteRow {
+    channel: string;
+    user_id: string;
+    agent_session_id: string;
+    created_at: number;
+    last_used_at: number | null;
+}
+export interface MessagingRouteRecord {
+    channel: string;
+    userId: string;
+    agentSessionId: string;
+    createdAt: Date;
+    lastUsedAt: Date | undefined;
+}
 export interface MachineExecution {
     id: string;
     prompt: string;
@@ -100,6 +137,17 @@ export declare class MachineDB {
      * Get all active (starting/running) executions.
      */
     getActiveExecutions(): MachineExecution[];
+    /**
+     * Get all active executions where the agent name starts with the given
+     * prefix. Used by `prlt orchestrator status/attach/stop` to find all
+     * orchestrator executions (`orchestrator-{name}`) machine-wide.
+     */
+    getActiveByAgentPrefix(prefix: string): MachineExecution[];
+    /**
+     * Find an execution by session ID (unique across the machine).
+     * Returns the most recently started match, or null.
+     */
+    findBySessionId(sessionId: string): MachineExecution | null;
     /**
      * Delete an execution record.
      */
@@ -140,5 +188,55 @@ export declare class MachineDB {
      * Get executions with stale heartbeats (older than timeoutMinutes).
      */
     getStaleExecutions(timeoutMinutes: number): MachineExecution[];
+    /**
+     * Insert or replace a registered messaging channel.
+     *
+     * Channels are keyed by `name` (e.g. "telegram"). Re-registering the
+     * same channel updates its config and marks it active — this is what
+     * `prlt gateway connect` does on repeat calls.
+     */
+    upsertMessagingChannel(params: {
+        name: string;
+        type: string;
+        configJson: string;
+        active?: boolean;
+    }): void;
+    /** Look up a single channel by name. */
+    getMessagingChannel(name: string): MessagingChannelRecord | null;
+    /**
+     * List channels. When `onlyActive` is true (the default), only channels
+     * with `active = 1` are returned — this is what the gateway daemon
+     * uses at startup.
+     */
+    listMessagingChannels(options?: {
+        onlyActive?: boolean;
+    }): MessagingChannelRecord[];
+    /** Mark a channel inactive (keeps config around for re-enable). */
+    setMessagingChannelActive(name: string, active: boolean): void;
+    /** Remove a channel's registration entirely. */
+    deleteMessagingChannel(name: string): void;
+    /**
+     * Stamp a channel's `last_message_at` to now — called each time the
+     * router successfully routes an inbound message. Used by
+     * `prlt gateway status` to show channel activity.
+     */
+    touchMessagingChannel(name: string, timestamp?: number): void;
+    /** Look up an existing route, or null if this user has never been seen. */
+    getMessagingRoute(channel: string, userId: string): MessagingRouteRecord | null;
+    /**
+     * Bind a `(channel, user)` pair to an agent session. Idempotent — if a
+     * binding already exists it is updated to point at the new agent.
+     */
+    upsertMessagingRoute(params: {
+        channel: string;
+        userId: string;
+        agentSessionId: string;
+    }): MessagingRouteRecord;
+    /** Stamp `last_used_at` to now — called every time a route is used. */
+    touchMessagingRoute(channel: string, userId: string, timestamp?: number): void;
+    /** List routes for a channel (or all channels when `channel` omitted). */
+    listMessagingRoutes(channel?: string): MessagingRouteRecord[];
+    /** Count messages handled by a channel since `since` (for status output). */
+    countMessagingRoutesForChannel(channel: string): number;
     close(): void;
 }

package/dist/lib/machine-db.js

@@ -102,6 +102,28 @@ export class MachineDB {
         lifecycle_state TEXT NOT NULL DEFAULT 'healthy',
         retries INTEGER NOT NULL DEFAULT 0
       );
+
+      -- Messaging gateway (PRLT-1255) — bridges external messaging platforms
+      -- (Telegram, Slack, ...) to agent sessions via prlt session poke.
+      CREATE TABLE IF NOT EXISTS messaging_channels (
+        name TEXT PRIMARY KEY,
+        type TEXT NOT NULL,
+        config_json TEXT NOT NULL,
+        active INTEGER NOT NULL DEFAULT 1,
+        last_message_at INTEGER
+      );
+
+      CREATE TABLE IF NOT EXISTS messaging_routes (
+        channel TEXT NOT NULL,
+        user_id TEXT NOT NULL,
+        agent_session_id TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        last_used_at INTEGER,
+        PRIMARY KEY (channel, user_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_messaging_routes_agent
+        ON messaging_routes(agent_session_id);
     `);
         // Migrate existing databases that don't have the persistent columns
         this.addColumnIfMissing('executions', 'persistent', 'INTEGER NOT NULL DEFAULT 0');
@@ -227,6 +249,23 @@ export class MachineDB {
         const rows = this.db.prepare("SELECT * FROM executions WHERE status IN ('starting', 'running') ORDER BY started_at DESC").all();
         return rows.map(rowToExecution);
     }
+    /**
+     * Get all active executions where the agent name starts with the given
+     * prefix. Used by `prlt orchestrator status/attach/stop` to find all
+     * orchestrator executions (`orchestrator-{name}`) machine-wide.
+     */
+    getActiveByAgentPrefix(prefix) {
+        const rows = this.db.prepare("SELECT * FROM executions WHERE status IN ('starting', 'running') AND agent_name LIKE ? ORDER BY started_at DESC").all(`${prefix}%`);
+        return rows.map(rowToExecution);
+    }
+    /**
+     * Find an execution by session ID (unique across the machine).
+     * Returns the most recently started match, or null.
+     */
+    findBySessionId(sessionId) {
+        const row = this.db.prepare('SELECT * FROM executions WHERE session_id = ? ORDER BY started_at DESC LIMIT 1').get(sessionId);
+        return row ? rowToExecution(row) : null;
+    }
     /**
      * Delete an execution record.
      */
@@ -331,8 +370,121 @@ export class MachineDB {
     `).all(cutoff, Date.now() - timeoutMinutes * 60 * 1000);
         return rows.map(rowToExecution);
     }
+    // ===========================================================================
+    // Messaging gateway (PRLT-1255)
+    // ===========================================================================
+    /**
+     * Insert or replace a registered messaging channel.
+     *
+     * Channels are keyed by `name` (e.g. "telegram"). Re-registering the
+     * same channel updates its config and marks it active — this is what
+     * `prlt gateway connect` does on repeat calls.
+     */
+    upsertMessagingChannel(params) {
+        const active = params.active === false ? 0 : 1;
+        this.db.prepare(`
+      INSERT INTO messaging_channels (name, type, config_json, active, last_message_at)
+      VALUES (?, ?, ?, ?, NULL)
+      ON CONFLICT(name) DO UPDATE SET
+        type = excluded.type,
+        config_json = excluded.config_json,
+        active = excluded.active
+    `).run(params.name, params.type, params.configJson, active);
+    }
+    /** Look up a single channel by name. */
+    getMessagingChannel(name) {
+        const row = this.db.prepare('SELECT * FROM messaging_channels WHERE name = ?').get(name);
+        return row ? messagingChannelRowToRecord(row) : null;
+    }
+    /**
+     * List channels. When `onlyActive` is true (the default), only channels
+     * with `active = 1` are returned — this is what the gateway daemon
+     * uses at startup.
+     */
+    listMessagingChannels(options) {
+        const onlyActive = options?.onlyActive !== false;
+        const rows = onlyActive
+            ? this.db.prepare('SELECT * FROM messaging_channels WHERE active = 1 ORDER BY name ASC').all()
+            : this.db.prepare('SELECT * FROM messaging_channels ORDER BY name ASC').all();
+        return rows.map(messagingChannelRowToRecord);
+    }
+    /** Mark a channel inactive (keeps config around for re-enable). */
+    setMessagingChannelActive(name, active) {
+        this.db.prepare('UPDATE messaging_channels SET active = ? WHERE name = ?').run(active ? 1 : 0, name);
+    }
+    /** Remove a channel's registration entirely. */
+    deleteMessagingChannel(name) {
+        this.db.prepare('DELETE FROM messaging_channels WHERE name = ?').run(name);
+    }
+    /**
+     * Stamp a channel's `last_message_at` to now — called each time the
+     * router successfully routes an inbound message. Used by
+     * `prlt gateway status` to show channel activity.
+     */
+    touchMessagingChannel(name, timestamp = Date.now()) {
+        this.db.prepare('UPDATE messaging_channels SET last_message_at = ? WHERE name = ?').run(timestamp, name);
+    }
+    // ---------------------------------------------------------------------------
+    // Routes — (channel, user) → agent session
+    // ---------------------------------------------------------------------------
+    /** Look up an existing route, or null if this user has never been seen. */
+    getMessagingRoute(channel, userId) {
+        const row = this.db.prepare('SELECT * FROM messaging_routes WHERE channel = ? AND user_id = ?').get(channel, userId);
+        return row ? messagingRouteRowToRecord(row) : null;
+    }
+    /**
+     * Bind a `(channel, user)` pair to an agent session. Idempotent — if a
+     * binding already exists it is updated to point at the new agent.
+     */
+    upsertMessagingRoute(params) {
+        const now = Date.now();
+        this.db.prepare(`
+      INSERT INTO messaging_routes (channel, user_id, agent_session_id, created_at, last_used_at)
+      VALUES (?, ?, ?, ?, NULL)
+      ON CONFLICT(channel, user_id) DO UPDATE SET
+        agent_session_id = excluded.agent_session_id
+    `).run(params.channel, params.userId, params.agentSessionId, now);
+        return this.getMessagingRoute(params.channel, params.userId);
+    }
+    /** Stamp `last_used_at` to now — called every time a route is used. */
+    touchMessagingRoute(channel, userId, timestamp = Date.now()) {
+        this.db.prepare('UPDATE messaging_routes SET last_used_at = ? WHERE channel = ? AND user_id = ?').run(timestamp, channel, userId);
+    }
+    /** List routes for a channel (or all channels when `channel` omitted). */
+    listMessagingRoutes(channel) {
+        const rows = channel
+            ? this.db.prepare('SELECT * FROM messaging_routes WHERE channel = ? ORDER BY created_at DESC').all(channel)
+            : this.db.prepare('SELECT * FROM messaging_routes ORDER BY created_at DESC').all();
+        return rows.map(messagingRouteRowToRecord);
+    }
+    /** Count messages handled by a channel since `since` (for status output). */
+    countMessagingRoutesForChannel(channel) {
+        const row = this.db.prepare('SELECT COUNT(*) AS n FROM messaging_routes WHERE channel = ?').get(channel);
+        return row?.n ?? 0;
+    }
     close() {
         this.db.close();
     }
 }
+// =============================================================================
+// Row → record converters for messaging tables
+// =============================================================================
+function messagingChannelRowToRecord(row) {
+    return {
+        name: row.name,
+        type: row.type,
+        configJson: row.config_json,
+        active: row.active === 1,
+        lastMessageAt: row.last_message_at ? new Date(row.last_message_at) : undefined,
+    };
+}
+function messagingRouteRowToRecord(row) {
+    return {
+        channel: row.channel,
+        userId: row.user_id,
+        agentSessionId: row.agent_session_id,
+        createdAt: new Date(row.created_at),
+        lastUsedAt: row.last_used_at ? new Date(row.last_used_at) : undefined,
+    };
+}
 //# sourceMappingURL=machine-db.js.map