@cleocode/core 2026.6.13 → 2026.6.15

package/dist/conduit/delivery-router.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Delivery Router + Session Store — route inbound channel messages to the agent
+ * and route the agent's reply back to the originating channel.
+ *
+ * This is the minimal Session Store + Delivery Router stub from T1797 (epic
+ * T11854 · saga T10419). It tracks per-channel session affinity in memory and
+ * resolves an {@link OutboundReply} back to the {@link ChannelAdapter} that
+ * originated the inbound exchange. Channels register with the router; inbound
+ * messages flow `adapter.receive() → router.ingest() → handler`, and the
+ * handler's reply flows `router.dispatch() → adapter.send()` over the SAME
+ * channel by session affinity.
+ *
+ * The store is in-memory by design for the contained increment: the underlying
+ * conduit `LocalTransport` already persists the message rows in conduit.db
+ * (via the consolidated `conduit_*` domain through the store chokepoint), so the
+ * router does NOT open its own database handle and introduces no new schema.
+ * A durable session table is a follow-up if cross-process routing is needed.
+ *
+ * @see T1797 — Session Store + Delivery Router.
+ * @epic T11854
+ * @saga T10419
+ * @module conduit/delivery-router
+ */
+import type { ChannelAdapter, ChannelSession, InboundMsg, OutboundReply } from '@cleocode/contracts';
+/** Handler invoked for each routed inbound message; returns an optional reply. */
+export type InboundHandler = (msg: InboundMsg) => Promise<OutboundReply | undefined>;
+/**
+ * In-memory per-channel session-affinity store.
+ *
+ * Keyed on `(channelId, sessionKey)`, it remembers the last inbound exchange so
+ * the {@link DeliveryRouter} can route a reply back to the originating channel
+ * without the caller threading routing state.
+ *
+ * @see T1797
+ */
+export declare class SessionStore {
+    private readonly sessions;
+    /**
+     * Record (or refresh) the session for an inbound message.
+     *
+     * @param msg - The inbound message establishing the session.
+     * @returns The stored {@link ChannelSession}.
+     */
+    touch(msg: InboundMsg): ChannelSession;
+    /**
+     * Look up a stored session by channel + session key.
+     *
+     * @param channelId - The channel id.
+     * @param sessionKey - The channel-native session key.
+     * @returns The session if present, else `undefined`.
+     */
+    get(channelId: string, sessionKey: string): ChannelSession | undefined;
+    /**
+     * List every tracked session (newest-touched first).
+     *
+     * @returns A snapshot array of sessions.
+     */
+    list(): ChannelSession[];
+    /** Remove all tracked sessions. */
+    clear(): void;
+}
+/**
+ * Routes inbound channel messages to a handler and delivers replies back to the
+ * originating channel by session affinity.
+ *
+ * Channels register via {@link DeliveryRouter.register}. Calling
+ * {@link DeliveryRouter.run} drains each registered adapter's `receive()`
+ * stream, invokes the handler, and — when the handler returns a reply — routes
+ * it back over the same channel.
+ *
+ * @see T1797
+ */
+export declare class DeliveryRouter {
+    private readonly adapters;
+    private readonly store;
+    /**
+     * Create a router.
+     *
+     * @param store - Optional injected {@link SessionStore} (a fresh in-memory
+     *   store is created when omitted).
+     */
+    constructor(store?: SessionStore);
+    /** The session store backing this router. */
+    get sessions(): SessionStore;
+    /**
+     * Register a channel adapter with the router.
+     *
+     * @param adapter - The adapter to route for.
+     * @throws When an adapter with the same id is already registered.
+     */
+    register(adapter: ChannelAdapter): void;
+    /**
+     * Resolve the adapter registered for a channel id.
+     *
+     * @param channelId - The channel id.
+     * @returns The adapter if registered, else `undefined`.
+     */
+    adapter(channelId: string): ChannelAdapter | undefined;
+    /**
+     * Ingest a single inbound message: record session affinity and invoke the
+     * handler. When the handler returns a reply, it is dispatched back to the
+     * originating channel.
+     *
+     * Exposed independently of {@link DeliveryRouter.run} so a caller (or test)
+     * can drive one message at a time over an in-memory transport.
+     *
+     * @param msg - The inbound message.
+     * @param handler - The agent handler producing an optional reply.
+     */
+    ingest(msg: InboundMsg, handler: InboundHandler): Promise<void>;
+    /**
+     * Dispatch an outbound reply back to a channel.
+     *
+     * Resolution order for the destination channel + session:
+     *   1. Explicit `reply.channelId` / `reply.sessionKey`.
+     *   2. The originating inbound message's channel + session (affinity).
+     *   3. The adapter's `config.homeChannel` session fallback.
+     *
+     * @param reply - The reply to deliver.
+     * @param origin - The inbound message being replied to (for affinity).
+     * @throws When no destination channel can be resolved or is unregistered.
+     */
+    dispatch(reply: OutboundReply, origin?: InboundMsg): Promise<void>;
+    /**
+     * Drain a registered adapter's inbound stream, routing each message through
+     * the handler until the adapter stops (its `receive()` iterator ends).
+     *
+     * @param channelId - The channel to run.
+     * @param handler - The agent handler producing optional replies.
+     * @throws When the channel is not registered.
+     */
+    run(channelId: string, handler: InboundHandler): Promise<void>;
+}
+//# sourceMappingURL=delivery-router.d.ts.map

