Event reference

The event taxonomy, the JSON envelope shared by all events, and per-browser URL capture support.

Every event Tadoru records — regardless of source — shares one OS-independent JSON envelope. The stable schema is the core asset of the project: capture backends may change per OS, but the shape your tools consume does not.

Event envelope

One event per line (NDJSON) in raw outputs (query --format jsonl, record, export):

{
  "v": 1,
  "id": "evt_01J...",
  "ts": "2026-08-16T12:34:56.789Z",
  "mono_ns": 128374651234,
  "source": "macos.ax",
  "type": "window.focus",
  "app":    { "name": "Safari", "bundle_id": "com.apple.Safari", "pid": 501 },
  "window": { "title": "Design doc", "id": 42 },
  "element":{ "role": "AXButton", "title": "Send", "value": null },
  "data":   { },
  "redaction": { "applied": true, "rules": ["email"] }
}

This envelope is also published as a machine-readable JSON Schema at /schema/event.schema.json — the single contract all surfaces share, and the file the Rust core’s types are tested against.

Event taxonomy

The current event types. The Permission column shows what must be granted for the type to be captured (see the permissions guide).

In --types filters, a trailing wildcard selects a whole family: browser.*, ui.*, and so on.

type is deliberately an open set, not a closed enum: future platforms and versions may add types without a version bump, and consumers must skip unknown types rather than error.

Per-type payloads

What each type carries in data, and whether the envelope’s window / element are present (✓) or null (—). The normative definitions live in the JSON Schema as per-type conditions.

field_kind classifies the focused input field: text / search / url / email / number / other, or null when focus is not on a text-like element. There is no password value — secure fields are excluded before an event exists.

input.key in detail

The exact shape of “fact of typing + field type by default, content opt-in”:

A shortcut is an action, not content — so combo is recorded without opt-in. It is a primary timeline ingredient (saves, commits, tab switches).

Coalescing guarantees

Events are coalesced before they reach the store, so consumers never see raw key-repeat or scroll floods:

Shortcuts and ui.click never coalesce (one action = one event). Coalescing buffers are always flushed on pause, stop, and batch flush — no events are lost.

What text_content changes

Only content (what you typed or copied) is opt-in. Facts of use (shortcuts, clicks, URLs, titles) are recorded by default:

Schema versioning

• Additive changes (new fields, new types, new sources) do not bump v. Consumers must ignore unknown fields and skip unknown types.
• Breaking changes (removal, rename, meaning change) bump v, with a store migration to match.

Browser URL capture

browser.navigate (URL capture) currently supports Chrome only. The reason is a privacy guarantee: Chromium exposes each window’s mode (normal / incognito) deterministically via AppleScript, which lets Tadoru make a hard promise — Incognito windows are always excluded from URL capture, with no configuration knob needed.

Safari/Firefox support may come later, but only if a genuinely reliable private-mode detection mechanism exists.

Two layers of data

• Raw event layer — complete and machine-readable; what query, record, and export return.
• Timeline layer — human/LLM-readable; session splitting, dedup, coalescing, token-budgeted serialization. What timeline and get_timeline return.

Timeline sessions carry event_ids back-references to the underlying raw events. They are included only in the JSON format (--format json), and are dropped when the output must be coarsened to fit the token budget.