Skip to content

fix(agents): upgrade Pi to 1.5.0 - #2794

Closed
github-actions[bot] wants to merge 1 commit into
mainfrom
gardener/upstream/pi-1.5.0
Closed

github-actions[bot] wants to merge 1 commit into
mainfrom
gardener/upstream/pi-1.5.0

Conversation

@github-actions

@github-actions github-actions Bot commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Summary

Moves agents/harness/pi, agents/models/pi-ai and the pi tool adapters from Pi 1.4.0 to Pi 1.5.0.

Package From To
@earendil-works/pi-ai 1.4.0 1.5.0
@earendil-works/pi-durable 1.4.0 1.5.0
@earendil-works/chord 1.4.0 1.5.0
@earendil-works/pi-tui (dev, exact) 1.4.0 1.5.0
@earendil-works/pi-telemetry, pi-agent-core (examples, experimental) 1.4.0 1.5.0
@earendil-works/pi-schema — ~1.5.0 (new optional peer + dev)
peer range chord, pi-ai, pi-durable ~1.4.0 ~1.5.0

Pi 1.5.0 came out on 2026-11-02, the only release since 1.4.0. Our ~1.4.0 peer range doesn't cover it, so users can't install it with agents yet. pi-durable 1.5 breaks its API in many places (durable changelog).

Draft: the library, its tests and its docs are done and pass. Three example apps are built on watchEvents()/AgentEvent, which Pi removed, and still need a client rewrite. See What's left.

