soha-contracts

Shared public contracts for OpenSoha.

This repository is the source of truth for schemas consumed across Soha core, Soha CLI, Soha Agent, Soha Web, official skills, connectors, and Soha Cloud services. Product repositories should depend on generated SDKs, HTTP APIs, JSON Schemas, or released artifacts from this repository instead of copying business logic between repos.

Layout

openapi/soha-api.yaml                 Canonical public Soha HTTP API source
openapi/soha-api.json                 Generated canonical JSON distribution
openapi/spec_generated.go             Embedded Go accessors and version/hash metadata
compat/openapi-0.1.0.snapshot.json    OpenAPI compatibility baseline
examples                              Valid request/response and manifest examples
fixtures                              Valid and invalid contract payloads
capabilities/cluster-capability-matrix.schema.json  Direct/Agent runtime capability matrix
profiles/agent-profile.schema.json    Agent runtime profile manifest
presets/mcp-preset.schema.json        MCP preset manifest
governance/approval-request.schema.json  Approval request and trace contract
governance/audit-log.schema.json      Audit log contract
agent/agent-protocol.schema.json      Runner and agent control-plane protocol
runner/operation-lifecycle.schema.json  Long-running operation lifecycle events
mcp/gateway-manifest.schema.json      AI Gateway / MCP capability manifest
skills/skill-manifest.schema.json     Official skill front matter contract
plugins/plugin-manifest.schema.json   Plugin and marketplace package manifest
events/event-envelope.schema.json     Shared event envelope contract
auth/token-claims.schema.json         Token/JWT claims contract
auth/permission-catalog.json          Canonical resource/action permission catalog
auth/permission-catalog.schema.json   Permission definition and migration metadata
connectors/connector-event-envelope.schema.json  Connector runtime event batch envelope
network/network-runtime-protocol.schema.json  Network control/runtime message contract
network/network-ingest-event.schema.json  Bounded heartbeat, Accounting and flow event batches
gen/go/sohaapi                        Go SDK types for stable cross-repo contracts
gen/ts/sohaapi                        TypeScript SDK types for stable Web contracts

Boundary Rules

• soha remains the open-source core and must run standalone.
• Cloud-only tenant lifecycle, billing, quota, SaaS IAM, and operations contracts do not belong here unless they are explicitly public extension points.
• Open-source Soha may keep tenant-aware fields, but the default distribution uses tenantId = default and workspaceId = default.
• Public behavior changes should update this repository first, then update generated SDKs and consumers.

SDK Consumers

Current SDK entry points:

• Go: github.com/opensoha/soha-contracts/gen/go/sohaapi
• Go OpenAPI artifact: github.com/opensoha/soha-contracts/openapi
• TypeScript: @opensoha/contracts/gen/ts/sohaapi
• npm OpenAPI artifacts: @opensoha/contracts/openapi/soha-api.yaml and @opensoha/contracts/openapi/soha-api.json

The current SDK pass covers auth, AI Gateway capability/tool/result types, runner-facing protocol DTOs, plugin marketplace/install DTOs, public Cloud extension point DTOs, and AI Gateway token management, audit, approval, and governance DTOs used by soha-cli, soha-agent, and soha-web.

SDK DTOs are generated from openapi/soha-api.yaml with openapi-typescript and oapi-codegen:

The public DTO surface also includes Identity applications, providers, policies, OIDC clients, SAML SP/IdP configuration, MFA challenges, runtime capabilities, and versioned Outpost agent messages. Sensitive enrollment and protocol inputs are write-only; response DTOs exclude private keys and raw SAML assertions.

npm run generate
npm run check:generated

npm run check:generated generates SDK and OpenAPI distribution output in a temporary directory and compares it to committed files. It must not rewrite generated files during a freshness check. The Go openapi package exposes copies of both formats plus Version, YAMLSHA256, and JSONSHA256. The Go auth package embeds the canonical permission catalog and exposes its catalog version, definition hash, and artifact hash. Refresh it with npm run generate:permissions; consumers conformance-check their local keys against this artifact instead of maintaining a second catalog.

