webgcp.org / extensions / task-answer / v0.1-draft

Task Answer

org.webgcp/task-answer — webGCP extension, version 0.1 (draft)

DRAFT. Shipped by one implementation (the reference host's POST /webgcp/v0/answer). Field names and the outcome union are stable enough to build against; the extension identifier and this page are the compatibility contract.

1. Purpose

A host implementing this extension accepts one task in a webGCP §6.4-shaped envelope and returns exactly one of three typed outcomes:

an answer, produced by the cheapest tier that could honestly answer it, grounded in the host's pillar context where that materially improves the answer;
a directive, when the task is engagement-scale (must be cost-estimated before anyone commits) or contested (needs adversarial examination) — the host reports the committed path and spends nothing further;
a clarification request — at most one question, and only for user-owned ambiguity that no inspection could resolve.

Behind the door the host runs an escalator: an evaluation call picks the cheapest plausible starting rung, and structured insufficiency codes from each rung drive append-only escalation. That machinery is deliberately not part of this contract — only the outcome shapes, the provenance rules, and the discovery surface are normative.

2. Discovery

A host declares the extension in its /.well-known/webgcp descriptor and advertises the endpoint and the bundle contract:

{
  "endpoints":  { "answer": "https://<host>/webgcp/v0/answer", ... },
  "bundle_contracts_available": [
    { "contract_uri": "urn:webgcp:<host>:task-answer/v0.1",
      "url": "https://<host>/webgcp/bundles/task-answer-v0.1.json" } ],
  "extensions": {
    "org.webgcp/task-answer": {
      "version": "0.1",
      "spec": "https://webgcp.org/extensions/task-answer/v0.1-draft/" } }
}

3. Request

POST /webgcp/v0/answer
{
  "filter": { "query": "<the task text>" },          // required
  "budget": { "max_tokens": 150000, "budget_usd": 1.0 }, // optional, clamped by the host
  "bundle": { "contract_uri": "urn:webgcp:<host>:task-answer/v0.1" }  // optional pin
}

A pinned contract_uri the host does not serve returns the §6.7 manifest_mismatch typed failure. A missing or empty filter.query returns invalid_request (HTTP 400) — never kb_unavailable.

4. Outcomes

HTTP	`status`	`disposition`	meaning
200	`ok`	`answered`	`bundle.task_answer.value.answer` holds the answer; `value.answered_at_rung` names the tier that produced it
200	`ok`	`directive`	`value.directive` holds the committed path (an estimate-then-spawn wire, a deliberation referral, or a verifier-seat referral); `value.exhausted` is `true` when the ladder ran out without an answer
200	`needs_input`	—	`clarify` holds exactly ONE question; answer it and re-submit
200	`manifest_mismatch` / `out_of_scope`	—	§6.7 typed failures
400	`invalid_request`	—	malformed envelope (caller's fault, typed)
503	`kb_unavailable`	—	backend fault OR a governance refusal upstream (e.g. the host's daily metered spend quota) — typed, never silent

Free-form error / errorMessage fields never appear; the typed union above is the whole failure surface.

5. Provenance

Every task_answer bundle carries _meta with:

authority: "derived" — always. An LLM-produced answer is a derived view, never a canonical assertion.
receipt_ref — the host's sealed audit receipt for this evaluation, and rung_trace, metered_usd, llm_calls — the reconstructable-tier rule made caller-visible: what ran, in what order, at what cost.
verification_note, when present, flags an answer the caller can and should check mechanically (the host detected it is decidable by evaluation).
pillar_bundle, when present, is the attested context bundle hash + the skill list that grounded the answer (see the Attested Context extension).

6. Security posture

Caller-supplied authority never crosses. On an unauthenticated door the host pins the data classification of every forwarded task to its public tier; an envelope cannot assert a higher one.
Budgets are clamped host-side; the caller's numbers are requests, not commands.
Directives are inert data. Priced and deliberative work is committed work: the door returns the path, it never auto-spends down it.
The host's own spend governance (per-call budgets, daily metered quota) applies behind the door and surfaces as typed kb_unavailable, never as silent spend.

7. Known limitations and deferred work

Answer tiers can fabricate the contents of named-but-absent private material despite prompt-level prohibition; the structural mitigation is the pillar-citation surface in _meta. A grounding wall (citation-enforced answering) is deferred work.
Cost quotes inside priced directives are ADVISORY until the host's estimator is calibrated; quote: null is the honest cold-start value.
Long evaluations (30–130 s measured) require the host's front-end timeout to accommodate them; an async (202-plus-poll) variant is deferred until measurement shows the synchronous form failing at an edge.