SMOODEV-1472: Structured output (JSON-schema constrained responses) in the LLM client

[brentrager]

What

Implements structured output in the smooth-operator engine's LLM client — the keystone Phase 5 parity gap (SMOODEV-1472). The general-agent brain must emit a typed JSON object every turn; this gives the client a way to request a schema-constrained JSON response and parse it back in a typed way.

API added

• ResponseFormat (public enum, re-exported from the crate root):

  pub enum ResponseFormat {
      JsonSchema { name: String, schema: serde_json::Value, strict: bool },
  }
  // ctor (defaults strict = true):
  ResponseFormat::json_schema(name: impl Into<String>, schema: serde_json::Value) -> Self

• LlmClient:
  • chat_structured(&self, messages: &[&Message], format: &ResponseFormat) -> Result<LlmResponse>
  • chat_with_format(&self, messages: &[&Message], tools: &[ToolSchema], format: Option<&ResponseFormat>) -> Result<LlmResponse> (core; chat now delegates with None)
• LlmResponse parse helpers:
  • structured_json(&self) -> Result<serde_json::Value>
  • deserialize_json<T: DeserializeOwned>(&self) -> Result<T>
  • Both surface a clear error (with a content snippet) on empty/non-JSON content — never a silent empty/null value.
• LlmProvider trait gains chat_structured; MockLlmClient records the requested ResponseFormat on RecordedCall.response_format.

OpenAI vs Anthropic handling

• OpenAI-compatible (ApiFormat::OpenAiCompat, the LiteLLM gateway path): serialized on /chat/completions as
  response_format: { type: "json_schema", json_schema: { name, schema, strict } }.
• Anthropic-native (ApiFormat::Anthropic, /v1/messages): Anthropic has no response_format, so structured output is done via a forced single tool call — a synthetic tool whose input_schema IS the requested schema, forced with tool_choice: { type: "tool", name }. The forced tool's input is surfaced back as the JSON content string, so both paths return the same shape. Schema names are sanitized to valid Anthropic tool names.

Tests (TDD, via MockLlmClient)

• OpenAI request carries the response_format json_schema object (and is omitted when absent).
• Anthropic forced-tool request serialization (tool_choice + tool input_schema).
• chat_structured records the requested format; plain chat records None.
• JSON response parses via structured_json() and deserializes into a typed T.
• Non-JSON / empty response surfaces a clear error (asserts it does not silently return empty).
• Scripted error propagation; trait-object usage; sanitize_tool_name edge cases.

All 353 crate tests pass; cargo fmt --check, cargo clippy --all-targets -D warnings, release build, and cargo publish --dry-run --locked are green. Changeset added (minor). No new deps (Cargo.lock unchanged).

Follow-ups (deferred, noted in code + changeset)

• Streaming structured output (chat_stream sends response_format: None today).
• Agent-level wiring (Agent::run schema-constrained final response) — the agent tool loop is large; the client + provider + mock surface is landed here so it's unblocking.

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 1b6c25e

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR