opensquid 0.5.395

package/dist/channels/adapters/telegram.js

@@ -0,0 +1,400 @@
+/**
+ * telegram:// adapter — outbound Bot API delivery via grammy.
+ *
+ * URI scheme: `telegram://<chat_id>[/<topic_id>]`
+ *   - `chat_id` may be negative (supergroups + channels are negative).
+ *   - Optional `topic_id` maps to grammy's `message_thread_id` (forum
+ *     topics in supergroups).
+ *
+ * Allowlist: enforced at `send()`. A chat_id not in
+ * `opts.allowlistChatIds` rejects with `{ ok: false, error: 'chat not
+ * in allowlist' }` BEFORE any API call — no leak of policy decision to
+ * the chat itself.
+ *
+ * Inbound (long-polling) is opt-in via `start()`. The 409 Conflict path
+ * is the documented degradation when another consumer holds the token
+ * (e.g. a parallel Claude Code plugin:telegram bot): we back off
+ * exponentially up to 5 attempts and otherwise stay outbound-only.
+ *
+ * Critical async-pattern note: grammy's `bot.start()` returns a promise
+ * that resolves ONLY on shutdown (when `bot.stop()` is called) — it
+ * does NOT resolve on successful start. Awaiting it deadlocks the
+ * caller forever. We deliberately do not await it; we only attach a
+ * `.catch()` to handle the 409 retry path. The legacy adapter at
+ * `src.legacy/chat/adapters/telegram.ts` documents the same gotcha.
+ *
+ * Outbound-only mode: when `opts.outboundOnly === true` OR every 409
+ * retry has been exhausted, `send()` continues to work (it uses
+ * `bot.api.sendMessage` over HTTPS, which is independent of the
+ * long-poll). `start()` becomes a no-op in this state.
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Bot, GrammyError, HttpError, InputFile } from 'grammy';
+import { inboundMediaDir } from '../../runtime/paths.js';
+/** Maximum 409 retry attempts before falling back to outbound-only. */
+const MAX_409_RETRIES = 5;
+/** Cap for exponential backoff between 409 retries. */
+const RETRY_BACKOFF_CAP_MS = 30_000;
+/**
+ * Parse `telegram://<chat_id>[/<topic_id>]` into its parts. Returns
+ * `null` when the URI is malformed.
+ */
+function parseUri(uri) {
+    const match = /^telegram:\/\/(-?\d+)(?:\/(\d+))?$/.exec(uri);
+    if (match === null)
+        return null;
+    const chatIdStr = match[1];
+    if (chatIdStr === undefined)
+        return null;
+    const chatId = Number(chatIdStr);
+    const topicStr = match[2];
+    const topicId = topicStr !== undefined ? Number(topicStr) : undefined;
+    return topicId === undefined ? { chatId } : { chatId, topicId };
+}
+/** Map a grammy/transport error to the canonical `SendResult` failure shape.
+ *  Shared by `send` + `sendPhoto` so the wire-error contract stays identical. */
+function mapSendError(e) {
+    if (e instanceof GrammyError) {
+        return { ok: false, error: `telegram api ${e.error_code}: ${e.description}` };
+    }
+    if (e instanceof HttpError) {
+        return { ok: false, error: `network: ${e.message}` };
+    }
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+}
+/** Default download seam — fetch the bytes from the Telegram file URL. */
+const defaultDownload = async (url) => {
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`download failed: HTTP ${String(res.status)}`);
+    }
+    return new Uint8Array(await res.arrayBuffer());
+};
+/** Extension from a Telegram `file_path` (`photos/file_42.jpg` → `jpg`);
+ *  falls back to `bin` when none is present. */
+function extFromFilePath(filePath) {
+    const dot = filePath.lastIndexOf('.');
+    if (dot === -1 || dot === filePath.length - 1)
+        return 'bin';
+    return filePath.slice(dot + 1).toLowerCase();
+}
+/** Pick the largest PhotoSize by file_size, then width (Telegram orders
+ *  ascending but we don't rely on that). Returns undefined for an empty array. */
+function largestPhoto(photos) {
+    let best;
+    for (const p of photos) {
+        if (best === undefined) {
+            best = p;
+            continue;
+        }
+        const pScore = p.file_size ?? p.width ?? 0;
+        const bScore = best.file_size ?? best.width ?? 0;
+        if (pScore > bScore)
+            best = p;
+    }
+    return best;
+}
+/**
+ * Build the rich `InboundChatMessage` from a grammy context. Pure. `direct`
+ * is a Telegram private chat (`chat.id === from.id`); `mentionsBot` is a
+ * case-insensitive `@<botUsername>` scan of the text (false when the bot
+ * username is unknown). `receivedAt` uses the platform `date` (unix seconds)
+ * when present, else the empty string is avoided by the caller.
+ */
+function buildTransportMessage(ctx, botUsername, nowIso) {
+    if (ctx.chat === undefined)
+        return null;
+    const fromId = ctx.from?.id;
+    const senderId = fromId !== undefined ? String(fromId) : '';
+    // CAT.4 — a media message carries its body as `caption`, not `text`. Mirror
+    // the caption into `text` so caption-only photos still drive a non-empty
+    // envelope (it's ALSO carried on each media entry's `caption`).
+    const text = ctx.message?.text ?? ctx.message?.caption ?? '';
+    const threadId = ctx.message?.message_thread_id;
+    const date = ctx.message?.date;
+    const mentionsBot = botUsername !== undefined && botUsername !== ''
+        ? text.toLowerCase().includes(`@${botUsername.toLowerCase()}`)
+        : false;
+    return {
+        platform: 'telegram',
+        messageId: ctx.message?.message_id !== undefined ? String(ctx.message.message_id) : '',
+        chatId: String(ctx.chat.id),
+        ...(threadId !== undefined ? { topicId: threadId } : {}),
+        sender: ctx.from?.username ?? ctx.from?.first_name ?? senderId,
+        senderId,
+        text,
+        receivedAt: date !== undefined ? new Date(date * 1000).toISOString() : nowIso,
+        mentionsBot,
+        direct: ctx.chat.type === 'private' || String(ctx.chat.id) === senderId,
+    };
+}
+export function telegramAdapter(opts) {
+    const bot = new Bot(opts.token);
+    let started = false;
+    let stopped = false;
+    const inboundHandlers = [];
+    const transportHandlers = [];
+    let inboundMiddlewareInstalled = false;
+    const download = opts.download ?? defaultDownload;
+    /**
+     * CAT.4 — download every photo/document on the message to the media dir and
+     * return the resulting `InboundMedia` pointers (empty when none). Resolves
+     * each `file_id` → `file_path` via `getFile`, downloads the bytes via the
+     * injectable seam, and writes `telegram-<message_id>-<n>.<ext>`. A per-item
+     * failure is swallowed (best-effort) so one broken attachment can't drop the
+     * whole message; the surviving items + text still flow through.
+     */
+    async function downloadMedia(ctx, messageId) {
+        const api = ctx.api;
+        if (api === undefined)
+            return [];
+        const dir = opts.mediaDownloadDir ?? inboundMediaDir();
+        const caption = ctx.message?.caption;
+        const out = [];
+        let n = 0;
+        const pending = [];
+        const photo = largestPhoto(ctx.message?.photo ?? []);
+        if (photo !== undefined)
+            pending.push({ kind: 'photo', fileId: photo.file_id });
+        const doc = ctx.message?.document;
+        if (doc !== undefined) {
+            pending.push({
+                kind: 'document',
+                fileId: doc.file_id,
+                ...(doc.mime_type !== undefined ? { mime: doc.mime_type } : {}),
+            });
+        }
+        for (const item of pending) {
+            try {
+                const file = await api.getFile(item.fileId);
+                const filePath = file.file_path;
+                if (filePath === undefined || filePath.length === 0)
+                    continue;
+                const url = `https://api.telegram.org/file/bot${opts.token}/${filePath}`;
+                const bytes = await download(url);
+                const ext = extFromFilePath(filePath);
+                const dest = join(dir, `telegram-${messageId}-${String(n)}.${ext}`);
+                await mkdir(dir, { recursive: true });
+                await writeFile(dest, bytes);
+                out.push({
+                    kind: item.kind,
+                    path: dest,
+                    ...(caption !== undefined ? { caption } : {}),
+                    ...(item.mime !== undefined ? { mime: item.mime } : {}),
+                });
+                n += 1;
+            }
+            catch {
+                // best-effort: skip a failed attachment, keep the rest + the text.
+            }
+        }
+        return out;
+    }
+    /**
+     * Install the single grammy `'message'` middleware (idempotent). Builds the
+     * rich `InboundChatMessage` once per update, feeds every enabled transport
+     * slot with it, and derives the lossy `InboundChannelEvent` for every
+     * enabled inbound slot. One bot, one middleware, two surfaces.
+     */
+    function ensureMiddleware() {
+        if (inboundMiddlewareInstalled)
+            return;
+        inboundMiddlewareInstalled = true;
+        bot.on('message', async (ctx) => {
+            const base = buildTransportMessage(ctx, opts.botUsername, new Date().toISOString());
+            if (base === null)
+                return;
+            // CAT.4 — download any attachments + attach the pointers. A message with
+            // media but no text still produces a non-null envelope here (no drop).
+            const media = await downloadMedia(ctx, base.messageId);
+            const msg = media.length > 0 ? { ...base, media } : base;
+            for (const slot of transportHandlers) {
+                if (!slot.enabled)
+                    continue;
+                try {
+                    await slot.fn(msg);
+                }
+                catch {
+                    // Handler errors stay inside the adapter — never bubble to grammy.
+                }
+            }
+            if (inboundHandlers.length > 0) {
+                const channelUri = msg.topicId !== undefined
+                    ? `telegram://${msg.chatId}/${msg.topicId}`
+                    : `telegram://${msg.chatId}`;
+                const event = {
+                    kind: 'inbound_channel',
+                    channelUri,
+                    sender: msg.senderId !== '' ? msg.senderId : 'unknown',
+                    text: msg.text,
+                    ...(msg.topicId !== undefined ? { threadKey: String(msg.topicId) } : {}),
+                    receivedAt: msg.receivedAt,
+                };
+                for (const slot of inboundHandlers) {
+                    if (!slot.enabled)
+                        continue;
+                    try {
+                        await slot.fn(event);
+                    }
+                    catch {
+                        // Handler errors stay inside the adapter.
+                    }
+                }
+            }
+        });
+    }
+    /** Auto-start long-polling if not already running (no-op in outbound-only). */
+    function ensureStarted() {
+        if (started || stopped)
+            return;
+        started = true;
+        stopped = false;
+        void attemptStart(0);
+    }
+    async function attemptStart(attempt) {
+        if (stopped)
+            return;
+        try {
+            // Defensive: clear any stale webhook config that would prevent
+            // long-polling. `drop_pending_updates: false` preserves unread
+            // updates across reconnects.
+            await bot.api.deleteWebhook({ drop_pending_updates: false });
+        }
+        catch {
+            // deleteWebhook failure is non-fatal — proceed to bot.start().
+        }
+        // DO NOT await bot.start(). It resolves on shutdown only; awaiting
+        // here would deadlock. `.catch()` handles the 409 retry path.
+        bot.start({ drop_pending_updates: false }).catch((e) => {
+            if (e instanceof GrammyError && e.error_code === 409) {
+                if (attempt < MAX_409_RETRIES) {
+                    const next = attempt + 1;
+                    const delay = Math.min(RETRY_BACKOFF_CAP_MS, 1000 * 2 ** next);
+                    setTimeout(() => {
+                        void attemptStart(next);
+                    }, delay);
+                }
+                // Else: give up on inbound; outbound-only path remains.
+                return;
+            }
+            // Non-409 errors: leave bot stopped. send() still works.
+        });
+    }
+    return {
+        scheme: 'telegram',
+        validate(uri) {
+            return /^telegram:\/\/-?\d+(\/\d+)?$/.test(uri);
+        },
+        async send(uri, message) {
+            const parsed = parseUri(uri);
+            if (parsed === null)
+                return { ok: false, error: 'bad uri' };
+            if (!opts.allowlistChatIds.includes(parsed.chatId)) {
+                return { ok: false, error: 'chat not in allowlist' };
+            }
+            try {
+                const extra = parsed.topicId !== undefined ? { message_thread_id: parsed.topicId } : undefined;
+                const sent = (await bot.api.sendMessage(parsed.chatId, message.text, extra));
+                const sentId = sent?.message_id;
+                return sentId !== undefined ? { ok: true, messageId: String(sentId) } : { ok: true };
+            }
+            catch (e) {
+                return mapSendError(e);
+            }
+        },
+        async sendPhoto(uri, photoOpts) {
+            const parsed = parseUri(uri);
+            if (parsed === null)
+                return { ok: false, error: 'bad uri' };
+            if (!opts.allowlistChatIds.includes(parsed.chatId)) {
+                return { ok: false, error: 'chat not in allowlist' };
+            }
+            // Explicit threadId arg wins over any topic embedded in the URI.
+            const thread = photoOpts.threadId ?? parsed.topicId;
+            try {
+                const extra = {};
+                if (photoOpts.caption !== undefined)
+                    extra.caption = photoOpts.caption;
+                if (thread !== undefined)
+                    extra.message_thread_id = thread;
+                const sent = (await bot.api.sendPhoto(parsed.chatId, new InputFile(photoOpts.path), extra));
+                const sentId = sent?.message_id;
+                return sentId !== undefined ? { ok: true, messageId: String(sentId) } : { ok: true };
+            }
+            catch (e) {
+                return mapSendError(e);
+            }
+        },
+        async start() {
+            if (started || opts.outboundOnly === true) {
+                started = true;
+                return;
+            }
+            started = true;
+            stopped = false;
+            // Kick off the start loop. Do NOT await — bot.start() resolves on
+            // shutdown only.
+            void attemptStart(0);
+            // Yield via microtask so the polling loop registers before send
+            // dispatch. Using Promise.resolve() (not setImmediate) so vitest's
+            // fake timers don't stall the await; microtasks aren't trapped.
+            await Promise.resolve();
+        },
+        async stop() {
+            if (!started)
+                return;
+            stopped = true;
+            started = false;
+            // Disable all subscription slots so an in-flight grammy update can't
+            // fire a handler after stop() returns.
+            for (const slot of inboundHandlers)
+                slot.enabled = false;
+            for (const slot of transportHandlers)
+                slot.enabled = false;
+            try {
+                await bot.stop();
+            }
+            catch {
+                // best-effort — if grammy already shut down, nothing to do.
+            }
+        },
+        async subscribeInbound(handler) {
+            // Outbound-only mode cannot accept inbound — surface as a stub that
+            // immediately resolves on unsubscribe. (Skip + audit lives in the
+            // router; the adapter itself stays silent.)
+            if (opts.outboundOnly === true) {
+                return { unsubscribe: () => Promise.resolve() };
+            }
+            ensureMiddleware();
+            const slot = { enabled: true, fn: handler };
+            inboundHandlers.push(slot);
+            ensureStarted();
+            await Promise.resolve();
+            return {
+                unsubscribe: () => {
+                    slot.enabled = false;
+                    return Promise.resolve();
+                },
+            };
+        },
+        async subscribeTransport(handler) {
+            // Outbound-only mode cannot accept inbound.
+            if (opts.outboundOnly === true) {
+                return { unsubscribe: () => Promise.resolve() };
+            }
+            ensureMiddleware();
+            const slot = { enabled: true, fn: handler };
+            transportHandlers.push(slot);
+            ensureStarted();
+            await Promise.resolve();
+            return {
+                unsubscribe: () => {
+                    slot.enabled = false;
+                    return Promise.resolve();
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=telegram.js.map

package/dist/channels/adapters/telegram.js.map

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

package/dist/channels/adapters/webhook.d.ts

@@ -0,0 +1,53 @@
+/**
+ * webhook:// adapter — generic outbound HTTPS POST with optional HMAC
+ * signing and jittered exponential backoff on 5xx.
+ *
+ * URI scheme: `webhook://<name>` where `<name>` is an exact string
+ * match against `opts.name`. Each webhookAdapter instance handles
+ * exactly one URI — the runtime registers one adapter per configured
+ * webhook endpoint.
+ *
+ * Body: JSON `{ text, severity }`. We keep the surface minimal so the
+ * receiver doesn't need to parse opensquid-internal types.
+ *
+ * Signature header (optional): `x-opensquid-signature: sha256=<hex>`
+ * where `<hex>` is the lowercase HMAC-SHA256 of the raw response body
+ * keyed by `signingSecret`. Receivers should compute the same HMAC and
+ * timing-safe compare. The convention mirrors GitHub's webhook spec.
+ *
+ * Retry policy: 3 total attempts. On 5xx, wait `100ms × 2^attempt + jitter`
+ * (jitter ≤ half the base delay) then retry. 4xx and network errors on
+ * the final attempt are not retried. The exit shape is always a
+ * SendResult — the adapter never throws.
+ *
+ * Security: `signingSecret` is closed over by this function and never
+ * appears in any log line, error string, or returned SendResult. Same
+ * discipline as the Telegram/Discord/Slack adapters.
+ */
+import type { ChannelAdapter } from '../types.js';
+export interface WebhookAdapterOpts {
+    /** Name segment in the URI: `webhook://<name>`. Must be non-empty. */
+    name: string;
+    /** Destination URL (https:// recommended). */
+    url: string;
+    /** Optional HMAC-SHA256 signing key. When set, every POST carries
+     * `x-opensquid-signature: sha256=<hex>`. */
+    signingSecret?: string;
+    /**
+     * Injection seam for tests — defaults to the global `fetch`. Production
+     * callers should leave this unset.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Injection seam for tests — defaults to `Math.random()`. Production
+     * callers should leave this unset.
+     */
+    random?: () => number;
+    /**
+     * Injection seam for the backoff sleep — defaults to `setTimeout`-
+     * based promise. Tests pass a synchronous stub.
+     */
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function webhookAdapter(opts: WebhookAdapterOpts): ChannelAdapter;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/channels/adapters/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../../src/channels/adapters/webhook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,cAAc,EAA8B,MAAM,aAAa,CAAC;AAE9E,MAAM,WAAW,kBAAkB;IACjC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ;gDAC4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAUD,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB,GAAG,cAAc,CA2DvE"}

package/dist/channels/adapters/webhook.js

@@ -0,0 +1,98 @@
+/**
+ * webhook:// adapter — generic outbound HTTPS POST with optional HMAC
+ * signing and jittered exponential backoff on 5xx.
+ *
+ * URI scheme: `webhook://<name>` where `<name>` is an exact string
+ * match against `opts.name`. Each webhookAdapter instance handles
+ * exactly one URI — the runtime registers one adapter per configured
+ * webhook endpoint.
+ *
+ * Body: JSON `{ text, severity }`. We keep the surface minimal so the
+ * receiver doesn't need to parse opensquid-internal types.
+ *
+ * Signature header (optional): `x-opensquid-signature: sha256=<hex>`
+ * where `<hex>` is the lowercase HMAC-SHA256 of the raw response body
+ * keyed by `signingSecret`. Receivers should compute the same HMAC and
+ * timing-safe compare. The convention mirrors GitHub's webhook spec.
+ *
+ * Retry policy: 3 total attempts. On 5xx, wait `100ms × 2^attempt + jitter`
+ * (jitter ≤ half the base delay) then retry. 4xx and network errors on
+ * the final attempt are not retried. The exit shape is always a
+ * SendResult — the adapter never throws.
+ *
+ * Security: `signingSecret` is closed over by this function and never
+ * appears in any log line, error string, or returned SendResult. Same
+ * discipline as the Telegram/Discord/Slack adapters.
+ */
+import { createHmac } from 'node:crypto';
+const MAX_ATTEMPTS = 3;
+const BASE_DELAY_MS = 100;
+/** Default jittered exponential backoff: `100ms × 2^attempt + jitter`. */
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function webhookAdapter(opts) {
+    const f = opts.fetch ?? fetch;
+    const rng = opts.random ?? Math.random;
+    const sleep = opts.sleep ?? defaultSleep;
+    const expectedUri = `webhook://${opts.name}`;
+    function sign(body) {
+        if (opts.signingSecret === undefined || opts.signingSecret === '')
+            return null;
+        const hex = createHmac('sha256', opts.signingSecret).update(body).digest('hex');
+        return `sha256=${hex}`;
+    }
+    /** Jittered backoff for attempt index `i` (0-based). */
+    function backoffMs(i) {
+        const base = BASE_DELAY_MS * 2 ** i;
+        // Jitter is up to half the base delay — keeps retries deterministic
+        // enough to test while still spreading load.
+        const jitter = Math.floor(rng() * (base / 2));
+        return base + jitter;
+    }
+    return {
+        scheme: 'webhook',
+        validate(uri) {
+            return uri === expectedUri;
+        },
+        async send(uri, message) {
+            if (uri !== expectedUri)
+                return { ok: false, error: 'bad uri' };
+            const body = JSON.stringify({ text: message.text, severity: message.severity });
+            const headers = { 'content-type': 'application/json' };
+            const signature = sign(body);
+            if (signature !== null)
+                headers['x-opensquid-signature'] = signature;
+            let lastError = '';
+            for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+                try {
+                    const res = await f(opts.url, { method: 'POST', headers, body });
+                    if (res.ok)
+                        return { ok: true };
+                    if (res.status >= 500 && attempt < MAX_ATTEMPTS - 1) {
+                        await sleep(backoffMs(attempt));
+                        lastError = `webhook ${res.status}`;
+                        continue;
+                    }
+                    // 4xx, or 5xx on final attempt — non-retryable.
+                    return { ok: false, error: `webhook ${res.status}` };
+                }
+                catch (e) {
+                    lastError = e instanceof Error ? e.message : String(e);
+                    if (attempt < MAX_ATTEMPTS - 1) {
+                        await sleep(backoffMs(attempt));
+                        continue;
+                    }
+                    return { ok: false, error: redactSecret(lastError, opts.signingSecret) };
+                }
+            }
+            return { ok: false, error: redactSecret(lastError || 'unreachable', opts.signingSecret) };
+        },
+    };
+}
+function redactSecret(message, secret) {
+    if (secret === undefined || secret === '')
+        return message;
+    return message.replaceAll(secret, '[redacted]');
+}
+//# sourceMappingURL=webhook.js.map

package/dist/channels/adapters/webhook.js.map

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

package/dist/channels/chat.d.ts

@@ -0,0 +1,18 @@
+/**
+ * chat:// adapter — in-session reply via Claude Code's reply surface.
+ *
+ * Hook-context contract: Claude Code captures a hook's stderr as the
+ * reply text shown to the agent. Outside hook context (e.g. MCP server
+ * over stdio), writing to stdout would corrupt the JSON-RPC stream, so
+ * we still write to stdout ONLY when OPENSQUID_HOOK_CONTEXT is unset.
+ * The MCP server entrypoint must NEVER set OPENSQUID_HOOK_CONTEXT=1
+ * and must NEVER route through chat:// without first redirecting its
+ * own stdout (see runtime/notification router, Task 1.14).
+ *
+ * URI scheme: `chat://` (no host, no path required). Any string starting
+ * with `chat://` validates; the suffix is reserved for future routing
+ * hints (e.g. `chat://main`) and is currently ignored.
+ */
+import type { ChannelAdapter } from './types.js';
+export declare const chatAdapter: ChannelAdapter;
+//# sourceMappingURL=chat.d.ts.map

package/dist/channels/chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../src/channels/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,cAAc,EAA8B,MAAM,YAAY,CAAC;AAE7E,eAAO,MAAM,WAAW,EAAE,cAiBzB,CAAC"}

package/dist/channels/chat.js

@@ -0,0 +1,35 @@
+/**
+ * chat:// adapter — in-session reply via Claude Code's reply surface.
+ *
+ * Hook-context contract: Claude Code captures a hook's stderr as the
+ * reply text shown to the agent. Outside hook context (e.g. MCP server
+ * over stdio), writing to stdout would corrupt the JSON-RPC stream, so
+ * we still write to stdout ONLY when OPENSQUID_HOOK_CONTEXT is unset.
+ * The MCP server entrypoint must NEVER set OPENSQUID_HOOK_CONTEXT=1
+ * and must NEVER route through chat:// without first redirecting its
+ * own stdout (see runtime/notification router, Task 1.14).
+ *
+ * URI scheme: `chat://` (no host, no path required). Any string starting
+ * with `chat://` validates; the suffix is reserved for future routing
+ * hints (e.g. `chat://main`) and is currently ignored.
+ */
+export const chatAdapter = {
+    scheme: 'chat',
+    validate(uri) {
+        return uri === 'chat://' || uri.startsWith('chat://');
+    },
+    // Async signature is required by the ChannelAdapter contract; stdio writes
+    // are themselves synchronous, hence the eslint disable.
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async send(_uri, message) {
+        const tagged = `[opensquid:${message.severity ?? 'info'}] ${message.text}`;
+        if (process.env.OPENSQUID_HOOK_CONTEXT === '1') {
+            process.stderr.write(tagged + '\n');
+        }
+        else {
+            process.stdout.write(tagged + '\n');
+        }
+        return { ok: true };
+    },
+};
+//# sourceMappingURL=chat.js.map

package/dist/channels/chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.js","sourceRoot":"","sources":["../../src/channels/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,CAAC,MAAM,WAAW,GAAmB;IACzC,MAAM,EAAE,MAAM;IACd,QAAQ,CAAC,GAAW;QAClB,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACxD,CAAC;IACD,2EAA2E;IAC3E,wDAAwD;IACxD,4DAA4D;IAC5D,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,OAAuB;QAC9C,MAAM,MAAM,GAAG,cAAc,OAAO,CAAC,QAAQ,IAAI,MAAM,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC;QAC3E,IAAI,OAAO,CAAC,GAAG,CAAC,sBAAsB,KAAK,GAAG,EAAE,CAAC;YAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;QACtC,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;CACF,CAAC"}