What changed upstream that affects us

  • high · breaking: "Tool argument validation runs on @earendil-works/pi-schema… now that pi-ai itself no longer re-exports TypeBox" (release, 6536f801). import { Type } from "@earendil-works/pi-ai" stops compiling in harness/pi/skills.ts:1, browser/tools/pi.ts:2, web/fetch/tools/pi.ts:6, web/search/tools/pi.ts:6, plus test fixtures and examples. These now use pi-schema's builders, the replacement upstream's migration note names:
    -import { Type } from "@earendil-works/pi-ai";
    +import { int, obj, opt, str } from "@earendil-works/pi-schema";
    -  return Type.Object({
    -    query: Type.String({ minLength: 1, ... }),
    -    limit: Type.Optional(Type.Integer({ minimum: 1, ... }))
    -  });
    +  return obj(
    +    { query: str({ minLength: 1, ... }), limit: opt(int({ minimum: 1, ... })) },
    +    { open: true }
    +  );
  • high · breaking: "Removed watchEvents() and its types AgentEvent, AgentEventStream, SnapshotEvent, MessageChange…" (durable changelog, f3255de7). Our public PiSession.events() (harness/pi/harness.ts:969 before) returned watchEvents()'s stream. It is replaced by watch(), which returns Pi's own conversation view:
    -  async events(context: Context = BG): Promise<AgentEventStream> {
    -    const pi = await this.#harness.pi();
    -    return watchEvents(pi, conversationId(this.id), context);
    -  }
    +  async watch(context: Context = BG, window?: ConversationWindow): Promise<ConversationWatch> {
    +    const conversation = await this.#harness.conversation(this.id);
    +    return conversation.watch(context, window);
    +  }
    The examples that use events() are covered under What's left.
  • high · breaking + workaround: "Restart-limited tasks no longer park… Harness.retryTask(), the restart_limit blocked reason… and the task_parked report… are removed" (durable changelog). pi.retryTask (harness.ts:497 before) and the restart_limit check (harness.ts:832 before) no longer compile. With parking gone, the code that worked around it has nothing left to do, so it is deleted: #parked(), retryParked(), PiHarness.retry(), PiSession.retry(), and the "parked" value of PiPendingOperation.status (types.ts:78). A cut-off task now ends visibly: the tool gets an error result, or the run ends unanswered.
  • medium · docs: the same two changes, plus session_failed → storage_failed, made docs/agents/harnesses/pi.md wrong (the call table, How recovery works, the tool example using Type, the install line). It now documents watch(), Pi ending restart-limited tasks, task_interrupted, storage_failed and pi-schema.
  • low · breaking (tests): "Storage conformance suite" grew (commit(batches, receive, context), runCounted). We get it through registerStorageConformance, and session-store.test.ts now runs 37 cases, up from 30, all passing. Our SqliteStorage comes from pi-durable, so nothing of ours changes.
  • low · new feature (type contract): whenIdle: "reject" on input submissions (#11149). tests-d/pi-durable-contract.test-d.ts:31 requires every pi input option to be exposed or excluded on purpose. Not adopted: it is a new option and nothing forces it on us. It is excluded explicitly with a comment. Possible follow-up: PiSubmitOptions.whenIdle.
  • low · new feature: ConversationTranscript, HarnessOptions.readOnly, continue submissions, maxTurns, run-end tasks, beforeProviderRequest, Usage.cost.totalFromProvider, GPT-6.1 Terra. Not adopted: all are new APIs that nothing forces on us. Users reach them through harness.pi() or pi-ai directly.
No effect on us (pi-durable, chord, pi-ai and pi-tui items: 40)
  • "SqliteExecutor… gains runCounted": we use pi-durable's own SQLite storage; no custom SqliteDatabase.
  • "Storage.commit() stores a group of commits in one call": no custom Storage; the conformance suite passes.
  • "Storage.mintId()'s contract is narrowed": bundled storage.
  • "Watches use Chord's WatchHandle/WatchEnd… listeners take one change object… tagged WatchCall": our only watch is watch() above; tests use call.kind === "value".
  • "Document watches follow their address": we don't watch documents.
  • "watches deliver the commits made while their listener runs… in one callback": no listener of ours depends on per-commit calls.
  • "Removed documentState(), viewState(), taskGraph()": unused.
  • "Partial answers and running tool output are stored later… persistWithinMs": we don't use subscribeCommits(); harness tests pass.
  • "FileSystem.watch()… WatchChange → FileChange" and "FileChange is tagged… stop()": we don't use pi-durable/env.
  • "HostCallback gains telemetry": no switch over it.
  • "ConversationView.entries is a window": messages() reads Conversation.context(), not the view.
  • "Conversation.watch(context, window?)… ConversationWindow": passed through by watch().
  • "pi.live is no longer empty after a failed run… check run === undefined": busy() already checks live?.run !== undefined (harness.ts).
  • "A generation whose model request was in flight when the host died no longer resends it": pi-internal recovery; tests pass.
  • "Observer<T>… shapes", "subscribeCommits is observeCommits": unused.
  • "HarnessOptions.onReport(report) takes one Report": our factory leaves onReport to the host; only the examples pass it, with a single parameter that still compiles.
  • "DocumentCommitChange is tagged": unused.
  • "CompactionStatus.reason… trigger": unused.
  • "TaskInspection.state… pending (was ready)": we only read submissions from inspect() now.
  • "SessionEnd… tagged by kind": #piClosing passes closed through without reading its reason.
  • "ReportFrom… tagged": unused.
  • "afterTool runs on every result": we register no afterTool.
  • "A call to a tool its request did not offer gets a pi.tool task": pi-internal.
  • "SubmissionRecord gains a type: \"continue\"": #result already returns done for a non-input record.
  • "RunFailureReason gains nothing_to_answer, turn_limit, interrupted, restart_limit": PiOperationResult.reason passes pi's reason through.
  • "pi.live.run has a required turns field": we never write pi.live.
  • "A Session's close ends synchronous observers failed": unused.
  • "Group commit", "A normal agent run makes no storage reads", "scheduler's per-commit work no longer grows", cancellation and observer-ordering changes: performance and ordering inside pi; harness tests pass.
  • "Fixed a tool round with control.handoff…", memory-retention fixes (#9265), thinkingLevel on stored messages, __proto__ partial-commit fix, rejected-commit publication, throwing telemetry adapter: pi-internal fixes.
  • "read resolving to \"\" for an image in Code Mode", Code Mode WASM import, tool_search ranking and non-ASCII tokenizing: built-in tools we don't register.
  • "Faster streaming… parsed incrementally" (f715a15c): models/pi-ai/wires/partial-arguments.ts still uses parseStreamingJson, which is still exported; models/pi-ai tests pass.
  • "Added Usage.cost.totalFromProvider": optional field; our wires compile and tests pass.
  • "Added concrete responseModel metadata": wires/chat-completions.ts:371 already sets responseModel.
  • "Updated the built-in model catalog to models.dev v2": no @cf/ id in pi-ai 1.4's Workers AI catalog is missing from 1.5, and the ids our docs and examples use are still there.
  • "Changed the default OpenAI model to gpt-6.1-sol": coding-agent default; we pass models explicitly.
  • "refactor provider definitions (#11368)": the provider subpaths we import still resolve; typecheck and tests pass.
  • "Fixed Gemini tool schemas sending unsupported const", Bedrock strict-tool fallback, OpenRouter cost and alias fixes, OpenCode endpoints, Zhipu 1308, LiteLLM overflow, Kimi K3.1, DeepSeek V4.1, GPT-5.4/5.5 namespace, Claude system-update and effort fixes: provider internals we don't wrap.
  • "Fixed the faux provider counting simulated cache-write tokens as input": our faux-based tests don't assert usage.
  • pi-tui: Kitty F-keys and image cropping, nested blockquotes, wrap and strikethrough, display math, CJK URL autolinks, Orca terminal: the TUI channel's 144 tests pass.
No effect on us (coding agent, CLI and extensions: 55)

All of these are in @earendil-works/pi-coding-agent or the terminal app, which we don't depend on: extension changelogs and collapseChangelog; custom self-update command and pi update fixes (--min-release-age, pnpm naming, Windows git clean, stale extension versions); pi.exec() maxBuffer/truncated, crash, SIGKILL, UTF-8 and spawn-error fixes; device-code login actions; keyText()/keyHint(); MarkdownTransformContext ids; ctx.ui.custom() blocked; extensions' TypeBox compat entry and TypeBoxAgentTool; tightened system prompt; /model names and search ranking; /resume search; MCP OAuth client registration and URL hardening; pi mcp login -l; glob DoS fix; saved "Do not trust"; Apple Terminal Shift+Enter; OSC 7501/133; SDK compaction OAuth; setActiveTools ordering; nested package-lock.json through symlinks; fd/rg on ARM32; login URL and control-character hardening; tui.select.pageUp/pageDown; control-sequence parameters in tool output; pi -e refresh; Windows path casing; ~ prefix display; HTML export blank page and system messages; macOS bash abort; WSL helpers and external editor; codemode description summaries; fullscreen model-scope notice; deleted cwd; failed session writes; /tree thinking level and context edits; hidden-thinking blank rows; npm audit advice; extension editor over a dialog; grep with lone CR; --model with slashes; slow forking; failing package install at startup; todo example; undici and Gondolin bumps; image resizing JPEG-first; [Skill warnings] label; terminal title escapes; fullscreen double-click selection; removed sandbox/ extension example.

Decisions

  • pi-schema becomes an optional peer (~1.5.0) of agents. pi-ai no longer exports Type, and upstream's migration is pi-schema's obj()/str(). The alternative, plain JSON Schema literals, would type every tool's args as unknown. pi-durable already depends on pi-schema 1.5.0 exactly, so Pi users have it installed already.
  • Tool schemas use { open: true }. pi-schema's obj() is closed by default (additionalProperties: false), but TypeBox's Type.Object was open. open: true keeps the schema the model sees, and the arguments we accept, as they were. Literal unions stay anyOf of const (union([lit(...)])), as before.
  • events() is replaced by watch(context?, window?), not emulated. Pi removed the event stream on purpose ("a renderer renders state instead of assembling it from events"). Rebuilding events on top of views would be our own copy of a removed upstream API. watch() returns Pi's ConversationWatch unchanged.
  • retry() and the parked status are removed, not kept as no-ops. With parking gone, retry() could only return false, which hides the change from callers. Removing it makes their code fail to compile, and the docs say what to do instead: submit again.
  • The tests were rewritten to match. The retry() test (harness.test.ts, park:) is gone. The restart-limit test now asserts the operation settles, pending() empties, and no alarm or wake job is left. The events test now checks the view shows a run, then a tool, then idle, and that a late watch() carries the same transcript as messages(). The search.test.ts cast changed because pi-schema types properties as unknown.
  • Changeset minor. The peer range moves, and agents/harness/pi's public API changes.

Needs a maintainer

  • Rewriting the three event-based examples (see What's left). Options: (a) send the conversation view's values and ops over the socket and fold them on the client with ConversationTranscript; (b) for the channels example, map view changes to SessionEvents. Recommendation: (a) for harnesses/pi and tools/browser (they share protocol.ts/view.ts/sockets.ts), because the ops carry the same text and tool deltas the events did. Then (b) for channels.
  • Removing retry() and the parked status from a public API. Options: remove them (this PR), or keep them as deprecated no-ops for one release. Recommendation: remove, because Pi no longer parks anything, so a no-op would silently report false.
  • Exposing whenIdle: "reject". Options: add it to PiSubmitOptions now, or later. Recommendation: later, in its own PR. This PR only moves to 1.5.

Affected open PRs

Other changes

  • packages/agents/package.json: dev and peer chord/pi-ai/pi-durable to ~1.5.0, dev pi-tui to 1.5.0, new dev + optional peer @earendil-works/pi-schema@~1.5.0.
  • pnpm-workspace.yaml: the pi-agent-core>pi-ai override to ~1.5.0.
  • pnpm-lock.yaml: regenerated by pnpm install. It resolves only 1.5.0 for every @earendil-works/* package, adds pi-schema and drops pi-ai's typebox. The install also re-resolved the peer suffixes of the existing @opencode/* 2.0.24 entries (ws, openai); their versions are unchanged.
  • examples/next/{channels,harnesses/pi,models,tools/browser}/package.json, experimental/pi-recovery/package.json: pi pins to ~1.5.0. channels, harnesses/pi and models also add @earendil-works/pi-schema for their tool schemas.
  • examples/next/channels/src/pi/agent.ts, examples/next/models/src/pi.ts, examples/next/harnesses/pi/src/tests/worker.ts: Type → pi-schema builders.
  • examples/next/harnesses/pi/README.md: package-sources line to ~1.5.0, and pi-schema added.
  • docs/agents/harnesses/pi.md: as above. docs/agents/models-pi-ai.md:372: required pi-ai range to ~1.5.0.
  • packages/agents/src/harness/pi/types.ts: PiPendingOperation.status drops parked; the header comment says "conversation views" instead of "events".
  • harness.ts: the session_failed comment now says storage_failed; unused imports removed.
  • .changeset/pi-1-5.md: agents minor, including the one-way note.

Evidence

  • Before (1.4.0, unchanged code): harness-pi 75/75, workers src/tests/models/pi-ai 110/110, channels 144/144, examples/next/harnesses/pi 9/9.
  • Before (1.5.0, unchanged code): packages/agents failed typecheck: Type missing from pi-ai (6 files), watchEvents/AgentEventStream/AgentEvent missing, retryTask missing, restart_limit comparison, and the whenIdle contract test.
  • After: harness-pi 81/81 (session-store conformance 37, harness 36, factory 5, options 2, browser 1), workers src/tests/models/pi-ai 110/110, workers src/tests/models/pi-ai src/tests/web src/tests/browser 618/618, channels 144/144. packages/agents builds. All 9 packages/agents tsconfigs typecheck (including tests-d), and so do examples/next/models and experimental/pi-recovery. oxfmt --check ., oxlint . and sherif pass. check:exports reports agents - all exports valid; the other packages it lists were not built in this run.

What's left

  • examples/next/harnesses/pi and examples/next/tools/browser don't typecheck. src/protocol.ts, src/sockets.ts and src/view.ts import AgentEvent, AgentEventStream and MessageChange, and call session.events(). examples/next/harnesses/pi/src/tests/worker.ts (watch(), snapshotTexts()) does the same, so that example's tests can't pass yet. Cause: Pi 1.5 removed the event stream. Fix to try: change the socket protocol to send ConversationWatch values and ops, and rebuild view.ts on ConversationTranscript.merge() plus pi.live (generation.message, tools, runFailure), following upstream's migration table.
  • examples/next/channels doesn't typecheck. src/pi/channels-harness.ts translates AgentEvent/MessageChange into channel SessionEvents from session.events(). Fix to try: translate from conversation-view calls instead (text appends from pi.live.generation.message, tool slots from pi.live.tools, idle from pi.live.run going away).
  • Example docs still describe events. docs/agents/harnesses/pi.md:266 (Run the example), examples/next/harnesses/pi/README.md and NOTES.md say the example streams session.events(). Update them together with the rewrite.

Merge Danger

Door: one-way

Blast Radius: Pi users

Pi 1.5 migrates stored state as it writes. pi.live goes to version 3, and the pi.tool and pi.generation tasks to versions 3 and 2. Its changelog says "code built against version 1 cannot read a conversation this version wrote to", and an older Harness leaves the new tasks blocked (task_too_old). After a Durable Object runs this version, rolling agents back to a Pi 1.4 build can't read its sessions. Users on ~1.4.0 get a peer-dependency warning until they move pi-ai, pi-durable and chord to 1.5 and install @earendil-works/pi-schema. Code that calls session.events(), retry(), or checks for the parked status has to change.


Opened by Gardener's pi-upgrade task. Commits pushed by Gardener don't start CI: close and reopen this pull request, or push to it, to run it. Review comments are handled by Gardener's pr-review-fix task.

Move every @earendil-works pin to 1.5.0 (peer ranges ~1.5.0) and adapt
agents/harness/pi and the pi tool adapters: tool schemas move from
pi-ai's removed TypeBox re-export to @earendil-works/pi-schema (new
optional peer), PiSession.events() becomes watch() on Pi's conversation
view, and retry() and the parked status are removed now that Pi ends
restart-limited tasks. The three AgentEvent-based examples still need
rewriting.

Gardener-Operation: op_bed681da0c423c05b523abcc1f21a6cbc46ed74c1ca453d8c5db5dc43cd6a557:d943d9d686e2a78ebf729dd739f00a82af5cfb7de7b46bda0f3db4abfda66a3a
@github-actions github-actions Bot added the dependencies Pull requests that update a dependency file label Nov 2, 2026
@changeset-bot

changeset-bot Bot commented Nov 2, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 6c7a4cd

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

@github-actions

Copy link
Copy Markdown
Contributor Author

Superseded by #2855. main already resolves Pi 1.5.0, and that pull request moves to Pi 1.5.1.

@github-actions github-actions Bot closed this Nov 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dependencies Pull requests that update a dependency file

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant