feat(pi): add update branch mode

Author: Bill Leoutsakos

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

@@ -14,6 +14,8 @@ import { PI_SEARCH_PROVIDERS } from '@/executor/handlers/pi/keys'
 
 const searchProviderField = PiBlock.subBlocks.find((subBlock) => subBlock.id === 'searchProvider')
 const searchApiKeyField = PiBlock.subBlocks.find((subBlock) => subBlock.id === 'searchApiKey')
+const targetBranchField = PiBlock.subBlocks.find((subBlock) => subBlock.id === 'targetBranch')
+const modeField = PiBlock.subBlocks.find((subBlock) => subBlock.id === 'mode')
 
 function searchKeyVisible(values: Record<string, unknown>): boolean {
   return evaluateSubBlockCondition(searchApiKeyField?.condition, values)
@@ -75,3 +77,73 @@ describe('Pi block search fields', () => {
     expect(PiBlock.inputs.searchApiKey).toBeDefined()
   })
 })
+
+describe('Pi Update Branch fields', () => {
+  it('offers Update Branch with the other cloud modes when E2B is enabled', () => {
+    const original = process.env.NEXT_PUBLIC_E2B_ENABLED
+    process.env.NEXT_PUBLIC_E2B_ENABLED = 'true'
+    try {
+      const options =
+        typeof modeField?.options === 'function' ? modeField.options() : modeField?.options
+      expect(options).toContainEqual({
+        label: 'Update Branch',
+        id: 'cloud_branch',
+        description: 'Checks out an existing branch, makes changes, and pushes commits back',
+      })
+    } finally {
+      if (original === undefined) Reflect.deleteProperty(process.env, 'NEXT_PUBLIC_E2B_ENABLED')
+      else process.env.NEXT_PUBLIC_E2B_ENABLED = original
+    }
+  })
+
+  it('requires the target branch only in Update Branch mode', () => {
+    expect(targetBranchField?.type).toBe('short-input')
+    expect(targetBranchField?.required).toBe(true)
+    expect(evaluateSubBlockCondition(targetBranchField?.condition, { mode: 'cloud_branch' })).toBe(
+      true
+    )
+    expect(evaluateSubBlockCondition(targetBranchField?.condition, { mode: 'cloud' })).toBe(false)
+    expect(evaluateSubBlockCondition(targetBranchField?.condition, { mode: 'cloud_review' })).toBe(
+      false
+    )
+    expect(evaluateSubBlockCondition(targetBranchField?.condition, { mode: 'local' })).toBe(false)
+  })
+
+  it('declares the target branch input and branch output for cloud authoring modes', () => {
+    expect(PiBlock.inputs.targetBranch).toBeDefined()
+    expect(
+      evaluateSubBlockCondition(PiBlock.outputs.branch.condition, { mode: 'cloud_branch' })
+    ).toBe(true)
+    expect(evaluateSubBlockCondition(PiBlock.outputs.branch.condition, { mode: 'cloud' })).toBe(
+      true
+    )
+    expect(
+      evaluateSubBlockCondition(PiBlock.outputs.branch.condition, { mode: 'cloud_review' })
+    ).toBe(false)
+  })
+
+  it('reuses skills and memory fields, including their dependent controls', () => {
+    for (const id of [
+      'skills',
+      'memoryType',
+      'conversationId',
+      'slidingWindowSize',
+      'slidingWindowTokens',
+    ]) {
+      const field = PiBlock.subBlocks.find((subBlock) => subBlock.id === id)
+      expect(
+        evaluateSubBlockCondition(field?.condition, {
+          mode: 'cloud_branch',
+          memoryType: id === 'slidingWindowTokens' ? 'sliding_window_tokens' : 'sliding_window',
+        })
+      ).toBe(true)
+    }
+  })
+
+  it('hides Create PR and Review Code-specific fields', () => {
+    for (const id of ['baseBranch', 'branchName', 'draft', 'prTitle', 'prBody', 'pullNumber']) {
+      const field = PiBlock.subBlocks.find((subBlock) => subBlock.id === id)
+      expect(evaluateSubBlockCondition(field?.condition, { mode: 'cloud_branch' })).toBe(false)
+    }
+  })
+})

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

@@ -42,14 +42,28 @@ const CLOUD_REVIEW: { field: 'mode'; value: 'cloud_review' } = {
   field: 'mode',
   value: 'cloud_review',
 }
