codex-channel-bgos 0.2.0

package/dist/outbound.d.ts

@@ -0,0 +1,223 @@
+import type { BgosApi } from "./bgos-api.js";
+import type { ApprovalMeta, FromAgentInput, MessageOption } from "./types.js";
+export declare class BgosOutbound {
+    /** Public read-only handle on the underlying REST client; consumers
+     *  occasionally need it (e.g. inbound-handler routes uploadFile through
+     *  publishMediaPath). */
+    readonly api: BgosApi;
+    private typingEmitter;
+    private onLastError;
+    private onOutbound;
+    /** Single-flight guard for replaySpool: concurrent callers (the 60s spool
+     *  timer, onReconnect, recover) await the same in-flight run instead of each
+     *  loading + re-sending the same spooled entries (double-send). */
+    private spoolInFlight;
+    private sleepFn;
+    constructor(api: BgosApi);
+    /** Wire the WS typing emitter (contract C4). Without it, sendTyping no-ops. */
+    setTypingEmitter(fn: (p: {
+        chatId: number;
+        assistantId: number;
+    }) => void): void;
+    /** Report an outbound failure to the heartbeat lastError channel. */
+    setLastErrorReporter(fn: (code: string, message: string) => void): void;
+    /** Called on every successful send (drives heartbeat lastOutboundAt). */
+    setOutboundReporter(fn: () => void): void;
+    /** Test seam: override the retry sleep so specs don't wait real seconds. */
+    setSleepFn(fn: (ms: number) => Promise<void>): void;
+    private rawSend;
+    /**
+     * Pick the reply endpoint + apply the outbound retry policy (contract C3).
+     *
+     * Default `messages` (POST /api/v1/messages) is the historical path used for
+     * every normal reply, proactive send, and `/board` fan-out. `send-message`
+     * (POST /api/v1/send-message) is used ONLY for a2a peer replies.
+     *
+     * Retry (backoff 1s/5s/25s) applies ONLY to the provably-undelivered
+     * network-error class + 429 (see classifyOutboundError), because the backend
+     * insert is not idempotent. Ambiguous failures (timeouts, 5xx) are NOT
+     * retried and reject to the caller. After 3 failed retries of the safe class
+     * the payload is spooled to the outbox for later replay.
+     */
+    private deliver;
+    /**
+     * Replay any spooled outbound payloads (contract C3). Called by the adapter
+     * on WS reconnect and every 60s while non-empty. Entries older than 24h are
+     * dropped on load; safe-class failures are re-kept, ambiguous failures on
+     * replay are dropped to avoid a non-idempotent duplicate.
+     *
+     * Single-flight: concurrent callers (the 60s spool timer racing an
+     * onReconnect racing a recover, or WS flapping spawning overlapping
+     * onReconnects) coalesce onto one in-flight run. Two overlapping runs would
+     * otherwise both load the SAME entries and each re-send them, and the backend
+     * insert is NOT idempotent, so that produces duplicate agent messages.
+     */
+    replaySpool(): Promise<void>;
+    private runReplaySpool;
+    sendText(params: {
+        assistantId: number;
+        chatId: number;
+        text: string;
+        fromAgent?: FromAgentInput;
+        /** Anchor this reply to an earlier message - BGOS renders a slim
+         *  Telegram-style quoted header inside the bubble (tap → jump to
+         *  source) and persists a frozen text/sender snapshot. Use when
+         *  answering a stale question, following up on a past commitment,
+         *  or surfacing a cron-triggered nudge tied to an older message.
+         *  Same-chat constraint enforced server-side (400 otherwise). See
+         *  bgos-agent-capabilities.md §9. */
+        replyToId?: number;
+        /** Route via `/send-message` instead of `/messages`. Set only for a2a
+         *  peer replies so the backend's peer-reply bridge resolves the
+         *  initiator's `wait_for_reply`. Defaults to `/messages` (unchanged). */
+        replyVia?: "messages" | "send-message";
+    }): Promise<{
+        id: number;
+    }>;
+    /**
+     * Send a text message stamped with an inline-agent identity.
+     *
+     * Each call produces a distinct bubble in the BGOS UI labeled with the
+     * supplied name / color / avatar - used by Codex's `/board` so the
+     * Research, Finance, Strategy, etc. agents each render as their own
+     * sender even though they share one bound assistant.
+     *
+     * The backend's hybrid resolver tries `peerId` (registry id) →
+     * `assistantId` (cross-assistant peer) → `externalId` (string lookup),
+     * falling back to inline `{name,color,avatarUrl}` when no peer is found.
+     * For Codex, pass `name` + `color` (and optionally `avatarUrl`) - the
+     * inline path is what we need.
+     */
+    sendAsAgent(params: {
+        assistantId: number;
+        chatId: number;
+        text: string;
+        agent: FromAgentInput;
+        options?: MessageOption[];
+    }): Promise<{
+        id: number;
+    }>;
+    sendButtons(params: {
+        assistantId: number;
+        chatId: number;
+        text: string;
+        options: MessageOption[];
+        /** See sendText.replyToId. */
+        replyToId?: number;
+        /** See sendText.replyVia. */
+        replyVia?: "messages" | "send-message";
+    }): Promise<{
+        id: number;
+    }>;
+    /**
+     * Render an approval request bubble.
+     *
+     * Callback layout: `ea:<decision>:<reqId>` matching Telegram parity
+     * (Hermes uses the same prefix). Decisions: `once|session|always|deny`.
+     *
+     * Default options cover the standard 4-button bubble. Pass `options`
+     * explicitly to override (e.g. for a smaller agreement flow).
+     */
+    sendApprovalRequest(params: {
+        assistantId: number;
+        chatId: number;
+        text: string;
+        meta: ApprovalMeta;
+        options?: MessageOption[];
+        /** See sendText.replyToId - anchor an approval bubble to the user's
+         *  earlier request the agent is now asking permission to act on. */
+        replyToId?: number;
+        /** See sendText.replyVia. */
+        replyVia?: "messages" | "send-message";
+    }): Promise<{
+        id: number;
+    }>;
+    /**
+     * Send an `ask_user_input` prompt.
+     *
+     * `modal=true` (BGOS default for `ask_user_input`) renders as a
+     * pop-over sheet. `modal=false` renders as inline buttons that don't
+     * intrude. Use modal only when the user just messaged (~2 min) - see
+     * agent hints + the canonical capability doc.
+     *
+     * Today the backend's `messageType: 'ask_user_input'` carries `options`
+     * directly. If the canonical capability doc later splits askId/askOrder
+     * out, this method gains those args - for now we keep the surface
+     * minimal.
+     */
+    sendAskUserInput(params: {
+        assistantId: number;
+        chatId: number;
+        prompt: string;
+        options?: MessageOption[];
+        modal?: boolean;
+    }): Promise<{
+        id: number;
+    }>;
+    /** Send a file (image, video, document, audio) via the attachment-bridge. */
+    sendFile(params: {
+        assistantId: number;
+        chatId: number;
+        filePath: string;
+        caption?: string;
+        fileName?: string;
+        mimeType?: string;
+        /** See sendText.replyToId. */
+        replyToId?: number;
+        /** See sendText.replyVia. */
+        replyVia?: "messages" | "send-message";
+    }): Promise<{
+        id: number;
+    }>;
+    /** Image - enforces image/* MIME if provided; otherwise lets MIME
+     *  inference handle it. */
+    sendImage(params: {
+        assistantId: number;
+        chatId: number;
+        filePath: string;
+        caption?: string;
+        fileName?: string;
+        mimeType?: string;
+        /** See sendText.replyToId. */
+        replyToId?: number;
+        /** See sendText.replyVia. */
+        replyVia?: "messages" | "send-message";
+    }): Promise<{
+        id: number;
+    }>;
+    /** Video - enforces video/* MIME if provided. */
+    sendVideo(params: {
+        assistantId: number;
+        chatId: number;
+        filePath: string;
+        caption?: string;
+        fileName?: string;
+        mimeType?: string;
+        /** See sendText.replyToId. */
+        replyToId?: number;
+        /** See sendText.replyVia. */
+        replyVia?: "messages" | "send-message";
+    }): Promise<{
+        id: number;
+    }>;
+    sendAgentError(params: {
+        assistantId: number;
+        chatId: number;
+        reason: string;
+    }): Promise<{
+        id: number;
+    }>;
+    /**
+     * Send a "typing..." indicator (contract C4). Emits the client-side WS
+     * `typing` event via the wired emitter (throttled 1/3s per chat inside
+     * BgosWs). Best-effort: no emitter wired (or an emit failure) resolves
+     * silently so a reply path is never broken over a typing indicator.
+     */
+    sendTyping(params: {
+        assistantId: number;
+        chatId: number;
+    }): Promise<void>;
+}
+/** Backwards-compatible alias retained for the public API surface. */
+export { BgosOutbound as BGOSOutbound };
+//# sourceMappingURL=outbound.d.ts.map

