@a5c-ai/channels-adapter 5.1.1-staging.0007199a1cb2

package/dist/config.js

@@ -0,0 +1,323 @@
+// Config loading + validation (SPEC §5, DESIGN §1).
+//
+// `loadConfig(yamlStringOrPath, { env })` -> { config, errors }. It NEVER throws:
+// malformed YAML, an unresolved ${ENV}, an unknown backend type, a malformed
+// filter, or a backend.validateConfig failure are all collected into
+// `errors: string[]` so misconfiguration surfaces as actionable diagnostics
+// rather than a crash at poll time.
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import yaml from 'js-yaml';
+import { registry } from './registry.js';
+const KNOWN_OPS = new Set([
+    'eq', 'ne', 'in', 'nin', 'includes', 'contains', 'regex', 'exists', 'gt', 'gte', 'lt', 'lte'
+]);
+const DEFAULT_POLL_INTERVAL = 60;
+// SPEC §5: default `state.maxSeenPerSource` when the YAML omits it. A finite
+// default keeps the FIFO seen-bound from silently becoming UNBOUNDED (which would
+// let state files grow without limit); an explicit YAML value still wins.
+const DEFAULT_MAX_SEEN_PER_SOURCE = 1000;
+// SPEC §10 / DESIGN §7.5: the session-spawner config additions. All keys are
+// OPTIONAL and additive — an absent key preserves today's behavior.
+const SPAWN_MODES = new Set(['headless', 'interactive']);
+const APPROVAL_MODES = new Set(['yolo', 'prompt', 'deny']);
+const ON_EVENT_VALUES = new Set(['emit', 'spawn', 'both']);
+// adapters McpServerConfig.name regex.
+const MCP_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+/** Default global spawn block (DESIGN §7.5). `agent` defaults to the CANONICAL
+ *  adapters key `'claude'`. An explicit YAML `agent` value is preserved verbatim
+ *  here (normalization happens in the spawner, not at load). */
+const SPAWN_DEFAULTS = {
+    agent: 'claude',
+    mode: 'headless',
+    approvalMode: 'yolo',
+    selfMcpName: 'mcp-channels',
+    maxConcurrent: 4
+};
+/**
+ * Interpolate `${NAME}` placeholders from `env` across the PARSED config tree.
+ * Walking the parsed structure (rather than the raw text) means YAML comments
+ * are already stripped, so a literal `${ENV}` inside a comment is never mistaken
+ * for a required variable. Records every unresolved name in `errors`.
+ */
+function interpolateNode(node, env, missing) {
+    if (typeof node === 'string') {
+        return node.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_m, name) => {
+            const val = env[name];
+            if (val === undefined || val === null || val === '') {
+                missing.add(name);
+                return '';
+            }
+            return String(val);
+        });
+    }
+    if (Array.isArray(node)) {
+        return node.map((v) => interpolateNode(v, env, missing));
+    }
+    if (node && typeof node === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(node)) {
+            out[k] = interpolateNode(v, env, missing);
+        }
+        return out;
+    }
+    return node;
+}
+/**
+ * Validate a filter spec recursively. Pushes human-readable problems into
+ * `errors`. Mirrors the engine in filter.js so a bad filter is caught at load
+ * time (rather than silently never matching at runtime).
+ */
+function validateFilter(spec, sourceId, errors) {
+    if (spec == null)
+        return;
+    if (typeof spec !== 'object' || Array.isArray(spec)) {
+        errors.push(`Source "${sourceId}": filter must be an object`);
+        return;
+    }
+    const s = spec;
+    if (Array.isArray(s.all)) {
+        s.all.forEach((sub) => validateFilter(sub, sourceId, errors));
+        return;
+    }
+    if (Array.isArray(s.any)) {
+        s.any.forEach((sub) => validateFilter(sub, sourceId, errors));
+        return;
+    }
+    if ('not' in s) {
+        validateFilter(s.not, sourceId, errors);
+        return;
+    }
+    // An empty object is "no gate"; allow it.
+    if (!('field' in s) && !('op' in s))
+        return;
+    // Leaf clause.
+    if (typeof s.field !== 'string' || s.field.length === 0) {
+        errors.push(`Source "${sourceId}": filter clause is missing a "field"`);
+    }
+    if (typeof s.op !== 'string' || !KNOWN_OPS.has(s.op)) {
+        errors.push(`Source "${sourceId}": filter clause has an unknown op "${s.op}" ` +
+            `(valid: ${[...KNOWN_OPS].join(', ')})`);
+    }
+}
+/**
+ * Validate an EFFECTIVE spawn config block (DESIGN §7.5). `label` identifies the
+ * origin in error messages. Pushes human-readable problems into `errors`; never
+ * throws.
+ */
+function validateSpawn(spawn, label, errors) {
+    if (spawn == null)
+        return;
+    if (typeof spawn !== 'object' || Array.isArray(spawn)) {
+        errors.push(`${label}: spawn must be a mapping`);
+        return;
+    }
+    const sp = spawn;
+    if (sp.mode != null && !SPAWN_MODES.has(sp.mode)) {
+        errors.push(`${label}: spawn.mode must be one of headless, interactive (got "${sp.mode}")`);
+    }
+    if (sp.approvalMode != null && !APPROVAL_MODES.has(sp.approvalMode)) {
+        errors.push(`${label}: spawn.approvalMode must be one of yolo, prompt, deny (got "${sp.approvalMode}")`);
+    }
+    if (sp.selfMcpName != null && !MCP_NAME_RE.test(String(sp.selfMcpName))) {
+        errors.push(`${label}: spawn.selfMcpName must match ^[a-zA-Z0-9_-]{1,64}$ (got "${sp.selfMcpName}")`);
+    }
+    if (sp.maxConcurrent != null) {
+        const n = sp.maxConcurrent;
+        if (typeof n !== 'number' || !Number.isInteger(n) || n < 1) {
+            errors.push(`${label}: spawn.maxConcurrent must be a positive integer (got "${n}")`);
+        }
+    }
+    if (sp.promptTemplate != null && typeof sp.promptTemplate !== 'string') {
+        errors.push(`${label}: spawn.promptTemplate must be a string`);
+    }
+}
+/** Shallow-merge a per-source spawn block OVER the global defaults (per-source
+ *  wins). `env` is deep-merged so a source can add one variable without
+ *  redefining the whole block (DESIGN §7.5). */
+function mergeSpawn(global, perSource) {
+    const merged = { ...(global || {}) };
+    if (perSource && typeof perSource === 'object' && !Array.isArray(perSource)) {
+        for (const [k, v] of Object.entries(perSource)) {
+            if (v === undefined)
+                continue;
+            if (k === 'env' && v && typeof v === 'object' && !Array.isArray(v)) {
+                merged.env = { ...(merged.env || {}), ...v };
+            }
+            else {
+                merged[k] = v;
+            }
+        }
+    }
+    return merged;
+}
+/**
+ * Resolve the raw YAML text from either an inline string or a file path. An
+ * inline config always contains newlines; a bare path won't, so a single-line
+ * existing file is read from disk. Returns `{ text, baseDir }` where `baseDir`
+ * is the directory custom backends resolve against.
+ */
+function resolveSource(input) {
+    if (typeof input === 'string' && !input.includes('\n')) {
+        try {
+            if (existsSync(input) && statSync(input).isFile()) {
+                return { text: readFileSync(input, 'utf8'), baseDir: dirname(resolve(input)) };
+            }
+        }
+        catch {
+            // fall through to treating it as inline YAML
+        }
+    }
+    return { text: String(input ?? ''), baseDir: process.cwd() };
+}
+/**
+ * Load and validate a channels config.
+ */
+export function loadConfig(input, opts = {}) {
+    const env = opts.env || process.env;
+    const errors = [];
+    const { text, baseDir } = resolveSource(input);
+    let parsed;
+    try {
+        parsed = yaml.load(text);
+    }
+    catch (err) {
+        errors.push(`Failed to parse YAML: ${err?.message || String(err)}`);
+        return {
+            config: { server: { permissionRelay: false }, sources: [], state: { maxSeenPerSource: DEFAULT_MAX_SEEN_PER_SOURCE }, defaults: { pollIntervalSeconds: DEFAULT_POLL_INTERVAL }, spawn: {}, baseDir },
+            errors
+        };
+    }
+    // Interpolate ${ENV} on the parsed tree (comments already stripped), then
+    // surface any unresolved variables as actionable errors.
+    const missing = new Set();
+    let raw = interpolateNode(parsed, env, missing);
+    for (const name of missing) {
+        errors.push(`Missing required environment variable: \${${name}}`);
+    }
+    if (raw == null || typeof raw !== 'object') {
+        errors.push('Config must be a YAML mapping with `server` and `sources`.');
+        raw = {};
+    }
+    const server = raw.server && typeof raw.server === 'object' ? raw.server : {};
+    const state = raw.state && typeof raw.state === 'object' ? raw.state : {};
+    const defaults = raw.defaults && typeof raw.defaults === 'object' ? raw.defaults : {};
+    const defaultInterval = typeof defaults.pollIntervalSeconds === 'number'
+        ? defaults.pollIntervalSeconds
+        : DEFAULT_POLL_INTERVAL;
+    if (!server.name) {
+        errors.push('config.server.name is required.');
+    }
+    // server.replySecret (DESIGN §7.4): optional string (typically ${ENV}). An
+    // empty/unset value is omitted (per-process random key path).
+    let replySecret;
+    if (server.replySecret != null && server.replySecret !== '') {
+        if (typeof server.replySecret === 'string') {
+            replySecret = server.replySecret;
+        }
+        else {
+            errors.push('config.server.replySecret must be a string.');
+        }
+    }
+    // Global spawn defaults block (DESIGN §7.5). Validate the RAW block, then
+    // normalize it onto config.spawn with documented defaults applied.
+    const rawSpawn = raw.spawn && typeof raw.spawn === 'object' && !Array.isArray(raw.spawn) ? raw.spawn : null;
+    if (raw.spawn != null && !rawSpawn) {
+        errors.push('config.spawn must be a mapping.');
+    }
+    validateSpawn(rawSpawn, 'global spawn', errors);
+    const globalSpawn = mergeSpawn(SPAWN_DEFAULTS, rawSpawn);
+    const rawSources = Array.isArray(raw.sources) ? raw.sources : [];
+    if (!Array.isArray(raw.sources)) {
+        errors.push('config.sources must be an array.');
+    }
+    const sources = rawSources.map((s) => {
+        const src = s && typeof s === 'object' ? s : {};
+        const id = src.id;
+        if (!id)
+            errors.push('Each source requires an `id`.');
+        // onEvent routing (DESIGN §7.5): default 'emit' so existing configs (which
+        // have no onEvent) keep emitting and never spawn. An unknown value is an error.
+        let onEvent = 'emit';
+        if (src.onEvent != null) {
+            if (ON_EVENT_VALUES.has(src.onEvent)) {
+                onEvent = src.onEvent;
+            }
+            else {
+                errors.push(`Source "${id}": onEvent must be one of emit, spawn, both (got "${src.onEvent}")`);
+            }
+        }
+        // Per-source spawn merged OVER the global spawn (per-source wins). Validate
+        // the EFFECTIVE merged block so an invalid effective mode/name is caught.
+        const rawSrcSpawn = src.spawn && typeof src.spawn === 'object' && !Array.isArray(src.spawn) ? src.spawn : null;
+        if (src.spawn != null && !rawSrcSpawn) {
+            errors.push(`Source "${id}": spawn must be a mapping.`);
+        }
+        const effectiveSpawn = mergeSpawn(globalSpawn, rawSrcSpawn);
+        validateSpawn(effectiveSpawn, `Source "${id}"`, errors);
+        const normalized = {
+            id,
+            backend: src.backend,
+            pollIntervalSeconds: typeof src.pollIntervalSeconds === 'number'
+                ? src.pollIntervalSeconds
+                : defaultInterval,
+            auth: src.auth || {},
+            config: src.config || {},
+            filter: src.filter,
+            routing: src.routing || {},
+            onEvent,
+            spawn: effectiveSpawn,
+            baseDir
+        };
+        // Backend resolution: a built-in/registered type, OR a relative path to a
+        // custom JS module. We only deeply validate registered types here; a custom
+        // path is validated at load time by registry.load().
+        const backendType = normalized.backend;
+        const looksLikePath = typeof backendType === 'string' &&
+            (backendType.startsWith('.') ||
+                backendType.startsWith('/') ||
+                /\.[cm]?js$/.test(backendType) ||
+                /^[A-Za-z]:[\\/]/.test(backendType));
+        if (!backendType) {
+            errors.push(`Source "${id}": a \`backend\` is required.`);
+        }
+        else if (!looksLikePath) {
+            const backend = registry.get(backendType);
+            if (!backend) {
+                errors.push(`Source "${id}": unknown backend type "${backendType}".`);
+            }
+            else if (typeof backend.validateConfig === 'function') {
+                try {
+                    const problems = backend.validateConfig(normalized) || [];
+                    for (const p of problems)
+                        errors.push(p);
+                }
+                catch (err) {
+                    errors.push(`Source "${id}": backend.validateConfig threw: ${err?.message || err}`);
+                }
+            }
+        }
+        validateFilter(normalized.filter, id, errors);
+        return normalized;
+    });
+    const config = {
+        server: {
+            name: server.name,
+            instructions: server.instructions,
+            permissionRelay: !!server.permissionRelay,
+            replySecret
+        },
+        state: {
+            dir: state.dir,
+            maxSeenPerSource: typeof state.maxSeenPerSource === 'number'
+                ? state.maxSeenPerSource
+                : DEFAULT_MAX_SEEN_PER_SOURCE
+        },
+        defaults: { pollIntervalSeconds: defaultInterval },
+        spawn: globalSpawn,
+        sources,
+        baseDir
+    };
+    return { config, errors };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/dedup.d.ts

@@ -0,0 +1,26 @@
+/**
+ * FIFO-prune a seen array to at most `max` entries (newest retained), but NEVER
+ * drop an id in `keep` — the boundary bucket. A naive count-based FIFO can evict
+ * an id whose timestamp still sits at/after the cursor (re-returned by the next
+ * inclusive `since`/`>=` query) → a duplicate emit. Retaining the boundary bucket
+ * makes the bound "soft": if `keep` alone exceeds `max`, all kept ids survive
+ * (the cursor guarantees the window stays small in practice) (SPEC §5.3,
+ * finding §3).
+ */
+export declare function boundSeen(seen: string[], { max, keep }?: {
+    max?: number;
+    keep?: Iterable<string>;
+}): string[];
+/**
+ * `fresh`: items whose id is not already in `seen` (deduped within the batch);
+ * `seen`: the union (prior seen + fresh ids), bounded by `max` (boundary-safe).
+ */
+export declare function deriveNew<T>(items: T[], { idOf, seen, max, keep }: {
+    idOf: (item: T) => string;
+    seen?: string[];
+    max?: number;
+    keep?: Iterable<string>;
+}): {
+    fresh: T[];
+    seen: string[];
+};

package/dist/dedup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup.d.ts","sourceRoot":"","sources":["../src/dedup.ts"],"names":[],"mappings":"AAQA;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,EAAE,GAAG,EAAE,IAAI,EAAE,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;CAAO,GAC5D,MAAM,EAAE,CA6BV;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EACzB,KAAK,EAAE,CAAC,EAAE,EACV,EACE,IAAI,EACJ,IAAS,EACT,GAAG,EACH,IAAI,EACL,EAAE;IACD,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;CACzB,GACA;IAAE,KAAK,EAAE,CAAC,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAgBhC"}

package/dist/dedup.js

@@ -0,0 +1,68 @@
+// Shared dedup helper (SPEC §5.3, DESIGN §5).
+//
+// `deriveNew` is the single chokepoint for "drop what we've already emitted".
+// Backends and the core both lean on it so "at most once" holds even when a
+// polling window overlaps the previous one (an inclusive `since`, a
+// minute-granularity JQL `>=`, …). Backends only choose the id derivation
+// (`idOf`) and any cursor post-filter; this function owns the seen-set logic.
+/**
+ * FIFO-prune a seen array to at most `max` entries (newest retained), but NEVER
+ * drop an id in `keep` — the boundary bucket. A naive count-based FIFO can evict
+ * an id whose timestamp still sits at/after the cursor (re-returned by the next
+ * inclusive `since`/`>=` query) → a duplicate emit. Retaining the boundary bucket
+ * makes the bound "soft": if `keep` alone exceeds `max`, all kept ids survive
+ * (the cursor guarantees the window stays small in practice) (SPEC §5.3,
+ * finding §3).
+ */
+export function boundSeen(seen, { max, keep } = {}) {
+    const arr = Array.isArray(seen) ? seen : [];
+    if (typeof max !== 'number' || !Number.isFinite(max) || arr.length <= max) {
+        return [...arr];
+    }
+    const keepSet = keep ? new Set(keep) : null;
+    if (!keepSet || keepSet.size === 0) {
+        // Plain FIFO: keep the most-recent `max` ids.
+        return arr.slice(arr.length - max);
+    }
+    // Walk newest→oldest, taking ids until we hit `max`, but ALWAYS taking a
+    // boundary id even past the budget. Preserve original order in the result.
+    const retainIdx = new Set();
+    let budget = max;
+    for (let i = arr.length - 1; i >= 0; i -= 1) {
+        const id = arr[i];
+        if (keepSet.has(id)) {
+            retainIdx.add(i); // boundary id: always retained
+        }
+        else if (budget > 0) {
+            retainIdx.add(i);
+            budget -= 1;
+        }
+    }
+    const out = [];
+    for (let i = 0; i < arr.length; i += 1) {
+        if (retainIdx.has(i))
+            out.push(arr[i]);
+    }
+    return out;
+}
+/**
+ * `fresh`: items whose id is not already in `seen` (deduped within the batch);
+ * `seen`: the union (prior seen + fresh ids), bounded by `max` (boundary-safe).
+ */
+export function deriveNew(items, { idOf, seen = [], max, keep }) {
+    const known = new Set(seen);
+    const fresh = [];
+    const freshIds = [];
+    for (const item of Array.isArray(items) ? items : []) {
+        const id = idOf(item);
+        if (known.has(id))
+            continue;
+        // Mark immediately so a duplicate id within this same batch is fresh once.
+        known.add(id);
+        fresh.push(item);
+        freshIds.push(id);
+    }
+    const nextSeen = boundSeen([...seen, ...freshIds], { max, keep });
+    return { fresh, seen: nextSeen };
+}
+//# sourceMappingURL=dedup.js.map

package/dist/dedup.js.map

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

package/dist/filter.d.ts

@@ -0,0 +1,9 @@
+import type { FilterSpec } from './types.js';
+/**
+ * Evaluate a filter spec (leaf or combinator) against a payload.
+ */
+export declare function filterMatch(spec: unknown, payload: unknown): boolean;
+/**
+ * Compile a filter spec into a reusable predicate `(payload) => boolean`.
+ */
+export declare function compileFilter(spec: FilterSpec | null | undefined): (payload: unknown) => boolean;

package/dist/filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter.d.ts","sourceRoot":"","sources":["../src/filter.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAc,UAAU,EAAE,MAAM,YAAY,CAAC;AA+EzD;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAqBpE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GAClC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAE/B"}

package/dist/filter.js

@@ -0,0 +1,115 @@
+// Declarative filter engine (SPEC §4, DESIGN §1).
+//
+// A filter `spec` is either a leaf clause `{ field, op, value, ignoreCase? }` or
+// a combinator `{ all: [...] } | { any: [...] } | { not: clause }`. Matching is
+// performed against a dot-path payload. The cardinal rule (AC-9/AC-10): an
+// unknown op, a bad/missing dot-path, or a malformed regex yields NO MATCH and
+// NEVER throws — a misconfigured filter must not be able to crash a poll.
+/**
+ * Resolve a dot-path (e.g. "issue.assignee.login") against an object. Returns
+ * `undefined` for any missing segment or when traversing into a primitive.
+ */
+function getPath(obj, path) {
+    if (obj == null || typeof path !== 'string')
+        return undefined;
+    let cur = obj;
+    for (const key of path.split('.')) {
+        if (cur == null || (typeof cur !== 'object' && typeof cur !== 'function')) {
+            return undefined;
+        }
+        cur = cur[key];
+    }
+    return cur;
+}
+/** Build a RegExp, returning `null` if the pattern is invalid. */
+function safeRegExp(pattern, flags) {
+    try {
+        return new RegExp(pattern, flags);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Evaluate a single leaf clause.
+ */
+function matchLeaf(clause, payload) {
+    const { field, op, value, ignoreCase } = clause;
+    if (typeof field !== 'string' || typeof op !== 'string')
+        return false;
+    const actual = getPath(payload, field);
+    switch (op) {
+        case 'eq':
+            return actual === value;
+        case 'ne':
+            return actual !== value;
+        case 'in':
+            return Array.isArray(value) && value.includes(actual);
+        case 'nin':
+            return Array.isArray(value) && !value.includes(actual);
+        case 'includes':
+            // The FIELD is an array that must contain `value`.
+            return Array.isArray(actual) && actual.includes(value);
+        case 'contains': {
+            // The FIELD is a string that must contain the substring `value`.
+            if (typeof actual !== 'string' || typeof value !== 'string')
+                return false;
+            return ignoreCase
+                ? actual.toLowerCase().includes(value.toLowerCase())
+                : actual.includes(value);
+        }
+        case 'regex': {
+            if (typeof actual !== 'string' || typeof value !== 'string')
+                return false;
+            const re = safeRegExp(value, ignoreCase ? 'i' : '');
+            return re ? re.test(actual) : false;
+        }
+        case 'exists': {
+            const present = actual !== undefined && actual !== null;
+            // value:true asserts presence; value:false asserts absence.
+            return value === false ? !present : present;
+        }
+        case 'gt':
+            return typeof actual === 'number' && typeof value === 'number' && actual > value;
+        case 'gte':
+            return typeof actual === 'number' && typeof value === 'number' && actual >= value;
+        case 'lt':
+            return typeof actual === 'number' && typeof value === 'number' && actual < value;
+        case 'lte':
+            return typeof actual === 'number' && typeof value === 'number' && actual <= value;
+        default:
+            // Unknown operator => no match (never throw).
+            return false;
+    }
+}
+/**
+ * Evaluate a filter spec (leaf or combinator) against a payload.
+ */
+export function filterMatch(spec, payload) {
+    // An empty / missing filter matches everything (no gate configured).
+    if (spec == null)
+        return true;
+    if (typeof spec !== 'object')
+        return false;
+    const s = spec;
+    if (Array.isArray(s.all)) {
+        return s.all.every((sub) => filterMatch(sub, payload));
+    }
+    if (Array.isArray(s.any)) {
+        return s.any.some((sub) => filterMatch(sub, payload));
+    }
+    if ('not' in s) {
+        return !filterMatch(s.not, payload);
+    }
+    // Leaf clause. An object with no field/op (e.g. `{}`) is treated as "no gate".
+    if (!('field' in s) && !('op' in s))
+        return true;
+    return matchLeaf(s, payload);
+}
+/**
+ * Compile a filter spec into a reusable predicate `(payload) => boolean`.
+ */
+export function compileFilter(spec) {
+    return (payload) => filterMatch(spec, payload);
+}
+//# sourceMappingURL=filter.js.map

package/dist/filter.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { ChannelServer, DEFAULT_INSTRUCTIONS } from './server.js';
+export { createRuntime } from './runtime.js';
+export { Poller } from './poller.js';
+export { defineBackend } from './backend.js';
+export { registry, Registry } from './registry.js';
+export { default as webhookBackend } from './backends/webhook.js';
+export type { NormalizedTriggerEvent, TriggerBackend } from '@a5c-ai/triggers-adapter';
+export { loadConfig } from './config.js';
+export { compileFilter, filterMatch } from './filter.js';
+export { StateStore, MemoryStateStore } from './state.js';
+export { deriveNew, boundSeen } from './dedup.js';
+export { encodeReplyTo, decodeReplyTo, dispatchReply, createRelay } from './relay.js';
+export { SessionSpawner, buildSpawnRunOptions } from './spawner.js';
+export type * from './types.js';

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAInD,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGlE,YAAY,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAEvF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGtF,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGpE,mBAAmB,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,21 @@
+// Public package surface (SPEC §3, DESIGN §1).
+//
+// This is what library consumers import. It re-exports the channel server, the
+// runtime bootstrap, the backend authoring helper + registry, and the filter,
+// state, dedup, and relay primitives.
+export { ChannelServer, DEFAULT_INSTRUCTIONS } from './server.js';
+export { createRuntime } from './runtime.js';
+export { Poller } from './poller.js';
+export { defineBackend } from './backend.js';
+export { registry, Registry } from './registry.js';
+// SPEC §4 — the OPTIONAL additive webhook-ingest backend (built on
+// `@a5c-ai/triggers-adapter`'s `normalizeEvent`). Alongside github/jira.
+export { default as webhookBackend } from './backends/webhook.js';
+export { loadConfig } from './config.js';
+export { compileFilter, filterMatch } from './filter.js';
+export { StateStore, MemoryStateStore } from './state.js';
+export { deriveNew, boundSeen } from './dedup.js';
+export { encodeReplyTo, decodeReplyTo, dispatchReply, createRelay } from './relay.js';
+// SPEC §10 / DESIGN §7 — the event-triggered session spawner.
+export { SessionSpawner, buildSpawnRunOptions } from './spawner.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,EAAE;AACF,+EAA+E;AAC/E,8EAA8E;AAC9E,sCAAsC;AAEtC,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEnD,mEAAmE;AACnE,yEAAyE;AACzE,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAKlE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEtF,8DAA8D;AAC9D,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC"}