@interactive-inc/claude-funnel 0.7.1 → 0.8.1

package/lib/gateway/listener-supervisor.ts

@@ -0,0 +1,339 @@
+import type { ConnectorConfig } from "@/connectors/connector-config-schema"
+import type { FunnelConnectorListener } from "@/connectors/connector-listener"
+import type { ChannelConnectorView } from "@/engine/channels/channels"
+import { FunnelLogger } from "@/engine/logger/logger"
+import { NodeFunnelLogger } from "@/engine/logger/node-logger"
+
+type ConnectorRegistry = {
+  listAllConnectors(): ChannelConnectorView[]
+  createListener(
+    channelName: string,
+    connectorName: string,
+  ): { config: ConnectorConfig; channelId: string; listener: FunnelConnectorListener } | null
+}
+
+type SupervisorNotify = (
+  channelName: string,
+  connectorName: string,
+  content: string,
+  meta?: Record<string, string>,
+) => Promise<void>
+
+type RunningEntry = {
+  config: ConnectorConfig
+  channelName: string
+  channelId: string
+  listener: FunnelConnectorListener
+}
+
+type ListenerStats = {
+  events: number
+  errors: number
+  failureCount: number
+  lastEventAt: string | null
+}
+
+type Deps = {
+  channels: ConnectorRegistry
+  notify: SupervisorNotify
+  logger?: FunnelLogger
+  healthCheckIntervalMs?: number
+  maxBackoffMs?: number
+  sleep?: (ms: number) => Promise<void>
+  now?: () => number
+}
+
+const defaultLogger = new NodeFunnelLogger()
+const DEFAULT_HEALTH_INTERVAL_MS = 30_000
+const DEFAULT_MAX_BACKOFF_MS = 60_000
+
+const defaultSleep = (ms: number): Promise<void> =>
+  new Promise((r) => {
+    setTimeout(r, ms)
+  })
+
+type ListenerEntryStatus = {
+  channelName: string
+  channelId: string
+  name: string
+  type: ConnectorConfig["type"]
+  alive: boolean
+  events: number
+  errors: number
+  failureCount: number
+  lastEventAt: string | null
+}
+
+/**
+ * Owns the running listener instances and their lifecycle.
+ *
+ * Lives in the gateway process and is the only place that calls
+ * `listener.start()` / `listener.stop()`. Each entry is keyed by
+ * `${channelName}/${connectorName}` so the same connector name can exist in
+ * multiple channels without colliding.
+ *
+ * Periodically polls each running listener's `isAlive()` and auto-restarts
+ * dead listeners with exponential backoff (1s, 2s, 4s, ... capped). Resets
+ * the backoff counter on successful restart.
+ */
+export class FunnelListenerSupervisor {
+  private readonly channels: ConnectorRegistry
+  private readonly notify: SupervisorNotify
+  private readonly logger: FunnelLogger
+  private readonly running = new Map<string, RunningEntry>()
+  private readonly failureCounts = new Map<string, number>()
+  private readonly stats = new Map<string, ListenerStats>()
+  private readonly healthCheckIntervalMs: number
+  private readonly maxBackoffMs: number
+  private readonly sleep: (ms: number) => Promise<void>
+  private readonly now: () => number
+  private healthCheckTimer: ReturnType<typeof setInterval> | null = null
+  private healthCheckInFlight = false
+
+  constructor(deps: Deps) {
+    this.channels = deps.channels
+    this.notify = deps.notify
+    this.logger = deps.logger ?? defaultLogger
+    this.healthCheckIntervalMs = deps.healthCheckIntervalMs ?? DEFAULT_HEALTH_INTERVAL_MS
+    this.maxBackoffMs = deps.maxBackoffMs ?? DEFAULT_MAX_BACKOFF_MS
+    this.sleep = deps.sleep ?? defaultSleep
+    this.now = deps.now ?? (() => Date.now())
+  }
+
+  static keyOf(channelName: string, connectorName: string): string {
+    return `${channelName}/${connectorName}`
+  }
+
+  isRunning(channelName: string, connectorName: string): boolean {
+    return this.running.has(FunnelListenerSupervisor.keyOf(channelName, connectorName))
+  }
+
+  list(): ListenerEntryStatus[] {
+    return [...this.running.entries()].map(([key, entry]) => {
+      const stats = this.stats.get(key)
+
+      return {
+        channelName: entry.channelName,
+        channelId: entry.channelId,
+        name: entry.config.name,
+        type: entry.config.type,
+        alive: entry.listener.isAlive(),
+        events: stats?.events ?? 0,
+        errors: stats?.errors ?? 0,
+        failureCount: this.failureCounts.get(key) ?? 0,
+        lastEventAt: stats?.lastEventAt ?? null,
+      }
+    })
+  }
+
+  async start(
+    channelName: string,
+    connectorName: string,
+  ): Promise<{ ok: boolean; reason?: string }> {
+    const key = FunnelListenerSupervisor.keyOf(channelName, connectorName)
+
+    if (this.running.has(key)) {
+      return { ok: true, reason: "already running" }
+    }
+
+    const created = this.channels.createListener(channelName, connectorName)
+
+    if (!created) {
+      return {
+        ok: false,
+        reason: `connector "${connectorName}" not found in channel "${channelName}"`,
+      }
+    }
+
+    const bind = async (content: string, meta?: Record<string, string>) => {
+      try {
+        await this.notify(channelName, connectorName, content, meta)
+        this.recordEvent(key)
+      } catch (error) {
+        this.recordError(key)
+        throw error
+      }
+    }
+
+    try {
+      await created.listener.start(bind)
+      this.running.set(key, {
+        config: created.config,
+        channelName,
+        channelId: created.channelId,
+        listener: created.listener,
+      })
+      this.ensureStats(key)
+      this.logger.info(`${created.config.type} listener started`, {
+        channel: channelName,
+        connector: connectorName,
+      })
+
+      return { ok: true }
+    } catch (error) {
+      this.logger.error(`${created.config.type} listener failed to start`, {
+        channel: channelName,
+        connector: connectorName,
+        error: error instanceof Error ? error.message : String(error),
+      })
+
+      return {
+        ok: false,
+        reason: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+
+  async stop(
+    channelName: string,
+    connectorName: string,
+  ): Promise<{ ok: boolean; reason?: string }> {
+    const key = FunnelListenerSupervisor.keyOf(channelName, connectorName)
+    const entry = this.running.get(key)
+
+    if (!entry) return { ok: true, reason: "not running" }
+
+    try {
+      await entry.listener.stop()
+      this.running.delete(key)
+      this.failureCounts.delete(key)
+      this.logger.info(`${entry.config.type} listener stopped`, {
+        channel: channelName,
+        connector: connectorName,
+      })
+
+      return { ok: true }
+    } catch (error) {
+      this.logger.error(`${entry.config.type} listener failed to stop`, {
+        channel: channelName,
+        connector: connectorName,
+        error: error instanceof Error ? error.message : String(error),
+      })
+
+      return {
+        ok: false,
+        reason: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+
+  async restart(
+    channelName: string,
+    connectorName: string,
+  ): Promise<{ ok: boolean; reason?: string }> {
+    const stopped = await this.stop(channelName, connectorName)
+
+    if (!stopped.ok) return stopped
+
+    return await this.start(channelName, connectorName)
+  }
+
+  async startAll(): Promise<void> {
+    const all = this.channels.listAllConnectors()
+
+    for (const view of all) {
+      await this.start(view.channelName, view.name)
+    }
+
+    this.startHealthCheck()
+  }
+
+  async stopAll(): Promise<void> {
+    this.stopHealthCheck()
+
+    for (const [, entry] of [...this.running.entries()]) {
+      await this.stop(entry.channelName, entry.config.name)
+    }
+  }
+
+  private ensureStats(key: string): ListenerStats {
+    const existing = this.stats.get(key)
+
+    if (existing) return existing
+
+    const fresh: ListenerStats = { events: 0, errors: 0, failureCount: 0, lastEventAt: null }
+
+    this.stats.set(key, fresh)
+
+    return fresh
+  }
+
+  private recordEvent(key: string): void {
+    const stats = this.ensureStats(key)
+
+    stats.events += 1
+    stats.lastEventAt = new Date(this.now()).toISOString()
+  }
+
+  private recordError(key: string): void {
+    this.ensureStats(key).errors += 1
+  }
+
+  private startHealthCheck(): void {
+    if (this.healthCheckTimer) return
+
+    this.healthCheckTimer = setInterval(() => {
+      void this.runHealthCheck()
+    }, this.healthCheckIntervalMs)
+
+    this.healthCheckTimer.unref()
+  }
+
+  private stopHealthCheck(): void {
+    if (!this.healthCheckTimer) return
+
+    clearInterval(this.healthCheckTimer)
+    this.healthCheckTimer = null
+  }
+
+  private async runHealthCheck(): Promise<void> {
+    if (this.healthCheckInFlight) return
+
+    this.healthCheckInFlight = true
+
+    try {
+      for (const [key, entry] of [...this.running.entries()]) {
+        if (entry.listener.isAlive()) {
+          this.failureCounts.delete(key)
+          continue
+        }
+
+        await this.recoverDead(entry.channelName, entry.config.name, entry.config.type)
+      }
+    } finally {
+      this.healthCheckInFlight = false
+    }
+  }
+
+  private async recoverDead(
+    channelName: string,
+    connectorName: string,
+    type: ConnectorConfig["type"],
+  ): Promise<void> {
+    const key = FunnelListenerSupervisor.keyOf(channelName, connectorName)
+    const failureCount = this.failureCounts.get(key) ?? 0
+    const backoffMs = Math.min(1000 * 2 ** failureCount, this.maxBackoffMs)
+
+    this.logger.warn(`${type} listener unhealthy, restarting`, {
+      channel: channelName,
+      connector: connectorName,
+      attempt: failureCount + 1,
+      backoffMs,
+    })
+
+    await this.stop(channelName, connectorName)
+    await this.sleep(backoffMs)
+
+    const result = await this.start(channelName, connectorName)
+
+    if (result.ok) {
+      this.failureCounts.delete(key)
+      this.logger.info(`${type} listener recovered`, {
+        channel: channelName,
+        connector: connectorName,
+      })
+    } else {
+      this.failureCounts.set(key, failureCount + 1)
+    }
+  }
+}

package/lib/gateway/listeners-client.ts

@@ -0,0 +1,128 @@
+import { z } from "zod"
+
+type Deps = {
+  port: number
+  isDaemonRunning: () => boolean
+  /** Returns the daemon's gateway token, or null if unavailable. Sent as `Authorization: Bearer`. */
+  getToken?: () => string | null
+}
+
+const listenerEntrySchema = z.object({
+  channelName: z.string(),
+  channelId: z.string(),
+  name: z.string(),
+  type: z.string(),
+  alive: z.boolean(),
+})
+
+const listenersResponseSchema = z.object({
+  listeners: z.array(listenerEntrySchema),
+})
+
+const opErrorBodySchema = z.object({
+  reason: z.string().optional(),
+})
+
+export type ListenerEntry = z.infer<typeof listenerEntrySchema>
+
+export type ListenerOpResult =
+  | { state: "ok" }
+  | { state: "offline" }
+  | { state: "error"; reason: string }
+
+export type ListListenersResult =
+  | { state: "ok"; listeners: ListenerEntry[] }
+  | { state: "offline" }
+  | { state: "error"; reason: string }
+
+const OFFLINE: ListenerOpResult = { state: "offline" }
+
+/**
+ * HTTP client for listener operations on a running gateway daemon.
+ *
+ * Returns `{ state: "offline" }` when the daemon isn't running so callers
+ * (CLI hot-reload paths) can treat that as a no-op without parsing strings.
+ * Pair this with `FunnelGateway` (process control) for the full picture.
+ */
+export class FunnelListenersClient {
+  private readonly port: number
+  private readonly isDaemonRunning: () => boolean
+  private readonly getToken: () => string | null
+
+  constructor(deps: Deps) {
+    this.port = deps.port
+    this.isDaemonRunning = deps.isDaemonRunning
+    this.getToken = deps.getToken ?? (() => null)
+    Object.freeze(this)
+  }
+
+  async list(): Promise<ListListenersResult> {
+    if (!this.isDaemonRunning()) return { state: "offline" }
+
+    try {
+      const res = await fetch(`http://localhost:${this.port}/listeners`, {
+        headers: this.authHeaders(),
+      })
+
+      if (!res.ok) return { state: "error", reason: `HTTP ${res.status}` }
+
+      const parsed = listenersResponseSchema.safeParse(await res.json())
+
+      if (!parsed.success) {
+        return { state: "error", reason: "malformed daemon response" }
+      }
+
+      return { state: "ok", listeners: parsed.data.listeners }
+    } catch (error) {
+      return { state: "error", reason: error instanceof Error ? error.message : String(error) }
+    }
+  }
+
+  async start(channelName: string, connectorName: string): Promise<ListenerOpResult> {
+    if (!this.isDaemonRunning()) return OFFLINE
+
+    return await this.call("POST", `/listeners/${this.path(channelName, connectorName)}/start`)
+  }
+
+  async stop(channelName: string, connectorName: string): Promise<ListenerOpResult> {
+    if (!this.isDaemonRunning()) return OFFLINE
+
+    return await this.call("DELETE", `/listeners/${this.path(channelName, connectorName)}`)
+  }
+
+  async restart(channelName: string, connectorName: string): Promise<ListenerOpResult> {
+    if (!this.isDaemonRunning()) return OFFLINE
+
+    return await this.call("POST", `/listeners/${this.path(channelName, connectorName)}/restart`)
+  }
+
+  private path(channelName: string, connectorName: string): string {
+    return `${encodeURIComponent(channelName)}/${encodeURIComponent(connectorName)}`
+  }
+
+  private authHeaders(): Record<string, string> {
+    const token = this.getToken()
+
+    return token ? { authorization: `Bearer ${token}` } : {}
+  }
+
+  private async call(method: "POST" | "DELETE", path: string): Promise<ListenerOpResult> {
+    try {
+      const res = await fetch(`http://localhost:${this.port}${path}`, {
+        method,
+        headers: this.authHeaders(),
+      })
+
+      if (!res.ok) {
+        const parsed = opErrorBodySchema.safeParse(await res.json().catch(() => null))
+        const reason = parsed.success ? parsed.data.reason : undefined
+
+        return { state: "error", reason: reason ?? `HTTP ${res.status}` }
+      }
+
+      return { state: "ok" }
+    } catch (error) {
+      return { state: "error", reason: error instanceof Error ? error.message : String(error) }
+    }
+  }
+}

package/lib/gateway/resolve-daemon-script.ts

@@ -0,0 +1,26 @@
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+
+/**
+ * Locate the daemon entry script. Works in both dev (running from source)
+ * and built mode (bundled into dist/bin.js with daemon at dist/gateway/daemon.js).
+ *
+ * The candidates cover:
+ *  1. dev: this helper lives at lib/gateway/, so daemon.ts is its sibling
+ *  2. built sibling: dist/gateway/daemon.js if the helper itself ends up at dist/gateway/
+ *  3. bundled: when this helper is inlined into dist/bin.js, import.meta.dir is dist/,
+ *     and daemon.js lives at dist/gateway/daemon.js
+ */
+export const resolveDaemonScript = (): string => {
+  const candidates = [
+    resolve(import.meta.dir, "./daemon.ts"),
+    resolve(import.meta.dir, "./daemon.js"),
+    resolve(import.meta.dir, "./gateway/daemon.js"),
+  ]
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate
+  }
+
+  throw new Error(`daemon script not found (looked in ${candidates.join(", ")})`)
+}

package/lib/gateway/routes/channels.connectors.call.ts

@@ -0,0 +1,39 @@
+import { HTTPException } from "hono/http-exception"
+import { z } from "zod"
+import { factory } from "@/gateway/factory"
+import { zParam } from "@/gateway/routes/validator"
+
+const bodySchema = z.object({
+  method: z.string().min(1),
+  path: z.string().min(1),
+  body: z.unknown().optional(),
+})
+
+/**
+ * POST /channels/:channel/connectors/:connector/call
+ *
+ * Generic adapter call. Used by the funnel MCP server (running in the Claude
+ * Code process) to send replies/reactions/etc. without spawning a CLI
+ * subprocess. Mirrors the CLI's `funnel channels <c> connectors <conn> request
+ * --method=...` but with a structured JSON body and no shell.
+ */
+export const channelsConnectorsCallHandler = factory.createHandlers(
+  zParam(z.object({ channel: z.string().min(1), connector: z.string().min(1) })),
+  async (c) => {
+    const param = c.req.valid("param")
+    const raw = await c.req.json().catch(() => null)
+    const parsed = bodySchema.safeParse(raw)
+
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: parsed.error.issues[0]?.message ?? "invalid body" })
+    }
+
+    const result = await c.var.deps.channels.call(param.channel, param.connector, {
+      method: parsed.data.method,
+      path: parsed.data.path,
+      body: parsed.data.body ?? {},
+    })
+
+    return c.json({ ok: true, result })
+  },
+)

package/lib/gateway/routes/health.ts

@@ -0,0 +1,13 @@
+import { factory } from "@/gateway/factory"
+
+/** GET /health — liveness + listener registry snapshot. */
+export const healthHandler = factory.createHandlers((c) => {
+  const deps = c.var.deps
+
+  return c.json({
+    ok: true,
+    pid: deps.selfPid,
+    clients: deps.broadcaster.getClientCount(),
+    listeners: deps.supervisor.list(),
+  })
+})

package/lib/gateway/routes/index.ts

@@ -0,0 +1,24 @@
+import { factory } from "@/gateway/factory"
+import { channelsConnectorsCallHandler } from "@/gateway/routes/channels.connectors.call"
+import { healthHandler } from "@/gateway/routes/health"
+import { listenersListHandler } from "@/gateway/routes/listeners.list"
+import { listenersRestartHandler } from "@/gateway/routes/listeners.restart"
+import { listenersStartHandler } from "@/gateway/routes/listeners.start"
+import { listenersStopHandler } from "@/gateway/routes/listeners.stop"
+import { statusHandler } from "@/gateway/routes/status"
+
+/**
+ * Top-level Hono app for the gateway daemon. Mounts every HTTP endpoint flat
+ * (the WebSocket /ws upgrade is handled directly by `Bun.serve`). Deps come
+ * from the `deps` variable set by `FunnelGatewayServer`'s middleware — same
+ * shape as CLI's `c.var.funnel`.
+ */
+export const gatewayRoutes = factory
+  .createApp()
+  .get("/health", ...healthHandler)
+  .get("/status", ...statusHandler)
+  .get("/listeners", ...listenersListHandler)
+  .post("/listeners/:channel/:connector/start", ...listenersStartHandler)
+  .delete("/listeners/:channel/:connector", ...listenersStopHandler)
+  .post("/listeners/:channel/:connector/restart", ...listenersRestartHandler)
+  .post("/channels/:channel/connectors/:connector/call", ...channelsConnectorsCallHandler)

package/lib/gateway/routes/listeners.list.ts

@@ -0,0 +1,6 @@
+import { factory } from "@/gateway/factory"
+
+/** GET /listeners — running connector listeners with alive/dead status. */
+export const listenersListHandler = factory.createHandlers((c) => {
+  return c.json({ listeners: c.var.deps.supervisor.list() })
+})

package/lib/gateway/routes/listeners.restart.ts

@@ -0,0 +1,15 @@
+import { z } from "zod"
+import { factory } from "@/gateway/factory"
+import { zParam } from "@/gateway/routes/validator"
+
+/** POST /listeners/:channel/:connector/restart — stop + start a connector listener. */
+export const listenersRestartHandler = factory.createHandlers(
+  zParam(z.object({ channel: z.string().min(1), connector: z.string().min(1) })),
+  async (c) => {
+    const param = c.req.valid("param")
+
+    const result = await c.var.deps.supervisor.restart(param.channel, param.connector)
+
+    return c.json(result, result.ok ? 200 : 400)
+  },
+)

package/lib/gateway/routes/listeners.start.ts

@@ -0,0 +1,15 @@
+import { z } from "zod"
+import { factory } from "@/gateway/factory"
+import { zParam } from "@/gateway/routes/validator"
+
+/** POST /listeners/:channel/:connector/start — start a connector listener. */
+export const listenersStartHandler = factory.createHandlers(
+  zParam(z.object({ channel: z.string().min(1), connector: z.string().min(1) })),
+  async (c) => {
+    const param = c.req.valid("param")
+
+    const result = await c.var.deps.supervisor.start(param.channel, param.connector)
+
+    return c.json(result, result.ok ? 200 : 400)
+  },
+)

package/lib/gateway/routes/listeners.stop.ts

@@ -0,0 +1,15 @@
+import { z } from "zod"
+import { factory } from "@/gateway/factory"
+import { zParam } from "@/gateway/routes/validator"
+
+/** DELETE /listeners/:channel/:connector — stop a connector listener. */
+export const listenersStopHandler = factory.createHandlers(
+  zParam(z.object({ channel: z.string().min(1), connector: z.string().min(1) })),
+  async (c) => {
+    const param = c.req.valid("param")
+
+    const result = await c.var.deps.supervisor.stop(param.channel, param.connector)
+
+    return c.json(result, result.ok ? 200 : 400)
+  },
+)

package/lib/gateway/routes/route-deps.ts

@@ -0,0 +1,11 @@
+import type { FunnelChannels } from "@/engine/channels/channels"
+import type { FunnelBroadcaster } from "@/gateway/broadcaster"
+import type { FunnelListenerSupervisor } from "@/gateway/listener-supervisor"
+
+export type GatewayRouteDeps = {
+  selfPid: number
+  broadcaster: FunnelBroadcaster
+  supervisor: FunnelListenerSupervisor
+  channels: FunnelChannels
+  uptimeMs: () => number
+}

package/lib/gateway/routes/status.ts

@@ -0,0 +1,15 @@
+import { factory } from "@/gateway/factory"
+
+/** GET /status — listener registry, connected channels, and broadcaster metrics. */
+export const statusHandler = factory.createHandlers((c) => {
+  const deps = c.var.deps
+
+  return c.json({
+    ok: true,
+    pid: deps.selfPid,
+    uptimeMs: deps.uptimeMs(),
+    clients: deps.broadcaster.listChannels(),
+    listeners: deps.supervisor.list(),
+    broadcaster: deps.broadcaster.getMetrics(),
+  })
+})

package/lib/gateway/routes/validator.ts

@@ -0,0 +1,17 @@
+import { zValidator } from "@hono/zod-validator"
+import type { ZodType } from "zod"
+
+/**
+ * Path-param validator for gateway routes. On failure it answers with the same
+ * `{ ok: false, reason }` shape the listener routes already use, so
+ * `FunnelListenersClient` can surface the message without special-casing.
+ */
+export const zParam = <T extends ZodType>(schema: T) =>
+  zValidator("param", schema, (result, c) => {
+    if (result.success) return
+
+    const issue = result.error.issues[0]
+    const reason = issue ? `${issue.path.join(".")}: ${issue.message}` : "invalid request"
+
+    return c.json({ ok: false, reason }, 400)
+  })