package/dist/conduit/delivery-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-router.d.ts","sourceRoot":"","sources":["../../src/conduit/delivery-router.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,UAAU,EACV,aAAa,EACd,MAAM,qBAAqB,CAAC;AAE7B,kFAAkF;AAClF,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,UAAU,KAAK,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAAC;AAOrF;;;;;;;;GAQG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAE9D;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,UAAU,GAAG,cAAc;IAYtC;;;;;;OAMG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAItE;;;;OAIG;IACH,IAAI,IAAI,cAAc,EAAE;IAIxB,mCAAmC;IACnC,KAAK,IAAI,IAAI;CAGd;AAED;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAC9D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC;;;;;OAKG;gBACS,KAAK,CAAC,EAAE,YAAY;IAIhC,6CAA6C;IAC7C,IAAI,QAAQ,IAAI,YAAY,CAE3B;IAED;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAOvC;;;;;OAKG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAItD;;;;;;;;;;OAUG;IACG,MAAM,CAAC,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrE;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBxE;;;;;;;OAOG;IACG,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;CASrE"}

package/dist/conduit/delivery-router.js.map

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

package/dist/conduit/index.d.ts

@@ -2,15 +2,18 @@
  * Conduit — High-level agent messaging for the CLEO ecosystem.
  *
  * Exports the ConduitClient (high-level messaging), HttpTransport
- * (HTTP polling to cloud), LocalTransport (offline SQLite), and
- * createConduit factory.
+ * (HTTP polling to cloud), LocalTransport (offline SQLite), the
+ * channel layer (LocalTuiChannelAdapter + DeliveryRouter/SessionStore),
+ * and the createConduit factory.
  *
  * @module conduit
  */
 export { ConduitClient } from './conduit-client.js';
+export { DeliveryRouter, type InboundHandler, SessionStore, } from './delivery-router.js';
 export { createConduit, resolveTransport } from './factory.js';
 export { HttpTransport } from './http-transport.js';
 export { LocalTransport } from './local-transport.js';
+export { LOCAL_TUI_CHANNEL_ID, LocalTuiChannelAdapter, type LocalTuiChannelAdapterOptions, } from './local-tui-adapter.js';
 export type { conduitCoreOps } from './ops.js';
 export { SseTransport } from './sse-transport.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/conduit/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/conduit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/conduit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,cAAc,EACd,KAAK,cAAc,EACnB,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,6BAA6B,GACnC,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/conduit/index.js

@@ -2,14 +2,17 @@
  * Conduit — High-level agent messaging for the CLEO ecosystem.
  *
  * Exports the ConduitClient (high-level messaging), HttpTransport
- * (HTTP polling to cloud), LocalTransport (offline SQLite), and
- * createConduit factory.
+ * (HTTP polling to cloud), LocalTransport (offline SQLite), the
+ * channel layer (LocalTuiChannelAdapter + DeliveryRouter/SessionStore),
+ * and the createConduit factory.
  *
  * @module conduit
  */
 export { ConduitClient } from './conduit-client.js';
+export { DeliveryRouter, SessionStore, } from './delivery-router.js';
 export { createConduit, resolveTransport } from './factory.js';
 export { HttpTransport } from './http-transport.js';
 export { LocalTransport } from './local-transport.js';
