feat(pi): manage pull requests in update mode

Author: Bill Leoutsakos

apps/docs/content/docs/en/workflows/blocks/pi.mdx

@@ -76,7 +76,7 @@ describe('Pi block search fields', () => {
 })
 
 describe('Pi cloud authoring surface', () => {
-  it('offers Create PR, Update Branch, Review Code, and Local Dev as top-level modes', () => {
+  it('offers Create PR, Update PR, Review Code, and Local Dev as top-level modes', () => {
     const mode = PiBlock.subBlocks.find((subBlock) => subBlock.id === 'mode')
     const options =
       typeof mode?.options === 'function'
@@ -163,7 +163,7 @@ describe('Pi cloud authoring surface', () => {
     expect(evaluateSubBlockCondition(pullNumber?.condition, { mode: 'cloud_review' })).toBe(true)
   })
 
-  it('requires the target branch only in Update Branch mode', () => {
+  it('requires the target branch only in Update PR mode', () => {
     expect(targetBranchField?.type).toBe('short-input')
     expect(targetBranchField?.required).toBe(true)
     expect(evaluateSubBlockCondition(targetBranchField?.condition, { mode: 'cloud_branch' })).toBe(
@@ -207,10 +207,22 @@ describe('Pi cloud authoring surface', () => {
     }
   })
 
-  it('hides Create PR and Review Code-specific fields', () => {
-    for (const id of ['baseBranch', 'branchName', 'draft', 'prTitle', 'prBody', 'pullNumber']) {
+  it('shows PR metadata controls and hides Create PR and Review Code-only fields', () => {
+    for (const id of ['baseBranch', 'prTitle', 'prBody', 'prState']) {
+      const field = PiBlock.subBlocks.find((subBlock) => subBlock.id === id)
+      expect(evaluateSubBlockCondition(field?.condition, { mode: 'cloud_branch' })).toBe(true)
+    }
+    for (const id of ['branchName', 'draft', 'pullNumber']) {
       const field = PiBlock.subBlocks.find((subBlock) => subBlock.id === id)
       expect(evaluateSubBlockCondition(field?.condition, { mode: 'cloud_branch' })).toBe(false)
     }
+    const prState = PiBlock.subBlocks.find((subBlock) => subBlock.id === 'prState')
+    expect(
+      evaluateSubBlockCondition(prState?.condition, {
+        mode: 'cloud_branch',
+        babysitMode: true,
+      })
+    ).toBe(false)
+    expect(PiBlock.inputs.prState).toBeDefined()
   })
 })

apps/sim/blocks/blocks/pi.test.ts

@@ -81,6 +81,15 @@ const CLOUD_WITHOUT_BABYSIT: {
   value: 'cloud',
   and: { field: 'babysitMode', value: true, not: true },
 }
+const CLOUD_BRANCH_WITHOUT_BABYSIT: {
+  field: 'mode'
+  value: 'cloud_branch'
+  and: { field: 'babysitMode'; value: true; not: true }
+} = {
+  field: 'mode',
+  value: 'cloud_branch',
+  and: { field: 'babysitMode', value: true, not: true },
+}
 const LOCAL: { field: 'mode'; value: 'local' } = { field: 'mode', value: 'local' }
 const AUTHORING_MODES: {
   field: 'mode'
@@ -127,14 +136,14 @@ export const PiBlock: BlockConfig<PiResponse> = {
   description: 'Run an autonomous coding agent on a repo',
   authMode: AuthMode.ApiKey,
   longDescription:
-    'The Pi Coding Agent runs the Pi harness against a real repository. Create PR opens a new pull request, Update Branch pushes to an existing branch without force-pushing, Review Code posts a structured review, and Local Dev edits files over SSH. Create PR and Update Branch can optionally babysit their pull request through trusted bot reviews and required checks. Authoring modes can reuse skills and conversation memory. Any mode can optionally get one web_search tool backed by your own key.',
+    'The Pi Coding Agent runs the Pi harness against a real repository. Create PR opens a new pull request, Update PR pushes to an existing branch and creates or updates its pull request, Review Code posts a structured review, and Local Dev edits files over SSH. Create PR and Update PR can optionally babysit their pull request through trusted bot reviews and required checks. Authoring modes can reuse skills and conversation memory. Any mode can optionally get one web_search tool backed by your own key.',
   bestPractices: `
   - Use Create PR for hands-off changes against a GitHub repo where a reviewable PR is the deliverable.
-  - Use Update Branch to continue work on an existing remote branch, including one previously created by Pi.
-  - Enable Babysit Mode on Create PR or Update Branch when trusted review bots and required checks should be monitored and fixed in bounded rounds.
+  - Use Update PR to continue work on an existing remote branch and create or update its pull request.
+  - Enable Babysit Mode on Create PR or Update PR when trusted review bots and required checks should be monitored and fixed in bounded rounds.
   - Use Review Code to analyze an existing PR and leave summary + inline review comments.
   - Use Local Dev to edit a repo on your own machine; expose the machine on a public hostname/tunnel so Sim can reach it over SSH.
-  - Create PR and Update Branch require your own provider API key because the model runs in the sandbox. Review Code keeps the model key in Sim and can use either BYOK or a hosted key.
+  - Create PR and Update PR require your own provider API key because the model runs in the sandbox. Review Code keeps the model key in Sim and can use either BYOK or a hosted key.
   - Internet Search is off by default and always needs your own key for the selected provider, from the block field or Settings > BYOK. Leave it on None unless the task genuinely needs external information.
   `,
   category: 'blocks',
@@ -164,9 +173,9 @@ export const PiBlock: BlockConfig<PiResponse> = {
               description: 'Runs in an isolated sandbox, clones your repo, and opens a PR',
             },
             {
-              label: 'Update Branch',
+              label: 'Update PR',
               id: 'cloud_branch',
-              description: 'Checks out an existing branch, makes changes, and pushes commits back',
+              description: 'Updates an existing branch and creates or updates its pull request',
             },
             {
               label: 'Review Code',
@@ -245,7 +254,7 @@ export const PiBlock: BlockConfig<PiResponse> = {
       paramVisibility: 'user-only',
       placeholder: 'GitHub personal access token',
       tooltip:
-        'Personal access token used for GitHub access. Create PR needs clone/push/PR permissions; Update Branch needs clone/push permissions. With Babysit Mode, either also needs pull request, check/Actions read, thread write, and issue comment permissions. Review Code needs clone + review permissions.',
+        'Personal access token used for GitHub access. Create PR and Update PR both need clone, push, and pull request read/write permissions. With Babysit Mode, either also needs check/Actions reads, thread writes, and issue comments. Review Code needs clone + review permissions.',
       required: true,
       condition: CLOUD_ANY,
     },
@@ -254,8 +263,9 @@ export const PiBlock: BlockConfig<PiResponse> = {
       title: 'Base Branch',
       type: 'short-input',
       placeholder: 'e.g., main (defaults to the repository default branch)',
-      tooltip: 'The branch the pull request is opened against; the repo is cloned from it too.',
-      condition: CLOUD,
+      tooltip:
+        'Create PR clones this branch and opens against it. Update PR changes an existing pull request only when set, or uses it when creating a missing pull request.',
+      condition: CLOUD_AUTHORING,
     },
     {
       id: 'targetBranch',
@@ -273,7 +283,7 @@ export const PiBlock: BlockConfig<PiResponse> = {
       type: 'switch',
       defaultValue: false,
       description:
-        'Use the branch PR, request the configured bot reviews, and fix trusted feedback and required checks in bounded rounds.',
+        'Create or update the branch PR, request the configured bot reviews, and fix trusted feedback and required checks in bounded rounds.',
       condition: CLOUD_AUTHORING,
     },
     {
@@ -304,21 +314,36 @@ export const PiBlock: BlockConfig<PiResponse> = {
       mode: 'advanced',
       condition: CLOUD_WITHOUT_BABYSIT,
     },
+    {
+      id: 'prState',
+      title: 'PR State',
+      type: 'dropdown',
+      defaultValue: 'preserve',
+      options: [
+        { label: 'Leave unchanged', id: 'preserve' },
+        { label: 'Draft', id: 'draft' },
+        { label: 'Ready for review', id: 'ready' },
+      ],
+      tooltip:
+        'State for an existing pull request. When a pull request must be created, Leave unchanged uses the Create PR default and opens it as a draft.',
+      mode: 'advanced',
+      condition: CLOUD_BRANCH_WITHOUT_BABYSIT,
+    },
     {
       id: 'prTitle',
       title: 'PR Title',
       type: 'short-input',
-      placeholder: 'Generated from the run when blank',
+      placeholder: 'Generated for a new PR; preserves an existing PR when blank',
       mode: 'advanced',
-      condition: CLOUD,
+      condition: CLOUD_AUTHORING,
     },
     {
       id: 'prBody',
       title: 'PR Body',
       type: 'long-input',
-      placeholder: 'Generated from the run when blank',
+      placeholder: 'Generated for a new PR; preserves an existing PR when blank',
       mode: 'advanced',
-      condition: CLOUD,
+      condition: CLOUD_AUTHORING,
     },
     {
       id: 'pullNumber',
@@ -542,19 +567,23 @@ export const PiBlock: BlockConfig<PiResponse> = {
   inputs: {
     mode: {
       type: 'string',
-      description: 'Execution mode: Create PR, Update Branch, Review Code, or Local Dev',
+      description: 'Execution mode: Create PR, Update PR, Review Code, or Local Dev',
     },
     task: { type: 'string', description: 'Instruction for the coding agent' },
     model: { type: 'string', description: 'AI model to use' },
     owner: { type: 'string', description: 'GitHub repository owner (cloud modes)' },
     repo: { type: 'string', description: 'GitHub repository name (cloud modes)' },
     githubToken: { type: 'string', description: 'GitHub token (cloud modes)' },
-    baseBranch: { type: 'string', description: 'Base branch for the PR (Create PR)' },
+    baseBranch: { type: 'string', description: 'Base branch for the pull request' },
     branchName: { type: 'string', description: 'Branch to create (Create PR)' },
-    targetBranch: { type: 'string', description: 'Existing branch to update (Update Branch)' },
+    targetBranch: { type: 'string', description: 'Existing branch to update (Update PR)' },
     draft: { type: 'boolean', description: 'Open the PR as a draft (Create PR)' },
-    prTitle: { type: 'string', description: 'Pull request title (Create PR)' },
-    prBody: { type: 'string', description: 'Pull request body (Create PR)' },
+    prTitle: { type: 'string', description: 'Pull request title' },
+    prBody: { type: 'string', description: 'Pull request body' },
+    prState: {
+      type: 'string',
+      description: 'Existing pull request state: preserve, draft, or ready (Update PR)',
+    },
     babysitMode: {
       type: 'boolean',
       description: 'Babysit trusted bot reviews and required checks after authoring',

apps/sim/blocks/blocks/pi.ts

@@ -115,13 +115,19 @@ export interface PiCloudBabysitOptions {
   executionId?: string
 }
 
-/** Parameters for a cloud (E2B) Pi run that updates an existing branch. */
+export type PiPullRequestState = 'preserve' | 'draft' | 'ready'
+
+/** Parameters for a cloud (E2B) Pi run that updates an existing branch and its pull request. */
 export interface PiCloudBranchRunParams extends PiContextualRunParams {
   mode: 'cloud_branch'
   owner: string
   repo: string
   githubToken: string
   targetBranch: string
+  baseBranch?: string
+  prTitle?: string
+  prBody?: string
+  prState: PiPullRequestState
   babysit?: PiCloudBabysitOptions
 }