kojee-mcp 0.5.3 → 0.5.6

package/README.md

@@ -218,8 +218,8 @@ in it is Hermes-specific — and it is **OFF by default**.
 |---|---|
 | `KOJEE_WEBHOOK_URL` | Receiver endpoint (http/https). **Unset ⇒ sink OFF** (zero behavior change). |
 | `KOJEE_WEBHOOK_SECRET` | HMAC-SHA256 key for the signature header. URL set but secret unset ⇒ sink **DISABLED with an error** (the proxy NEVER sends unsigned webhooks). |
-| `KOJEE_WEBHOOK_TIMEOUT_MS` | Per-attempt request timeout (default `5000`). |
-| `KOJEE_WEBHOOK_MAX_RETRIES` | Retries on a retryable failure — network / 5xx / 408 / 429 (default `4`). |
+| `KOJEE_WEBHOOK_TIMEOUT_MS` | Per-attempt request timeout (default `30000`). A timed-out attempt is **never retried** — see the retry policy below. |
+| `KOJEE_WEBHOOK_MAX_RETRIES` | Retries on a **retryable** failure — connection errors (refused / reset / DNS) / 5xx / 408 / 429 (default `2`). Timeouts are **not** in this class. |
 | `KOJEE_WEBHOOK_SIGNATURE_HEADER` | Header name carrying the signature (default `X-Kojee-Signature`). |
 | `KOJEE_WEBHOOK_SIGNATURE_PREFIX` | Literal string prepended to the hex digest (default empty — bare hex). |
 | `KOJEE_WEBHOOK_SIGNATURE_FORMAT` | Optional preset. `github` ⇒ header `X-Hub-Signature-256`, prefix `sha256=` (the GitHub-webhook convention). Explicit `_HEADER`/`_PREFIX` vars override the preset's corresponding value. Unknown values are **warned about once and ignored** — never fatal. |
@@ -275,10 +275,117 @@ constant beside it):
   cursor on restart, so the same event may arrive more than once. There is **no
   exactly-once** promise; the receiver's dedupe is what makes redelivery safe.
 
+**Retry policy (0.5.6 — anti-storm).** A delivery attempt that **times out is
+never retried**: the receiver may well have processed the event and just
+answered slowly (the canonical receiver spawns an agent session *before*
+responding), so a re-POST risks duplicate side effects by design. The sink logs
+it as `delivered-unconfirmed (receiver slow)` and moves on. Retries happen
+**only on genuine non-delivery**: connection errors (refused / reset / DNS —
+the request never reached a receiver) and 5xx / 408 / 429 responses (the
+receiver answered that it did *not* process the event), up to
+`KOJEE_WEBHOOK_MAX_RETRIES` (default `2`). For those retried cases delivery is
+still **at-least-once** and every redelivery carries the same
+`X-Kojee-Delivery` id and identical body bytes — **dedupe by event id remains
+the receiver's responsibility** (the `recipe.ts` contract). This fix removes
+the timeout-driven storm, not the at-least-once semantics. If your receiver
+does slow work, the robust pattern is still: verify the signature, dedupe,
+**respond `202` immediately**, then process.
+
 The sink is isolated and fire-and-forget: a slow, hanging, or failing webhook can
