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

package/dist/spawner.js

@@ -0,0 +1,368 @@
+// Event-triggered session spawner (SPEC §10 / DESIGN §7).
+//
+// A surviving event (post filter + dedup) can spawn a fresh agent session via
+// `@a5c-ai/adapters` instead of — or in addition to — emitting into the current
+// session. The spawned session is SELF-ASSOCIATED: it is re-launched with THIS
+// MCP server over stdio (same config path) and handed the event context + the
+// same `reply_to` token, so it can post back to the SAME origin by calling the
+// `reply` tool.
+//
+// Two seams:
+//   - `buildSpawnRunOptions(source, event, { configPath, replySecret })` is a
+//     PURE function mapping the effective spawn config + event -> adapters
+//     `RunOptions`. No I/O, no client — the cheapest, most stable unit target.
+//   - `SessionSpawner` calls an INJECTED adapters-like client's `run(opts)` with
+//     bounded concurrency + error isolation. `@a5c-ai/adapters` is lazy-loaded
+//     only when no client is injected (so the suite stays fully offline and the
+//     dep is never imported in CI).
+import { fileURLToPath } from 'node:url';
+import { isAbsolute, resolve } from 'node:path';
+/**
+ * The canonical adapters agent id for Claude Code, as registered by
+ * `registerBuiltInAdapters(client)` in `@a5c-ai/adapters` (verified empirically:
+ * `client.adapters.get('claude')` resolves; `'claude-code'` does NOT). SPEC §10
+ * examples and configs write `claude-code` as a friendly alias — we normalize it
+ * to the canonical id so `client.run({ agent })` actually resolves the adapter.
+ */
+const DEFAULT_AGENT = 'claude';
+/**
+ * Map of friendly/catalog agent aliases -> the canonical adapter key the
+ * `@a5c-ai/adapters` registry resolves. `'claude-code'` is the documented friendly
+ * name (SPEC §10.3) but is an UNNORMALIZED catalog alias the registry does not
+ * resolve; the registered id is `'claude'`. A user may write either.
+ */
+const AGENT_ALIASES = { 'claude-code': 'claude' };
+/**
+ * Normalize a configured agent id to the canonical adapter key, so a friendly
+ * alias (e.g. `claude-code`) resolves against the real adapters registry. An
+ * unknown/already-canonical id passes through unchanged.
+ */
+export function normalizeAgentId(agent) {
+    if (agent == null || agent === '')
+        return DEFAULT_AGENT;
+    return AGENT_ALIASES[agent] || agent;
+}
+/** Absolute path to THIS framework's cli.js, resolved from this module so it is
+ *  correct regardless of the child's cwd (Windows-safe; no process.cwd reliance). */
+function defaultCliPath() {
+    return fileURLToPath(new URL('./cli.js', import.meta.url));
+}
+/**
+ * Render a `promptTemplate` with literal `{{…}}` substitution. Supported
+ * placeholders: `{{content}}`, `{{reply_to}}`, `{{source_id}}`, `{{meta.KEY}}`.
+ * Substitution is a SINGLE pass with literal values, so untrusted event text in
+ * `content`/`meta` can never inject a *new* placeholder (an unknown `{{meta.X}}`
+ * or missing key expands to the empty string).
+ */
+function renderTemplate(template, { content, reply_to, source_id, meta }) {
+    return String(template).replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_m, key) => {
+        if (key === 'content')
+            return content == null ? '' : String(content);
+        if (key === 'reply_to')
+            return reply_to == null ? '' : String(reply_to);
+        if (key === 'source_id')
+            return source_id == null ? '' : String(source_id);
+        if (key.startsWith('meta.')) {
+            const metaKey = key.slice('meta.'.length);
+            const val = meta ? meta[metaKey] : undefined;
+            return val == null ? '' : String(val);
+        }
+        // Unknown placeholder -> empty string (boring, predictable).
+        return '';
+    });
+}
+/**
+ * Build the default spawned prompt (AC-23): the event content, the routing-
+ * relevant meta (rendered as `key: value` lines), the source id, the `reply_to`
+ * token verbatim, and an explicit instruction to call the `reply` tool with it.
+ */
+function buildDefaultPrompt(source, event) {
+    const meta = event.meta || {};
+    const reply_to = meta.reply_to;
+    const lines = [];
+    lines.push('A new channel event was triggered and needs your attention.');
+    lines.push('');
+    lines.push(`source_id: ${source.id}`);
+    // Routing-relevant meta first (whatever identifies origin for that backend),
+    // then the remaining identifier meta (kind/author/etc.), excluding reply_to
+    // (surfaced separately, verbatim, below).
+    const routingKeys = ['repo', 'issue_number', 'project', 'issue_key', 'kind', 'author'];
+    const seen = new Set();
+    for (const key of routingKeys) {
+        if (key in meta && meta[key] != null && meta[key] !== '') {
+            lines.push(`${key}: ${meta[key]}`);
+            seen.add(key);
+        }
+    }
+    for (const [key, value] of Object.entries(meta)) {
+        if (key === 'reply_to' || seen.has(key))
+            continue;
+        if (value == null || value === '')
+            continue;
+        lines.push(`${key}: ${value}`);
+    }
+    lines.push('');
+    lines.push('Event content:');
+    lines.push(event.content == null ? '' : String(event.content));
+    lines.push('');
+    lines.push(`reply_to: ${reply_to == null ? '' : reply_to}`);
+    lines.push('');
+    lines.push('To respond to the origin of this event, call the `reply` tool with `reply_to` ' +
+        'set to the token above and your message as `text`. Echo the token exactly; ' +
+        'do not modify it.');
+    return lines.join('\n');
+}
+/**
+ * PURE mapping of (source, event, ctx) -> adapters `RunOptions` (SPEC §10.2).
+ * Reads the source's EFFECTIVE spawn config (`source.spawn`, already merged over
+ * the global defaults by config.js / the caller). Optional fields are OMITTED
+ * when unset (never emitted as `undefined`) so the adapter's own defaults apply.
+ */
+export function buildSpawnRunOptions(source, event, ctx = {}) {
+    const spawn = (source && source.spawn) || {};
+    const { configPath, replySecret, resolveCliPath } = ctx;
+    // --- prompt -------------------------------------------------------------
+    let prompt;
+    if (typeof spawn.promptTemplate === 'string') {
+        prompt = renderTemplate(spawn.promptTemplate, {
+            content: event.content,
+            reply_to: event.meta ? event.meta.reply_to : undefined,
+            source_id: source.id,
+            meta: event.meta || {}
+        });
+    }
+    else {
+        prompt = buildDefaultPrompt(source, event);
+    }
+    const opts = {
+        // Normalize the configured agent to the canonical adapters key so a friendly
+        // alias (`claude-code`) resolves against the real registry (`claude`). An
+        // unset agent falls back to the canonical default.
+        agent: normalizeAgentId(spawn.agent),
+        prompt
+    };
+    // --- mode mapping (exactly one of nonInteractive/interactive) -----------
+    const mode = spawn.mode || 'headless';
+    if (mode === 'interactive') {
+        opts.interactive = true;
+    }
+    else {
+        opts.nonInteractive = true;
+    }
+    // --- optional passthroughs (omitted when unset) -------------------------
+    if (spawn.model != null && spawn.model !== '')
+        opts.model = spawn.model;
+    if (spawn.systemPrompt != null && spawn.systemPrompt !== '') {
+        opts.systemPrompt = spawn.systemPrompt;
+    }
+    // approvalMode defaults to 'yolo' (autonomous reply).
+    opts.approvalMode = spawn.approvalMode || 'yolo';
+    // cwd resolved to an absolute path against the config's baseDir when set.
+    if (spawn.cwd != null && spawn.cwd !== '') {
+        const base = (source && source.baseDir) || process.cwd();
+        opts.cwd = isAbsolute(spawn.cwd) ? spawn.cwd : resolve(base, spawn.cwd);
+    }
+    if (spawn.env && typeof spawn.env === 'object') {
+        opts.env = { ...spawn.env };
+    }
+    // --- self-association mcpServers entry (AC-20) --------------------------
+    const cliPath = (typeof resolveCliPath === 'function' && resolveCliPath()) || defaultCliPath();
+    const selfMcp = {
+        name: spawn.selfMcpName || 'mcp-channels',
+        transport: 'stdio',
+        command: 'node',
+        args: [cliPath, configPath],
+        env: replySecret ? { MCP_CHANNELS_REPLY_SECRET: replySecret } : {}
+    };
+    opts.mcpServers = [selfMcp];
+    return opts;
+}
+/**
+ * The default lazy loader for the `@a5c-ai/adapters` client. Dynamic-imports the
+ * package, creates a client via the real `createClient()` factory, registers the
+ * built-in adapters ONTO that client via the real `registerBuiltInAdapters(client)`
+ * (so `agent:'claude'` resolves — the core `AdapterRegistry` starts empty), and
+ * returns it. NEVER imported at module load — only invoked when no client is
+ * injected (so tests that inject a fake stay fully offline).
+ *
+ * Bound HONESTLY to the in-repo `@a5c-ai/adapters` API: `createClient` and
+ * `registerBuiltInAdapters` are real exported symbols (re-exported from
+ * `@a5c-ai/comm-adapter` + `@a5c-ai/adapters-cli`), and the returned
+ * `AgentMuxClient.run(options)` is the real launch entry. The dynamic `import(...)`
+ * type is the package's own module type, so the factory/registration call sites are
+ * genuinely type-checked against the real signatures rather than cast through
+ * `unknown`. The structural `AdaptersClientLike` seam is preserved ONLY at the
+ * injection boundary (so the offline suite can supply a fake), and the real
+ * `AgentMuxClient` structurally satisfies it (it exposes `run(options): RunHandle`).
+ */
+/* c8 ignore start -- the real `@a5c-ai/adapters` launch path is environment-gated
+   (needs the claude CLI + auth) and out of scope for the offline suite (DESIGN §7.7);
+   tests always inject a fake client or loadClient. */
+async function defaultLoadClient() {
+    const mod = await import('@a5c-ai/adapters');
+    const client = mod.createClient();
+    mod.registerBuiltInAdapters(client);
+    return client;
+}
+/**
+ * Launches sessions for surviving events via an injected adapters-like client.
+ * Bounded concurrency (a tiny promise-queue semaphore), error isolation (a
+ * throwing/rejecting `run` is caught + logged, never thrown to the caller), and
+ * an `onDispatch` hook so the poller records seen-on-dispatch exactly once.
+ */
+export class SessionSpawner {
+    client;
+    configPath;
+    replySecret;
+    maxConcurrent;
+    log;
+    resolveCliPath;
+    loadClient;
+    onDispatch;
+    _free;
+    _waiters;
+    _clientPromise;
+    constructor({ client, configPath, replySecret, maxConcurrent = 4, log, resolveCliPath, loadClient, onDispatch } = {}) {
+        this.client = client || null;
+        this.configPath = configPath;
+        this.replySecret = replySecret;
+        this.maxConcurrent = Math.max(1, Number(maxConcurrent) || 4);
+        this.log = typeof log === 'function' ? log : () => { };
+        this.resolveCliPath = resolveCliPath;
+        this.loadClient = typeof loadClient === 'function' ? loadClient : defaultLoadClient;
+        this.onDispatch = typeof onDispatch === 'function' ? onDispatch : null;
+        // Concurrency semaphore: count of free slots + a FIFO queue of waiters.
+        this._free = this.maxConcurrent;
+        this._waiters = [];
+        // Memoize a lazily-loaded client so we resolve the dep at most once.
+        this._clientPromise = null;
+    }
+    /**
+     * Resolve the adapters client: the injected one if present, else the lazily
+     * loaded one. A failure to obtain a client is surfaced as a CLEAR, actionable
+     * error (AC-25). Memoized so the dep is resolved at most once.
+     */
+    async _getClient() {
+        if (this.client)
+            return this.client;
+        if (!this._clientPromise) {
+            this._clientPromise = (async () => {
+                let loaded;
+                try {
+                    loaded = await this.loadClient();
+                }
+                catch (err) {
+                    throw new Error("Spawn is configured but no client was injected and '@a5c-ai/adapters' " +
+                        `could not be loaded (${err?.message || err}); install it or inject a client.`);
+                }
+                if (!loaded || typeof loaded.run !== 'function') {
+                    throw new Error("Spawn is configured but no usable adapters client is available; install " +
+                        "'@a5c-ai/adapters' or inject a client with a run(options) method.");
+                }
+                return loaded;
+            })();
+            // Don't cache a rejected promise — let a later validate()/spawn retry.
+            this._clientPromise.catch(() => {
+                this._clientPromise = null;
+            });
+        }
+        return this._clientPromise;
+    }
+    /**
+     * Startup validation hook (AC-25): if no client is injected, eagerly attempt
+     * to obtain one so a missing dep fails FAST and LOUDLY at startup rather than
+     * silently at event time. Throws a clear error when no client can be obtained.
+     * A no-op when a client is injected (stays offline).
+     */
+    async validate() {
+        if (this.client)
+            return;
+        await this._getClient();
+    }
+    /** Acquire a concurrency slot (awaits when the cap is reached). */
+    _acquire() {
+        if (this._free > 0) {
+            this._free -= 1;
+            return Promise.resolve();
+        }
+        return new Promise((res) => {
+            this._waiters.push(res);
+        });
+    }
+    /** Release a concurrency slot, handing it to the next waiter if any. */
+    _release() {
+        const next = this._waiters.shift();
+        if (next) {
+            next();
+        }
+        else {
+            this._free += 1;
+        }
+    }
+    /**
+     * Spawn a session for one surviving event. Builds RunOptions, resolves the
+     * client, acquires a concurrency slot, calls `client.run(opts)`, and returns
+     * the launch outcome. NEVER throws to the caller (the poller): a launch error
+     * is caught + logged and converted to `{ ok:false, error }`. The event is
+     * recorded as dispatched EXACTLY ONCE (AC-24), regardless of launch outcome.
+     *
+     * The missing-client/dep error (AC-25) is the one case allowed to surface as a
+     * rejection (it is a misconfiguration, not a per-launch failure).
+     */
+    async spawn(source, event) {
+        // Resolve the client FIRST. A missing client/dep is a hard configuration
+        // error (AC-25) and is allowed to surface. (When a client is injected this
+        // never throws.)
+        const client = await this._getClient();
+        // Record the event as dispatched exactly once, BEFORE the launch settles, so
+        // a launch failure does not roll back dedup (at-most-once stance, AC-24).
+        if (this.onDispatch) {
+            try {
+                this.onDispatch(source, event);
+            }
+            catch {
+                // an onDispatch hook failure must not affect the spawn outcome
+            }
+        }
+        const opts = buildSpawnRunOptions(source, event, {
+            configPath: this.configPath,
+            replySecret: this.replySecret,
+            resolveCliPath: this.resolveCliPath
+        });
+        await this._acquire();
+        // `client.run` may throw SYNCHRONOUSLY (bad options) -> caught here -> the
+        // slot is released and the failure reported. This is a launch-start failure.
+        let handle;
+        try {
+            handle = client.run(opts);
+        }
+        catch (err) {
+            this._release();
+            this.log(`spawner: spawn failed for source "${source?.id}": ${err?.message || err}`);
+            return { ok: false, error: err };
+        }
+        // The slot is bound to the HANDLE's lifetime: the cap is on in-flight launches
+        // (DESIGN §7.2), so the slot stays occupied while the handle is open, and is
+        // freed the moment it settles (success OR failure).
+        let rejected = false;
+        let launchError;
+        Promise.resolve(handle).then(() => {
+            this._release();
+        }, (err) => {
+            rejected = true;
+            launchError = err;
+            this._release();
+        });
+        // Give an IMMEDIATE rejection a chance to settle, so it is reported as
+        // `{ ok:false }` and logged (AC-24). A pending (long-lived) handle does not
+        // reject in this window and is reported as a started launch.
+        await Promise.resolve();
+        await Promise.resolve();
+        if (rejected) {
+            this.log(`spawner: spawn failed for source "${source?.id}": ${launchError?.message || launchError}`);
+            return { ok: false, error: launchError };
+        }
+        return { ok: true, handle };
+    }
+}
+//# sourceMappingURL=spawner.js.map

