Polpo records everything — chat history, agent transcripts, event logs, and per-run activity. This data powers the TUI dashboard, the web UI, and post-mortem analysis.
Chat Sessions
When you interact with Polpo via the TUI, the OpenAI-compatible endpoint (POST /v1/chat/completions), or the REST API, your messages are persisted in chat sessions. This means you can close the terminal, reopen it, and your conversation history is still there.
How It Works
- When you send your first message, Polpo creates a new session
- The session title is set to the first 60 characters of your first message
- Every message (yours and Polpo’s responses) is saved with a timestamp
- If you reopen the TUI within 30 minutes, the previous session is automatically resumed
- After 30 minutes of inactivity, a new session starts
Session Data
Each session stores:
| Field | Description |
|---|
id | Unique session ID |
title | First 60 chars of the first message |
createdAt | When the session started |
updatedAt | Last message timestamp |
messageCount | Total messages in the session |
TUI Commands
| Command | Description |
|---|
/sessions | Browse past sessions, view messages, delete sessions |
REST API
| Method | Path | Description |
|---|
POST | /v1/chat/completions | Talk to Polpo (OpenAI-compatible, primary endpoint) |
GET | /chat/sessions | List all sessions |
GET | /chat/sessions/:id/messages | Get messages for a session |
PATCH | /chat/sessions/:id | Rename a session ({ title: string }) |
DELETE | /chat/sessions/:id | Delete a session |
Session Events
| Event | When |
|---|
session:created | New chat session started |
message:added | Message saved to a session |
Agent Transcripts
When Polpo spawns an agent, it creates a session transcript — a JSONL file recording every message, tool call, and result in the agent’s conversation.
Session Reader
Polpo can read agent transcripts to extract structured summaries:
| Field | Description |
|---|
sessionId | Agent session ID |
transcriptPath | Path to the JSONL file |
messageCount | Total messages in the transcript |
toolCalls | List of tool names the agent called |
filesCreated | Files the agent created |
filesEdited | Files the agent edited |
lastMessage | Last assistant message (truncated to 300 chars) |
todos | TODO/FIXME items found in agent output |
errors | Errors encountered during execution |
Connecting Tasks to Transcripts
Each AgentHandle can carry a sessionId. When a task is running, you can use the /inspect TUI command or the REST API to access the agent’s transcript in real-time.
Agent transcripts are recorded automatically for all agents. Full JSONL logs are written to .polpo/logs/.
Pruning
Sessions accumulate over time. The SessionStore interface includes a prune(keepSessions) method that deletes all but the N most recent sessions. This can be called programmatically or through the TUI session manager.
Event Log
Every event Polpo emits is captured in a persistent LogStore. Each time Polpo starts, it creates a new logging session.
Log Entries
Each log entry contains:
| Field | Type | Description |
|---|
ts | string | ISO timestamp |
event | string | Event name (e.g. task:created, agent:spawned) |
data | object | Full event payload |
Log Sessions
Events are grouped by session (one per Polpo start):
| Field | Type | Description |
|---|
sessionId | string | Unique session ID |
startedAt | string | ISO timestamp |
entries | number | Total log entries in this session |
Storage
- File-based (default): JSONL files in
.polpo/logs/
- SQLite: Alternative via
"storage": "sqlite" in settings
Viewing Logs
| Where | How |
|---|
| TUI | /logs command, or the Logs tab |
| REST API | GET /logs (list sessions), GET /logs/:sessionId (entries) |
| React SDK | useLogs() hook |
High-frequency events like orchestrator:tick are excluded from log persistence to avoid noise.
Agent Activity Tracking
While an agent is working on a task, Polpo tracks its activity in real-time. This data feeds the live dashboard, stale detection, and health checks.
Activity Fields
| Field | Type | Description |
|---|
lastTool | string | Name of the last tool called (e.g. Write, Bash) |
lastFile | string | Last file path touched |
filesCreated | string[] | Files created during this task |
filesEdited | string[] | Files edited during this task |
toolCalls | number | Total tool invocations |
totalTokens | number | Cumulative LLM token usage |
lastUpdate | string | ISO timestamp of last activity |
summary | string | Latest output snippet |
sessionId | string | Agent session ID (for transcript access) |
How Activity Flows
- The runner polls the engine for activity every 1500ms
- Changes are written to the RunStore (so Polpo can read them)
- Polpo reads activity on each tick (every 5s) and emits
agent:activity events
- The TUI and Web UI consume these events for live updates
Stale Detection
If lastUpdate hasn’t changed for longer than staleThreshold (default: 5 minutes), Polpo emits an agent:stale event and may kill the agent.
Per-Run Activity Logs
Every runner writes a detailed JSONL activity log to .polpo/logs/run-<runId>.jsonl. This is a more granular record than Polpo’s event log — it captures individual tool calls, transcript messages, and activity snapshots.
Each line is a JSON object. The first line is a header:
{"_run": true, "runId": "abc123", "taskId": "task-1", "agentName": "backend-dev", "startedAt": "2025-02-15T14:00:00Z", "pid": 12345}
{"ts": "2025-02-15T14:00:05Z", "event": "activity", "data": {"toolCalls": 3, "filesCreated": ["src/db.ts"], "lastUpdate": "..."}}
{"ts": "2025-02-15T14:00:06Z", "type": "assistant", "message": {"role": "assistant", "content": [...]}}
Entry Types
| Type | Description |
|---|
_run (header) | Run metadata: runId, taskId, agentName, startedAt, pid |
activity | Activity snapshot (deduplicated — only written when data changes) |
| Transcript entries | Raw engine messages (assistant text, tool_use, tool_result) |
| Custom events | Lifecycle events logged via logEvent() |
Viewing Run Logs
| Where | How |
|---|
| REST API | GET /logs/:sessionId or task activity endpoint |
| React SDK | useTaskActivity(taskId) hook |
| Files | .polpo/logs/run-<runId>.jsonl |
Per-run logs are invaluable for debugging why an agent failed or made unexpected decisions. They capture the full agent conversation including every tool call input and output.