+export { LOCAL_TUI_CHANNEL_ID, LocalTuiChannelAdapter, } from './local-tui-adapter.js';
 export { SseTransport } from './sse-transport.js';
 //# sourceMappingURL=index.js.map

package/dist/conduit/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/conduit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/conduit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EACL,cAAc,EAEd,YAAY,GACb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GAEvB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/conduit/local-tui-adapter.d.ts

@@ -0,0 +1,89 @@
+/**
+ * LocalTuiChannelAdapter — the first reference {@link ChannelAdapter} (T11952).
+ *
+ * A fully-offline, daemon-OFF terminal channel that rides the EXISTING conduit
+ * {@link Transport} (the project-local `LocalTransport` over conduit.db). It
+ * needs no network and no platform credential: the single local operator on the
+ * other end of stdin/stdout is treated as a verified sender.
+ *
+ * The adapter translates between the channel-native surface and the normalized
+ * {@link InboundMsg} / {@link OutboundReply} shapes the {@link DeliveryRouter}
+ * consumes. It does NOT reinvent the transport — every wire operation delegates
+ * to the injected {@link Transport} (push/poll/subscribe), so the SAME adapter
+ * works over `LocalTransport` in production and an in-memory transport in tests.
+ *
+ * Platform adapters (Telegram/Discord/Slack/WhatsApp — T11855) implement the
+ * same {@link ChannelAdapter} contract but are credential+network gated and are
+ * out of scope for this contained increment.
+ *
+ * @epic T11854
+ * @saga T10419
+ * @module conduit/local-tui-adapter
+ */
+import type { ChannelAdapter, ChannelConfig, ChannelHealth, InboundMsg, OutboundReply, Transport, TransportConnectConfig } from '@cleocode/contracts';
+/** Default channel id for the Local-TUI adapter. */
+export declare const LOCAL_TUI_CHANNEL_ID = "local-tui";
+/** Options for constructing a {@link LocalTuiChannelAdapter}. */
+export interface LocalTuiChannelAdapterOptions {
+    /** The transport this channel rides (e.g. conduit `LocalTransport`). */
+    transport: Transport;
+    /** Transport connect config (agentId / apiKey / apiBaseUrl). */
+    connectConfig: TransportConnectConfig;
+    /** Per-channel configuration. */
+    config?: ChannelConfig;
+    /** Channel id override (defaults to {@link LOCAL_TUI_CHANNEL_ID}). */
+    id?: string;
+}
+/**
+ * Local terminal channel adapter over a conduit {@link Transport}.
+ *
+ * @see T11952
+ */
+export declare class LocalTuiChannelAdapter implements ChannelAdapter {
+    readonly id: string;
+    readonly config: ChannelConfig;
+    private readonly transport;
+    private readonly connectConfig;
+    private status;
+    private detail;
+    private unsubscribe;
+    private queue;
+    /** Create a Local-TUI channel adapter. */
+    constructor(options: LocalTuiChannelAdapterOptions);
+    /**
+     * Connect the transport and begin buffering inbound messages.
+     *
+     * Idempotent: a second `start()` while already connected is a no-op.
+     */
+    start(): Promise<void>;
+    /** Detach the subscription, end the inbound stream, and disconnect. */
+    stop(): Promise<void>;
+    /**
+     * Stream inbound messages as they arrive on the transport.
+     *
+     * Yields each {@link InboundMsg} until {@link LocalTuiChannelAdapter.stop}
+     * ends the iterator. When the transport lacks `subscribe()`, falls back to a
+     * single drain of `poll()` so the channel is still usable.
+     */
+    receive(): AsyncIterable<InboundMsg>;
+    /**
+     * Send a reply back to the channel over the transport.
+     *
+     * @param reply - The reply. The destination session resolves from
+     *   `reply.sessionKey` then `config.homeChannel` then the default TTY session.
+     */
+    send(reply: OutboundReply): Promise<void>;
+    /** Sample the adapter's current health. */
+    health(): ChannelHealth;
+    /** Push a transport message onto the inbound queue (after policy filtering). */
+    private onTransportMessage;
+    /**
+     * Normalize a {@link ConduitMessage} into an {@link InboundMsg}, applying the
+     * channel's allowlist + require-mention policy. Returns `undefined` when the
+     * message is filtered out.
+     */
+    private toInbound;
+    /** Whether the message content mentions the connected agent id. */
+    private mentionsAgent;
+}
+//# sourceMappingURL=local-tui-adapter.d.ts.map

