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

package/dist/runtime.js

@@ -0,0 +1,198 @@
+// Runtime composition root (SPEC §3/§6, DESIGN §1/§3).
+//
+// createRuntime(configPathOrYaml, deps) loads + validates config, constructs the
+// ChannelServer, resolves backends (built-in via the registry, custom via a
+// relative path), wires the Poller, and wires the reply tool back through the
+// opaque reply_to token to the owning backend's reply(). Returns
+// { server, poller, config, start, stop }.
+//
+//   start(): connect the (optional) transport + start the poller.
+//   stop():  stop the poller + close the server.
+//
+// `deps` injects the seams the tests need: a fake `http`, an in-memory
+// `stateStore`, a fixed `now`, and/or a capturing `transport`.
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadConfig } from './config.js';
+import { ChannelServer } from './server.js';
+import { Poller } from './poller.js';
+import { StateStore } from './state.js';
+import { registry } from './registry.js';
+import { createRelay } from './relay.js';
+import { SessionSpawner } from './spawner.js';
+/** A backend reference is a custom-module path (not a built-in type) when it
+ *  looks like a relative/absolute path or ends in a JS extension. */
+function looksLikePath(backend) {
+    return (typeof backend === 'string' &&
+        (backend.startsWith('.') ||
+            backend.startsWith('/') ||
+            /\.[cm]?js$/.test(backend) ||
+            /^[A-Za-z]:[\\/]/.test(backend)));
+}
+export async function createRuntime(configPathOrYaml, deps = {}) {
+    const { config, errors } = loadConfig(configPathOrYaml, { env: deps.env });
+    if (errors.length > 0) {
+        throw new Error(`mcp-channels: invalid config:\n  - ${errors.join('\n  - ')}`);
+    }
+    const http = deps.http || ((url, opts) => fetch(url, opts));
+    const now = deps.now || (() => new Date());
+    // Resolve the effective reply secret (DESIGN §7.4): config wins, env is the
+    // fallback. When set, a bound relay signs AND verifies with the derived key so
+    // the running instance interoperates with a child sharing the secret (both
+    // directions). When unset, the bound relay degrades to the per-process random
+    // key — identical to today's behavior (backward compatible).
+    const replySecret = config.server.replySecret ||
+        (deps.env ? deps.env.MCP_CHANNELS_REPLY_SECRET : process.env.MCP_CHANNELS_REPLY_SECRET) ||
+        undefined;
+    const relay = createRelay(replySecret);
+    const stateStore = deps.stateStore ||
+        new StateStore({
+            dir: config.state.dir || defaultStateDir(config.server.name),
+            maxSeenPerSource: config.state.maxSeenPerSource
+        });
+    const server = new ChannelServer({
+        name: config.server.name,
+        instructions: config.server.instructions,
+        permissionRelay: config.server.permissionRelay
+    });
+    // Wire a default permission handler when the relay is enabled (finding §13).
+    if (config.server.permissionRelay) {
+        server.setPermissionRequestHandler(async (req) => {
+            let behavior = 'deny';
+            try {
+                if (typeof deps.permissionHandler === 'function') {
+                    const decision = await deps.permissionHandler(req);
+                    behavior = decision === 'allow' ? 'allow' : 'deny';
+                }
+            }
+            catch {
+                behavior = 'deny';
+            }
+            await server.emitPermission({ request_id: req?.request_id, behavior });
+        });
+    }
+    // Cache resolved backends per source id (custom backends are imported once).
+    const backendCache = new Map();
+    const sourcesById = new Map(config.sources.map((s) => [s.id, s]));
+    async function resolveBackend(source) {
+        if (backendCache.has(source.id))
+            return backendCache.get(source.id);
+        let backend;
+        if (looksLikePath(source.backend)) {
+            backend = await registry.load(source.backend, config.baseDir);
+        }
+        else {
+            backend = registry.get(source.backend);
+        }
+        if (backend)
+            backendCache.set(source.id, backend);
+        return backend;
+    }
+    // Eagerly resolve + validate custom-path backends at startup so a broken
+    // custom backend (missing poll/reply, bad import) fails createRuntime rather
+    // than the first tick.
+    for (const source of config.sources) {
+        if (looksLikePath(source.backend)) {
+            await resolveBackend(source); // throws -> propagates out of createRuntime
+        }
+    }
+    // Wire the reply tool through relay.dispatchReply — the SINGLE source of truth
+    // for the reply path (decode token -> owning source + backend -> backend.reply).
+    server.setReplyHandler(async ({ reply_to, text }) => relay.dispatchReply({
+        reply_to,
+        text,
+        http,
+        resolveSource: (id) => sourcesById.get(id),
+        // Resolve the reply backend from the token's OWN sourceId, not by scanning
+        // sources for a matching `type`.
+        resolveBackend: async (_backendType, sourceId) => {
+            const source = sourcesById.get(sourceId);
+            if (!source)
+                return undefined;
+            return resolveBackend(source);
+        }
+    }));
+    // Construct a SessionSpawner only when a source actually opts into spawning
+    // (DESIGN §7.1).
+    const wantsSpawn = config.sources.some((s) => s.onEvent === 'spawn' || s.onEvent === 'both');
+    let spawner = null;
+    if (wantsSpawn) {
+        spawner = new SessionSpawner({
+            client: deps.client,
+            loadClient: deps.loadClient,
+            configPath: resolveConfigPath(configPathOrYaml),
+            replySecret,
+            maxConcurrent: config.spawn?.maxConcurrent,
+            resolveCliPath: deps.resolveCliPath,
+            log: deps.log || (() => { })
+        });
+        // AC-25: a source needs spawn but no client is injected and the optional dep
+        // can't be obtained -> fail STARTUP clearly, not at event time.
+        await spawner.validate();
+    }
+    const poller = new Poller({
+        sources: config.sources,
+        resolveBackend,
+        stateStore,
+        server,
+        spawner,
+        // Mint reply_to under the bound relay so a child sharing the secret can
+        // decode tokens this instance emitted (DESIGN §7.6).
+        encodeReplyTo: relay.encodeReplyTo,
+        http,
+        now,
+        log: () => { }
+    });
+    let started = false;
+    return {
+        server,
+        poller,
+        config,
+        errors,
+        async start() {
+            if (started)
+                return;
+            started = true;
+            if (deps.transport) {
+                await server.connect(deps.transport);
+            }
+            poller.start();
+        },
+        async stop() {
+            poller.stop();
+            if (started) {
+                try {
+                    await server.close();
+                }
+                catch {
+                    // ignore close errors during teardown
+                }
+            }
+            started = false;
+        }
+    };
+}
+/**
+ * Resolve the config path for the self-MCP re-launch (DESIGN §7.3): an existing
+ * file path is resolved ABSOLUTELY (so the child finds it regardless of cwd);
+ * inline YAML (which has no path on disk) is passed through unchanged.
+ */
+function resolveConfigPath(input) {
+    if (typeof input === 'string' && !input.includes('\n')) {
+        try {
+            if (existsSync(input) && statSync(input).isFile()) {
+                return resolve(input);
+            }
+        }
+        catch {
+            // fall through — treat as inline / non-file
+        }
+    }
+    return input;
+}
+/** Default per-server state dir under ~/.claude/channels/<name>/state. */
+function defaultStateDir(name) {
+    const home = process.env.HOME || process.env.USERPROFILE || process.cwd();
+    return `${home}/.claude/channels/${name || 'mcp-channels'}/state`;
+}
+//# sourceMappingURL=runtime.js.map

