Skip to main content

Sessions — attribution, and stopping an agent right now

Every sensitive action runs inside an attributable session: this agent, acting under this credential, within this window. That is what makes two things possible that a log line cannot — containment (there is something to terminate) and reconstruction (there is something to replay).

What a session carries​

FieldWhy it is there
agentId, serviceTokenIdWhich agent, under which credential
principalWho the agent is acting for
purpose, environmentThe declared reason and blast radius
policySetHashThe rules in force when the session opened, so a historical decision can be replayed against them
startedAt, expiresAt, actionsThe window, and how much happened inside it
statusactive · expired · terminated

Every decision returns its session and seals it into evidence:

{ "decision": "allow", "allowed": true,
  "session": { "sessionId": "ses_9f2…", "status": "active", "actions": 14 } }

The lifecycle rule​

expired    → rolls over to a fresh session
terminated → DENIED, and never rolls over

Expiry is normal operation: an agent working past the TTL should not need an operator. Termination is sticky — a kill switch a retry loop can undo is not a kill switch.

Sessions bind to the credential, not merely the agent, because the credential is the unit an operator actually cuts. Restoring a contained agent is therefore a deliberate act — issue it a new credential — rather than something that happens by itself once the TTL lapses.

The kill switch​

# stop one session
curl -s -XPOST "$API/v1/sessions/ses_9f2…/terminate" -H "Authorization: Bearer $TOKEN" \
  -d '{"reason":"suspected prompt injection"}'

# stop every live session for an agent
curl -s -XPOST "$API/v1/sessions/agents/aid_71d…/terminate" -H "Authorization: Bearer $TOKEN" \
  -d '{"reason":"agent compromised"}'

# what is live right now
curl -s "$API/v1/sessions/registry?activeOnly=true" -H "Authorization: Bearer $TOKEN"

Properties that matter when you are actually using this under pressure:

  • The next action is denied immediately. The session gate runs before the policy path, so containment does not depend on policy being configured.
  • Monitor Mode does not soften it. An operator pulling the switch is not a policy outcome.
  • A reason is required, and the termination is sealed with the operator who did it — containment is itself a security decision someone must answer for.
  • It is idempotent. Containment gets retried under pressure; a second call is a no-op, not an error.

Reconstruction​

curl -s "$API/v1/sessions/ses_9f2…/events" -H "Authorization: Bearer $TOKEN"

Returns the session's decisions, detections and credential activity in order — each carrying the policy-set hash that produced it, inside the hash-chained evidence ledger.

See also​