@a5c-ai/channels-adapter 5.1.1-staging.5ee7f5f98b91

package/dist/poller.d.ts

@@ -0,0 +1,63 @@
+import type { Backend, ChannelEvent, ReplyToken } from './types.js';
+import type { StateStoreLike } from './state.js';
+type AnySource = Record<string, any>;
+/** A spawner-like seam the poller dispatches surviving events to. */
+export interface SpawnerLike {
+    spawn(source: AnySource, event: ChannelEvent): unknown;
+}
+/** A server-like seam the poller emits surviving events to. */
+export interface EmitTargetLike {
+    emit(event: {
+        content: string;
+        meta: Record<string, unknown>;
+    }): void | Promise<void>;
+}
+export interface PollerDeps {
+    sources: AnySource[];
+    resolveBackend: (source: AnySource) => Backend | undefined | Promise<Backend | undefined>;
+    stateStore: StateStoreLike;
+    server: EmitTargetLike;
+    spawner?: SpawnerLike | null;
+    encodeReplyTo?: (record: ReplyToken) => string;
+    http: (url: string | URL, opts?: Record<string, unknown>) => Promise<unknown>;
+    now?: () => Date;
+    log?: (...args: unknown[]) => void;
+}
+export declare class Poller {
+    sources: AnySource[];
+    resolveBackend: PollerDeps['resolveBackend'];
+    stateStore: StateStoreLike;
+    server: EmitTargetLike;
+    spawner: SpawnerLike | null;
+    encodeReplyTo: (record: ReplyToken) => string;
+    http: PollerDeps['http'];
+    now: () => Date;
+    log: (...args: unknown[]) => void;
+    _byId: Map<string, AnySource>;
+    _timers: Map<string, ReturnType<typeof setInterval>>;
+    _initialized: Set<string>;
+    _active: Map<string, Promise<void>>;
+    _pending: Map<string, Promise<void>>;
+    constructor({ sources, resolveBackend, stateStore, server, spawner, encodeReplyTo, http, now, log }: PollerDeps);
+    /**
+     * Run a single poll for one source. Ticks for the SAME source are SERIALIZED
+     * AND COALESCED:
+     *  - if no tick is in flight, this one runs immediately;
+     *  - if a tick is in flight and NONE is pending, exactly ONE follow-up is
+     *    scheduled to run after the active one settles;
+     *  - if a tick is in flight and a follow-up is ALREADY pending, this call is
+     *    COALESCED onto that single pending tick.
+     * Ticks for DIFFERENT sources run concurrently. Errors are isolated so one
+     * failing tick doesn't poison the next.
+     */
+    tick(sourceId: string): Promise<void>;
+    /**
+     * The actual single-poll body (no serialization). Use `tick()` externally.
+     */
+    _runTick(sourceId: string): Promise<void>;
+    /** Start interval polling for every source. */
+    start(): void;
+    /** Stop all interval polling. */
+    stop(): void;
+}
+export {};

package/dist/poller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"poller.d.ts","sourceRoot":"","sources":["../src/poller.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAErC,qEAAqE;AACrE,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC;CACxD;AAED,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvF;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,cAAc,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IAC1F,UAAU,EAAE,cAAc,CAAC;IAC3B,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC;IAC/C,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9E,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED,qBAAa,MAAM;IACjB,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,cAAc,EAAE,UAAU,CAAC,gBAAgB,CAAC,CAAC;IAC7C,UAAU,EAAE,cAAc,CAAC;IAC3B,MAAM,EAAE,cAAc,CAAC;IACvB,OAAO,EAAE,WAAW,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC;IAC9C,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACzB,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAClC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC9B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC;IACrD,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACpC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;gBAEzB,EACV,OAAO,EACP,cAAc,EACd,UAAU,EACV,MAAM,EACN,OAAO,EACP,aAAa,EACb,IAAI,EACJ,GAAG,EACH,GAAG,EACJ,EAAE,UAAU;IAqBb;;;;;;;;;;OAUG;IACH,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCrC;;OAEG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsF/C,+CAA+C;IAC/C,KAAK,IAAI,IAAI;IAcb,iCAAiC;IACjC,IAAI,IAAI,IAAI;CAMb"}

package/dist/poller.js

