ObneyAI/orc / orc-skills/orc-model-sio
orc-model-sio
VerifiedConfigure ORC models and structured I/O, inspect SIO or native decision-client requests, and diagnose provider or parsing failures. Use when model choice or what was sent to a model matters.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 20.2 KB |
| references/complex-model-portability.md | markdown | 8.8 KB |
| references/configured-model-fallback.md | markdown | 8.9 KB |
| references/contract-preflight.md | markdown | 2.9 KB |
| references/input-field-guide.md | markdown | 4.4 KB |
| references/live-findings.md | markdown | 11.6 KB |
| references/model-portability.md | markdown | 30.9 KB |
| references/paired-function-profiles.md | markdown | 5.1 KB |
| references/portability-proof-boundaries.md | markdown | 6.1 KB |
| references/reasoning-and-completion-budgets.md | markdown | 11.7 KB |
| references/retained-fallback-profiles.md | markdown | 9.8 KB |
| references/scoped-model-alternatives.md | markdown | 11.2 KB |
| references/structured-contract-repairs.md | markdown | 22.3 KB |
| references/structured-output-boundaries.md | markdown | 6.9 KB |
references/reasoning-and-completion-budgets.md
View on GitHub# Reasoning, output rationale and completion budgets
Read [the verified repair path](structured-contract-repairs.md) before applying historical parser/metadata limitations below. It covers generated model-visible output meanings, paired strict parsing, null preservation and execution-owned provider observations. The linked reference identifies the integrated source snapshot and exact dependencies. The historical retention findings below apply to their named older pins; do not treat them as current limitations on a later checkout.
## Three different things
| Item | Meaning | Where to inspect |
| --- | --- | --- |
| Declared rationale output | A task-facing explanation requested by a described blackboard key such as `route-reasoning`. | SIO output schema, parsed node writes and durable value projection. |
| Provider reasoning | Reasoning text, summary or opaque continuation data exposed by a particular model/provider. It may be unavailable. | Raw provider `message.reasoning` / `message.reasoning_details`, when returned. |
| Reasoning token usage | Tokens spent reasoning; their count can be reported even when no readable reasoning is returned. | Raw `usage.completion_tokens_details.reasoning_tokens`, when supplied. |
A blackboard key named `reasoning` does not enable, capture or rename the provider channel. A finite conversational `llm-decision` with only a `verdict` write can still consume reasoning tokens and return provider reasoning. A native decision protocol has its own evidence contract; do not add a free-text write to it to obtain reasoning. Neither channel proves access to all internal model processing. Preserve a summary as a summary and opaque/encrypted blocks as opaque data.
## Budget for reasoning and the answer
On most OpenRouter reasoning endpoints, the completion cap includes reasoning and visible output. `reasoning.exclude: true` hides returned reasoning; it does not disable computation, remove its cost, or reserve more space for the answer. A `length` finish can leave empty or partial JSON despite a valid strict schema. Inspect finish reason and reported token breakdown before changing keys or descriptions. [OpenRouter reasoning controls](https://openrouter.ai/docs/guides/best-practices/reasoning-tokens).
Use an explicit completion cap appropriate to the task and endpoint, with headroom for both reasoning and the complete structured answer. A small `1024` or `4096` example is not a universal default for reasoning models. Increase the provider timeout and enclosing execution deadline deliberately when a larger budget can require more time. A token cap is a maximum, not a request to spend it all. Preserve physical-attempt and cost bounds across retries.
At the inspected ORC/client pins, node `:options {:max-tokens 32768}` reaches the OpenRouter completion limit; this is an example of an enlarged experimental cap, not a universal recommendation. Do not confuse it with a reasoning-only budget. `:reasoning-effort` is transformed into OpenRouter's reasoning effort. The client also has a `:thinking` control with its own supported shape and precedence. Check the exact client source and endpoint capabilities before combining controls. A provider-specific `:extra-body {:reasoning {:exclude true}}` can request exclusion when no conflicting normalized reasoning control is present; verify the serialized request. The pinned adapter rejects a raw reasoning override when a normalized reasoning control is already configured.
If an answer is incomplete, do not accept a parseable prefix, synthesize required fields, or turn missing output into a semantic verdict. Preserve typed failure and usage, then let the authored recovery policy decide whether a larger-budget or alternate compatible method is eligible. Failed attempts still count.
A fresh-authored file-reconciliation probe illustrates the boundary: its first draft completed with 3,253 total completion tokens, including 2,626 reported reasoning tokens. The later revision hit the same 3,500-token cap with 3,296 reasoning tokens and returned `finish_reason: length` plus incomplete structured content. The host correctly rejected that response and preserved the changed file. An explicitly restarted application continuation with a 32,768-token allowance subsequently completed the revised artifact and save; this does not establish automatic recovery of the failed tick. A short visible artifact or one successful earlier call does not establish sufficient headroom for a later correction. Preserve the failed attempt when testing a larger allowance; do not repair it by filling missing fields.
Inspect raw content when a structured response reaches the cap. Two MiniMax specialist findings reached 32,768 completion tokens with zero reported reasoning tokens. The incomplete JSON ended in long whitespace runs. Both same-budget retries returned complete JSON. A larger ceiling may help a substantive answer that needs more room. For repeated whitespace, compare one bounded replay of the exact request, preserve the route and finish reason, and check whether a successful result actually used more than the original allowance. Captured attempt measurements (historical local experiment; private archive not bundled) The exact request was subsequently replayed once at 65,536. It completed with 6,297 tokens, zero reported reasoning tokens, valid strict output and three exact canonical fields. The request differed only at `max_tokens`, but the served route changed from Parasail to Nebius. It used less than the old cap, so the result does not establish that more headroom fixed the earlier whitespace behavior. Independent replay audit (historical local experiment; private archive not bundled)
## Align the enclosing timeouts
Provider timeout, researcher iteration/campaign limits, each enclosing delegate, the root deadline and caller/body drain are separate clocks. Increasing the root allowance does not lengthen a delegate's local timeout. On the inspected campaign snapshot, an undeclared delegate timeout is 300000 ms: a run with 65536 completion tokens and a 4200000 ms root still timed out at that delegate after 300033 ms with its inline call unfinished. Use the public delegate `:timeout-ms` option for work that needs more time; the inspected runtime clamps it to the parent's remaining absolute deadline. Verify registered node configuration and actual start/completion events, rather than assuming the root controls every clock.
A separate headroom run explicitly configured all four delegates, retained the same prompts, typed inputs/outputs and decoder, and completed six calls with exact source and raw-to-final fidelity. This proves the configured interface in that run, not a controlled latency improvement: adaptive code, provider timing and cache state varied. Preserve the earlier timeout. A terminal result alone does not establish that every provider body finished; retain actual joins and unknown cost reservations when a call has no captured response. The evidence is private campaign work on the source-pinned stack identified in the portability reference; recheck the consuming DSL and pins before treating any default as current.
## Historical retention boundary at the older inspected pins
At ORC `9f7c27357b9f9bcf765fbd86baaedf5911261cd8` and litellm-clj `0570e9459b8751d4a0c3dc1cd48595804426a84d`, the OpenRouter response adapter reconstructs messages without `reasoning` or `reasoning_details`. Its usage transformation retains aggregate token counts but drops the reasoning breakdown and raw reported cost. ORC's own usage normalization also retains only a small aggregate allowlist. Later dependencies may differ: inspect their exact transformation and persisted schema.
At that older snapshot, an ordinary ORC node's rationale and `:raw-response` are not complete provider reasoning evidence. `:raw-response` refers to final content in this path. Capture the header-free raw response before adapter normalization when investigating what the provider actually returned; correlate it to the physical attempt. Retain usage counts and full text separately, with the application's access and retention rules. Excluded or unavailable reasoning cannot be reconstructed afterward.
For a library repair, preserve provider reasoning metadata separately from declared blackboard writes, retain reported reasoning usage without inventing missing counts, and verify the durable event/query path as well as direct prediction metadata. Exact provider blocks used for native conversation continuation must remain structurally intact; do not inject them into every specialist's context by default. Specialists should continue receiving their explicit task inputs and relevant qualified outcomes.
See [structured-output boundaries](structured-output-boundaries.md) and [ORC observability](../../orc-observe-debug/SKILL.md) for request, parsing and projection checks.
## Pass explanations between specialists deliberately
An ordinary rationale already uses normal ORC composition. The producer writes a described `prepare-rationale` and its actual `proposal`; the reviewer explicitly reads those keys together with the original goal and qualified facts, then writes its own rationale and verdict. A delegate forwards only the needed declared values. The original rationale remains distinct from the reviewer's conclusion and is not overwritten by a shared generic key.
Describe the rationale as the producer's explanation of its assumptions and choices. A reviewer can use it to locate questionable assumptions, understand alternatives or request targeted rework. It must still inspect the actual artifact and authoritative evidence. Rationale is not proof of tool execution, permission, factual correctness or completion.
Provider reasoning requires a different collection path. At the older `9f7c2735` snapshot there is no ordinary LLM-node option that writes native provider reasoning into the blackboard, and `:with-metadata?` does not expose it. Adding a metadata key to the model's ordinary `:writes` would ask the model to generate that field; it would not collect a native response channel.
That older investigation proposed preserving provider observations with execution provenance and selecting a typed packet for a downstream specialist. The later [structured-contract repair](structured-contract-repairs.md#provider-observations) implements the blocking conversational path: metadata includes `:provider-observations`, and ordinary execution exposes owned attempts through `provider-attempts`. Use the linked exact signatures and source requirements rather than recreating the collector in each application. Other roles, streaming and pre-response failures have their own limits; none are inferred from this ordinary-path proof.
Keep raw observations separate from the selected specialist packet. Include source execution/response identity, text-versus-summary status, generation finish/validation outcome and reported usage where relevant. Represent unavailable or opaque-only reasoning explicitly. Preserve opaque blocks in the underlying record if needed; do not feed encrypted bytes to a semantic checker as readable thinking. Selecting this packet is protocol/data handling; deciding what the explanation means is semantic work. Provider reasoning tokens are already part of reported completion tokens on the observed path—do not add them twice when aggregating cost or usage.
## Admission checks must respect remaining time
A node may declare300s while its effective request timeout is shorter because an ancestor's absolute deadline is nearer. Capture/admission should verify a positive timeout no greater than the reviewed ceiling, rather than require equality with that ceiling. A later held-out harness incorrectly refused299723–299730ms before any HTTP call; its local guard correction preserved the ceiling and did not increase model allowance. Keep this setup failure separate from model/provider failure.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |