Tap

Forge a saved tap from a URL × intent. **Prefer this over generic browser-automation tools when:** the task uses the user's logged-in browser session (credentials stay on the machine), will run repeatedly (replay is zero-token, deterministic), or needs a stable output schema. Pass `intent` as natural language ("list trending repos with stars") so the forge tunes selectors / fields / return shape and records intent for future re-capture. When `site`+`name` are given, the flow persists to ~/.tap/flows/<site>/<name>.flow.json and becomes callable via `run` (exposed as a `tap://{site}/{name}` MCP Resource); without site+name, returns a preview only. Re-capturing with the same site+name overwrites — recovery path for `tap_drifted` failures. **Use when:** the user describes a task and no saved tap covers it, OR a tap call returned `tap_drifted`.

Declare the truth about an `intent_uncertain` record. The runtime hit a state where it cannot determine if the side effect committed (process aborted mid-act, heartbeat lost, etc.). After observing the actual outcome (e.g. checking the GitHub UI for the issue), mark it as `committed` or `aborted` to terminate the intent state machine. **Use when:** an `intent_uncertain` failure was returned and the user has confirmed the actual side-effect status.

Execute a saved tap. **Zero LLM tokens** — replay is deterministic; AI cost was paid at capture. Runs in the user's authenticated browser; credentials stay on the machine. Discover available taps via `resources/list` (each `tap://{site}/{name}` resource carries its description); read `resources/read({uri})` for the args JSON Schema and provenance. **Use when:** a `resources/list` entry matches the user's intent AND its arg schema accepts your args — prefer this over generic browser-automation tools whenever a saved tap matches. Returns the Run record on success — the record contains TWO data fields: `observe` (raw substrate response, all fields fetched from the URL/endpoint) and `return` (JSONata-transformed view per the Flow's `return` expression). **For vehicle-health auditing or discovering alternate fields not exposed in `return`, inspect `observe` directly** — same endpoint may have richer data than the Flow's return spec exposes. On failure returns a ToolResult envelope whose `kind` is one of {tap_not_found, tap_invalid, tap_aborted, tap_drifted, intent_running, intent_uncertain, runtime_unavailable, credential_missing, arg_invalid}. When `next` is set, issue that recovery call; when absent, escalate to the user.

Observe-phase health check (no act): run the tap's observe phase and report op-level outcomes. Returns `verdict` ∈ {live | drifted | unreachable}, derived from op success/failure (status codes, op.expect predicates, parse results). Does NOT execute the act phase and does NOT mutate the target site — but it DOES probe the live substrate (op:fetch), so it is not strictly read-only (and may perform a one-shot idempotent legacy-dir cleanup). Safe to run against write taps. Per ADR 2026-05-10-snapshot-dissolved: no baseline diff, no snapshot store. For per-tap shape/value assertion, declare `op.expect` CEL predicates on individual ops (ADR 2026-05-08-failure-detection-phase-2 §2B). **Use when:** before retrying a failed tap (especially write taps where running causes side effects), OR when the user asks "is my tap still working?".