-const CLOUD_ANY: { field: 'mode'; value: Array<'cloud' | 'cloud_review'> } = {
+const CLOUD_BRANCH: { field: 'mode'; value: 'cloud_branch' } = {
   field: 'mode',
-  value: ['cloud', 'cloud_review'],
+  value: 'cloud_branch',
+}
+const CLOUD_ANY: {
+  field: 'mode'
+  value: Array<'cloud' | 'cloud_branch' | 'cloud_review'>
+} = {
+  field: 'mode',
+  value: ['cloud', 'cloud_branch', 'cloud_review'],
+}
+const CLOUD_AUTHORING: { field: 'mode'; value: Array<'cloud' | 'cloud_branch'> } = {
+  field: 'mode',
+  value: ['cloud', 'cloud_branch'],
 }
 const LOCAL: { field: 'mode'; value: 'local' } = { field: 'mode', value: 'local' }
-const AUTHORING_MODES: { field: 'mode'; value: Array<'cloud' | 'local'> } = {
+const AUTHORING_MODES: {
+  field: 'mode'
+  value: Array<'cloud' | 'cloud_branch' | 'local'>
+} = {
   field: 'mode',
-  value: ['cloud', 'local'],
+  value: ['cloud', 'cloud_branch', 'local'],
 }
 const MEMORY_TYPES = ['conversation', 'sliding_window', 'sliding_window_tokens']
 
@@ -85,12 +99,13 @@ 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 spins up an isolated sandbox, clones a GitHub repo, edits with native shell + git, and opens a pull request. Review Code checks out a pinned PR snapshot with read-only tools and posts a structured review with optional inline comments. Local Dev edits files on your own machine over SSH. Create PR and Local Dev can reuse skills and multi-turn memory; Review Code runs without either because PR contents are untrusted. Any mode can optionally get one web_search tool backed by your own Exa, Serper, Parallel AI, or Firecrawl key; the agent writes its own queries, so repository content may reach the provider, and results are untrusted third-party data.',
+    'The Pi Coding Agent runs the Pi harness against a real repository. Create PR spins up an isolated sandbox, clones a GitHub repo, edits with native shell + git, and opens a pull request. Update Branch checks out an existing branch and pushes the agent’s changes back to it without force-pushing. Review Code checks out a pinned PR snapshot with read-only tools and posts a structured review with optional inline comments. Local Dev edits files on your own machine over SSH. Create PR, Update Branch, and Local Dev can reuse skills and multi-turn memory; Review Code runs without either because PR contents are untrusted. Any mode can optionally get one web_search tool backed by your own Exa, Serper, Parallel AI, or Firecrawl key; the agent writes its own queries, so repository content may reach the provider, and results are untrusted third-party data.',
   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.
   - 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 requires 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 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.
   - Internet Search is off by default and always needs your own key for the selected provider, entered on the block. There is no workspace BYOK fallback and no hosted key. Leave it on None unless the task genuinely needs external information.
   `,
   category: 'blocks',
@@ -102,7 +117,7 @@ export const PiBlock: BlockConfig<PiResponse> = {
       id: 'mode',
       title: 'Mode',
       type: 'dropdown',
-      /** Create PR and Review Code require E2B and stay hidden when it is disabled. */
+      /** Cloud modes require E2B and stay hidden when it is disabled. */
       value: () => (isTruthy(getEnv('NEXT_PUBLIC_E2B_ENABLED')) ? 'cloud' : 'local'),
       options: () => {
         const options = [
@@ -119,6 +134,11 @@ export const PiBlock: BlockConfig<PiResponse> = {
               id: 'cloud',
               description: 'Runs in an isolated sandbox, clones your repo, and opens a PR',
             },
+            {
+              label: 'Update Branch',
+              id: 'cloud_branch',
+              description: 'Checks out an existing branch, makes changes, and pushes commits back',
+            },
             {
               label: 'Review Code',
               id: 'cloud_review',
@@ -156,7 +176,7 @@ export const PiBlock: BlockConfig<PiResponse> = {
       defaultValue: 'none',
       options: SEARCH_PROVIDER_OPTIONS,
       tooltip:
-        'Gives the agent a single web_search tool backed by the selected provider. Search always uses your own key for that provider, never a Sim-hosted one, because Create PR places the key inside the coding sandbox.',
+        'Gives the agent a single web_search tool backed by the selected provider. Search always uses your own key for that provider, never a Sim-hosted one, because cloud authoring places the key inside the coding sandbox.',
     },
     {
       id: 'searchApiKey',
@@ -204,7 +224,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; Review Code needs clone + review permissions.',
+        'Personal access token used for GitHub access. Create PR needs clone/push/PR permissions; Update Branch needs clone/push permissions; Review Code needs clone + review permissions.',
       required: true,
       condition: CLOUD_ANY,
     },
@@ -216,6 +236,16 @@ export const PiBlock: BlockConfig<PiResponse> = {
       tooltip: 'The branch the pull request is opened against; the repo is cloned from it too.',
       condition: CLOUD,
     },
+    {
+      id: 'targetBranch',
+      title: 'Target Branch',
+      type: 'short-input',
+      placeholder: 'e.g., feature/add-auth',
+      tooltip:
+        'Existing remote branch to update. The run never force-pushes and fails if the branch does not exist or changes while Pi is running.',
+      required: true,
+      condition: CLOUD_BRANCH,
+    },
     {
       id: 'branchName',
       title: 'Branch Name',
@@ -417,12 +447,12 @@ export const PiBlock: BlockConfig<PiResponse> = {
       mode: 'advanced',
       required: {
         field: 'mode',
-        value: ['cloud', 'local'],
+        value: ['cloud', 'cloud_branch', 'local'],
         and: { field: 'memoryType', value: MEMORY_TYPES },
       },
       condition: {
         field: 'mode',
-        value: ['cloud', 'local'],
+        value: ['cloud', 'cloud_branch', 'local'],
         and: { field: 'memoryType', value: MEMORY_TYPES },
       },
       dependsOn: ['memoryType'],
@@ -435,7 +465,7 @@ export const PiBlock: BlockConfig<PiResponse> = {
       mode: 'advanced',
       condition: {
         field: 'mode',
-        value: ['cloud', 'local'],
+        value: ['cloud', 'cloud_branch', 'local'],
         and: { field: 'memoryType', value: ['sliding_window'] },
       },
       dependsOn: ['memoryType'],
@@ -448,7 +478,7 @@ export const PiBlock: BlockConfig<PiResponse> = {
       mode: 'advanced',
       condition: {
         field: 'mode',
-        value: ['cloud', 'local'],
+        value: ['cloud', 'cloud_branch', 'local'],
         and: { field: 'memoryType', value: ['sliding_window_tokens'] },
       },
       dependsOn: ['memoryType'],
@@ -460,15 +490,16 @@ export const PiBlock: BlockConfig<PiResponse> = {
   inputs: {
     mode: {
       type: 'string',
-      description: 'Execution mode: Create PR, Review Code, or Local Dev',
+      description: 'Execution mode: Create PR, Update Branch, 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 (Create PR and Review Code)' },
-    repo: { type: 'string', description: 'GitHub repository name (Create PR and Review Code)' },
-    githubToken: { type: 'string', description: 'GitHub token (Create PR and Review Code)' },
+    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)' },
     branchName: { type: 'string', description: 'Branch to create (Create PR)' },
+    targetBranch: { type: 'string', description: 'Existing branch to update (Update Branch)' },
     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)' },
@@ -512,7 +543,7 @@ export const PiBlock: BlockConfig<PiResponse> = {
     branch: {
       type: 'string',
       description: 'Branch pushed with the changes',
-      condition: CLOUD,
+      condition: CLOUD_AUTHORING,
     },
     reviewUrl: {
       type: 'string',

apps/sim/blocks/blocks/pi.ts

@@ -105,6 +105,15 @@ export interface PiCloudRunParams extends PiContextualRunParams {
   prBody?: string
 }
 
+/** Parameters for a cloud (E2B) Pi run that updates an existing branch. */
+export interface PiCloudBranchRunParams extends PiContextualRunParams {
+  mode: 'cloud_branch'
+  owner: string
+  repo: string
+  githubToken: string
+  targetBranch: string
+}
+
 /** Parameters for a cloud (E2B) Pi run that reviews an existing PR. */
 export interface PiCloudReviewRunParams extends PiRunBaseParams {
   mode: 'cloud_review'
@@ -115,7 +124,11 @@ export interface PiCloudReviewRunParams extends PiRunBaseParams {
   reviewEvent: 'COMMENT' | 'REQUEST_CHANGES'
 }
 
-export type PiRunParams = PiLocalRunParams | PiCloudRunParams | PiCloudReviewRunParams
+export type PiRunParams =
+  | PiLocalRunParams
+  | PiCloudRunParams
+  | PiCloudBranchRunParams
+  | PiCloudReviewRunParams
 
 /** Progress callbacks and cancellation passed into a backend run. */
 export interface PiRunContext {