@@ -0,0 +1,195 @@
+// Poller — per-source scheduling + the inbound pipeline (SPEC §3/§6 R5,
+// DESIGN §1/§3.1).
+//
+// For each source, on its scheduled tick (or a test's explicit tick(id)):
+//   1. load state           StateStore.get(id) -> { cursor, seen }
+//   2. poll the backend      backend.poll({ source, state, http, log, now })
+//   3. FILTER (core)         keep events whose payload satisfies source.filter
+//   4. DEDUP (core)          drop events whose id is already in seen
+//   5. mint reply_to         attach the opaque routing token to event.meta
+//   6. persist state         StateStore.set(id, { cursor', seen ∪ survivor ids })
+//   7. EMIT                  server.emit({ content, meta }) per survivor
+//
+// Filtering happens BEFORE dedup so a non-matching event is simply ignored that
+// tick (not recorded as seen). Dedup is the authoritative at-most-once gate.
+import { compileFilter } from './filter.js';
+import { deriveNew } from './dedup.js';
+import { encodeReplyTo as defaultEncodeReplyTo } from './relay.js';
+export class Poller {
+    sources;
+    resolveBackend;
+    stateStore;
+    server;
+    spawner;
+    encodeReplyTo;
+    http;
+    now;
+    log;
+    _byId;
+    _timers;
+    _initialized;
+    _active;
+    _pending;
+    constructor({ sources, resolveBackend, stateStore, server, spawner, encodeReplyTo, http, now, log }) {
+        this.sources = sources || [];
+        this.resolveBackend = resolveBackend;
+        this.stateStore = stateStore;
+        this.server = server;
+        this.spawner = spawner || null;
+        // The reply_to minter. Injected (secret-bound) by the runtime when a shared
+        // replySecret is configured; otherwise the module's per-process function.
+        this.encodeReplyTo = typeof encodeReplyTo === 'function' ? encodeReplyTo : defaultEncodeReplyTo;
+        this.http = http;
+        this.now = now || (() => new Date());
+        this.log = log || (() => { });
+        this._byId = new Map(this.sources.map((s) => [s.id, s]));
+        this._timers = new Map();
+        this._initialized = new Set();
+        /** the in-flight tick per source. */
+        this._active = new Map();
+        /** the single COALESCED follow-up per source. */
+        this._pending = new Map();
+    }
+    /**
+     * Run a single poll for one source. Ticks for the SAME source are SERIALIZED
+     * AND COALESCED:
+     *  - if no tick is in flight, this one runs immediately;
+     *  - if a tick is in flight and NONE is pending, exactly ONE follow-up is
+     *    scheduled to run after the active one settles;
+     *  - if a tick is in flight and a follow-up is ALREADY pending, this call is
+     *    COALESCED onto that single pending tick.
+     * Ticks for DIFFERENT sources run concurrently. Errors are isolated so one
+     * failing tick doesn't poison the next.
+     */
+    tick(sourceId) {
+        // No tick in flight → run now and record it as the active one.
+        if (!this._active.has(sourceId)) {
+            const run = this._runTick(sourceId)
+                .catch(() => { })
+                .finally(() => {
+                if (this._active.get(sourceId) === run)
+                    this._active.delete(sourceId);
+            });
+            this._active.set(sourceId, run);
+            return run;
+        }
+        // A tick is in flight. If one is already pending, coalesce onto it.
+        const pending = this._pending.get(sourceId);
+        if (pending)
+            return pending;
+        // Otherwise schedule EXACTLY ONE follow-up after the active tick settles.
+        const active = this._active.get(sourceId);
+        const next = active
+            .then(() => { }, () => { })
+            .then(() => {
+            // Promote the pending tick to active before running it.
+            this._pending.delete(sourceId);
+            const run = this._runTick(sourceId)
+                .catch(() => { })
+                .finally(() => {
+                if (this._active.get(sourceId) === run)
+                    this._active.delete(sourceId);
+            });
+            this._active.set(sourceId, run);
+            return run;
+        });
+        this._pending.set(sourceId, next);
+        return next;
+    }
+    /**
+     * The actual single-poll body (no serialization). Use `tick()` externally.
+     */
+    async _runTick(sourceId) {
+        const source = this._byId.get(sourceId);
+        if (!source)
+            return;
+        const backend = await this.resolveBackend(source);
+        if (!backend) {
+            this.log(`poller: no backend for source "${sourceId}"`);
+            return;
+        }
+        // One-time init before the first poll of this source.
+        if (!this._initialized.has(sourceId)) {
+            this._initialized.add(sourceId);
+            if (typeof backend.init === 'function') {
+                await backend.init(source);
+            }
+        }
+        const state = this.stateStore.get(sourceId);
+        const polled = await backend.poll({
+            source,
+            state,
+            http: this.http,
+            log: this.log,
+            now: this.now()
+        });
+        const events = Array.isArray(polled?.events) ? polled.events : [];
+        // (3) FILTER — core is the authoritative gate.
+        const predicate = compileFilter(source.filter);
+        const matched = events.filter((e) => predicate(e?.payload));
+        // (4) DEDUP — at-most-once across overlapping windows.
+        const { fresh, seen } = deriveNew(matched, {
+            idOf: (e) => e.id,
+            seen: state.seen || []
+        });
+        // (6) persist: cursor advances; seen is the union (store enforces the bound).
+        // Protect this tick's window ids from FIFO eviction so a boundary id still
+        // inside the cursor window can't be pruned and then re-emitted next poll
+        // (finding §3). The boundary bucket is a subset of the current window, so
+        // passing every matched id is a safe superset to keep.
+        const nextCursor = polled?.state?.cursor ?? null;
+        const keepSeen = matched.map((e) => e.id);
+        await this.stateStore.set(sourceId, { cursor: nextCursor, seen, keepSeen });
+        // (5) mint reply_to + (7) DISPATCH each survivor per the source's effective
+        // onEvent (DESIGN §7.6): emit -> server.emit, spawn -> spawner.spawn, both ->
+        // both. The SAME minted reply_to is shared between the emitted meta and the
+        // spawned event. Default is 'emit' (today's behavior) so existing sources
+        // never spawn.
+        const action = source.onEvent || 'emit';
+        const doEmit = action === 'emit' || action === 'both';
+        const doSpawn = (action === 'spawn' || action === 'both') && this.spawner;
+        for (const ev of fresh) {
+            const reply_to = this.encodeReplyTo({
+                sourceId,
+                backendType: backend.type || source.backend,
+                routing: ev.routing || {}
+            });
+            // The event carrying the minted reply_to in its meta (shared by both paths).
+            const meta = { ...(ev.meta || {}), reply_to };
+            if (doEmit) {
+                await this.server.emit({ content: ev.content, meta });
+            }
+            if (doSpawn) {
+                // Spawn is dispatched but NOT awaited to completion (the spawner bounds
+                // concurrency + isolates errors internally), so a slow/failing launch
+                // never stalls the tick or blocks sibling events.
+                const spawnEvent = { ...ev, meta };
+                const p = this.spawner.spawn(source, spawnEvent);
+                if (p && typeof p.catch === 'function') {
+                    p.catch((err) => this.log(`poller: spawn dispatch failed for "${sourceId}": ${err?.message || err}`));
+                }
+            }
+        }
+    }
+    /** Start interval polling for every source. */
+    start() {
+        for (const source of this.sources) {
+            const ms = Math.max(1, Number(source.pollIntervalSeconds) || 60) * 1000;
+            const timer = setInterval(() => {
+                this.tick(source.id).catch((err) => this.log(`poller: tick("${source.id}") failed: ${err?.message || err}`));
+            }, ms);
+            // Don't keep the process alive solely for polling.
+            if (typeof timer.unref === 'function')
+                timer.unref();
+            this._timers.set(source.id, timer);
+        }
+    }
+    /** Stop all interval polling. */
+    stop() {
+        for (const timer of this._timers.values()) {
+            clearInterval(timer);
+        }
+        this._timers.clear();
+    }
+}
+//# sourceMappingURL=poller.js.map

