@interactive-inc/claude-funnel 0.8.0 → 0.10.0

package/lib/engine/mcp/usage-hint-for-type.ts

@@ -0,0 +1,15 @@
+export 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."
+}

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

@@ -30,6 +30,8 @@ export const profileConfigSchema = z.object({
   path: z.string(),
   subAgent: z.string(),
   channelId: z.string(),
+  /** Forwards `--brief` to claude on launch (enables the SendUserMessage tool). */
+  brief: z.boolean().optional(),
 })
 
 export type ProfileConfig = z.infer<typeof profileConfigSchema>

package/lib/funnel.ts

@@ -2,22 +2,36 @@ import { join } from "node:path"
 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 { FunnelFileSystem } from "@/engine/fs/file-system"
+import { MemoryFunnelFileSystem } from "@/engine/fs/memory-file-system"
+import { NodeFunnelFileSystem } from "@/engine/fs/node-file-system"
+import { FunnelIdGenerator } from "@/engine/id/id-generator"
+import { MemoryFunnelIdGenerator } from "@/engine/id/memory-id-generator"
+import { NodeFunnelIdGenerator } from "@/engine/id/node-id-generator"
 import { FunnelLogger } from "@/engine/logger/logger"
+import { MemoryFunnelLogger } from "@/engine/logger/memory-logger"
 import { NodeFunnelLogger } from "@/engine/logger/node-logger"
 import { FunnelMcp } from "@/engine/mcp/mcp"
 import { FunnelProcessRunner } from "@/engine/process/process-runner"
+import { MemoryFunnelProcessRunner } from "@/engine/process/memory-process-runner"
 import { NodeFunnelProcessRunner } from "@/engine/process/node-process-runner"
 import { FunnelProfiles } from "@/engine/profiles/profiles"
+import { MockFunnelSettingsReader } from "@/engine/settings/mock-settings-reader"
 import { FunnelSettingsReader } from "@/engine/settings/settings-reader"
 import { FUNNEL_DIR, FunnelSettingsStore } from "@/engine/settings/settings-store"
-import type { FunnelClock } from "@/engine/time/clock"
+import { FunnelClock } from "@/engine/time/clock"
+import { MemoryFunnelClock } from "@/engine/time/memory-clock"
+import { NodeFunnelClock } from "@/engine/time/node-clock"
+import { FunnelChannelPublisher } from "@/gateway/channel-publisher"
 import { FunnelGateway } from "@/gateway/gateway"
 import { FunnelGatewayServer } from "@/gateway/gateway-server"
 import { FunnelGatewayToken } from "@/gateway/gateway-token"
 import { FunnelListenersClient } from "@/gateway/listeners-client"
 
+const DEFAULT_TMP_DIR = "/tmp/funnel"
+const SANDBOX_DIR = "/sandbox/.funnel"
+const SANDBOX_TMP_DIR = "/sandbox/tmp"
+
 type Props = {
   /** Settings persistence (channels with nested connectors / profiles). Defaults to a FunnelSettingsStore rooted at `dir`. */
   store?: FunnelSettingsReader
@@ -57,89 +71,180 @@ type Props = {
  * ```
  */
 export class Funnel {
+  private readonly cache = new Map<string, unknown>()
+
   constructor(private readonly props: Props = {}) {
     Object.freeze(this)
   }
 
-  /** Settings reader. If not injected, a FunnelSettingsStore rooted at `dir` is created. */
-  get store(): FunnelSettingsReader {
-    return (
-      this.props.store ??
-      new FunnelSettingsStore({
-        path: join(this.props.dir ?? FUNNEL_DIR, "settings.json"),
-        fs: this.props.fs,
-      })
-    )
+  /**
+   * Sandboxed Funnel wired with in-memory implementations for every IO boundary.
+   * Touches no real disk, processes, wall-clock time, or UUIDs — safe for tests
+   * and ad-hoc experiments. Override individual fields by passing them in `props`.
+   */
+  static inMemory(props: Props = {}): Funnel {
+    return new Funnel({
+      store: props.store ?? new MockFunnelSettingsReader(),
+      fs: props.fs ?? new MemoryFunnelFileSystem(),
+      process: props.process ?? new MemoryFunnelProcessRunner(),
+      logger: props.logger ?? new MemoryFunnelLogger(),
+      clock: props.clock ?? new MemoryFunnelClock(),
+      idGenerator: props.idGenerator ?? new MemoryFunnelIdGenerator(),
+      dir: props.dir ?? SANDBOX_DIR,
+      tmpDir: props.tmpDir ?? SANDBOX_TMP_DIR,
+    })
+  }
+
+  private memo<T>(key: string, build: () => T): T {
+    if (this.cache.has(key)) return this.cache.get(key) as T
+
+    const value = build()
+    this.cache.set(key, value)
+
+    return value
+  }
+
+  /** Resolved on-disk paths the facade will read/write when methods are called. Pure compute, not memoized. */
+  get paths(): { dir: string; tmpDir: string; settings: string } {
+    const dir = this.props.dir ?? FUNNEL_DIR
+    const tmpDir = this.props.tmpDir ?? DEFAULT_TMP_DIR
+
+    return { dir, tmpDir, settings: join(dir, "settings.json") }
+  }
+
+  /** Filesystem boundary. Defaults to NodeFunnelFileSystem. */
+  get fs(): FunnelFileSystem {
+    return this.memo("fs", () => this.props.fs ?? new NodeFunnelFileSystem())
   }
 
   /** Process runner boundary. Defaults to NodeFunnelProcessRunner. */
   get process(): FunnelProcessRunner {
-    return this.props.process ?? new NodeFunnelProcessRunner()
+    return this.memo("process", () => this.props.process ?? new NodeFunnelProcessRunner())
   }
 
   /** Logger boundary. Defaults to NodeFunnelLogger. */
   get logger(): FunnelLogger {
-    return this.props.logger ?? new NodeFunnelLogger()
+    return this.memo("logger", () => this.props.logger ?? new NodeFunnelLogger())
+  }
+
+  /** Clock boundary. Defaults to NodeFunnelClock. */
+  get clock(): FunnelClock {
+    return this.memo("clock", () => this.props.clock ?? new NodeFunnelClock())
+  }
+
+  /** ID generator boundary. Defaults to NodeFunnelIdGenerator. */
+  get idGenerator(): FunnelIdGenerator {
+    return this.memo("idGenerator", () => this.props.idGenerator ?? new NodeFunnelIdGenerator())
+  }
+
+  /** Settings reader. If not injected, a FunnelSettingsStore rooted at `dir` is created. */
+  get store(): FunnelSettingsReader {
+    return this.memo(
+      "store",
+      () =>
+        this.props.store ??
+        new FunnelSettingsStore({
+          path: this.paths.settings,
+          fs: this.fs,
+        }),
+    )
   }
 
   /** Pure factory that constructs per-type listeners and adapters from connector configs. */
   get factory(): FunnelConnectorFactory {
-    return new FunnelConnectorFactory({
-      fs: this.props.fs,
-      process: this.props.process,
-      logger: this.props.logger,
-      dir: this.props.dir,
-    })
+    return this.memo(
+      "factory",
+      () =>
+        new FunnelConnectorFactory({
+          fs: this.fs,
+          process: this.process,
+          logger: this.logger,
+          dir: this.paths.dir,
+        }),
+    )
   }
 
   /** Channel CRUD + nested connector CRUD + schedule entries + listener/adapter dispatch. */
   get channels(): FunnelChannels {
-    return new FunnelChannels({
-      store: this.store,
-      factory: this.factory,
-      profileChecker: this.profiles,
-      clock: this.props.clock,
-      idGenerator: this.props.idGenerator,
-    })
+    return this.memo(
+      "channels",
+      () =>
+        new FunnelChannels({
+          store: this.store,
+          factory: this.factory,
+          profileChecker: this.profiles,
+          clock: this.clock,
+          idGenerator: this.idGenerator,
+        }),
+    )
   }
 
   /** Launch profiles (named presets for `fnl claude`: path + sub-agent + channel id). */
   get profiles(): FunnelProfiles {
-    return new FunnelProfiles({ store: this.store })
+    return this.memo("profiles", () => new FunnelProfiles({ store: this.store }))
   }
 
   /** funnel MCP installer (writes/removes `.mcp.json` entries in target repos). */
   get mcp(): FunnelMcp {
-    return new FunnelMcp({ fs: this.props.fs })
+    return this.memo("mcp", () => new FunnelMcp({ fs: this.fs }))
   }
 
   /** Launch Claude Code with a channel injected via env, MCP installed, gateway ensured. */
   get claude(): FunnelClaude {
-    return new FunnelClaude({
-      channels: this.channels,
-      mcp: this.mcp,
-      gateway: this.gateway,
-      fs: this.props.fs,
-      process: this.props.process,
-      logger: this.props.logger,
-      dir: this.props.dir,
-    })
+    return this.memo(
+      "claude",
+      () =>
+        new FunnelClaude({
+          channels: this.channels,
+          mcp: this.mcp,
+          gateway: this.gateway,
+          fs: this.fs,
+          process: this.process,
+          logger: this.logger,
+          dir: this.paths.dir,
+        }),
+    )
   }
 
   /** Gateway daemon controller (PID-file, start/stop the separate `bun daemon.ts` process). */
   get gateway(): FunnelGateway {
-    return new FunnelGateway({
-      fs: this.props.fs,
-      process: this.props.process,
-      clock: this.props.clock,
-      dir: this.props.dir,
-      tmpDir: this.props.tmpDir,
-    })
+    return this.memo(
+      "gateway",
+      () =>
+        new FunnelGateway({
+          fs: this.fs,
+          process: this.process,
+          clock: this.clock,
+          dir: this.paths.dir,
+          tmpDir: this.paths.tmpDir,
+        }),
+    )
   }
 
   /** Read / generate the daemon's gateway token (mode 0600 file under `dir`). */
   get gatewayToken(): FunnelGatewayToken {
-    return new FunnelGatewayToken({ fs: this.props.fs, dir: this.props.dir })
+    return this.memo(
+      "gatewayToken",
+      () => new FunnelGatewayToken({ fs: this.fs, dir: this.paths.dir }),
+    )
+  }
+
+  /**
+   * HTTP client for `POST /channels/:channel/publish` on the running gateway
+   * daemon. Use it to push arbitrary content into a channel from outside any
+   * connector. Returns `{ state: "offline" }` if the daemon isn't up.
+   */
+  get publisher(): FunnelChannelPublisher {
+    return this.memo("publisher", () => {
+      const gateway = this.gateway
+      const token = this.gatewayToken
+
+      return new FunnelChannelPublisher({
+        port: gateway.getPort(),
+        isDaemonRunning: () => gateway.isRunning(),
+        getToken: () => token.read(),
+      })
+    })
   }
 
   /**
@@ -148,13 +253,15 @@ export class Funnel {
    * paths stay write-only without parsing strings.
    */
   get listeners(): FunnelListenersClient {
-    const gateway = this.gateway
-    const token = this.gatewayToken
+    return this.memo("listeners", () => {
+      const gateway = this.gateway
+      const token = this.gatewayToken
 
-    return new FunnelListenersClient({
-      port: gateway.getPort(),
-      isDaemonRunning: () => gateway.isRunning(),
-      getToken: () => token.read(),
+      return new FunnelListenersClient({
+        port: gateway.getPort(),
+        isDaemonRunning: () => gateway.isRunning(),
+        getToken: () => token.read(),
+      })
     })
   }
 
@@ -177,9 +284,9 @@ export class Funnel {
       settings: this.store,
       port: options.port,
       logDir: options.logDir,
-      process: this.props.process,
-      clock: this.props.clock,
-      logger: this.props.logger,
+      process: this.process,
+      clock: this.clock,
+      logger: this.logger,
       killCompetingSlack: options.killCompetingSlack,
       token: options.token ?? this.gatewayToken.ensure(),
     })

package/lib/gateway/broadcaster.ts

@@ -1,4 +1,4 @@
-import type { ServerWebSocket } from "bun"
+import { type ServerWebSocket } from "bun"
 import { FunnelLogger } from "@/engine/logger/logger"
 import { NoopFunnelLogger } from "@/engine/logger/noop-logger"
 

package/lib/gateway/channel-publisher.ts

@@ -0,0 +1,67 @@
+import {
+  publishResponseSchema,
+  type PublishRequest,
+  type PublishResult,
+} from "@/gateway/publish-schema"
+
+type Deps = {
+  port: number
+  isDaemonRunning: () => boolean
+  /** Returns the daemon's gateway token, or null if unavailable. Sent as `Authorization: Bearer`. */
+  getToken?: () => string | null
+}
+
+const OFFLINE: PublishResult = { state: "offline" }
+
+/**
+ * HTTP client for `POST /channels/:channel/publish` on a running gateway
+ * daemon. Returns `{ state: "offline" }` when the daemon isn't up so callers
+ * can branch without exceptions, mirroring `FunnelListenersClient`.
+ */
+export class FunnelChannelPublisher {
+  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 publish(channelName: string, request: PublishRequest): Promise<PublishResult> {
+    if (!this.isDaemonRunning()) return OFFLINE
+
+    try {
+      const url = `http://localhost:${this.port}/channels/${encodeURIComponent(channelName)}/publish`
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { ...this.authHeaders(), "content-type": "application/json" },
+        body: JSON.stringify(request),
+      })
+
+      if (!res.ok) {
+        const text = await res.text()
+
+        return { state: "error", reason: text || `HTTP ${res.status}` }
+      }
+
+      const parsed = publishResponseSchema.safeParse(await res.json())
+
+      if (!parsed.success) {
+        return { state: "error", reason: "malformed daemon response" }
+      }
+
+      return { state: "ok", offset: parsed.data.offset }
+    } catch (error) {
+      return { state: "error", reason: error instanceof Error ? error.message : String(error) }
+    }
+  }
+
+  private authHeaders(): Record<string, string> {
+    const token = this.getToken()
+
+    return token ? { authorization: `Bearer ${token}` } : {}
+  }
+}

