@interactive-inc/claude-funnel 0.25.1 → 0.26.0

package/README.md

@@ -34,13 +34,13 @@ external sources                          outbound replies
                      agent  (subscribes to one channel)
 ```
 
-Three concepts make up the model:
+Two concepts make up the transport model:
 
 Channel — a named subscription box (transport only). Holds one or more connectors and a delivery mode; it does not carry launch flags. An agent session subscribes to exactly one channel. Delivery is `fanout` (every subscriber sees every event, the default) or `exclusive` (one event per subscriber, round-robin — for worker pools).
 
 Connector — a single attachment from a channel to an external source. Four types ship today: `slack`, `gh`, `discord`, `schedule`. The first three are bidirectional (events in, replies out); `schedule` is one-way (cron ticks in).
 
-Profile — a saved launch preset. Bundles `{ path, channelId, options, env, resume }` so `fnl claude --profile cto` reproduces a known setup: which directory to launch from, which channel to bind, and the launch recipe (args prepended to the claude argv, env layered under the process, session reuse). The first profile in the list is the default.
+Profile sits on top of that model as a launch convenience, not part of it — you never need one to run an agent (`fnl claude --channel <name>` is enough). It is a saved launch preset bundling `{ path, channelId, options, env, resume }` so `fnl claude --profile cto` reproduces a known setup: which directory to launch from, which channel to bind, and the launch recipe (args prepended to the claude argv, env layered under the process, session reuse). A profile carries a stable uuid `id` (the unit the PID file and the resumable session key off, so renaming it strands neither); `name` is just the handle you type. The first profile in the list is the default. Because a profile already binds a channel, `--profile` and `--channel` cannot be combined.
 
 The daemon is where all external connections live. It runs on port 9742, supervises connectors with auto-restart, broadcasts events to subscribed agent sessions over WebSocket, and serves the reply API that MCP calls. Starting or stopping an agent never starts or stops external connections.
 
@@ -116,13 +116,11 @@ Or drop a `funnel.json` in the repo and `fnl claude` (no args) inside the repo w
   ],
   "profiles": [
     {
-      "name": "ops-pm",
       "channel": "ops",
       "options": ["--brief", "--agent", "pm"],
       "env": { "ANTHROPIC_MODEL": "claude-sonnet-4-6" }
     },
     {
-      "name": "review-reviewer",
       "channel": "review",
       "options": ["--agent", "reviewer"]
     }
@@ -208,7 +206,7 @@ fnl profiles remove <name>
 
 fnl claude                                   launch the first channel from ./funnel.json, or the default profile
 fnl claude --channel <name>                  with funnel.json: pick that channel; without: raw launch
-fnl claude --profile <name>                  launch a named profile (ignores funnel.json)
+fnl claude --profile <name>                  launch a named profile (ignores funnel.json; cannot combine with --channel)
 fnl claude [...]                             positionals and any flag other than -p / --profile / --channel
                                               (e.g. --agent, --resume, -c, --model) pass through to claude
 fnl mcp                                      run as an MCP server (invoked from .mcp.json)
@@ -265,10 +263,13 @@ Connector  =
   | { type: "discord",  name, botToken }                Discord Gateway
   | { type: "schedule", name, entries[] }               cron-driven; entries = { id, cron, prompt, enabled?, catchupPolicy? }
 
-Profile    = { name, path, channelId, options[], env, resume }
+Profile    = { id, name, path, channelId, options[], env, resume, sessionId? }
         named launch preset: where to launch (path), which channel to bind, and the launch recipe —
         options[] prepends to the claude argv, env layers under the process (process.env wins on
-        collision), resume toggles session reuse. the first profile is the default.
+        collision), resume toggles session reuse. the first profile is the default. id is a stable
+        uuid (the key the PID file and resumable session hang off, so a rename strands neither);
+        name is the CLI handle. sessionId is execution state, not config — the claude session this
+        profile last launched, written by the launcher and read back on the next resume.
 
 LocalConfig = { channels: ChannelSpec[], profiles?: ProfileSpec[] }
         per-repo file (funnel.json). channels[] required; first entry is default, --channel selects.
@@ -279,16 +280,17 @@ ChannelSpec = { name, connectors? }
         literal, an env-var reference at `env.<field>` resolved from process.env and ./.env.local, or
         omission for a TTY prompt persisted to ~/.funnel.
 
-ProfileSpec = { name, channel, options?, env?, resume? }
+ProfileSpec = { channel, options?, env?, resume? }
         launch recipe bound to a channel by name. applied inline on launch (the first spec bound to the
-        chosen channel); not persisted into the global profiles[] list.
+        chosen channel — selected by its channel binding, not by name); not persisted into the global
+        profiles[] list.
 
 Settings   = { channels[], profiles[] }                 → ~/.funnel/settings.json
 ```
 
 ## File layout
 
-Persistent state lives under `~/.funnel/`. Volatile logs and the event store live under `/tmp/funnel/`.
+Persistent state lives under `~/.funnel/`. Volatile logs and the event log live under `/tmp/funnel/`.
 
 ```
 ~/.funnel/
@@ -296,7 +298,7 @@ Persistent state lives under `~/.funnel/`. Volatile logs and the event store liv
 ├── gateway.pid                                         daemon PID
 ├── gateway.token                                       Bearer token for daemon HTTP / WS
 ├── claude/
-│   └── <profile>.pid                                   prevents double-launch of the same profile
+│   └── <profile-id>.pid                                prevents double-launch of the same profile (keyed by profile id)
 └── channels/
     └── <channel-id>/
         └── connectors/
@@ -304,7 +306,7 @@ Persistent state lives under `~/.funnel/`. Volatile logs and the event store liv
                 └── state.json                          per-connector durable state (e.g. schedule lastFiredAt)
 
 /tmp/funnel/
-├── events.db                                           SQLite event store with replay-by-seq
+├── events.db                                           SQLite event log with replay-by-offset
 ├── funnel.log                                          diagnostic log (daemon lifecycle, listener boot, connects)
 └── gateway.log                                         daemon stdout/stderr
 ```
@@ -372,13 +374,21 @@ Run the gateway in-process (no daemon spawn — useful for tests or embedding):
 ```ts
 const server = funnel.gatewayServer({ port: 9742 })
 await server.start()                       // Bun.serve (HTTP + WS) + listener supervisor
-const unsubscribe = server.getBroadcaster().subscribe(({ content, meta }) => {
-  console.log(meta?.connector, content)
+const unsubscribe = server.onEvent(({ content, meta }) => {
+  console.log(meta?.connector, content)    // in-process observer for every broadcast event
 })
 await server.stop()
 unsubscribe()
 ```
 
+Persistence and replay live behind the `FunnelEventLog` port. The default is a `SqliteFunnelEventLog` (durable across daemon restarts: it seeds the broadcaster's offset and serves reconnect replay). Inject `MemoryFunnelEventLog` — or any `FunnelEventLog` — to swap or disable durable replay; `onEvent` is a separate, write-only observation hook and does not replace it:
+
+```ts
+import { MemoryFunnelEventLog } from "@interactive-inc/claude-funnel"
+
+const server = funnel.gatewayServer({ port: 9742, eventLog: new MemoryFunnelEventLog() })
+```
+
 The daemon exposes `/health`, `/status`, `/listeners*`, `/channels/:channel/connectors/:connector/call`, plus the `/ws?channel=<name>` WebSocket.
 
 ### Sandboxed Funnel