@yolk-sdk/agent 0.0.1-canary.9 → 0.1.0-canary.100

package/README.md

@@ -1,49 +1,147 @@
 # @yolk-sdk/agent
 
-Domain-free agent protocol, loop, runtime, client, and tool primitives.
+Domain-free agent protocol, loop, runtime, Effect-native client, compaction, classifier models, tools, React, providers, OAuth, skillset, and voice primitives.
 
-Root export is intentionally tiny. Import feature APIs from explicit subpaths.
+Root export is intentionally empty. Import feature APIs from explicit subpaths.
 
 ## Install
 
 ```bash
-pnpm add @yolk-sdk/agent@canary effect
+pnpm add @yolk-sdk/agent@canary effect@4.0.0
 ```
 
+Add `react` if you use `@yolk-sdk/agent/react` or `@yolk-sdk/agent/voice/react`.
+
+Running the experimental `@yolk-sdk/agent/providers/*/conformance` cases? Also add `@yolk-sdk/conformance@canary` (usually as a dev dependency); the cases run through `@yolk-sdk/conformance/runner`.
+
 Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
+Use the SDK's matching Effect version (`4.0.0`) in host code.
+Published package metadata requires Node.js 22+.
 
 ## Subpaths
 
-| Subpath                        | Purpose                                                        |
-| ------------------------------ | -------------------------------------------------------------- |
-| `@yolk-sdk/agent/protocol`     | Wire messages, events, content, usage, tool schemas            |
-| `@yolk-sdk/agent/loop`         | Stateless LLM/tool loop                                        |
-| `@yolk-sdk/agent/loop/testing` | Faux provider and tool executor test helpers                   |
-| `@yolk-sdk/agent/runtime`      | Transcript or append-backed runtime orchestration              |
-| `@yolk-sdk/agent/client`       | HTTP/NDJSON transport and client state helpers                 |
-| `@yolk-sdk/agent/tools`        | Tool module registry, `makeTool`, task/question tool contracts |
+| Subpath                                                  | Purpose                                                                                       |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `@yolk-sdk/agent/protocol`                               | Wire messages, events, content, usage, tool schemas                                           |
+| `@yolk-sdk/agent/loop`                                   | Stateless LLM/tool loop                                                                       |
+| `@yolk-sdk/agent/loop/testing`                           | Faux provider and tool executor test helpers                                                  |
+| `@yolk-sdk/agent/runtime`                                | Transcript or append-backed runtime orchestration                                             |
+| `@yolk-sdk/agent/client`                                 | HTTP/NDJSON transport, HITL resume, retry/error state helpers                                 |
+| `@yolk-sdk/agent/compaction`                             | Host-owned compaction budgets, checkpoints, formatting, retry                                 |
+| `@yolk-sdk/agent/classification`                         | Classifier model contract: typed questions, answers, usage, errors                            |
+| `@yolk-sdk/agent/tools`                                  | Tool registry, typed inputs, interactions, subagents/questions, durable tool ledger           |
+| `@yolk-sdk/agent/react`                                  | Headless React chat hook, reducer, selectors, and render model                                |
+| `@yolk-sdk/agent/oauth`                                  | Provider-neutral OAuth token and broker contracts                                             |
+| `@yolk-sdk/agent/providers/openai`                       | OpenAI/Codex OAuth and broker helpers                                                         |
+| `@yolk-sdk/agent/providers/openai/codex`                 | OpenAI Codex request and auth helpers                                                         |
+| `@yolk-sdk/agent/providers/openai/codex-usage`           | Codex subscription-allowance snapshots                                                        |
+| `@yolk-sdk/agent/providers/openai/codex-provider`        | Codex LLM provider factory                                                                    |
+| `@yolk-sdk/agent/providers/openai/provider`              | OpenAI-compatible LLM provider factory                                                        |
+| `@yolk-sdk/agent/providers/openai/conformance`           | Synthetic OpenAI chat, Codex Responses, and Codex usage fixtures and conformance cases        |
+| `@yolk-sdk/agent/providers/openai/realtime`              | OpenAI Realtime session config and event codecs                                               |
+| `@yolk-sdk/agent/providers/openai/speech`                | OpenAI text-to-speech and transcription adapters                                              |
+| `@yolk-sdk/agent/providers/vercel/ai-gateway-provider`   | Vercel AI Gateway Chat Completions provider factory                                           |
+| `@yolk-sdk/agent/providers/vercel/ai-gateway-classifier` | Vercel AI Gateway classifier (`POST /v1/evaluate`) layer                                      |
+| `@yolk-sdk/agent/providers/vercel/conformance`           | Verified Gateway chat fixtures, synthetic classifier fixtures, and conformance cases          |
+| `@yolk-sdk/agent/providers/opencode/go-provider`         | OpenCode Go Chat Completions, Messages, and Responses provider                                |
+| `@yolk-sdk/agent/providers/opencode/usage`               | OpenCode Go subscription-allowance snapshots                                                  |
+| `@yolk-sdk/agent/providers/opencode/conformance`         | Synthetic OpenCode Go (per protocol, commentary replay, usage) fixtures and conformance cases |
+| `@yolk-sdk/agent/providers/anthropic`                    | Anthropic/Claude OAuth and broker helpers                                                     |
+| `@yolk-sdk/agent/providers/anthropic/claude`             | Claude request and auth helpers                                                               |
+| `@yolk-sdk/agent/providers/anthropic/usage`              | Claude subscription-allowance snapshots                                                       |
+| `@yolk-sdk/agent/providers/anthropic/claude-provider`    | Claude LLM provider factory                                                                   |
+| `@yolk-sdk/agent/providers/anthropic/conformance`        | Synthetic Anthropic Messages and Claude usage fixtures and conformance cases                  |
+| `@yolk-sdk/agent/providers/xai`                          | Grok subscription OAuth and token broker helpers                                              |
+| `@yolk-sdk/agent/providers/xai/grok`                     | Grok subscription request and auth helpers                                                    |
+| `@yolk-sdk/agent/providers/xai/grok-provider`            | Grok subscription LLM provider factory                                                        |
+| `@yolk-sdk/agent/providers/xai/usage`                    | Grok subscription-allowance snapshots                                                         |
+| `@yolk-sdk/agent/providers/xai/conformance`              | Synthetic Grok Responses and Grok usage fixtures and conformance cases                        |
+| `@yolk-sdk/agent/providers/subscription-usage`           | Shared allowance snapshot and safe error schemas                                              |
+| `@yolk-sdk/agent/skillset`                               | Portable skill and slash-command parsing/catalogs                                             |
+| `@yolk-sdk/agent/voice`                                  | Voice protocol, controller, tool handler, projection, speech                                  |
+| `@yolk-sdk/agent/voice/browser`                          | Browser WebRTC voice transport                                                                |
+| `@yolk-sdk/agent/voice/react`                            | Headless browser voice React hook                                                             |
 
 ## Imports
 
 ```ts
-import { makeSubagentRunId, UserMessage } from '@yolk-sdk/agent/protocol'
+import {
+  danglingHostToolCalls,
+  hitlResponseEvent,
+  isTerminalAgentEvent,
+  makeSubagentRunId,
+  ProviderErrorInfo,
+  PlainHitlResponse,
+  questionResponseStructuredContent,
+  repairDanglingHostToolCalls,
+  UserMessage,
+  validateNoDanglingHostToolCalls
+} from '@yolk-sdk/agent/protocol'
 import { run } from '@yolk-sdk/agent/loop'
-import { runRuntime } from '@yolk-sdk/agent/runtime'
-import { initialAgentClientState } from '@yolk-sdk/agent/client'
+import { runRuntime, RuntimeRequest } from '@yolk-sdk/agent/runtime'
+import {
+  documentPartFromTextFile,
+  initialAgentClientState,
+  streamAgentEventStreamUntilTerminal,
+  toolRunsFromHitlRequests
+} from '@yolk-sdk/agent/client'
 import {
-  makeNonRecursiveTaskToolModule,
-  makeTaskToolResult,
+  makeContextBudget,
+  makePreviewSummaryMessage,
+  makeWindowCompactionTransformer
+} from '@yolk-sdk/agent/compaction'
+import {
+  makeInteractionTool,
+  makeNonRecursiveSubagentToolModule,
+  makeSubagentToolResult,
+  modelVisibleToolError,
+  modelVisibleToolErrorStructuredContent,
   makeQuestionToolModule,
-  resolveTools
+  omitNullOptionalToolArguments,
+  resolveTools,
+  withToolArgumentsErrorHint
 } from '@yolk-sdk/agent/tools'
+import {
+  AgentChatAction,
+  AgentChatPart,
+  applyAgentEventToChatProjection,
+  makeAgentChatEventProjectionState,
+  useAgentChat
+} from '@yolk-sdk/agent/react'
+import { makeVercelAiGatewayProviderLayer } from '@yolk-sdk/agent/providers/vercel/ai-gateway-provider'
 ```
 
+`RuntimeRequest` is a value on `@yolk-sdk/agent/runtime` (`Transcript`, `AppendInput`, `AppendHitlResponse`). Pass `RuntimeRequest.Transcript({ sessionId, messages })` into `runRuntime`. For append requests, omitted or `undefined` `expectedRevision` still means use the loaded log revision (`??`).
+
 Test helpers live behind their own subpath:
 
 ```ts
 import { FauxProvider, Reply, TestToolExecutor } from '@yolk-sdk/agent/loop/testing'
 ```
 
+## Headless React chat
+
+`useAgentChat` exposes protocol messages, render-oriented chat messages, run/error/waiting state,
+and actions for submit, stop, edit, regenerate, delete, tool approval, question, and typed input responses. The
+package supplies no components, styling, auth, or route ownership, and React remains an optional
+peer used only by React subpaths.
+
+Chat ADTs on `@yolk-sdk/agent/react` are value constructors: `AgentChatPart`, `ChatToolState`,
+`DeleteChatTurnResult`, `EditChatUserMessageResult`, `RegenerateChatMessagesResult`, `AgentChatItem`,
+`ToolRunState`, `AgentChatAction`, and hook results such as `AgentChatSubmitResult`. They are
+`Data.taggedEnum` plain objects (`_tag` last), not Equal/Hash classes. Duration descriptors use
+`ToolDurationKnown` / `ToolDurationUnknown` (`Schema.TaggedStruct.make` validates those plains).
+Prefer `AgentChatPart.Text({ ... })` over handwritten `{ _tag: 'Text', ... }`, omit absent optionals,
+and discriminate with `$is` (for example `AgentChatSubmitResult.$is('Submitted')(result)`).
+`useAgentChat` dispatches `AgentChatAction` constructors and returns those hook-result values.
+
+By default the hook streams HTTP/NDJSON through `@yolk-sdk/agent/client`. Pass an
+`AgentChatTransport` through the `transport` option to use another runtime. A custom transport
+receives the transcript, session/model options, HITL responses, and an `AbortSignal`, and returns an
+`AsyncIterable<AgentEvent>`; the host still owns endpoint auth and persistence. Custom transport
+rejections are normalized to `AgentTransportError` internally while retaining the original cause.
+Native abort causes stop quietly; other non-Error rejections display `Agent request failed`.
+
 ## Quick start
 
 ```ts
@@ -61,6 +159,368 @@ const program = run({
 // Provide LLM provider, loop config, context transformer, and tool executor layers in the host app.
 ```
 