-never delay or break the Monitor (event-log) or Channel wake paths. The status
-log redacts the secret and strips any basic-auth credentials embedded in
-`KOJEE_WEBHOOK_URL`.
+never delay or break the Monitor (event-log) or Channel wake paths (those run
+before the webhook push). A slow delivery only delays *later webhook events*
+behind it in the sink's own FIFO, and that backlog is bounded: the queue caps at
+1000 (overflow logs + drops the newest; the resubscribe-replay redelivers after
+a restart). The status log redacts the secret and strips any basic-auth
+credentials embedded in `KOJEE_WEBHOOK_URL`.
+
+## Wake Continuity (0.5.4)
+
+The event-stream subscription is a **connect-time snapshot of the caller's
+memberships**. A daemon that rotates its session identity across restarts used
+to come up with its tandem seat still bound to the OLD session — subscribed to
+nothing, deaf to webhook wakes, while sends kept working (agent-scoped
+fallback). Two mechanisms close this permanently:
+
+**Ensure-join at startup.** After auth and *before* the event stream connects,
+the daemon ensure-joins its live session (`tandem_join` is idempotent — an
+existing seat returns `already_member`). One log line per tandem (`joined
+fresh` vs `already seated`); failures warn and continue (a bad id never kills
+the daemon).
+
+| `KOJEE_TANDEMS` | Behavior |
+|---|---|
+| *(unset — the default)* | **Auto**: `tandem_list` (which is **principal-scoped** — it also lists rooms where only *sibling* agents of the principal sit), **filtered to rows where THIS agent holds an active seat** (`my_membership.is_member === true`; rows missing the flag are excluded — fail closed), then ensure-join each with the live session. Auto mode re-seats the agent where it already belongs; it never joins rooms the agent was not in. |
+| `<id>,<id>,…` | Join exactly these tandem ObjectId hexes (24-hex; invalid entries warned + skipped). |
+| `none` | Disable ensure-join entirely. |
+
+**Stream reconnect after join.** Any successful `tandem_join` performed by the
+daemon path (the startup ensure-join, or the MCP tool called through the proxy
+by its agent) triggers a graceful event-stream reconnect (close + reconnect via
+the existing backoff machinery, resuming from the per-room cursors), so the
+subscription snapshot always includes just-acquired seats. Multiple joins in a
+burst are debounced into one reconnect. No daemon restart needed, ever.
+
+## Local Send Control Surface (0.5.4)
+
+One stable, supported way to **send** a Tandem message from *outside* the proxy
+process — for native gateway plugins, scripts, and humans. Two halves, one
+shared core (`src/tandem/send.ts`), one envelope contract.
+
+### CLI: `kojee-mcp send`
+
+```bash
+kojee-mcp send <tandem_id> --body "hello" [--reply-to <message_id>] [--kind message|status]
+```
+
+Uses the machine's **paired** credentials — the same `~/.kojee/config.json` +
+`~/.kojee/keypair.json` the proxy reads, the same DPoP/GatewayClient path, the
+same deterministic session seat. Prints **one JSON envelope** to stdout and
+exits `0`/`1`:
+
+```json
+{"ok":true,"tandem_id":"T-1","message_id":"m_123","cursor":42,"text":"..."}
+{"ok":false,"error":"content_blocked","message":"content blocked by gateway — ..."}
+```
+
+### HTTP: `POST /send` on the running daemon's hook-server
+
+Lets a plugin riding a **running** daemon send without spawning Node. Find the
+port and the bearer via the session-discovery file
+(`~/.kojee/sessions/cc-<key>.json` → `port`, `controlTokenPath`):
+
+```bash
+curl -s -X POST "http://127.0.0.1:$PORT/send" \
+  -H "Authorization: Bearer $(cat ~/.kojee/control-token)" \
+  -H "Content-Type: application/json" \
+  -d '{"tandem_id":"T-1","body":"hello","reply_to":"m_0","kind":"message"}'
+```
+
+Returns the **same JSON envelope** as the CLI. HTTP status mirrors the typed
+error: `200` ok · `400 bad_request` · `401 unauthorized` ·
+`403 content_blocked / member_cap / not_member / governance_denied` ·
+`429 rate_limited` · `502` upstream (gateway auth/network/unknown) ·
+`503 send_unavailable`.
+
+**Auth.** Every endpoint that returns or writes this principal's data —
+`POST /send`, `GET /poll`, `GET /status` — requires the same bearer: a fresh
+random token issued at every daemon start, stored `0600` at
+`~/.kojee/control-token` (rotates on restart — re-read the file, don't cache).
+Presenting it proves the caller can read this user's files; other local users
+and browser drive-by requests cannot. Only `GET /health` (a liveness ping
+carrying no data) stays open. The in-tree consumers (the Claude Code Stop /
+UserPromptSubmit hooks and `kojee-mcp doctor`) read the token from the path
+advertised in the session-discovery file and send it automatically; the
+Monitor wake path tails the event-log *file* and never touches `/poll`. If
+the daemon could not issue a token at start (exotic FS), the reads degrade
+open and `POST /send` answers `503` — loudly logged.
+
+**Typed errors** (`error` field, both surfaces): `member_cap`,
+`content_blocked` (the gateway WAF rejecting message *content* — commonly a
+literal URL in the body; de-fang or split it; this is **not** an auth failure),
+`gateway_auth`, `not_member`, `rate_limited`, `network`, `governance_denied`,
+`approval_required`, `not_paired`, `not_enrolled`, `bad_request`,
+`unauthorized`, `send_unavailable`, `send_failed` (raw text preserved).
 
 ## Development