package/dist/conduit/local-tui-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-tui-adapter.d.ts","sourceRoot":"","sources":["../../src/conduit/local-tui-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,aAAa,EAGb,UAAU,EACV,aAAa,EACb,SAAS,EACT,sBAAsB,EACvB,MAAM,qBAAqB,CAAC;AAE7B,oDAAoD;AACpD,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAKhD,iEAAiE;AACjE,MAAM,WAAW,6BAA6B;IAC5C,wEAAwE;IACxE,SAAS,EAAE,SAAS,CAAC;IACrB,gEAAgE;IAChE,aAAa,EAAE,sBAAsB,CAAC;IACtC,iCAAiC;IACjC,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,sEAAsE;IACtE,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAkDD;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyB;IACvD,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,WAAW,CAA2B;IAC9C,OAAO,CAAC,KAAK,CAAuC;IAEpD,0CAA0C;gBAC9B,OAAO,EAAE,6BAA6B;IAOlD;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAsB5B,uEAAuE;IACjE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B;;;;;;OAMG;IACI,OAAO,IAAI,aAAa,CAAC,UAAU,CAAC;IAuB3C;;;;;OAKG;IACG,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAY/C,2CAA2C;IAC3C,MAAM,IAAI,aAAa;IAUvB,gFAAgF;IAChF,OAAO,CAAC,kBAAkB;IAO1B;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAmBjB,mEAAmE;IACnE,OAAO,CAAC,aAAa;CAGtB"}

package/dist/conduit/local-tui-adapter.js