package/dist/runtime.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,64 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { ReplyResult } from './types.js';
+/** A reply handler invoked when Claude calls the `reply` tool. */
+export type ReplyHandler = (a: {
+    reply_to: string;
+    text: string;
+}) => Promise<ReplyResult>;
+/** A permission-request handler invoked on an inbound permission_request. */
+export type PermissionRequestHandler = (req: {
+    request_id: string;
+    tool_name?: string;
+    description?: string;
+    input_preview?: string;
+}) => void | Promise<void>;
+export declare const DEFAULT_INSTRUCTIONS: string;
+export declare class ChannelServer {
+    name: string;
+    permissionRelay: boolean;
+    instructions: string;
+    server: Server;
+    _replyHandler: ReplyHandler | null;
+    _permissionRequestHandler: PermissionRequestHandler | null;
+    constructor({ name, instructions, permissionRelay }?: {
+        name: string;
+        instructions?: string;
+        permissionRelay?: boolean;
+    });
+    /** Register the `reply` tool handlers (ListTools + CallTool). */
+    _registerReplyTool(): void;
+    /** Wire the inbound permission_request notification handler. */
+    _registerPermissionRelay(): void;
+    /**
+     * Set the handler invoked when Claude calls the `reply` tool.
+     */
+    setReplyHandler(fn: ReplyHandler): void;
+    /**
+     * Set the handler invoked on an inbound permission_request (relay mode).
+     */
+    setPermissionRequestHandler(fn: PermissionRequestHandler): void;
+    /**
+     * Emit one channel event as a notifications/claude/channel.
+     */
+    emit({ content, meta }?: {
+        content?: string;
+        meta?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Emit a permission decision back to Claude (relay mode). `behavior` is coerced
+     * to EXACTLY 'allow' or 'deny' so the SPEC §2 contract holds regardless of what
+     * the caller passes — any value other than the literal 'allow' becomes 'deny'
+     * (silence/garbage means deny, the safe stance for an untrusted-input gate).
+     */
+    emitPermission({ request_id, behavior }: {
+        request_id: string;
+        behavior: 'allow' | 'deny';
+    }): Promise<void>;
+    /**
+     * Connect the underlying MCP server to a transport.
+     */
+    connect(transport: Transport): Promise<void>;
+    /** Close the underlying MCP server. */
+    close(): Promise<void>;
+}

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAKnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAe9C,kEAAkE;AAClE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AAE3F,6EAA6E;AAC7E,MAAM,MAAM,wBAAwB,GAAG,CAAC,GAAG,EAAE;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAyB3B,eAAO,MAAM,oBAAoB,QAQnB,CAAC;AAEf,qBAAa,aAAa;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,yBAAyB,EAAE,wBAAwB,GAAG,IAAI,CAAC;gBAE/C,EACV,IAAI,EACJ,YAAY,EACZ,eAAuB,EACxB,GAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,eAAe,CAAC,EAAE,OAAO,CAAA;KAIlE;IAoCD,iEAAiE;IACjE,kBAAkB,IAAI,IAAI;IA8D1B,gEAAgE;IAChE,wBAAwB,IAAI,IAAI;IAuBhC;;OAEG;IACH,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI;IAIvC;;OAEG;IACH,2BAA2B,CAAC,EAAE,EAAE,wBAAwB,GAAG,IAAI;IAI/D;;OAEG;IACG,IAAI,CAAC,EACT,OAAO,EACP,IAAI,EACL,GAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAU5E;;;;;OAKG;IACG,cAAc,CAAC,EACnB,UAAU,EACV,QAAQ,EACT,EAAE;QACD,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;KAC5B,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjB;;OAEG;IACG,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,uCAAuC;IACjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/server.js

@@ -0,0 +1,217 @@
+// ChannelServer — wraps the MCP `Server` to implement the claude/channel
+// contract (SPEC §2/§6 R1, DESIGN §1).
+//
+//   - Declares channel capabilities: always experimental['claude/channel']={}
+//     and tools={}; experimental['claude/channel/permission']={} when the
+//     optional permission relay is enabled.
+//   - emit({content,meta}) sends exactly ONE notifications/claude/channel with
+//     SANITIZED meta (identifier keys only) and never a `source` key.
+//   - Registers the `reply` tool (ListTools + CallTool); a reply handler returns
+//     { ok, ref? } and the tool maps falsy ok / a throw to { isError:true }.
+//   - Transport-injectable via connect(transport) so tests capture the wire.
+//   - Optional permission relay: handles inbound permission_request and exposes
+//     emitPermission({request_id, behavior}).
+import { z } from 'zod';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+const CHANNEL_NOTIFICATION = 'notifications/claude/channel';
+const PERMISSION_NOTIFICATION = 'notifications/claude/channel/permission';
+const PERMISSION_REQUEST_NOTIFICATION = 'notifications/claude/channel/permission_request';
+/** A meta key is valid iff it is a bare identifier: ^[A-Za-z0-9_]+$ */
+const IDENTIFIER_RE = /^[A-Za-z0-9_]+$/;
+// Strip control chars (incl. newlines/tabs/DEL), double/single quotes, and angle
+// brackets from meta VALUES so a value can never break the wire
+// `<channel k="v" ...>` attribute encoding or smuggle markup into the channel tag.
+// Built from explicit hex escapes to avoid literal control bytes in source.
+const UNSAFE_VALUE_CHARS = new RegExp("[\u0000-\u001F\u007F\"'<>]", "g");
+/**
+ * Sanitize meta into a strict `Record<string,string>`:
+ *  - drop keys that are not bare identifiers `[A-Za-z0-9_]+`,
+ *  - never emit a `source` key (Claude sets `source` from the server name),
+ *  - drop entries whose value is null/undefined,
+ *  - coerce every kept value to a String and strip control / quote / angle-bracket
+ *    characters so the wire attribute stays clean (SPEC §2, finding §11).
+ */
+function sanitizeMeta(meta) {
+    const out = {};
+    if (!meta || typeof meta !== 'object')
+        return out;
+    for (const [k, v] of Object.entries(meta)) {
+        if (k === 'source')
+            continue;
+        if (!IDENTIFIER_RE.test(k))
+            continue;
+        if (v === null || v === undefined)
+            continue;
+        out[k] = String(v).replace(UNSAFE_VALUE_CHARS, '');
+    }
+    return out;
+}
+// Default server `instructions` (SPEC §5, finding §12). Surfaced to Claude when
+// the config does not override them; explains how channel events arrive and how
+// to respond to the origin via the `reply` tool + the event's `reply_to` token.
+export const DEFAULT_INSTRUCTIONS = 'This MCP server is a Claude Code *channel*. External events (e.g. GitHub or ' +
+    'Jira activity) arrive as <channel source="..." ...>content</channel> tags. ' +
+    'Each event carries a `reply_to` attribute — an opaque routing token. To respond ' +
+    'back to the origin of an event (post a comment on the originating issue/PR or ' +
+    'Jira issue), call the `reply` tool with that event\'s exact `reply_to` value and ' +
+    'your `text`. Do not invent or modify `reply_to`; echo it verbatim. The token is ' +
+    'opaque and carries no secrets — it only tells the framework where your reply ' +
+    'should go.';
+export class ChannelServer {
+    name;
+    permissionRelay;
+    instructions;
+    server;
+    _replyHandler;
+    _permissionRequestHandler;
+    constructor({ name, instructions, permissionRelay = false } = {}) {
+        this.name = name;
+        this.permissionRelay = !!permissionRelay;
+        // Use the caller's instructions when provided, else a sane default that
+        // guides Claude to use the reply tool (never silently empty).
+        this.instructions =
+            typeof instructions === 'string' && instructions.length > 0
+                ? instructions
+                : DEFAULT_INSTRUCTIONS;
+        this._replyHandler = null;
+        this._permissionRequestHandler = null;
+        const capabilities = {
+            tools: {},
+            experimental: {
+                'claude/channel': {}
+            }
+        };
+        if (this.permissionRelay) {
+            capabilities.experimental['claude/channel/permission'] = {};
+        }
+        this.server = new Server({ name: name || 'mcp-channels', version: '0.1.0' }, { capabilities, instructions: this.instructions });
+        this._registerReplyTool();
+        if (this.permissionRelay) {
+            this._registerPermissionRelay();
+        }
+    }
+    /** Register the `reply` tool handlers (ListTools + CallTool). */
+    _registerReplyTool() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: 'reply',
+                    description: 'Reply back to the origin of a channel event. Pass the event\'s ' +
+                        'reply_to token and your text; the framework routes it to the right ' +
+                        'backend (e.g. a GitHub/Jira comment).',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            reply_to: {
+                                type: 'string',
+                                description: 'The opaque reply_to token from the inbound <channel> meta.'
+                            },
+                            text: { type: 'string', description: 'The reply text to post to origin.' }
+                        },
+                        required: ['reply_to', 'text']
+                    }
+                }
+            ]
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (req) => {
+            const { name, arguments: args = {} } = req.params;
+            if (name !== 'reply') {
+                return { content: [{ type: 'text', text: `unknown tool: ${name}` }], isError: true };
+            }
+            if (!this._replyHandler) {
+                return {
+                    content: [{ type: 'text', text: 'reply: no reply handler is configured' }],
+                    isError: true
+                };
+            }
+            try {
+                const result = await this._replyHandler({
+                    reply_to: args.reply_to,
+                    text: args.text
+                });
+                if (!result || !result.ok) {
+                    return {
+                        content: [{ type: 'text', text: 'reply failed: could not deliver to origin' }],
+                        isError: true
+                    };
+                }
+                const ref = result.ref ? ` (${result.ref})` : '';
+                return { content: [{ type: 'text', text: `reply sent${ref}` }] };
+            }
+            catch (err) {
+                return {
+                    content: [
+                        { type: 'text', text: `reply failed: ${err?.message || String(err)}` }
+                    ],
+                    isError: true
+                };
+            }
+        });
+    }
+    /** Wire the inbound permission_request notification handler. */
+    _registerPermissionRelay() {
+        this.server.setNotificationHandler(z.object({
+            method: z.literal(PERMISSION_REQUEST_NOTIFICATION),
+            params: z
+                .object({
+                request_id: z.string(),
+                tool_name: z.string().optional(),
+                description: z.string().optional(),
+                input_preview: z.string().optional()
+            })
+                .loose()
+        }), async (notification) => {
+            if (this._permissionRequestHandler) {
+                await this._permissionRequestHandler(notification.params);
+            }
+        });
+    }
+    /**
+     * Set the handler invoked when Claude calls the `reply` tool.
+     */
+    setReplyHandler(fn) {
+        this._replyHandler = fn;
+    }
+    /**
+     * Set the handler invoked on an inbound permission_request (relay mode).
+     */
+    setPermissionRequestHandler(fn) {
+        this._permissionRequestHandler = fn;
+    }
+    /**
+     * Emit one channel event as a notifications/claude/channel.
+     */
+    async emit({ content, meta } = {}) {
+        await this.server.notification({
+            method: CHANNEL_NOTIFICATION,
+            params: {
+                content: content ?? '',
+                meta: sanitizeMeta(meta)
+            }
+        });
+    }
+    /**
+     * Emit a permission decision back to Claude (relay mode). `behavior` is coerced
+     * to EXACTLY 'allow' or 'deny' so the SPEC §2 contract holds regardless of what
+     * the caller passes — any value other than the literal 'allow' becomes 'deny'
+     * (silence/garbage means deny, the safe stance for an untrusted-input gate).
+     */
+    async emitPermission({ request_id, behavior }) {
+        await this.server.notification({
+            method: PERMISSION_NOTIFICATION,
+            params: { request_id, behavior: behavior === 'allow' ? 'allow' : 'deny' }
+        });
+    }
+    /**
+     * Connect the underlying MCP server to a transport.
+     */
+    async connect(transport) {
+        await this.server.connect(transport);
+    }
+    /** Close the underlying MCP server. */
+    async close() {
+        await this.server.close();
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,uCAAuC;AACvC,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,4CAA4C;AAC5C,+EAA+E;AAC/E,sEAAsE;AACtE,iFAAiF;AACjF,6EAA6E;AAC7E,6EAA6E;AAC7E,gFAAgF;AAChF,8CAA8C;AAE9C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACtB,MAAM,oCAAoC,CAAC;AAI5C,MAAM,oBAAoB,GAAG,8BAA8B,CAAC;AAC5D,MAAM,uBAAuB,GAAG,yCAAyC,CAAC;AAC1E,MAAM,+BAA+B,GAAG,iDAAiD,CAAC;AAE1F,uEAAuE;AACvE,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAExC,iFAAiF;AACjF,gEAAgE;AAChE,mFAAmF;AACnF,4EAA4E;AAC5E,MAAM,kBAAkB,GAAG,IAAI,MAAM,CAAC,4BAA4B,EAAE,GAAG,CAAC,CAAC;AAazE;;;;;;;GAOG;AACH,SAAS,YAAY,CAAC,IAAyC;IAC7D,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,GAAG,CAAC;IAClD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC,KAAK,QAAQ;YAAE,SAAS;QAC7B,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC;YAAE,SAAS;QACrC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS;YAAE,SAAS;QAC5C,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAC/B,8EAA8E;IAC9E,6EAA6E;IAC7E,kFAAkF;IAClF,gFAAgF;IAChF,mFAAmF;IACnF,kFAAkF;IAClF,+EAA+E;IAC/E,YAAY,CAAC;AAEf,MAAM,OAAO,aAAa;IACxB,IAAI,CAAS;IACb,eAAe,CAAU;IACzB,YAAY,CAAS;IACrB,MAAM,CAAS;IACf,aAAa,CAAsB;IACnC,yBAAyB,CAAkC;IAE3D,YAAY,EACV,IAAI,EACJ,YAAY,EACZ,eAAe,GAAG,KAAK,KAC+C,EAIvE;QACC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC,eAAe,CAAC;QACzC,wEAAwE;QACxE,8DAA8D;QAC9D,IAAI,CAAC,YAAY;YACf,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC;gBACzD,CAAC,CAAC,YAAY;gBACd,CAAC,CAAC,oBAAoB,CAAC;QAC3B,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAC1B,IAAI,CAAC,yBAAyB,GAAG,IAAI,CAAC;QAEtC,MAAM,YAAY,GAGd;YACF,KAAK,EAAE,EAAE;YACT,YAAY,EAAE;gBACZ,gBAAgB,EAAE,EAAE;aACrB;SACF,CAAC;QACF,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,YAAY,CAAC,YAAY,CAAC,2BAA2B,CAAC,GAAG,EAAE,CAAC;QAC9D,CAAC;QAED,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CACtB,EAAE,IAAI,EAAE,IAAI,IAAI,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,EAClD,EAAE,YAAY,EAAE,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE,CAClD,CAAC;QAEF,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1B,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,IAAI,CAAC,wBAAwB,EAAE,CAAC;QAClC,CAAC;IACH,CAAC;IAED,iEAAiE;IACjE,kBAAkB;QAChB,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;YACjE,KAAK,EAAE;gBACL;oBACE,IAAI,EAAE,OAAO;oBACb,WAAW,EACT,iEAAiE;wBACjE,qEAAqE;wBACrE,uCAAuC;oBACzC,WAAW,EAAE;wBACX,IAAI,EAAE,QAAQ;wBACd,UAAU,EAAE;4BACV,QAAQ,EAAE;gCACR,IAAI,EAAE,QAAQ;gCACd,WAAW,EAAE,4DAA4D;6BAC1E;4BACD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,mCAAmC,EAAE;yBAC3E;wBACD,QAAQ,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC;qBAC/B;iBACF;aACF;SACF,CAAC,CAAC,CAAC;QAEJ,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YACjE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,EAAE,EAAE,GAAG,GAAG,CAAC,MAG1C,CAAC;YACF,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;gBACrB,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,IAAI,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;YACvF,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,CAAC;gBACxB,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,uCAAuC,EAAE,CAAC;oBAC1E,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC;oBACtC,QAAQ,EAAE,IAAI,CAAC,QAAkB;oBACjC,IAAI,EAAE,IAAI,CAAC,IAAc;iBAC1B,CAAC,CAAC;gBACH,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;oBAC1B,OAAO;wBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,2CAA2C,EAAE,CAAC;wBAC9E,OAAO,EAAE,IAAI;qBACd,CAAC;gBACJ,CAAC;gBACD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;gBACjD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,EAAE,EAAE,CAAC,EAAE,CAAC;YACnE,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO;oBACL,OAAO,EAAE;wBACP,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAkB,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE;qBAClF;oBACD,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,gEAAgE;IAChE,wBAAwB;QACtB,IAAI,CAAC,MAAM,CAAC,sBAAsB,CAChC,CAAC,CAAC,MAAM,CAAC;YACP,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,+BAA+B,CAAC;YAClD,MAAM,EAAE,CAAC;iBACN,MAAM,CAAC;gBACN,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;gBACtB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;gBAChC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;gBAClC,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;aACrC,CAAC;iBACD,KAAK,EAAE;SACX,CAAC,EACF,KAAK,EAAE,YAAY,EAAE,EAAE;YACrB,IAAI,IAAI,CAAC,yBAAyB,EAAE,CAAC;gBACnC,MAAM,IAAI,CAAC,yBAAyB,CAClC,YAAY,CAAC,MAAiD,CAC/D,CAAC;YACJ,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,eAAe,CAAC,EAAgB;QAC9B,IAAI,CAAC,aAAa,GAAG,EAAE,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,2BAA2B,CAAC,EAA4B;QACtD,IAAI,CAAC,yBAAyB,GAAG,EAAE,CAAC;IACtC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,EACT,OAAO,EACP,IAAI,KACoD,EAAE;QAC1D,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC;YAC7B,MAAM,EAAE,oBAAoB;YAC5B,MAAM,EAAE;gBACN,OAAO,EAAE,OAAO,IAAI,EAAE;gBACtB,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC;aACzB;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,cAAc,CAAC,EACnB,UAAU,EACV,QAAQ,EAIT;QACC,MAAM,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC;YAC7B,MAAM,EAAE,uBAAuB;YAC/B,MAAM,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,EAAE;SAC1E,CAAC,CAAC;IACL,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAO,CAAC,SAAoB;QAChC,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;IAED,uCAAuC;IACvC,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;CACF"}

package/dist/spawner.d.ts

@@ -0,0 +1,96 @@
+import type { RunOptions, ChannelEvent, SpawnConfig } from './types.js';
+type AnySource = Record<string, any>;
+/** The minimal structural seam the spawner needs from an adapters-like client.
+ *  Typed locally (NOT imported from `@a5c-ai/adapters`) so the pure
+ *  `buildSpawnRunOptions` mapping is duck-typed by `client.run()` and the package
+ *  never couples to the SDK's exact internal RunOptions type. */
+export interface AdaptersClientLike {
+    run(opts: RunOptions): unknown;
+}
+/**
+ * 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 declare function normalizeAgentId(agent: string | null | undefined): string;
+/**
+ * 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 declare function buildSpawnRunOptions(source: AnySource & {
+    id: string;
+    spawn?: SpawnConfig;
+    baseDir?: string;
+}, event: ChannelEvent, ctx?: {
+    configPath: string;
+    replySecret?: string;
+    resolveCliPath?: () => string;
+}): RunOptions;
+export interface SessionSpawnerDeps {
+    client?: AdaptersClientLike;
+    configPath: string;
+    replySecret?: string;
+    maxConcurrent?: number;
+    log?: (...args: unknown[]) => void;
+    resolveCliPath?: () => string;
+    loadClient?: () => Promise<AdaptersClientLike> | AdaptersClientLike;
+    onDispatch?: (source: AnySource, event: ChannelEvent) => void;
+}
+/**
+ * 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 declare class SessionSpawner {
+    client: AdaptersClientLike | null;
+    configPath: string;
+    replySecret?: string;
+    maxConcurrent: number;
+    log: (...args: unknown[]) => void;
+    resolveCliPath?: () => string;
+    loadClient: () => Promise<AdaptersClientLike> | AdaptersClientLike;
+    onDispatch: ((source: AnySource, event: ChannelEvent) => void) | null;
+    _free: number;
+    _waiters: Array<() => void>;
+    _clientPromise: Promise<AdaptersClientLike> | null;
+    constructor({ client, configPath, replySecret, maxConcurrent, log, resolveCliPath, loadClient, onDispatch }?: SessionSpawnerDeps);
+    /**
+     * 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.
+     */
+    _getClient(): Promise<AdaptersClientLike>;
+    /**
+     * 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).
+     */
+    validate(): Promise<void>;
+    /** Acquire a concurrency slot (awaits when the cap is reached). */
+    _acquire(): Promise<void>;
+    /** Release a concurrency slot, handing it to the next waiter if any. */
+    _release(): void;
+    /**
+     * 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).
+     */
+    spawn(source: AnySource & {
+        id: string;
+        spawn?: SpawnConfig;
+    }, event: ChannelEvent): Promise<{
+        ok: boolean;
+        handle?: unknown;
+        error?: unknown;
+    }>;
+}
+export {};

package/dist/spawner.d.ts.map

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