@interactive-inc/claude-funnel 0.8.0 → 0.8.1

package/dist/engine/settings/settings-schema.d.ts

@@ -0,0 +1,132 @@
+import { z } from "zod";
+/**
+ * Routing mode when multiple WS clients are subscribed to the same channel.
+ *
+ * - `fanout` (default): every connected client receives every event. Right when each
+ *   subscriber has its own job (e.g., TUI mirrors, distinct Claude profiles each running
+ *   their own pipeline against the same source).
+ * - `exclusive`: each event is delivered to exactly one connected client, picked
+ *   round-robin per channel. Right when subscribers are interchangeable workers and you
+ *   want each event handled once. Tap=all clients (TUI dashboard) always receive,
+ *   regardless of mode, so they can passively observe.
+ */
+export declare const channelDeliveryModeSchema: z.ZodEnum<{
+    fanout: "fanout";
+    exclusive: "exclusive";
+}>;
+export type ChannelDeliveryMode = z.infer<typeof channelDeliveryModeSchema>;
+export declare const channelConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    delivery: z.ZodDefault<z.ZodEnum<{
+        fanout: "fanout";
+        exclusive: "exclusive";
+    }>>;
+    connectors: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        type: z.ZodLiteral<"slack">;
+        botToken: z.ZodString;
+        appToken: z.ZodString;
+        createdAt: z.ZodOptional<z.ZodString>;
+        updatedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        type: z.ZodLiteral<"gh">;
+        pollInterval: z.ZodOptional<z.ZodNumber>;
+        createdAt: z.ZodOptional<z.ZodString>;
+        updatedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        type: z.ZodLiteral<"discord">;
+        botToken: z.ZodString;
+        createdAt: z.ZodOptional<z.ZodString>;
+        updatedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        type: z.ZodLiteral<"schedule">;
+        entries: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            cron: z.ZodString;
+            prompt: z.ZodString;
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            catchupPolicy: z.ZodDefault<z.ZodEnum<{
+                latest: "latest";
+                all: "all";
+                skip: "skip";
+            }>>;
+        }, z.core.$strip>>>;
+        createdAt: z.ZodOptional<z.ZodString>;
+        updatedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "type">>>;
+}, z.core.$strip>;
+export type ChannelConfig = z.infer<typeof channelConfigSchema>;
+export declare const profileConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+    subAgent: z.ZodString;
+    channelId: z.ZodString;
+}, z.core.$strip>;
+export type ProfileConfig = z.infer<typeof profileConfigSchema>;
+export declare const SETTINGS_VERSION = 1;
+export declare const settingsSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodLiteral<1>>;
+    channels: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        delivery: z.ZodDefault<z.ZodEnum<{
+            fanout: "fanout";
+            exclusive: "exclusive";
+        }>>;
+        connectors: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            type: z.ZodLiteral<"slack">;
+            botToken: z.ZodString;
+            appToken: z.ZodString;
+            createdAt: z.ZodOptional<z.ZodString>;
+            updatedAt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            type: z.ZodLiteral<"gh">;
+            pollInterval: z.ZodOptional<z.ZodNumber>;
+            createdAt: z.ZodOptional<z.ZodString>;
+            updatedAt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            type: z.ZodLiteral<"discord">;
+            botToken: z.ZodString;
+            createdAt: z.ZodOptional<z.ZodString>;
+            updatedAt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            type: z.ZodLiteral<"schedule">;
+            entries: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                cron: z.ZodString;
+                prompt: z.ZodString;
+                enabled: z.ZodDefault<z.ZodBoolean>;
+                catchupPolicy: z.ZodDefault<z.ZodEnum<{
+                    latest: "latest";
+                    all: "all";
+                    skip: "skip";
+                }>>;
+            }, z.core.$strip>>>;
+            createdAt: z.ZodOptional<z.ZodString>;
+            updatedAt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>], "type">>>;
+    }, z.core.$strip>>>;
+    profiles: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        path: z.ZodString;
+        subAgent: z.ZodString;
+        channelId: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type Settings = z.infer<typeof settingsSchema>;

package/dist/engine/settings/settings-store.d.ts