The Go client in gen/go/sohaapi/client.go intentionally keeps a stable hand-written method surface while DTOs are generated from OpenAPI. For 0.1.x, the supported Go client method surface covers:

• system health and readiness checks;
• public auth discovery, password login, refresh, OIDC code exchange, current principal/profile/bootstrap, logout, and stream tickets;
• delivery, Docker, and agent-run claim/status/callback runner APIs;
• Identity Outpost runtime claim, heartbeat, access-check, and event APIs;
• WebAuthn authentication/step-up and administrator MFA revoke/reset APIs;
• AI Gateway audit, approval, governance, token, service-account, and MCP capability APIs;
• plugin marketplace, install, enable/disable, upgrade, configuration, and manifest APIs.

Other Go consumers should use the generated DTOs directly and keep HTTP calling code in the consumer until those APIs are promoted into the supported client surface. Redirect-oriented flows such as OIDC provider redirects should not use the JSON-only doJSON helper until a non-JSON client mode is added.

The Go generator and generated DTO checks run with Go 1.26.6 in CI.

Validation

Run:

npm test

The validation gate checks generated SDK freshness, JSON schema syntax, valid and invalid JSON Schema fixtures, valid and invalid OpenAPI DTO fixtures, request/response and manifest examples, OpenAPI structure and operation ID uniqueness, version synchronization, OpenAPI lint rules, breaking-change compatibility against the checked-in baseline, TypeScript type declarations, and Go compilation for the generated SDK package.

Useful focused checks:

npm run check:version-sync
npm run validate
npm run lint:openapi
npm run check:openapi-breaking
npm run check:openapi-loose-boundaries
npm run check:json-schema-compat
npm run release:artifacts
npm run release:verify -- dist/release/opensoha-contracts-0.1.0.tgz

When intentionally establishing a new OpenAPI compatibility baseline, update the snapshot with:

npm run check:openapi-breaking:update

Do not update the baseline just to silence an unexpected breaking-change failure.

Consumer Matrix

Network runtime schemas and network-access DTOs require 0.1.17 or later; they are absent from npm 0.1.16 and Go v0.1.15. For unpublished changes, use the local consumer matrix below: it packs this checkout for Web and supplies an isolated Go workspace. After publishing, update consumer versions and lockfiles and verify them without the local override.

The cross-repository consumer gate is:

npm run check:consumers

By default, the script discovers sibling checkouts under the parent directory and skips any missing consumer. CI uses the strict form:

npm run check:consumers -- --consumer soha --require-all
npm run check:consumers -- --consumer soha-web --require-all
npm run check:consumers -- --consumer soha-cli --require-all
npm run check:consumers -- --consumer soha-agent --require-all

Go consumers run in a temporary go.work that replaces the contracts module with this checkout. soha-web runs npm ci, installs a packed copy of this checkout without changing its dependency manifest or lockfile, and builds against that package.

Use --dry-run to inspect the discovered commands without executing consumer builds.

Compatibility Policy

See COMPATIBILITY.md for the versioning, compatibility, fixture, baseline, and consumer adoption rules. In short, 0.1.x changes may add optional contract surface but must not remove existing public operations, rename operation IDs, remove existing response statuses, remove schema properties, add required request properties, or remove enum values.

Release Shape

The stable TypeScript package name is @opensoha/contracts, and the stable Go module path is github.com/opensoha/soha-contracts/gen/go/sohaapi.

Release tags must be v<package.json version>. npm test runs npm run check:version-sync, which verifies package.json, package-lock.json, OpenAPI info.version, the Go module path, the Go client user agent version, and the GitHub release tag when the workflow runs from a tag.

Release artifacts are prepared and verified with:

npm run release:artifacts
npm run release:verify -- dist/release/opensoha-contracts-0.1.0.tgz

The command writes dist/release/<npm-tarball>.tgz, a matching .sha256 checksum file, dist/release/release-manifest.json, a CycloneDX SBOM with its checksum, a provenance policy manifest with its checksum, and, when provided by CI, dist/release/consumer-matrix.json. release:verify checks the tarball checksum, manifest metadata, packed package.json, every exported package entrypoint, both OpenAPI artifact hashes, the SBOM identity and checksum, the provenance policy and checksum, and the consumer matrix summary.

