Module agent 

Agent protocol — shared types used by both the daemon (tsafe-agent) and the client (tsafe-cli open_vault_via_agent).

Security model

• The agent holds the vault password in memory, zeroized on drop.
• Access requires the session token plus a requesting_pid claim that matches the real peer PID on the IPC transport.
• The daemon enforces the TTL chosen at tsafe agent unlock; expired sessions reject new requests and clear their socket state on exit.
• The named pipe is \\.\pipe\tsafe-agent-{agent_pid}.
• The TSAFE_AGENT_SOCK env var carries {pipe_name}::{session_token_hex}.
• A state file (agent.sock in the data dir) persists the sock address so processes that do not inherit TSAFE_AGENT_SOCK (e.g. VS Code background terminals) can still reach a running agent.

Wire protocol

Request and response are newline-terminated JSON objects written over the named pipe. One request → one response per connection.

Structs

AgentSession

AgentSessionOutcome

CellRecord

Immutable record established on the first Resolve for a cell.

Enums

AgentRequest

AgentResponse

AgentSessionState

CellState

Lifecycle state of a tracked cell in the daemon’s in-memory cache.

CellosRequest

Requests sent by the CellOS broker over TSAFE_SOCKET.

CellosResponse

Responses from the daemon over TSAFE_SOCKET.

Constants

ENV_AGENT_SOCK

Set by tsafe agent unlock after the user approves. Format: {pipe_name}::{session_token_hex}

ENV_CELLOS_SOCK

Path for the CellOS broker Unix socket. Overridden by TSAFE_SOCKET.

Functions

agent_sock_path

Path to the agent socket state file. Written by the daemon on startup; deleted on exit. Allows processes that don’t inherit TSAFE_AGENT_SOCK to find a running agent.

cellos_socket_path

Resolve the CellOS broker socket path: $TSAFE_SOCKET or ~/.tsafe/agent.sock.

clear_agent_sock

Delete the agent state file (called on daemon exit).

format_agent_sock

Build the value to put in TSAFE_AGENT_SOCK.

parse_agent_sock

Parse TSAFE_AGENT_SOCK into (pipe_name, session_token_hex).

ping_agent

pipe_name

read_agent_sock

Read the agent socket address from the state file. Returns None if missing.

read_agent_sock_env

request_password_from_agent

send_lock

write_agent_sock

Write the agent socket address to the state file so other processes can find it. File is restricted to owner-only on Unix (it contains the session token).