update-cloudflare-agent-stack

name	update-cloudflare-agent-stack
description	Review and upgrade c0's Cloudflare agent stack packages: agents, @cloudflare/think, @cloudflare/codemode, and @cloudflare/shell. Use when asked to update, audit, modernize, or plan upgrades for the Agents SDK, Think, Code Mode, Shell, agent runtime, @callable usage, Agent Skills, MCP agent support, or related Cloudflare agent libraries in this repo.

Update Cloudflare Agent Stack

Review version and API changes before editing. Start with an executive summary and recommended update path, then implement only after the user asks to proceed.

Scope

Primary packages:

• agents
• @cloudflare/think
• @cloudflare/codemode
• @cloudflare/shell

Also inspect dependent or peer packages when the upgrade requires it:

• ai
• chat
• @modelcontextprotocol/sdk
• @cloudflare/sandbox
• @cloudflare/dynamic-workflows
• @cloudflare/containers

Start With Evidence

1. Read the current package usage in:
   • apps/api/package.json
   • packages/api/package.json
   • packages/sandbox/Dockerfile
   • nub.lock
   • packages/api/src/server/background/isolate/agent.ts
   • packages/api/src/server/background/isolate/runtime.ts
   • packages/api/src/server/background/isolate/mcp.ts
   • packages/api/src/server/mcp/**/*.ts
2. Query installed and latest versions with nub, npm view, and lockfile inspection.
3. Fetch current upstream docs and release notes before making claims:
   • Cloudflare Agents docs: https://developers.cloudflare.com/agents/
   • Cloudflare Agents changelog: https://developers.cloudflare.com/changelog/product/agents/
   • GitHub source/release notes for cloudflare/agents
   • npm metadata for each package
4. Inspect the installed and latest package tarballs when release notes are incomplete:
   • npm pack agents@<version>
   • npm pack @cloudflare/think@<version>
   • npm pack @cloudflare/codemode@<version>
   • npm pack @cloudflare/shell@<version>
5. Compare exported types and runtime entrypoints before deciding whether code changes are benign or require refactors.

Report Before Updating

Before editing package versions, respond with:

• Current versions and latest versions.
• Relevant release-note highlights between those versions.
• Breaking or risky API differences found by source/tarball inspection.
• Repo surfaces affected.
• Recommended path, choosing one:
  • Conservative bump: minimal package updates and compatibility fixes.
  • Targeted refactor: remove or simplify c0 custom code that the newer library replaces.
  • Larger modernization: adopt new library features such as Agent Skills, newer MCP helpers, scheduling, resumable streaming, or changed Think runtime patterns.
• Validation plan and known risks.

Do not treat release-note summaries as sufficient when c0 uses internals or experimental APIs. Read source/types for those surfaces.

Implementation Rules

• Work on a separate branch for this upgrade, normally codex/update-cloudflare-agent-stack, unless the user requests a different branch name.
• Use nub for dependency changes.
• Keep package versions aligned where peer ranges imply a stack upgrade.
• Prefer deleting obsolete c0 glue code over preserving compatibility shims when the new library has an idiomatic replacement.
• Reassess @callable() and agents/vite usage. @callable() is for external Agent RPC; same-worker Durable Object RPC should not need the decorators or Agents Vite plugin.
• If agents/vite is still required, confirm whether it returns a single plugin or a plugin array in the target version, and wire it without nested plugin arrays.
• If package upgrades change MCP server/client APIs, update c0's MCP handlers and isolate MCP manager integration against current types.
• If @cloudflare/shell or sandbox-facing packages change workspace, git, filesystem, or process APIs, update the runtime provider code rather than adapting with broad casts.
• If @cloudflare/codemode changes agent/tool interfaces, update Code Mode integration and tests around the new contracts.

Validation

Run the repo's required checks before handoff:

• nub run typecheck
• nub run lint
• nub run format

Run focused checks based on changed surfaces:

• nub run --filter @c0/background-api typecheck
• nub run --filter @c0/api typecheck
• nub run test:alchemy
• Relevant MCP, isolate, workflow, sandbox, or e2e tests if touched.

If a validation command fails because of an unrelated pre-existing issue, run the narrowest check that still validates the upgraded surface and report both results.

Final Response

Include:

• Packages updated and exact version movement.
• Release-note/API changes that mattered.
• Files changed.
• Tests run with pass/fail status.
• Remaining risks or follow-up refactors.

Keep the final concise, but include enough evidence that the user can judge whether the upgrade was conservative or modernization-oriented.