Skip to content

feat: add Verse8 Agent8 services - #86

Merged
imjlk merged 7 commits into
mainfrom
codex/verse8-agent8-services
Jul 16, 2026
Merged

imjlk merged 7 commits into
mainfrom
codex/verse8-agent8-services

Conversation

@imjlk

@imjlk imjlk commented Jul 16, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • add opt-in Agent8 cloud storage with a game-owned RPC client, mandatory authenticated-encryption codec, and fail-closed server state helper
  • HMAC account and slot identifiers so global user state contains only opaque versioned envelopes
  • add a collection-backed verified leaderboard provider plus a game-specific verification boundary
  • persist only public retained-entry fields in board collections and protect attempt integrity markers plus decision collection IDs with a stable server-only HMAC secret
  • apply exact server-side ordering and shared opaque cursors over bounded collection reads without filter-plus-order or startAfter
  • recover idempotently through a durable pending-decision handoff when an entry write succeeds before its private decision marker
  • keep default Verse8 target storage local and expose cloud save at runtime only when the Agent8 client is injected
  • document the server/client wiring, key lifecycle, and focused Sampo changeset

Safety boundaries

  • does not add the React-based Agent8 browser SDK to the Phaser starter
  • never falls back to local storage after an Agent8 storage client is configured
  • requires a game-owned authenticated-encryption codec with a server-only key, fresh nonce, and account/slot associated data
  • stores no plaintext save values or raw slot names in client-subscribable global user state
  • requires stable high-entropy server-only persistence secrets of at least 32 UTF-8 bytes
  • scopes remote cloud state and leaderboard reads to the authenticated sender account
  • requires server-owned submission verification before a leaderboard write
  • keeps the lower-level recorder server-only and leaves PlatformGateway.leaderboard unavailable
  • does not persist verification evidence or raw non-retained attempt history in public board collections
  • makes private attempt-decision collection IDs infeasible to derive from public board and attempt IDs
  • blocks board operations on pending decisions until their private marker is durably written or validated
  • rejects malformed envelopes, JSON and Unicode, duplicate records, attempt collisions, inconsistent decision markers, oversized loaded storage state, and oversized boards
  • bounds retained participants to 1,000 by default with a 10,000 hard configuration ceiling

Validation

  • pnpm check
  • pnpm build:packages
  • pnpm test:prepared
  • shared verified leaderboard provider conformance suite
  • 39 Verse8 adapter tests and Node ESM dist imports
  • independent HMAC-SHA-256 reference vectors for storage slots and decision IDs
  • catalog, ad, target-config, effective-config, and target validators
  • pnpm build:verse8
  • pnpm smoke:target verse8
  • post-edit TypeScript graph synchronization

Changeset

Adds minor changesets for @mpgd/adapter-verse8 and @mpgd/cli.

Summary by CodeRabbit

  • New Features

    • Added opt-in encrypted Agent8 cloud storage for Verse8 integrations.
    • Added server-verified leaderboards with authenticated participant scoping and game-specific submission validation.
    • Added bounded, opaque cursor pagination for leaderboard queries.
    • Added public exports for Agent8 storage and verified leaderboard services.
  • Documentation

    • Documented setup, security boundaries, storage behavior, leaderboard verification, and pagination.
    • Clarified that generic platform leaderboards remain disabled by default.
  • Tests

    • Added comprehensive coverage for storage validation, limits, recovery, verification, retention, and pagination.

@imjlk

imjlk commented Jul 16, 2026

Copy link
Copy Markdown
Owner Author

@codex review

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 16, 2026 •

Copy link
Copy Markdown

@imjlk I'll review the changes now.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai

coderabbitai Bot commented Jul 16, 2026 •

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@imjlk, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 45 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 225190b0-4c39-4397-a9b2-fd56ba283770

📥 Commits

Reviewing files that changed from the base of the PR and between 609966c and 5eb4bef.

