09 , sessions

Sessions

A session is the governance boundary around a single agent interaction. It tracks everything from the moment the agent starts working to the moment it finishes: what tools it called, how much budget it consumed, what its declared purpose was, and whether it stayed within bounds.

Sessions solve a fundamental problem: without them, an agent could accumulate unlimited cost or call volume across multiple interactions, and there would be no way to attribute decisions to a specific task. Sessions give you a container for accountability.

Every session has four properties: a unique ID, a purpose declaration (what the agent says it's doing), a budget envelope (maximum calls and cost), and a status (open, closed, or budget-exhausted). When the budget runs out, all subsequent tool calls within that session are denied immediately , the agent cannot bypass this by requesting more budget.

Session lifecycle

Open a session, execute governed tool calls within it, then close it. All decisions are attributed to the session for audit and cost tracking.

Open a session

Start a new session with a purpose and budget constraints.

faramesh session open \
  support-bot \
  --budget 200 \
  --ttl 30m

Close a session

Close the session when the task is complete. Remaining budget is released.

faramesh session close <agent-id>

List sessions

Show all active and recently closed sessions.

faramesh session list

Check budget

See how much budget remains in a session.

faramesh session budget <agent-id>

Inspect a session

Detailed session state including decision history and budget usage.

faramesh session inspect <agent-id>

Set purpose

Update the purpose declaration on an active session.

faramesh session purpose declare \
  <agent-id> \
  "escalated to billing dispute"