10  web_search: Broad Discovery Under a Budget

Part III · Skills and the compositional research toolchain

Implementation baseline: server-owned OpenAI hosted-search bridge · reviewed reference snapshot 45a903c

Search discovers candidates. It does not establish that a page was read, that generated notes follow from the page, or that a URL supports the final answer. The Northstar workflow therefore uses search to find official guidance, then crosses a separate retrieval boundary in Chapter 11.

10.1 Search is a tool, not ambient model knowledge

web_search is a server-owned application tool inside the provider-neutral loop. An OpenAI or Anthropic coordinator may propose the same typed call, but the server owns validation, authorization, budget, recipient, execution, progress, and the bounded result.

The backend is a separate OpenAI Responses request with native hosted web_search. It is not a provider-native tool secretly attached to the coordinator. The nested route receives a short fixed instruction and the selected query—not the complete conversation, document corpus, or tool history. Search calls and results remain private to the shared loop; Pi does not execute them a second time.

coordinator proposes web_search(query)
        ↓ validate / authorize / debit
separate fixed OpenAI search-model request
        ↓ require completed native receipt
normalize and fit candidate result
        ↓
coordinator receives bounded notes + URL candidates

This bridge design matters for portability. The application tool has one name and result shape even when the coordinator changes. It does not imply that hosted-search internals, ranking, consulted pages, latency, or output quality are provider-neutral.

10.2 Search-model binding

The search recipient and model come from reviewed agent.yaml, not tool arguments:

- name: web_search
  model: gpt-5.4
  maxCalls: 300
  maxSources: 1000
  sourcesPerCall: 100
  timeoutMs: 45000
  maxOutputTokens: 4096
  requestTimeoutMs: 21600000

The model is an unprefixed OpenAI wire ID. The bridge uses the server’s approved OpenAI credential and endpoint configuration. Callers cannot provide a provider, credential, endpoint, header, retry setting, or larger limit. SDK retries are zero, and there is no automatic alternate search provider or model.

A configured model name is a declaration, not a live capability probe. Startup can validate syntax and bounds without proving that the account currently permits hosted search. A remote rejection fails safely rather than selecting an undisclosed fallback.

10.3 Two budgets, two meanings

One HTTP invocation owns one BoundedSearchSession. Its primary budgets are:

  • application calls—each admitted search attempt spends one slot before backend dispatch; and
  • distinct returned source URLs—new normalized candidates admitted into bounded results spend aggregate source capacity.

A failed backend call retains its call debit because remote work may already have occurred. It spends no source slots when no result is admitted. Repeated normalized URLs do not spend another unique-source slot. A new HTTP request, including a later Pi continuation, receives a new budget; this is not a conversation-wide or distributed quota.

sourcesPerCall limits one result independently of maxSources. These are ceilings, not targets. The prompt asks for focused evidence and material follow-ups rather than consuming every permitted call. A default allowance of 300 calls demonstrates accounting capacity; it does not promise that a six-hour, 300-call live run will finish, remain affordable, or fit model context.

The whole-request deadline includes coordinator work. Per-call timeout and provider output-token settings remain separate. Clients, proxies, account quotas, context windows, and provider limits may terminate earlier.

10.4 Completion-order admission under concurrency

Queries that do not depend on each other can run concurrently. A dependent query—one needing a name discovered by the first—must wait. Concurrency introduces a source-budget race: two results can complete when only one has remaining capacity.

Admission therefore occurs atomically in completion order. The first completed valid result claims available new-source slots; a later completion sees the updated aggregate. Already-submitted remote work can still finish after capacity has been exhausted, but its candidates cannot overbook admission.

This ordering is deterministic relative to observed completion, not query submission. It is not relevance ranking across calls. If product policy needs priority by topic or source class, it must schedule or reserve capacity before dispatch rather than rewriting history after completion.

Result fields include remaining-call and remaining-source snapshots. Concurrent activity can make them stale immediately. Runtime admission remains authoritative.

10.5 Candidate normalization

Backend output is untrusted. The normalizer:

  • accepts bounded HTTP(S) URL candidates;
  • rejects embedded username/password credentials and unsafe schemes;
  • normalizes with the platform URL parser;
  • uses exact normalized URL.toString() equality for deduplication;
  • bounds source title and excerpt-like fields;
  • keeps answer-linked candidates ahead of broader consulted candidates when available; and
  • separates generated notes from source records.

Exact URL equality is not semantic document identity. Tracking-parameter variants can consume separate slots, and two different URLs can serve identical bytes. Conversely, removing or reordering query parameters could change a resource, so the search layer does not invent a stronger equivalence.

Native API/non-URL source objects and unsafe locators are excluded. A normalized locator says only that the application admitted this candidate string into the result. It does not prove that the candidate is public-fetchable under Chapter 11’s policy.

10.6 Completion receipts before authority

Streaming text from the nested model is not enough for success. The bridge requires one completed native response and a matching completed hosted-search call/result identity. Missing or conflicting receipts, excess distinct native executions, incomplete terminal state, duplicate response terminals, malformed output, cancellation, and deadline expiry fail closed.

Identical repeated SDK observations can be consolidated only when call IDs, inputs, outputs, native completion observations, and the final item agree. This handles duplicate observation of one execution; it does not increase the native execution allowance or create exactly-once remote work.

The requested provider cap is observable after the fact. It cannot preempt undisclosed remote internals or undo provider work already performed. A native search action may generate several queries or consult several pages. The 192-code-point application query limit is not a bound on those provider-generated operations.

10.7 Provisional search progress

Negotiated Pi clients can display bounded generated search text while the nested request runs. The card labels it provisional and unverified. It is not assistant final-output streaming, page-open telemetry, or a citation.

