@interactive-inc/claude-funnel 0.4.1 → 0.8.0

package/lib/engine/mcp/channel-server.ts

@@ -0,0 +1,204 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { Server } from "@modelcontextprotocol/sdk/server/index.js"
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js"
+import { FUNNEL_MCP_NAME } from "@/engine/mcp/mcp"
+import { settingsSchema } from "@/engine/settings/settings-schema"
+
+const GATEWAY_BASE_URL = process.env.FUNNEL_GATEWAY_URL ?? "http://localhost:9742"
+const GATEWAY_WS_URL = `${GATEWAY_BASE_URL.replace(/^http/, "ws")}/ws`
+const RECONNECT_DELAY = 1000
+const MAX_RECONNECT_DELAY = 10000
+const SETTINGS_PATH = join(homedir(), ".funnel", "settings.json")
+const TOOL_CONNECTOR_TYPES = new Set(["slack", "gh", "discord"])
+
+const readGatewayToken = (): string | null => {
+  const fromEnv = process.env.FUNNEL_GATEWAY_TOKEN
+
+  if (fromEnv && fromEnv.length > 0) return fromEnv
+
+  const path = join(homedir(), ".funnel", "gateway.token")
+
+  if (!existsSync(path)) return null
+
+  const value = readFileSync(path, "utf-8").trim()
+
+  return value.length > 0 ? value : null
+}
+
+const readChannelConnectors = (
+  channelId: string,
+): { channelName: string; connectors: { name: string; type: string }[] } | null => {
+  if (!existsSync(SETTINGS_PATH)) return null
+
+  const raw = JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"))
+  const parsed = settingsSchema.safeParse(raw)
+
+  if (!parsed.success) return null
+
+  const channel = parsed.data.channels.find((c) => c.id === channelId)
+
+  if (!channel) return null
+
+  const connectors = channel.connectors
+    .filter((c) => TOOL_CONNECTOR_TYPES.has(c.type))
+    .map((c) => ({ name: c.name, type: c.type }))
+
+  return { channelName: channel.name, connectors }
+}
+
+const usageHintForType = (type: string): string => {
+  if (type === "slack") {
+    return "Slack Web API. method=POST path=chat.postMessage body={channel,text,thread_ts?}"
+  }
+
+  if (type === "discord") {
+    return "Discord REST API. method=POST path=/channels/<id>/messages body={content,...}"
+  }
+
+  if (type === "gh") {
+    return "GitHub REST via gh CLI. method=POST path=repos/owner/repo/issues/N/comments body={body}"
+  }
+
+  return "Generic adapter call."
+}
+
+export const startChannelServer = async (): Promise<void> => {
+  const channelId = process.env.FUNNEL_CHANNEL_ID
+  const channel = channelId ? readChannelConnectors(channelId) : null
+  const token = readGatewayToken()
+
+  const server = new Server(
+    { name: FUNNEL_MCP_NAME, version: "1.0.0" },
+    {
+      capabilities: {
+        experimental: { "claude/channel": {} },
+        tools: {},
+      },
+      instructions: [
+        `Events arrive inside <channel source="${FUNNEL_MCP_NAME}"> tags. Use meta.event_type to discriminate.`,
+        "",
+        "To reply or act, call the connector tool exposed by this MCP (one tool per connector configured on this channel). Each tool takes { method, path, body } matching the underlying adapter's CallInput.",
+      ].join("\n"),
+    },
+  )
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const tools = (channel?.connectors ?? []).map((c) => ({
+      name: c.name,
+      description: `Call the "${c.name}" (${c.type}) connector. ${usageHintForType(c.type)}`,
+      inputSchema: {
+        type: "object" as const,
+        properties: {
+          method: { type: "string", description: "HTTP verb or API method (e.g. POST, chat.postMessage)" },
+          path: { type: "string", description: "API path or method name (adapter-specific)" },
+          body: { type: "object", description: "Request body / params (adapter-specific)" },
+        },
+        required: ["method", "path"],
+      },
+    }))
+
+    return { tools }
+  })
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (!channel) {
+      throw new Error("FUNNEL_CHANNEL_ID is not set or channel not found in settings.json")
+    }
+
+    const connectorName = request.params.name
+    const args = (request.params.arguments ?? {}) as Record<string, unknown>
+    const method = typeof args.method === "string" ? args.method : ""
+    const path = typeof args.path === "string" ? args.path : ""
+    const body = args.body ?? {}
+
+    if (!method || !path) {
+      throw new Error("`method` and `path` are required")
+    }
+
+    const url = `${GATEWAY_BASE_URL}/channels/${encodeURIComponent(channel.channelName)}/connectors/${encodeURIComponent(connectorName)}/call`
+    const headers: Record<string, string> = { "content-type": "application/json" }
+
+    if (token) headers.authorization = `Bearer ${token}`
+
+    const res = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ method, path, body }),
+    })
+
+    const text = await res.text()
+
+    if (!res.ok) {
+      throw new Error(`gateway call failed (${res.status}): ${text}`)
+    }
+
+    return {
+      content: [{ type: "text", text }],
+    }
+  })
+
+  const transport = new StdioServerTransport()
+
+  await server.connect(transport)
+
+  if (!channelId) return
+
+  const baseUrl = `${GATEWAY_WS_URL}?channel=${encodeURIComponent(channelId)}`
+  const protocols = token ? [`funnel.token.${token}`] : undefined
+  let reconnectDelay = RECONNECT_DELAY
+  let lastOffset = 0
+
+  const connect = () => {
+    const sinceQuery = lastOffset > 0 ? `&since=${lastOffset}` : ""
+    const wsUrl = `${baseUrl}${sinceQuery}`
+    const ws = new WebSocket(wsUrl, protocols)
+
+    ws.addEventListener("open", () => {
+      reconnectDelay = RECONNECT_DELAY
+      process.stderr.write(`funnel: connected (${wsUrl})\n`)
+    })
+
+    ws.addEventListener("message", async (event) => {
+      try {
+        const payload = JSON.parse(String(event.data))
+        const eventType = payload.meta?.event_type ?? "unknown"
+
+        if (typeof payload.offset === "number" && payload.offset > lastOffset) {
+          lastOffset = payload.offset
+        }
+
+        process.stderr.write(`funnel: received event (${eventType})\n`)
+
+        await server.notification({
+          method: "notifications/claude/channel",
+          params: {
+            content: payload.content,
+            meta: payload.meta,
+          },
+        })
+      } catch (error) {
+        process.stderr.write(
+          `funnel: error: ${error instanceof Error ? error.message : String(error)}\n`,
+        )
+      }
+    })
+
+    ws.addEventListener("close", () => {
+      process.stderr.write(`funnel: disconnected, reconnecting in ${reconnectDelay}ms\n`)
+      setTimeout(connect, reconnectDelay)
+      reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_DELAY)
+    })
+
+    ws.addEventListener("error", () => {
+      // close handler will reconnect
+    })
+  }
+
+  connect()
+}

