Skip to content

api-schema-contract.md

Latest commit

 

History

History
122 lines (90 loc) · 20.4 KB

api-schema-contract.md

File metadata and controls

122 lines (90 loc) · 20.4 KB
Raw

API And CLI Schema Contract

Status: P8-3 API / CLI Schema Freeze & Release Evidence Policy Last updated: 2026-06-29

This document is the public contract index for the pre-alpha daemon-ready runtime surface. It freezes the package-root API boundary, CLI JSON schema inventory, schema versioning policy, redaction requirements, and failure taxonomy used by embedders and release gates.

It does not add a daemon, HTTP/RPC API, database, WAL, remote worker, UI, telemetry, npm publication, npm token, trusted publishing setup, or authenticated real-agent gate.

Public Root Boundary

The package root value export is intentionally limited to:

  • createAgentRuntime

The package root TypeScript type exports are the supported source-compatible import boundary for pre-alpha consumers:

  • runtime facade and options: AgentRuntime, RuntimeOptions, DetectOptions, DetectedAgent, RuntimeEnvironment
  • run API and records: RunRequest, RunHandle, RunRecord, RunStatus, RunResult, RuntimeContextBlock, RuntimeSessionRef
  • goal API and records: CreateGoalRequest, GoalHandle, GoalRecord, GoalStatus, PlannerOutput, PlannerTask, ScheduledTask, TaskEvidence, TaskAttemptEvidence, TaskRetryPolicy, TaskStatus, ValidationCommandResult
  • event and replay contracts: AgentEvent, SchedulerEvent, ReplayEvent, VersionedEventEnvelope, EventScope, EventTerminalContract, EventTerminalReason, RuntimeUsage
  • diagnostics and store inspection: RuntimeDiagnostic, RuntimeErrorCode, DiagnosticsBundle, ExportDiagnosticsRequest, InspectStoreOptions, StoreHealth, StoreHealthSummary, StoreHealthIssue, StoreHealthWarning, StoreActiveRecord, StorageLockInspection, RuntimeOwner, OwnerStatus, StoreRepairReport, StoreRepairAction
  • adapter authoring types: AgentAdapterDef, AgentCapabilities, AdapterCompatibilityProfile, AgentId, BuildArgsInput, PermissionPolicy, PromptTransport, RuntimeModelOption, StreamParser

