simstudioai
diff --git a/‎apps/docs/content/docs/en/workflows/blocks/pi.mdx‎
Lines changed: 19 additions & 1 deletion b/‎apps/docs/content/docs/en/workflows/blocks/pi.mdx‎
Lines changed: 19 additions & 1 deletion
diff --git a/‎apps/sim/blocks/blocks/pi.test.ts‎
Lines changed: 77 additions & 0 deletions b/‎apps/sim/blocks/blocks/pi.test.ts‎
Lines changed: 77 additions & 0 deletions
diff --git a/‎apps/sim/blocks/blocks/pi.ts‎
Lines changed: 64 additions & 1 deletion b/‎apps/sim/blocks/blocks/pi.ts‎
Lines changed: 64 additions & 1 deletion
diff --git a/‎apps/sim/executor/handlers/pi/backend.ts‎
Lines changed: 21 additions & 0 deletions b/‎apps/sim/executor/handlers/pi/backend.ts‎
Lines changed: 21 additions & 0 deletions
@@ -4,6 +4,7 @@ description: The Pi Coding Agent block runs an autonomous coding agent on a real
 pageType: reference
 ---
 
+import { Callout } from 'fumadocs-ui/components/callout'
 import { BlockPreview } from '@/components/workflow-preview'
 import { FAQ } from '@/components/ui/faq'
 