📒 Files selected for processing (6)
  • .sampo/changesets/verse8-agent8-services.md
  • README.md
  • adapters/verse8/src/agent8-services.test.ts
  • adapters/verse8/src/agent8-services.ts
  • docs/VERSE8_AGENT8_SERVICES.md
  • packages/cli/templates/phaser-game/README.md
📝 Walkthrough

Walkthrough

Adds opt-in Verse8 Agent8 cloud storage, a server-verified leaderboard provider with authenticated participant scoping and opaque pagination, gateway integration, tests, exports, documentation, and release metadata.

Changes

Verse8 Agent8 integration

Layer / File(s) Summary
Agent8 storage contracts and gateway routing
adapters/verse8/src/agent8-services.ts, adapters/verse8/src/index.ts, adapters/verse8/src/index.test.ts
Adds validated, bounded, locked cloud-state storage and routes gateway operations to an injected Agent8 storage client without local fallback.
Verified leaderboard persistence and pagination
adapters/verse8/src/agent8-services.ts, adapters/verse8/src/agent8-services.test.ts
Adds authenticated submission verification, digest-backed decisions, retained entries, ranking, recovery handling, and bounded opaque cursor snapshots.
Exports, target wiring, and service documentation
adapters/verse8/src/agent8.ts, adapters/verse8/test/agent8-dist-import.mjs, docs/VERSE8_AGENT8_SERVICES.md, README.md, packages/cli/templates/phaser-game/README.md, .sampo/changesets/verse8-agent8-services.md, tools/smoke/effective-target-config.ts
Publishes Agent8 exports, documents server-only integration contracts, updates starter guidance and release metadata, and clarifies default local storage configuration.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant GameClient
  participant Verse8PlatformGateway
  participant Agent8StorageService
  participant Agent8StateContext
  GameClient->>Verse8PlatformGateway: save/load cloud state
  Verse8PlatformGateway->>Agent8StorageService: delegate storage operation
  Agent8StorageService->>Agent8StateContext: read/update authenticated user state
  Agent8StateContext-->>Agent8StorageService: stored state
  Agent8StorageService-->>Verse8PlatformGateway: storage result
Loading
sequenceDiagram
  participant AuthenticatedClient
  participant LeaderboardBoundary
  participant GameVerifier
  participant VerifiedLeaderboardProvider
  AuthenticatedClient->>LeaderboardBoundary: submit attempt
  LeaderboardBoundary->>GameVerifier: verify submission
  GameVerifier-->>LeaderboardBoundary: verified attempt or rejection
  LeaderboardBoundary->>VerifiedLeaderboardProvider: record verified attempt
  VerifiedLeaderboardProvider-->>AuthenticatedClient: submission or snapshot result
Loading

Possibly related PRs

  • imjlk/mpgd-kit#57: Introduces the shared verified-leaderboard contract implemented by this provider.
  • imjlk/mpgd-kit#58: Adds the conformance suite exercised by these Verse8 leaderboard tests.
  • imjlk/mpgd-kit#82: Updates the Verse8 adapter foundation used by this gateway integration.

Poem

A rabbit hops through cloud-saved state,
While verified scores line up straight.
Cursors turn, digests gleam,
Safe leaderboards join the stream.
“No local fallback!” the bunny sings,
Agent8 brings authenticated things.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title is concise and accurately summarizes the main change: adding Verse8 Agent8 services.
Description check ✅ Passed It covers the required summary and validation sections with substantial implementation notes; only the optional Notes section is missing.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/verse8-agent8-services

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1cf7654af2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread adapters/verse8/src/agent8-services.ts Resolved
Comment thread adapters/verse8/src/agent8-services.ts Resolved
Comment thread adapters/verse8/src/agent8-services.ts Resolved

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
adapters/verse8/src/agent8-services.test.ts (1)

73-157: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider adding a test for the orphaned-attempt-entry recovery path.

