feat(conversation): multi-agent + distributed primitives + cross-gateway protocol

[drewstone]

Summary

Three stacked commits, each one phase, turning agent-runtime into a real distributed agent runtime.

Phase	Commit	What
1	c7ac6f1	defineConversation / runConversation / runConversationStream / createConversationBackend — N participants driven turn-by-turn via any AgentExecutionBackend, with maxTurns / maxCreditsCents / haltOn policy and per-event stream markers. Recursion: a conversation is an agent.
2	76f4338	Deterministic turnId, durable ConversationJournal (in-memory + JSONL on disk with fsync), per-turn deadline + retry + per-participant circuit breaker, automatic cross-gateway header propagation.
3	76f4338	docs/agent-bus-protocol.md — normative cross-gateway header contract + 9 protocol-level tests.

Why this is real distributed-agent infrastructure

Every participant is an AgentExecutionBackend, so the same driver works against any reachable endpoint — in-process iterable, local cli-bridge, sandbox, router, remote agent-gateway. Same code drives same-machine, same-cluster, and cross-cloud orchestration; only the backend's baseURL changes.

Layered on top:

• Idempotent turn ids — <runId>.t<index>.<speaker-slug>; stable across retries so a caching gateway can dedupe by (runId, turnId).
• Durable journal — every committed turn fsynced before turn_end yields. Reusing a runId against the same journal resumes from the last committed turn; a driver crash mid-run loses zero acknowledged turns.
• Per-turn call policy — perAttemptDeadlineMs aborts a hung upstream; maxRetries + jittered backoff replay the same logical turn (same turnId); per-participant circuit breaker opens after N consecutive failures with cooldown.
• Cross-gateway header propagation — every outbound participant call carries the original user's X-Tangle-Forwarded-Authorization (downstream gateways bill the right wallet), an incrementing X-Tangle-Forwarded-Depth (refused by agent-gateway at DEFAULT_MAX_DEPTH=4), a stable X-Tangle-RunId, a X-Tangle-TurnId, and — under recursion — X-Tangle-Parent-TurnId. createOpenAICompatibleBackend already merges context.propagatedHeaders into its outbound HTTP.

Surface added (additive only)

// Phase 1
defineConversation, runConversation, runConversationStream, createConversationBackend

// Phase 2
turnId, slugifySpeaker
ConversationJournal, InMemoryConversationJournal, FileConversationJournal
BackendCallPolicy, CircuitBreakerState, CircuitBreakerConfig
CircuitOpenError, DeadlineExceededError
defaultIsRetryable, computeBackoff, makePerAttemptSignal, sleep

// Phase 3
FORWARD_HEADERS, ForwardHeaderName, DEFAULT_MAX_DEPTH
readDepth, isDepthExceeded, buildForwardHeaders, PropagatedHeaders

Plus 13 exported types.

Recursion is composable across all of it

createConversationBackend wraps a Conversation as an AgentExecutionBackend. A conversation IS an agent. A swarm can be a participant in another swarm; published behind a single agent-gateway endpoint, the recursion is invisible to the caller. Protocol's runId-immutability guarantees all nested hops correlate to one trace. (Caught and fixed a self-inflicted protocol violation during testing: recursion was minting fresh runIds; nested runs now inherit.)

Distributed-systems concerns made explicit

docs/agent-bus-protocol.md is normative for any gateway implementer:

• Depth monotonicity (gateways MUST NOT reset the counter)
• Authorization preservation (forward sk-tan-USER verbatim, never substitute)
• runId immutability through nested conversations
• 413 refusal granularity (gateways MUST refuse with 413 Payload Too Large with the observed depth)
• Idempotency advisory: gateways MAY dedupe by (runId, turnId)

Test coverage

40 new tests, 183/183 total.

• Phase 1 (13): validation, alternation + round-robin defaults, all five halt reasons (max_turns, max_credits, predicate, abort, participant_error), event-stream ordering, recursion.
• Phase 2 (18): turnId determinism + slugify edge cases, journal persist+resume + halted-replay + clash + halted-append-refusal, retry success + exhaustion + turn_retry events, deadline timeout + retryable classification, circuit-breaker open/cooldown/reset, header propagation + runId preservation + no-leak.
• Phase 3 (9): readDepth parsing (empty → 0, integer, fail-loud non-integer, multi-valued first-wins), isDepthExceeded boundary, buildForwardHeaders increment + identity + run/turn + parent + speaker + omits absent optionals, runId immutability across recursion, depth math through nesting.

Version

0.17.2 → 0.18.0 (additive minor; no breaking changes).

Test plan

• pnpm typecheck — clean
• pnpm test — 183/183 (14 files)
• biome check — clean
• pnpm build (tsup ESM + DTS) — clean

What stays out (deliberately)

• A real D1 / R2 / postgres journal adapter — interface is small (~30 lines); in-memory + file adapters cover tests + scratch.
• agent-gateway middleware that enforces the depth limit — separate PR against tangle-network/agent-gateway. agent-runtime emits; agent-gateway enforces.
• A cli-bridge adapter that honors inbound forwarded headers — separate PR; agent-runtime is ready to emit them now.

[tangletools]

APPROVE. Reviewed all four conversation modules + the protocol spec + 40 new tests + the rebase resolution. The architecture is the right call — multi-agent belongs in agent-runtime (runConversation is the natural sibling of runAgentTask), not a sidecar tool, because the recursion (createConversationBackend exposing a conversation as an AgentExecutionBackend) only composes if the primitive lives inside the SDK.

Load-bearing invariants I checked

1. Journal append-before-yield ordering (run-conversation.ts). Turn is appendTurn'd before turn_end is yielded. A subscriber that flushes UI state on turn_end and a journal that crashes mid-call cannot diverge: the turn is durably committed before any external observer sees it. ✓
2. runId immutability across nesting (conversation-backend.ts). Caught and fixed in flight — nested runConversationStream now inherits context.runId instead of minting fresh. Without this, every recursive call would break trace correlation in violation of the protocol spec. Test phase3.test.ts covers it explicitly. ✓
3. Depth monotonicity (headers.ts:buildForwardHeaders). inboundDepth + 1 always; no path resets. The runtime trusts the caller's inboundDepth (gateway enforces honesty on inbound), which is correct: every intermediate runtime adds +1 from whatever it received. ✓
4. Authorization preservation (run-conversation.ts:89). forwardedAuthorization is read once at run start from the caller's headers and passed verbatim into every per-turn buildForwardHeaders call. The runtime never substitutes its own credentials. ✓
5. Idempotent retries (call-policy.ts + run-conversation.ts). The turnId derives deterministically from (runId, index, speakerSlug) before the attempt loop opens; every attempt within the loop carries the same id. A caching gateway can safely dedupe by (runId, turnId). ✓
6. Per-participant breaker isolation (run-conversation.ts:91-97). A Map keyed on participant name; A's failures cannot open B's circuit. Constructed once per run, not module-global. ✓

Things I deliberately probed and accepted

• Credit cap is between-turns, not mid-stream. Documented in the module header. A turn that overshoots completes; the cap halts the next turn. Pragmatic — mid-stream abort during the SSE drain would orphan token usage that the backend already burned but didn't get to report.
• Per-attempt deadline aborts via AbortSignal.reason = DeadlineExceededError. Backends that respect signal (which the in-tree createOpenAICompatibleBackend does) tear down the HTTP request cleanly. Backends that don't will hang until the deadline + a for await iteration; the runner's outer try/catch still recovers. Acceptable.
• Idempotency is advisory, not enforced. A gateway that doesn't dedupe charges N× for a retry — that's the caller's choice, called out in the protocol spec. Right call to not bake it into the contract.

Deliberately deferred (named in the PR description, agreed)

• D1/R2/postgres journal adapter (in-tree adapters cover scratch + on-disk durability).
• agent-gateway middleware enforcing the depth limit on inbound (agent-runtime emits; agent-gateway will enforce in a separate PR).
• cli-bridge inbound-header propagation (forward X-Tangle-Forwarded-* from incoming router request into outbound backend calls).

Rollout watch-items

• The 'alternate' turn-order default for two-party + auto round-robin for N is intuitive but worth documenting in the user-facing README before the SDK release. The header docstring covers it; a quickstart snippet would help.
• FileConversationJournal does an fs.open(path, 'a') per turn. Fine at 10s of turns/sec; at 1000s of turns/sec a downstream user would want a batching adapter — outside this PR's scope, but worth a follow-up note when we publish a D1 adapter.
• agent-bus-protocol.md is currently versioned v0. When agent-gateway lands and we have a second runtime implementing the contract, bumping to v1 + adding x-tangle-protocol-version header is the right move (already called out in the doc).

Verified locally

pnpm typecheck clean • pnpm test 354/354 (38 files) • biome check clean (one pre-existing warning in tests/mcp/in-process-executor.test.ts:116 from main, untouched by this PR) • pnpm build (tsup ESM + DTS) clean • rebase onto origin/main resolved 2 conflicts (package.json version → 0.26.0, index.ts re-exports merged alongside main's mcp + otel additions).

Approving.