Input: Web‑search agent input layer

[functor-flow]

Input: Web‑search agent input layer

full spec at spec

flowchart TD
  Raw["Validator prediction / external claim"]
  Req["WebSearchRequest (validated)"]
  Task["SearchTask (id + target)"]
  Hist["SearchHistory (initial, empty)"]
  Loop["runWebSearchAgent (Serper → Crawler → Embeddings → Nav → Decision)"]
  Result["AgentResult"]

  Raw --> Req
  Req --> Task
  Task --> Hist
  Task --> Loop
  Hist --> Loop
  Loop --> Result

Loading

Target: Define a minimal verification target, the central agent entrypoint, and the initial search query construction used by the rest of the pipeline.

---

Status: Not implemented.

Role. Be the single entry surface for the web-search agent: take a prediction/claim plus optional context, turn it into a SearchTask with an initial SearchHistory, and hand that into the workflow loop.

Responsibilities.

• Define the external request shape (WebSearchRequest) used by the Validator and any external callers.
• Normalize each request into a SearchTask (stable id and VerificationTarget) and create an empty SearchHistory for that task.
• Expose a pure function like runWebSearchAgent(task) that drives the loop (Serper → Crawler → Embeddings → Nav → Decision) and returns an AgentResult the Validator can adapt to validation_result.
• Provide a helper like handleExternalSearchRequest(payload) that validates unknown input, builds a SearchTask, calls runWebSearchAgent, and returns the final AgentResult.

---

Context

The Validator works with predictions in a richer DB schema. For this input spec we only need to remember that it has:

• A stable prediction_id.
• The original tweet / prediction text.
• Parsed goal/timeframe spans and normalized timeframe fields.
• Optional free‑form context.

We do not expose the full DB row to the web‑search agent. Instead, the caller (Validator or external) sends a compact request that describes exactly what should be checked on the web.

---

Agent‑facing request and internal types

External surface for calling the web‑search agent:

interface WebSearchRequest {
  verification_target: VerificationTarget;
}

What the agent is asked to verify, in human terms:

interface VerificationTarget {
  // e.g. "Who won the 2024 U.S. presidential election?"
  // or "Did Bitcoin close above $100k on 2025-11-20 (UTC)?"
  description: string;

  timeframe?: {
    start_utc?: string | null;     // ISO; optional / null when open
    end_utc?: string | null;       // ISO; optional / null when open
  } | null;

  // Optional surface for trace / proof text; agent does not depend on these
  claim_text?: string | null;      // original tweet / prediction text
  context?: string | null;         // extra plain-text context (thread, notes, etc.)
}

Minimal internal task object the pipeline works with:

interface SearchTask {
  id: string;                      // stable id for logging/history
  target: VerificationTarget;      // the only thing downstream modules must rely on
}

The agent is responsible for turning VerificationTarget into a concrete search strategy. A key piece of that is the initial SERP query built from the target:

// Used by the Serper module as the starting query for this task
type InitialSearchQuery = string;

The Search History & Evidence module will later own the full history shape; for now we just assume an empty history object is created per SearchTask and passed through the workflow loop.

The agent returns a high‑level result that the Validator can map into its existing validation_result schema:

interface AgentResult {
  outcome: string; // e.g. MaturedTrue | MaturedFalse | ...
  proof: string;   // short markdown summary + key snippets
  sources: Array<{
    url: string;
    title: string;
    pub_date: string | null;
    excerpt: string;
  }>;
  debug?: {
    total_queries?: number;
    total_pages_visited?: number;
  };
}

---

TODO

• Add shared types/schemas for WebSearchRequest, VerificationTarget, SearchTask, and AgentResult in a single module (e.g. src/types/agent.ts), using the minimal structure above.
• Implement a pure helper buildInitialSearchQuery(target: VerificationTarget): InitialSearchQuery that turns the verification target into the initial Serper query string (using description and timeframe only; no Validator‑specific concepts leak in).
• Implement runWebSearchAgent(task: SearchTask): Promise<AgentResult> as the single orchestration entrypoint for the pipeline:
  • initialize an empty search history object for this task.id (concrete shape can be refined by the Search History & Evidence work),
  • compute the initial Serper query via buildInitialSearchQuery(target), and
  • pass SearchTask, the initial query, and the history into the Workflow Loop (Serper → Crawler → Embeddings → Nav → Decision).
• Implement handleExternalSearchRequest(payload: unknown): Promise<AgentResult>:
  • validate/parse payload into WebSearchRequest,
  • construct a SearchTask,
  • call runWebSearchAgent,
  • return AgentResult. (No HTTP/transport details here; this is a pure function.)

[linear]

SWARM-65