fix(pi): correct search normalization edge cases and the budget's stated scope

Follow-ups from review of the web-search work. Each fix lands in both the host
adapter (`normalize.ts`) and the Create PR sandbox copy (`extension-source.ts`),
with the extension test asserting the two produce byte-identical envelopes.

- `usableUrl` was the one provider-controlled field not whitespace-bounded:
  title/snippet/date all go through `collapseWhitespace`, `url` only trimmed.
  Up to 2048 chars of newlines and control characters could ride into the
  envelope. Dropped rather than collapsed — `url` must stay byte-exact to stay
  resolvable, so collapsing would emit a different, still-dead link, and a URL
  carrying raw whitespace is already malformed under RFC 3986.

- `numResults: null` (or `''`, or `[]`) returned 1 result, not the documented
  default of 5: `Number(null)` is a finite 0, so the clamp floor won rather
  than the default. Only a real number or a non-blank numeric string now counts
  as the model having asked for a count.

- Envelope truncation was silent. When results were dropped to fit the 50 KB
  ceiling the model read the short list as the complete answer. It now carries
  a message saying so, and the message is inside what gets measured so the note
  cannot push a truncated envelope back over the ceiling.

- The budget is per *block execution*, not per workflow run: the counter lives
  in the tool spec and both adapters build a fresh one per execution, so a Pi
  block inside a Loop gets the full allowance every iteration. The constant,
  the agent-facing message, and the docs all claimed "per run". Renamed to
  `PI_SEARCH_MAX_CALLS_PER_EXECUTION` and corrected the wording rather than
  tightening the cap, since a shared ceiling would fail late iterations of a
  legitimate fan-out.

- The Search API Key tooltip promised "switching providers clears this field".
  That clear is driven through the collaborative editor setter, so a workflow
  imported, forked, or updated via the API keeps the previous provider's key —
  exactly the case where sending it to a new vendor matters.

Docs also gain a warning that Create PR hands both the model key and the search
key to the agent as environment variables, which Pi copies into every bash
child. That matters most for Settings > BYOK keys: those are workspace-scoped,
only admins can manage them, and the API only ever returns them masked — yet
anyone who can run a Pi block in Create PR mode can read the raw value.

Author: icecrasher321

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

@@ -65,9 +65,15 @@ Your key for the chosen provider. On hosted Sim it is optional for Local Dev and
 
 ### 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 run, which bounds accidental tool loops and the quota one run can consume.
+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, never a Sim-hosted one, because Create PR places the key inside the coding sandbox. Enter it in **Search API Key** or store it in **Settings → BYOK**; the run fails with a setup error before any sandbox is created when neither is present. Switching providers clears the key field in the editor, so re-enter the key that belongs to the provider you picked.
+Search always uses **your own key** for the selected provider, never a Sim-hosted one, because Create PR places the key inside the coding sandbox. Enter it in **Search API Key** or store it in **Settings → BYOK**; the run fails with a setup error before any sandbox is created when neither is present. Changing the provider in the editor clears the key 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 matters most for keys stored in **Settings → BYOK**, which belong to the workspace rather than to you. Sim otherwise only ever displays those masked, and only workspace admins can add or remove them — but anyone who can run a Pi block in Create PR mode can read the raw value. When that is not acceptable for a given key, put a separate key on the block's own **Search API Key** field instead of relying on the BYOK fallback, and 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.
 

apps/sim/blocks/blocks/pi.ts

@@ -166,8 +166,12 @@ export const PiBlock: BlockConfig<PiResponse> = {
       paramVisibility: 'user-only',
       connectionDroppable: false,
       placeholder: 'Falls back to the key stored in Settings > BYOK',
+      // 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. Switching providers clears this field, so re-enter the key for the provider you picked.',
+        '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'],
     },

apps/sim/executor/handlers/pi/cloud-review-tools.ts

@@ -16,7 +16,8 @@ const REVIEW_TOOLS_COMMAND = `python3 ${REVIEW_TOOLS_SCRIPT_PATH}`
 const REVIEW_TOOL_TIMEOUT_MS = 30_000
 /**
  * Both ceilings bound `runOperation`, i.e. sandbox traffic only. Optional web search is registered
- * separately by the review backend and counts against its own `PI_SEARCH_MAX_CALLS_PER_RUN` instead.
+ * separately by the review backend and counts against its own
+ * `PI_SEARCH_MAX_CALLS_PER_EXECUTION` instead.
  */
 const MAX_TOOL_CALLS = 200
 const MAX_TOOL_OUTPUT_BYTES = 5_000_000

apps/sim/executor/handlers/pi/search/extension-source.test.ts