Internal but packaged files under dist/** may exist in the npm tarball because TypeScript declarations and the CLI need them. Their presence is not a subpath-import promise. Built-in adapter values, parser helpers, executable-resolution helpers, stores, schedulers, task-graph helpers, and storage implementation modules remain internal implementation details.

getAdapter(id) and RuntimeOptions.adapters remain pre-alpha adapter-extension points. Their root type imports are documented for adapter experimentation, but internal built-in adapters are not root value exports.

Schema Versioning Policy

  • Adding optional fields is allowed within the same schema version.
  • Removing a field, renaming a field, changing a field type, or changing field semantics requires a schema version bump.
  • Changing redaction guarantees requires a schema version bump and migration note.
  • Changing terminal reason or classification vocabulary requires docs, tests, and a migration note.
  • Removing a CLI command, removing a flag, or changing flag semantics requires a pre-alpha breaking-change note.
  • CLI and daemon callers should branch on schemaVersion and ignore unknown optional fields.

CLI JSON Schema Inventory

Schema Required top-level fields Classification fields Redaction rules
agent-runtime.event.v1 schemaVersion, id, sequence, timestamp, scope, event terminal.result, terminal.reason Runtime redaction before CLI emission; no prompts, tokens, Bearer values, auth env values, or private cwd paths.
agent-runtime.diagnostics.v1 schemaVersion, exportedAt, subject, manifest, events, diagnostics, storageDiagnostics, consistencyWarnings, supervisorSummary, adapterSummary supervisorSummary.terminalReason, diagnostics[].code No raw event payload dump, raw corrupt JSONL line, prompt, token, Bearer value, auth env value, or private path.
agent-runtime.conformance.v1 schemaVersion, ok, mode, agents agents[].runClassification, agents[].skippedReason, agents[].failureReason observedTextTail and diagnostics are bounded and redacted; no prompt, token, raw stdout/stderr, or private cwd.
agent-runtime.daemonVerification.v1 schemaVersion, ok, packageName, version, packageSource, checks, diagnostics ok, checks.*, diagnostics[].code Installed-tarball gate summary only; fake CLIs only; no temp paths, prompt, token, Bearer value, auth env value, or private cwd.
agent-runtime.runtimeSafety.v1 schemaVersion, ok, packageName, version, packageSource, checks, diagnostics ok, checks.*, diagnostics[].code Installed-tarball gate summary only; fake CLIs only; bounded diagnostics only; no prompt, token, Bearer value, auth env value, or private cwd.
agent-runtime.publishedDaemonConsumer.v1 schemaVersion, ok, packageName, version, packageSource, checks, diagnostics, noAuthenticatedRealRun ok, checks.*, diagnostics[].code Published-package gate summary only; fake CLIs only; no temp paths, prompt, token, Bearer value, auth env value, or private cwd.
agent-runtime.publishedAdapters.v1 schemaVersion, ok, packageName, version, packageSource, checks, agents, diagnostics, noAuthenticatedRealRun ok, checks.failureIsolation, agents[].terminalStatus No temp paths, raw stdout/stderr, full prompt, token, Bearer value, auth env value, or private cwd.
agent-cli-runtime.publishedSmoke.v1 schemaVersion, ok, packageName, version, packageSource, checks, diagnostics ok, checks.*, diagnostics[].code Published-package smoke summary only; no raw stdout/stderr, temp paths, prompt, token, Bearer value, auth env value, or private cwd.
agent-cli-runtime.publishedVerification.v1 schemaVersion, ok, packageName, version, gitSha, checkedAt, packageSource, gates, registry, diagnostics, noAuthenticatedRealRun, noNpmPublish, noNpmToken ok, gates[].ok, gates[].schemaVersion, registry.ok, diagnostics[].code No raw stdout/stderr, temp paths, full prompt, npm token references, token, Bearer value, auth env value, or private cwd.
agent-cli-runtime.packagedDocsVerification.v1 schemaVersion, ok, packageSource, version, inspectedDocs, diagnostics ok, inspectedDocs[].ok, diagnostics[].code Packaged-docs summary only; no raw package extraction paths, raw stdout/stderr, prompt, token, Bearer value, auth env value, or private cwd.
agent-cli-runtime.postAlphaEvidence.v1 schemaVersion, ok, packageName, version, registry, githubRelease, diagnostics ok, registry.ok, githubRelease.ok, diagnostics[].code Post-alpha verification summary only; no raw stdout/stderr, temp paths, prompt, token, Bearer value, auth env value, or private cwd.
agent-cli-runtime.realCompatibilityMatrix.v1 schemaVersion, checkedAt, packageVersion, gitSha, gitDirty, gitInputDirty, gitOutputDirty, dirtySummary, commands, adapters, needsVerificationAudit, packageBoundary adapters[].safePreflight.runClassification, adapters[].optionalSmoke.runClassification, needsVerificationAudit[].items Repo-only evidence summary; no raw stdout/stderr, resolved executable paths, prompt, token, Bearer value, auth env value, private cwd, or local temp paths.
agent-cli-runtime.realCompatibilityEvidenceVerification.v1 schemaVersion, ok, evidenceSchemaVersion, file, checkedAt, targetSha, freshness, dirtyPolicy, diagnosticSummary, diagnostics ok, targetSha.status, freshness.status, dirtyPolicy.status, diagnosticSummary.codes, diagnostics[].code Diagnostics are redacted; no private paths, token-looking values, Bearer values, auth env assignments, raw stdout/stderr, full prompt text, or raw observed real CLI output.
agent-runtime.realSmoke.v1 schemaVersion, type, ok, mode, adapter, version, auth, modelsSource, runClassification, expectedTextRequired, expectedTextMatched, observedTextDeltaCount, observedTextTail, cwdMutationChecked, cwdMutated, diagnosticsCount, diagnostics, skippedReason, failureReason runClassification, skippedReason, failureReason No final run record, prompt, token, raw stdout/stderr, or private cwd; observedTextTail is bounded and redacted.
agent-runtime.storeHealth.v1 schemaVersion, ok, checkedAt, lock, totals, corruptManifests, corruptEventLogs, partialTails, activeRecords, activeInterrupted, warnings, storageDiagnostics, diagnostics ok, lock.status, diagnostics.byCode No raw corrupt JSONL line, token, Bearer value, auth env value, or private path.
agent-runtime.storeRepair.v1 schemaVersion, storageDir, checkedAt, dryRun, applied, ok, actions, diagnostics ok, blockedReason, actions[].action, diagnostics.byCode Backup paths and diagnostics are redacted; no raw corrupt JSONL line, token, Bearer value, auth env value, or private path.
agent-runtime.cliError.v1 schemaVersion, ok, error error.code error.message is short and redacted; no prompt, token, Bearer value, auth env value, or private path.
agent-cli-runtime.releaseVerification.v1 schemaVersion, ok, checkedFiles, tarball, diagnostics, artifactNames, gateEvidence, packageName, version ok, diagnostics[].code Diagnostics are redacted; no private package paths, token-looking values, Bearer values, auth env assignments, npm token references, repo-only real compatibility evidence scripts, repo-only package content scripts, or disallowed package paths.
agent-cli-runtime.releaseGateEvidence.v1 schemaVersion, generatedAt, gates, noAuthenticatedRealRun, noNpmPublish, noNpmToken gates[].ok, gates[].outputSchemaVersion, gates[].packageSource, gates[].evidenceSchemaVersion, gates[].targetSha.status, gates[].freshness.status, gates[].dirtyPolicy.status, gates[].diagnostics.codes, gates[].repoOnlyEvidence.status No authenticated real run output, npm token references, raw paths, prompts, secrets, raw evidence files, raw stdout/stderr, or diagnostic messages.
agent-cli-runtime.releaseArtifactNormalization.v1 schemaVersion, ok, downloadDir, outDir, artifacts, diagnostics ok, diagnostics[].code, artifacts[].artifactName No absolute local paths; repo-external input/output directories are represented as <external_artifact_dir> / <external_output_dir>, and only expected release-candidate artifact filenames are copied.
agent-cli-runtime.mainReleaseCandidateEvidence.v1 schemaVersion, stage, evidenceKind, checkedAt, releaseTargetSha, targetRef, mainEvidence, branchEvidence, historicalMainEvidence, compatibilityVerification, localReleaseCandidate, remoteReleaseCandidate, downloadedArtifacts, boundary mainEvidence, branchEvidence, historicalMainEvidence[].historical, historicalMainEvidence[].currentMainFreshEvidence, compatibilityVerification.ok, remoteReleaseCandidate.run.status, remoteReleaseCandidate.run.conclusion, remoteReleaseCandidate.artifacts.valid, downloadedArtifacts.verified Repo-only current main summary; historical P8 summaries are listed as historical and non-current; no raw stdout/stderr, workflow logs, prompts, private paths, token-looking values, Bearer values, auth env assignments, tarball shasums, or pack shasums.
agent-cli-runtime.packageContentEquivalence.v1 schemaVersion, ok, baseRef, headRef, packageName, packageVersion, packageContentEqual, basePackageDigest, headPackageDigest, baseFileCount, headFileCount, changedPackageFiles, evidenceOnlyDrift, freshReleaseCandidateRequired, diagnostics ok, packageContentEqual, evidenceOnlyDrift, freshReleaseCandidateRequired, diagnostics[].code, changedPackageFiles[].status Diagnostics and ref labels are redacted; no temp worktree path, private path, token-looking value, Bearer value, auth env assignment, raw stdout/stderr, workflow log, prompt, tarball shasum, or pack shasum.
agent-cli-runtime.stableSurfaceCheck.v1 schemaVersion, ok, packageRoot, publicTypes, schemaInventory, cliVocabularies, packagedDocs, diagnostics, boundary ok, packageRoot.ok, publicTypes.ok, schemaInventory.ok, cliVocabularies.ok, packagedDocs.ok, diagnostics[].code, boundary.repoOnlyGate, boundary.stableSurfaceCheckIsRuntimePublicApi Repo-only stable surface gate summary; no raw stdout/stderr, workflow log, prompt, private path, token-looking value, Bearer value, or auth env assignment.

Failure Taxonomy

Event terminal reasons use the EventTerminalReason vocabulary:

  • success
  • failed
  • timeout
  • canceled
  • interrupted
  • validation_failed
  • execution_failed
  • unavailable
  • auth_missing
  • task_graph_invalid

Smoke and conformance classifications use:

  • success
  • real_run_skipped
  • auth_missing
  • unavailable_executable
  • unsupported_flag
  • needs_verification
  • unexpected_output
  • cwd_mutated
  • timeout
  • failed

Classification rules:

  • skipped is not success.
  • auth_missing is not unavailable.
  • needs_verification must not be guessed into a flag mapping or success state.
  • unsupported_flag, unexpected_output, and cwd_mutated are smoke/conformance classifications, not normal run terminal reasons.
  • The historical run result spelling cancelled maps to daemon-facing terminal reason canceled.

Release Gate Rules

Default gates may run real local detection/profile certification, but they must not launch authenticated real agent runs. --allow-real-run is the explicit local account/network boundary and remains outside CI, dogfood, prepublish, and release-candidate gates.

Release verification and gate evidence schemas must stay aligned with scripts/verify-release-artifacts.mjs and scripts/create-release-candidate.mjs. gate-evidence.json records the installed-tarball daemon-ready gates and the offline repo-only real compatibility evidence verification gate, while release-verification.json validates artifacts, package file parity, private-path/secret scans, repo-only evidence boundaries, and release gate evidence.

Published package verification uses agent-cli-runtime.publishedVerification.v1 and stays repo-only. It aggregates smoke:published, published:daemon:verify, published:adapters:verify, release:post-alpha:verify, and npm registry metadata without storing raw stdout/stderr or adding any publish credential path.

Repo-only real compatibility matrix evidence uses agent-cli-runtime.realCompatibilityMatrix.v1 and is generated by npm run compat:real:evidence under .release-evidence/p8-2-real-cli-compatibility-matrix.json. It is not a package runtime CLI schema, but it follows the same redaction boundary: no raw stdout/stderr, no full prompt text, no private absolute paths, no token values, no Bearer values, no auth environment assignment values, no local temp paths, and no resolved executable paths. The matrix records checkedAt, packageVersion, gitSha, gitDirty, gitInputDirty, gitOutputDirty, dirtySummary, commands, adapters, needsVerificationAudit, packageBoundary, and no-secret/no-raw-output flags. The default command runs only safe real preflight; authenticated real smoke requires explicit --allow-real-run --agent <id> --expect-text <text> pairs.

Real compatibility verification uses agent-cli-runtime.realCompatibilityEvidenceVerification.v1 and is run with npm run compat:real:evidence:verify. It is an offline repo-only evidence gate: it reads the existing evidence file, does not start authenticated real CLI runs, and fails with stable diagnostic codes such as invalid_schema, unsafe_content, missing_dirty_state, target_sha_invalid, target_sha_mismatch, checked_at_invalid, evidence_too_old, dirty_evidence_not_allowed, skip_state_claimed_as_success, authenticated_success_incomplete, needs_verification_missing, and package_boundary_invalid. Release review passes --target-sha <sha> --max-age-hours <n> --release-strict; the verifier output records targetSha, freshness, dirtyPolicy, diagnosticSummary, and redacted diagnostics. --allow-dirty is the explicit policy for dirty input evidence, while matrix-output-only dirty state is reported as dirtyPolicy.status: "self_dirty_only".

Release gates do not refresh real CLI evidence. npm run prepublish:check runs the default offline verifier after installed-package daemon/runtime safety gates and before dogfood. Local npm run release:candidate defaults to --real-compatibility-mode local-strict, uses the checked-in P8 matrix gitSha as the release target unless --target-sha <sha> is explicitly supplied, and records a real-compatibility-evidence gate with script: "compat:real:evidence:verify", command: "npm run compat:real:evidence:verify -- --target-sha <target_sha> --max-age-hours 24 --release-strict", outputSchemaVersion: "agent-cli-runtime.realCompatibilityEvidenceVerification.v1", evidenceSchemaVersion: "agent-cli-runtime.realCompatibilityMatrix.v1", targetSha, freshness, dirtyPolicy, ok, and diagnostics summarized as { count, codes }. Remote clean-checkout release-candidate workflows pass --real-compatibility-mode repo-only-skipped and record command: "repo-only real compatibility evidence not refreshed in CI", targetSha.status: "repo_only_not_run", freshness.status: "repo_only_not_run", dirtyPolicy.status: "repo_only_not_run", dirtyPolicy.policy: "repo-only-skipped", empty diagnostics, and repoOnlyEvidence.status: "not_refreshed_in_ci". Release gate artifacts must not embed .release-evidence/p8-2-real-cli-compatibility-matrix.json, raw verifier output, raw stdout/stderr, diagnostic messages, full prompts, private paths, tokens, Bearer values, or auth environment values.

Downloaded release-candidate artifacts are normalized with npm run release:artifacts:normalize -- --download-dir <gh-download-dir> --out-dir <normalized-artifact-dir> before release:verify. The normalizer copies only npm-pack.json, package-files.txt, gate-evidence.json, release-verification.json, and agent-cli-runtime-*.tgz from their expected gh run download artifact directories; missing, duplicate, unknown, or misplaced files produce stable agent-cli-runtime.releaseArtifactNormalization.v1 JSON diagnostics. It does not inspect package contents and does not replace agent-cli-runtime.releaseVerification.v1.

Main release-candidate evidence uses agent-cli-runtime.mainReleaseCandidateEvidence.v1 and is generated with npm run release:main-candidate:evidence -- --stage <stage> --release-target-sha <origin-main-sha> --local-release-dir <local-strict-dir> --remote-run-json <run.json> --artifacts-json <artifacts.json> --downloaded-dir <normalized-artifact-dir> --out .release-evidence/<stage-lower>-main-release-candidate.json. The stage label accepts current phase labels such as P9-2 and is not tied to P8. The summary binds releaseTargetSha to origin/main, records local strict compatibility and release verification, records a fresh release-candidate.yml --ref main run with matching headSha, and lists P8 main release-candidate files only under historicalMainEvidence with historical: true and currentMainFreshEvidence: false.

Package content equivalence uses agent-cli-runtime.packageContentEquivalence.v1 and is run with npm run release:package-content:verify -- --base-ref <release-target-sha> --head-ref <sha-or-ref>. It compares npm package-visible files from temporary git worktrees by package-relative file list, mode, size, and file-content hashes. It does not treat gzip/tarball bytes as the only equivalence signal. Package-external evidence, tests, and repo-only scripts can produce evidenceOnlyDrift: true with freshReleaseCandidateRequired: false; package-visible README/docs/package.json/dist/types/bin/examples changes produce package content drift and require fresh release-candidate evidence before the head ref is treated as a release target.

Stable surface regression checking uses agent-cli-runtime.stableSurfaceCheck.v1 and is run with npm run stable:surface:check after npm run build. It verifies the package-root runtime value export, root declaration boundary, schema inventory documentation, terminal/classification vocabularies, experimental adapter-surface classification, and npm package exclusions for repo-only paths and scripts. This is a beta-candidate repository/release gate, not a runtime public API schema for package consumers.