package/dist/poller.js.map

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

package/dist/registry.d.ts

@@ -0,0 +1,22 @@
+import type { Backend } from './types.js';
+declare class Registry {
+    _map: Map<string, Backend>;
+    constructor();
+    /**
+     * Register a backend programmatically.
+     */
+    register(type: string, backend: Backend): Backend;
+    /**
+     * Look up a backend by type. Returns `undefined` for an unknown type (never
+     * throws).
+     */
+    get(type: string): Backend | undefined;
+    /**
+     * Dynamically import a custom backend referenced by (relative) path, resolving
+     * it against `baseDir`. Validates the module exposes the hook interface.
+     */
+    load(path: string, baseDir: string): Promise<Backend>;
+}
+/** The shared registry instance (built-ins pre-registered). */
+export declare const registry: Registry;
+export { Registry };

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAS1C,cAAM,QAAQ;IACZ,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;;IAS3B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;IAKjD;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAItC;;;OAGG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAO5D;AAED,+DAA+D;AAC/D,eAAO,MAAM,QAAQ,UAAiB,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/registry.js

@@ -0,0 +1,59 @@
+// Backend registry (SPEC §3/§6 R2, DESIGN §1).
+//
+// Maps a backend `type` -> backend module. Built-ins `github` and `jira` are
+// pre-registered as the REAL backend modules (statically imported), so a single
+// module instance is shared everywhere: `registry.get('github')` returns the same
+// object that `import github from './backends/github.js'` yields.
+//
+// Custom backends referenced from YAML by relative path are loaded on demand via
+// `registry.load(path, baseDir)` (dynamic import, resolved against the config dir).
+import { pathToFileURL } from 'node:url';
+import { resolve, isAbsolute } from 'node:path';
+import { defineBackend } from './backend.js';
+import githubBackend from './backends/github.js';
+import jiraBackend from './backends/jira.js';
+import webhookBackend from './backends/webhook.js';
+/** Built-in backend type -> backend module. */
+const BUILTINS = {
+    github: githubBackend,
+    jira: jiraBackend,
+    webhook: webhookBackend
+};
+class Registry {
+    _map;
+    constructor() {
+        this._map = new Map();
+        for (const [type, backend] of Object.entries(BUILTINS)) {
+            this._map.set(type, backend);
+        }
+    }
+    /**
+     * Register a backend programmatically.
+     */
+    register(type, backend) {
+        this._map.set(type, backend);
+        return backend;
+    }
+    /**
+     * Look up a backend by type. Returns `undefined` for an unknown type (never
+     * throws).
+     */
+    get(type) {
+        return this._map.get(type);
+    }
+    /**
+     * Dynamically import a custom backend referenced by (relative) path, resolving
+     * it against `baseDir`. Validates the module exposes the hook interface.
+     */
+    async load(path, baseDir) {
+        const abs = isAbsolute(path) ? path : resolve(baseDir || process.cwd(), path);
+        const mod = (await import(pathToFileURL(abs).href));
+        const backend = (mod.default ?? mod);
+        // Validate it really is a backend (throws a clear error if not).
+        return defineBackend(backend);
+    }
+}
+/** The shared registry instance (built-ins pre-registered). */
+export const registry = new Registry();
+export { Registry };
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,EAAE;AACF,6EAA6E;AAC7E,gFAAgF;AAChF,kFAAkF;AAClF,kEAAkE;AAClE,EAAE;AACF,iFAAiF;AACjF,oFAAoF;AAEpF,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,aAAa,MAAM,sBAAsB,CAAC;AACjD,OAAO,WAAW,MAAM,oBAAoB,CAAC;AAC7C,OAAO,cAAc,MAAM,uBAAuB,CAAC;AAGnD,+CAA+C;AAC/C,MAAM,QAAQ,GAA4B;IACxC,MAAM,EAAE,aAAa;IACrB,IAAI,EAAE,WAAW;IACjB,OAAO,EAAE,cAAc;CACxB,CAAC;AAEF,MAAM,QAAQ;IACZ,IAAI,CAAuB;IAE3B;QACE,IAAI,CAAC,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,KAAK,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,QAAQ,CAAC,IAAY,EAAE,OAAgB;QACrC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC7B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,OAAe;QACtC,MAAM,GAAG,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;QAC9E,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAA6C,CAAC;QAChG,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAqB,CAAC;QACzD,iEAAiE;QACjE,OAAO,aAAa,CAAC,OAAO,CAAY,CAAC;IAC3C,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,QAAQ,EAAE,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/relay.d.ts

@@ -0,0 +1,58 @@
+import type { ReplyToken, ReplyResult } from './types.js';
+/**
+ * Encode a routing record into an opaque, URL-safe, tamper-evident token of the
+ * form `<payload>.<sig>` where `payload = base64url(JSON(record))` and
+ * `sig = base64url(HMAC-SHA256(payload))`.
+ *
+ * The optional trailing `secret` (DESIGN §7.4) derives the signing key so a
+ * second process with the SAME secret can verify the token. Omitted ⇒ the
+ * per-process random key (existing single-arg behavior is unchanged).
+ */
+export declare function encodeReplyTo(record: ReplyToken | unknown, secret?: string): string;
+/**
+ * Decode an opaque token back into the routing record, VERIFYING the HMAC first.
+ * Returns `null` for any garbage (missing/invalid signature, bad base64, non-JSON,
+ * empty/nullish, or a tampered payload) — NEVER throws (AC-16).
+ *
+ * The optional trailing `secret` must match the one used to encode (DESIGN §7.4):
+ * a token minted under secret A does not verify under secret B (or the default),
+ * yielding `null`. Omitted ⇒ the per-process random key (unchanged behavior).
+ */
+export declare function decodeReplyTo(token: unknown, secret?: string): ReplyToken | null;
+/** Arguments to `dispatchReply`. */
+export interface DispatchArgs {
+    reply_to: string;
+    text: string;
+    resolveSource: (id: string) => Record<string, unknown> | undefined;
+    resolveBackend: (type: string, sourceId?: string) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>;
+    http: (url: string | URL, opts?: Record<string, unknown>) => Promise<unknown>;
+    /** Shared secret to decode under (DESIGN §7.4). */
+    secret?: string;
+}
+/** A relay bound to an optional shared secret. */
+export interface BoundRelay {
+    encodeReplyTo: (record: ReplyToken) => string;
+    decodeReplyTo: (token: unknown) => ReplyToken | null;
+    dispatchReply: (args: Omit<DispatchArgs, 'secret'>) => Promise<ReplyResult>;
+}
+/**
+ * Bind a shared `secret` to a relay instance (DESIGN §7.4). Returns
+ * `{ encodeReplyTo, decodeReplyTo, dispatchReply }` whose encode/decode use the
+ * derived key (and dispatchReply decodes under it), so the running instance signs
+ * AND verifies with the shared key. With no secret, this is exactly the
+ * per-process behavior of the module-level functions.
+ */
+export declare function createRelay(secret?: string): BoundRelay;
+/**
+ * Decode a reply token, look up the owning source + backend, and dispatch the
+ * reply to that backend. The single source of truth for the reply path; the
+ * runtime's reply handler delegates here. Returns the backend's `{ ok, ref? }`;
+ * an unknown/garbled/forged token or a missing source/backend yields
+ * `{ ok: false }` WITHOUT throwing (AC-16).
+ *
+ * The token's `sourceId` is passed as the second argument to `resolveBackend` so
+ * the caller can route to the EXACT owning source's backend (rather than the
+ * first backend matching `type`), which keeps two custom backends that share a
+ * `type` from cross-dispatching.
+ */
+export declare function dispatchReply({ reply_to, text, resolveSource, resolveBackend, http, secret }: DispatchArgs): Promise<ReplyResult>;

