@interactive-inc/claude-funnel 0.4.1 → 0.8.0

package/lib/connectors/connector-listener.ts

@@ -0,0 +1,20 @@
+export type NotifyFn = (content: string, meta?: Record<string, string>) => Promise<void>
+
+/**
+ * Long-lived event source for one connector.
+ *
+ * `start()` opens the underlying connection (Slack Socket Mode, Discord
+ * Gateway, GH polling, schedule tick) and pushes events through `notify`.
+ * `stop()` releases the resources so the supervisor can recreate the listener
+ * with new config without restarting the whole gateway. `isAlive()` lets the
+ * supervisor periodically health-check and auto-restart dead listeners; the
+ * default optimistic implementation is fine for poll/tick-based listeners
+ * that self-heal.
+ */
+export abstract class FunnelConnectorListener {
+  abstract start(notify: NotifyFn): Promise<void>
+  abstract stop(): Promise<void>
+  isAlive(): boolean {
+    return true
+  }
+}

package/lib/{modules/connectors/funnel-discord-adapter.ts → connectors/discord-adapter.ts}

@@ -1,10 +1,7 @@
-import {
-  FunnelConnectorAdapter,
-  type CallInput,
-} from "@/modules/connectors/funnel-connector-adapter"
-import { FunnelHttpClient } from "@/modules/http/funnel-http-client"
-import { NodeFunnelHttpClient } from "@/modules/http/node-funnel-http-client"
-import type { DiscordConnectorConfig } from "@/modules/connectors/discord-connector-schema"
+import { FunnelConnectorAdapter, type CallInput } from "@/connectors/connector-adapter"
+import { FunnelHttpClient } from "@/engine/http/http-client"
+import { NodeFunnelHttpClient } from "@/engine/http/node-http-client"
+import type { DiscordConnectorConfig } from "@/connectors/discord-connector-schema"
 
 const DISCORD_API_BASE = "https://discord.com/api/v10"
 
