Module watcher_session 

Watcher agent (synaps agent) session accounting and turn driving.

The agent’s [limits] (session tokens, cost, time, tool calls, and the daily cost cap) are enforced by the ENGINE inside each turn: before every turn the role budget is narrowed to what the session has left (SessionAllowance::turn_budget), so the engine stops the turn at a round boundary with a valid history and a typed BudgetExceeded. Calls past the tool-call allowance get the engine’s synthetic refusal result, not a cancel; in-budget calls of the same parallel batch still run.

drive_turn meters one turn’s stream into SessionTotals: usage is priced with the runtime’s pricing table (cache reads and writes included), tool calls are counted when they produce a result (a refused call is not counted), and a clean exit is recorded only when the watcher_exit tool reports that the handoff was saved.

Structs

SessionAllowance

A session’s limits plus what was already spent today before it started.

SessionTotals

What one watcher session has used so far.

TurnReport

How one watcher turn ended.

Enums

SessionLimit

A watcher session limit.

Constants

HANDOFF_PROMPT

The prompt for the turn that asks for a handoff after a session limit.

HANDOFF_TIMEOUT

How long the post-limit handoff turn may run.

TURN_DEADLINE_GRACE

Extra time past the session time limit before a turn still running is cancelled. The engine stops a turn at the next provider call once the session time is used up; this deadline only catches a turn stuck in a long tool round (a slow command, a timeout: 0 subagent).

Functions

drive_turn

Drain one turn’s stream, metering it into totals. model prices usage events that do not name their model. on_event sees every event after it was metered (for logging).

push_user_prompt

Append a user prompt to messages without creating two consecutive user messages: a turn that ended on its tool results (a budget stop) already ends with a user message, which then gets the prompt as a text block.

run_handoff_turn

After a session limit: ask for the handoff in one more turn, bounded by HANDOFF_TIMEOUT and the role’s per-turn limits, and metered into totals like every other turn (it is real spend).

run_session_turn

One turn of a watcher session, as synaps agent runs it: the role budget narrowed to what the session has left.

run_turn

Run one turn of runtime over messages under budget, metered into totals; messages becomes the turn’s final history. A signal cancels the turn; so does deadline (the handoff turn’s backstop).

usage_cost

Price one request’s usage with the runtime’s pricing table (the same one the engine’s turn cost budget uses), cache reads and writes included.

watch_turn

Watches one streaming turn: cancels it on SIGINT/SIGTERM, or once deadline passes, as a host stop (canceled tool results say so, not “by user”). Exits when the turn ends. Session limits are otherwise enforced by the engine inside the turn.