package/dist/outbound.d.ts.map

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

package/dist/outbound.js

@@ -0,0 +1,366 @@
+import { publishMediaPath } from "./attachment-bridge.js";
+import { sanitizeFromAgent } from "./agent-identity.js";
+import { classifyOutboundError, OUTBOUND_BACKOFFS_MS, } from "./outbound-retry.js";
+import { appendOutbox, loadOutbox, rewriteOutbox, } from "./outbox.js";
+/**
+ * High-level outbound adapter for the Codex channel.
+ *
+ * Wraps `BgosApi.postMessage` with the modality-specific helpers
+ * `BGOSAdapter` + the fork's reply-handle expose:
+ *   - `sendText`              plain assistant reply
+ *   - `sendButtons`           text + ≤6 inline option chips
+ *   - `sendApprovalRequest`   approval bubble (`ea:<decision>:<reqId>`)
+ *   - `sendAskUserInput`      blocking pop-under (modal or inline)
+ *   - `sendFile/Image/Video`  attach a local file via attachment-bridge
+ *   - `sendAgentError`        styled error bubble used on dispatch failure
+ *   - `sendTyping`            best-effort indicator (no-op on backend today)
+ *
+ * Validation is light - the backend does the authoritative checks. We
+ * enforce limits client-side only when the failure mode is silent (e.g.
+ * options>6 truncates, not 400; message-type mismatches sometimes
+ * succeed but render wrong). Limits we enforce:
+ *   - inline buttons: max 6 options (matches PR #62 backend limit + the
+ *     `inline_buttons_shipped` memory).
+ *
+ * `BgosOutbound` is the canonical export used everywhere; `BGOSOutbound`
+ * is kept as an alias for the brief moment in PR #82 where the scaffold
+ * named it that way (so existing imports don't break).
+ */
+/** Backend rejects inline messages with >6 options. */
+const INLINE_OPTION_LIMIT = 6;
+export class BgosOutbound {
+    /** Public read-only handle on the underlying REST client; consumers
+     *  occasionally need it (e.g. inbound-handler routes uploadFile through
+     *  publishMediaPath). */
+    api;
+    typingEmitter = null;
+    onLastError = null;
+    onOutbound = null;
+    /** Single-flight guard for replaySpool: concurrent callers (the 60s spool
+     *  timer, onReconnect, recover) await the same in-flight run instead of each
+     *  loading + re-sending the same spooled entries (double-send). */
+    spoolInFlight = null;
+    sleepFn = (ms) => new Promise((r) => setTimeout(r, ms));
+    constructor(api) {
+        this.api = api;
+    }
+    /** Wire the WS typing emitter (contract C4). Without it, sendTyping no-ops. */
+    setTypingEmitter(fn) {
+        this.typingEmitter = fn;
+    }
+    /** Report an outbound failure to the heartbeat lastError channel. */
+    setLastErrorReporter(fn) {
+        this.onLastError = fn;
+    }
+    /** Called on every successful send (drives heartbeat lastOutboundAt). */
+    setOutboundReporter(fn) {
+        this.onOutbound = fn;
+    }
+    /** Test seam: override the retry sleep so specs don't wait real seconds. */
+    setSleepFn(fn) {
+        this.sleepFn = fn;
+    }
+    rawSend(payload, replyVia) {
+        return replyVia === "send-message"
+            ? this.api.sendMessage(payload)
+            : this.api.postMessage(payload);
+    }
+    /**
+     * Pick the reply endpoint + apply the outbound retry policy (contract C3).
+     *
+     * Default `messages` (POST /api/v1/messages) is the historical path used for
+     * every normal reply, proactive send, and `/board` fan-out. `send-message`
+     * (POST /api/v1/send-message) is used ONLY for a2a peer replies.
+     *
+     * Retry (backoff 1s/5s/25s) applies ONLY to the provably-undelivered
+     * network-error class + 429 (see classifyOutboundError), because the backend
+     * insert is not idempotent. Ambiguous failures (timeouts, 5xx) are NOT
+     * retried and reject to the caller. After 3 failed retries of the safe class
+     * the payload is spooled to the outbox for later replay.
+     */
+    async deliver(payload, replyVia) {
+        let attempt = 0;
+        for (;;) {
+            try {
+                const r = await this.rawSend(payload, replyVia);
+                this.onOutbound?.();
+                return r;
+            }
+            catch (err) {
+                const cls = classifyOutboundError(err);
+                if (cls.retriable && attempt < OUTBOUND_BACKOFFS_MS.length) {
+                    const wait = cls.retryAfterMs ?? OUTBOUND_BACKOFFS_MS[attempt];
+                    attempt += 1;
+                    await this.sleepFn(wait);
+                    continue;
+                }
+                const message = err instanceof Error ? err.message : String(err);
+                if (cls.retriable) {
+                    // Exhausted the safe class: spool for later replay.
+                    appendOutbox({
+                        ts: Date.now(),
+                        payload,
+                        ...(replyVia ? { replyVia } : {}),
+                    });
+                }
+                this.onLastError?.("outbound_failed", message);
+                throw err;
+            }
+        }
+    }
+    /**
+     * Replay any spooled outbound payloads (contract C3). Called by the adapter
+     * on WS reconnect and every 60s while non-empty. Entries older than 24h are
+     * dropped on load; safe-class failures are re-kept, ambiguous failures on
+     * replay are dropped to avoid a non-idempotent duplicate.
+     *
+     * Single-flight: concurrent callers (the 60s spool timer racing an
+     * onReconnect racing a recover, or WS flapping spawning overlapping
+     * onReconnects) coalesce onto one in-flight run. Two overlapping runs would
+     * otherwise both load the SAME entries and each re-send them, and the backend
+     * insert is NOT idempotent, so that produces duplicate agent messages.
+     */
+    replaySpool() {
+        if (this.spoolInFlight)
+            return this.spoolInFlight;
+        this.spoolInFlight = this.runReplaySpool().finally(() => {
+            this.spoolInFlight = null;
+        });
+        return this.spoolInFlight;
+    }
+    async runReplaySpool() {
+        const entries = loadOutbox();
+        if (entries.length === 0)
+            return;
+        // Claim the entries by clearing the spool up-front (atomic tmp + rename).
+        // At-most-once for the non-idempotent insert: a crash mid-replay cannot
+        // double-send on restart, and a concurrent send failure re-spools below.
+        // Failed safe-class entries are re-APPENDED (not rewritten) so a
+        // concurrent deliver() spool during replay is preserved.
+        rewriteOutbox([]);
+        for (const entry of entries) {
+            try {
+                await this.rawSend(entry.payload, entry.replyVia);
+                this.onOutbound?.();
+            }
+            catch (err) {
+                const cls = classifyOutboundError(err);
+                if (cls.retriable)
+                    appendOutbox(entry);
+                // Ambiguous replay failures are dropped: the write may have applied.
+            }
+        }
+    }
+    // -------------------------------------------------------------------
+    // Text + buttons
+    // -------------------------------------------------------------------
+    sendText(params) {
+        const fromAgent = sanitizeFromAgent(params.fromAgent);
+        const payload = {
+            assistantId: params.assistantId,
+            chatId: params.chatId,
+            sender: "assistant",
+            text: params.text,
+            messageType: "standard",
+            ...(fromAgent ? { fromAgent } : {}),
+            ...(params.replyToId !== undefined && { replyToId: params.replyToId }),
+        };
+        return this.deliver(payload, params.replyVia);
+    }
+    /**
+     * Send a text message stamped with an inline-agent identity.
+     *
+     * Each call produces a distinct bubble in the BGOS UI labeled with the
+     * supplied name / color / avatar - used by Codex's `/board` so the
+     * Research, Finance, Strategy, etc. agents each render as their own
+     * sender even though they share one bound assistant.
+     *
+     * The backend's hybrid resolver tries `peerId` (registry id) →
+     * `assistantId` (cross-assistant peer) → `externalId` (string lookup),
+     * falling back to inline `{name,color,avatarUrl}` when no peer is found.
+     * For Codex, pass `name` + `color` (and optionally `avatarUrl`) - the
+     * inline path is what we need.
+     */
+    sendAsAgent(params) {
+        if (params.options !== undefined &&
+            params.options.length > INLINE_OPTION_LIMIT) {
+            throw new Error(`sendAsAgent: ${params.options.length} options exceeds inline limit (${INLINE_OPTION_LIMIT})`);
+        }
+        const fromAgent = sanitizeFromAgent(params.agent);
+        const payload = {
+            assistantId: params.assistantId,
+            chatId: params.chatId,
+            sender: "assistant",
+            text: params.text,
+            messageType: "standard",
+            ...(fromAgent ? { fromAgent } : {}),
+            ...(params.options ? { options: params.options } : {}),
+        };
+        return this.api.postMessage(payload);
+    }
+    sendButtons(params) {
+        if (params.options.length > INLINE_OPTION_LIMIT) {
+            // Throw rather than truncate - the agent should be told it sent
+            // too many options so it can re-emit. (Hermes truncates with a
+            // warning because the agent gets the buttons via a regex in its
+            // text; we have a typed call here so the contract is firmer.)
+            throw new Error(`sendButtons: ${params.options.length} options exceeds inline limit (${INLINE_OPTION_LIMIT})`);
+        }
+        const payload = {
+            assistantId: params.assistantId,
+            chatId: params.chatId,
+            sender: "assistant",
+            text: params.text,
+            options: params.options,
+            messageType: "standard",
+            ...(params.replyToId !== undefined && { replyToId: params.replyToId }),
+        };
+        return this.deliver(payload, params.replyVia);
+    }
+    // -------------------------------------------------------------------
+    // Approval bubbles
+    // -------------------------------------------------------------------
+    /**
+     * Render an approval request bubble.
+     *
+     * Callback layout: `ea:<decision>:<reqId>` matching Telegram parity
+     * (Hermes uses the same prefix). Decisions: `once|session|always|deny`.
+     *
+     * Default options cover the standard 4-button bubble. Pass `options`
+     * explicitly to override (e.g. for a smaller agreement flow).
+     */
+    sendApprovalRequest(params) {
+        const reqId = params.meta.request_id;
+        const defaults = [
+            {
+                text: "Allow once",
+                callbackData: `ea:once:${reqId}`,
+                style: "success",
+            },
+            {
+                text: "Allow for session",
+                callbackData: `ea:session:${reqId}`,
+                style: "success",
+            },
+            {
+                text: "Always allow",
+                callbackData: `ea:always:${reqId}`,
+                style: "default",
+            },
+            { text: "Deny", callbackData: `ea:deny:${reqId}`, style: "danger" },
+        ];
+        const payload = {
+            assistantId: params.assistantId,
+            chatId: params.chatId,
+            sender: "assistant",
+            text: params.text,
+            options: params.options ?? defaults,
+            messageType: "approval_request",
+            approvalMeta: params.meta,
+            ...(params.replyToId !== undefined && { replyToId: params.replyToId }),
+        };
+        return this.deliver(payload, params.replyVia);
+    }
+    // -------------------------------------------------------------------
+    // ask_user_input pop-under (modal or inline)
+    // -------------------------------------------------------------------
+    /**
+     * Send an `ask_user_input` prompt.
+     *
+     * `modal=true` (BGOS default for `ask_user_input`) renders as a
+     * pop-over sheet. `modal=false` renders as inline buttons that don't
+     * intrude. Use modal only when the user just messaged (~2 min) - see
+     * agent hints + the canonical capability doc.
+     *
+     * Today the backend's `messageType: 'ask_user_input'` carries `options`
+     * directly. If the canonical capability doc later splits askId/askOrder
+     * out, this method gains those args - for now we keep the surface
+     * minimal.
+     */
+    sendAskUserInput(params) {
+        if (params.options &&
+            params.options.length > INLINE_OPTION_LIMIT &&
+            params.modal === false) {
+            throw new Error(`sendAskUserInput (inline): ${params.options.length} options exceeds inline limit (${INLINE_OPTION_LIMIT})`);
+        }
+        const payload = {
+            assistantId: params.assistantId,
+            chatId: params.chatId,
+            sender: "assistant",
+            text: params.prompt,
+            // The backend's messageType union doesn't include "ask_user_input"
+            // in the OutboundMessagePayload type today - but the wire format
+            // accepts it (the canonical capability doc documents it). Cast to
+            // sidestep the union, mirroring how Hermes handles this.
+            messageType: "ask_user_input",
+            options: params.options,
+        };
+        return this.api.postMessage(payload);
+    }
+    // -------------------------------------------------------------------
+    // Files / media
+    // -------------------------------------------------------------------
+    /** Send a file (image, video, document, audio) via the attachment-bridge. */
+    async sendFile(params) {
+        const fileRef = await publishMediaPath(this.api, params.filePath, {
+            fileName: params.fileName,
+            mimeType: params.mimeType,
+        });
+        const payload = {
+            assistantId: params.assistantId,
+            chatId: params.chatId,
+            sender: "assistant",
+            text: params.caption ?? "",
+            messageType: "standard",
+            files: [fileRef],
+            ...(params.replyToId !== undefined && { replyToId: params.replyToId }),
+        };
+        return this.deliver(payload, params.replyVia);
+    }
+    /** Image - enforces image/* MIME if provided; otherwise lets MIME
+     *  inference handle it. */
+    sendImage(params) {
+        if (params.mimeType && !params.mimeType.startsWith("image/")) {
+            throw new Error(`sendImage: mimeType ${params.mimeType} is not image/*`);
+        }
+        return this.sendFile(params);
+    }
+    /** Video - enforces video/* MIME if provided. */
+    sendVideo(params) {
+        if (params.mimeType && !params.mimeType.startsWith("video/")) {
+            throw new Error(`sendVideo: mimeType ${params.mimeType} is not video/*`);
+        }
+        return this.sendFile(params);
+    }
+    // -------------------------------------------------------------------
+    // Errors + typing
+    // -------------------------------------------------------------------
+    sendAgentError(params) {
+        const payload = {
+            assistantId: params.assistantId,
+            chatId: params.chatId,
+            sender: "assistant",
+            text: `⚠ Agent error: ${params.reason}`,
+            messageType: "agent_error",
+        };
+        return this.api.postMessage(payload);
+    }
+    /**
+     * Send a "typing..." indicator (contract C4). Emits the client-side WS
+     * `typing` event via the wired emitter (throttled 1/3s per chat inside
+     * BgosWs). Best-effort: no emitter wired (or an emit failure) resolves
+     * silently so a reply path is never broken over a typing indicator.
+     */
+    async sendTyping(params) {
+        try {
+            this.typingEmitter?.(params);
+        }
+        catch {
+            /* best-effort */
+        }
+        return;
+    }
+}
+/** Backwards-compatible alias retained for the public API surface. */
+export { BgosOutbound as BGOSOutbound };
+//# sourceMappingURL=outbound.js.map

