docs: consolidate API semantics and resource contracts - #280
Merged
Merged
Conversation
Merge the installation, execution configuration and write provenance contracts into admin-api.md, add the per-request key lookup and its 503, complete the route table, and trim core-errors.md and core-metrics.md to current reference (execution slots follow core.execution_concurrency).
Add wire-semantics.md (Core behavior where the pinned contract is silent or differs), sessions-events.md, message-content.md and vaults.md, built from the current rules of the alignment, list-query, history, message, function image and credential notes, which are deleted with their dated evidence. Rewrite source-files.md and environment-files.md to current rules, fixing the Go os.Root writer and reader, image support on self_hosted and Claude bridge protocol 3. Code-level rules go to IMPLEMENTATION.md; inbound links move to the new owners.
Keep the pin, per-resource status with owning contracts, one list of differences from OpenAI and the known gaps. Drop milestone evidence, PR histories and the rules now owned by the subject contracts.
docs/api/README.md becomes the namespace and credential page, with the device credential and x_agents_core.environment. The Agents API guide absorbs the user guide's harness choice, task tables and failure diagnosis, fixes the none placement's model rules and links provider precedence and the difference list. The console and administration content of web-management.md already lives in console-server.md and admin-api.md.
… guide A new openai_hosted Session reads idle while its sandbox is prepared, failed also covers failed Turns and input, initial input is required on none and for streamed creation, and Session usage stays null while a Turn runs. Failure diagnosis points at Session diagnostics.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
API behavior was split between user guides, evidence logs and overlapping resource notes. Give wire semantics, Vaults, message content, Sessions/events and source Files one owner each; keep the public guide task-oriented and the coverage ledger explicit about remaining gaps. Delete superseded documents and repoint callers without changing README layout.
Independent review completed and significant accuracy/lost-fact findings were corrected, including reservation outcomes, input wait behavior, credential deletion effects and missing event coverage. Execution capability and native-test details link to the consolidated Harness contracts.
Validation passed: name guard, distribution/installer checks, repository Markdown links, API Diagnostic tests and v1 contract tests. After integrating the scripts cleanup, name guard and distribution-manifest tests were rerun. Lower-priority wording suggestions are deferred; Runtime/service-document ownership cleanup follows in the Runtime documentation PR.
Need help on this PR? Tag
@codesmith-botwith what you need. Autofix is disabled.