mirror of
https://github.com/nearai/ironclaw.git
synced 2026-09-03 08:06:01 +08:00
6dccbfbcbd
* docs: fix live drift in extension, responses API, and channel docs The public tutorial taught the retired manifest v2 authoring format ([[host_api]] / [capability_provider.tools] / runtime_credentials), which the v3 parser hard-rejects, and never mentioned origin_gate_matrix; the Responses API page claimed temperature is rejected (accepted 0.0-2.0 and forwarded), claimed model must be "default" (any well-formed name <= 256 bytes), claimed max_output_tokens is rejected (accepted and ignored by DTO policy), and omitted the required model field from every request example; the channel tutorial pointed at two files that no longer exist. - docs/extensions/building-a-tool.md: rewrite manifest sections to the v3 [[tools]] / [[tools.credentials]] / [auth.<vendor>] shape, document origin_gate_matrix (origins, policies, ratchet), correct the hosted-MCP [mcp] section, packaging via ironclaw_extension_support package modules, and v3 test references; drop the nonexistent script runtime kind. - docs/api/responses.mdx: correct model/temperature/tools/tool_choice rejection rules, document unknown-field tolerance, add the required model field to all 15 request examples. - docs/channels/building-a-channel.mdx: replace dead crates/ironclaw_first_party_extensions + available_extensions.rs registration instructions with the current package-directory mechanism. - docs/reborn/contracts/extensions.md: state that production manifests author v3 (lowering into the v2 resolved model described there); label the v2 examples as legacy. - docs/reborn/how-to-port-tool-to-reborn.md: superseded banner pointing at the v3 guides. Part of #7317 (doc-truth pipeline, PR 1 of 5). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: address Copilot and CodeRabbit review on doc-drift PR - responses.mdx: tool_choice is rejected only without external-tools wiring; with external tools enabled it passes validation and is currently ignored (validate_responses_supported_fields_with_external_tools never checks it). - building-a-tool.md: clarify that effect-derived host ports are validation vocabulary against the HostPortCatalog allowlist; adapters are built by host-runtime services after authorization/obligations, never from manifests. - how-to-port-tool-to-reborn.md: mark the decision tree's RuntimeKind targets historical (v3 accepts only wasm|first_party; MCP is top-level [mcp]; process/CLI work is the sandbox lane). - building-a-channel.mdx: document the user install flow — virtual package root /system/extensions/<id>/manifest.toml, ironclaw extension search / install <extension-id> (ID, not path), WebUI Extensions lifecycle. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(responses): align the limits bullet with the corrected tool_choice claim The rejection list was corrected in the previous commit (tool_choice is rejected only without external-tools wiring); the "Limits and quirks" bullet still said "not supported ... rejected with 400". Same claim, one wording. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs: apply verified code-review findings on the drift PR A full code review of this PR against live code surfaced claims the original drift pass got wrong or missed; every fix below was re-verified against the cited source before editing: - responses.mdx: standard `ironclaw serve` deployments always wire external tools (OpenAiCompatRouteMountPorts requires the store/resume pair; mount.rs wires them unconditionally), so `tools` is accepted and `tool_choice` is accepted-and-ignored on shipped binaries — the conditional 400s apply only to custom compositions without the wiring (now a Note). temperature is validated and carried in the submitted turn payload but not applied as a provider sampling parameter. Non-streaming wait timeout is 30 s (DEFAULT_RESPONSES_WAIT_TIMEOUT), not 120. usage on retrieval is read best-effort from persisted run state incl. USD cost (read_run_usage), not always zero. - building-a-tool.md: the [auth.example] oauth2_code recipe gains the required token_response map (deny_unknown_fields rejects the example as previously written); Gmail/Google Calendar corrected to first_party runtimes (their manifests declare kind = "first_party"); the worked api_key recipe is github's, not slack's; the tail "Quick implementation checklist" and reference list were still v2-era (script lane, assets/<extension>/ path, "manifest v2", v2.rs pointer) and now teach the v3 shape; composition/CLI package-naming claim narrowed (the binary does link slack/telegram adapter crates). - contracts/extensions.md: legacy-format paragraph no longer claims host-bundled packages ship v2 (none do), and origin_gate_matrix is attributed to capability.rs + building-a-tool.md instead of extension-runtime/overview.md §3, which does not mention it. - how-to-port banner: `script` manifest authoring is retired; the RuntimeKind::Script symbol survives as the process-sandbox lane's kind. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>