+Loop composition is those four Layers plus `run` / `runModelTurn` / `runToolBatch`.
+Merge them with `makeAgentLoopLayer`. Omitted tools use `ToolExecutor.unavailable`; omitted transformer/config use identity and `LoopConfig.defaultLayer`.
+Intercept by decorating a service (`decorateLLMProvider`), not with hooks.
+Durable hosts fold model-turn steps with `collectModelTurn`. Use `collectModelTurnAttempt` when the fold must retain partial output after a failed stream. Kernel incomplete streams (zero `Done` events) set optional `LLMError.responseIssue: 'missing_done'` and stay `invalid_response` / `retryable: false`.
+
+```ts
+import { makeAgentLoopLayer } from '@yolk-sdk/agent/loop'
+import { FauxProvider, Reply } from '@yolk-sdk/agent/loop/testing'
+
+const LoopLayer = makeAgentLoopLayer({
+  provider: FauxProvider.layer(Reply.text('ok'))
+})
+```
+
+Guide source: [Loop and runtime](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/agent/loop-runtime.mdx#compose-the-loop-layer).
+
+## OAuth credentials
+
+`@yolk-sdk/agent/oauth` defines provider-neutral access-token, broker, freshness, and credential-source
+contracts. Provider subpaths add vendor request/response conversion without owning persistence.
+
+```ts
+import { credentialSourceFromBroker, type TokenBrokerClient } from '@yolk-sdk/agent/oauth'
+
+const makeTokenProgram = (hostBroker: TokenBrokerClient) =>
+  credentialSourceFromBroker(hostBroker, {
+    provider: 'openai-codex',
+    subjectId: 'host-user-id'
+  }).getAccessToken({ minTtlSeconds: 300 })
+```
+
+`hostBroker` is a host implementation of `TokenBrokerClient`. The host stores, refreshes, revokes,
+and authorizes credentials; the package receives short-lived access tokens and never persists
+secrets.
+
+## Provider configuration
+
+Provider output limits are host-owned when the endpoint supports them. Yolk does not infer model
+limits or apply hidden fallbacks.
+
+| Provider factory                   | Output-limit field    |
+| ---------------------------------- | --------------------- |
+| `makeOpenAiProviderLayer`          | `maxCompletionTokens` |
+| `makeVercelAiGatewayProviderLayer` | `maxCompletionTokens` |
+| `makeOpenCodeGoProviderLayer`      | `maxOutputTokens`     |
+| `makeOpenAiCodexProviderLayer`     | none                  |
+| `makeAnthropicClaudeProviderLayer` | `maxTokens`           |
+| `makeXAiGrokProviderLayer`         | `maxOutputTokens`     |
+
+The public `toOpenAiRequestBody`, `toAnthropicClaudeRequestBody`, and `toXAiGrokRequestBody` helpers
+require the matching limit configuration. ChatGPT subscription Codex rejects vendor
+`max_output_tokens`, so `makeOpenAiCodexProviderLayer` and `toOpenAiCodexRequestBody` ignore the
+optional deprecated `maxOutputTokens` compatibility field. `OpenAiProviderLayer` reads both
+`OPENAI_API_KEY` and integer `OPENAI_MAX_COMPLETION_TOKENS` through Effect Config.
+
+OpenCode Go uses API-key authentication with an explicit host-selected `protocol`:
+`chat-completions`, `messages`, or `responses`. Model IDs stay opaque: pass the Go API model ID
+without OpenCode's `opencode-go/` CLI prefix. The SDK does not fetch a catalog or guess the protocol
+from a model name. Check the [Go endpoint catalog](https://opencode.ai/docs/go/#endpoints).
+
+Server-side configuration fragment (the host supplies credentials and model policy):
+
+```ts
+import { Layer, Redacted } from 'effect'
+import { FetchHttpClient } from 'effect/http'
+import { makeOpenCodeGoProviderLayer } from '@yolk-sdk/agent/providers/opencode/go-provider'
+
+const GoLayer = makeOpenCodeGoProviderLayer({
+  apiKey: Redacted.make(hostOpenCodeGoApiKey),
+  protocol: 'messages',
+  maxOutputTokens: hostModelConfig.maxOutputTokens
+}).pipe(Layer.provide(FetchHttpClient.layer))
+```
+
+The default base URL is `https://opencode.ai/zen/go/v1`. Chat streams SSE (the Go adapter sets
+`streaming: true`) with Bearer auth; Messages uses SSE and `x-api-key`; Responses uses SSE and Bearer
+auth. All normalize to `LLMEvent`s.
+Messages retains native tool names and system instructions, without Claude OAuth fingerprinting.
+Responses sends `max_output_tokens`, unlike Codex. Go requires a nonempty key and positive safe-integer
+limit at layer construction. `extraHeaders` cannot override required protocol headers, regardless of
+case. Only override `baseUrl` with a trusted proxy because it receives the credential.
+
+Request `reasoningEffort` becomes chat `reasoning_effort`, Messages `output_config.effort` (omitting
+`minimal`), or Responses `reasoning.effort` with `summary: 'auto'`. `reasoningSummary` changes the
+Responses summary mode. Hosts must offer only model-supported efforts and media capabilities.
+Chat preserves provider `reasoning_content` in events and assistant replay. No OAuth, model discovery,
+automatic polling, or example-app UI integration is included.
+
+Read Go subscription allowance separately from per-request token usage (server-side fragment):
+
+```ts
+import { Effect, Redacted } from 'effect'
+import { FetchHttpClient } from 'effect/http'
+import { fetchOpenCodeGoSubscriptionUsage } from '@yolk-sdk/agent/providers/opencode/usage'
+
+const usageEffect = fetchOpenCodeGoSubscriptionUsage(Redacted.make(hostOpenCodeGoApiKey), {
+  requestTimeoutMs: 10_000
+}).pipe(Effect.provide(FetchHttpClient.layer))
+```
+
+The API-key endpoint (default `openCodeGoSubscriptionUsageUrl`) returns used percentages/reset instants for `five-hour`, `seven-day`, and
+`monthly` windows. Monthly resets follow the subscription's anniversary, not the first of the month;
+the adapter preserves the provider's timestamp. Missing/invalid percentages are omitted, not treated
+as zero. Treat snapshots as best-effort; hosts own polling, stale-data policy, persistence, and UI.
+The fetcher blocks redirects and sanitizes failures using the shared subscription-usage error types.
+
+Vercel AI Gateway uses its OpenAI-compatible Chat Completions endpoint, with a single JSON
+completion by default. Native PDF `DocumentPart` inputs are lowered to Gateway file parts by
+default; the selected Gateway model must advertise PDF input. Set factory option `streaming: true`
+for SSE deltas and independently set `reasoningContent: true` to preserve compatible models'
+`reasoning_content` output and assistant
+replay. Both default to false; replayed reasoning spends input tokens. Pass either an AI
+Gateway API key or Vercel OIDC token as `apiKey`; `maxCompletionTokens` is sent as Gateway
+`max_tokens`. The env-backed `VercelAiGatewayProviderLayer` tries `AI_GATEWAY_API_KEY` first, then
+`VERCEL_OIDC_TOKEN`, and requires integer
+`AI_GATEWAY_MAX_COMPLETION_TOKENS`. Model ids are opaque `provider/model` strings. Hosts may set
+`fallbackModels`, provider `routing`, and optional `http-referer` / `x-title` attribution headers.
+A request `reasoningEffort` is sent as Gateway `{ reasoning: { effort } }` by default; `reasoningEffortFormat: 'reasoning-effort'` sends the literal field instead (e.g. for DeepSeek-style hosts, with an optional `thinking` toggle merged into the request body). Hosts remain responsible for offering only efforts supported by the selected model. Required
+authorization and JSON headers cannot be replaced through `extraHeaders`. Only override
+`chatCompletionsUrl` with a trusted proxy because it receives the bearer credential.
+
+Grok subscription access uses `https://cli-chat-proxy.grok.com/v1/responses`, not the xAI developer
+API-key endpoint. The adapter sends the required CLI-session and model-routing headers and rejects
+mismatched or expired access-token envelopes before HTTP. `makeXAiGrokProviderLayer` also requires
+a truthful host-owned `clientVersion`, sent as `x-grok-client-version`, because the xAI CLI proxy
+version-gates requests and rejects missing or outdated versions with HTTP 426; required headers
+stay non-overridable through `extraHeaders`. The package exports browser-PKCE and
+device-flow constants; hosts own the callback listener or device polling, token exchange/refresh,
+secure storage, and model discovery. Only set `responsesUrl` to a trusted proxy because it receives
+the OAuth bearer. xAI controls the public CLI OAuth client and private, unsupported proxy contract,
+so hosts should treat those surfaces as changeable and confirm that their use complies with xAI
+terms.
+
+Set optional `reasoningEffort` on `run` or `runRuntime`; provider adapters lower it to vendor
+configuration. Anthropic Claude forwards `low`, `medium`, `high`, and `xhigh` through
+`output_config.effort`. It omits `minimal`, which Anthropic does not support. Hosts remain
+responsible for choosing an effort accepted by the selected provider and model.
+
+### Anthropic tool schemas
+
+Claude subscription OAuth rejects some valid JSON Schema constructs that Effect Schema can emit
+for unions, refinements, and tuples. The Claude adapter therefore projects tool parameters to a
+provider-compatible object schema without `anyOf`, `oneOf`, `allOf`, or tuple-only `prefixItems`.
+When a constraint cannot be represented faithfully, the projection widens the model-facing schema
+rather than excluding a valid call. Tool execution remains safe because `makeTool` validates the
+returned arguments against the original Effect Schema (through its JSON codec) before invoking the
+executor.
+
+Before projection, `toAnthropicClaudeRequestBody` and the Claude provider decode `ToolDef.parameters`
+and `ToolCall.params` as `Schema.Json`. Non-JSON values fail as non-retryable `LLMError` with
+`cause: 'provider_error'`. `ToolDef.parameters` now admits `ToolJsonSchema` at construction;
+`ToolCall.params` stays opaque. Provider admission also catches post-construction forgeries.
+After lone-surrogate rewrite, the request
+body is decoded as JSON again and fails rather than skipping serialization. HTTP error bodies that
+are not JSON still classify from status. Tool-result blocks omit `is_error` when the result carries
+no flag, so follow-up request bodies stay valid; an explicit boolean `isError` is still serialized.
+
+### Tool parameter documents
+
+`ToolDef.parameters` uses `ToolJsonSchema` from `@yolk-sdk/agent/protocol`: a boolean schema or
+plain JSON object. `ToolJsonSchemaObject` is the object arm; `decodeToolJsonSchema` and
+`decodeToolJsonSchemaObject` return `Option`. This checks representation, not JSON Schema semantics.
+Construction/decode preserve admitted identity and accept finite primitives, dense ordinary arrays,
+plain/null-prototype objects, own `__proto__`/`constructor` keys and DAG aliases. Accessors are
+rejected unread; exotic prototypes, hidden/symbol keys, undefined, nonfinite values and cycles fail.
+No Proxy side-effect immunity or immutability is promised. Tool call parameters/results and HITL
+remain opaque. Background wrapping preserves boolean `true`/`false` as the arguments schema;
+reference/resource restrictions still apply at activation. `makeTool` may add root `type: "object"`
+to typeless `anyOf`/`oneOf` unions whose members are all object schemas, as required by strict
+OpenAI-compatible upstreams; primitives, unknown, and already-typed roots are unchanged, and call
+validation still decodes through the original Effect Schema's JSON codec. Effect 4.0.0 exports
+`Schema.isPattern` to JSON Schema only for `u`-flag regexes (optionally with `d`, `g`, or `y`);
+add `u` to keep model-visible `pattern` hints.
+
+### Tool arguments: `null` and unknown keys
+
+Tool arguments are accepted exactly as advertised: unambiguous `null`s are normalized, and keys
+that would be silently lost are rejected. `ToolDef.parameters` describes the schema's canonical JSON codec, so `Schema.optional(X)` is
+advertised as `X | null`. `makeTool` (validate and execute), `makeInputTool`/`makeInteractionTool`
+call params, and the loop `question` decode model arguments with `Schema.toCodecJson(parameters)`:
+`null` on `Schema.optional(X)` decodes as absent and `withDecodingDefault` still applies,
+`Schema.optional(Schema.NullOr(X))` keeps `null`, and required non-nullable fields still reject it.
+`undefined`-valued keys from in-process callers count as absent.
+Non-finite numbers (the codec's `"NaN"`/`"Infinity"` strings) are validation errors. Objects are
+advertised closed (`additionalProperties: false`), so unknown keys at any depth are model-visible
+validation errors instead of being stripped (also through closed-input declarations whose JSON codec
+bypasses their own parser). Their error message names each unknown key and lists the allowed keys at that path; this includes
+a `null` on another union member's field.
+`resolveTools` also drops `null` where the advertised schema declares a property optional without
+admitting `null` (for example `Schema.optionalKey(X)`, the subagent `model`, or raw MCP schemas)
+before any registration sees the call; `omitNullOptionalToolArguments` (`@yolk-sdk/agent/tools`) exposes that step for hosts
+that dispatch registrations themselves. User-submitted input/interaction responses are unchanged.
+
+### OpenAI Chat Completions, Responses, and extraBody
+
+OpenAI Chat Completions and Responses lowering (including Codex) likewise admits
+`ToolDef.parameters` and tool-call `params` as `Schema.Json` before they are copied onto the request
+body. Non-JSON tool documents and arguments fail as non-retryable `LLMError` `provider_error` before
+transport. `ToolDef.parameters` admits `ToolJsonSchema`; `ToolCall.params` stays opaque. Public Codex wrapper
+`OpenAiCodexTool.parameters` remains `unknown`; that field is not a `Schema.Json` input type.
+
+Optional request-body fields such as `max_output_tokens`, `tools`, `parallel_tool_calls`, and
+`reasoning` are omitted unless present — they are not own-property `undefined`. After lone-surrogate
+rewrite, Chat Completions and Responses request bodies are decoded as `Schema.Json` again and fail
+rather than skipping serialization. Inbound HTTP JSON bodies admit `Schema.Json` before class/helper
+consumption (`invalid_response` on failure). Responses SSE event JSON admits `Schema.Json`;
+non-object JSON events are ignored (not failed), while malformed non-JSON event text still fails
+`invalid_response`. First `response.completed` remains terminal. HTTP error bodies stay raw text for
+`classifyProviderFailure`.
+
+Chat Completions transport defaults to one JSON body. Set `OpenAiProviderConfig.streaming: true` to
+request incremental `chat.completion.chunk` SSE deltas with `stream_options.include_usage`, folded
+into text/reasoning/tool-call events plus terminal and usage events. Unterminated streams fail
+`invalid_response` and never emit `Done`. Hosts must only enable streaming against endpoints that
+serve chat SSE; OpenCode Go `chat-completions` always sets it.
+
+`OpenAiProviderConfig.extraBody` takes `OpenAiRequestExtras` (JSON-object input). Lowering
+projects enumerable own string fields into an independent portable-data snapshot. Canonical
+`model`, `messages`, `stream`, `tools`, `parallel_tool_calls`, `max_completion_tokens`, and
+`max_tokens` are discarded **without reading their values**; `reasoning` is also discarded when
+`reasoningEffortFormat` is `reasoning-object`. Root symbols/non-enumerable fields are not projected.
+Surviving accessors are rejected unread. Nested values must be finite JSON data with plain/null
+prototypes or dense ordinary arrays; exotic objects, cycles, hidden/symbol keys and extra array
+properties fail. DAG aliases remain aliases in the snapshot; the input is not mutated or retained.
+Invalid extras fail with non-retryable `provider_error`, fixed message
+`Invalid … extraBody JSON: expected a JSON object`, and no HTTP request. Messages never echo values.
+The composed request still passes final `Schema.Json` admission after lone-surrogate rewriting.
+This is not a guarantee against Proxy traps. Gateway routing projects its declared `order`, `only`
+and `sort` fields into JSON; canonical headers and provider identity stay host-owned.
+
+### OpenAI Realtime tool JSON
+
+Public `OpenAiRealtimeFunctionTool.parameters` and `openAiRealtimeToolParameters(parameters: Schema.Json)`
+now require admitted JSON. Non-JSON advertisement fails `VoiceToolBridgeError` before transport:
+synchronous `toOpenAiRealtimeTool`, `makeOpenAiRealtimeSessionConfig`, and
+`openAiRealtimeSessionConfigFromVoice` throw; `toOpenAiRealtimeToolEffect`,
+`makeOpenAiRealtimeSessionConfigEffect`, and `openAiRealtimeSessionConfigFromVoiceEffect` fail in the
+Effect error channel. Unexpected mapper defects (for example throwing getters) remain defects via
+`Effect.suspend` / `Result`, not `VoiceToolBridgeError`.
+
+Union-root lowering uses `Map<string, Schema.Json>` plus `Object.fromEntries` so own `__proto__` /
+`constructor` fields merge (first-seen / string-enum union) instead of prototype assignment or
+inherited `constructor` masquerading as Schema.Json. Required intersection, empty-required omission,
+and object-root identity are unchanged.
+
+## Provider failures and retries
+
+Provider adapters classify safe failure metadata at the boundary. The loop owns bounded retry
+policy and emits protocol-visible retry/error state:
+
+- `ProviderErrorInfo` carries safe provider id, failure kind, HTTP status, provider code, optional
+  `retryAfterMs`, and optional `stream` diagnostics (`ProviderStreamDiagnostics`) on chat
+  `unexpected_content_type` / `incomplete_stream` failures. Diagnostics contain counters and
+  milestones, never transcript content, raw headers, or body fragments. See the
+  [stream diagnostics guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/troubleshooting.mdx#diagnose-chat-stream-failures-with-stream-diagnostics).
+- Chat Completions and Responses HTTP failures copy the envelope string `code` (falling back to
+  `type`) into `provider.providerCode`; free-text upstream bodies stay out of `LLMError`.
+- `AgentRetry.provider` exposes current retry metadata and chosen `delayMs`.
+- `AgentError.provider` preserves final terminal metadata.
+- `AgentErrorCode` includes `rate_limit`, `overloaded`, `context_overflow`, and generic
+  `provider_error`.
+- Client and React state keep `error: string | null` for compatibility and add typed `errorInfo` /
+  `retryInfo`.
+- `buildAgentChatItems` can project active retry state as an `AgentChatItem` with `_tag: 'Retry'`.
+- Anthropic prompt-too-long responses become non-retryable `context_overflow`; the host-owned
+  compaction wrapper may compact and retry once.
+- Anthropic `max_tokens` and OpenAI-compatible `finish_reason: "length"` / `"content_filter"`
+  completions fail as non-retryable `invalid_response` instead of reporting truncated or filtered
+  output as complete.
+
+Raw provider response bodies stay out of protocol/UI. Hosts own durable persistence and display of
+typed retry/error state.
+
+## Subscription allowance snapshots
+
+The Claude, Codex, and Grok usage adapters read best-effort consumer subscription allowance
+percentages and reset windows. Claude normalizes its aggregate five-hour and seven-day windows;
+Codex normalizes primary and secondary rate-limit windows; Grok normalizes its aggregate shared
+credit allowance. Additional provider-specific buckets are ignored. These private provider
+endpoints may change without notice. Pass a fresh host-owned `OAuthAccessToken` and provide an
+Effect `HttpClient`:
+
+```ts
+import { Effect } from 'effect'
+import { FetchHttpClient } from 'effect/http'
+import { fetchOpenAiCodexSubscriptionUsage } from '@yolk-sdk/agent/providers/openai/codex-usage'
+
+const snapshot = await fetchOpenAiCodexSubscriptionUsage(hostOAuthAccessToken).pipe(
+  Effect.provide(FetchHttpClient.layer),
+  Effect.runPromise
+)
+```
+
+Use `fetchAnthropicClaudeSubscriptionUsage` from
+`@yolk-sdk/agent/providers/anthropic/usage` for Claude. Use
+`fetchXAiGrokSubscriptionUsage` from `@yolk-sdk/agent/providers/xai/usage` for Grok and pass the
+actual authenticated xAI `user_id` as `xAiUserId`. The generic token `accountId` is not interpreted
+as an xAI user id. Also pass your host integration's truthful version as `clientVersion`; the
+adapter sends it with `x-grok-client-mode: headless` and never claims an official Grok client
+version.
+
+Provider adapters return an immutable Effect `Chunk` of semantic window ids, percentages, and
+optional reset/duration fields; hosts own labels, polling, persistence, stale-data policy, alert
+thresholds, billing interpretation, and UI. Configure `requestTimeoutMs` at the server integration
+boundary. Each fetcher defaults to its exported URL constant; the optional `url` override is only
+for a trusted proxy or local emulator, because the credential is sent to it. `FetchHttpClient.layer` is configured for manual
+redirects. A custom `HttpClient` must not follow redirects for these credential-bearing requests.
+
+Subscription allowance snapshots are separate from protocol `AgentUsage`, which accounts for tokens
+used by model requests and nested model work.
+
+## Usage accounting
+
+Provider `LLMUsage` events are additive deltas. Adapters normalize vendor counters before emitting;
+for example, Anthropic stream snapshots become deltas and cached input tokens count toward input
+totals. The loop aggregates usage and emits protocol `UsageUpdate` / terminal usage for hosts to
+persist or display.
+
+## Context compaction
+
+`@yolk-sdk/agent/compaction` provides pure budgeting, planning, estimation, checkpoint, and
+formatting utilities plus Effect-native context-transformer and provider-retry adapters. It does
+not summarize or persist checkpoints. Hosts own thresholds, summary policy, durable storage, and
+active-run guards. The one-shot context-overflow wrapper calls your host compactor.
+
+```ts
+import {
+  makeContextBudget,
+  makePreviewSummaryMessage,
+  makeWindowCompactionTransformer
+} from '@yolk-sdk/agent/compaction'
+
+const budget = makeContextBudget({
+  contextWindowTokens: 200_000,
+  reservedOutputTokens: 20_000,
+  warningRatio: 0.8,
+  compactionRatio: 1
+})
+
+const ContextLayer = makeWindowCompactionTransformer({
+  strategy: 'window-summary-v1',
+  thresholdTokens: budget.compactionInputTokens,
+  tailMessageCount: 16,
+  makeSummaryMessage: messages => makePreviewSummaryMessage(messages)
+})
+```
+
+The default estimator uses provider-neutral character and media heuristics. Pass
+`TokenEstimateOptions.countTextTokens` to improve estimates for selected message text, reasoning,
+and host tool-call identifiers, or pass a whole-transcript `estimateTokens` to planners and
+transformers. Exact provider-request accounting must also include system prompts, tool definitions,
+vendor framing, and a safety margin. Reuse one estimator for warnings, planning, and before/after
+checks; tokenizer dependencies remain host-owned.
+
+## Skillsets
+
+`@yolk-sdk/agent/skillset` parses skill Markdown and slash-command Markdown into portable
+`SkillInfo`, `CommandInfo`, and `SkillsetManifest` data. Use `parseSkillMarkdown` /
+`parseCommandMarkdown` at file or database boundaries, `renderCommand` for command invocation, and
+`mergeSkillsets` to combine host sources. Earlier sources win name conflicts; duplicate names
+inside one source fail validation. Hosts own file discovery, storage, enablement, and source order.
+
 ## Protocol content
 
 `Content` is either plain text or ordered parts:
@@ -71,55 +531,485 @@ const program = run({
 - `AudioPart` with `InlineBase64`, `Url`, or host-owned `Ref` source
 
 Build sources with `inlineBase64AttachmentSource`, `urlAttachmentSource`, or
-`refAttachmentSource`. Providers require inline/resolved media before lowering. Use inline base64
-for simple apps, or persist `Ref` values and call `resolveContentAttachmentSources` at your storage
-boundary before provider execution. Host apps own upload, auth, retention, and ref hydration policy.
+`refAttachmentSource`. OpenAI-compatible Chat Completions providers support inline text documents;
+native PDF `DocumentPart` lowering is opt-in through `supportsPdfAttachments`, while Vercel AI
+Gateway enables it by default (set `supportsPdfAttachments: false` to disable it). For URL-backed
+user-message PDFs, both opted-in generic OpenAI chat and Gateway use the host-provided `HttpClient`
+to fetch and buffer the PDF before sending inline file data; the provider does not fetch the URL.
+Hosts must authorize attachment URLs and enforce destination and redirect policy, streamed-byte
+limits, timeouts, safe logging, and credential isolation so provider credentials are never attached
+to attachment destinations. The SDK resolver does not establish those guarantees. Prefer validated
+inline bytes when the host cannot provide a bounded attachment transport. OpenAI Chat and Vercel AI
+Gateway support image URLs; OpenAI Codex supports image
+and document URLs; Anthropic supports image and PDF URLs. The Grok
+Responses lowerer can encode image URLs/data URLs, but hosts should enable image capability only for
+subscription models they have verified accept image input. Use
+inline base64 for simple apps, durable URLs for app-owned uploads, or persist opaque `Ref` values and
+resolve them immediately before each provider attempt. `resolveContentAttachmentSources` handles one
+`Content`; `resolveMessageAttachmentSources` and `resolveMessagesAttachmentSources` also walk assistant
+text and nested provider tool results, preserving metadata and ordering without mutating history.
+All accept `AttachmentSourceResolver<E, R>`, preserve typed Effect errors/services, and leave opaque
+tool/provider payloads alone. Resolution does not add provider media capabilities or cache sources.
+
+Host apps own upload, authorization, byte/MIME limits, retention, and fresh signing. Put a host
+resolving provider wrapper inside `makeContextOverflowRetryProvider` so compaction sees refs and each
+retry signs the effective context afresh. Never persist the resolved copy. See the
+[private attachment guide](https://github.com/magoz/yolk-sdk/blob/main/apps/docs/content/docs/guides/private-attachments.mdx) for the
+host-owned composition and bounded connector transport.
+
+OpenAI Codex preserves text, image, and document `ToolResultMessage` parts as native function output
+content. Anthropic Claude preserves text, images, inline text documents, and URL/base64 PDFs as
+nested tool-result content. OpenAI-compatible Chat Completions, including Vercel AI Gateway, keep
+tool-result text in the tool message and lower images, readable text documents, and opted-in PDFs to
+origin-labeled supplementary user content after the complete tool-result block. Canonical history is
+unchanged. Audio, unresolved references, and other document formats still fail before the provider
+request.
+
+```ts
+import { ImagePart, UserMessage, urlAttachmentSource } from '@yolk-sdk/agent/protocol'
+
+const message = UserMessage.make({
+  content: [
+    ImagePart.make({
+      source: urlAttachmentSource('https://cdn.example.com/image.webp'),
+      mimeType: 'image/webp'
+    })
+  ]
+})
+```
+
+For text files, use `documentPartFromText`, `inferTextDocumentMimeType`, and the client helper
+`documentPartFromTextFile` to create UTF-8 inline
+`DocumentPart` values without trusting filename extensions over explicit non-text MIME types.
 
 Use model capabilities like `textOnlyModelCapabilities`, `textImageModelCapabilities`, or
 `textImageDocumentModelCapabilities` so the loop rejects unsupported inputs before provider calls.
 
+## Message envelope
+
+Messages may carry model-visible envelope facts without polluting authored `content`:
+
+```ts
+UserMessage.make({
+  content: 'Can you summarize this?',
+  createdAtMs: 1781260200000,
+  author: { displayName: 'Magoz' },
+  annotations: {
+    source: 'web',
+    ui_origin: 'document_toolbar',
+    timezone: 'Europe/Madrid',
+    locale: 'en-US',
+    input_method: 'keyboard',
+    message_kind: 'question',
+    client_sent_at: '2026-06-12T10:30:00.000Z'
+  }
+})
+```
+
+- `content`: authored message body only.
+- `createdAtMs`: message creation/sent time; providers render it as ISO `sent_at` context.
+- `author.displayName`: presentation label only; not identity, auth, or a stable id.
+- `annotations`: app-owned JSON object; context only, not instructions.
+
+Provider adapters can use `messageContextText` and `prependMessageContextToContent` to render
+envelopes into model input while keeping `content` authored-only.
+
+Annotations must be JSON-compatible. Use stable app-owned keys, preferably `snake_case`. Use ISO
+strings for dates inside annotations. Never put secrets, credentials, private ids, auth state, or
+hidden policy in annotations, author, or timestamps; providers may send them to models.
+
+## Replay-safe chat projection
+
+Durable transports may reconnect or replay overlapping chunks. Protocol events can carry optional
+`eventId`; `LLMTextDelta` and `LLMReasoningDelta` can also carry `textSoFar` / `reasoningSoFar`
+snapshots when a host can provide cumulative text.
+
+Use `applyAgentEventToChatProjection` for replayable event logs:
+
+```ts
+import {
+  applyAgentEventToChatProjection,
+  makeAgentChatEventProjectionState
+} from '@yolk-sdk/agent/react'
+
+const projection = events.reduce(
+  (state, event) => applyAgentEventToChatProjection(state, event),
+  makeAgentChatEventProjectionState()
+)
+```
+
+Use `applyAgentEventToChatMessages` only for ephemeral local streams where append-only deltas cannot
+replay.
+
+When the host promotes queued user input into a durable stream, emit a replay-safe user event:
+
+```ts
+import { UserMessage, UserMessageEvent } from '@yolk-sdk/agent/protocol'
+
+const event = UserMessageEvent.make({
+  eventId: 'session_1:user-message_42',
+  message: UserMessage.make({ content: 'Please also compare the alternatives.' })
+})
+```
+
+The host owns queueing and promotion policy and must assign a stable `eventId` so reconnects do not
+project the same promoted message twice.
+
+## Parallel tool calls
+
+OpenAI, Vercel AI Gateway, OpenAI Codex, and Grok requests enable vendor parallel tool calls when tools are available. The
+Codex stream adapter preserves every sibling function call and suppresses final-response replays
+by call id. The loop executes calls emitted in the same model turn concurrently, bounded by the
+host-configured `LoopConfig.toolConcurrency`; dependent work waits for the next model turn.
+
+## Transcript invariants
+
+Every assistant host tool call must be followed by a matching `ToolResultMessage` before the next
+non-tool message/provider request. Use `validateNoDanglingHostToolCalls` for preflight checks,
+`danglingHostToolCalls` for diagnostics, and `repairDanglingHostToolCalls` only when loading older
+persisted transcripts that already have gaps. Built-in providers reject dangling host tool calls
+before vendor lowering with a non-retryable validation error.
+
 ## Human-in-the-loop
 
 HITL is protocol-level, not UI-level:
 
 - Add `approval: { mode: 'manual' }` to a `ToolDef` to pause before execution.
 - `run` / `runRuntime` emit `ToolApprovalRequested` then `AgentAwaitingInput`.
-- Resume by passing `hitlResponses` or using client helpers like `submitToolApprovalResponse`.
+- Resume by passing `hitlResponses`, using `useAgentChat` methods like
+  `submitToolApprovalResponse` / `submitQuestionResponse`, or using client stream helpers like
+  `streamToolApprovalResponseEventStream`.
 - Denials become model-visible `ToolResult` messages with `isError = true`.
-- Use `makeQuestionToolModule` to expose the package-owned `question` tool; answers resume as structured tool results and model-visible text with selected labels.
+- Use `makeQuestionToolModule` to expose the package-owned `question` tool; answers resume as structured tool results and model-visible text with selected labels. The loop intercepts questions only when the tool is enabled in `tools`; omitted questions return an unavailable result without HITL or executor dispatch, even if a provider emits one.
+- Use `makeInputTool({ name, description, response, renderer })` for custom typed input. Apps own the response Effect schema and renderer; the SDK carries JSON data only. Pass `resolveTools(...).inputs` alongside `tools` to loop/runtime configs. The original `callParameters` and `response` schemas validate server-side, including refinements; display JSON Schema is not the validator. Invalid calls fail before prompting; invalid submissions remain pending for correction. The first valid submission or cancellation settles the request and cannot be overwritten by stale responses.
+- Resume custom inputs with `submitInputResponse`, `streamInputResponseEventStream`, or WebSocket `InputResponseInput`. Echo request/call IDs; do not reconstruct them. Input collection is not authorization: a draft composer never grants permission to send. Input tools cannot carry approval/background policy or execute directly.
+- Use `makeInteractionTool` when a person must edit proposed values and authorize one server-defined action. Unlike data-only inputs, interactions execute the selected action on the exact validated values before the next model turn. Hosts own renderers, authentication, scoped immutable receipt storage, and atomic acceptance; browser responses alone never authorize execution. Pass `interactionHost` to `resolveTools`, then both `toolSet.interactions` and `toolSet.interactionHost` to loop/runtime configs. Durable hosts load `loadInteractionReceipts` before passing `interactionReceipts` to `prepareToolBatch`.
+- Submit interactions with `submitInteractionResponse`, `streamInteractionResponseEventStream`, or WebSocket `InteractionResponseInput`; the host must authenticate and atomically accept the response server-side before SDK resume. Submission is not completion; only real server results settle the UI. An `unknown` outcome needs host reconciliation, never automatic action retry. Voice/realtime and background activation are unsupported. See [action-backed interactions](https://github.com/magoz/yolk-sdk/blob/main/packages/agent/src/tools/README.md#action-backed-interactions) for registration and host-boundary details.
+- Use `questionResponseStructuredContent` / `plainHitlResponse` before storing durable HITL payloads that must be plain JSON. `PlainHitlResponse` is a `Data.taggedEnum` value (`QuestionResponse` / `ToolApprovalResponse` / `InputResponse` / `InteractionResponse`); the helpers omit absent optionals then call those constructors (`_tag` last, plain objects, not Schema classes).
+- Use `toolRunsFromHitlRequests` to hydrate paused UI state from `AgentAwaitingInput.requests`.
+- Use `hitlResponseEvent` when a client needs optimistic approval/question UI updates before resumed stream events arrive. Typed input and interaction submissions stay pending until server acceptance; accepted interactions stay active until the actual outcome. Never synthesize an interaction result from local submission or acceptance.
 - Approval is a host-enforced per-call gate for normal tools, not a model-callable permission tool or persisted allow-always system.
 
-## Task subagents
+HTTP client helpers treat `AgentEnd`, `AgentError`, and `AgentAwaitingInput` as logical stream
+end for consumers. Use `isTerminalAgentEvent` when projecting generic protocol streams. After a
+terminal event the response body drains to EOF; cancellation before a terminal event still aborts
+the active body reader.
+Durable Workflow clients can use `streamAgentEventStreamUntilTerminal`,
+`streamAgentRunEventStreamUntilTerminal`, and `streamAgentRunHitlResponseEventStreamUntilTerminal` to follow
+continuation chunks by `x-workflow-run-id` and `x-workflow-stream-tail-index` headers. These helpers
+fail with `AgentTransportError` if no terminal event is reached before the continuation limit.
+Empty non-terminal continuation chunks are polling gaps: the client waits briefly, retries from the
+same `startIndex`, and respects the request `signal` while waiting.
+Outbound `startIndex` values must be non-negative safe integers; invalid values fail before the
+HTTP request is sent.
+For HITL resume responses, `x-workflow-stream-tail-index` means the stream tail before the returned
+body. The returned body starts at `tail + 1`; the next continuation starts after all returned
+events. `continuationLimit: 0` disables follow-up chunks, so any non-terminal response fails
+immediately.
+
+```ts
+import { Stream } from 'effect'
+import { streamAgentEventStreamUntilTerminal } from '@yolk-sdk/agent/client'
+import { UserMessage } from '@yolk-sdk/agent/protocol'
+
+const events = Stream.toAsyncIterable(
+  streamAgentEventStreamUntilTerminal({
+    endpoint: '/api/agent/workflow',
+    sessionId: 'session_1',
+    messages: [UserMessage.make({ content: 'Hello' })],
+    runEndpoint: runId => `/api/agent/workflow/${encodeURIComponent(runId)}`
+  })
+)
+
+for await (const event of events) {
+  // Apply AgentEvent to app state.
+}
+```
+
+The SDK client does not own durable route auth, run ownership, Workflow hook-token routing, or HITL
+request matching. Hosts expose the run endpoints and validate access/response identity server-side.
+
+## Voice
+
+`VoiceSession.layer` (`@yolk-sdk/agent/voice`) composes a supplied `VoiceTransport` layer,
+`VoiceController`, and an optional `VoiceEventOutbox`. Configured `eventLog` captures events without
+an external stream consumer; omitting it never captures an ambient outbox. The returned event stream
+has one queue consumer and is not a broadcast subscription. Without a consumer, events accumulate
+in memory; hosts should normally drain it. Seeds run during acquisition.
+
+Breaking 0.x migration: `makeVoiceController` no longer takes `options.transport`; provide
+`VoiceTransport` with `Effect.provideService`, or use `VoiceSession.layer`.
+`webRtcVoiceTransportLayer` (`voice/browser`) and `webSocketVoiceTransportLayer` (`voice`) acquire
+scoped transports. `Layer.succeed(VoiceTransport, transport)` injects a caller-owned value; it does
+not allocate/finalize it or guarantee fresh resources. Keep the entire usage effect inside a
+provided layer, or use `Layer.buildWithScope` when an explicit session scope owns its lifetime.
+`useYolkVoice` builds each attempt in that attempt's scope and retains stop/unmount cleanup.
+
+Voice is a first-class modality: browser WebRTC transport, client controller, server tool
+handler, approval HITL, transcript projection, and one-shot TTS/STT contracts.
+
+- `useYolkVoice` (`@yolk-sdk/agent/voice/react`) owns browser session lifecycle, user drafts,
+  and pending approvals; provider codecs come from `@yolk-sdk/agent/providers/openai/realtime`.
+- Tools execute server-side only: the controller forwards the normalized
+  `VoiceSessionToolCallRequest` JSON envelope to your endpoint; `handleVoiceToolCall` returns a
+  JSON-compatible `VoiceToolCallOutcome` envelope, applies `ToolDef.approval` policy, and never runs
+  approval-gated tools without a matching approved response.
+- Approval-gated calls pause with `AwaitingInput`; approvals/denials resume through
+  `submitHitlResponse`. Voice questions and custom typed inputs are unsupported in v1.
+- `projectVoiceEvent` turns voice events into protocol messages with no dangling host tool
+  calls. Assistant drafts are keyed per provider output item (falling back to response id), so
+  back-to-back responses, multi-item responses, and duplicate final transcript event families
+  never concatenate, wipe, or duplicate messages. `sequenceVoiceEvent`/`dedupeStoredVoiceEvents`
+  give replay-safe durable event ids; `voiceSeedTextsFromMessages` seeds new provider sessions
+  after reconnect, optionally prefixing user seeds with author display names via
+  `{ includeAuthors: true }` for multi-user transcripts.
+- `makeWebSocketVoiceTransport` covers Node/server realtime sessions and requires a host-provided
+  `Socket.WebSocketConstructor` layer, such as `Socket.layerWebSocketConstructorGlobal`;
+  `@yolk-sdk/agent/providers/openai/speech` provides `makeOpenAiSpeechSynthesizerLayer` and
+  `makeOpenAiTranscriberLayer` for the provider-neutral voice services.
+  `VoiceSpeechRequest.instructions` steers delivery style only, and
+  provider 429s (rate limit or exhausted credits) surface as `VoiceSpeechError` code
+  `rate_limited` so hosts can distinguish quota from outage.
+- Browser WebRTC hosts that implement `WebRtcPeerConnectionLike`
+  (`@yolk-sdk/agent/voice/browser`) treat `addTrack(track, stream)` as a void command. The
+  transport discards the DOM `RTCRtpSender`. Hosts and fakes must not read a sender from this
+  capability. Real `RTCPeerConnection.addTrack` remains assignable.
+- `protocolToolCallFromVoice` still returns `ToolCall`. Voice raw argument JSON admits finite
+  JSON (`Schema.Json`). Actual `null`, `false`, and `0` still admit as those values. Non-JSON
+  and non-finite numbers fail admission: raw text `1e999` projects as the argument string
+  `'1e999'`, and `decideVoiceToolCall` approval display params are `{ argumentsJson: '1e999' }`
+  (not `Infinity`; do not demonstrate with `JSON.stringify(Infinity)`, which is `null`). Nested
+  overflow such as `{"n":1e999}` takes the same mapper-specific fallbacks. Approval identifiers,
+  gates, deny, and execution schema validation are unchanged.
+
+## Classifier models
+
+`@yolk-sdk/agent/classification` is a provider-neutral contract for classifier models such as
+TypeSafe's Jev: one `state` (a string, JSON object, or JSON array) and named `boolean`, `choice`
+(2-255 options), or `score` (2-10 levels, lowest first) questions, answered together with
+probabilities. `classify` types each answer from its question (a choice answer's `choice` is the
+union of its option keys) and checks every answer against its question. Probabilities are kept as
+returned, never renormalized. Failures are typed (`ClassificationRequestInvalid`,
+`ClassificationProviderError`, `ClassificationResponseInvalid`); a response that fails to decode
+keeps the billed `usage`. Classification is a read; authorization stays host policy.
+
+`@yolk-sdk/agent/providers/vercel/ai-gateway-classifier` calls AI Gateway `POST /v1/evaluate`
+(Gateway calls this evaluation) with `typesafe-ai/jev` by default and the same Gateway credential
+as the chat provider:
 
-`task` is the package-owned contract for subagent delegation. The SDK provides schema,
-validation, non-recursive module wiring, subagent result extraction, and structured task result
-metadata. Host apps provide the actual nested runtime.
+```ts
+import { Effect, Redacted } from 'effect'
+import { FetchHttpClient } from 'effect/http'
+import { classify } from '@yolk-sdk/agent/classification'
+import { makeVercelAiGatewayClassifierLayer } from '@yolk-sdk/agent/providers/vercel/ai-gateway-classifier'
+
+const program = classify({
+  state: { subject: 'Invoice question', body: 'I was charged twice.' },
+  questions: {
+    route: {
+      type: 'choice',
+      instructions: 'Which team should handle this ticket?',
+      criteria: { billing: 'Payments and refunds.', bug: 'Product defects.' }
+    }
+  }
+}).pipe(
+  Effect.map(result => result.answers.route.choice), // 'billing' | 'bug'
+  Effect.provide(makeVercelAiGatewayClassifierLayer({ apiKey: Redacted.make(gatewayKey) })),
+  Effect.provide(FetchHttpClient.layer)
+)
+```
+
+`providerOptions` passes through unchanged (for example `{ gateway: { zeroDataRetention: true } }`).
+`providerMetadata.gateway.cost` becomes `usage.costUsd`, and `x-ai-gateway-evaluation-fallback-*`
+response headers are kept in `providerMetadata.evaluationFallbackHeaders`.
+
+## Subagents
+
+`subagent` is the package-owned contract for child-agent delegation. The SDK provides schema,
+validation, non-recursive module wiring, subagent result extraction, and structured result
+metadata. Host apps provide inline or independently durable child execution.
 
 Recommended setup:
 
-- expose `makeNonRecursiveTaskToolModule` only to the top-level agent
+- expose `makeNonRecursiveSubagentToolModule` only to the top-level agent
 - resolve subagent tools with `subagent: true`
-- omit `task` from subagent toolsets
+- omit `subagent` from subagent toolsets
 - include only tools that are safe for autonomous delegated work
 - use `makeSubagentRunId(call.id)` for protocol-aligned run ids
-- return `makeTaskToolResult(...)` so UI can show subagent id, type, status, model, and timing
-
-See `examples/next/lib/agents/workflow-runtime/text-response.ts` for host-owned execution wiring.
+- optionally configure model and reasoning-effort choices so the parent can select child runtime settings
+- treat omitted `model` and `reasoning_effort` parameters as inheritance of host runtime settings
+- return `makeSubagentToolResult(...)` so UI can show subagent id, type, status, model, reasoning effort, timing, optional usage/turns, and typed failure metadata
+- use `subagentUsageFromToolResult(...)` when a host must add child usage to cumulative workflow usage
+
+Durable hosts may opt into `background: true` in the tool registration options. This advertises
+an optional model parameter `background`; inline hosts keep their existing schema and behavior.
+Return `makeSubagentAcceptedToolResult({ callId, workflowRunId, parentRunId })` for background acceptance.
+The optional parent identity lets a later conversation run address the original child. Keep
+acceptance independent of how quickly the child finishes.
+It emits normal tool completion but **not** `SubagentCompleted`, and carries no usage. Keep the
+logical `subagent:<toolCallId>` identity separate from the physical Workflow id. Never append a
+second tool result for the original launch. Hosts may deliver findings automatically or expose
+host-owned status/wait tools whose observations do not masquerade as fresh child usage. The SDK
+registers none of those observation tools and promises no automatic delivery. Its default background
+parameter and acceptance text therefore defer to host instructions instead of naming unavailable
+tools. Hosts should describe their actual completion policy in model-visible instructions and retain
+lookup identities in accepted-result text if they customize it; structured metadata alone may not
+survive provider lowering. Host-owned storage must remain readable after parent end.
+
+A lost control response or exhausted observation budget is not a terminal child failure. Hosts
+can return a `ToolResult` with `structuredContent.type: 'subagent_observation'` and a matching
+`subagent_run_id: makeSubagentRunId(call.id)`. The loop completes the tool observation but suppresses
+`SubagentCompleted`; nested results do not contribute child usage. Include truthful status and an
+owned recovery handle in the observation. Use normal final results for genuine terminal outcomes,
+not this marker. These child observations are separate from generic background tool `acceptance`.
+
+`prepareToolBatch` from `@yolk-sdk/agent/loop` exposes the same HITL preflight used by the loop.
+Durable orchestration must check `pendingRequests` before dispatching **any** tool, even calls
+listed in `callsToExecute`. Preserve synthetic results and original call ordering when committing.
+
+Keep host-owned subagent execution wiring outside this package; pass only the package subagent contract across the boundary.
+
+## Background tool calls
+
+Any `makeTool` registration can opt into model-chosen background execution with `background: true`.
+The flag is inert until `resolveTools(modules, context, { backgroundHost })` receives a
+`BackgroundToolHost`, which asserts a real lifecycle owner (durable run, queue, or session) exists.
+Without a host, definitions, approval ids, and inline behavior are unchanged.
+
+- Activated tools advertise a required `{ execution: 'foreground' | 'background', arguments }`
+  envelope; the original parameter schema nests under `arguments` and `$defs` stay at the root.
+  Only document-root `#/$defs/...` references (without percent-encoded fragments) are supported.
+  Other reference forms and resource/anchor keywords (`$id`, legacy `id`, `$anchor`, `$dynamicAnchor`,
+  `$dynamicRef`, `$recursiveAnchor`, `$recursiveRef`) fail activation with
+  `ToolRegistryError.cause: 'background_unsupported_schema'`. Literal defaults/examples/const/enum
+  data are not traversed as schemas.
+- The registry validates the envelope and original parameters without business effects, strips the
+  control fields, then executes inline or calls `host.accept({ call, request, context })`.
+  `makeTool` invalid business arguments still return structured model-visible errors in either
+  mode, without business/admission effects. Raw validator and host errors remain typed failures.
+- `accept` returns a versioned `BackgroundToolAccepted` receipt (`{ version: 1, executionId }`),
+  never a closure. Make it idempotent per call id; fail with a `ToolError` to decline. The registry
+  never falls back to inline execution.
+- Use protocol `toolResultMessageFromResult(result, envelope?)` to preserve every result field and
+  receipt when creating transcript messages; timestamps/authors remain explicit host inputs.
+- The result is one acknowledgement `ToolResult` with typed `acceptance` metadata; the loop emits
+  `ToolExecutionAccepted` (no `ToolExecutionCompleted`, no usage). Client state, chat projection,
+  and tool cards treat `Accepted` as settled but not completed; active input/approval/Started
+  replays cannot replace accepted calls or receipts, including across turn cleanup and hydration.
+- Activated definitions are unsupported in voice/realtime, including foreground envelope calls.
+  Resolve voice toolsets without a background host. Synchronous realtime tool/config mappers throw
+  `VoiceToolBridgeError` for unsupported activation **and** for non-JSON tool `parameters`; use
+  `toOpenAiRealtimeToolEffect`, `makeOpenAiRealtimeSessionConfigEffect`, or
+  `openAiRealtimeSessionConfigFromVoiceEffect` inside Effect programs to catch that typed error.
+  Unexpected mapper defects stay defects, not `VoiceToolBridgeError`. Voice handlers deny before
+  approval matching, and the low-level bridge rejects activated registry dispatch before validation,
+  inline execution, or admission.
+- Raw `ToolRegistration` objects need a side-effect-free `validate` to activate; the loop-owned
+  `question` and `subagent` tools cannot activate (subagents keep `makeSubagentAcceptedToolResult`).
+- Manual approval fences the whole batch; activated calls bind the approval `requestId` to the tool
+  name, mode, and canonical arguments, and malformed envelopes are rejected before any prompt.
+  IDs intentionally contain the full canonical payload: hosts must accommodate opaque, potentially
+  long IDs or enforce input bounds before admission; never truncate or rebuild them.
+- Hosts own authorization, status/wait tools, cancellation, terminal storage, usage, and delivery.
+  Never append a second result for the original call.
+
+## Code mode tool contract
+
+These options are the tool contract that [`@yolk-sdk/codemode`](https://github.com/magoz/yolk-sdk/blob/main/packages/codemode/README.md) builds on.
+This package declares them; it does not run scripts.
+
+- `makeTool({ output })` adds declaration-only `ToolDef.outputSchema`, lowered like `parameters`.
+- `callableBy: 'all' | 'model' | 'codemode'` (default `all`) decides who may call a tool. For
+  `codemode` only, `discovery: 'listed' | 'search'` (default `listed`) decides how scripts find it.
+  Codemode-only tools never reach providers. Approval, input, interaction, activated background,
+  `question`, `subagent`, and nested-access tools never run from code mode; `resolveTools` rejects
+  `callableBy: 'codemode'` on them.
+- `nestedToolAccess: true` gives a registration's `execute` a `nested` executor over the other
+  code-mode-callable tools of the same resolution and host context. Nested calls run through the
+  resolved execute path and fail closed with model-visible error results. Assign nested call ids as
+  `<parentToolCallId>/<seq>`.
+- `describe: ({ tools }) => string` on a nested-access registration computes its resolved
+  description from those nested tools; `def.description` stays the static fallback.
+- Report nested calls with protocol `recordNestedToolCall` and `nestedToolCallResultFields`. The
+  bounded `ToolResult.nestedCalls` record and summed `ToolResult.usage` never reach the model:
+  `toolResultMessageFromResult` drops both, and the loop does not add `ToolResult.usage` to run
+  usage. Capture them from the `ToolResult` or tool events when you need audit or billing records.
+  Size the record with `makeNestedToolCallRecorder({ maxCalls })`; per-status `counts` cover
+  every call, dropped ones included.
+
+## Durable tool ledger
+
+Steps that hosts re-execute (Vercel Workflow's queue is at-least-once) must not repeat writes.
+Pass `resolveTools(modules, context, { ledger: { store } })` with a host-implemented durable
+`ToolLedgerStore` scoped to the run: every ledgered call (by default every non-`read` call plus the
+built-in `subagent` tool, top-level or nested in code mode) runs at most once per ledger key. Add
+custom delegation tools with `isLedgered`. Input and interaction tools are never ledgered; their
+at-most-once guarantee is the host's `InteractionHost` receipts. A different call under the same key (tool name or a
+SHA-256 `argsDigest` of the full arguments, a stable format hosts persist) is a conflict, never a
+replay. Completed calls return their stored result, concurrent duplicates wait, and calls abandoned
+by a crash are never re-run (the model is told to verify). Executors receive a stable
+`idempotencyKey`. Stores get the lease length (`leaseMs`) so they can use database time, and must
+keep their operations interruptible (the ledger's timeouts cannot cut uninterruptible store work).
+`deadline` bounds only waiting for a duplicate; recording an outcome can take about 15 s more.
+`onLedgerDecision` reports each call's decision (`fresh`, `completed`, `in_flight_wait`, ...) for
+logs and metrics. Without the option behavior is unchanged. See
+[the tools README](https://github.com/magoz/yolk-sdk/blob/main/packages/agent/src/tools/README.md#durable-tool-ledger).
+
+## Tool failures
+
+Use `modelVisibleToolError(...)` for expected tool-domain failures the model can recover
+from, such as invalid arguments, not-found resources, denied policy, or unavailable upstream
+data. `makeTool` converts these failures into `ToolResult.isError = true` so the agent can
+see the message and continue. The result includes structured content with `type`, `tool`,
+`reason`, `message`, and optional `details` for UI/runtime handling.
+
+Optional `makeTool({ invalidParamsMessage })` receives the `Schema.SchemaError` produced by
+decoding `parameters` through its JSON codec (validate and execute). The decode error is passed
+through unwrapped. Default text is `Invalid ${name} arguments: ${String(error)}`, which keeps the
+`SchemaError(...)` wrapper, followed by one line per object (path and allowed-key set) naming its unknown keys and
+listing the allowed keys. Custom callbacks can append the same hint with `withToolArgumentsErrorHint(message, error)`. In Effect 4, `SchemaError` extends native `Error`, but the
+wrapper remains part of this tool-message contract; do not default to `.message`.
+Existing `(error: unknown) => string` callbacks remain assignable.
+
+Thrown `ToolError`s become model-visible failed tool results plus `ToolExecutionError` events,
+so keep messages safe and non-secret. Reserve stream failure for provider/runtime defects,
+aborts, and implementation bugs outside typed tool execution.
 
 ## Host responsibilities
 
-- Choose models/providers and map provider streams into protocol events.
+- Choose models/providers and provide an LLM provider layer, using SDK provider subpaths or host adapters.
+- Store, refresh, revoke, and authorize OAuth credentials; expose only runtime access tokens.
+- Configure model-specific provider output-token limits.
+- Build UI components and styling, own auth, and wire headless React hooks to host transports.
 - Persist sessions, transcripts, and append logs.
+- Persist/return one `ToolResultMessage` for every host tool call, including `isError` failures.
+- Persist terminal provider failures and clear active run ids where applicable.
 - Provide tools, approval policy, auth, storage, and observability.
+- When steps can re-execute, implement a durable `ToolLedgerStore` scoped to one run (plus the turn
+  or step when call ids can repeat), keep its operations interruptible, and reserve about 15 s of
+  the step budget after `deadline` for recording outcomes.
+- If you send `ToolDef`s to providers yourself (outside `run`/`runModelTurn`), filter them with
+  protocol `providerToolDefs`; codemode-only tools must never reach providers. Executor decorators
+  outside `ResolvedToolSet.execute` do not see nested code mode calls.
 - Compact context and decide memory/search policy.
 
 ## Boundaries
 
-- No React, Next.js, provider SDKs, auth, storage drivers, or app concepts.
+- Core loop/protocol/runtime/tools have no React, Next.js, provider SDKs, auth, storage drivers, or app concepts.
+- `@yolk-sdk/agent/compaction` combines pure planning/formatting helpers with Effect-native transformer and retry adapters; hosts own thresholds, summaries, compaction payloads, and durable compactor policy.
+- `@yolk-sdk/agent/classification` is provider-neutral (no Node, React, or provider code); provider subpaths supply `ClassifierModel` layers.
+- `@yolk-sdk/agent/react` is headless and uses React as an optional peer.
+- Provider subpaths own vendor wire/auth mechanics only; hosts own token storage, refresh, routing, and policy.
+- `@yolk-sdk/agent/providers/openai/speech` is server integration requiring runtime
+  `FormData`/`Blob`, a host `HttpClient` layer, and a secret API key; do not invoke it from browser
+  code.
 - Loop stays stateless: transcript in, events out.
 - Runtime owns generic session orchestration only; host apps own persistence adapters and policy.
+- Client HTTP helpers are runtime-portable with a host `HttpClient` layer. Attachment helpers need
+  `Blob`/`File` and may use `FileReader`; the Cloudflare WebSocket transport needs the global
+  `WebSocket` constructor when its stream runs. None read browser globals at import time.
 - Tools model generic metadata/execution; host apps own concrete tool catalogs.
-- `task` is the standard subagent delegation tool. Packages define the schema; host apps execute subagents and omit `task` from subagent toolsets in v1.
+- `subagent` is the standard delegation tool. Packages define the schema; host apps execute subagents and omit `subagent` from child toolsets in v1.
 
 ## Testing