A session binds an agent to one live browser tab. It is transport-level: it says which tab an agent controls, not who the user is. Application login is a separate, ordinary action.

​
Lifecycle

  1. The page opens and calls POST /__aim/session. The bridge returns a sessionToken and sets an HttpOnly aim_session cookie (Secure on HTTPS, SameSite=Strict).
  2. The page shows the token in an “agent instructions” panel. The human copies it to their agent. That copy is the explicit delegation.
  3. The agent sends Authorization: Bearer <token> on every request. The cookie aim_session=<token> also works.
  4. The session ends on expiry (at most one hour without renewal), on the disconnect action, or when the bridge restarts.
Agents should use the token the page displays, not mint their own with POST /__aim/session. A self-minted token isn’t bound to any tab, so actions that need browser state will fail with 409.

​
Tab ownership

Only one tab can own a session. The bridge uses a short tab lease (about 15 seconds). After a reload or navigation, the new tab may wait up to 15 seconds for the old lease to expire. If a session is attached to a different page than the one requested, the manifest request returns 409 naming the connected page. Open that page, or invoke disconnect and start a new session.

​
Application login

Login is application logic, exposed like any other action. In the demo:
  • Signed out: state.authenticated is false and only login is registered.
  • login takes {"username": "...", "password": "..."}. The server verifies it and attaches the identity to the existing session.
  • Signed in: the real actions appear. The agent never logs in again for each action.
  • logout returns to the login view without revoking the transport token.
The server rejects protected invocations even if a browser forges a snapshot claiming to be signed in.

​
Failing closed

An expired or invalid token returns 401. It never falls back to public state or to another session. Manifest responses are sent with Cache-Control: private, no-store and Vary: Cookie, Authorization.