Mochi

Mochi is an open-source AI-native game controller: one persistent AI gaming companion, one durable player memory, and a standard way for compatible games to summon the agent through official contracts, APIs, MCP tools, signed wake events, legal affordances, and server-side validation.

Mochi plays with you, not for you. It can act while you are away, but it stays inside the game rules, remembers what matters, and brings you back when the moment deserves your hand.

What Mochi Is

Mochi is being built for games that explicitly choose to support AI-agent play. A compatible game owns the truth: state, secrets, legal actions, validation, and outcomes stay server-authoritative. Mochi owns companion continuity, play style, legal decisioning, memory proposals, and debriefs. Internally, Mochi is building toward a console for AI-native games, but the open-source v0 should not overpromise a hosted store or managed console before the controller loop works.

The first target ecosystem is:

• Prom13us as the first Level 4 agent-native reference game.
• Rizz My Robot as a second proof for a very different social game loop.
• Sitrep later, once the protocol can handle faster tactical decisions.

The long-term goal is a controller standard that third-party studios can adopt without handing Mochi hidden mechanics or asking it to impersonate a human player.

Studios can start with the Studio Quickstart, which walks from a game-owned mochi-game.json contract to official reads, one server-validated legal intent, signed wakes, and local conformance checks.

What Mochi Is Not

Mochi is not:

• AI cheating software.
• A bot that plays arbitrary human games.
• A screen scraper, input injector, process reader, memory reader, packet inspector, aim assistant, or anti-cheat bypass.
• NPC middleware.
• A generic "AI plays any game" harness.

Mochi should refuse unsupported games and cheating-shaped requests. Future game actions must go through explicit game contracts, sanctioned state and affordance APIs, signed wake events, legal intent submission, and server-side validation. The official unsupported-game refusal policy lives in docs/policy/unsupported-games.md.

Why Agent-Native Games Need A Controller

Agent-native games are designed around persistent AI players, companions, or co-pilots that can safely participate when the human is present or away. That needs different infrastructure from ordinary automation:

• The game must declare exactly what Mochi may see and do.
• The game must validate every proposed action.
• The human must be able to coach, approve, override, and inspect decisions.
• Memory must survive sessions without turning manual notes into game canon.
• Debriefs and commentary must explain outcomes without leaking hidden mechanics.

Mochi exists to make those boundaries normal instead of improvised for every game.

Architecture Sketch

The v0 runtime shape is an OpenClaw-like daemon and Gateway with Telegram-first human coaching and terminal access. Games call Mochi directly when something needs attention, and current local proofs exercise parts of that path without opening public ingress or claiming production game play.

compatible game
  -> signed wake event
  -> Mochi daemon
  -> fresh game state and legal affordances
  -> policy, model, or human approval route
  -> legal intent or no-op
  -> game server validates outcome
  -> trace, memory proposal, and public-safe debrief

Core surfaces in the v0 track:

• local or VPS daemon using the same protocol across deployments
• Telegram as the primary coaching, commentary, and approval channel, with explicit-config live delivery and Bot API polling primitives
• terminal commands for setup, status, game connection, memory, and doctor checks
• local workspace files such as BOOTSTRAP.md, IDENTITY.md, SOUL.md, PLAYER.md, GAMING_MANIFESTO.md, and per-game strategy.md
• mochi-game.json contracts for game authority
• durable signed wakes, Gateway run state, replayable checkpoints, provider-safe Active Context, model-generation calls, trusted-adapter receipts, and redacted debriefs

Architecture vocabulary is defined in docs/architecture/vocabulary.md: the Mochi Agent is the persistent companion; the Mochi Controller Engine is the daemon runtime; the Mochi SDK is game-developer helper glue; the Game Connector is game-owned integration code; and the Game Server owns truth and validates outcomes.

Gateway vocabulary is defined in docs/gateway/overview.md: Mochi Gateway is the planned player-owned local/VPS/game-colocated controller process around one Mochi Agent and many compatible game sessions. It may coordinate bounded internal child runs for compatible-game subagent lanes and operator/developer verification work, but it is not a consumer multi-agent gateway, generic MCP proxy, relay inbox, hosted service, or game-owned connector.

Markdown identity, memory, and strategy files guide Mochi. Deterministic hooks, policy validators, contract checks, approval gates, and server-side validation enforce what Mochi may actually do.

Protocol interop stays layered: mochi-game.json owns game authority, MCP is a tool/context transport, AG-UI-style events are for user-visible status, and A2A is reserved for later agent-to-agent discovery and coordination.