package/lib/{modules/mcp/funnel-mcp.ts → engine/mcp/mcp.ts}

@@ -1,18 +1,22 @@
 import { join } from "node:path"
-import { FunnelFileSystem } from "@/modules/fs/funnel-file-system"
-import { NodeFunnelFileSystem } from "@/modules/fs/node-funnel-file-system"
+import { z } from "zod"
+import { FunnelFileSystem } from "@/engine/fs/file-system"
+import { NodeFunnelFileSystem } from "@/engine/fs/node-file-system"
 
 export const FUNNEL_MCP_COMMAND = "funnel"
 export const FUNNEL_MCP_NAME = "funnel"
 
-type McpEntry = {
-  command?: string
-  args?: string[]
-}
+const mcpEntrySchema = z.object({
+  command: z.string().optional(),
+  args: z.array(z.string()).optional(),
+})
 
-type McpConfig = {
-  mcpServers?: Record<string, McpEntry>
-}
+const mcpConfigSchema = z.object({
+  mcpServers: z.record(z.string(), mcpEntrySchema).optional(),
+})
+
+type McpEntry = z.infer<typeof mcpEntrySchema>
+type McpConfig = z.infer<typeof mcpConfigSchema>
 
 type Deps = {
   fs?: FunnelFileSystem
@@ -20,6 +24,11 @@ type Deps = {
 
 const defaultFs = new NodeFunnelFileSystem()
 
+/**
+ * Installs/uninstalls the funnel MCP entry into a target repository's
+ * `.mcp.json`. Detects an existing entry by command match so renaming is
+ * preserved across re-installs.
+ */
 export class FunnelMcp {
   private readonly fs: FunnelFileSystem
 
@@ -90,13 +99,23 @@ export class FunnelMcp {
 
     if (!content) return {}
 
+    let parsed: unknown
+
     try {
-      return JSON.parse(content) as McpConfig
+      parsed = JSON.parse(content)
     } catch (error) {
       throw new Error(
         `invalid .mcp.json (${mcpPath}): ${error instanceof Error ? error.message : String(error)}`,
       )
     }
+
+    const result = mcpConfigSchema.safeParse(parsed)
+
+    if (!result.success) {
+      throw new Error(`invalid .mcp.json (${mcpPath}): ${result.error.message}`)
+    }
+
+    return result.data
   }
 
   private writeConfig(repoPath: string, config: McpConfig): void {

package/lib/{modules/process/memory-funnel-process-runner.ts → engine/process/memory-process-runner.ts}

@@ -4,7 +4,7 @@ import {
   FunnelProcessRunner,
   type RunOptions,
   type RunResult,
-} from "@/modules/process/funnel-process-runner"
+} from "@/engine/process/process-runner"
 
 export type MemoryProcessResponse = {
   exitCode?: number

package/lib/{modules/process/node-funnel-process-runner.ts → engine/process/node-process-runner.ts}

@@ -4,12 +4,22 @@ import {
   FunnelProcessRunner,
   type RunOptions,
   type RunResult,
-} from "@/modules/process/funnel-process-runner"
+} from "@/engine/process/process-runner"
 
 const toEnv = (env?: Record<string, string>): Record<string, string> | undefined => {
   if (!env) return undefined
 
-  return { ...(process.env as Record<string, string>), ...env }
+  const merged: Record<string, string> = {}
+
+  for (const [key, value] of Object.entries(process.env)) {
+    if (typeof value === "string") merged[key] = value
+  }
+
+  for (const [key, value] of Object.entries(env)) {
+    merged[key] = value
+  }
+
+  return merged
 }
 
 export class NodeFunnelProcessRunner extends FunnelProcessRunner {
@@ -59,25 +69,6 @@ export class NodeFunnelProcessRunner extends FunnelProcessRunner {
       stdio: ["inherit", "inherit", "inherit"],
     })
 
-    const forward = (signal: "SIGINT" | "SIGTERM") => {
-      try {
-        proc.kill(signal)
-      } catch {
-        // ignore
-      }
-
-      setTimeout(() => {
-        try {
-          proc.kill("SIGKILL")
-        } catch {
-          // ignore
-        }
-      }, 3000).unref()
-    }
-
-    process.on("SIGINT", () => forward("SIGINT"))
-    process.on("SIGTERM", () => forward("SIGTERM"))
-
     return await proc.exited
   }
 

package/lib/{modules/process/funnel-process-runner.ts → engine/process/process-runner.ts}

@@ -19,6 +19,11 @@ export type DetachOptions = {
   env?: Record<string, string>
 }
 
+/**
+ * Process boundary covering one-shot runs, sync runs, foreground attach, and
+ * detached background spawns. Default is NodeFunnelProcessRunner (Bun.spawn);
+ * MemoryFunnelProcessRunner records calls and lets tests stub responses.
+ */
 export abstract class FunnelProcessRunner {
   abstract run(command: string[], options?: RunOptions): Promise<RunResult>
   abstract runSync(command: string[]): RunResult

package/lib/engine/profiles/profile-channel-checker.ts

@@ -0,0 +1,7 @@
+/**
+ * Read-side dependency that lets FunnelChannels ask whether a profile
+ * references a given channel id, without depending on FunnelProfiles directly.
+ */
+export type ProfileChannelChecker = {
+  hasChannelRef(channelId: string): boolean
+}

package/lib/engine/profiles/profiles.ts

@@ -0,0 +1,126 @@
+import { FunnelSettingsReader } from "@/engine/settings/settings-reader"
+import type { ProfileConfig } from "@/engine/settings/settings-schema"
+
+type Deps = {
+  store: FunnelSettingsReader
+}
+
+/**
+ * Named launch presets for `fnl claude`. Each profile bundles a working
+ * directory, a sub-agent name, and the channel id its Claude instance will
+ * subscribe to. Implements ProfileChannelChecker so FunnelChannels can refuse
+ * to remove a channel that is still referenced.
+ *
+ * The first entry in the persisted array is treated as the default profile;
+ * `asDefault` reorders the array to put a named profile first.
+ *
+ * `channelId` always stores the channel's stable id (uuid). CLI surfaces
+ * resolve channel name → id before calling `add`/`update` here.
+ */
+export class FunnelProfiles {
+  private readonly store: FunnelSettingsReader
+
+  constructor(deps: Deps) {
+    this.store = deps.store
+    Object.freeze(this)
+  }
+
+  list(): ProfileConfig[] {
+    return this.store.read().profiles
+  }
+
+  get(name: string): ProfileConfig | null {
+    return this.list().find((p) => p.name === name) ?? null
+  }
+
+  getDefault(): ProfileConfig | null {
+    return this.list()[0] ?? null
+  }
+
+  add(config: ProfileConfig): void {
+    const settings = this.store.read()
+
+    if (settings.profiles.some((p) => p.name === config.name)) {
+      throw new Error(`profile "${config.name}" already exists`)
+    }
+
+    if (!settings.channels.some((c) => c.id === config.channelId)) {
+      throw new Error(`channel id "${config.channelId}" not found`)
+    }
+
+    settings.profiles.push(config)
+
+    this.store.write(settings)
+  }
+
+  remove(name: string): void {
+    const settings = this.store.read()
+
+    const index = settings.profiles.findIndex((p) => p.name === name)
+
+    if (index < 0) throw new Error(`profile "${name}" not found`)
+
+    settings.profiles.splice(index, 1)
+
+    this.store.write(settings)
+  }
+
+  rename(oldName: string, newName: string): void {
+    const settings = this.store.read()
+
+    const profile = settings.profiles.find((p) => p.name === oldName)
+
+    if (!profile) throw new Error(`profile "${oldName}" not found`)
+
+    if (settings.profiles.some((p) => p.name === newName)) {
+      throw new Error(`profile "${newName}" already exists`)
+    }
+
+    profile.name = newName
+
+    this.store.write(settings)
+  }
+
+  asDefault(name: string): void {
+    const settings = this.store.read()
+
+    const index = settings.profiles.findIndex((p) => p.name === name)
+
+    if (index < 0) throw new Error(`profile "${name}" not found`)
+
+    if (index === 0) return
+
+    const [profile] = settings.profiles.splice(index, 1)
+
+    if (!profile) return
+
+    settings.profiles.unshift(profile)
+
+    this.store.write(settings)
+  }
+
+  hasChannelRef(channelId: string): boolean {
+    return this.store.read().profiles.some((p) => p.channelId === channelId)
+  }
+
+  update(name: string, fields: Partial<Omit<ProfileConfig, "name">>): void {
+    const settings = this.store.read()
+
+    const profile = settings.profiles.find((p) => p.name === name)
+
+    if (!profile) throw new Error(`profile "${name}" not found`)
+
+    if (fields.channelId !== undefined) {
+      if (!settings.channels.some((c) => c.id === fields.channelId)) {
+        throw new Error(`channel id "${fields.channelId}" not found`)
+      }
+
+      profile.channelId = fields.channelId
+    }
+
+    if (fields.path !== undefined) profile.path = fields.path
+    if (fields.subAgent !== undefined) profile.subAgent = fields.subAgent
+
+    this.store.write(settings)
+  }
+}

package/lib/{modules/settings/mock-funnel-settings-reader.ts → engine/settings/mock-settings-reader.ts}

@@ -1,9 +1,10 @@
-import { FunnelSettingsReader } from "@/modules/settings/funnel-settings-reader"
-import type { Settings } from "@/modules/settings/settings-schema"
+import { FunnelSettingsReader } from "@/engine/settings/settings-reader"
+import { SETTINGS_VERSION } from "@/engine/settings/settings-schema"
+import type { Settings } from "@/engine/settings/settings-schema"
 
 export const createSettings = (partial: Partial<Settings> = {}): Settings => ({
+  version: SETTINGS_VERSION,
   channels: [],
-  repositories: [],
   profiles: [],
   ...partial,
 })

package/lib/{modules/settings/funnel-settings-reader.ts → engine/settings/settings-reader.ts}

@@ -1,4 +1,4 @@
-import type { Settings } from "@/modules/settings/settings-schema"
+import type { Settings } from "@/engine/settings/settings-schema"
 
 export abstract class FunnelSettingsReader {
   abstract read(): Settings

package/lib/engine/settings/settings-schema.ts

@@ -0,0 +1,46 @@
+import { z } from "zod"
+import { connectorConfigSchema } from "@/connectors/connector-config-schema"
+
+/**
+ * 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 const channelDeliveryModeSchema = z.enum(["fanout", "exclusive"])
+
+export type ChannelDeliveryMode = z.infer<typeof channelDeliveryModeSchema>
+
+export const channelConfigSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  delivery: channelDeliveryModeSchema.default("fanout"),
+  connectors: z.array(connectorConfigSchema).default([]),
+})
+
+export type ChannelConfig = z.infer<typeof channelConfigSchema>
+
+export const profileConfigSchema = z.object({
+  name: z.string(),
+  path: z.string(),
+  subAgent: z.string(),
+  channelId: z.string(),
+})
+
+export type ProfileConfig = z.infer<typeof profileConfigSchema>
+
+export const SETTINGS_VERSION = 1
+
+export const settingsSchema = z.object({
+  /** Schema version. New files always write the current version; older files without one are read as v1. */
+  version: z.literal(SETTINGS_VERSION).default(SETTINGS_VERSION),
+  channels: z.array(channelConfigSchema).default([]),
+  profiles: z.array(profileConfigSchema).default([]),
+})
+
+export type Settings = z.infer<typeof settingsSchema>

package/lib/engine/settings/settings-store.ts

@@ -0,0 +1,110 @@
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import { FunnelFileSystem } from "@/engine/fs/file-system"
+import { NodeFunnelFileSystem } from "@/engine/fs/node-file-system"
+import { FunnelSettingsReader } from "@/engine/settings/settings-reader"
+import { SETTINGS_VERSION, settingsSchema } from "@/engine/settings/settings-schema"
+import type { Settings } from "@/engine/settings/settings-schema"
+
+export const FUNNEL_DIR = join(homedir(), ".funnel")
+export const SETTINGS_PATH = join(FUNNEL_DIR, "settings.json")
+
+type Deps = {
+  path?: string
+  fs?: FunnelFileSystem
+}
+
+const defaultFs = new NodeFunnelFileSystem()
+
+export class FunnelSettingsStore extends FunnelSettingsReader {
+  private readonly path: string
+  private readonly fs: FunnelFileSystem
+
+  constructor(deps: Deps = {}) {
+    super()
+    this.path = deps.path ?? SETTINGS_PATH
+    this.fs = deps.fs ?? defaultFs
+    Object.freeze(this)
+  }
+
+  read(): Settings {
+    if (!this.fs.existsSync(this.path)) {
+      return {
+        version: SETTINGS_VERSION,
+        channels: [],
+        profiles: [],
+      }
+    }
+
+    const content = this.fs.readFileSync(this.path)
+    const parsed: unknown = JSON.parse(content)
+
+    if (this.looksLikeLegacy(parsed)) {
+      throw new Error(
+        `legacy settings.json detected at ${this.path}. The schema changed (channel.connectors are now nested objects with ids; profile fields renamed). Migration is intentionally not provided. Back up and remove the old file:\n  mv ${this.path} ${this.path}.bak`,
+      )
+    }
+
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      "version" in parsed &&
+      parsed.version !== SETTINGS_VERSION
+    ) {
+      throw new Error(
+        `unsupported settings.json version (${this.path}): expected ${SETTINGS_VERSION}, got ${String(parsed.version)}`,
+      )
+    }
+
+    const result = settingsSchema.safeParse(parsed)
+
+    if (!result.success) {
+      throw new Error(
+        `invalid settings.json (${this.path}): ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", ")}`,
+      )
+    }
+
+    return result.data
+  }
+
+  private looksLikeLegacy(parsed: unknown): boolean {
+    if (!parsed || typeof parsed !== "object") return false
+
+    const obj = parsed as Record<string, unknown>
+
+    if (Array.isArray(obj.channels)) {
+      for (const channel of obj.channels) {
+        if (!channel || typeof channel !== "object") continue
+        const ch = channel as Record<string, unknown>
+
+        if (Array.isArray(ch.connectors) && ch.connectors.some((x) => typeof x === "string")) {
+          return true
+        }
+
+        if (!("id" in ch) && "name" in ch) return true
+      }
+    }
+
+    if (Array.isArray(obj.connectors)) return true
+    if (Array.isArray(obj.repositories)) return true
+
+    if (Array.isArray(obj.profiles)) {
+      for (const profile of obj.profiles) {
+        if (!profile || typeof profile !== "object") continue
+        const p = profile as Record<string, unknown>
+
+        if ("repository" in p || "envFiles" in p || ("channel" in p && !("channelId" in p))) {
+          return true
+        }
+      }
+    }
+
+    return false
+  }
+
+  write(settings: Settings): void {
+    this.fs.mkdirSync(dirname(this.path), { recursive: true })
+    const versioned: Settings = { ...settings, version: SETTINGS_VERSION }
+    this.fs.writeFileSync(this.path, `${JSON.stringify(versioned, null, 2)}\n`)
+  }
+}

package/lib/engine/time/clock.ts

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