# 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

```json
{
  "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:

```bash
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:

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

This makes your workflows auditable and debuggable.

***

### Switching Between Roles

Want to try a different agent configuration?

```bash
npx pilso start -r developer
```

To list available roles:

```bash
npx pilso roles list
```

To add a new one:

```bash
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:

```bash
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pil.so/roles-and-sessions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.