Skip to content

feat(agents)!: start a Pi session from an existing history - #2926

Merged
ben-reitz merged 3 commits into
feat/pi-1.6from
feat/pi-root-init
Nov 20, 2026
Merged

ben-reitz merged 3 commits into
feat/pi-1.6from
feat/pi-root-init

Conversation

@ben-reitz

@ben-reitz ben-reitz commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

A host couldn't start a Pi session from a chat history it already has. PiHarness created the root session as soon as Pi opened, before any request arrived, so there was no point at which Pi's init could be passed. Now the root is created on its first use, and everywhere PiHarness creates a session it takes Pi's init.

Summary

 PiHarness
+  root({ agent, init })         // → { session, created }
 PiSessions
-  create()
+  create({ agent, init })
-  fork(from)
+  fork(from, { agent, init })

 Pi opens (onStart)
-  pi.root({ agent: defaults })  // before any request
 first use of the root: prompt, submit, messages, watch, …
+  pi.root({ agent: defaults })  // creates it if absent
const { session, created } = await this.harness.root({
  agent: { instructions: "You are an editor." },
  init: async (tx, id) => {
    await tx.appendEntry(UserEntry, id, { model: [userMessage] });
    await tx.appendEntry(AssistantEntry, id, { model: [assistantMessage] });
  }
});
if (!created) {
  // The root already existed, so the history was not written.
}
  • agent and init are Pi's own AgentChange and ConversationInit, passed through. agent is applied over defaults for the root and create(), and over the parent's configuration for a fork.
  • init runs in the commit that creates the session. If the root already exists, nothing is written and init doesn't run; created says which happened. An init that throws creates nothing, so a later root() can try again.
  • There is no option that takes messages. Turning a host's messages into entries stays with the host; pi.md has a copyable example, one entry per message.

Evidence

  • Before: with the root created when Pi opens, 7 of the 9 new tests in PiHarness's root session fail.
    After: vitest run --project harness-pi passes, 115 tests (102 existing, unchanged, and 13 new).
  • The new tests run through a real Durable Object: a seeded root (user message, tool call, tool result, answer) is in the transcript and in the next model request; an existing root is left alone with created: false; a seed racing a prompt creates the root once; a failing init creates nothing; a session created before the root doesn't take id "1"; an object restarted before its root exists can still be seeded; create() and fork() seed too.
  • agent follows Pi's rule when it is applied over defaults: an undefined field keeps the default and null clears it. Without that merge, the two undefined tests fail.
  • A type test pins PiSessionCreateOptions to Pi's ConversationCreateOptions without ownership.

Merge Danger

Door: two-way

Objects that already have a root behave as before. Seeded entries are ordinary Pi entries.

Blast Radius: new objects

On an object whose root has not been used yet:

  • sessions.list() doesn't include the root.
  • Through harness.pi(), pi.conversation(ROOT_CONVERSATION_ID) returns undefined, and Pi's own pi.root() creates the root without defaults. Code that does either should call harness.root() first.

@ben-reitz
ben-reitz added this pull request to stack #2927 November 20, 2026 14:15
@changeset-bot

changeset-bot Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: e34ae06

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

@ben-reitz ben-reitz changed the title feat/pi root init feat(agents)!: start a Pi session from an existing history Nov 20, 2026
devin-ai-integration[bot]

This comment was marked as resolved.

@agent-think

agent-think Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

🟡 agents import sizes: 1 entry point grew

Entry point Exports Largest gzip change Size now
🟡 agents/harness/pi 1 resized +161 B (+1.15%) 13.8 KiB
Changed exports (1)
Import Gzip change Size now
🟡 agents/harness/pi#PiHarness +161 B (+1.15%) 13.8 KiB
How this works

Each runtime export is bundled on its own, minified, and gzipped. Changes smaller than 100 B, or smaller than 1% and 1 KiB, are ignored. Growth over 10% or 5 KiB is marked 🔴. This report is informational and does not fail CI. The workflow artifact contains every measurement.

Compared 3e899ee0 → e34ae061 · workflow run · reported by agent-think[bot]

@pkg-pr-new

pkg-pr-new Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

agents

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

@cloudflare/ai-chat

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

@cloudflare/codemode

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

hono-agents

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

@cloudflare/shell

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

@cloudflare/think

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

@cloudflare/voice

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

@cloudflare/worker-bundler

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

commit: e34ae06

A host that starts a session from an existing history needs Pi's `init`
on the commit that creates the conversation. PiHarness created the root
when Pi opened, in onStart, before any request could seed it.

- Opening Pi no longer creates the root. The first use of the root session
  (`conversation()`) creates it with `defaults`, through `pi.root()`, which
  returns an existing root as is.
- `harness.root({ agent, init })` creates the root with `agent` over
  `defaults` and `init` in one commit, and reports `created`: whether its
  `init` ran in the commit that created the root. Pi runs a commit's
  callback once and resolves only once it is stored, so this is exact.
- `sessions.create()` and `sessions.fork()` take the same options
  (`PiSessionCreateOptions`).
- The contract type test pins the options to Pi's `ConversationCreateOptions`
  and `Harness.root()`.
- Test fixtures that read the root through `pi.root()` create it through
  the harness first, so it still gets `defaults`.
root() and sessions.create() spread agent over the defaults, so a field that was explicitly undefined replaced the default, and pi then ignored it: the session was created without its default model, thinking level or turn limit. The merge now follows pi's rule for an AgentChange: undefined leaves the default, null clears it.
@ben-reitz
ben-reitz merged commit 6fef21d into main Nov 20, 2026
26 checks passed
@ben-reitz
ben-reitz deleted the feat/pi-root-init branch November 20, 2026 15:25
@github-actions github-actions Bot mentioned this pull request Nov 19, 2026
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