package/lib/gateway/gateway-server.ts

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync } from "node:fs"
 import { join } from "node:path"
-import type { Server, ServerWebSocket } from "bun"
+import { type Server, type ServerWebSocket } from "bun"
 import type { Hono } from "hono"
 import type { FunnelChannels } from "@/engine/channels/channels"
 import { constantTimeEqual, requireBearerToken } from "@/gateway/auth-middleware"
@@ -104,8 +104,9 @@ export class FunnelGatewayServer {
     this.supervisor = new FunnelListenerSupervisor({
       channels: this.channels,
       logger: this.logger,
-      notify: (channelName, connectorName, content, meta) =>
-        this.notify(channelName, connectorName, content, meta),
+      notify: async (channelName, connectorName, content, meta) => {
+        this.emit({ channel: channelName, connector: connectorName, content, meta })
+      },
       now: this.nowMs,
     })
   }
@@ -278,6 +279,7 @@ export class FunnelGatewayServer {
         supervisor: this.supervisor,
         channels: this.channels,
         uptimeMs: () => (this.startedAt ? this.nowMs() - this.startedAt : 0),
+        emit: (input) => this.emit(input),
       })
 
       return next()
@@ -371,32 +373,42 @@ export class FunnelGatewayServer {
     this.logger.info("funnel gateway running")
   }
 
