openclaw-proxy-protocol

Shared semantic turn transport protocol types for openclaw Gateway and openclaw-hub.

This package is the canonical cross-repository protocol surface for:

• agent.turn.*
• tool.invoke.*
• local.execution.envelope
• billing.recorded
• capability sync payloads

For capability sync, pluginManifests is intentionally limited to governance-facing plugin metadata and coarse capability flags. Per-plugin internal topology lists stay inside Gateway runtime state.

It exists so Gateway and Hub can evolve independently without falling back to ad-hoc sibling file: imports or copy-pasted protocol files.

Current topology:

• source lives at openclaw-proxy-protocol
• openclaw consumes it through a local repo dependency during development
• openclaw-hub consumes it as a published semver dependency
• the package is independently versioned from the main openclaw runtime
• the canonical standalone repository target is huizhou-shunshi-intelligent/openclaw-proxy-protocol on Gitee

This is now a first-class engineering artifact. Protocol changes must follow explicit semver and release order.

Repository-readiness status:

• package metadata is self-contained inside this directory
• protocol source now lives under src/ and published artifacts live under committed dist/
• npm packaging can be validated locally with npm run pack:check
• CI and tag release workflows now live in .github/workflows/ and .gitee/workflows/
• release guidance now lives in docs/releasing.md
• changelog and license now live with the package instead of relying on repo-global context
• remaining monorepo coupling is limited to development-time local consumption from openclaw

Repository layout:

• src/index.ts is the source-of-truth protocol definition file
• dist/index.d.ts and dist/index.js are the published package entrypoints
• tsconfig.json exists locally so the package can build independently of the parent repo
• docs/agent-runtime-p0-protocol-draft.md tracks the P0 execution/attempt/sidechain/control protocol draft

Install

Inside the xiaozhiclaw repo, consume it as a local repo package.

{
  "dependencies": {
    "openclaw-proxy-protocol": "file:../openclaw-proxy-protocol"
  }
}

Outside the monorepo, consume the published package instead of a sibling file path.

{
  "dependencies": {
    "openclaw-proxy-protocol": "^2.0.1"
  }
}

Version Flow

Use semver with protocol-specific meaning:

1. major: remove or rename exported fields/types/messages, delete compatibility aliases, or change required-field semantics
2. minor: add backward-compatible messages, payload fields, or optional metadata
3. patch: docs, packaging metadata, or fixes that do not change the public protocol contract

Recent examples of minor additions include explicit approval step context fields and the compatibility-safe local.execution.envelope projection surface.

1.0.0 starts the explicit breaking-change wave that removes the legacy Gateway-side relay-api-proxy* source/export surface and makes semantic-turn-transport* the only canonical Gateway naming.

Release Order

Protocol releases are ordered and must not be collapsed:

1. update openclaw-proxy-protocol
2. publish the protocol package
3. upgrade openclaw-hub to the published semver and refresh its lockfile
4. deploy Hub first
5. upgrade Gateway/openclaw mainline and plugin-sdk surfaces
6. remove compatibility shims only after Hub and Gateway mainlines have both migrated

Why Hub before Gateway:

• Hub is the cloud-side protocol and orchestration truth
• Gateway is the desktop transport consumer
• rolling Hub first keeps Gateway fallback compatibility windows explicit

Release

This package is released independently from the main openclaw runtime version.

1. Update protocol types in this package first.
2. Run npm run build when you change src/index.ts.
3. Publish the package with the local release script in scripts/release-proxy-protocol.mjs.
4. Upgrade openclaw-hub to the new semver version.
5. Refresh the hub lockfile after the published version is available.
6. Deploy Hub before removing Gateway compatibility shims.

Example:

node scripts/release-proxy-protocol.mjs --version 1.0.0

Consumer Migration

Gateway / openclaw migration order:

1. add new neutral or semantic exports first
2. migrate source imports to the new canonical names and paths
3. rebuild plugin-sdk declarations and verify old package-local paths and old type aliases are gone from generated d.ts output
4. only then delete compatibility aliases and deprecated files

Hub migration order:

1. bump openclaw-proxy-protocol semver in openclaw-hub/package.json
2. refresh the lockfile against the published version
3. update Hub source imports/usages to the new canonical fields/types
4. build and deploy Hub before asking Gateway to drop old compatibility readers

If the package is later split out of the monorepo into a dedicated repository, keep the same release order and semver policy; only the source location changes.

Independent Repo Checklist

The package is now extraction-ready at the directory level. To complete the final split into a dedicated repository, keep the package contents unchanged and only perform repository-boundary work:

1. keep src/ as the only source-of-truth and publish dist/
2. keep repository, homepage, and bugs in package.json pointing at the standalone repository
3. use scripts/release-proxy-protocol.mjs as the package-local release entrypoint
4. keep the publish order protocol -> Hub -> Gateway
5. do not reintroduce sibling file: dependencies for Hub or any other external consumer
6. keep this directory aligned with its standalone Gitee repository workflow and evolve CI/release there as the canonical path

Consumer rule

openclaw-hub must not depend on this package through a sibling file: path. Cross-repo consumers should always use the published versioned package so release order, rollback and CI are all explicit.

Starting from the real 1.0.0 release, ProxyUsageInfo and ProxyBilledInfo are no longer part of the public contract. Consumers should use TransportUsageInfo and TransportBillingInfo directly.