Skip to content

Agent sessions

This page explains what an agent session is in TOVIO, why it is the unit fleet operators reason about, and how renewals of a long-running job collapse into one session rather than many. It is explanation, not a how-to — for the commands, see capability tokens and the MCP server.

The MCP edge and coordination registry are implemented

Capability tokens, secret_clearance, provenance, the MCP server, the coordination session registry, overlap detection/events, and project-context reporting of overlapping intents run today. Each Node/MCP write session now injects a server-generated correlation ID into every commit it creates. Coordination remains advisory, and a complete fleet dashboard remains future work. This page distinguishes the implemented registry from the broader intended fleet model.

What a session is

An agent session is one connection of one agent identity, bound to exactly one capability token, working on one task. When an agent presents its token to the MCP server, the server validates it once and opens a session bound to that single agent identity. From then on the session carries no privilege beyond the token — every tool call re-presents the token and is re-checked from scratch.

The shape of a session, then, is simple and deliberately narrow:

  • One agent. The session acts only as the bound entity=agent identity. There is no ambient human identity to borrow — unlike the CLI, the MCP server has no login of its own.
  • One token. A session is pinned to a single token. Its scope, its operations, and its deadline are exactly the token's. The session cannot outlive the token's expires_at.
  • One task. The token carries a task_id and an optional task_description. A session is the live execution of that one bounded task.

A single agent may hold several concurrent sessions — for example, one per worktree, each with its own token. Those sessions share nothing but the underlying repository; each is enforced independently.

human ── issues ──▶ capability token ── presented at connect ──▶ agent session
                    (one task, one deadline)                     (one agent, one token)

"One agent, one task, one day"

Operators do not want to count raw MCP connections — a flaky network or a process restart would make that number meaningless. The unit that matters is one agent doing one task, observed over a working period (think: one agent, one task, one day). That is the granularity at which coordination, auditing, and any future reporting are meant to make sense.

This framing keeps the human in control of the mental model. When you ask "what are my agents doing?", the answer is a list of tasks in flight, each tied to a token you issued and a human who authorized it — not a churn of low-level socket events.

Why renewals are deduplicated

Tokens are never indefinite (that is the safety backstop — see expiry and renewal). A long job — an overnight refactor, a large migration — will outlive its first token and must renew to keep going. Renewal is a deliberate re-issue of a fresh token with equal-or-narrower scope, linked to the prior token through provenance.

If each renewal counted as a new session, a single overnight task would look like a dozen sessions by morning. That is wrong: it is still one agent, one task. So the session model deduplicates across renewals — the renewal chain is one continuous session, not many.

The mechanism is provenance. A renewed token references its predecessor (token_issue audit event naming the prior token_id), so the chain of tokens for a task is reconstructable. A session that renews its token mid-flight stays the same logical session; the deduplication follows the token lineage.

Renewal keeps the deadline real

Deduplication is about identity, not about removing the deadline. Each token in the chain still expires on its own; the job renews proactively (well before expiry) so the active operation always runs under a valid token. An expired token still fails closed — see capability tokens.

Coordination across sessions

Because the unit is "one agent, one task", TOVIO can reason about what happens when two tasks touch the same code. A session declares the path globs it intends to work on — and, from provenance, the base it works against (working_against) — with tovio agent intent declare --token <id> <globs>; the declaration is a short-TTL visibility signal (one hour by default, --ttl in seconds) that registers the session with the Forge, which runs an overlap detector across the active sessions of that repository. It returns advisory coordination overlaps to the declaring agent, and emits an agent.intent_overlap event into the Forge's event log, when two sessions:

  • declare overlapping path scopes (path_scope), or
  • overlap a scope another session holds an advisory lease on (leased_scope), or
  • build on bases that have diverged (diverged_base).

A declaration that a lease soft-blocks is the one case that records nothing: the Forge returns the overlaps with soft_blocked set and refuses the registration outright, so no session is stored and no event is emitted until the agent retries with --force.

{
  "kind": "path_scope",
  "other_session": "cap_9d22…",
  "other_agent": "did:tovio:agent/cgm-sync",
  "detail": "src/integrations/cgm/**"
}

Warnings are advisory by default — they never block. An orchestrator may use them to serialize or re-scope its sub-agents. A session can request a time-bounded lease on its declared globs (--lease): a peer entering a leased scope gets the stronger leased_scope warning, and — only if the repository's coordination policy requires it — is soft-blocked, a refusal the peer may consciously override with --force. The default posture is calm: TOVIO tells you two agents are near each other and lets you decide, rather than halting work.

Overlap detection runs in the Forge

The session registry and the overlap detector behind POST /coord/sessions are Forge features and ship with it; a declaration is also recorded locally under .tovio/intents/, which is what tovio agent intent check and intent list read, so a Forge that is unreachable never blocks the declare. Over MCP, project_context reports overlapping peer intents from that local record only, and labels every one path_scope --- the Forge detector's leased_scope and diverged_base findings, and any peer registered from another machine, are not visible there. The MCP contract's target of a coordination_warnings field in one combined connect handshake, and its third rule (a dependency another session's base relies on being mutated, which needs a semantic-graph query), are not returned yet.

What this means for fleet operators

If you run many agents, the session model gives you a clean operational picture:

  • A bounded list of tasks, each tied to a token, a model, and a human authorizer — not a stream of connections.
  • Stable identity across renewals, so a long task is one line on a dashboard, not a growing pile.
  • Advisory coordination, so concurrent agents are visible and steerable without a global lock.
  • A full audit trail, because every session's writes are provenance-stamped back to a human (see capability tokens).

Where this connects

Last reviewed September 9, 2026

Suggest an improvement to this page Not for security reports — see disclosure