@@ -22,9 +22,13 @@ import {
   extractPiSearchRecords,
   normalizePiSearchRecords,
   PI_SEARCH_BUDGET_MESSAGE,
-  PI_SEARCH_MAX_CALLS_PER_RUN,
+  PI_SEARCH_DEFAULT_RESULTS,
+  PI_SEARCH_MAX_CALLS_PER_EXECUTION,
+  PI_SEARCH_MAX_SNIPPET_LENGTH,
+  PI_SEARCH_MAX_TITLE_LENGTH,
   PI_SEARCH_TIMEOUT_MS,
   PI_SEARCH_TOOL_NAME,
+  PI_SEARCH_TRUNCATED_MESSAGE,
   serializePiSearchEnvelope,
 } from '@/executor/handlers/pi/search/normalize'
 
@@ -182,19 +186,19 @@ describe('provider requests', () => {
     expect(fetchMock).not.toHaveBeenCalled()
   })
 
-  it('enforces the same per-run budget as the host adapter, per extension load', async () => {
+  it('enforces the same per-execution budget as the host adapter, per extension load', async () => {
     // A fresh Response per call: a body stream can only be read once.
     fetchMock.mockImplementation(() => jsonResponse({ results: [] }))
     const tool = register('exa')
 
-    for (let call = 0; call < PI_SEARCH_MAX_CALLS_PER_RUN; call++) {
+    for (let call = 0; call < PI_SEARCH_MAX_CALLS_PER_EXECUTION; call++) {
       await tool.execute('call-1', { query: `pi ${call}` })
     }
 
     await expect(tool.execute('call-1', { query: 'one too many' })).rejects.toThrow(
       PI_SEARCH_BUDGET_MESSAGE
     )
-    expect(fetchMock).toHaveBeenCalledTimes(PI_SEARCH_MAX_CALLS_PER_RUN)
+    expect(fetchMock).toHaveBeenCalledTimes(PI_SEARCH_MAX_CALLS_PER_EXECUTION)
     // A fresh load is a fresh sandbox run, so the count starts over.
     await expect(register('exa').execute('call-1', { query: 'fresh run' })).resolves.toBeDefined()
   })
@@ -286,6 +290,50 @@ describe('normalization parity with the host adapter', () => {
     const result = await register('firecrawl').execute('call-1', { query: 'pi' })
     expect(JSON.parse(result.content[0].text).results).toHaveLength(1)
   })
+
+  // `url` is dropped rather than whitespace-collapsed in both copies; a divergence here would let
+  // the sandbox hand the agent a link the host modes would have refused.
+  it('drops links carrying whitespace or control characters, as the host adapter does', async () => {
+    const records = [
+      { title: 'Space', url: 'https://example.com/a b' },
+      { title: 'Newline', url: 'https://example.com/a\nb' },
+      { title: 'Nul', url: 'https://example.com/a\u0000b' },
+      { title: 'Del', url: 'https://example.com/a\u007fb' },
+      { title: 'Kept', url: 'https://example.com/a-b_c%20d' },
+    ]
+    fetchMock.mockResolvedValue(jsonResponse({ results: records }))
+
+    const result = await register('exa').execute('call-1', { query: 'pi', numResults: 10 })
+    expect(result.content[0].text).toBe(
+      serializePiSearchEnvelope(normalizePiSearchRecords('exa', records, 10))
+    )
+    expect(JSON.parse(result.content[0].text).results).toHaveLength(1)
+  })
+
+  it('treats a blank result count as absent, as the host adapter does', async () => {
+    fetchMock.mockResolvedValue(jsonResponse({ results: [] }))
+
+    await register('exa').execute('call-1', { query: 'pi', numResults: null })
+    expect(JSON.parse(fetchMock.mock.calls[0][1].body).numResults).toBe(PI_SEARCH_DEFAULT_RESULTS)
+  })
+
+  it('says so when results were dropped to fit the envelope, as the host adapter does', async () => {
+    const records = Array.from({ length: 10 }, (_, i) => ({
+      title: '\u898b'.repeat(PI_SEARCH_MAX_TITLE_LENGTH),
+      url: `https://example.com/${i}?${'q'.repeat(1500)}`,
+      text: '\u6f22'.repeat(PI_SEARCH_MAX_SNIPPET_LENGTH),
+    }))
+    fetchMock.mockResolvedValue(jsonResponse({ results: records }))
+
+    const result = await register('exa').execute('call-1', { query: 'pi', numResults: 10 })
+    const parsed = JSON.parse(result.content[0].text)
+
+    expect(parsed.results.length).toBeLessThan(records.length)
+    expect(parsed.message).toBe(PI_SEARCH_TRUNCATED_MESSAGE)
+    expect(result.content[0].text).toBe(
+      serializePiSearchEnvelope(normalizePiSearchRecords('exa', records, 10))
+    )
+  })
 })
 
 describe('failure handling', () => {

apps/sim/executor/handlers/pi/search/extension-source.ts

@@ -16,7 +16,7 @@ import {
   EXA_MAX_TEXT_CHARACTERS,
   PI_SEARCH_BUDGET_MESSAGE,
   PI_SEARCH_DEFAULT_RESULTS,
-  PI_SEARCH_MAX_CALLS_PER_RUN,
+  PI_SEARCH_MAX_CALLS_PER_EXECUTION,
   PI_SEARCH_MAX_DATE_LENGTH,
   PI_SEARCH_MAX_ENVELOPE_BYTES,
   PI_SEARCH_MAX_QUERY_LENGTH,
@@ -31,6 +31,7 @@ import {
   PI_SEARCH_TOOL_DESCRIPTION,
   PI_SEARCH_TOOL_NAME,
   PI_SEARCH_TOOL_PARAMETERS,
+  PI_SEARCH_TRUNCATED_MESSAGE,
 } from '@/executor/handlers/pi/search/normalize'
 
 /**
@@ -70,8 +71,9 @@ const MAX_DATE_LENGTH = ${PI_SEARCH_MAX_DATE_LENGTH}
 const MAX_URL_LENGTH = ${PI_SEARCH_MAX_URL_LENGTH}
 const MAX_ENVELOPE_BYTES = ${PI_SEARCH_MAX_ENVELOPE_BYTES}
 const NO_RESULTS_MESSAGE = ${JSON.stringify(PI_SEARCH_NO_RESULTS_MESSAGE)}
+const TRUNCATED_MESSAGE = ${JSON.stringify(PI_SEARCH_TRUNCATED_MESSAGE)}
 const EXA_MAX_TEXT_CHARACTERS = ${EXA_MAX_TEXT_CHARACTERS}
-const MAX_CALLS_PER_RUN = ${PI_SEARCH_MAX_CALLS_PER_RUN}
+const MAX_CALLS_PER_RUN = ${PI_SEARCH_MAX_CALLS_PER_EXECUTION}
 const BUDGET_MESSAGE = ${JSON.stringify(PI_SEARCH_BUDGET_MESSAGE)}
 
 const PROVIDER_LABELS = {
@@ -146,10 +148,13 @@ function collapseWhitespace(value) {
   return value.replace(/\\s+/g, " ").trim()
 }
 
+const URL_FORBIDDEN_CHARACTERS = /[\\s\\u0000-\\u001f\\u007f]/
+
 function usableUrl(value) {
   const raw = asText(value).trim()
   if (!raw || raw.length > MAX_URL_LENGTH) return undefined
   if (!/^https?:\\/\\//i.test(raw)) return undefined
+  if (URL_FORBIDDEN_CHARACTERS.test(raw)) return undefined
   return raw
 }
 
@@ -221,7 +226,11 @@ function serializeEnvelope(results) {
   const kept = results.slice()
   for (;;) {
     const envelope =
-      kept.length === 0 ? { results: [], message: NO_RESULTS_MESSAGE } : { results: kept }
+      kept.length === 0
+        ? { results: [], message: NO_RESULTS_MESSAGE }
+        : kept.length < results.length
+          ? { results: kept, message: TRUNCATED_MESSAGE }
+          : { results: kept }
     const serialized = JSON.stringify(envelope)
     if (kept.length === 0 || new TextEncoder().encode(serialized).length <= MAX_ENVELOPE_BYTES) {
       return serialized
@@ -259,7 +268,7 @@ export default function (pi) {
     throw new Error("Unsupported search provider: " + provider)
   }
 
-  // Per extension load, which the CLI does once per run — same ceiling as the host adapter.
+  // Per extension load, which the CLI does once per invocation — same ceiling as the host adapter.
   let calls = 0
 
   pi.registerTool({
@@ -272,9 +281,15 @@ export default function (pi) {
       const rawQuery = params && typeof params.query === "string" ? params.query.trim() : ""
       if (!rawQuery) throw new Error("query is required")
       const query = rawQuery.slice(0, MAX_QUERY_LENGTH)
-      const rawCount = Number(params ? params.numResults : undefined)
-      const numResults = Number.isFinite(rawCount)
-        ? Math.min(MAX_RESULTS, Math.max(MIN_RESULTS, Math.floor(rawCount)))
+      const rawCount = params ? params.numResults : undefined
+      const parsedCount =
+        typeof rawCount === "number"
+          ? rawCount
+          : typeof rawCount === "string" && rawCount.trim()
+            ? Number(rawCount)
+            : Number.NaN
+      const numResults = Number.isFinite(parsedCount)
+        ? Math.min(MAX_RESULTS, Math.max(MIN_RESULTS, Math.floor(parsedCount)))
         : DEFAULT_RESULTS
 
       calls += 1

apps/sim/executor/handlers/pi/search/normalize.test.ts

@@ -14,6 +14,7 @@ import {
   PI_SEARCH_MAX_SNIPPET_LENGTH,
   PI_SEARCH_MAX_TITLE_LENGTH,
   PI_SEARCH_TOOL_PARAMETERS,
+  PI_SEARCH_TRUNCATED_MESSAGE,
   parsePiSearchArgs,
   serializePiSearchEnvelope,
 } from '@/executor/handlers/pi/search/normalize'
@@ -31,6 +32,20 @@ describe('parsePiSearchArgs', () => {
     )
   })
 
+  // `Number(null)` / `Number('')` / `Number([])` are a finite 0, so a naive clamp turns every one of
+  // these into a single result — the opposite of the documented default.
+  it('treats a blank or null result count as absent, not as zero', () => {
+    for (const numResults of [null, undefined, '', '   ', []]) {
+      expect(parsePiSearchArgs({ query: 'pi', numResults }).numResults).toBe(
+        PI_SEARCH_DEFAULT_RESULTS
+      )
+    }
+  })
+
+  it('accepts a numeric string the way it accepts a number', () => {
+    expect(parsePiSearchArgs({ query: 'pi', numResults: '3' }).numResults).toBe(3)
+  })
+
   it('clamps the result count instead of failing the call', () => {
     expect(parsePiSearchArgs({ query: 'pi', numResults: 0 }).numResults).toBe(1)
     expect(parsePiSearchArgs({ query: 'pi', numResults: 500 }).numResults).toBe(
@@ -201,6 +216,25 @@ describe('normalizePiSearchRecords', () => {
     ).toEqual([{ title: 'Kept', url: 'https://example.com/ok', snippet: '(no snippet)' }])
   })
 
+  // `url` is the one field that must stay byte-exact to stay resolvable, so unlike title/snippet it
+  // is dropped rather than whitespace-collapsed — collapsing would emit a different, still-dead link.
+  it('drops links carrying whitespace or control characters', () => {
+    expect(
+      normalizePiSearchRecords(
+        'exa',
+        [
+          { title: 'Space', url: 'https://example.com/a b' },
+          { title: 'Newline', url: 'https://example.com/a\nb' },
+          { title: 'Tab', url: 'https://example.com/a\tb' },
+          { title: 'Nul', url: 'https://example.com/a\u0000b' },
+          { title: 'Del', url: 'https://example.com/a\u007fb' },
+          { title: 'Kept', url: 'https://example.com/a-b_c%20d' },
+        ],
+        10
+      )
+    ).toEqual([{ title: 'Kept', url: 'https://example.com/a-b_c%20d', snippet: '(no snippet)' }])
+  })
+
   it('honors the requested limit', () => {
     const records = Array.from({ length: 9 }, (_, i) => ({
       title: `T${i}`,
@@ -244,6 +278,25 @@ describe('serializePiSearchEnvelope', () => {
     expect('publishedDate' in parsed.results[0]).toBe(false)
   })
 
+  it('says so when results were dropped, instead of reading as a complete answer', () => {
+    const results = Array.from({ length: 10 }, (_, i) => ({
+      title: '見'.repeat(PI_SEARCH_MAX_TITLE_LENGTH),
+      url: `https://example.com/${i}?${'q'.repeat(1500)}`,
+      snippet: '漢'.repeat(PI_SEARCH_MAX_SNIPPET_LENGTH),
+    }))
+    const parsed = JSON.parse(serializePiSearchEnvelope(results))
+
+    expect(parsed.results.length).toBeLessThan(results.length)
+    expect(parsed.message).toBe(PI_SEARCH_TRUNCATED_MESSAGE)
+  })
+
+  it('stays silent when everything fit', () => {
+    const parsed = JSON.parse(
+      serializePiSearchEnvelope([{ title: 'A', url: 'https://example.com/a', snippet: 'S' }])
+    )
+    expect('message' in parsed).toBe(false)
+  })
+
   // The per-field caps count UTF-16 units, so ten maximal results only exceed the byte ceiling once
   // the text is multi-byte — which is exactly the case a character-counted cap alone would miss.
   it('drops whole results to fit the byte ceiling, never truncating mid-string', () => {