-  private async notify(
-    channelName: string,
-    connectorName: string,
-    content: string,
-    meta?: Record<string, string>,
-  ): Promise<void> {
-    const channelId = this.lookupChannelId(channelName)
-    const connectorId = channelId ? this.lookupConnectorId(channelId, connectorName) : null
+  /**
+   * Broadcast `content` to subscribers of `channel`, persisting the event in
+   * the SQLite store and stamping `meta.channel{,Id}` / `meta.connector{,Id}`
+   * when they resolve. Used by both the connector-listener path (via the
+   * supervisor's `notify` callback) and the public `/channels/:channel/publish`
+   * route. Returns the assigned event offset.
+   */
+  emit(input: {
+    channel: string
+    connector?: string
+    content: string
+    meta?: Record<string, string>
+  }): { offset: number } {
+    const channelId = this.lookupChannelId(input.channel)
+    const connectorId =
+      channelId && input.connector ? this.lookupConnectorId(channelId, input.connector) : null
     const enriched: Record<string, string> = {
-      ...meta,
-      channel: channelName,
-      connector: connectorName,
+      ...input.meta,
+      channel: input.channel,
     }
 
+    if (input.connector) enriched.connector = input.connector
     if (channelId) enriched.channelId = channelId
     if (connectorId) enriched.connectorId = connectorId
 
-    const event = this.broadcaster.broadcast(content, enriched)
+    const event = this.broadcaster.broadcast(input.content, enriched)
 
     this.eventStore.record({
-      content,
+      content: input.content,
       channelId: channelId ?? null,
       connectorId: connectorId ?? null,
       meta: enriched,
       offset: event.offset,
     })
+
+    return { offset: event.offset }
   }
 
   private lookupChannelId(channelName: string): string | null {

package/lib/gateway/publish-schema.ts

@@ -0,0 +1,27 @@
+import { z } from "zod"
+
+/**
+ * Shared schema for `POST /channels/:channel/publish` — used by both the
+ * gateway route handler (input validation) and the CLI / programmable client
+ * (request shape). The route resolves `channel` from the path; this body
+ * covers everything else.
+ */
+export const publishRequestSchema = z.object({
+  content: z.string().min(1),
+  meta: z.record(z.string(), z.string()).optional(),
+  connector: z.string().min(1).optional(),
+})
+
+export type PublishRequest = z.infer<typeof publishRequestSchema>
+
+export const publishResponseSchema = z.object({
+  ok: z.literal(true),
+  offset: z.number().int().nonnegative(),
+})
+
+export type PublishResponse = z.infer<typeof publishResponseSchema>
+
+export type PublishResult =
+  | { state: "ok"; offset: number }
+  | { state: "offline" }
+  | { state: "error"; reason: string }

package/lib/gateway/routes/channels.publish.ts

@@ -0,0 +1,44 @@
+import { zValidator } from "@hono/zod-validator"
+import { z } from "zod"
+import { factory } from "@/gateway/factory"
+import { publishRequestSchema } from "@/gateway/publish-schema"
+import type { PublishResponse } from "@/gateway/publish-schema"
+import { zParam } from "@/gateway/routes/validator"
+
+/**
+ * POST /channels/:channel/publish
+ *
+ * Inject arbitrary content into a channel. Mirrors the connector-driven `notify`
+ * path: events go through `broadcaster.broadcast` + `eventStore.record`, so
+ * subscribers see them exactly as if a listener had produced them.
+ *
+ * Body validation is Zod-shared with the client (`publishRequestSchema`); the
+ * response (`publishResponseSchema`) carries the assigned offset so callers can
+ * correlate with the persistent event store.
+ */
+export const channelsPublishHandler = factory.createHandlers(
+  zParam(z.object({ channel: z.string().min(1) })),
+  zValidator("json", publishRequestSchema, (result, c) => {
+    if (result.success) return
+
+    const issue = result.error.issues[0]
+    const reason = issue ? `${issue.path.join(".")}: ${issue.message}` : "invalid body"
+
+    return c.json({ ok: false, reason }, 400)
+  }),
+  (c) => {
+    const param = c.req.valid("param")
+    const body = c.req.valid("json")
+
+    const event = c.var.deps.emit({
+      channel: param.channel,
+      connector: body.connector,
+      content: body.content,
+      meta: body.meta,
+    })
+
+    const response: PublishResponse = { ok: true, offset: event.offset }
+
+    return c.json(response)
+  },
+)

package/lib/gateway/routes/index.ts

@@ -1,5 +1,6 @@
 import { factory } from "@/gateway/factory"
 import { channelsConnectorsCallHandler } from "@/gateway/routes/channels.connectors.call"
+import { channelsPublishHandler } from "@/gateway/routes/channels.publish"
 import { healthHandler } from "@/gateway/routes/health"
 import { listenersListHandler } from "@/gateway/routes/listeners.list"
 import { listenersRestartHandler } from "@/gateway/routes/listeners.restart"
@@ -22,3 +23,4 @@ export const gatewayRoutes = factory
   .delete("/listeners/:channel/:connector", ...listenersStopHandler)
   .post("/listeners/:channel/:connector/restart", ...listenersRestartHandler)
   .post("/channels/:channel/connectors/:connector/call", ...channelsConnectorsCallHandler)
+  .post("/channels/:channel/publish", ...channelsPublishHandler)

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

@@ -2,10 +2,18 @@ import type { FunnelChannels } from "@/engine/channels/channels"
 import type { FunnelBroadcaster } from "@/gateway/broadcaster"
 import type { FunnelListenerSupervisor } from "@/gateway/listener-supervisor"
 
+export type GatewayEmitInput = {
+  channel: string
+  connector?: string
+  content: string
+  meta?: Record<string, string>
+}
+
 export type GatewayRouteDeps = {
   selfPid: number
   broadcaster: FunnelBroadcaster
   supervisor: FunnelListenerSupervisor
   channels: FunnelChannels
   uptimeMs: () => number
+  emit: (input: GatewayEmitInput) => { offset: number }
 }

package/lib/index.ts

@@ -8,6 +8,7 @@ export * from "@/funnel"
 export * from "@/engine/channels/channels"
 export * from "@/engine/claude/claude"
 export * from "@/engine/mcp/mcp"
+export * from "@/engine/mcp/channel-server"
 export * from "@/engine/profiles/profiles"
 export * from "@/engine/settings/settings-reader"
 export * from "@/engine/settings/settings-store"
@@ -39,12 +40,28 @@ export * from "@/engine/id/memory-id-generator"
 // Connectors
 export * from "@/connectors/connector-factory"
 export * from "@/connectors/connector-config-schema"
+export * from "@/connectors/connector-listener"
+export * from "@/connectors/discord-connector-schema"
+export * from "@/connectors/gh-connector-schema"
 export * from "@/connectors/schedule-connector-schema"
+export * from "@/connectors/slack-connector-schema"
 
 // Gateway
 export * from "@/gateway/gateway"
 export * from "@/gateway/gateway-server"
+export * from "@/gateway/gateway-token"
 export * from "@/gateway/broadcaster"
+export * from "@/gateway/channel-publisher"
 export * from "@/gateway/funnel-event-store"
 export * from "@/gateway/listener-supervisor"
 export * from "@/gateway/listeners-client"
+export * from "@/gateway/publish-schema"
+
+// CLI — embeddable Hono app + argv translator
+export * from "@/cli/factory"
+export * from "@/cli/router/to-request"
+export * from "@/cli/router/query-to-cli-args"
+export { app as cliApp, createCliApp } from "@/cli/routes"
+
+// TUI — launcher (consumers can spawn the OpenTUI dashboard with their own Funnel)
+export * from "@/tui/tui"