@interactive-inc/claude-funnel 0.28.0 → 0.30.0

package/README.md

@@ -42,7 +42,7 @@ Connector — a single attachment from a channel to an external source. Four typ
 
 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.
+The daemon is where all external connections live. It runs on port 9742, bound to loopback (`127.0.0.1`) only so it is never reachable off-box; set `FUNNEL_HOST=0.0.0.0` to expose it deliberately (every privileged endpoint still requires the bearer token regardless). It 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.
 
 The MCP layer is a thin bridge into the agent. It subscribes to the bound channel over WebSocket (the daemon does the work) and exposes one tool per callable connector so the agent can reply back out.
 
@@ -102,11 +102,7 @@ Or drop a `funnel.json` in the repo and `fnl claude` (no args) inside the repo w
       "connectors": [
         {
           "type": "slack",
-          "name": "my-slack",
-          "env": {
-            "botToken": "SLACK_BOT_TOKEN",
-            "appToken": "SLACK_APP_TOKEN"
-          }
+          "name": "my-slack"
         }
       ]
     },
@@ -132,21 +128,18 @@ Or drop a `funnel.json` in the repo and `fnl claude` (no args) inside the repo w
 
 A channel declares only transport — its `connectors` and delivery mode. The launch recipe lives on `profiles[]`: each profile binds to a channel by name and carries `options` (prepended to the claude argv before user-supplied CLI args, which still come last — use it for flags like `--brief`, `--agent <name>`, `--model <name>`), `env` (layered under the launched claude process — `process.env` from the launching shell wins on collision), and `resume`. `fnl claude` applies the first profile bound to the chosen channel.
 
-The optional `connectors` array on a channel is the source of truth for that channel: missing connectors are created, an existing connector matched by token under a different name is renamed in place, and connectors not declared are removed on launch. An absent `connectors` field leaves `~/.funnel` alone.
+The optional `connectors` array on a channel is the source of truth for that channel: missing connectors are created and connectors not declared are removed on launch. Connectors are matched by name. An absent `connectors` field leaves existing connectors alone.
 
-On launch, the chosen channel's transport (`connectors`, delivery) is materialized into the global `~/.funnel/settings.json` Channel entry; the profile recipe is passed straight to the launcher and is not persisted there. Raw launches (`fnl claude --channel <name>` without funnel.json) bind transport only and carry no recipe.
+A repo with a `funnel.json` is scoped to itself. On first launch funnel writes a stable `id` (uuid) to the top of `funnel.json` and keeps every byte of funnel state under `~/.funnel/projects/<id>/`, never touching the global `~/.funnel` — only the event log and temp files under `/tmp/funnel/` are shared. This scoping applies to every CLI command run in the repo, not just `fnl claude`. On launch the chosen channel's transport (`connectors`, delivery) is materialized into `~/.funnel/projects/<id>/settings.json`; the profile recipe is passed straight to the launcher and is not persisted there. Raw launches (`fnl claude --channel <name>` without funnel.json) bind transport only against the global `~/.funnel` and carry no recipe.
 
 The optional top-level `$schema` points at the JSON Schema so editors can validate and autocomplete the file. The recommended reference for repos with a local install is `./node_modules/@interactive-inc/claude-funnel/funnel.schema.json` — it works without a network round-trip and editors do not need to prompt for trust. The same file is also published at `https://interactive-inc.github.io/open-claude-funnel/funnel.schema.json` (editors usually require explicit trust on first use), and `fnl schema > funnel.schema.json` regenerates a local copy on demand.
 
-Each token field resolves in this order:
+Connectors in `funnel.json` carry no tokens. A connector's token is set out of band and stored only in the repo-scoped settings:
 
-- literal value at the field itself (e.g. `"botToken": "xoxb-..."`) — used as-is
-- env-var name at `env.<field>` (e.g. `"env": { "botToken": "SLACK_BOT_TOKEN" }`) — looked up in `process.env`, falling back to `./.env.local` in the cwd; fails with a clear error when neither is set
-- field omitted everywhere — `fnl claude` prompts on a TTY and writes the answer to `~/.funnel/settings.json`; on non-TTY stdin the launch fails so CI / agent-spawned-agent runs do not hang
+- run `fnl channels <ch> connectors set <c> --bot-token=...` (etc.) in the repo to write it to `~/.funnel/projects/<id>/settings.json`
+- or omit it — `fnl claude` prompts on a TTY at launch and saves the answer there; it carries over so later launches do not re-prompt. On non-TTY stdin the launch fails so CI / agent-spawned-agent runs do not hang
 
-Setting both a literal and an `env.<field>` for the same field is an error (pick one).
-
-`funnel.json` itself is never written to — secrets stay in env vars, `.env.local`, or `~/.funnel`, never in the committed file.
+Only the `id` is ever written back to `funnel.json`; tokens never live in the repo.
 
 Cron-driven agent runs:
 
@@ -271,21 +264,23 @@ Profile    = { id, name, path, channelId, options[], env, resume, sessionId? }
         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[] }
+LocalConfig = { id?, channels: ChannelSpec[], profiles?: ProfileSpec[] }
         per-repo file (funnel.json). channels[] required; first entry is default, --channel selects.
+        id (uuid) is written back on first launch; this repo's funnel state lives under
+        ~/.funnel/projects/<id>/ and the global ~/.funnel is never touched.
 
 ChannelSpec = { name, connectors? }
         transport declaration (no id, since funnel.json declares by name). connectors materialize into
-        the matching Channel in ~/.funnel/settings.json on launch. Connector token fields accept a
-        literal, an env-var reference at `env.<field>` resolved from process.env and ./.env.local, or
-        omission for a TTY prompt persisted to ~/.funnel.
+        the matching Channel in ~/.funnel/projects/<id>/settings.json on launch. Connectors carry no
+        tokens; a token is set via the CLI or prompted on a TTY at launch and saved to that scoped settings.
 
 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 — selected by its channel binding, not by name); not persisted into the global
         profiles[] list.
 
-Settings   = { channels[], profiles[] }                 → ~/.funnel/settings.json
+Settings   = { channels[], profiles[] }                 → ~/.funnel/settings.json (global)
+                                                          or ~/.funnel/projects/<id>/settings.json (per-repo funnel.json)
 ```
 
 ## File layout
@@ -294,7 +289,10 @@ Persistent state lives under `~/.funnel/`. Volatile logs and the event log live
 
 ```
 ~/.funnel/
-├── settings.json                                       channels[] with nested connectors, profiles[]
+├── settings.json                                       global channels[] with nested connectors, profiles[]
+├── projects/
+│   └── <id>/                                           per-repo state for a repo with funnel.json
+│       └── settings.json, gateway.token, claude/, ...  (same layout as the global root, scoped by funnel.json id)
 ├── gateway.pid                                         daemon PID
 ├── gateway.token                                       Bearer token for daemon HTTP / WS
 ├── claude/