@@ -29,11 +26,9 @@ export class FunnelDiscordAdapter extends FunnelConnectorAdapter {
   async call(input: CallInput): Promise<unknown> {
     const method = (input.method || "GET").toUpperCase()
     const path = input.path.startsWith("/") ? input.path : `/${input.path}`
+    const body = input.body
     const hasBody =
-      input.body &&
-      typeof input.body === "object" &&
-      method !== "GET" &&
-      Object.keys(input.body as object).length > 0
+      body !== null && typeof body === "object" && method !== "GET" && Object.keys(body).length > 0
 
     const res = await this.http.fetch({
       method,

package/lib/{modules/connectors → connectors}/discord-connector-schema.ts

@@ -1,9 +1,12 @@
 import { z } from "zod"
 
 export const discordConnectorSchema = z.object({
-  type: z.literal("discord"),
+  id: z.string(),
   name: z.string(),
+  type: z.literal("discord"),
   botToken: z.string().min(10),
+  createdAt: z.string().datetime().optional(),
+  updatedAt: z.string().datetime().optional(),
 })
 
 export type DiscordConnectorConfig = z.infer<typeof discordConnectorSchema>

package/lib/connectors/discord-listener.ts

@@ -0,0 +1,111 @@
+import { Client, GatewayIntentBits, Partials } from "discord.js"
+import { FunnelConnectorListener, type NotifyFn } from "@/connectors/connector-listener"
+import { FunnelDiscordEventProcessor } from "@/connectors/discord-event-processor"
+import { FunnelLogger } from "@/engine/logger/logger"
+import { NodeFunnelLogger } from "@/engine/logger/node-logger"
+import type { DiscordConnectorConfig } from "@/connectors/discord-connector-schema"
+
+type Deps = {
+  config: DiscordConnectorConfig
+  logger?: FunnelLogger
+}
+
+const defaultLogger = new NodeFunnelLogger()
+
+export class FunnelDiscordListener extends FunnelConnectorListener {
+  private readonly config: DiscordConnectorConfig
+  private readonly logger: FunnelLogger
+  private client: Client | null = null
+
+  constructor(deps: Deps) {
+    super()
+    this.config = deps.config
+    this.logger = deps.logger ?? defaultLogger
+  }
+
+  async start(notify: NotifyFn): Promise<void> {
+    const client = new Client({
+      intents: [
+        GatewayIntentBits.Guilds,
+        GatewayIntentBits.GuildMessages,
+        GatewayIntentBits.MessageContent,
+        GatewayIntentBits.DirectMessages,
+      ],
+      partials: [Partials.Channel],
+    })
+
+    client.on("messageCreate", async (message) => {
+      const ownUserId = client.user?.id ?? ""
+      const mentionedUserIds = [...message.mentions.users.keys()]
+
+      this.logger.info("discord messageCreate", {
+        author: message.author.id,
+        authorIsBot: String(message.author.bot),
+        channelId: message.channelId,
+        guildId: message.guildId ?? "",
+        mentions: mentionedUserIds.join(","),
+        ownUserId,
+        mentioned: String(mentionedUserIds.includes(ownUserId)),
+      })
+
+      const processor = new FunnelDiscordEventProcessor({ ownUserId })
+
+      const result = processor.process({
+        authorId: message.author.id,
+        authorIsBot: message.author.bot,
+        channelId: message.channelId,
+        guildId: message.guildId,
+        mentionedUserIds,
+        raw: message.toJSON(),
+      })
+
+      if (result.skip) {
+        this.logger.info("discord skip", { reason: "bot author" })
+        return
+      }
+
+      try {
+        await notify(result.content, result.meta)
+      } catch (error) {
+        this.logger.error("discord notify error", {
+          error: error instanceof Error ? error.message : String(error),
+        })
+      }
+    })
+
+    client.on("ready", (readyClient) => {
+      this.logger.info("discord ready", {
+        userId: readyClient.user.id,
+        tag: readyClient.user.tag,
+        guilds: String(readyClient.guilds.cache.size),
+      })
+    })
+
+    client.on("error", (error) => {
+      this.logger.error("discord client error", {
+        error: error instanceof Error ? error.message : String(error),
+      })
+    })
+
+    await client.login(this.config.botToken)
+    this.client = client
+  }
+
+  async stop(): Promise<void> {
+    if (!this.client) return
+
+    try {
+      await this.client.destroy()
+    } catch (error) {
+      this.logger.error("discord stop error", {
+        error: error instanceof Error ? error.message : String(error),
+      })
+    } finally {
+      this.client = null
+    }
+  }
+
+  override isAlive(): boolean {
+    return this.client !== null
+  }
+}

package/lib/{modules/connectors/funnel-gh-adapter.ts → connectors/gh-adapter.ts}

@@ -1,9 +1,6 @@
-import {
-  FunnelConnectorAdapter,
-  type CallInput,
-} from "@/modules/connectors/funnel-connector-adapter"
-import { FunnelProcessRunner } from "@/modules/process/funnel-process-runner"
-import { NodeFunnelProcessRunner } from "@/modules/process/node-funnel-process-runner"
+import { FunnelConnectorAdapter, type CallInput } from "@/connectors/connector-adapter"
+import { FunnelProcessRunner } from "@/engine/process/process-runner"
+import { NodeFunnelProcessRunner } from "@/engine/process/node-process-runner"
 
 type Deps = {
   process?: FunnelProcessRunner

package/lib/{modules/connectors → connectors}/gh-connector-schema.ts

@@ -1,9 +1,12 @@
 import { z } from "zod"
 
 export const ghConnectorSchema = z.object({
-  type: z.literal("gh"),
+  id: z.string(),
   name: z.string(),
+  type: z.literal("gh"),
   pollInterval: z.number().int().positive().optional(),
+  createdAt: z.string().datetime().optional(),
+  updatedAt: z.string().datetime().optional(),
 })
 
 export type GhConnectorConfig = z.infer<typeof ghConnectorSchema>

package/lib/{modules/connectors/funnel-gh-listener.ts → connectors/gh-listener.ts}

@@ -1,26 +1,36 @@
-import {
-  FunnelConnectorListener,
-  type NotifyFn,
-} from "@/modules/connectors/funnel-connector-listener"
-import { logger } from "@/modules/logger"
-import { FunnelProcessRunner } from "@/modules/process/funnel-process-runner"
-import { NodeFunnelProcessRunner } from "@/modules/process/node-funnel-process-runner"
-import type { GhConnectorConfig } from "@/modules/connectors/gh-connector-schema"
-
-type GhNotification = {
-  id: string
-  reason: string
-  subject: { type: string; url: string; title: string }
-  repository: { full_name: string }
-  updated_at: string
-}
+import { z } from "zod"
+import { FunnelConnectorListener, type NotifyFn } from "@/connectors/connector-listener"
+import { FunnelLogger } from "@/engine/logger/logger"
+import { NodeFunnelLogger } from "@/engine/logger/node-logger"
+import { FunnelProcessRunner } from "@/engine/process/process-runner"
+import { NodeFunnelProcessRunner } from "@/engine/process/node-process-runner"
+import type { GhConnectorConfig } from "@/connectors/gh-connector-schema"
+
+const ghNotificationSchema = z.object({
+  id: z.string(),
+  reason: z.string(),
+  subject: z.object({
+    type: z.string(),
+    url: z.string(),
+    title: z.string(),
+  }),
+  repository: z.object({ full_name: z.string() }),
+  updated_at: z.string(),
+})
+
+const ghNotificationsSchema = z.array(ghNotificationSchema)
+
+type GhNotification = z.infer<typeof ghNotificationSchema>
 
 type Deps = {
   config: GhConnectorConfig
   process?: FunnelProcessRunner
+  logger?: FunnelLogger
+  now?: () => Date
 }
 
 const defaultProcess = new NodeFunnelProcessRunner()
+const defaultLogger = new NodeFunnelLogger()
 
 const MAX_SEEN = 10000
 const KEEP_SEEN = 5000
@@ -28,14 +38,20 @@ const KEEP_SEEN = 5000
 export class FunnelGhListener extends FunnelConnectorListener {
   private readonly config: GhConnectorConfig
   private readonly process: FunnelProcessRunner
+  private readonly logger: FunnelLogger
+  private readonly now: () => Date
   private readonly seen = new Map<string, string>()
   private bootstrapped = false
-  private since = new Date().toISOString()
+  private since: string
+  private timer: ReturnType<typeof setInterval> | null = null
 
   constructor(deps: Deps) {
     super()
     this.config = deps.config
     this.process = deps.process ?? defaultProcess
+    this.logger = deps.logger ?? defaultLogger
+    this.now = deps.now ?? (() => new Date())
+    this.since = this.now().toISOString()
   }
 
   async start(notify: NotifyFn): Promise<void> {
@@ -43,22 +59,41 @@ export class FunnelGhListener extends FunnelConnectorListener {
 
     const interval = this.config.pollInterval ?? 60
 
-    setInterval(() => void this.pollOnce(notify), interval * 1000).unref()
+    this.timer = setInterval(() => void this.pollOnce(notify), interval * 1000)
+    this.timer.unref()
+  }
+
+  async stop(): Promise<void> {
+    if (!this.timer) return
+
+    clearInterval(this.timer)
+    this.timer = null
+  }
+
+  override isAlive(): boolean {
+    return this.timer !== null
   }
 
   async pollOnce(notify: NotifyFn): Promise<void> {
-    const nextSince = new Date().toISOString()
+    const nextSince = this.now().toISOString()
     const params = new URLSearchParams({ since: this.since, all: "false" })
 
     try {
       const result = await this.process.run(["gh", "api", `/notifications?${params}`])
 
       if (result.exitCode !== 0) {
-        logger.error("gh poll failed", { stderr: result.stderr })
+        this.logger.error("gh poll failed", { stderr: result.stderr })
+        return
+      }
+
+      const parsed = ghNotificationsSchema.safeParse(JSON.parse(result.stdout))
+
+      if (!parsed.success) {
+        this.logger.warn("gh response did not match schema", { error: parsed.error.message })
         return
       }
 
-      const items = JSON.parse(result.stdout) as GhNotification[]
+      const items: GhNotification[] = parsed.data
 
       for (const item of items) {
         if (this.seen.get(item.id) === item.updated_at) continue
@@ -94,7 +129,7 @@ export class FunnelGhListener extends FunnelConnectorListener {
       this.since = nextSince
       this.bootstrapped = true
     } catch (error) {
-      logger.error("gh poll error", {
+      this.logger.error("gh poll error", {
         error: error instanceof Error ? error.message : String(error),
       })
     }

package/lib/{modules/connectors → connectors}/match-cron.ts

@@ -18,14 +18,16 @@ const parseField = (expr: string, min: number, max: number): Field => {
       lo = min
       hi = max
     } else if (rangePart.includes("-")) {
-      const [a, b] = rangePart.split("-").map(Number)
+      const [aStr, bStr] = rangePart.split("-")
+      const a = Number(aStr)
+      const b = Number(bStr)
 
       if (!Number.isFinite(a) || !Number.isFinite(b)) {
         throw new Error(`invalid cron range: "${rangePart}"`)
       }
 
-      lo = a as number
-      hi = b as number
+      lo = a
+      hi = b
     } else {
       const n = Number(rangePart)
 
@@ -54,7 +56,11 @@ export const matchCron = (expr: string, date: Date): boolean => {
     throw new Error(`cron must have 5 fields (got ${parts.length}): "${expr}"`)
   }
 
-  const [minute, hour, dom, month, dow] = parts as [string, string, string, string, string]
+  const [minute, hour, dom, month, dow] = parts
+
+  if (!minute || !hour || !dom || !month || !dow) {
+    throw new Error(`cron has empty fields: "${expr}"`)
+  }
 
   const fields = [
     { field: parseField(minute, 0, 59), value: date.getMinutes() },

package/lib/connectors/schedule-connector-schema.ts

@@ -0,0 +1,33 @@
+import { z } from "zod"
+
+/**
+ * Catch-up behavior when the daemon was down past one or more matching minutes.
+ *
+ * - `latest`: fire once with the most recent missed match (default; preserves prior behavior).
+ * - `all`: fire once per missed minute, oldest first (capped at 24 h).
+ * - `skip`: never fire missed matches; only fire when the current minute matches.
+ */
+export const scheduleCatchupPolicySchema = z.enum(["latest", "all", "skip"])
+
+export type ScheduleCatchupPolicy = z.infer<typeof scheduleCatchupPolicySchema>
+
+export const scheduleEntrySchema = z.object({
+  id: z.string(),
+  cron: z.string(),
+  prompt: z.string(),
+  enabled: z.boolean().default(true),
+  catchupPolicy: scheduleCatchupPolicySchema.default("latest"),
+})
+
+export type ScheduleEntry = z.infer<typeof scheduleEntrySchema>
+
+export const scheduleConnectorSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  type: z.literal("schedule"),
+  entries: z.array(scheduleEntrySchema).default([]),
+  createdAt: z.string().datetime().optional(),
+  updatedAt: z.string().datetime().optional(),
+})
+
+export type ScheduleConnectorConfig = z.infer<typeof scheduleConnectorSchema>

package/lib/connectors/schedule-listener.ts

@@ -0,0 +1,207 @@
+import { FunnelConnectorListener, type NotifyFn } from "@/connectors/connector-listener"
+import { matchCron } from "@/connectors/match-cron"
+import { ScheduleStateStore } from "@/connectors/schedule-state-store"
+import { FunnelLogger } from "@/engine/logger/logger"
+import { NodeFunnelLogger } from "@/engine/logger/node-logger"
+import type { ScheduleConnectorConfig, ScheduleEntry } from "@/connectors/schedule-connector-schema"
+
+type Deps = {
+  config: ScheduleConnectorConfig
+  lastFiredStore: ScheduleStateStore
+  logger?: FunnelLogger
+  now?: () => Date
+}
+
+const defaultLogger = new NodeFunnelLogger()
+
+const MAX_CATCHUP_MINUTES = 60 * 24
+
+export class FunnelScheduleListener extends FunnelConnectorListener {
+  private readonly config: ScheduleConnectorConfig
+  private readonly lastFiredStore: ScheduleStateStore
+  private readonly logger: FunnelLogger
+  private readonly now: () => Date
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private stopped = false
+
+  constructor(deps: Deps) {
+    super()
+    this.config = deps.config
+    this.lastFiredStore = deps.lastFiredStore
+    this.logger = deps.logger ?? defaultLogger
+    this.now = deps.now ?? (() => new Date())
+  }
+
+  async start(notify: NotifyFn): Promise<void> {
+    this.stopped = false
+
+    const scheduleNext = () => {
+      if (this.stopped) return
+
+      const date = this.now()
+      const msUntilNextMinute = 60_000 - (date.getSeconds() * 1000 + date.getMilliseconds())
+      this.timer = setTimeout(async () => {
+        if (this.stopped) return
+        await this.tick(notify)
+        scheduleNext()
+      }, msUntilNextMinute)
+
+      this.timer.unref()
+    }
+
+    await this.tick(notify)
+    scheduleNext()
+  }
+
+  async stop(): Promise<void> {
+    this.stopped = true
+
+    if (this.timer) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+  }
+
+  override isAlive(): boolean {
+    return !this.stopped && this.timer !== null
+  }
+
+  async tick(notify: NotifyFn): Promise<void> {
+    const now = this.truncateToMinute(this.now())
+    const state = this.lastFiredStore.load()
+    let changed = false
+
+    for (const entry of this.config.entries) {
+      if (!entry.enabled) continue
+
+      const fired = await this.fireEntry(entry, now, state, notify)
+
+      if (fired) changed = true
+    }
+
+    if (changed) this.lastFiredStore.save(state)
+  }
+
+  private async fireEntry(
+    entry: ScheduleEntry,
+    now: Date,
+    state: Map<string, Date>,
+    notify: NotifyFn,
+  ): Promise<boolean> {
+    const lastFired = state.get(entry.id)
+    const searchFrom = lastFired ? new Date(lastFired.getTime() + 60_000) : now
+
+    if (searchFrom.getTime() > now.getTime()) return false
+
+    if (entry.catchupPolicy === "skip") {
+      try {
+        if (!matchCron(entry.cron, now)) return false
+      } catch (error) {
+        this.logInvalidCron(entry, error)
+        return false
+      }
+
+      await this.notifyOne(entry, now, notify, false)
+      state.set(entry.id, now)
+      return true
+    }
+
+    if (entry.catchupPolicy === "all") {
+      const matches = this.findAllMatches(entry.cron, searchFrom, now, entry.id)
+
+      if (matches.length === 0) return false
+
+      for (const match of matches) {
+        await this.notifyOne(entry, match, notify, match.getTime() !== now.getTime())
+      }
+
+      state.set(entry.id, matches[matches.length - 1] ?? now)
+      return true
+    }
+
+    const match = this.findMostRecentMatch(entry.cron, searchFrom, now, entry.id)
+
+    if (!match) return false
+
+    await this.notifyOne(entry, match, notify, match.getTime() !== now.getTime())
+    state.set(entry.id, match)
+    return true
+  }
+
+  private async notifyOne(
+    entry: ScheduleEntry,
+    firedAt: Date,
+    notify: NotifyFn,
+    catchup: boolean,
+  ): Promise<void> {
+    const meta: Record<string, string> = {
+      event_type: "schedule",
+      schedule_id: entry.id,
+      cron: entry.cron,
+      fired_at: firedAt.toISOString(),
+      catchup_policy: entry.catchupPolicy,
+    }
+
+    if (catchup) meta.catchup = "true"
+
+    await notify(entry.prompt, meta)
+  }
+
+  private findMostRecentMatch(cron: string, from: Date, until: Date, entryId: string): Date | null {
+    const maxIterations = Math.min(
+      MAX_CATCHUP_MINUTES,
+      Math.floor((until.getTime() - from.getTime()) / 60_000) + 1,
+    )
+
+    for (let i = 0; i < maxIterations; i++) {
+      const candidate = new Date(until.getTime() - i * 60_000)
+
+      try {
+        if (matchCron(cron, candidate)) return candidate
+      } catch (error) {
+        this.logInvalidCron({ id: entryId, cron } as ScheduleEntry, error)
+        return null
+      }
+    }
+
+    return null
+  }
+
+  private findAllMatches(cron: string, from: Date, until: Date, entryId: string): Date[] {
+    const maxIterations = Math.min(
+      MAX_CATCHUP_MINUTES,
+      Math.floor((until.getTime() - from.getTime()) / 60_000) + 1,
+    )
+    const matches: Date[] = []
+
+    for (let i = 0; i < maxIterations; i++) {
+      const candidate = new Date(from.getTime() + i * 60_000)
+
+      if (candidate.getTime() > until.getTime()) break
+
+      try {
+        if (matchCron(cron, candidate)) matches.push(candidate)
+      } catch (error) {
+        this.logInvalidCron({ id: entryId, cron } as ScheduleEntry, error)
+        return []
+      }
+    }
+
+    return matches
+  }
+
+  private logInvalidCron(entry: Pick<ScheduleEntry, "id" | "cron">, error: unknown): void {
+    this.logger.error("invalid cron expression in schedule", {
+      connector: this.config.name,
+      id: entry.id,
+      cron: entry.cron,
+      error: error instanceof Error ? error.message : String(error),
+    })
+  }
+
+  private truncateToMinute(date: Date): Date {
+    const copy = new Date(date.getTime())
+    copy.setSeconds(0, 0)
+    return copy
+  }
+}

package/lib/connectors/schedule-state-store.ts

@@ -0,0 +1,54 @@
+import { dirname } from "node:path"
+import { FunnelFileSystem } from "@/engine/fs/file-system"
+import { NodeFunnelFileSystem } from "@/engine/fs/node-file-system"
+
+type Deps = {
+  path: string
+  fs?: FunnelFileSystem
+}
+
+const defaultFs = new NodeFunnelFileSystem()
+
+/**
+ * Per-connector lastFiredAt persistence for the schedule listener. The path is
+ * passed in by FunnelConnectorFactory so this store does not know about the
+ * funnel directory layout (`channels/<id>/connectors/<id>/state.json` lives
+ * outside this class).
+ */
+export class ScheduleStateStore {
+  private readonly path: string
+  private readonly fs: FunnelFileSystem
+
+  constructor(deps: Deps) {
+    this.path = deps.path
+    this.fs = deps.fs ?? defaultFs
+    Object.freeze(this)
+  }
+
+  load(): Map<string, Date> {
+    const map = new Map<string, Date>()
+
+    if (!this.fs.existsSync(this.path)) return map
+
+    const raw: unknown = JSON.parse(this.fs.readFileSync(this.path))
+
+    if (raw === null || typeof raw !== "object") return map
+
+    for (const [id, iso] of Object.entries(raw)) {
+      if (typeof iso === "string") map.set(id, new Date(iso))
+    }
+
+    return map
+  }
+
+  save(state: Map<string, Date>): void {
+    const obj: Record<string, string> = {}
+
+    for (const [id, date] of state) {
+      obj[id] = date.toISOString()
+    }
+
+    this.fs.mkdirSync(dirname(this.path), { recursive: true })
+    this.fs.writeFileSync(this.path, `${JSON.stringify(obj, null, 2)}\n`)
+  }
+}