The tag workflow runs npm test, npm pack --dry-run, the strict consumer matrix, requires NPM_TOKEN, publishes npm with provenance, verifies the npm package and Go module tag after publish, and attaches the tarball, checksum, SBOM, SBOM checksum, provenance policy, provenance policy checksum, manifest, and consumer matrix to the GitHub release. It then downloads the published release assets and runs release:verify against the downloaded tarball.

The local release manifest records the provenance policy expected from the tag workflow. It does not prove a remote npm registry attestation by itself; that evidence is produced and checked only after the tag workflow publishes with npm publish --provenance.

During private staging, consumers intentionally use sibling repository checkouts, go.work / replace entries, and file:../soha-contracts package dependencies instead of resolving this repository through anonymous GitHub module fetches or npm. After the repository is publicly readable and the npm package is published, released consumer modules can switch to a real soha-contracts version tag and the published npm package without changing SDK import paths.

License

This repository is licensed under the Apache License 2.0. See LICENSE for the full license text.

Workbench model preferences

WorkbenchSendMessageStreamRequest.modelPreferences selects a public model and an optional auto, low, medium, or high reasoning effort for internal general chat. Preferences persist in session metadata when a message is sent; an empty public model follows the global default. External agents and analysis modes manage their own models. The workbench catalog exposes only permitted public model names.

Gateway routes may declare metadata.reasoningEfforts: ["low", "medium", "high"] (or a supported subset). Only OpenAI-wire routes without protocol conversion expose these levels; every eligible fallback must support a level for it to be offered. Unknown capabilities offer automatic reasoning only. Explicit supported efforts map to reasoning_effort for chat completions and reasoning.effort for Responses.

Shared native Helm task adapter

helmrelease/runtime applies the versioned Helm execution contract through Helm 4. Both core Direct and the standalone Agent supply their own authorized action configuration; queueing, approvals, secret resolution and chart downloads remain outside this package. SDK-only consumers need not import this optional package. Its native revision and recovery checks are tested once for both execution modes.

Agent-local authenticated POST endpoints /api/v1/platform/helm/delivery/prepare, /api/v1/platform/helm/delivery/preflight and /api/v1/platform/helm/delivery/observe accept HelmExecutionTaskPayload and return a data envelope with the prepared payload or HelmExecutionTaskResult, respectively. They enforce the configured cluster identity and are read-only; apply is accepted only by the claimed-task runner. Confidential requests are bounded to 8 MiB, rendered manifests plus hooks to 2 MiB and values to 1 MiB, and are never logged.

Controller-aware Agent execution

Manifest tasks emitted by the controller-aware Core use manifest_agent_v3.<clusterId> and require the Agent summary capability manifest.execution.v3. New Agents also accept legacy manifest_agent.<clusterId> and manifest_agent_v2.<clusterId> tasks using the protected executor. Old Agents cannot claim the new provider kind; capability checks alone are not a substitute for this claim boundary during rolling upgrades.

Native YAML/CR writes and workload restart, scale, rollback and image changes use the existing request/response bodies under /api/v1/platform/ownership-v2, with the original route suffix. This endpoint family guarantees live external-owner checks for Operator, Argo CD, and Argo Rollouts resources and optimistic identity fencing; ownership conflicts return HTTP 409. Core must not fall back to older mutations after 404/405. Reads retain their existing routes.

resource/runtime implements bounded WorkloadCronJob, Argo CD, and Argo Rollouts adapters shared by Direct and Agent. The frozen inventory, operation identity, current generation, resource UID/version, and child-resource evidence determine completion. Blue-green and Traefik canary delivery observe native Service revisions, weights, and complete AnalysisRun metric windows. Promotion only releases manual pauses; analysis failure and cancellation require confirmed stable traffic. Restoring desired configuration uses a new governed operation. Other CRs and traffic plugins are not inferred as supported from a generic Ready condition.