docs(spec+plan): session-aware structured output for agent.session.send

[jddunn]

Two-file pair documenting the design and implementation of an optional responseSchema parameter on AgentSession.send that routes through each provider's native structured-output API while preserving session memory:

• OpenAI: response_format: { type: 'json_schema', json_schema: { ... } }
• Anthropic: forced tool-use (single tool with input_schema, tool_choice forced)
• Gemini: responseMimeType + responseSchema in generationConfig
• OpenRouter / unknown: degrades to json_object (no schema enforcement)

Existing agentos plumbing already partially in place: generateText already passes _responseFormat through to providers, OpenAIProvider already forwards the OpenAI shape verbatim (line 662), AnthropicProvider already builds tool_choice (line 848), GeminiProvider already maps json_object to responseMimeType (line 732). What's missing is exposing this on session.send (currently text-only) plus per-provider routing of schema-bearing payloads.

Motivation: paracosm's commander/department/judge calls fail schema validation 3x in a row on gpt-5.4-mini and fall back to the literal "Commander decision unavailable; defer to department consensus" text in stored artifacts. With native enforcement the retry loop becomes dead code.

Plan is 6 tasks + verification, ~315 lines of source + tests across 5 files, fully backward-compatible. No breaking change to any existing API.

Summary

• What does this PR change?
• Why is this change needed?

Checklist

• Tests added/updated
• Docs updated (README or typedoc)
• Conventional commit title/body

Related

Fixes # (issue)

Summary by Sourcery

Document the design and implementation plan for adding session-aware structured output to agent.session.send, enabling schema-enforced, provider-native structured responses while preserving session memory.

Documentation:

• Add a design spec describing how agent.session.send will accept a Zod response schema and route it through provider-native structured output mechanisms for OpenAI, Anthropic, Gemini, and fallbacks.
• Add an implementation plan detailing the new adapter, provider-specific handling, API overloads, testing strategy, and rollout steps for session-aware structured output in agent.session.send.

Summary by CodeRabbit

• Documentation
  • Added comprehensive implementation plan for session-aware structured output with provider-native support (OpenAI, Anthropic, Gemini), Zod schema validation, and memory persistence across requests
  • Added design specification detailing API extensions for optional response schemas, typed object parsing, and intelligent routing across multiple AI providers