Module ambient 

Ambient Model Call (AMC) gateway — the single mandatory path for every non-user-driven (“ambient”) model call in the backend: cheap, background LLM calls that augment the UX (e.g. summarizing what an agent is doing for the pane header / Swarm tree) rather than answering a user’s own turn. See docs/specs/SPEC_AMBIENT_MODEL_CALLS_FRAMEWORK_2026_07_03.md.

Every ambient call is keyed by (entity_id, purpose) and carries a caller-supplied generation (monotonic per entity — e.g. a turn counter). The gateway:

• cancels a lower-generation in-flight call for the same key the moment a higher-generation one is admitted (real subprocess cancellation via the returned CancellationToken, not just a discard-on-arrival check)
• rejects a request whose generation is not strictly greater than the highest one already admitted for that key (stale-on-arrival — the caller does no work at all, not even a discarded one)

This does NOT track token usage itself — callers record usage through the normal per-call-site accounting path (tagged by purpose), same as any other RPC result. The gateway’s job is coalescing/cancellation only.

Modules

call

The one path every ambient Haiku call takes: admit through the gateway, optionally wait for a concurrency permit, do the caller’s own preparation, then run the CLI and judge the reply.

cli

The Claude CLI subprocess behind every ambient call: spawn it as bare text generation, race it against cancellation and a timeout, and parse its stream-json reply.

digest

What a model is shown of a pane’s recent conversation: a bounded digest read from the block’s output file, with hidden memory-reinjection turns removed.

limits

How many ambient CLI calls may run at once. AmbientGateway coalesces and cancels only within one (entity, purpose) key; without a cap, N panes finishing a turn at the same moment would each spawn their own CLI.

outcome

One outcome per ambient call, logged and counted.

prompt

One place for the wording every ambient Haiku call shares, so the plain-text rules, the “this is data, not a conversation” framing and the reply format aren’t copy-pasted (and drifting) across each call site.

purpose

Every ambient purpose, in one place: its tag (the second half of an AmbientCallKey, the outcome-log purpose and the token-usage category), how long its CLI call may run, and which queue it waits in. Each caller keeps its OWN purpose: two callers under one purpose cancel each other.

reply

The reply format an ambient call asks for, and the one reader of it.

sanitize

Strips the formatting a model wraps around its whole reply. Whether what is left is usable is the reply format’s question (reply), then the purpose’s own check (validate).

spend

Tells the frontend what every ambient call spent, for the status bar’s token totals.

tasks

The background and one-shot ambient Haiku callers: pushed and per-definition activity summaries, subagent and workflow-batch names, and narration. Each is best-effort — every failure path returns None and the caller carries on without. They all go through call::admit / Slot::run, so admission, cancellation, concurrency caps and reply validation are the same for each.

title

Where a session title is stored, and when a new one replaces the old.

validate

What a well-formed answer must still satisfy. The reply format (reply) has already turned away anything that isn’t an ANSWER: or SKIP; these checks judge the answer text itself: its size, and whether it is a real title (a stored one too, from an older build), or a safe suggestion.

Structs

AmbientCallGuard

Held for the duration of one admitted ambient call.

AmbientCallKey

Identifies one class of ambient call for a specific entity, e.g. (block_id, "activity_summary"). purpose is a short stable string — also suitable for tagging cost/usage dashboards by call category.

AmbientGateway

GatewayState 🔒

InFlight 🔒

Enums

Admission

Outcome of admitting a request for a key at a given generation.

Statics

GATEWAY 🔒

Functions

gateway

The process-wide ambient-call gateway singleton.