recordVerifiedAttempt in adapters/verse8/src/agent8-services.ts (lines 319-329) has specific recovery logic for when an entries write succeeded but the corresponding attempts decision write never completed (e.g. a crash between the two calls). This is a non-obvious, implementation-specific correctness guarantee that the imported conformance suite is unlikely to cover, since it depends on the two-collection storage model of this specific provider. A test that manually seeds fixture's entries collection (bypassing attempts) and then re-submits the same attempt would validate this recovery path directly.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@adapters/verse8/src/agent8-services.test.ts` around lines 73 - 157, Add a
focused test near the existing provider tests that seeds the fixture’s entries
collection for an attempt without creating its corresponding attempts decision,
then re-submits that same attempt through recordVerifiedAttempt. Assert the
orphaned entry is recovered correctly and the resulting state matches the normal
successful recording path, using the fixture APIs and symbols exposed by
createAgent8Context.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@adapters/verse8/src/agent8-services.test.ts`:
- Around line 73-157: Add a focused test near the existing provider tests that
seeds the fixture’s entries collection for an attempt without creating its
corresponding attempts decision, then re-submits that same attempt through
recordVerifiedAttempt. Assert the orphaned entry is recovered correctly and the
resulting state matches the normal successful recording path, using the fixture
APIs and symbols exposed by createAgent8Context.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: be4fac93-1bcb-461d-8f4e-dc59700aee01

📥 Commits

Reviewing files that changed from the base of the PR and between 760cdec and 1cf7654.

📒 Files selected for processing (12)
  • .sampo/changesets/verse8-agent8-services.md
  • README.md
  • adapters/verse8/src/agent8-services.test.ts
  • adapters/verse8/src/agent8-services.ts
  • adapters/verse8/src/agent8.ts
  • adapters/verse8/src/index.test.ts
  • adapters/verse8/src/index.ts
  • adapters/verse8/test/agent8-dist-import.mjs
  • docs/VERSE8_AGENT8_SERVICES.md
  • packages/cli/templates/phaser-game/README.md
  • packages/target-config/targets.json
  • tools/smoke/effective-target-config.ts

@imjlk

imjlk commented Jul 16, 2026

Copy link
Copy Markdown
Owner Author

Addressed all current review feedback in 0798bfc and a4d4eaf:

  • removed verification evidence and non-retained attempt history from global collections
  • moved boards and attempt decisions to digest-derived collections with public retained fields only
  • removed Agent8 filter-plus-order, counts, range queries, and indexed sort keys
  • added bounded server-side ranking and opaque cursor slicing
  • added an interruption-recovery test for an entry write that precedes its decision marker
  • reran the full package build, prepared test suite, target validators, Verse8 production build, and 36 adapter tests

@codex review

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 16, 2026 •

Copy link
Copy Markdown

@imjlk Thanks for the detailed summary of the changes. I'll review the updated code now.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a4d4eafade

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread adapters/verse8/src/agent8-services.ts Resolved
Comment thread packages/target-config/targets.json Resolved
Comment thread adapters/verse8/src/agent8-services.ts Resolved
@imjlk

imjlk commented Jul 16, 2026

Copy link
Copy Markdown
Owner Author

Addressed the latest Codex review in 609966c:

  • use own-property checks for user-controlled storage keys and cover inherited names under entry limits
  • keep the default Verse8 effective target storage local; gate optional Agent8 cloud UI on the injected gateway runtime feature
  • reject trailing unpaired high surrogates in save keys, values, and object keys
  • narrow the Sampo changeset to the adapter and CLI packages
  • rerun pnpm check, package builds, the full prepared suite, target validators, the Verse8 production build, target smoke, 38 adapter tests, and the post-edit TypeScript graph tour

@codex review

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 16, 2026 •

Copy link
Copy Markdown

@imjlk Thanks for the update. I'll review the latest changes in commit 609966c now, covering the own-property checks for storage keys, the local-default/Agent8-gated storage capability, unpaired surrogate rejection, and the narrowed changeset scope.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/VERSE8_AGENT8_SERVICES.md`:
- Around line 81-84: Update the Verse8 example’s cloud-save gating to call the
gateway capabilities API and read the cloudSave property from await
gateway.getCapabilities(). Remove the unsupported gateway.features reference
while preserving the existing conditional behavior.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 56b87932-fa4c-4691-8f6c-72f9c732768f