package/dist/outbound.js.map

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

package/dist/outbox.d.ts

@@ -0,0 +1,16 @@
+import type { OutboundMessagePayload } from "./types.js";
+export interface OutboxEntry {
+    /** Epoch ms when the entry was spooled. */
+    ts: number;
+    payload: OutboundMessagePayload;
+    replyVia?: "messages" | "send-message";
+}
+/** Read the spool, dropping entries older than 24h. Never throws. */
+export declare function loadOutbox(): OutboxEntry[];
+/** Append one entry, then compact to the newest MAX_ENTRIES. Never throws. */
+export declare function appendOutbox(entry: OutboxEntry): void;
+/** Atomically replace the spool with `entries` (tmp + rename). Never throws. */
+export declare function rewriteOutbox(entries: OutboxEntry[]): void;
+/** Empty the spool. Never throws. */
+export declare function clearOutbox(): void;
+//# sourceMappingURL=outbox.d.ts.map

package/dist/outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../src/outbox.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,sBAAsB,CAAC;IAChC,QAAQ,CAAC,EAAE,UAAU,GAAG,cAAc,CAAC;CACxC;AAUD,qEAAqE;AACrE,wBAAgB,UAAU,IAAI,WAAW,EAAE,CA2B1C;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAarD;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI,CAW1D;AAED,qCAAqC;AACrC,wBAAgB,WAAW,IAAI,IAAI,CAElC"}