mirror of
https://github.com/nearai/ironclaw.git
synced 2026-06-09 03:24:59 +08:00
b921b42998
* docs(api): document the Responses API end-to-end Covers auth (gateway token vs per-user /api/tokens), session continuity via previous_response_id, streaming, externally-provided function tools (the engine-native round trip landed in #3122), structured x_context, per-request instructions, error envelope, and the current limits (one-call-per-turn, no tool_choice, no temperature). Wires the new page into docs.json under a top-level "API" group so it sits next to Channels and Extensions rather than buried under Capabilities. * docs(api): address PR #3709 review feedback Verified against the current code, not just the bot suggestions: - Auto-generated gateway token: 32 random bytes hex-encoded => 64 chars, not 32 (src/channels/web/mod.rs:118-121). - Token create response field: token_prefix, not prefix (src/channels/web/handlers/tokens.rs:92). - Streaming events: response.in_progress is defined but the worker only emits response.created (src/channels/web/responses_api.rs:1530-1536), so drop the row that promises an event clients never see. - Auth errors: the gateway middleware returns plain-text 401/403/503 before the request reaches the Responses handler (src/channels/web/platform/auth.rs:1133), not the JSON envelope. - previous_response_id ownership: 404 is the GET behavior only; POST decodes the UUID and dispatches into the agent (src/channels/web/responses_api.rs:1237-1244), so cross-user resume fails at the turn level, not via 404. - instructions caveat: IronClaw currently prepends the <instructions> block into the user message and persists it (responses_api.rs:1231-1234), so it does replay across turns even though the OpenAI spec promises one-turn semantics. - Anchor: #input-shapes never existed; point to #external-tools where the array form is actually shown. The Gemini bot also flagged `resp.output_text` as a phantom property across both SDK examples. Verified directly against openai-python/src/openai/types/responses/response.py:310-322 and openai-node/src/resources/responses/responses.ts:963 - both expose output_text as a convenience aggregator over output_text content blocks, and their own docstrings recommend it over walking output[0]. SDK examples kept as-is.