feat(primeintellect): prove live multi-turn rollouts

README.md

@@ -207,7 +207,7 @@ All 29 live in [`examples/`](./examples).
 - New here? [`docs/concepts.md`](./docs/concepts.md), the mental model in plain terms.
 - [`docs/canonical-api.md`](./docs/canonical-api.md), find the primitive: "I want to ___ → use ___".
 - [`docs/api/primitive-catalog.md`](./docs/api/primitive-catalog.md), every export in one generated, never-stale list with its import path. Check it before building anything new.
-- Import subpaths: the root export is the product surface (`handleChatTurn`, `improve`); deeper capabilities ship as subpaths: `/loops` (multi-agent + the loop kernel), `/knowledge` (KB improvement), `/primeintellect` (Prime task, runtime, and trace adapter), `/mcp` (tool servers), `/intelligence` (observability drop-in), `/lifecycle`, `/agent`, `/profiles`, `/platform`, `/analyst-loop`, `/environment-provider`.
+- Import subpaths: the root export is the product surface (`handleChatTurn`, `improve`); deeper capabilities ship as subpaths: `/loops` (multi-agent + the loop kernel), `/conversation` (multi-turn conversations), `/knowledge` (KB improvement), `/primeintellect` (Prime task, runtime, and trace adapter), `/mcp` (tool servers), `/intelligence` (observability drop-in), `/lifecycle`, `/agent`, `/profiles`, `/platform`, `/analyst-loop`, `/environment-provider`.
 - [`docs/architecture.md`](./docs/architecture.md), the design, end to end.
 - [`bench/HARNESS.md`](./bench/HARNESS.md), the experiment harness and how to run a benchmark.
 

docs/api/README.md

@@ -9,6 +9,7 @@
 - [agent](agent.md)
 - [analyst-loop](analyst-loop.md)
 - [candidate-execution](candidate-execution.md)
+- [conversation](conversation.md)
 - [index](index.md)
 - [intelligence](intelligence.md)
 - [knowledge](knowledge.md)

docs/api/conversation.md

@@ -0,0 +1,325 @@
+[**@tangle-network/agent-runtime**](README.md)
+
+***
+
+[@tangle-network/agent-runtime](README.md) / conversation
+
+# conversation
+
+## References
+
+### BackendCallPolicy
+
+Re-exports [BackendCallPolicy](index.md#backendcallpolicy)
+
+***
+
+### CircuitBreakerConfig
+
+Re-exports [CircuitBreakerConfig](index.md#circuitbreakerconfig)
+
+***
+
+### CircuitBreakerState
+
+Re-exports [CircuitBreakerState](index.md#circuitbreakerstate)
+
+***
+
+### CircuitOpenError
+
+Re-exports [CircuitOpenError](index.md#circuitopenerror)
+
+***
+
+### computeBackoff
+
+Re-exports [computeBackoff](index.md#computebackoff)
+
+***
+
+### DeadlineExceededError
+
+Re-exports [DeadlineExceededError](index.md#deadlineexceedederror)
+
+***
+
+### defaultIsRetryable
+
+Re-exports [defaultIsRetryable](index.md#defaultisretryable)
+
+***
+
+### makePerAttemptSignal
+
+Re-exports [makePerAttemptSignal](index.md#makeperattemptsignal)
+
+***
+
+### RetryableErrorPredicate
+
+Re-exports [RetryableErrorPredicate](index.md#retryableerrorpredicate)
+
+***
+
+### RetryBackoff
+
+Re-exports [RetryBackoff](index.md#retrybackoff)
+
+***
+
+### sleep
+
+Re-exports [sleep](index.md#sleep)
+
+***
+
+### createConversationBackend
+
+Re-exports [createConversationBackend](index.md#createconversationbackend)
+
+***
+
+### defineConversation
+
+Re-exports [defineConversation](index.md#defineconversation)
+
+***
+
+### buildForwardHeaders
+
+Re-exports [buildForwardHeaders](index.md#buildforwardheaders)
+
+***
+
+### DEFAULT\_MAX\_DEPTH
+
+Re-exports [DEFAULT_MAX_DEPTH](index.md#default_max_depth)
+
+***
+
+### FORWARD\_HEADERS
+
+Re-exports [FORWARD_HEADERS](index.md#forward_headers)
+
+***
+
+### ForwardHeaderName
+
+Re-exports [ForwardHeaderName](index.md#forwardheadername)
+
+***
+
+### isDepthExceeded
+
+Re-exports [isDepthExceeded](index.md#isdepthexceeded)
+
+***
+
+### PropagatedHeaders
+
+Re-exports [PropagatedHeaders](index.md#propagatedheaders)
+
+***
+
+### readDepth
+
+Re-exports [readDepth](index.md#readdepth)
+
+***
+
+### ConversationJournal
+
+Re-exports [ConversationJournal](index.md#conversationjournal)
+
+***
+
+### ConversationJournalEntry
+
+Re-exports [ConversationJournalEntry](index.md#conversationjournalentry)
+
+***
+
+### FileConversationJournal
+
+Re-exports [FileConversationJournal](index.md#fileconversationjournal)
+
+***
+
+### InMemoryConversationJournal
+
+Re-exports [InMemoryConversationJournal](index.md#inmemoryconversationjournal)
+
+***
+
+### D1DatabaseLike
+
+Re-exports [D1DatabaseLike](index.md#d1databaselike)
+
+***
+
+### D1StmtLike
+
+Re-exports [D1StmtLike](index.md#d1stmtlike)
+
+***
+
+### d1ToSqlAdapter
+
+Re-exports [d1ToSqlAdapter](index.md#d1tosqladapter)
+
+***
+
+### SqlAdapter
+
+Re-exports [SqlAdapter](index.md#sqladapter)
+
+***
+
+### SqlConversationJournal
+
+Re-exports [SqlConversationJournal](index.md#sqlconversationjournal)
+
+***
+
+### runConversation
+
+Re-exports [runConversation](index.md#runconversation)
+
+***
+
+### runConversationStream
+
+Re-exports [runConversationStream](index.md#runconversationstream)
+
+***
+
+### PersonaConversationResult
+
+Re-exports [PersonaConversationResult](index.md#personaconversationresult)
+
+***
+
+### PersonaDriver
+
+Re-exports [PersonaDriver](index.md#personadriver)
+
+***
+
+### RunPersonaConfig
+
+Re-exports [RunPersonaConfig](index.md#runpersonaconfig)
+
+***
+
+### RunPersonaConversationOptions
+
+Re-exports [RunPersonaConversationOptions](index.md#runpersonaconversationoptions)
+
+***
+
+### runPersonaConversation
+
+Re-exports [runPersonaConversation](index.md#runpersonaconversation)
+
+***
+
+### runPersonaDispatch
+
+Re-exports [runPersonaDispatch](index.md#runpersonadispatch)
+
+***
+
+### slugifySpeaker
+
+Re-exports [slugifySpeaker](index.md#slugifyspeaker)
+
+***
+
+### turnId
+
+Re-exports [turnId](index.md#turnid-1)
+
+***
+
+### AuthSource
+
+Re-exports [AuthSource](index.md#authsource-1)
+
+***
+
+### Conversation
+
+Re-exports [Conversation](index.md#conversation)
+
+***
+
+### ConversationDriveState
+
+Re-exports [ConversationDriveState](index.md#conversationdrivestate)
+
+***
+
+### ConversationParticipant
+
+Re-exports [ConversationParticipant](index.md#conversationparticipant)
+
+***
+
+### ConversationPolicy
+
+Re-exports [ConversationPolicy](index.md#conversationpolicy)
+
+***
+
+### ConversationResult
+
+Re-exports [ConversationResult](index.md#conversationresult)
+
+***
+
+### ConversationStreamEvent
+
+Re-exports [ConversationStreamEvent](index.md#conversationstreamevent)
+
+***
+
+### ConversationTurn
+
+Re-exports [ConversationTurn](index.md#conversationturn)
+
+***
+
+### HaltContext
+
+Re-exports [HaltContext](index.md#haltcontext)
+
+***
+
+### HaltPredicate
+
+Re-exports [HaltPredicate](index.md#haltpredicate)
+
+***
+
+### HaltReason
+
+Re-exports [HaltReason](index.md#haltreason)
+
+***
+
+### HaltSignal
+
+Re-exports [HaltSignal](index.md#haltsignal)
+
+***
+
+### RunConversationOptions
+
+Re-exports [RunConversationOptions](index.md#runconversationoptions)
+
+***
+
+### TurnOrder
+
+Re-exports [TurnOrder](index.md#turnorder)

docs/api/primitive-catalog.md

@@ -258,6 +258,47 @@ Import from `@tangle-network/agent-runtime/agent` — 48 exports.
 
 **Undocumented supporting types** (add a TSDoc line at the declaration to earn a table row): `AgentRubric`, `AgentRunContext`, `AgentRunInvocation`, `AgentRuntime`, `AnalystConfig`, `AutoApplyPolicy`, `CreateSandboxActOptions`, `CreateSurfaceImprovementAdapterOpts`, `DraftPatchInput`, `DraftPatchOutput`, `JudgeConfig`, `OutcomeMeasurementOpts`, `ResolvedSurface`, `RubricDimension`, `KnownAgentProfileMaterializationAxis`.
 
+### Multi-turn conversations
+
+Import from `@tangle-network/agent-runtime/conversation` — 53 exports.
+
+| Symbol | Kind | Summary |
+|---|---|---|
+| `buildForwardHeaders` | function | Build the headers to emit on an outbound participant call, given the |
+| `computeBackoff` | function | Compute the delay before the next attempt. Default: 250ms exponential with jitter. |
+| `createConversationBackend` | function | Wrap a `Conversation` so it satisfies `AgentExecutionBackend`. The result is |
+| `d1ToSqlAdapter` | function | Adapt a Cloudflare D1 binding to the SqlAdapter shape. Lives here so D1 |
+| `defineConversation` | function | Declarative constructor for a multi-agent `Conversation`. Validates inputs |
+| `isDepthExceeded` | function | Refuse further forwarding when the inbound depth has reached the limit. |
+| `makePerAttemptSignal` | function | Build a per-attempt AbortSignal linked to the parent signal AND fired when |
+| `readDepth` | function | Read the depth counter off an inbound request. Missing → 0 (caller is the |
+| `runConversation` | function | Conversation orchestrator. Drives N participants in turn through their own |
+| `runConversationStream` | function | Streaming conversation orchestrator: drives N participants in turn through their own backends, enforcing `maxTurns` / `maxCreditsCents` / `haltOn`, yielding per-event stream markers. |
+| `runPersonaConversation` | function | Run one worker profile against one persona as a multi-round conversation. |
+| `runPersonaDispatch` | function | Wrap {@link runPersonaConversation} as a `ProfileDispatchFn` for |
+| `sleep` | function | Resolve after `ms` milliseconds — used for retry backoff in conversation call policy. |
+| `slugifySpeaker` | function | Reduce a speaker name to ASCII alphanumerics + dashes. Preserves enough |
+| `turnId` | function | Deterministic turn identifier. Stable across retries of the same logical |
+| `DEFAULT_MAX_DEPTH` | const | Hard cap on chained gateway hops; refused beyond this. Default keeps recursion bounded. |
+| `defaultIsRetryable` | const | Default retryable classification — network/timeout class errors. Errors |
+| `FORWARD_HEADERS` | const | Standard names — lowercased so Headers maps interop on every runtime. |
+| `CircuitBreakerState` | class | Live circuit-breaker state — one instance per (participant, conversation run). |
+| `CircuitOpenError` | class | Thrown when the circuit breaker is open for a participant and no retry is allowed yet. |
+| `DeadlineExceededError` | class | Thrown when a backend call exceeds its per-attempt deadline. |
+| `FileConversationJournal` | class | JSONL on disk. One line per record; first line is the `begin`, subsequent |
+| `InMemoryConversationJournal` | class | In-memory `ConversationJournal` — suitable for testing and single-process runs. |
+| `SqlConversationJournal` | class | SQL-backed ConversationJournal. Two tables — runs (one row per runId, holds |
+| `CircuitBreakerConfig` | interface | Circuit-breaker tuning. `failuresToOpen` consecutive failures opens it; closed only after `cooldownMs`. |
+| `ConversationJournalEntry` | interface | Durable conversation transcript — survives a driver process crash mid-run. |
+| `D1DatabaseLike` | interface | Structural type matching the surface of `D1Database` we depend on, so the |
+| `SqlAdapter` | interface | Minimal SQL driver shape. Implementations forward to whichever client the |
+| `PersonaDriver` | type | A persona that drives the conversation: either a full driver `AgentProfile` |
+| `PropagatedHeaders` | type | Header bag carried through `AgentBackendContext.propagatedHeaders` so |
+| `RetryableErrorPredicate` | type | Pure judgment of whether an error is worth retrying. Defaults: TimeoutError, AbortError, fetch-level network errors. |
+| `RetryBackoff` | type | Backoff between attempts. Constant ms, or `(attempt: 1-indexed) => ms`. |
+
+**Undocumented supporting types** (add a TSDoc line at the declaration to earn a table row): `BackendCallPolicy`, `Conversation`, `ConversationDriveState`, `ConversationJournal`, `ConversationParticipant`, `ConversationPolicy`, `ConversationResult`, `ConversationTurn`, `D1StmtLike`, `HaltContext`, `HaltSignal`, `PersonaConversationResult`, `RunConversationOptions`, `RunPersonaConfig`, `RunPersonaConversationOptions`, `AuthSource`, `ConversationStreamEvent`, `ForwardHeaderName`, `HaltPredicate`, `HaltReason`, `TurnOrder`.
+
 ### Intelligence SDK — Observe + provable-OFF billing
 
 Import from `@tangle-network/agent-runtime/intelligence` — 85 exports.