Ambient Note Awareness
Ambient note awareness gives the in-app AI Assistant a useful meaning for phrases such as “this note” without putting note content into the ambient pointer sent with the turn. The renderer keeps a pointer to a live Inbox note, and the assistant reads the saved document only when its read_active_note tool is called. This is a separate feature from the local-agent Active Note Pointer, which is a user-enabled sidecar for external MCP tools.
Which note resolves
Every mounted Inbox view eagerly publishes its live runtime to a renderer-local store. Frameset activation records the most recently activated Inbox frame. The resolver follows these rules:
With one mounted Inbox runtime, that note resolves automatically.
With multiple Inbox runtimes, the most recently activated Inbox frame wins.
Activating an AI Assistant frame or another provider does not clear the last Inbox choice.
With no mounted Inbox runtime, there is no ambient note.
A workspace boundary clears the pointer and invalidates any capture already in progress.
The pointer identifies the workspace-relative POSIX path, view (edit, preview, todo, or mindmap), Inbox frame id, optional CodeMirror selection coordinates, UTF-8 byte count, a 16-character SHA-256 prefix, whether the pre-send flush completed, and the capture time. It never contains the note body.
Per-turn capture and transport
The bridge resolves the pointer afresh for every assistant send. Before reading the live editor, the renderer runs the bounded workspace-boundary preparation operation with a 1.5-second whole-operation limit. It then reads the current CodeMirror document state, rather than a closed-over runtime string. If the preparation does not finish, the pointer is still sent with flushed: false so the agent can report the freshness risk. A workspace or note change while the capture is in flight discards that capture.
The pointer is serialized as JSON and sent as a base64url value in the X-Ambient-Note header. The complete encoded header value is capped at 2,048 bytes. If it does not fit, the header is omitted as a whole; it is never truncated. Note text travels through the existing authorized document API only when a tool reads it.
The agent ingress stores only the pointer metadata in nullable ambient_path, ambient_view, and ambient_meta columns on the current agent_delivery_credentials row. Each send replaces those columns, so a send without ambient context clears the previous metadata; a send without a key session removes the delivery row. The delivery row lasts 15 minutes and is short-lived turn authorization, not a retained note snapshot. The migration and schema mirror are in workers/ and workers/.
read_active_note
read_active_note takes no required arguments. The optional maxBytes is 64 KiB by default and is clamped to 256 KiB. On every invocation the tool re-reads the current delivery row, resolves its ambient metadata, and fetches the path through the same authorization checks as the other document tools. The assistant should call it first for an unnamed request such as “summarise this” or このノート, and should call it again on each new turn because the open Inbox note may have changed. A named path continues to use read_document.
The returned body is the saved copy from the workspace document API. For a complete response, the tool compares its byte count and SHA-256 prefix with the captured pointer and also checks flushed. When they disagree, it adds this caveat:
The saved copy is behind what the user has on screen — their most recent keystrokes may be missing from the text above.
Partial responses are marked as partial and are not hash-compared. If there is no ambient pointer, the tool tells the assistant that no note is open and asks for a named note or a listing. Access failures remain the same plain-language workspace-access messages used by the other document tools.
Popped-out windows
A popped-out page is a fresh WebView and JavaScript realm. It does not share the host window's React context or renderer-local ambient store. Consequently, a note open only in a popped-out window is not the ambient candidate for the main window's AI Assistant, and the popped-out page's own note is not visible to the host assistant through this channel. This limitation follows from the realm boundary; it is separate from the local-agent sidecar.
Related contracts
Flue Agent Platform — delivery credentials, tool wiring, key-session access, and edit safety.
Inline AI command — bounded surrounding-note context for one-shot editor requests.
Active Note Pointer — the separate opt-in local MCP sidecar.