A Mochi agent card gives compatible games a public-safe way to discover an instance's supported games, capabilities, modalities, auth requirements, budgets, and availability before sending wakes.

Compatibility Levels

Mochi compatibility is a ladder:

| Level | Name | Meaning | | --- | --- | --- | | 0 | Documented | The game exposes docs or read-only APIs. Mochi can learn rules but cannot act. | | 1 | Legal Actions | The game exposes official state, affordances, and submit-intent endpoints. | | 2 | Game Summons | The game can wake Mochi through signed, durable, replay-safe events. | | 3 | Companion Loop | The game supports debriefs, coaching, memory deltas, no-op reasons, and takeover. | | 4 | Agent-Native | The game design structurally depends on Mochi-like persistent AI players. |

Prom13us should become the first Level 4 reference implementation. Rizz My Robot should prove the protocol works outside long-running world simulation.

Safety Boundary

Mochi-compatible games must be explicit opt-ins. A game contract should define auth, game id, contract version, transports, wake reasons, endpoints, MCP tools, action affordance schema, redaction rules, issue routing, and anti-cheat boundaries.

Official Mochi no-ops for games without trusted Mochi-compatible contracts, unsupported human games, screen scraping, input injection, hidden-state reads, packet inspection, anti-cheat bypass, and terms-of-service evasion. This is a public product boundary, not a license restriction on forks.

The game remains authoritative for:

• canon state
• hidden mechanics
• legality checks
• accepted or rejected outcomes
• redaction rules
• security-sensitive report routing

Mochi memory edits are not game truth. Manual contract edits must be treated as untrusted until revalidated against a trusted signed or fetched copy.

Project Status

Mochi is pre-alpha. The repository currently has a Bun + TypeScript monorepo, contract schemas, wake storage, policy/memory/workspace primitives, a daemon status/readiness surface, a localhost-only dashboard shell with readiness, contract trust, tool inspection, replay review, active-context inspection, and memory guidance panels, local conformance tooling, provider auth and OpenAI/MiniMax model-generation runtime, CLI talk, Gateway conversation runs, provider-planned mock-game wake-to-receipt proof, Prom13us and Rizz adapter packages, explicit-config live Telegram delivery and Bot API polling primitives, tests, canonical commentary-mode planning, and planning docs. The local V0 owner proof lives in docs/runtime/v0-manual-proof.md.

The canonical Telegram commentary-mode plan lives in docs/telegram/commentary-mode.md. It defines co-watching versus away commentary, Telegram draft/final-message semantics, viewer-presence requirements, reply/memory-proposal boundaries, and the implementation PR sequence. Shared CommentaryCandidate and ViewerPresenceSignal schemas now live in @mochi/contracts, with thin game-facing validation helpers in @mochi/game-sdk. The deterministic commentary budget resolver lives in @mochi/policy and applies quiet hours, away-mode filtering, activation notice idempotency, hype bursts, and the one-final-message cadence. The deterministic commentary renderer lives in @mochi/debrief; it turns sendable commentary decisions into local, public-safe text and live-activation notice copy without provider calls. The Gateway commentary Telegram dispatcher now queues that rendered output through the durable outbox and proves fake rich final delivery while keeping draft telemetry ephemeral. The Gateway soft-prompt bridge now turns safe paired Telegram replies to unexpired commentary questions into pending memory patch proposals, without executing commands, submitting game actions, or writing durable memory directly. The Gateway model-written/hybrid commentary renderer now uses bounded provider context only when the owner-selected renderer allows it, records cost posture, falls back deterministically on provider or safety failures, and normalizes sendable model text into the existing commentary Telegram outbox payload. The Prom13us commentary local proof now converts public-safe Prom13us notification debriefs into commentary candidates, resolves live versus away presence, streams ephemeral co-watching draft telemetry, and proves final fake Telegram delivery evidence without live production credentials.