package/dist/spawner.js.map

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

package/dist/state.d.ts

@@ -0,0 +1,43 @@
+export interface SourceState {
+    cursor: unknown;
+    seen: string[];
+}
+export interface StateSetArgs {
+    cursor?: unknown;
+    seen?: string[];
+    keepSeen?: string[];
+}
+export interface StateStoreLike {
+    get(id: string): SourceState;
+    set(id: string, state: StateSetArgs): void | Promise<void>;
+}
+/**
+ * File-backed state store. One JSON file per source under `dir`.
+ */
+export declare class StateStore implements StateStoreLike {
+    dir: string;
+    maxSeenPerSource?: number;
+    constructor({ dir, maxSeenPerSource }?: {
+        dir: string;
+        maxSeenPerSource?: number;
+    });
+    _pathFor(id: string): string;
+    get(id: string): SourceState;
+    /**
+     * Atomically persist state for a source (temp file + rename). `state.keepSeen`
+     * (optional) lists boundary ids the FIFO prune must never drop (finding §3).
+     */
+    set(id: string, state: StateSetArgs): Promise<void>;
+}
+/**
+ * In-memory state store with the same contract (pluggable for tests).
+ */
+export declare class MemoryStateStore implements StateStoreLike {
+    maxSeenPerSource?: number;
+    _map: Map<string, SourceState>;
+    constructor({ maxSeenPerSource }?: {
+        maxSeenPerSource?: number;
+    });
+    get(id: string): SourceState;
+    set(id: string, state: StateSetArgs): Promise<void>;
+}

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,CAAC;IAC7B,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AASD;;GAEG;AACH,qBAAa,UAAW,YAAW,cAAc;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,CAAC,EAAE,MAAM,CAAC;gBAEd,EAAE,GAAG,EAAE,gBAAgB,EAAE,GAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAqD;IAOpI,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM;IAI5B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW;IAiB5B;;;OAGG;IACG,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAU1D;AAED;;GAEG;AACH,qBAAa,gBAAiB,YAAW,cAAc;IACrD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;gBAEnB,EAAE,gBAAgB,EAAE,GAAE;QAAE,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAO;IAKpE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW;IAMtB,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAM1D"}

