@jangmanj/pi-webtasks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JangMan-J
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,193 @@
+# pi-webtasks
+
+Session-bound web research for Pi, with a local evidence store.
+
+The extension owns transport, storage, indexing, recovery, and delivery. The model
+owns the research work: what to search, what to read, and what to ask. Nothing
+exposes SQL, provider ids, file paths, or raw HTTP.
+
+## Install
+
+```sh
+pi install npm:@jangmanj/pi-webtasks
+```
+
+Then run `/login` in Pi and choose **Parallel** (see [Credentials](#credentials)).
+
+This package was earlier published unscoped as `pi-webtasks`; that name is no
+longer published. If you installed it, run `pi remove npm:pi-webtasks`, then
+install the scoped name. The research store directory is the same, so stored
+evidence carries over.
+
+## Status
+
+Five tools, split by who writes the answer. The agent writes it from pages it
+reads (`web_search`, `web_fetch`), or a Parallel research agent writes it
+(`web_answer`, `web_research`):
+
+| Tool | Work |
+| --- | --- |
+| `web_search` | Find pages for an objective and 1-3 keyword queries; store the ranked sources and excerpts and return handles. |
+| `web_fetch` | Read known http(s) URLs (pages, PDFs) into the same store, as focused excerpts or full content. |
+| `web_answer` | Ask Parallel's research agent (Responses API) for a cited answer in seconds, and follow up in the same conversation. |
+| `web_research` | Hand a research job to Parallel's deep-research agent (Task API) in the background: a cited report or structured fields with per-field citations. `core` is the processor floor and `ultra2x` the most an agent may choose; progress and completion arrive as alerts. |
+| `web_recall` | Search stored evidence, or read one item by handle in bounded slices. |
+
+The agent-facing wording (tool descriptions, guidelines, receipts, and errors)
+describes Parallel's capabilities and what to do next. It does not expose the
+extension's policies or plumbing: processor limits, event streams, and the
+store stay internal. `tests/tool-wording.test.ts` checks that every guideline
+names its own tool, because Pi merges all guidelines into one list.
+
+There are no webhooks, no background receiver, no artifact files, and no awkward
+effort tiers. Collection happens inside Pi; if Pi is closed, collection stops
+and the next session reconciles provider state where retention permits.
+
+## Background research
+
+`web_research` requires an explicit output contract: either `output_schema` (a
+JSON Schema object) for fields, or `output_description` for the cited text report
+you want. The extension never invents one, and never relies on the provider's
+`auto` default. It submits once and returns a receipt. The run's event stream is
+collected while Pi is open: every event is recorded, and interim findings become
+stored evidence as they arrive, so `web_recall` can read partial results
+before the run finishes. Progress messages and source statistics feed the
+progress alerts. If the stream drops, it reconnects with backoff (3 s up to
+5 min).
+
+Alerts wake an idle session and queue behind a busy one; they never steer or
+interrupt active work. Progress updates follow one third of the lower published
+upper-latency estimate per processor (for example `core` every 1m40s). They are
+reminders to look, not deadlines or completion percentages. Completion, failure,
+and action-required alerts are immediate. A run that Parallel halts as
+`action_required` is alerted once and stays watched: progress alerts pause, and
+when it resumes or ends, that arrives as another alert. A closed stream is never
+treated as completion: the provider's run status decides.
+
+Alerts are persisted before delivery and delivered at-least-once: an alert stays
+unacknowledged until the agent reads that run, and a new runtime offers
+unacknowledged alerts again rather than losing them. Do not expect exactly-once.
+
+Task runs carry the local reference in their metadata inside the session's Task
+Group, so a crash between submission and recording the provider id is recovered
+from the group instead of resubmitting. `core` is the processor floor
+(`lite`/`base` are not offered for research) and `ultra2x` is what an agent may
+choose; the configured default is `core` (`WEBTASKS_TASK_PROCESSOR` overrides).
+
+## How evidence behaves
+
+- Every Search and Extract result is stored in `research.sqlite` under the Pi
+  session that requested it (`WEBTASKS_DIR`, else `<agent-dir>/webtasks`).
+- The model sees a bounded receipt with stable handles, never the whole corpus.
+  `web_recall { handle }` returns a bounded slice plus the next offset;
+  `web_recall { query }` searches stored text and returns handles.
+- Evidence belongs to one Pi session. A handle from another session behaves
+  exactly like a missing one, so nothing leaks across sessions.
+- Receipts return a local **context handle**. Passing it as `context` to a later
+  `web_search`/`web_fetch` keeps related calls in one provider research session;
+  the provider id itself never leaves the store.
+- A paid call is recorded before it is sent and is never retried automatically.
+  Replaying the same Pi invocation returns what is already stored instead of
+  paying twice; an interrupted request is marked `uncertain`, not silently
+  resubmitted. Every paid tool settles a failure the same way: a missing key or
+  a 4xx rejection is `failed`; anything else that may have reached Parallel
+  (5xx, 408, a lost connection, a timeout) is `uncertain`.
+- Retrieved text is untrusted material, not instructions.
+
+## Development
+
+Requirements: Node.js 22.19 or later, npm, and Pi 1.1 or later.
+The only runtime dependency is the pinned `parallel-web` SDK. SQLite uses Node's
+built-in implementation.
+
+```sh
+npm ci
+npm run check
+```
+
+`npm run check` runs the type checker and the offline suite. The offline suite
+uses real SQLite in temporary directories and a stubbed HTTP layer; it makes no
+paid request. `PI_PACKAGE_DIR` selects another installed Pi package directory for
+runtime tests.
+
+`node scripts/extract-tool-schemas.ts <dir>` dumps the registered tools exactly
+as the model sees them.
+
+`npm run smoke:pack` packs the package, installs the tarball into a scratch
+project, and loads it through Pi's real extension loader.
+
+CI (`.github/workflows/ci.yml`) runs the type checker, the suite, and the pack
+smoke test on Node 22.19 (the engines floor), 24, and 26, plus Pi 1.1.0 (the
+peer floor).
+
+## Releasing
+
+Releases publish from GitHub Actions through npm trusted publishing (OIDC), so
+no npm token is stored anywhere and every version carries a provenance
+attestation.
+
+```sh
+npm version patch        # or minor / major: bumps package.json, commits, tags vX.Y.Z
+git push --follow-tags   # the tag runs .github/workflows/publish.yml
+```
+
+The publish workflow reruns CI, refuses a tag that does not match
+`package.json`, publishes, and creates the GitHub release.
+
+One-time setup for a package name that is not on npm yet: `npm login`, then
+`npm run bootstrap:npm` in an interactive terminal (one 2FA approval). The
+script stages a throwaway `0.0.0-bootstrap` to create the package, links
+`publish.yml` (environment `npm`) as its trusted publisher, and pushes the
+`v<version>` tag, so CI publishes the first real version with provenance. Run
+`npm run bootstrap:npm -- --dry-run` first to check the plan. Later,
+`npm run bootstrap:npm -- --cleanup` removes the staged throwaway and the
+`0.0.0-stage` placeholder (two more approvals).
+
+Retired experiments, benchmarks, and the pre-rewrite implementation live in
+`.archive/` (git-ignored). `npm run docs:snapshot` refreshes the Parallel docs
+mirror into `docs/parallel/` (git-ignored); the design record and API notes live
+there too, outside version control.
+
+## Credentials
+
+Run `/login` in Pi and choose **Parallel**. Pi offers two sign-in methods:
+
+- **Browser sign-in** (listed under *Sign in with an account*). Pi opens
+  platform.parallel.ai in your browser. There you approve the request for
+  `127.0.0.1` and select an existing API key or create one. Pi receives the
+  approval on a temporary listener on `127.0.0.1`, exchanges it for the key, and
+  stores it. The listener accepts one callback and closes on success, error, or
+  cancel. After 120 seconds, Pi offers a prompt for the callback address from the
+  browser's address bar, for example over SSH without port forwarding. The
+  listener stays open while that prompt waits, so a browser callback can still
+  complete sign-in.
+- **API key** (listed under *Sign in with an API key*). Paste a key from the API
+  keys page on platform.parallel.ai.
+
+An empty entry stores nothing. Parallel adds no models, so the model picker is
+unchanged. The extension registers no commands.
+
+The stored login is used first. Without one, the extension uses
+`_PARALLEL_API_KEY` (`PARALLEL_API_KEY` is also accepted), then a key in `.env` or
+`parallel.env` beside the package manifest. Exported settings take precedence
+over the key files. The key is resolved on every call, so a login or logout takes
+effect on the next request. Credential files are not packaged or committed.
+
+Do not install `@parallel-web/pi-extension` alongside this package: it registers a
+`web_search` tool with the same name, so the two would collide.
+
+Balance is not shown by the extension; check the provider account directly. Do
+not paste credential values into tool arguments, diagnostics, or source files.
+
+## Limits
+
+- Search, Extract, and Answers are synchronous calls; only research tasks run in
+  the background.
+- `web_recall` returns bounded pages and slices, never a whole corpus in one
+  call. A page cursor carries its own search, so `web_recall { cursor }`
+  alone continues it.
+- Collection stops when Pi closes. Intermediate progress from while Pi was closed
+  is not replayed by the provider; completed results are recovered where the
+  account's retention policy allows.
+- Stored evidence is private data under the agent directory; retention and
+  cross-session visibility are still open decisions.

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@jangmanj/pi-webtasks",
+  "version": "0.1.0",
+  "description": "Session-bound web research tools with a local evidence store for Pi.",
+  "license": "MIT",
+  "author": "JangMan-J",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JangMan-J/pi-webtasks.git"
+  },
+  "homepage": "https://github.com/JangMan-J/pi-webtasks#readme",
+  "bugs": {
+    "url": "https://github.com/JangMan-J/pi-webtasks/issues"
+  },
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "parallel",
+    "web-search",
+    "research"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm test",
+    "smoke:pack": "node scripts/smoke-pack.mjs",
+    "docs:snapshot": "node scripts/snapshot-docs.mjs docs/parallel",
+    "bootstrap:npm": "bash scripts/npm-bootstrap.sh"
+  },
+  "dependencies": {
+    "parallel-web": "1.3.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": ">=1.1.0",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@types/node": "26.6.2",
+    "typebox": "1.3.27",
+    "typescript": "6.0.3"
+  },
+  "overrides": {
+    "undici": "8.12.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/alert-delivery.ts

@@ -0,0 +1,128 @@
+/**
+ * Alert delivery: hands the session's stored alerts to the agent, at least once.
+ *
+ * Alerts are written by the store: a completion commits its alert in the same
+ * transaction as its evidence, and progress alerts are queued on their
+ * schedule. This module owns everything after that:
+ *
+ *  - Draining: claim waiting alerts (failures and attention first, then
+ *    completions, then progress), hand each to the sink, mark it delivered.
+ *    Wake-ups coalesce: one drain runs at a time, and a wake-up during a drain
+ *    makes it look again before it goes idle.
+ *  - A failed hand-off is not delivery: the alert stays claimed and the next
+ *    wake-up offers it again.
+ *  - Delivered is not received: an alert stays open until the agent reads its
+ *    run (`received`), and a new runtime offers every unacknowledged alert
+ *    again (`start`). Duplicates are possible; silence is not.
+ *  - Nothing is handed over before `start` or after `stop`, and `stop` waits
+ *    for a running drain, so the store is never closed under it.
+ */
+
+import type { AlertRecord, ResearchStore } from "./store.ts";
+
+/** Hands one alert to the agent. Throwing means it was not handed over. */
+export type AlertSink = (alert: AlertRecord) => void | Promise<void>;
+
+type Options = {
+  store: ResearchStore;
+  sessionId: string;
+  deliver: AlertSink;
+  /** Reports a failed hand-off or an unavailable store. Delivery itself never throws. */
+  onError?: (err: unknown) => void;
+};
+
+/** Alerts claimed per pass. */
+const BATCH = 5;
+/** Passes per drain; anything left waits for the next wake-up. */
+const MAX_PASSES = 20;
+
+export function createAlertDelivery(options: Options) {
+  const { store, sessionId, deliver } = options;
+  const report = options.onError ?? (() => undefined);
+  /** The takeover and first drain; set once by `start`. */
+  let startup: Promise<void> | undefined;
+  let started = false;
+  let stopped = false;
+  let draining = false;
+  /** A wake-up arrived during the running drain: look once more before going idle. */
+  let again = false;
+  let current: Promise<void> = Promise.resolve();
+
+  async function drain(): Promise<void> {
+    try {
+      for (let pass = 0; pass < MAX_PASSES; pass++) {
+        if (stopped) return;
+        again = false;
+        const batch = await store.claimAlerts(sessionId, { limit: BATCH });
+        if (!batch.length) {
+          if (again) continue;
+          return;
+        }
+        for (const alert of batch) {
+          if (stopped) return;
+          try {
+            await deliver(alert);
+          } catch (err) {
+            // Not marked delivered: the alert stays claimed and the next wake-up offers it again.
+            report(err);
+            return;
+          }
+          // Unmarked, it is offered again: a duplicate, never a loss.
+          await store.markAlertDelivered(sessionId, alert.alert_id).catch(() => undefined);
+        }
+      }
+    } catch (err) {
+      report(err);
+    } finally {
+      // Cleared in the same step as the last check of `again`, so no wake-up falls between them.
+      draining = false;
+    }
+  }
+
+  /**
+   * Something may be waiting: drain it, or make the running drain look again.
+   * Resolves when that drain is idle. Never rejects.
+   */
+  function wake(): Promise<void> {
+    if (!started || stopped) return current;
+    if (draining) {
+      again = true;
+      return current;
+    }
+    draining = true;
+    current = drain();
+    return current;
+  }
+
+  /**
+   * Take over delivery for this session: what an earlier runtime handed over
+   * but never saw read is offered again, then everything waiting is drained.
+   * Wake-ups before this are covered by its drain.
+   */
+  function start(): Promise<void> {
+    if (stopped) return Promise.resolve();
+    startup ??= (async () => {
+      await store.requeueUnacknowledgedAlerts(sessionId).catch(report);
+      if (stopped) return;
+      started = true;
+      await wake();
+    })();
+    return startup;
+  }
+
+  /** The agent read this run's evidence: its alerts were received and are not offered again. */
+  async function received(reference: string): Promise<void> {
+    await store.acknowledgeRunAlerts(sessionId, reference).catch(() => undefined);
+  }
+
+  /** Hand nothing more over, and wait for a running takeover or drain to finish. */
+  async function stop(): Promise<void> {
+    stopped = true;
+    await startup;
+    await current;
+  }
+
+  return { start, wake, received, stop };
+}
+
+export type AlertDelivery = ReturnType<typeof createAlertDelivery>;

package/src/answer-service.ts

@@ -0,0 +1,237 @@
+/**
+ * Cited answers through the Responses API (`POST /v1/responses`), with local
+ * continuation and stored evidence.
+ *
+ * The pinned SDK has no Responses resource, so this module issues the documented
+ * raw request as a recorded paid call (`paid-call.ts`): never retried, because
+ * the API has no native background mode or retrieve-by-id, so an ambiguous
+ * outcome is recorded as `uncertain` rather than repeated.
+ */
+
+import type { ResearchStore, EvidenceInput, CitationInput } from "./store.ts";
+import { createPaidCalls, UnusableResponse } from "./paid-call.ts";
+import { sourcePolicy } from "./source-policy.ts";
+import { clean, oneLine, RECEIPT_LIMIT, replayReceipt, UNTRUSTED } from "./receipt.ts";
+
+/** The part of the Parallel client the answer path needs. */
+export type AnswerClient = {
+  apiKey?: string;
+  post(path: string, options?: {
+    body?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    maxRetries?: number;
+    timeout?: number;
+    signal?: AbortSignal;
+  }): Promise<unknown>;
+};
+
+export type AnswerInput = {
+  question: string;
+  effort?: "low" | "medium" | "high";
+  instructions?: string;
+  include_domains?: string[];
+  exclude_domains?: string[];
+  /** Local reference of an earlier answer to continue. */
+  continue_from?: string;
+};
+
+export const ANSWER_EFFORTS = ["low", "medium", "high"] as const;
+/** Parallel's own default; low suits only a fact one good source settles. */
+export const DEFAULT_ANSWER_EFFORT: (typeof ANSWER_EFFORTS)[number] = "medium";
+
+export type AnswerReceipt = { text: string; details: Record<string, unknown> };
+
+type Options = {
+  store: ResearchStore;
+  sessionId: string;
+  client: () => Promise<AnswerClient>;
+};
+
+type Annotation = { type?: string; url?: string; title?: string; start_index?: number; end_index?: number };
+
+/** Read the answer text: `output_text` when present, otherwise the message items. */
+function answerText(response: Record<string, unknown>): string {
+  if (typeof response.output_text === "string" && response.output_text.trim()) return response.output_text;
+  const output = response.output;
+  if (!Array.isArray(output)) return "";
+  const parts: string[] = [];
+  for (const item of output) {
+    if (!item || typeof item !== "object") continue;
+    const content = (item as { content?: unknown }).content;
+    if (!Array.isArray(content)) continue;
+    for (const part of content) {
+      if (part && typeof part === "object" && typeof (part as { text?: unknown }).text === "string") {
+        parts.push((part as { text: string }).text);
+      }
+    }
+  }
+  return parts.join("\n");
+}
+
+function annotations(response: Record<string, unknown>): Annotation[] {
+  const output = response.output;
+  if (!Array.isArray(output)) return [];
+  const found: Annotation[] = [];
+  for (const item of output) {
+    if (!item || typeof item !== "object") continue;
+    const content = (item as { content?: unknown }).content;
+    if (!Array.isArray(content)) continue;
+    for (const part of content) {
+      if (!part || typeof part !== "object") continue;
+      const list = (part as { annotations?: unknown }).annotations;
+      if (!Array.isArray(list)) continue;
+      for (const annotation of list) {
+        if (annotation && typeof annotation === "object" && (annotation as Annotation).type === "url_citation") {
+          found.push(annotation as Annotation);
+        }
+      }
+    }
+  }
+  return found;
+}
+
+function evidenceFromAnswer(text: string, list: Annotation[]): { evidence: EvidenceInput[]; citations: CitationInput[] } {
+  const evidence: EvidenceInput[] = [{
+    kind: "report",
+    origin: "provider_report",
+    title: "Cited answer",
+    body: text,
+    pointer: "output_text",
+    ref: "answer",
+  }];
+  const citations: CitationInput[] = [];
+  const seen = new Map<string, string>();
+  for (const annotation of list) {
+    const url = clean(annotation.url);
+    if (!url) continue;
+    let ref = seen.get(url);
+    if (!ref) {
+      ref = `src:${seen.size}`;
+      seen.set(url, ref);
+      evidence.push({
+        kind: "source",
+        origin: "provider_source",
+        title: clean(annotation.title),
+        url,
+        pointer: "annotations",
+        body: url,
+        payload: annotation,
+        ref,
+      });
+    }
+    const start = typeof annotation.start_index === "number" ? annotation.start_index : undefined;
+    const end = typeof annotation.end_index === "number" ? annotation.end_index : undefined;
+    const claim = start !== undefined && end !== undefined && end > start ? text.slice(start, end) : undefined;
+    citations.push({ evidence: "answer", source: ref, url, title: clean(annotation.title), claim: claim ? oneLine(claim, 300) : undefined });
+  }
+  return { evidence, citations };
+}
+
+/** The answer text for the receipt, cut at the budget with a pointer to the rest. */
+function answerPreview(text: string, limit = RECEIPT_LIMIT): { text: string; truncated: boolean } {
+  if (text.length <= limit) return { text, truncated: false };
+  return { text: `${text.slice(0, limit)}\n\n[Answer continues; read the rest with web_recall { handle }]`, truncated: true };
+}
+
+export function createAnswerService({ store, sessionId, client }: Options) {
+  const calls = createPaidCalls({ store, sessionId, client });
+
+  async function continuationId(reference: string): Promise<string> {
+    const run = await store.run(sessionId, reference);
+    if (!run) throw new Error(`${reference} is not a research record in this session`);
+    if (run.kind !== "answer") throw new Error(`${reference} is not an earlier web_answer; continue a web_research run with web_research { continue_from }`);
+    if (!run.provider_run_id) throw new Error(`${reference} has no completed answer to continue from (state: ${run.state})`);
+    return run.provider_run_id;
+  }
+
+  async function answer(input: AnswerInput, call: { invocationId: string; signal?: AbortSignal }): Promise<AnswerReceipt> {
+    const question = clean(input.question);
+    if (!question) throw new Error("question must be a non-empty string");
+    const effort = input.effort ?? DEFAULT_ANSWER_EFFORT;
+    if (!(ANSWER_EFFORTS as readonly string[]).includes(effort)) throw new Error("effort must be low, medium, or high");
+    const previous = input.continue_from ? await continuationId(clean(input.continue_from)!) : undefined;
+    const { include, exclude } = sourcePolicy(input);
+
+    const intent = {
+      kind: "answer" as const,
+      question,
+      effort,
+      instructions: clean(input.instructions),
+      include_domains: include,
+      exclude_domains: exclude,
+      continue_from: clean(input.continue_from),
+    };
+    const body: Record<string, unknown> = {
+      model: "parallel",
+      input: question,
+      reasoning: { effort },
+      ...(previous ? { previous_response_id: previous } : {}),
+      ...(clean(input.instructions) ? { instructions: clean(input.instructions) } : {}),
+      ...(include.length || exclude.length
+        ? { tools: [{ type: "web_search", filters: { allowed_domains: include, blocked_domains: exclude } }] }
+        : {}),
+    };
+
+    const outcome = await calls.run({
+      kind: "answer",
+      label: "Answer",
+      intent,
+      invocation: call,
+      uncertainAdvice: reference => `Its outcome is unknown (record ${reference}); ask again only if you still need the answer.`,
+      send: async (parallel, { options }) => await parallel.post("/v1/responses", {
+        body,
+        ...(parallel.apiKey ? { headers: { Authorization: `Bearer ${parallel.apiKey}` } } : {}),
+        ...options,
+      }) as Record<string, unknown>,
+      settle: (response, reference) => {
+        const id = typeof response.id === "string" ? response.id : undefined;
+        if (!id) {
+          throw new UnusableResponse("uncertain", "response carried no id", `The answer came back incomplete (record ${reference}); ask again if you still need it.`);
+        }
+        const text = answerText(response);
+        if (!text.trim()) {
+          throw new UnusableResponse("failed", "response carried no answer text", `The answer came back empty (record ${reference}).`);
+        }
+        const { evidence, citations } = evidenceFromAnswer(text, annotations(response));
+        return { summary: oneLine(text, 120), providerRunId: id, rawResult: response, evidence, citations };
+      },
+    });
+
+    if (outcome.replayed) {
+      const { reference, run, hits } = outcome;
+      const first = hits.find(hit => hit.kind === "report") ?? hits[0];
+      // The stored answer is the body; leave room for the header and footer within the receipt budget.
+      const stored = first ? (await store.readEvidence(sessionId, first.handle, { limit: RECEIPT_LIMIT - 800 })).text : "";
+      const { text, details } = replayReceipt({ noun: "question", reference, state: run?.state ?? "unknown", hits, body: stored ? [stored] : [], listHits: !stored });
+      return { text, details: { ...details, handle: first?.handle } };
+    }
+
+    const { reference, settlement } = outcome;
+    const text = settlement?.evidence?.find(item => item.kind === "report")?.body ?? "";
+    const citations = settlement?.citations ?? [];
+    const report = outcome.evidence.find(item => item.kind === "report")?.handle;
+    const preview = answerPreview(text);
+    return {
+      text: [
+        preview.text,
+        "",
+        `Citations: ${citations.length} source link(s). Full answer: ${reference}.`,
+        `Ask a follow-up with web_answer { question, continue_from: "${reference}" }.`,
+        report ? `Read the stored answer with web_recall { handle: "${report}" }.` : undefined,
+        UNTRUSTED,
+      ].filter((line): line is string => line !== undefined).join("\n"),
+      details: {
+        reference,
+        handle: report,
+        sources: citations.length,
+        truncated: preview.truncated,
+        effort,
+        continued: previous !== undefined,
+      },
+    };
+  }
+
+  return { answer };
+}
+
+export type AnswerService = ReturnType<typeof createAnswerService>;