@cosplay-ai/protocol

Shared TypeScript types and Zod runtime validators for the Cosplay wire protocol. This package is the single source of truth for the contract between the OSS relay (cosplay/relay/) and the proprietary cloud Lambda handlers (cosplay-cloud/lambda/).

Both consumers depend on this package and must agree on its SemVer: PATCH for additive-optional changes, MINOR for new endpoints or message kinds, MAJOR for breaking changes (accompanied by a schema-version integer bump and the 426 Upgrade Required gate).

For the full design rationale and per-phase task list, see .cosplay/artifacts/cto/tasks-cosplay-protocol.md.

Installation (consumer side)

Cloud-side Lambda code (cosplay-cloud/) and any self-hosted-cloud implementation install the package from GitHub Packages:

npm install @cosplay-ai/protocol

This requires a .npmrc file pointing at the GitHub Packages registry:

@cosplay:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

• CI workflows in cosplay-cloud authenticate using GitHub Actions' built-in GITHUB_TOKEN — no extra secrets needed.
• Developer workstations create a classic personal access token at https://github.com/settings/tokens with the read:packages scope, then set GITHUB_TOKEN in the shell environment (or .env).

Publishing (maintainer side)

The CI workflow .github/workflows/publish-protocol.yml publishes automatically on a protocol-v* tag push (e.g. protocol-v0.1.0). Before cutting the first tag, complete the following operator-action checklist:

1. Register the @cosplay org scope on npmjs.org (free, ~5 minutes): https://www.npmjs.com/org/create — verify @cosplay is available.

   • If @cosplay is taken: rename the package to @aaronk9-web/cosplay-protocol (your reserved scope) and update all references in packages/protocol/package.json and the workflow file.

2. Enable GitHub Packages write permissions for this repo: Settings → Actions → General → Workflow permissions → check "Read and write packages".

3. Dry-run the publish locally from a clean build:

   npm run build:protocol
   npm publish -w @cosplay-ai/protocol --dry-run

   Confirm the tarball contains only: dist/, package.json, README.md.

4. Cut the first tag (version in package.json must match the tag suffix):

   git tag protocol-v0.1.0
   git push origin protocol-v0.1.0