@@ -0,0 +1,18 @@
+import { FunnelFileSystem } from "../fs/file-system";
+import { FunnelSettingsReader } from "./settings-reader";
+import type { Settings } from "./settings-schema";
+export declare const FUNNEL_DIR: string;
+export declare const SETTINGS_PATH: string;
+type Deps = {
+    path?: string;
+    fs?: FunnelFileSystem;
+};
+export declare class FunnelSettingsStore extends FunnelSettingsReader {
+    private readonly path;
+    private readonly fs;
+    constructor(deps?: Deps);
+    read(): Settings;
+    private looksLikeLegacy;
+    write(settings: Settings): void;
+}
+export {};

package/dist/engine/time/clock.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Time boundary. Default NodeFunnelClock returns `new Date()`; MemoryFunnelClock
+ * is settable and `advance(ms)`-able for deterministic schedule / timeout tests.
+ */
+export declare abstract class FunnelClock {
+    abstract now(): Date;
+    millis(): number;
+    iso(): string;
+}

package/dist/engine/time/memory-clock.d.ts

@@ -0,0 +1,12 @@
+import { FunnelClock } from "./clock";
+type Props = {
+    start?: Date;
+};
+export declare class MemoryFunnelClock extends FunnelClock {
+    private current;
+    constructor(props?: Props);
+    now(): Date;
+    set(date: Date): void;
+    advance(ms: number): void;
+}
+export {};

package/dist/engine/time/node-clock.d.ts

@@ -0,0 +1,4 @@
+import { FunnelClock } from "./clock";
+export declare class NodeFunnelClock extends FunnelClock {
+    now(): Date;
+}

package/dist/funnel.d.ts

@@ -0,0 +1,95 @@
+import { FunnelConnectorFactory } from "./connectors/connector-factory";
+import { FunnelChannels } from "./engine/channels/channels";
+import { FunnelClaude } from "./engine/claude/claude";
+import type { FunnelFileSystem } from "./engine/fs/file-system";
+import type { FunnelIdGenerator } from "./engine/id/id-generator";
+import { FunnelLogger } from "./engine/logger/logger";
+import { FunnelMcp } from "./engine/mcp/mcp";
+import { FunnelProcessRunner } from "./engine/process/process-runner";
+import { FunnelProfiles } from "./engine/profiles/profiles";
+import { FunnelSettingsReader } from "./engine/settings/settings-reader";
+import type { FunnelClock } from "./engine/time/clock";
+import { FunnelGateway } from "./gateway/gateway";
+import { FunnelGatewayServer } from "./gateway/gateway-server";
+import { FunnelGatewayToken } from "./gateway/gateway-token";
+import { FunnelListenersClient } from "./gateway/listeners-client";
+type Props = {
+    /** Settings persistence (channels with nested connectors / profiles). Defaults to a FunnelSettingsStore rooted at `dir`. */
+    store?: FunnelSettingsReader;
+    /** Filesystem boundary. Replace with MemoryFunnelFileSystem to sandbox all disk I/O. */
+    fs?: FunnelFileSystem;
+    /** Process runner used by gateway / claude / gh listener. Replace with MemoryFunnelProcessRunner for tests. */
+    process?: FunnelProcessRunner;
+    /** Logger flowed into every facet. Replace with MemoryFunnelLogger or NoopFunnelLogger to silence/inspect. */
+    logger?: FunnelLogger;
+    /** Clock used by schedule listener, gh poll watermarks, and gateway timeouts. */
+    clock?: FunnelClock;
+    /** ID generator for channel and connector ids. Use MemoryFunnelIdGenerator for deterministic tests. */
+    idGenerator?: FunnelIdGenerator;
+    /** Funnel home directory (settings.json + per-channel/per-connector dirs). Defaults to ~/.funnel. */
+    dir?: string;
+    /** Temp / runtime directory (gateway logs and PID adjacent files). Defaults to /tmp/funnel. */
+    tmpDir?: string;
+};
+/**
+ * Facade exposing every funnel facet as a getter.
+ *
+ * The same `Funnel` is used by the CLI, the TUI, and as a programmable library.
+ * All side-effecting boundaries (filesystem, process, logger, clock, id, paths) are
+ * injectable via `Props` — passing memory implementations gives a fully sandboxed
+ * Funnel that touches no real disk, processes, or wall-clock time.
+ *
+ * Connectors live nested inside their owning channel (channels[].connectors[]),
+ * so connector CRUD is reached via `funnel.channels.addConnector(...)` etc.
+ *
+ * @example
+ * ```ts
+ * const funnel = new Funnel({})
+ * const channel = funnel.channels.add({ name: "inbox" })
+ * funnel.channels.addConnector("inbox", { type: "slack", name: "ops", botToken, appToken })
+ * await funnel.gatewayServer({ port: 9742 }).start()
+ * ```
+ */
+export declare class Funnel {
+    private readonly props;
+    constructor(props?: Props);
+    /** Settings reader. If not injected, a FunnelSettingsStore rooted at `dir` is created. */
+    get store(): FunnelSettingsReader;
+    /** Process runner boundary. Defaults to NodeFunnelProcessRunner. */
+    get process(): FunnelProcessRunner;
+    /** Logger boundary. Defaults to NodeFunnelLogger. */
+    get logger(): FunnelLogger;
+    /** Pure factory that constructs per-type listeners and adapters from connector configs. */
+    get factory(): FunnelConnectorFactory;
+    /** Channel CRUD + nested connector CRUD + schedule entries + listener/adapter dispatch. */
+    get channels(): FunnelChannels;
+    /** Launch profiles (named presets for `fnl claude`: path + sub-agent + channel id). */
+    get profiles(): FunnelProfiles;
+    /** funnel MCP installer (writes/removes `.mcp.json` entries in target repos). */
+    get mcp(): FunnelMcp;
+    /** Launch Claude Code with a channel injected via env, MCP installed, gateway ensured. */
+    get claude(): FunnelClaude;
+    /** Gateway daemon controller (PID-file, start/stop the separate `bun daemon.ts` process). */
+    get gateway(): FunnelGateway;
+    /** Read / generate the daemon's gateway token (mode 0600 file under `dir`). */
+    get gatewayToken(): FunnelGatewayToken;
+    /**
+     * HTTP client for listener operations on the running gateway daemon.
+     * Returns `{ state: "offline" }` when the daemon is offline so hot-reload
+     * paths stay write-only without parsing strings.
+     */
+    get listeners(): FunnelListenersClient;
+    /**
+     * In-process gateway server. Unlike `gateway.start()` (which spawns a daemon),
+     * this returns a class that runs `Bun.serve` + listeners inside the current process —
+     * useful for tests, embedding, or custom hosts.
+     */
+    gatewayServer(options?: {
+        port?: number;
+        logDir?: string;
+        killCompetingSlack?: boolean;
+        /** Override the auth token. Defaults to the persisted gateway.token. Pass "" to disable auth (tests). */
+        token?: string;
+    }): FunnelGatewayServer;
+}
+export {};