@@ -37,7 +38,7 @@ Review Code uses a disposable sandbox for the repository, but the Pi harness and
 - Requires sandbox execution. The provider key stays in Sim, so hosted keys and BYOK are both supported.
 - Needs a **GitHub token** that can clone the repo and submit reviews (see [Setup](#setup-cloud-code-review)).
 - Needs the **Pull Request Number** to review.
-- Does not load skills or memory, and never exposes shell, write, edit, or arbitrary network tools to the reviewer.
+- Does not load skills or memory, and never exposes shell, write, or edit tools to the reviewer. Its only network access is [Internet Search](#internet-search), and only when you select a provider.
 - Rechecks the PR immediately before submission and pins the review to the exact checked-out head commit.
 - The deliverable is a **submitted review** — read `reviewUrl` and `commentsPosted`.
 
@@ -63,6 +64,22 @@ The model that drives the agent. Defaults to `claude-sonnet-4-6`. The dropdown c
 
 Your key for the chosen provider. On hosted Sim it is optional for Local Dev and Review Code runs (a hosted key is used and metered to your workspace). **Create PR requires your own key** because its model client runs in the sandbox. When the provider supports workspace BYOK, you can store the key in **Settings → BYOK** instead of entering it on the block.
 
+### Internet Search
+
+Off by default. Pick a provider — **Exa**, **Serper**, **Parallel AI**, or **Firecrawl** — and the agent gains a single `web_search` tool that returns a handful of results, each with a title, URL, snippet, and (where the provider reports one) a publication date. It works the same way in all three modes, and it is the agent's only network access in Review Code. The tool accepts at most 20 calls **per block execution**, which bounds accidental tool loops. A Pi block inside a Loop or Parallel gets that allowance again on every iteration, so bound the iteration count too if you care about what a single workflow run can spend.
+
+Search always uses **your own key** for the selected provider, entered in the block's **Search API Key** field. That field is the only source: there is no workspace BYOK fallback and Sim never supplies a hosted search key, so unlike the model key this field appears on every deployment. Leave it empty and the run fails with a setup error before any sandbox is created. Changing the provider in the editor clears the field, so re-enter the key that belongs to the provider you picked — a workflow you import, fork, or update through the API keeps whatever key was saved, so check it there.
+
+<Callout type="warn">
+  **Create PR exposes both keys to the agent.** Create PR runs the model client and the search client *inside* the sandbox, so the model key and the search key reach it as environment variables — and Pi copies its own environment into every shell command it runs. Your prompt, or instructions injected through the contents of the cloned repository, can therefore read either key and write it anywhere the agent can reach, including into the pull request itself. Sim strips verbatim key text out of run output, but that does not stop an agent that encodes the value first.
+
+  This is why the search key has no **Settings → BYOK** fallback. Workspace BYOK keys belong to the workspace rather than to you — Sim only ever displays them masked, and only workspace admins can add or remove them — so resolving one here would let anyone who can run a Pi block read a credential they cannot otherwise see. Requiring the key on the block keeps the exposure to a key its author already holds. Scope it to something you are willing to rotate.
+</Callout>
+
+Results are third-party data. The agent is instructed to treat them as quoted evidence and never to follow instructions found inside them — the same posture Pi takes toward repository contents.
+
+Traffic goes both ways: the agent writes its own queries after reading the repository, so leave search on **None** in Review Code when the pull request comes from an untrusted fork of a private repo. Injected instructions in a diff could otherwise put repository text into a query sent to the provider.
+
 ### Repository (Create PR / Review Code)
 
 - **Repository Owner / Repository Name** — the GitHub repo (for example `your-org` / `your-repo`).
@@ -176,6 +193,7 @@ Enable sandbox execution as for Create PR. BYOK is optional because the model cr
   { question: "Why does Local Dev need a public hostname?", answer: "Sim connects over raw SSH and blocks localhost, LAN, and private/reserved addresses for safety. Expose the machine with a TCP tunnel such as `ngrok tcp 22` and use the tunnel's host and port. Tailscale's private 100.x addresses won't work for the same reason." },
   { question: "What GitHub permissions does Create PR need?", answer: "A token that can clone, push, and open a PR. With a fine-grained token: select the repo and grant Contents: Read and write plus Pull requests: Read and write. With a classic token: the repo scope. For organization repos, the token must be SSO-authorized." },
   { question: "What GitHub permissions does Review Code need?", answer: "A token that can clone the repo and submit a review. With a fine-grained token: Contents: Read plus Pull requests: Read and write. Push permission is not required. With a classic token: the repo scope. For organization repos, the token must be SSO-authorized." },
+  { question: "Can the agent search the web?", answer: "Only if you pick a provider under Internet Search — Exa, Serper, Parallel AI, or Firecrawl. That adds one web_search tool in every mode, backed by your own key for that provider, entered on the block; there is no BYOK fallback and Sim never supplies a search key. Leave it on None and the agent has no search tool at all." },
   { question: "Can I give it Gmail, Slack, or other integrations?", answer: "Yes, in Local Dev via the Tools field. Selected Sim tools run through Sim with your connected credentials, the same as the Agent block, so the agent can act beyond the repo while it codes. MCP and custom tools aren't supported yet." },
   { question: "Where do the changes or feedback go?", answer: "In Create PR, to a new branch and a pull request (read prUrl and branch). In Review Code, to a submitted GitHub review on the existing PR (read reviewUrl and commentsPosted). In Local Dev, the files are edited in place on the target machine — review them with git there. Create PR and Local Dev also return changedFiles and a diff." },
   { question: "What happens when memory or context gets large?", answer: "For Create PR and Local Dev, Sim trims memory before the run based on the memory type, and Pi compacts older turns as needed. Review Code does not load or save memory because a malicious PR could otherwise expose or poison prior context." },
 
@@ -0,0 +1,77 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it, vi } from 'vitest'
+
+// The registry lives server-side (`keys.ts` reaches BYOK, which reaches the database) and the block
+// deliberately does not import it — no block imports from `@/executor`. This test is what ties the
+// two copies together, so adding a provider to one and not the other fails here.
+vi.mock('@/lib/api-key/byok', () => ({ getBYOKKey: vi.fn(), getApiKeyWithBYOK: vi.fn() }))
+
+import { evaluateSubBlockCondition } from '@/lib/workflows/subblocks/visibility'
+import { PiBlock } from '@/blocks/blocks/pi'
+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')
+
+function searchKeyVisible(values: Record<string, unknown>): boolean {
+  return evaluateSubBlockCondition(searchApiKeyField?.condition, values)
+}
+
+describe('Pi block search fields', () => {
+  it('offers None plus exactly the providers the resolver knows, defaulting to None', () => {
+    expect(searchProviderField?.type).toBe('dropdown')
+    expect(searchProviderField?.defaultValue).toBe('none')
+
+    const options = searchProviderField?.options as { id: string; label: string }[]
+    expect(options.map(({ id }) => id)).toEqual(['none', ...Object.keys(PI_SEARCH_PROVIDERS)])
+    // Labels too: a mismatch here means the dropdown names a provider differently from the setup
+    // error the run fails with.
+    expect(options.slice(1).map(({ label }) => label)).toEqual(
+      Object.values(PI_SEARCH_PROVIDERS).map(({ label }) => label)
+    )
+  })
+
+  // The same handling this block already gives githubToken, password, and privateKey.
+  it('keeps the search key out of connections, references, and plain text', () => {
+    expect(searchApiKeyField?.password).toBe(true)
+    expect(searchApiKeyField?.paramVisibility).toBe('user-only')
+    expect(searchApiKeyField?.connectionDroppable).toBe(false)
+  })
+
+  it('declares the key as dependent on the provider, which is what clears it in the editor', () => {
+    expect(searchApiKeyField?.dependsOn).toEqual(['searchProvider'])
+  })
+
+  it('shows the key field only once a provider is selected', () => {
+    expect(searchKeyVisible({ searchProvider: 'exa' })).toBe(true)
+    expect(searchKeyVisible({ searchProvider: 'firecrawl' })).toBe(true)
+    expect(searchKeyVisible({ searchProvider: 'none' })).toBe(false)
+    expect(searchKeyVisible({ searchProvider: '' })).toBe(false)
+  })
+
+  // A Pi block saved before this field existed has no stored value, and the serializer does not
+  // inject subBlock defaults — so `undefined` has to behave like None here too.
+  it('hides the key field on blocks saved before the field existed', () => {
+    expect(searchKeyVisible({})).toBe(false)
+    expect(searchKeyVisible({ searchProvider: undefined })).toBe(false)
+  })
+
+  // The field is the only source for the search key — no workspace BYOK fallback, no hosted key —
+  // so it has to be required. Safe despite the condition: the serializer's required check returns
+  // early for fields that are not visible, which is what keeps a Pi block with search off from
+  // failing validation over a key it does not need.
+  it('requires the key, which the hidden case must not enforce', () => {
+    expect(searchApiKeyField?.required).toBe(true)
+    expect(searchKeyVisible({ searchProvider: 'none' })).toBe(false)
+    expect(searchKeyVisible({})).toBe(false)
+  })
+
+  // `inputs` is the block's type map, not the delivery mechanism — the handler reads resolved
+  // params — but an undeclared input is a convention break the next block author would copy.
+  it('declares both fields in the block input map', () => {
+    expect(PiBlock.inputs.searchProvider).toBeDefined()
+    expect(PiBlock.inputs.searchApiKey).toBeDefined()
+  })
+})
@@ -53,18 +53,45 @@ const AUTHORING_MODES: { field: 'mode'; value: Array<'cloud' | 'local'> } = {
 }
 const MEMORY_TYPES = ['conversation', 'sliding_window', 'sliding_window_tokens']
 
+const SEARCH_PROVIDER_OPTIONS = [
+  { label: 'None', id: 'none' },
+  { label: 'Exa', id: 'exa' },
+  { label: 'Serper', id: 'serper' },
+  { label: 'Parallel AI', id: 'parallel' },
+  { label: 'Firecrawl', id: 'firecrawl' },
+]
+
+/**
+ * Mirrors `getApiKeyCondition()` for the model key: the search key's visibility is computed rather
+ * than declarative. The never-matching sentinel is how `buildModelVisibilityCondition` hides the
+ * model key when nothing is selected, and it is what keeps the field hidden on a block saved before
+ * this field existed — such a block has no stored `searchProvider`, and the declarative negative
+ * form would show the field, because a scalar `not` condition evaluates `undefined !== 'none'` as
+ * true.
+ */
+function getSearchApiKeyCondition() {
+  return (values?: Record<string, unknown>) => {
+    const provider = typeof values?.searchProvider === 'string' ? values.searchProvider : ''
+    if (!provider || provider === 'none') {
+      return { field: 'searchProvider', value: '__no_search_provider__' }
+    }
+    return { field: 'searchProvider', value: provider }
+  }
+}
+
 export const PiBlock: BlockConfig<PiResponse> = {
   type: 'pi',
   name: 'Pi Coding Agent',
   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.',
+    '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.',
   bestPractices: `
   - Use Create PR for hands-off changes against a GitHub repo where a reviewable PR is the deliverable.
   - 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.
+  - 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',
   integrationType: IntegrationType.AI,
@@ -122,6 +149,37 @@ export const PiBlock: BlockConfig<PiResponse> = {
 
     ...getProviderCredentialSubBlocks(),
 
+    {
+      id: 'searchProvider',
+      title: 'Internet Search',
+      type: 'dropdown',
+      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.',
+    },
+    {
+      id: 'searchApiKey',
+      title: 'Search API Key',
+      type: 'short-input',
+      password: true,
+      paramVisibility: 'user-only',
+      connectionDroppable: false,
+      placeholder: 'Your key for the selected provider',
+      // The only source: search has no workspace BYOK fallback and never uses a Sim-hosted key, and
+      // unlike the model key this field is shown on every deployment. Marking it required is what
+      // surfaces that in the editor rather than at the start of a run.
+      required: true,
+      // Scoped to the editor on purpose: the clear-on-switch is driven by `dependsOn` through the
+      // collaborative setter, so a workflow imported, forked, or updated through the API keeps
+      // whatever key was stored. Promising an unconditional clear would be wrong in exactly the
+      // case where sending the previous provider's key to a new vendor actually matters.
+      tooltip:
+        'Key for the selected search provider. Changing the provider in the editor clears this field, so re-enter the key for the one you picked. Imported or API-updated workflows keep the saved key — check it belongs to the selected provider.',
+      condition: getSearchApiKeyCondition(),
+      dependsOn: ['searchProvider'],
+    },
+
     {
       id: 'owner',
       title: 'Repository Owner',
@@ -434,6 +492,11 @@ export const PiBlock: BlockConfig<PiResponse> = {
     conversationId: { type: 'string', description: 'Conversation ID for memory' },
     slidingWindowSize: { type: 'string', description: 'Number of messages for sliding window' },
     slidingWindowTokens: { type: 'string', description: 'Max tokens for token-based window' },
+    searchProvider: {
+      type: 'string',
+      description: 'Web search provider for the agent: none, exa, serper, parallel, or firecrawl',
+    },
+    searchApiKey: { type: 'string', description: 'API key for the selected search provider' },
     ...PROVIDER_CREDENTIAL_INPUTS,
   },
   outputs: {
 
@@ -11,6 +11,7 @@ import type { TSchema } from 'typebox'
 import type { SSHConnectionConfig } from '@/app/api/tools/ssh/utils'
 import type { Message } from '@/executor/handlers/agent/types'
 import type { PiEvent, PiRunTotals } from '@/executor/handlers/pi/events'
+import type { PiSearchProvider } from '@/executor/handlers/pi/keys'
 import type { PiSupportedProvider } from '@/providers/pi-provider-configs'
 
 /** A conversation message seeded into the Pi run (subset of the Agent block's message). */
@@ -31,6 +32,7 @@ export type PiSshConnection = Pick<
 /** Result of invoking a tool Pi called. */
 export interface PiToolResult {
   text: string
+  /** Reported to Pi by throwing `text` from the converted tool; see `toPiTool` for why. */
   isError: boolean
 }
 
@@ -43,9 +45,27 @@ export interface PiToolSpec {
   name: string
   description: string
   parameters: TSchema
+  /**
+   * Guideline bullets Pi folds into the system prompt while the tool is active. This is the
+   * trusted channel: a `description` travels in the provider request's tool-definition array, so
+   * guidance placed there carries the same trust level as the payload it describes. Dropped in
+   * Review Code, which supplies a sealed `customPrompt` instead.
+   */
+  promptGuidelines?: string[]
   execute: (args: Record<string, unknown>) => Promise<PiToolResult>
 }
 
+/** Optional web search for a Pi run, resolved by the handler before mode dispatch. */
+export interface PiSearchConfig {
+  provider: PiSearchProvider
+  apiKey: string
+  /**
+   * Host-side tool for the two SDK modes. Absent for `cloud`, which has no host in the loop and
+   * registers a sandbox extension instead, so a spec built there could never execute.
+   */
+  tool?: PiToolSpec
+}
+
 interface PiRunBaseParams {
   /** Sim's catalog ID, retained for billing and output. */
   model: string
@@ -56,6 +76,7 @@ interface PiRunBaseParams {
   isBYOK: boolean
   task: string
   thinkingLevel?: string
+  search?: PiSearchConfig
 }
 
 interface PiContextualRunParams extends PiRunBaseParams {