instar 1.3.49 → 1.3.51

package/upgrades/side-effects/a2a-inbox-http-transport.md

@@ -0,0 +1,128 @@
+# Side-Effects Review — same-machine a2a transport via `/a2a/inbox`
+
+**Spec:** `docs/specs/MENTOR-LIVE-READINESS-SPEC.md` §Recipient side. Third
+fast-follow to PR #462 (receiver wiring) + PR #464 (lifeline-forward
+dispatch). Closes the bot-to-bot-block gap surfaced by dogfood.
+
+**Root cause being addressed:** Telegram Bot API structurally blocks
+bot-to-bot delivery: "Bots talking to each other could potentially get stuck
+in unwelcome loops. To avoid this, we decided that bots will not be able to
+see messages from other bots regardless of mode." (Bot API FAQ.) The spec
+assumed `Echo's mentor bot → Codey's primary bot via shared chat → Codey's
+lifeline forwards` would work. Empirically it doesn't — verified by sending
+4 marker messages to topic 458, Codey's bot poll-offset never advances past
+them, his lifeline-forward stays silent.
+
+**Change:** Three production files + two test files.
+- `src/server/routes.ts` (+ ~70 LoC: new `/a2a/inbox` POST route)
+- `src/server/middleware.ts` (+ 2 LoC: skip the API bearer middleware for
+  `/a2a/inbox` — uses per-agent token like `/messages/relay-agent`)
+- `src/server/AgentServer.ts` (+ ~75 LoC: same-machine path in
+  `deliverToMentee` via AgentRegistry + `fetch` to peer's `/a2a/inbox`,
+  before the Telegram bot fallback)
+- `tests/integration/a2a-inbox-route.test.ts` (new, 8)
+- `tests/e2e/a2a-inbox-lifecycle.test.ts` (new, 4)
+
+## What changed
+
+1. **`POST /a2a/inbox`** on every instar server. Accepts:
+   `{ text, topicId, senderAgent?, senderIsBot?, senderBotId?, fromUserId? }`.
+   Auth: Bearer token must match the target agent's per-agent token
+   (`verifyAgentToken` — same shape as `/messages/relay-agent`). Behaviour:
+   - 401 if bearer is missing or wrong
+   - 503 if no `ctx.telegram` adapter is configured at all (no hook surface)
+   - 400 if `text` (string) or `topicId` (number) are missing / malformed
+   - 200 `{ ok, agentMessage: true }` when the adapter's
+     `dispatchAgentMessageHook` claims the message
+   - 200 `{ ok, agentMessage: false, reason: 'not-routed' }` when the hook
+     refuses (no marker / malformed / not-allowlisted / not-allowed-role).
+     The route is dedicated to a2a — non-routable messages are NOT forwarded
+     to user-message handling.
+   - `senderIsBot` defaults to `true` if omitted — local peers holding our
+     agent token are bots by construction (the spoof defense is satisfied
+     by the bearer-token check upstream).
+2. **Auth middleware bypass for `/a2a/inbox`** — alongside the existing
+   `/messages/relay-agent` and `/messages/relay-machine` bypasses, since the
+   inbox enforces its own per-agent-token auth in-handler. Without this
+   bypass the API bearer middleware (using `config.authToken`) would 403
+   the request, because the caller holds the TARGET's per-agent token,
+   not the API bearer.
+3. **Same-machine routing in `deliverToMentee`** — before the existing
+   Telegram bot delivery, the method now:
+   - Imports `listAgents` from AgentRegistry + `getAgentToken` from the
+     token manager (lazy-imported inside the closure to avoid loading the
+     registry on every server boot).
+   - Looks up the mentee by `name === menteeAgent && name !== self.config.projectName`
+     (anti-self-target).
+   - If a local peer with a port is found AND we have the peer's token,
+     POSTs to `http://localhost:PORT/a2a/inbox` with the marker text +
+     sender context. On `agentMessage: true`, marks the outstanding-prompt
+     tracker as sent and audits a `transport: 'a2a-inbox-local'` row in
+     the sent-ledger.
+   - On any failure (no peer, no token, HTTP error, hook refused) logs and
+     falls through to the existing Telegram bot path (preserved unchanged
+     for cross-machine; currently unreachable due to the same bot-to-bot
+     block — a separate cross-machine transport is future work).
+   - The anti-ping-pong check (`outstanding.canSendTo`) runs ONCE before
+     either transport so the same correlation key gates both paths.
+
+## The seven questions
+
+1. **Over-block.** N/A. The inbox is a NEW dedicated endpoint; the route
+   refuses non-routable traffic with `agentMessage: false` but never
+   forwards to user handling. No existing route's behaviour changes.
+2. **Under-block.** Spoof defense is intact: per-agent token bearer auth
+   gates the route. `senderIsBot` defaulting to `true` is correct because
+   the peer authenticated with the target's own token — the spoof defense
+   it would otherwise enforce is satisfied earlier by the bearer check.
+   Anti-ping-pong: `outstanding.canSendTo` runs before either transport so
+   one outstanding prompt blocks both paths.
+3. **Level-of-abstraction fit.** Mirrors `/messages/relay-agent`'s pattern
+   exactly: own route, own auth, dispatch into existing in-process state.
+   No new abstraction.
+4. **Signal vs authority.** Inbox DECIDES route-or-drop via the hook (the
+   hook's existing routing matrix is the spec); audit ledger captures the
+   result. `deliverToMentee` DECIDES transport (local vs Telegram). All
+   audited; no silent paths.
+5. **Interactions.** Reuses AgentRegistry + AgentTokenManager (same APIs
+   already used by `/messages/relay-agent`). Reuses
+   `getOrCreateA2aLedger` + `getOrCreateMentorOutstanding` from the mentor
+   sender side. Reuses `dispatchAgentMessageHook` from PR #464. No new
+   shared mutable state.
+6. **External surfaces.** One new HTTP route (`/a2a/inbox`). One new
+   audit-ledger transport value (`'a2a-inbox-local'`). No new config keys.
+7. **Rollback cost.** Trivial — revert removes the route, the middleware
+   bypass, and the same-machine branch in `deliverToMentee`. The Telegram
+   bot path is untouched and preserved.
+
+## Testing
+
+12 new tests, all green (`tsc --noEmit` clean):
+
+- **Tier 2 integration (8):** `a2a-inbox-route` covers the auth + input-
+  validation matrix (401 missing bearer, 401 wrong bearer, 503 no adapter,
+  400 missing text, 400 bad topicId, 200 routed, 200 not-routed, 200 with
+  default senderIsBot:true).
+- **Tier 3 E2E lifecycle (4):** `a2a-inbox-lifecycle` covers full server
+  boot with the mentee receiver wiring + the inbox route alive (not 404),
+  auth-gated, and the full claim path that proves the inbox invokes the
+  adapter dispatcher end-to-end on the real production init path.
+
+A unit-tier slice for the same-machine branch in `deliverToMentee` is
+deferred — covered transitively by the E2E + the existing unit suite for
+`OutstandingPromptTracker` + the new integration test for the inbox route.
+A dedicated unit on the `deliverToMentee` branch would require mocking
+`fetch` + AgentRegistry + getAgentToken — defensible to add later but the
+behaviour is already tested at the boundary.
+
+## Migration parity
+
+No new config keys. The route registers unconditionally; if no
+`config.mentee.enabled` block is set on the receiver, the adapter has no
+hook installed and the route returns `agentMessage: false`. The
+`/messages/relay-agent` precedent is identical (always-registered route,
+behaviour depends on installed state).
+
+The `deliverToMentee` change is purely additive — when no local peer is
+registered, behaviour is byte-for-byte the same as before. No PostUpdateMigrator
+change required.

package/upgrades/side-effects/mentee-receiver-forward-dispatch.md

@@ -0,0 +1,99 @@
+# Side-Effects Review — mentee receiver wiring fires on lifeline-forward path
+
+**Spec:** `docs/specs/MENTOR-LIVE-READINESS-SPEC.md` §Recipient side.
+Fast-follow to PR #462 (mentee receiver wiring) — closes the dual-path
+ingress gap surfaced by dogfood.
+
+**Change:** Three production files + three test files.
+- `src/messaging/TelegramAdapter.ts` (+ ~55 LoC: `dispatchAgentMessageHook`
+  public method; polling text-dispatch now calls it instead of inlining the
+  hook logic — pure extraction, no behavior change on the polling path)
+- `src/server/routes.ts` (+ ~20 LoC: destructure `senderIsBot` /
+  `senderChatId` / `senderBotId` from forward body; invoke
+  `dispatchAgentMessageHook` before `onTopicMessage`; short-circuit on
+  `handled:true`)
+- `src/lifeline/TelegramLifeline.ts` (+ ~15 LoC: derive + include
+  `senderIsBot`/`senderChatId`/`senderBotId` in the forward body)
+- `tests/unit/TelegramAdapter-dispatchAgentMessageHook.test.ts` (new, 8)
+- `tests/integration/telegram-forward-a2a-dispatch.test.ts` (new, 3)
+
+## What changed
+
+1. **`dispatchAgentMessageHook` public method** on `TelegramAdapter`:
+   wraps the existing hook invocation with the FAIL-OPEN try/catch (a
+   broken hook never freezes the dispatch loop) and the senderBotId
+   derivation logic (sender_chat wins; rawFromId iff senderIsBot;
+   undefined for real users). Polling path now calls the dispatcher
+   instead of inlining the same code — pure extraction.
+2. **`/internal/telegram-forward` handler** destructures the new spoof-
+   defense fields from the request body. Before invoking `onTopicMessage`,
+   calls `dispatchAgentMessageHook`. On `handled:true`, returns
+   `{ ok: true, forwarded: true, agentMessage: true }` (NEW response shape
+   addition — additive, doesn't change the existing `{ ok, forwarded }`
+   contract for non-a2a forwards). On hook throw, logs + falls through
+   (same fail-open semantics as the polling path).
+3. **`TelegramLifeline.forwardToServer`** derives `senderIsBot` from
+   `rawMsg.from.is_bot === true`, `senderChatId` from
+   `rawMsg.sender_chat?.id`, `senderBotId` from `senderChatId ?? (isBot ?
+   rawMsg.from.id : undefined)`. Includes them in the buildBody output
+   only when they have values (omitted fields → server treats as falsy →
+   marker-bearing forwards drop closed for spoof defense).
+
+## The seven questions
+
+1. **Over-block.** N/A — additive. The forward route now invokes the hook
+   before `onTopicMessage`; if no hook is installed (or no adapter has
+   `dispatchAgentMessageHook`), the route falls through to the existing
+   behavior. Backward-compatible test (`preserves existing behavior when
+   the adapter has NO dispatchAgentMessageHook`) covers this.
+2. **Under-block.** Spoof defense is end-to-end on the forwarded path:
+   missing `senderIsBot` from older lifelines → server treats as falsy →
+   any marker drops as `agent-marker-spoofed-by-user`. This is the
+   fail-CLOSED side, matching spec invariant.
+3. **Level-of-abstraction fit.** Extraction-then-reuse: the hook
+   invocation logic moves from inlined to a method on the adapter, called
+   from both polling and forward paths. No new abstraction; just exposes
+   what was already there.
+4. **Signal vs authority.** The dispatcher returns a clean boolean to the
+   caller; the caller decides whether to short-circuit. Authority lives in
+   the caller (route or polling loop), not in the dispatcher. Same as the
+   prior inline version.
+5. **Interactions.** Reuses `agentMessageHook` set by `setAgentMessageHook`
+   — no new state. The forward route reads three new optional fields from
+   the body; older clients (lifeline pre-this-PR) omit them and get the
+   fail-CLOSED spoof defense automatically.
+6. **External surfaces.** The `/internal/telegram-forward` response gains
+   one additive flag (`agentMessage: true`) when the hook claims the
+   message; the existing `{ ok, forwarded }` contract is preserved
+   otherwise. No new routes. No new config.
+7. **Rollback cost.** Trivial — revert restores the inline hook call in
+   the polling path, drops the dispatcher and the forward-route call,
+   drops the lifeline body additions. The new `agentMessage:true` flag is
+   an additive response field, so any consumer relying on it would need a
+   one-line fix back to checking `forwarded:true` alone.
+
+## Testing
+
+11 new tests, all green (`tsc --noEmit` clean):
+
+- **Tier 1 unit (8):** `TelegramAdapter-dispatchAgentMessageHook` covers
+  no-op safe (no hook), handled:true short-circuit, handled:false
+  fall-through, FAIL-OPEN on hook throw, three senderBotId derivation
+  modes (sender_chat / rawFromId+isBot / undefined for users), explicit
+  override.
+- **Tier 2 integration (3):** `telegram-forward-a2a-dispatch` boots
+  `createRoutes` with a mock adapter through the real Express pipeline;
+  asserts short-circuit when hook claims, fall-through when not,
+  backward-compat when adapter lacks the method.
+- **Tier 3 E2E:** the existing `mentee-receiver-lifecycle.test.ts` from
+  PR #462 (which installs the hook end-to-end on server boot) plus the
+  live dogfood loop that motivated this PR are the lifecycle proof.
+
+## Migration parity
+
+No config changes; no new config keys. The lifeline-side change is
+deployed via the same npm release as the server-side change, so the
+mixed-version state is only momentary (server upgrades alongside its
+lifeline via the existing AutoUpdater + LifelineDriftPromoter pair).
+Mixed-version safety is preserved either direction (server new / lifeline
+old: spoof-fail-closed; server old / lifeline new: unknown fields ignored).