package/dist/gateway/auth-middleware.d.ts

@@ -0,0 +1,14 @@
+import type { MiddlewareHandler } from "hono";
+import type { Env } from "./factory";
+type Deps = {
+    expected: string;
+};
+/**
+ * Verifies `Authorization: Bearer <token>` against the daemon's gateway token.
+ * Mounted on the routes that mutate listener state or expose detailed status.
+ * `/health` is intentionally left unauthenticated so the daemon manager can
+ * probe liveness without needing the token.
+ */
+export declare const requireBearerToken: (deps: Deps) => MiddlewareHandler<Env>;
+export declare const constantTimeEqual: (a: string, b: string) => boolean;
+export {};

package/dist/gateway/broadcaster.d.ts

@@ -0,0 +1,122 @@
+import type { ServerWebSocket } from "bun";
+import { FunnelLogger } from "../engine/logger/logger";
+type ClientData = {
+    /** Stable channel id (uuid) that the WS client subscribed to. */
+    channel: string;
+    /** Human-facing channel name resolved at upgrade time, kept for log readability. */
+    channelName?: string | null;
+    /** Connector names belonging to that channel; used by tap-all replay filtering. */
+    connectors: string[];
+    tapAll?: boolean;
+    /** Routing mode resolved from channel config at upgrade time. Defaults to fanout. */
+    delivery?: "fanout" | "exclusive";
+};
+export type BroadcastEvent = {
+    content: string;
+    meta?: Record<string, string>;
+};
+export type ReplayableEvent = BroadcastEvent & {
+    offset: number;
+};
+export type BroadcastSubscriber = (event: ReplayableEvent) => void;
+/**
+ * Optional persistent replay source. Wired in by the gateway-server with
+ * `FunnelEventStore` (SQLite-backed) so reconnects across daemon restarts
+ * can recover events older than the in-memory buffer via an indexed
+ * `seq > since` range scan.
+ */
+type ReplaySource = {
+    loadSince(since: number): ReplayableEvent[];
+};
+type Deps = {
+    logger?: FunnelLogger;
+    maxBufferedBytes?: number;
+    now?: () => number;
+    /** Number of recent events kept in the in-memory replay buffer. */
+    replayBufferSize?: number;
+    /** Hard byte cap on replay buffer payloads. Older events are evicted FIFO until under this cap. */
+    replayBufferMaxBytes?: number;
+    /** Persistent replay source consulted when the in-memory buffer cannot satisfy `since`. */
+    persistentReplay?: ReplaySource;
+};
+type BroadcasterMetrics = {
+    clients: number;
+    subscribers: number;
+    eventsBroadcast: number;
+    droppedSlowClients: number;
+    lastBroadcastAt: string | null;
+    /** Latest emitted offset. Clients can `?since=<offset>` to ask for events strictly after this point. */
+    latestOffset: number;
+    /** Oldest offset still held in the replay buffer. Older values cannot be replayed and trigger a full resync. */
+    oldestReplayableOffset: number | null;
+};
+/**
+ * In-process pub/sub for connector events.
+ *
+ * Two outbound paths:
+ *   - WS clients connected via the gateway's `/ws` endpoint, scoped per channel
+ *   - In-process subscribers registered via `subscribe()` (programmable API)
+ *
+ * Backpressure: if a WS client's `bufferedAmount` exceeds `maxBufferedBytes`
+ * (default 1 MiB), the client is closed with code 1009 and dropped from the
+ * registry to keep one slow consumer from blocking the daemon.
+ *
+ * Replay: every emitted event gets a strictly increasing `offset`. The latest
+ * `replayBufferSize` events are kept in memory; reconnecting WS clients can
+ * pass `?since=<offset>` and the broadcaster resends matching events before
+ * resuming the live stream. The in-memory ring covers short reconnects;
+ * older history is served from the SQLite event store wired in as
+ * `persistentReplay`.
+ */
+export declare class FunnelBroadcaster {
+    private readonly clients;
+    private readonly subscribers;
+    private readonly logger;
+    private readonly maxBufferedBytes;
+    private readonly now;
+    private readonly replayBufferSize;
+    private readonly replayBufferMaxBytes;
+    private readonly replayBuffer;
+    private readonly persistentReplay;
+    private readonly exclusiveCursor;
+    private replayBufferBytes;
+    private eventsBroadcast;
+    private droppedSlowClients;
+    private lastBroadcastAt;
+    private latestOffset;
+    constructor(deps?: Deps);
+    getMetrics(): BroadcasterMetrics;
+    /**
+     * Returns events with offset > since, filtered by the connector subscription
+     * rules of `data`. Used at WS upgrade time when the client passes `?since=<offset>`.
+     *
+     * Two-tier lookup:
+     *   1. The in-memory ring buffer (covers short reconnects, last `replayBufferSize` events).
+     *   2. If `since` predates the oldest in-memory entry and a persistent replay source
+     *      is wired in (SQLite), the gap is filled from disk. This covers reconnects across
+     *      daemon restarts where the in-memory buffer was lost.
+     *
+     * Result is sorted ascending by offset and de-duplicated against the in-memory buffer.
+     */
+    replaySince(since: number, data: ClientData): ReplayableEvent[];
+    private matchesClient;
+    /**
+     * Returns the list of WS clients that should receive `event`. Tap=all clients always
+     * receive (passive observation). For each per-channel group:
+     *   - fanout → every matching client receives
+     *   - exclusive → exactly one client receives, picked round-robin per channel
+     */
+    private pickRecipients;
+    addClient(ws: ServerWebSocket<unknown>, data: ClientData): void;
+    removeClient(ws: ServerWebSocket<unknown>): void;
+    getClientCount(): number;
+    listChannels(): {
+        channel: string;
+        connectors: string[];
+    }[];
+    subscribe(handler: BroadcastSubscriber): () => void;
+    broadcast(content: string, meta?: Record<string, string>): ReplayableEvent;
+    /** Forward-seed the offset counter (used at startup from the persisted event store). */
+    seedLatestOffset(offset: number): void;
+}
+export {};

package/dist/gateway/daemon.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};