@@ -0,0 +1,225 @@
+/**
+ * LocalTuiChannelAdapter — the first reference {@link ChannelAdapter} (T11952).
+ *
+ * A fully-offline, daemon-OFF terminal channel that rides the EXISTING conduit
+ * {@link Transport} (the project-local `LocalTransport` over conduit.db). It
+ * needs no network and no platform credential: the single local operator on the
+ * other end of stdin/stdout is treated as a verified sender.
+ *
+ * The adapter translates between the channel-native surface and the normalized
+ * {@link InboundMsg} / {@link OutboundReply} shapes the {@link DeliveryRouter}
+ * consumes. It does NOT reinvent the transport — every wire operation delegates
+ * to the injected {@link Transport} (push/poll/subscribe), so the SAME adapter
+ * works over `LocalTransport` in production and an in-memory transport in tests.
+ *
+ * Platform adapters (Telegram/Discord/Slack/WhatsApp — T11855) implement the
+ * same {@link ChannelAdapter} contract but are credential+network gated and are
+ * out of scope for this contained increment.
+ *
+ * @epic T11854
+ * @saga T10419
+ * @module conduit/local-tui-adapter
+ */
+/** Default channel id for the Local-TUI adapter. */
+export const LOCAL_TUI_CHANNEL_ID = 'local-tui';
+/** Default session key used when no explicit thread is supplied (single TTY session). */
+const DEFAULT_SESSION_KEY = 'tui';
+/**
+ * A bounded async queue that lets a push-style transport subscription be
+ * consumed as a pull-style {@link AsyncIterable}.
+ *
+ * @internal
+ */
+class MessageQueue {
+    buffer = [];
+    waiters = [];
+    closed = false;
+    /** Enqueue a value (or hand it directly to a waiting consumer). */
+    push(value) {
+        if (this.closed)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter({ value, done: false });
+        }
+        else {
+            this.buffer.push(value);
+        }
+    }
+    /** Close the queue: pending and future consumers receive `done`. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        let waiter = this.waiters.shift();
+        while (waiter) {
+            waiter({ value: undefined, done: true });
+            waiter = this.waiters.shift();
+        }
+    }
+    /** Pull the next value, awaiting one if the buffer is empty. */
+    next() {
+        const buffered = this.buffer.shift();
+        if (buffered !== undefined) {
+            return Promise.resolve({ value: buffered, done: false });
+        }
+        if (this.closed) {
+            return Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+}
+/**
+ * Local terminal channel adapter over a conduit {@link Transport}.
+ *
+ * @see T11952
+ */
+export class LocalTuiChannelAdapter {
+    id;
+    config;
+    transport;
+    connectConfig;
+    status = 'disconnected';
+    detail;
+    unsubscribe;
+    queue;
+    /** Create a Local-TUI channel adapter. */
+    constructor(options) {
+        this.transport = options.transport;
+        this.connectConfig = options.connectConfig;
+        this.id = options.id ?? LOCAL_TUI_CHANNEL_ID;
+        this.config = options.config ?? {};
+    }
+    /**
+     * Connect the transport and begin buffering inbound messages.
+     *
+     * Idempotent: a second `start()` while already connected is a no-op.
+     */
+    async start() {
+        if (this.status === 'connected')
+            return;
+        try {
+            await this.transport.connect(this.connectConfig);
+            if (this.transport.subscribe) {
+                this.queue = new MessageQueue();
+                this.unsubscribe = this.transport.subscribe((m) => this.onTransportMessage(m));
+                this.status = 'connected';
+            }
+            else {
+                // No real-time subscription — the channel still functions via poll(),
+                // but inbound streaming is degraded (no queue: receive() drains poll()).
+                this.queue = undefined;
+                this.status = 'degraded';
+                this.detail = 'transport has no subscribe(); receive() falls back to poll()';
+            }
+        }
+        catch (err) {
+            this.status = 'error';
+            this.detail = err instanceof Error ? err.message : String(err);
+            throw err;
+        }
+    }
+    /** Detach the subscription, end the inbound stream, and disconnect. */
+    async stop() {
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        this.queue?.close();
+        this.queue = undefined;
+        await this.transport.disconnect();
+        this.status = 'disconnected';
+        this.detail = undefined;
+    }
+    /**
+     * Stream inbound messages as they arrive on the transport.
+     *
+     * Yields each {@link InboundMsg} until {@link LocalTuiChannelAdapter.stop}
+     * ends the iterator. When the transport lacks `subscribe()`, falls back to a
+     * single drain of `poll()` so the channel is still usable.
+     */
+    async *receive() {
+        if (this.status !== 'connected' && this.status !== 'degraded') {
+            throw new Error(`LocalTuiChannelAdapter.receive: channel "${this.id}" not started`);
+        }
+        // Degraded path: no real-time subscription — drain what poll() returns now.
+        if (!this.queue) {
+            const polled = await this.transport.poll();
+            for (const m of polled) {
+                const inbound = this.toInbound(m);
+                if (inbound)
+                    yield inbound;
+            }
+            return;
+        }
+        const queue = this.queue;
+        for (;;) {
+            const result = await queue.next();
+            if (result.done)
+                return;
+            yield result.value;
+        }
+    }
+    /**
+     * Send a reply back to the channel over the transport.
+     *
+     * @param reply - The reply. The destination session resolves from
+     *   `reply.sessionKey` then `config.homeChannel` then the default TTY session.
+     */
+    async send(reply) {
+        if (this.status !== 'connected' && this.status !== 'degraded') {
+            throw new Error(`LocalTuiChannelAdapter.send: channel "${this.id}" not started`);
+        }
+        const sessionKey = reply.sessionKey ?? this.config.homeChannel ?? DEFAULT_SESSION_KEY;
+        // Reply is addressed back to the connected operator id; the conversation is
+        // keyed by sessionKey so the originating thread is preserved.
+        await this.transport.push(this.connectConfig.agentId, reply.content, {
+            conversationId: sessionKey,
+        });
+    }
+    /** Sample the adapter's current health. */
+    health() {
+        return {
+            channelId: this.id,
+            status: this.status,
+            transport: this.transport.name,
+            detail: this.detail,
+            checkedAt: new Date().toISOString(),
+        };
+    }
+    /** Push a transport message onto the inbound queue (after policy filtering). */
+    onTransportMessage(message) {
+        const inbound = this.toInbound(message);
+        if (inbound) {
+            this.queue?.push(inbound);
+        }
+    }
+    /**
+     * Normalize a {@link ConduitMessage} into an {@link InboundMsg}, applying the
+     * channel's allowlist + require-mention policy. Returns `undefined` when the
+     * message is filtered out.
+     */
+    toInbound(message) {
+        const allowed = this.config.allowedUsers;
+        if (allowed && allowed.length > 0 && !allowed.includes(message.from)) {
+            return undefined;
+        }
+        if (this.config.requireMention && !this.mentionsAgent(message.content)) {
+            return undefined;
+        }
+        return {
+            id: message.id,
+            channelId: this.id,
+            from: message.from,
+            content: message.content,
+            sessionKey: message.threadId ?? this.config.homeChannel ?? DEFAULT_SESSION_KEY,
+            timestamp: message.timestamp,
+            payload: message.payload,
+        };
+    }
+    /** Whether the message content mentions the connected agent id. */
+    mentionsAgent(content) {
+        return content.includes(`@${this.connectConfig.agentId}`);
+    }
+}
+//# sourceMappingURL=local-tui-adapter.js.map

package/dist/conduit/local-tui-adapter.js.map

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

package/dist/config/config-repair.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Config file repair — crash-safe restore from backup (Amendment 1, T11997).
+ *
+ * Checks a JSON config file for parse failures.  When the live file is
+ * corrupt, the routine:
+ *
+ *   1. Quarantines the corrupt file beside the target (`.corrupt-<iso>`).
+ *   2. Scans available backup snapshots for the NEWEST valid (parseable) candidate.
+ *   3. Restores the best candidate atomically (tmp-rename) only when JSON parse
+ *      fails AND no active write window is detected.
+ *   4. Appends a structured audit record to `.cleo/audit/config-repair.jsonl`
+ *      that the `cleo health` surface can consume.
+ *
+ * Key invariants (Amendment 1):
+ *   - Never silently restore a stale backup — always quarantine first, then
+ *     restore the newest valid candidate.
+ *   - Restore only when `JSON.parse` fails on the live file (not merely on
+ *     schema drift).
+ *   - A `.tmp` survivor from a previously interrupted write (write-file-atomic
+ *     pattern) takes priority over numbered backups when it is both newer and
+ *     valid JSON.
+ *
+ * @task T11997
+ * @epic T11992
+ */
+/** Outcome of a {@link repairConfigFile} call. */
+export type ConfigRepairOutcome = 'healthy' | 'restored-from-backup' | 'restored-from-tmp' | 'quarantined-no-candidate' | 'skipped-active-write';
+/** Structured result of {@link repairConfigFile}. */
+export interface ConfigRepairResult {
+    /** What happened. */
+    readonly outcome: ConfigRepairOutcome;
+    /** Absolute path to the config file that was checked/restored. */
+    readonly configPath: string;
+    /** Absolute path to the backup used for restore (when applicable). */
+    readonly restoredFrom?: string;
+    /** Absolute path to the quarantine file (when a corrupt file was renamed). */
+    readonly quarantinedTo?: string;
+    /** Human-readable detail. */
+    readonly detail: string;
+}
+/**
+ * Check and optionally repair a JSON config file.
+ *
+ * Safe to call on config paths that do not yet exist — returns `'healthy'`
+ * immediately when the file is absent (a missing file is not a corrupt file).
+ *
+ * @param configPath  - Absolute path to the config JSON file to check.
+ * @param backupDir   - Directory containing numbered `.1`, `.2`, … backups.
+ *                      Pass `null` to skip backup-based restore.
+ * @param cwd         - Project root for audit-log path resolution.
+ * @returns Structured {@link ConfigRepairResult}.
+ *
+ * @example
+ * ```ts
+ * import { repairConfigFile } from '@cleocode/core/config/config-repair';
+ *
+ * const result = await repairConfigFile(
+ *   '/home/user/.local/share/cleo/config.json',
+ *   '/home/user/.local/share/cleo/backups',
+ *   '/home/user/projects/myapp',
+ * );
+ * if (result.outcome === 'restored-from-backup') {
+ *   console.log(`Restored from ${result.restoredFrom}`);
+ * }
+ * ```
+ *
+ * @task T11997
+ */
+export declare function repairConfigFile(configPath: string, backupDir: string | null, cwd: string): Promise<ConfigRepairResult>;
+//# sourceMappingURL=config-repair.d.ts.map

package/dist/config/config-repair.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-repair.d.ts","sourceRoot":"","sources":["../../src/config/config-repair.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAQH,kDAAkD;AAClD,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,sBAAsB,GACtB,mBAAmB,GACnB,0BAA0B,GAC1B,sBAAsB,CAAC;AAE3B,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,qBAAqB;IACrB,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AA0DD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,kBAAkB,CAAC,CAqJ7B"}