package/dist/relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../src/relay.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA8C1D;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAInF;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CA6BhF;AAED,oCAAoC;AACpC,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACnE,cAAc,EAAE,CACd,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,KAEf,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvB,SAAS,GACT,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;IACjD,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9E,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,CAAC;IAC9C,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,UAAU,GAAG,IAAI,CAAC;IACrD,aAAa,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;CAC7E;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAMvD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,EAClC,QAAQ,EACR,IAAI,EACJ,aAAa,EACb,cAAc,EACd,IAAI,EACJ,MAAM,EACP,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CA+BrC"}

package/dist/relay.js

@@ -0,0 +1,172 @@
+// The opaque, TAMPER-EVIDENT `reply_to` routing token + reply dispatch
+// (SPEC §4, DESIGN §4).
+//
+// A reply must reach the EXACT origin (this repo + issue number, or this Jira
+// key). Claude forwards only one small attribute back to us and inbound channel
+// text is an untrusted prompt-injection surface, so we must not let model-authored
+// text dictate where a write goes. The framework mints a single opaque token per
+// event (`meta.reply_to`); Claude treats it as a black box and echoes it back
+// when calling the `reply` tool. Only the framework interprets it.
+//
+// The token is `<base64url(JSON)>.<base64url(HMAC-SHA256)>` — URL-safe, a valid
+// meta identifier value (so it survives the meta-key sanitizer), and OPAQUE
+// (Claude can't read or mutate the routing target). The HMAC is computed over the
+// encoded payload with a PER-PROCESS random secret generated at startup, so a
+// forged/tampered token (e.g. a flipped char, or a hand-rolled base64url(JSON))
+// fails verification and is rejected. It is a *routing* token, not a bearer
+// secret: it carries no credentials (auth lives only in the loaded config, keyed
+// by source id) — the HMAC exists purely so the runtime never POSTs under real
+// credentials to a routing target it didn't itself mint.
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+// Per-process signing secret, generated once at module load. It never leaves the
+// process and is not derivable from a token, so tokens minted by this process
+// cannot be forged by anyone who hasn't seen the secret. A fresh secret each run
+// is fine for the single-process model: reply_to tokens are only meaningful
+// within the lifetime of the running server (the in-memory source/backend tables
+// they reference are process-local).
+//
+// SPEC §10 AC-21 / DESIGN §7.4: a SHARED secret makes a token portable across
+// processes (a spawned child must verify a token its parent minted). When a
+// non-empty secret is supplied, the HMAC key is DERIVED from it deterministically
+// (sha256(secret) -> 32 bytes) so two processes with the same secret produce
+// identical signatures. When no secret is supplied, this per-process random key
+// is used and behavior is identical to before (backward compatible).
+const REPLY_SECRET = randomBytes(32);
+/** Cache of derived 32-byte keys per shared secret string (avoid re-hashing). */
+const KEY_CACHE = new Map();
+/**
+ * Resolve the HMAC key: the derived key from a non-empty `secret`, else the
+ * per-process random key. A derived key is `sha256(secret)` (32 bytes), cached.
+ */
+function keyFor(secret) {
+    if (typeof secret === 'string' && secret.length > 0) {
+        let key = KEY_CACHE.get(secret);
+        if (!key) {
+            key = createHash('sha256').update(secret, 'utf8').digest();
+            KEY_CACHE.set(secret, key);
+        }
+        return key;
+    }
+    return REPLY_SECRET;
+}
+/** base64url-encode a Buffer/string without padding ambiguity. */
+function b64url(buf) {
+    return Buffer.from(buf).toString('base64url');
+}
+/** Compute the HMAC-SHA256 of `encodedPayload` (under `key`) as base64url. */
+function sign(encodedPayload, key) {
+    return createHmac('sha256', key).update(encodedPayload).digest('base64url');
+}
+/**
+ * Encode a routing record into an opaque, URL-safe, tamper-evident token of the
+ * form `<payload>.<sig>` where `payload = base64url(JSON(record))` and
+ * `sig = base64url(HMAC-SHA256(payload))`.
+ *
+ * The optional trailing `secret` (DESIGN §7.4) derives the signing key so a
+ * second process with the SAME secret can verify the token. Omitted ⇒ the
+ * per-process random key (existing single-arg behavior is unchanged).
+ */
+export function encodeReplyTo(record, secret) {
+    const json = JSON.stringify(record);
+    const payload = b64url(Buffer.from(json, 'utf8'));
+    return `${payload}.${sign(payload, keyFor(secret))}`;
+}
+/**
+ * Decode an opaque token back into the routing record, VERIFYING the HMAC first.
+ * Returns `null` for any garbage (missing/invalid signature, bad base64, non-JSON,
+ * empty/nullish, or a tampered payload) — NEVER throws (AC-16).
+ *
+ * The optional trailing `secret` must match the one used to encode (DESIGN §7.4):
+ * a token minted under secret A does not verify under secret B (or the default),
+ * yielding `null`. Omitted ⇒ the per-process random key (unchanged behavior).
+ */
+export function decodeReplyTo(token, secret) {
+    if (typeof token !== 'string' || token.length === 0)
+        return null;
+    const dot = token.lastIndexOf('.');
+    if (dot <= 0 || dot === token.length - 1)
+        return null;
+    const payload = token.slice(0, dot);
+    const provided = token.slice(dot + 1);
+    // Verify the signature in constant time. A flipped char in EITHER half makes
+    // the buffers differ (or differ in length) and the token is rejected.
+    let expectedBuf;
+    let providedBuf;
+    try {
+        expectedBuf = Buffer.from(sign(payload, keyFor(secret)), 'utf8');
+        providedBuf = Buffer.from(provided, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    if (expectedBuf.length !== providedBuf.length)
+        return null;
+    if (!timingSafeEqual(expectedBuf, providedBuf))
+        return null;
+    try {
+        const json = Buffer.from(payload, 'base64url').toString('utf8');
+        const obj = JSON.parse(json);
+        if (obj == null || typeof obj !== 'object')
+            return null;
+        return obj;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Bind a shared `secret` to a relay instance (DESIGN §7.4). Returns
+ * `{ encodeReplyTo, decodeReplyTo, dispatchReply }` whose encode/decode use the
+ * derived key (and dispatchReply decodes under it), so the running instance signs
+ * AND verifies with the shared key. With no secret, this is exactly the
+ * per-process behavior of the module-level functions.
+ */
+export function createRelay(secret) {
+    return {
+        encodeReplyTo: (record) => encodeReplyTo(record, secret),
+        decodeReplyTo: (token) => decodeReplyTo(token, secret),
+        dispatchReply: (args) => dispatchReply({ ...args, secret })
+    };
+}
+/**
+ * Decode a reply token, look up the owning source + backend, and dispatch the
+ * reply to that backend. The single source of truth for the reply path; the
+ * runtime's reply handler delegates here. Returns the backend's `{ ok, ref? }`;
+ * an unknown/garbled/forged token or a missing source/backend yields
+ * `{ ok: false }` WITHOUT throwing (AC-16).
+ *
+ * The token's `sourceId` is passed as the second argument to `resolveBackend` so
+ * the caller can route to the EXACT owning source's backend (rather than the
+ * first backend matching `type`), which keeps two custom backends that share a
+ * `type` from cross-dispatching.
+ */
+export async function dispatchReply({ reply_to, text, resolveSource, resolveBackend, http, secret }) {
+    const decoded = decodeReplyTo(reply_to, secret);
+    if (!decoded || !decoded.backendType)
+        return { ok: false };
+    const source = resolveSource(decoded.sourceId);
+    if (!source)
+        return { ok: false };
+    let backend;
+    try {
+        backend = await resolveBackend(decoded.backendType, decoded.sourceId);
+    }
+    catch {
+        return { ok: false };
+    }
+    if (!backend || typeof backend.reply !== 'function')
+        return { ok: false };
+    try {
+        const result = await backend.reply({
+            routing: decoded.routing,
+            text,
+            source,
+            http
+        });
+        return result || { ok: false };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+//# sourceMappingURL=relay.js.map

package/dist/relay.js.map

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

package/dist/runtime.d.ts

@@ -0,0 +1,27 @@
+import { ChannelServer } from './server.js';
+import { Poller } from './poller.js';
+import { type AdaptersClientLike } from './spawner.js';
+import type { ChannelsConfig } from './types.js';
+import type { StateStoreLike } from './state.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+export interface RuntimeDeps {
+    http?: (url: string | URL, opts?: Record<string, unknown>) => Promise<unknown>;
+    stateStore?: StateStoreLike;
+    now?: () => Date;
+    transport?: Transport;
+    env?: Record<string, string>;
+    client?: AdaptersClientLike;
+    loadClient?: () => Promise<AdaptersClientLike> | AdaptersClientLike;
+    resolveCliPath?: () => string;
+    permissionHandler?: (req: unknown) => 'allow' | 'deny' | Promise<'allow' | 'deny'>;
+    log?: (...args: unknown[]) => void;
+}
+export interface Runtime {
+    server: ChannelServer;
+    poller: Poller;
+    config: ChannelsConfig;
+    errors: string[];
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare function createRuntime(configPathOrYaml: string, deps?: RuntimeDeps): Promise<Runtime>;

package/dist/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAIrC,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,KAAK,EAAW,cAAc,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAI/E,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/E,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC;IACpE,cAAc,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,MAAM,CAAC,CAAC;IACnF,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAcD,wBAAsB,aAAa,CACjC,gBAAgB,EAAE,MAAM,EACxB,IAAI,GAAE,WAAgB,GACrB,OAAO,CAAC,OAAO,CAAC,CA2JlB"}