The implementation limits cumulative snapshots and visible size, batches small deltas, and redacts known raw or form-encoded server-key echoes. On failure or cancellation, the widget discards the provisional text and never persists it. Older clients receive no preview.

Progress callbacks cannot determine execution success, and a displayed preview cannot substitute for the completed receipt. Redaction covers specific known credential patterns; it is not a general confidentiality classifier. Query terms and generated text can still disclose sensitive facts.

10.8 Fitting the final output

The normalizer constructs one bounded result envelope. Optional generated notes are removed before source locators. If necessary, sources and the query preview are reduced until the final output fits both the serialized UTF-16-unit ceiling and UTF-8 byte ceiling.

Fitting is semantically lossy. Removing a source can reduce coverage; truncating a title or note can remove a qualifier. The result therefore reports candidates under stated bounds rather than claiming completeness. A safe search_failed outcome replaces malformed or unfit upstream content; raw provider bodies and errors do not pass through.

Generated notes are model synthesis, not quotations. Even when they mention a source, they are not retained source representations and cannot become exact evidence merely by surviving output fitting.

10.9 Privacy and recipient disclosure

A search query is a disclosure to the configured OpenAI recipient and potentially to the public-search ecosystem it invokes. The bridge sends less than the full coordinator context, but the selected query can still contain names, facts, or fragments derived from private material.

The application should disclose:

  • that the operation uses a separate OpenAI search model;
  • which model/recipient class is configured;
  • that public-network activity and charges may occur;
  • that non-storage is requested but is not a zero-retention certification; and
  • that results are generated candidates rather than verified source evidence.

Ordinary logs contain no query, snippets, URLs, credentials, or raw upstream failures. Safe diagnostics use categories, elapsed time, optional HTTP status, allowlisted SDK error names, and bounded observation counts. This minimizes routine exposure but does not make confidential search safe. A separate reviewed disclosure policy is required before enabling public search over sensitive conversations.

10.10 Why candidates are not admitted evidence

A search result can fail evidence use in several independent ways:

  1. the URL may be blocked by public-HTTPS retrieval policy;
  2. the page may redirect, change, reject access, or exceed limits;
  3. the retrieved representation may omit the relevant material;
  4. the generated search note may misstate the page;
  5. the page may be false, stale, or unsuitable; or
  6. the final claim may not follow from what was read.

Chapter 11 admits a concrete retrieved representation. Chapter 13 then evaluates identity, locators, claim support, and research completion. Search has completed its job when it supplies bounded candidates and records gaps honestly—not when it creates a citation-looking URL.

10.11 Current evidence and its limitations

Deterministic tests cover configuration rejection, exact query limits, 300-call admission, 1,000 aggregate URL slots, per-call fitting, concurrent completion, duplicate candidates, malformed and contradictory receipts, cancellation, provisional-preview privacy, output bytes, and zero automatic retries. Tests inject synthetic provider transport under network denial.

The currently published Northstar recording is dated live-provider and public-network evidence. Its metadata records an Anthropic coordinator and a separate openai/gpt-5.4 search recipient. The run visibly completes web_search and then read_source on selected official guidance. It demonstrates that exact reviewed route at that date. It does not establish:

  • deterministic search results;
  • completeness or ranking quality;
  • provider equivalence;
  • that every returned candidate was read;
  • general factual correctness or entailment;
  • production confidentiality; or
  • Open Responses conformance.

The historical Wikimedia report belongs to an older standalone backend and explicitly claimed no citations. It must not be described as evidence for the current hosted-search bridge.

10.12 Failure modes

Search-note laundering. Generated notes are quoted as page text. Read the selected representation first.

Budget reset laundering. A client creates repeated HTTP requests to evade a per-invocation limit. Add a separately owned higher-level quota when conversation or tenant accounting is required.

Completion without receipt. Provisional text is treated as successful search after terminal failure. Require the completed native execution record.

Recipient ambiguity. An Anthropic coordinator makes the UI imply Anthropic performed search. Disclose the separate OpenAI recipient.

Link-count confidence. Many URLs are treated as strong support. Evaluate suitability and claim support rather than counting candidates.

10.13 Pattern summary

Problem: Web discovery is useful but remote, variable, disclosure-bearing, and easy to misrepresent as evidence.

Pattern: Bind search to a reviewed recipient, debit calls and unique URLs separately, admit concurrent completions atomically, normalize and fit untrusted output, and label all results as candidates.

Result: Coordinators can discover public leads through one portable tool contract without turning hosted-search prose into source authority.

Cost: Separate retrieval, evidence review, recipient policy, higher-level quotas, and live compatibility evidence remain necessary.

10.14 Exercises

  1. Two concurrent calls complete with 80 new URLs each and 100 source slots remaining. Specify the admitted results under completion-order accounting.
  2. Design a conversation-level quota without trusting a caller-supplied session ID. State the missing identity requirement.
  3. Show how a correct URL citation could still fail Chapter 13’s support test.
  4. Define a user disclosure for an Anthropic-coordinated run that sends only a focused query to OpenAI search.

10.15 Chapter contract

  • Scope: search-model binding, call/source budgets, completion-order admission, candidate normalization, progress, output fitting, and disclosure.
  • Canonical claims: search output supplies candidates and generated notes, not admitted source representations or verified support.
  • Migration inputs: current hosted-search implementation, invariant review, deterministic tests, and dated Northstar live evidence.
  • Evidence gates: synthetic receipt/accounting tests plus separately dated and scoped live-search records.
  • Demonstration slots: Northstar shows the configured search route and follow-on retrieval, not search completeness or truth.
  • Source-claim ledger: each live claim names coordinator, search recipient/model, endpoint class, date, limits, and limitations.
  • Exclusions: public source retrieval belongs to Chapter 11; support and completion belong to Chapter 13.