Mochi still does not publish preferred @mochi/* player packages, host certification, open live HTTP ingress by default, expose public dashboard ingress, provide dashboard game control panels, run production Prom13us/Rizz play outside compatible-game contracts and server-validated proofs, support unsupported games, execute arbitrary live MCP tools, provide hosted accounts, or mutate game canon outside trusted game-owned validation.

Mochi uses the Apache-2.0 license. See CONTRIBUTING.md, SECURITY.md, and PRIVACY.md before opening public contributions, reporting vulnerabilities, or experimenting with local data.

Issue-reporting consent and attribution rules live in docs/privacy/issue-reporting.md. Mochi does not silently file issues under the player or use signed-out GitHub filing as a default.

Local repair candidate planning lives in docs/issue-reporting/repair-candidates.md. mochi repair plan --fixture failing-test turns fixture-backed local failure evidence into a redacted mochi.repair.plan RepairCandidate while keeping commandsExecuted: false, networkFiled: false, and codePushed: false. mochi repair proposal --fixture failing-test --workspace-root <repo> converts that evidence into a pending RepairProposal with workspace-relative target files, real target digests, validation commands, rollback notes, maintainer approval, and no current file writes or GitHub side effects. createRepairWorktreePlan() then records an API-only repair worktree plan with origin/main, branch name, sibling worktree path, dirty-checkout policy, cleanup commands, worktreeCreated: false, and codePushed: false. mochi repair apply --proposal <path> --patch <path> --approval-ref <ref> can then consume a maintainer-approved RepairProposal plus a local mochi.repair.patch full-file replacement artifact inside that isolated worktree. It checks approval, branch/base refs, target digests, and dirty WIP, writes only approved source files, returns mochi.repair.apply with a rollback command, and still reports codePushed: false and pullRequestCreated: false. After apply, mochi.repair.verification_report records required validation command metadata with redacted summaries and a local mochi.repair.report_ledger_event; repairs keep canAdvanceToPr: false until every proposal validation command passes and the ledger proof exists. See docs/issue-reporting/repair-verification.md. mochi.repair.github_authorization_dry_run then proves, without a live GitHub call, whether a future repair branch push and PR creation would be authorized by allowed repositories, identity mode, explicit approval, contentsWrite, pullRequestsWrite, base/head refs, labels, and verification ledger proof. It can emit mochi.repair.github_pull_request_intent, but still keeps networkFiled: false, codePushed: false, and pullRequestCreated: false. createOrUpdateRepairGitHubPullRequest() can then create or update the repair PR only after an exact create_or_update_pull_request maintainer approval for the same repository, identity, proposal, base/head branches, title, body digest, labels, and intent digest. It records mochi.repair.github_pull_request_result and mochi.repair.github_pull_request_audit_entry with the PR URL and redacted digest evidence; this live PR step sets networkFiled: true while keeping branchPushed: false, codePushed: false, hosted telemetry false, and no auto-merge. mochi.repair.pr_review_revision lets Mochi convert selected maintainer comments on that repair PR into a new pending RepairProposal revision without expanding authority. It rejects a stale repair branch, keeps pullRequestUpdated: false, and leaves the update gate closed with revision_requires_separate_approval_apply_and_verification until the revision is separately approved, applied, verified, ledgered, and authorized. There is no autonomous comment polling, no CI bypass, and no self-merge. See docs/issue-reporting/repair-github-authorization.md. Review-loop details live in docs/issue-reporting/repair-review-loop.md. self-repair-e2e is the reproducible local proof fixture for the whole bounded source-repair lane: detect, propose, approve, apply, verify, report, mocked PR intent. It records mochi.repair.self_repair_e2e_proof without live PR creation, package update apply, or game-runtime repair. See docs/issue-reporting/self-repair-e2e-proof.md.

Player Install

Mochi is pre-alpha, and the fallback CLI package is registry-proven at @rizzmyrobot/[email protected] by trusted publishing plus npm view @rizzmyrobot/[email protected] proof. The public player install path is npm/npx, not cloning the repository and running Bun.

Because @mochi/* npm ownership is not proven, the fallback package scope is the current public install target. The one-line player install is:

npm install -g @rizzmyrobot/mochi-cli
mochi setup

mochi setup is the player first-run command. In an interactive terminal it runs a real guided setup: choose MiniMax with an API key, OpenAI with an API key, MiniMax broker-backed OAuth, or Codex login; choose a provider model from a numbered menu; then choose terminal-only chat, Telegram, or Discord. MiniMax API key plus terminal-only chat remains the no-broker fallback so setup does not force a Telegram bot token before local terminal chat is useful. When a verified Mochi MiniMax OAuth broker issuer is configured, MiniMax OAuth is shown as an implemented runtime path and setup stores only local oauth: refs. When credentials are actually available, setup seeds the proof workspace, writes local runtime config refs, stores local secrets, validates selected Telegram bot tokens with the Bot API getMe check, and prints a concise current setup, next step, and try-it command. Detailed redacted audit output stays behind --format json. Non-interactive mochi setup --guide remains a no-write preview for CI, docs, and scripts.

MiniMax/OpenAI API-key refs, Telegram config, workspace seed files, local provider credential refs, and local Telegram token refs reuse the existing provider auth, configure, proof workspace seed, Telegram, Gateway, and secret-store packages. MiniMax API key is the default usable MiniMax first-run path for now. MiniMax OAuth remains visible as the desired consumer login path, but default onboarding does not ask normal users for a MiniMax OAuth client ID and does not store fake oauth: refs until a provider device/browser endpoint or Mochi auth broker exists. When that broker or provider browser/device endpoint is explicitly configured via environment, confirmed onboarding can run the existing PKCE browser login, RFC-style device flow, or MiniMax-style code/token polling flow and write MiniMax refs only after token exchange succeeds. A configured MOCHI_MINIMAX_OAUTH_ISSUER can provide device/token endpoints from broker metadata. If that metadata includes a verified Mochi broker attestation with a public client identity, onboarding can use it without asking the user for a MiniMax OAuth client ID; otherwise it still requires an explicit client identity or PKCE mode. Mochi does not bundle another tool's MiniMax OAuth client identity. Maintainers can run mochi provider oauth discover --provider minimax --issuer <url> to inspect a broker or authorization-server metadata document, and can run a redacted mochi provider oauth verify-broker --provider minimax --issuer <url> to check for a Mochi-owned broker attestation. They can also run mochi provider oauth probe to inspect endpoint shape without storing device codes or tokens. None of these commands is a default onboarding login by itself. Custom MiniMax OAuth app client IDs remain an advanced mochi provider oauth login --client-id ... path. Codex OAuth runs the external codex login path, but it is not yet a Mochi provider runtime for mochi talk. Discord is exposed as a product choice, but it does not accept or store Discord bot tokens until a Discord runtime package exists.

npx follows the same fallback scope:

npx @rizzmyrobot/mochi-cli setup
npx @rizzmyrobot/mochi-cli help
npx @rizzmyrobot/mochi-cli help advanced
npx @rizzmyrobot/mochi-cli gateway status
npx @rizzmyrobot/mochi-cli doctor repair --workspace-root ~/.mochi/workspace --confirm
npx @rizzmyrobot/mochi-cli tools doctor --workspace-root ~/.mochi/workspace --game mock-game

If maintainers later prove the @mochi/* npm scope is controlled by the project, the same player commands use the preferred package name:

npm install -g @mochi/cli
npx @mochi/cli setup
npx @mochi/cli gateway status
mochi setup

Current fallback CLI install gateway start --profile local --foreground can start the proven local live foreground runtime on loopback. gateway status and gateway doctor report not_running when nothing is reachable and probe the configured loopback live service when it is running. Dry-run planning remains available for setup review, and gateway install-service proposal plus gateway install-service apply can write/remove owner-approved local launchd or gated VPS systemd files without loading or starting them. proposal review --proposal <path> renders the same reviewed runtime-config or gateway service proposal artifact for terminal owner review before apply, with redacted fields only and no file writes.

Interactive mochi setup may write local workspace seed files, runtime config refs, and local secrets; MiniMax OAuth uses the configured Mochi broker issuer when one is present and otherwise stays on the API-key fallback; Telegram setup may call only the Bot API getMe validation endpoint. It does not call model providers, poll Telegram, send Telegram messages, connect Discord, connect production games, submit production intents, or change game canon. The separate credentialed talk command can call a selected model provider for a local Mochi reply; contributor/runtime docs describe the local owner proof for credentialed provider and Telegram conversation, and the mock-game proof exercises a fixture provider response plus a trusted local adapter receipt.

When setup is locally broken, mochi doctor repair --confirm runs the narrow self-repair lane. It may create only missing known workspace seed templates and the workspace attestation marker through existing proof primitives. It does not edit source code, install packages, rewrite memory truth, rewrite contracts, apply bootstrap/profile truth, call providers, poll Telegram, start Gateway, connect games, submit intents, or mutate game canon.

The local laptop Gateway install flow lives in docs/gateway/local-install.md. The player onboarding map lives in docs/onboarding/player.md.

mochi proof config-mutation --workspace-root <path> proves the owner-approved local config mutation loop without source-code repair, package updates, GitHub calls, Gateway service changes, provider calls, Telegram polling/sending, game actions, or game-canon mutation. The JSON payload type is mochi.cli.config_mutation_proof; it writes reviewable proposal artifacts, applies them through configure apply, runs configure status, and prints rollback metadata for the local runtime checkpoints. Live credential readiness is still reported separately inside status.

Game Developer SDK Install

Game developers install the current SDK package cone from npm with fallback package names. Until the preferred @mochi/* scope is proven and published, use:

npm install @rizzmyrobot/mochi-game-sdk @rizzmyrobot/mochi-contracts

Preferred @mochi/* package names remain a future migration condition, not a studio install command, until release docs record maintainer npm-scope control and registry proof for the exact preferred package versions.

The SDK helps studios expose game-owned contracts, state, affordances, signed wakes, legal intent validation, and receipts. It does not transfer game canon or hidden mechanics to Mochi. The studio onboarding map lives in docs/onboarding/studio.md.

Contributor Setup

Contributors use Bun inside the monorepo:

bun install
bun run verify
bun run cli -- status
bun run daemon
bun run cli -- dashboard --dry-run
bun run cli -- dashboard --contract tests/fixtures/contracts/valid-mochi-game.json --dry-run
bun run cli -- dashboard --trace-db ./decision-traces.sqlite --dry-run
bun run cli -- dashboard --memory-db ./memory.sqlite --dry-run
bun run cli -- gateway start --profile local --foreground
# optional, writes local proof artifacts/config/checkpoints under the workspace
bun run cli -- proof config-mutation --workspace-root ~/.mochi/workspace --format json
# optional, requires real owner-supplied provider and Telegram credentials
bun run cli -- configure proposal provider --workspace-root . --provider openai --model <model> --credential-ref secret:providers/openai/default --format json > /tmp/mochi-provider-config-proposal.json
bun run cli -- proposal review --proposal /tmp/mochi-provider-config-proposal.json
bun run cli -- configure apply --proposal /tmp/mochi-provider-config-proposal.json --approval-ref <approval-ref-from-proposal>
bun run cli -- configure proposal telegram --workspace-root . --owner owner-local --telegram-user-id <telegram-user-id> --bot-token-ref os:mochi/telegram/bot-token --format json > /tmp/mochi-telegram-config-proposal.json
bun run cli -- proposal review --proposal /tmp/mochi-telegram-config-proposal.json
bun run cli -- configure apply --proposal /tmp/mochi-telegram-config-proposal.json --approval-ref <approval-ref-from-proposal>
bun run cli -- configure provider --workspace-root . --provider openai --model <model> --credential-ref secret:providers/openai/default --credential-stdin
bun run cli -- configure telegram --workspace-root . --owner owner-local --telegram-user-id <telegram-user-id> --bot-token-ref os:mochi/telegram/bot-token --bot-token-stdin
bun run cli -- provider validate --workspace-root .
bun run cli -- telegram validate --workspace-root .
bun run cli -- talk --workspace-root . --game example-arena --message "Hello Mochi"
bun run cli -- telegram listen --poll-once --workspace-root . --game example-arena
bun run proof:live-owner -- --workspace-root . --game example-arena --skip-telegram
bun run release:cli-package-dry-run -- --out-dir dist/package-dry-runs/cli --scope fallback

Contributor commands only prove the repository shell and local dry-run package shape. The credentialed talk command can call a selected model provider for a local Mochi reply, and the credentialed telegram listen command can answer owner DMs through the same Gateway conversation handler after local CLI configuration. These contributor commands do not install a player controller from npm, connect to live games, connect to unsupported games, submit intents, or change game canon. Mochi does not connect to unsupported games.

For the redacted local V0 owner proof, use docs/runtime/v0-manual-proof.md. It shows the bun run proof:live-owner wrapper plus the CLI and Telegram transcript fields to capture without leaking provider keys, Telegram bot tokens, private prompts, or hidden game state.

The current gateway proofs are contributor-only: the mock-game proof exercises one local compatible game, and the Prom13us gateway dry-run proves signed wake routing, read-only context, no-op output, trace/debrief/audit, and no canon write without production Prom13us credentials. The contributor onboarding map lives in docs/onboarding/contributor.md.

Development Plan

The saved section-based sprint plan lives at docs/research/mochi-agent-native-controller-plan.md.

Early foundation work is intentionally sequenced:

1. Repo scaffold.
2. README product front door and boundary.
3. Open-source license decision ADR.
4. LICENSE file and SPDX/package metadata.
5. Package layout and shared TypeScript config.
6. Test harness and CI commands.
7. Contribution and security-reporting rules.

Each PR should introduce one durable concept, prove it, document it, and avoid weakening the anti-cheat boundary.