Repository navigation
Document the Core/Web boundary and drop unused public security schemes - #131
Merged
Merged
Conversation
The API index now lists every /api/v1 machine route with its caller and credential, and states that /v1 is exactly the 58 pinned routes. The public API guide keeps only the x_agents_core fields and says how an application reads its Session's model and harness; executor credential issuance stays in the Runtime and credential docs. Remove statements that Web screens for Projects and keys are still pending, that the console forwards only sandbox routes or serves the node and daemon WebSocket, that an unpaired console or remote project connection exists, and that a startup configuration read or Project-scoped execution configuration, Runtime history or observation read remains. Name the Core key instead of deployment or console credentials, point make openapi at its three outputs, compress the removed copy rules to the kept admin_copy provenance, and add the renamed --core-key-file installer flag to the upgrade table.
AGENTS.md now says which /api/v1 credentials come from /core/v1 and which nodes and Core create. The public API guide separates its paragraphs and points self_hosted callers to the operator-issued executor credential. The Docker-hosted guide and the harness selection contract still told operators to set AGENTS_API_MANAGED_RUNTIMES_FILE, which Core rejects. They now describe the database-owned deployment selected through /core/v1/sandbox/deployment, Docker nodes registered with parsar-sandbox-node, and the drained maintenance procedure. The Docker package cannot supply a complete Runtime release by itself, so the guide points to the Core distribution for that.
openapi-split already pruned core.openapi.yaml and runtime.openapi.yaml to the schemes their operations use. It now does the same for openapi.yaml, removing DeploymentAdminAuth, NodeAuth and NodeEnrollmentAuth while keeping the generator's formatting. make openapi regenerated only that removal.
The service README said consumers load the Docker package's image and start Core. The package records only the Runtime image ID, not the complete release a Docker deployment needs, so it now points to the Core distribution and installer. The release also ships parsar-sandbox-node. The hosted guide's acceptance limits called user-managed deployment future work and listed restricted networks, templates and Artifacts as open. They now state the supported network policies, templates and Artifacts, and the qualified self_hosted path with Core-key executor credentials and its limits.
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.
Summary
Docs phase (P5) of the Core/Web boundary. It brings repository documentation outside
apps/webanddocs/webin line with the three namespaces merged in #128. It also drops unused security schemes from the public OpenAPI contract.AGENTS.mdanddocs/api/README.mddescribe the/api/v1credentials accurately: enrollment tokens and executor credentials are issued through/core/v1, nodes register their own credential with an enrollment token, and Core writes daemon credentials into hosted sandboxes.docs/api/README.mdgains a Public API section (exactly the 58 pinned routes) and a table of/api/v1machine routes with caller and credential.docs/api/public-agent-api.mdkeeps onlyx_agents_corefields. It says an application reads the model fromagent.modeland an explicitly selected harness fromagent.x_agents_core.harness, and points self-hosted callers to the Core-key executor credential flow.CONTRIBUTING.md, the getting-started guides,services/agents-api/README.md,HOSTED-SANDBOX-MANAGER.mdand the runtime history/observation contracts:/api/v1;/v1execution-configuration.HOSTED-RELEASE.mdandharness-selection.mdno longer instruct operators to setAGENTS_API_MANAGED_RUNTIMES_FILE, which Core rejects at startup. They describe the database-owned deployment selected through/core/v1/sandbox/deployment, nodes owning Docker, and the maintenance procedure.HOSTED-RELEASE.mdalso states the current self-hosted path and its limits.scripts/openapi-splitnow prunes unused security schemes inopenapi.yamlas it already did forcore.openapi.yamlandruntime.openapi.yaml. The only generated change removesDeploymentAdminAuth,NodeAuthandNodeEnrollmentAuthfromopenapi.yaml.The structure of the install docs is intentionally unchanged. The new-user install work will restructure them. This PR makes only in-place factual fixes there.
Review
This is a docs-only change plus a two-line generator fix, so it got a self-review of the full diff following the repository's risk-based review rule. Factual claims were checked against the generated contracts, the installer, and the Core and console source.
Verification
d9d8d28e(the exact head): passed. It runsmake checkplus typecheck, core-doctor, the Web unit tests and the Web build.make openapishows no drift.go test ./scripts/openapi-split ./contracts/agents-api/...passes.git diff --checkis clean, and a relative-link check over every changed file passes.Need help on this PR? Tag
@codesmithwith what you need. Autofix is disabled.