Roles & Sessions

PILSO OS uses a role-based session model that gives you fine-grained control over how LLM agents behave, what tools they can access, and how long they maintain state.

Each agent session is scoped to a single role, which acts like a secure sandbox:

“You are this type of agent. Here are your tools. Stay within these boundaries.”

---

What is a Role?

A role in PILSO defines an agent’s identity, capabilities, and behavioral limits. Think of it like an AI-powered user account with a job description.

Defined in your pilso-roles.json, each role includes:

Field	Description
name	The role identifier (e.g. "signer", "developer")
description	Human-readable explanation of what the agent is for
tools	A list of MCP tool methods the role is allowed to use
goals	Natural-language prompts describing what the role should achieve
guardrails	Explicit behavioral constraints injected into the system prompt

---

Example: Role definition

{
  "signer": {
    "description": "An agent responsible for signing transactions using MetaMask.",
    "tools": ["metamask.sign"],
    "goals": [
      "Sign prepared transactions securely",
      "Ensure all transactions are reviewed before submission"
    ],
    "guardrails": [
      "Never initiate token transfers",
      "Always explain what you're signing",
      "Never deploy contracts"
    ]
  }
}

---

Starting a Role Session

Once your role is defined in pilso-roles.json, you can start a session using:

npx pilso start -r signer

This launches a live agent CLI with:

• The specified role (signer)

• All scoped tools loaded

• Your selected LLM connected

• Memory initialized for that session

---

What is a Session?

A session is a live runtime context between:

• An LLM (agent)

• A set of tools (MCP servers)

• A defined role

• The user's active prompt stream

Sessions track:

• Prompt history

• Tool call logs

• Agent decisions

• CLI environment state

All session data is saved inside:

.pilso/session-logs/{timestamp}.json

This makes your workflows auditable and debuggable.

---

Switching Between Roles

Want to try a different agent configuration?

npx pilso start -r developer

To list available roles:

npx pilso roles list

To add a new one:

npx pilso roles add deployer

Each session is completely sandboxed per role — no cross-contamination, no memory bleed.

---

Persistent vs Ephemeral Sessions

Mode	Behavior
Ephemeral	Default. Memory is wiped when the session ends.
Persistent	Coming soon. Agent memory (e.g. seen tools, known chains) persists across sessions.

---

Security via Role Boundaries

Roles are your first line of defense against LLM misuse. They:

• Scope the agent's available tools

• Shape the system prompt to guide intent

• Prevent actions like signing, deploying, or transferring unless explicitly allowed

Well-structured roles = safer agents.

---

Debugging Sessions

Every agent session is logged. You can inspect session histories with:

npx pilso sessions list
npx pilso sessions view <session-id>

Or just open the .json file in ./.pilso/session-logs/.

These logs include:

• All prompts + replies

• All MCP tool calls and responses

• Any signing events

This helps with auditing, testing, and fine-tuning roles.

Roles give your agents structure. Sessions bring them to life — safely, repeatably, and with full visibility.