feat(agents): add durable pi harness capability

[mattzcarey]

Summary

• add experimental PiHarness from agents/harness
• host pi's durable AgentHarness in a Lifecycle Durable Object using namespaced DO SQLite tables
• persist a Lifecycle wake before pi accepts work, while leaving transcript, model/tool effects, retries, and recovery under pi's authority
• add createWorkersAI from agents/providers/pi; Kimi K2.7 Code is the default model
• add a playable React/Kumo example with calculator, dice, memory, and clock tools
• add docs, an RFC, a changeset, bundle tests, and a real Worker eviction/recovery test

Intended API

export class PiAgent extends DurableObject<Env> {
  private readonly runtime = createWorkersAI(this.env.AI);

  readonly harness = new PiHarness({
    ...this.runtime,
    tools: () => tools
  });

  readonly lifecycle = Lifecycle.install(this).use(this.harness);

  async chat(prompt: string) {
    return this.harness.prompt(prompt);
  }
}

prompt(), getMessages(), findEntries(), and getResult() follow pi's public vocabulary. submit() is intentionally host-specific: it records the recovery wake before pi lane admission.

Why Lifecycle rather than Tasks

Pi already owns the durable operation state machine, including provider intent, tool intent and settlement, retries, cancellation, and recovery. Wrapping it in Tasks would introduce a second replay authority for the same effects. Lifecycle supplies storage and durable wake delivery only.

Temporary upstream pin

The completed durable harness is currently available on pi's dev branch but not in its npm release. This PR pins earendil-works/pi@c4b0e35abe631bc830190fa6cafbe81b098b97d7 as checked-in, checksummed build inputs. The published agents tarball contains the bundled runtime and licenses, but excludes those archives. We can replace this with normal released dependencies once upstream publishes the completed harness.

Demo

https://pi-harness-playground.mattzcarey.workers.dev

The deployed example uses @cf/moonshotai/kimi-k2.7-code. Production smoke tests exercised calculator tool calls and durable memory across turns.

Verification

• pnpm install --frozen-lockfile
• pnpm run check (all 122 TypeScript projects)
• pnpm exec nx affected -t test --base=origin/main --head=HEAD (24 affected projects)
• Agents suite: 161 files, 2,746 tests
• focused Worker eviction/recovery test
• public bundle test rejects unpublished aliases, node: imports, and createRequire
• package inspection confirms licenses are included and build-input archives are excluded
• pi archive SHA-256 checksums verified
• production calculator and durable-memory smoke tests

Review focus

This is a draft so we can iterate together. The decisions most worth reviewing are:

1. the PiHarness API and pi-aligned method names
2. agents/providers/pi as the provider boundary
3. the job-first submit() contract
4. the temporary upstream pin and bundling strategy
5. the stable message projection returned by prompt() and getMessages()

[changeset-bot]

🦋 Changeset detected

Latest commit: 3d13af6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
agents	Minor
@cloudflare/agent-think	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@2197

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@2197

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@2197

hono-agents

npm i https://pkg.pr.new/hono-agents@2197

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@2197

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@2197

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@2197

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@2197

commit: 3d13af6

[mattzcarey]

Superseded by #2210, which scopes this to an example.