Module sampling

Expand description

SamplingLlmClient — LlmClient impl backed by an MCP client’s sampling/createMessage capability.

Per the v0.9.0 design (docs/dev-log/0098-v0.9.0-implementation-plan.md §6 “Sampling-backed LLM client” / MAJOR 1 + MAJOR 3 resolutions):

Steward holds an Arc<dyn LlmClient>. When LlmConfig::McpSampling is configured, the Steward’s LlmClient is a SamplingLlmClient constructed at MCP initialize time (when the live peer becomes available — the TenantHandle::steward_slot LATE-population path).
SamplingLlmClient::complete() translates the workspace’s Message → rmcp::SamplingMessage, calls peer.create_message(params).await, extracts the assistant’s text from the returned CreateMessageResult, and emits a per-call AuditOperation::LlmSamplingCall row through the tenant’s WriteHandle (lesson #30: sync in writer-actor tx for ACID).
Privacy invariant: the audit details_json carries metadata only — model hint, message count, max_tokens, duration_ms, total prompt character count, output character count. The raw prompt content MUST NOT appear in the audit row. Pinned by [tests::audit_row_omits_raw_prompt_text].
Error paths land structured audit rows:
- Client refusal → result = "forbidden", details_json.reason = "client_refused".
- Timeout → result = "error", details_json.reason = "timeout".
- Other transport / malformed-response → result = "error", details_json.reason = <category>.
Per-call rate-limit / coalescing is deferred to v0.9.0 P4 (SamplingCoordinator). P2 wires the per-call path only.

Structs§

PeerSamplingClient: Production wrapper around rmcp::Peer<RoleServer>. The Peer is cheap to clone (internally Arc-backed) and stays valid for the lifetime of the MCP session.
SamplingLlmClient: LlmClient impl whose complete() calls back via the connected MCP client’s sampling capability.

SamplingError: Error surface for SamplingClient::create_message. Combines the real rmcp ServiceError (when wrapping a live Peer<RoleServer>) with [super::super::test_support::fake_mcp_client::FakeSamplingError] (when driving the fixture from tests).

DEFAULT_SAMPLING_TIMEOUT: Default per-call timeout. Drives the bounded wait around peer.create_message; if the client refuses or stalls, the caller sees a structured timeout error instead of an indefinite hang.

SamplingClient: Trait abstracting the sampling/createMessage RPC. The production impl wraps Arc<Peer<RoleServer>>; the test impl is [super::super::test_support::fake_mcp_client::FakeMcpClient].

build_sampling_steward: v0.9.0 P2: build a sampling-backed Arc<Steward> for a tenant that has resolved LlmConfig::McpSampling and just attached an MCP session.