phi-agent 0.18.1

phi-agent — Rust AI Agent runtime framework: orchestration, sessions, streaming built-in. You define tools, prompts, domain knowledge.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

# Sessions & Snapshots

phi-agent manages conversation state through sessions and supports creating/restoring snapshots for long-running work.

## Sessions

Each conversation turn is tracked within a session. Sessions provide:

- **Isolation** — each session has its own conversation history
- **Persistence** — event logs written to `~/.phi-agent/sessions/<id>/` as JSONL
- **Locking** — file-based locks prevent concurrent modification
- **Cleanup** — expired sessions are automatically removed

### Session lifecycle

```
create_session() → run_turn() → run_turn() → ... → session expires → cleanup
```

Sessions are created automatically on first use and cleaned up after expiry (default: 50 sessions max, configurable in `base_agent_builder`).

### Event log

Every turn is persisted as JSONL in the session directory:

```
~/.phi-agent/sessions/<session-id>/
  turn-001.jsonl
  turn-002.jsonl
  turn-003.jsonl
```

Each line is a JSON object representing one event (text delta, tool call start, tool call result, etc.).

## Snapshots

Snapshots capture the full conversation state at a point in time. They are useful for:

- Saving progress before a risky operation
- Creating checkpoints in long-running tasks
- Sharing conversation state for debugging

### REPL commands

| Command | Description |
|---------|-------------|
| `/snapshot <name>` | Create a snapshot of the current session |
| `/snapshots` | List all snapshots (sorted by date, newest first) |
| `/session` | Show current session ID and metadata |
| `/events` | Show recent events from the current turn |
| `/tools` | List registered tools |

### Programmatic API

```rust
use phi_agent::SessionContext;

let ctx = SessionContext::new(&session_id);

// Create a snapshot
create_snapshot(&ctx, "before-refactor").await?;

// List snapshots
let snapshots = list_snapshots(&ctx).await?;
for snap in &snapshots {
    println!("{} - {}", snap.name, snap.created_at);
}

// Restore a snapshot
restore_snapshot(&ctx, "before-refactor").await?;

// Delete a snapshot
delete_snapshot(&ctx, "before-refactor").await?;
```

### Snapshot storage

Snapshots are stored alongside session data:

```
~/.phi-agent/sessions/<session-id>/
  snapshots/
    before-refactor.json
    after-migration.json
```

## Validation

Session IDs and snapshot names are validated:

- Session IDs: alphanumeric + hyphens + underscores, max 64 characters
- Snapshot names: alphanumeric + hyphens + underscores, max 128 characters