package/dist/state.js

@@ -0,0 +1,92 @@
+// State persistence (SPEC §3, DESIGN §1).
+//
+// Each source has state `{ cursor, seen[] }`. The cursor narrows the next API
+// query to "since last time"; the seen-set is the correctness backstop that
+// guarantees at-most-once across overlapping windows. `seen` is FIFO-bounded by
+// `maxSeenPerSource` so state files stay small.
+//
+// Two implementations:
+//   - StateStore: file-backed JSON, one file per source, written atomically
+//     (temp file + rename) so a crash never leaves a half-written state file.
+//   - MemoryStateStore: in-memory, for tests / ephemeral runs.
+import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { boundSeen } from './dedup.js';
+const DEFAULT_STATE = () => ({ cursor: null, seen: [] });
+/** Turn a source id into a filesystem-safe file name. */
+function safeFileName(id) {
+    return `${String(id).replace(/[^A-Za-z0-9._-]/g, '_')}.json`;
+}
+/**
+ * File-backed state store. One JSON file per source under `dir`.
+ */
+export class StateStore {
+    dir;
+    maxSeenPerSource;
+    constructor({ dir, maxSeenPerSource } = {}) {
+        if (!dir)
+            throw new Error('StateStore requires a `dir`');
+        this.dir = dir;
+        this.maxSeenPerSource = maxSeenPerSource;
+        mkdirSync(this.dir, { recursive: true });
+    }
+    _pathFor(id) {
+        return join(this.dir, safeFileName(id));
+    }
+    get(id) {
+        const file = this._pathFor(id);
+        if (!existsSync(file))
+            return DEFAULT_STATE();
+        try {
+            const raw = readFileSync(file, 'utf8');
+            const parsed = JSON.parse(raw);
+            return {
+                cursor: parsed?.cursor ?? null,
+                seen: Array.isArray(parsed?.seen) ? parsed.seen : []
+            };
+        }
+        catch {
+            // A corrupt/unreadable state file degrades to empty state rather than
+            // crashing a poll; the cursor simply restarts.
+            return DEFAULT_STATE();
+        }
+    }
+    /**
+     * Atomically persist state for a source (temp file + rename). `state.keepSeen`
+     * (optional) lists boundary ids the FIFO prune must never drop (finding §3).
+     */
+    async set(id, state) {
+        const next = {
+            cursor: state?.cursor ?? null,
+            seen: boundSeen(state?.seen, { max: this.maxSeenPerSource, keep: state?.keepSeen })
+        };
+        const file = this._pathFor(id);
+        const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, JSON.stringify(next), 'utf8');
+        renameSync(tmp, file);
+    }
+}
+/**
+ * In-memory state store with the same contract (pluggable for tests).
+ */
+export class MemoryStateStore {
+    maxSeenPerSource;
+    _map;
+    constructor({ maxSeenPerSource } = {}) {
+        this.maxSeenPerSource = maxSeenPerSource;
+        this._map = new Map();
+    }
+    get(id) {
+        const v = this._map.get(id);
+        if (!v)
+            return DEFAULT_STATE();
+        return { cursor: v.cursor, seen: [...v.seen] };
+    }
+    async set(id, state) {
+        this._map.set(id, {
+            cursor: state?.cursor ?? null,
+            seen: boundSeen(state?.seen, { max: this.maxSeenPerSource, keep: state?.keepSeen })
+        });
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,140 @@
+export interface ChannelEvent {
+    /** Stable dedup id for this event. */
+    id: string;
+    /** Text Claude sees inside <channel>…</channel>. */
+    content: string;
+    /** Identifier-keyed channel attributes ([A-Za-z0-9_]+). */
+    meta: Record<string, string>;
+    /** Raw upstream object (so declarative dot-path filters can match). */
+    payload: Record<string, unknown>;
+    /** Origin coordinates a reply needs to reach back to. */
+    routing: Record<string, unknown>;
+}
+export interface PollContext {
+    source: Record<string, unknown>;
+    state: {
+        cursor: unknown;
+        seen: string[];
+    };
+    http: (url: string | URL, opts?: Record<string, unknown>) => Promise<unknown>;
+    log: (...args: unknown[]) => void;
+    now: Date;
+}
+export interface PollResult {
+    events: ChannelEvent[];
+    state: {
+        cursor: unknown;
+        seen?: string[];
+    };
+}
+export interface ReplyArgs {
+    routing: Record<string, unknown>;
+    text: string;
+    source: Record<string, unknown>;
+    http: (url: string | URL, opts?: Record<string, unknown>) => Promise<unknown>;
+}
+export interface ReplyResult {
+    ok: boolean;
+    ref?: string;
+}
+export interface Backend {
+    type: string;
+    validateConfig?: (source: Record<string, unknown>) => string[];
+    init?: (source: Record<string, unknown>) => void | Promise<void>;
+    poll: (ctx: PollContext) => Promise<PollResult>;
+    reply: (a: ReplyArgs) => Promise<ReplyResult>;
+}
+export interface ReplyToken {
+    sourceId: string;
+    backendType: string;
+    routing: Record<string, unknown>;
+}
+/** Effective spawn config (global defaults merged with per-source overrides). */
+export interface SpawnConfig {
+    agent?: string;
+    mode?: 'headless' | 'interactive';
+    approvalMode?: 'yolo' | 'prompt' | 'deny';
+    selfMcpName?: string;
+    maxConcurrent?: number;
+    model?: string;
+    cwd?: string;
+    systemPrompt?: string;
+    env?: Record<string, string>;
+    promptTemplate?: string;
+}
+/** Adapters McpServerConfig (the self-association entry). */
+export interface McpServerConfig {
+    name: string;
+    transport: 'stdio';
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+}
+/** Adapters RunOptions produced by `buildSpawnRunOptions` (SPEC §10.2). The
+ *  package's OWN structural type — deliberately NOT imported from the adapters
+ *  SDK so `buildSpawnRunOptions` stays a pure mapping duck-typed by `client.run()`. */
+export interface RunOptions {
+    agent: string;
+    prompt: string;
+    mcpServers: McpServerConfig[];
+    nonInteractive?: boolean;
+    interactive?: boolean;
+    cwd?: string;
+    model?: string;
+    approvalMode?: 'yolo' | 'prompt' | 'deny';
+    systemPrompt?: string;
+    env?: Record<string, string>;
+}
+/** The leaf-clause operators the filter engine understands (SPEC §4). */
+export type FilterOp = 'eq' | 'ne' | 'in' | 'nin' | 'includes' | 'contains' | 'regex' | 'exists' | 'gt' | 'gte' | 'lt' | 'lte';
+/** A leaf clause: a dot-path `field`, an `op`, a comparison `value`. */
+export interface FilterLeaf {
+    field?: string;
+    op?: FilterOp;
+    value?: unknown;
+    ignoreCase?: boolean;
+}
+/** A combinator clause: `all` (AND), `any` (OR), or `not` (negation). */
+export type FilterCombinator = {
+    all?: FilterSpec[];
+} | {
+    any?: FilterSpec[];
+} | {
+    not?: FilterSpec;
+};
+/** A filter spec is either a leaf clause or a combinator (recursively). */
+export type FilterSpec = FilterLeaf | FilterCombinator;
+/** A normalized source after `loadConfig`: defaults applied + spawn merged. */
+export interface NormalizedSource {
+    id: unknown;
+    backend: unknown;
+    pollIntervalSeconds: number;
+    auth: Record<string, unknown>;
+    config: Record<string, unknown>;
+    filter: unknown;
+    routing: Record<string, unknown>;
+    onEvent: 'emit' | 'spawn' | 'both';
+    spawn: SpawnConfig;
+    baseDir: string;
+}
+/** The validated channels config returned by `loadConfig`. */
+export interface ChannelsConfig {
+    server: {
+        name?: unknown;
+        instructions?: unknown;
+        permissionRelay: boolean;
+        replySecret?: string;
+    };
+    state: {
+        dir?: unknown;
+        maxSeenPerSource: number;
+    };
+    defaults: {
+        pollIntervalSeconds: number;
+    };
+    spawn: SpawnConfig;
+    sources: NormalizedSource[];
+    baseDir: string;
+}