📥 Commits

Reviewing files that changed from the base of the PR and between 1cf7654 and 609966c.

📒 Files selected for processing (6)
  • .sampo/changesets/verse8-agent8-services.md
  • README.md
  • adapters/verse8/src/agent8-services.test.ts
  • adapters/verse8/src/agent8-services.ts
  • docs/VERSE8_AGENT8_SERVICES.md
  • tools/smoke/effective-target-config.ts
🚧 Files skipped from review as they are similar to previous changes (3)
  • .sampo/changesets/verse8-agent8-services.md
  • tools/smoke/effective-target-config.ts
  • adapters/verse8/src/agent8-services.ts

Comment thread docs/VERSE8_AGENT8_SERVICES.md Resolved
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: 609966c008

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@imjlk

imjlk commented Jul 16, 2026

Copy link
Copy Markdown
Owner Author

Addressed the CodeRabbit documentation finding in b79c78a:

  • replace the unsupported gateway.features reference with await gateway.getCapabilities()
  • gate cloud-save UI and behavior on the returned cloudSave capability
  • rerun pnpm check and diff validation

@codex review

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 16, 2026 •

Copy link
Copy Markdown

@imjlk Thanks for the update. I'll review the changes in commit b79c78a now, covering the gateway.getCapabilities() replacement and the cloudSave-gated UI/behavior.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b79c78acae

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread adapters/verse8/src/agent8-services.ts Resolved
Comment thread adapters/verse8/src/agent8-services.ts Resolved
@imjlk

imjlk commented Jul 16, 2026

Copy link
Copy Markdown
Owner Author

Addressed the latest Codex security review in ecda1ea:

  • require a game-owned authenticated-encryption codec for Agent8 cloud saves; no plaintext default remains
  • HMAC account and slot identifiers and store only strict version-2 keyId/ciphertext envelopes in global user state
  • pass account and slot into seal/open so codecs can authenticate associated data
  • require stable high-entropy server-only persistence secrets for storage and verified leaderboards
  • HMAC attempt integrity markers and private decision collection IDs so public attempt IDs cannot derive them
  • add fail-closed envelope validation, secret validation, independent HMAC vectors, ciphertext-only state assertions, and updated key-lifecycle guidance
  • rerun pnpm check, package builds, the full prepared suite, target validators, Verse8 production build and smoke, 39 adapter tests, and the final TypeScript graph tour

@codex review

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 16, 2026 •

Copy link
Copy Markdown

@imjlk Thanks for the detailed update on the security hardening work. I'll review the changes in commit ecda1ea now, covering the authenticated-encryption codec requirement, HMAC-based account/slot identifiers and integrity markers, the version-2 envelope format, persistence secret requirements, and the fail-closed validation additions.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ecda1ea96f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread adapters/verse8/src/agent8-services.ts Resolved
Comment thread adapters/verse8/src/agent8-services.ts Resolved
@imjlk

imjlk commented Jul 16, 2026

Copy link
Copy Markdown
Owner Author

@codex review

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 16, 2026 •

Copy link
Copy Markdown

@imjlk I'll review the latest changes now.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 🎉

Reviewed commit: 5eb4beff9c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@imjlk
imjlk merged commit f3ea335 into main Jul 16, 2026
6 checks passed
@imjlk
imjlk deleted the codex/verse8-agent8-services branch July 16, 2026 07:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant