wehub-resource-sync
138 lines
3.3 KiB
Markdown
138 lines
3.3 KiB
Markdown
# Sessions and History
|
|
|
|
Sessions are durable OpenSquilla conversations. They let you inspect past work,
|
|
resume a conversation, export a transcript, or stop a turn that is still
|
|
running.
|
|
|
|
Use sessions when you want to:
|
|
|
|
- continue a previous chat from the CLI or Web UI;
|
|
- find the session key for an artifact, cost report, or channel thread;
|
|
- export a transcript for debugging or sharing;
|
|
- abort a long-running turn without deleting the session;
|
|
- delete old sessions after you no longer need them.
|
|
|
|
## Requirements
|
|
|
|
Session commands use the gateway RPC surface. Start or connect to the gateway
|
|
before running most session commands:
|
|
|
|
```sh
|
|
opensquilla gateway run
|
|
```
|
|
|
|
Or use the managed background gateway:
|
|
|
|
```sh
|
|
opensquilla gateway start --json
|
|
opensquilla gateway status
|
|
```
|
|
|
|
## List Recent Sessions
|
|
|
|
```sh
|
|
opensquilla sessions list
|
|
opensquilla sessions list --limit 20
|
|
opensquilla sessions list --status idle
|
|
opensquilla sessions list --agent main
|
|
opensquilla sessions list --channel telegram
|
|
opensquilla sessions list --since 2026-05-01
|
|
```
|
|
|
|
Use `--json` for scripts:
|
|
|
|
```sh
|
|
opensquilla sessions list --json
|
|
```
|
|
|
|
## Inspect a Session
|
|
|
|
```sh
|
|
opensquilla sessions show <session-key>
|
|
opensquilla sessions show <session-key> --json
|
|
```
|
|
|
|
The output includes the resolved session key, agent id, status, model, update
|
|
time, title, and the latest preview when available.
|
|
|
|
## Resume a Session
|
|
|
|
```sh
|
|
opensquilla sessions resume <session-key>
|
|
```
|
|
|
|
This opens terminal chat on the existing session. Use it when you want to keep
|
|
the same conversation state instead of starting a fresh chat.
|
|
|
|
## Abort a Running Turn
|
|
|
|
```sh
|
|
opensquilla sessions abort <session-key>
|
|
opensquilla sessions abort <session-key> --json
|
|
```
|
|
|
|
Abort stops the running turn if one exists. It does not delete the session.
|
|
|
|
## Export a Transcript
|
|
|
|
Export Markdown:
|
|
|
|
```sh
|
|
opensquilla sessions export <session-key>
|
|
opensquilla sessions export <session-key> --output session.md
|
|
```
|
|
|
|
Export JSON:
|
|
|
|
```sh
|
|
opensquilla sessions export <session-key> --format json --output session.json
|
|
```
|
|
|
|
Exported transcripts are useful for bug reports, audits, or moving a task into a
|
|
document. Remove secrets, private local paths, provider tokens, and private
|
|
channel identifiers before sharing an export publicly.
|
|
|
|
## Delete a Session
|
|
|
|
```sh
|
|
opensquilla sessions delete <session-key>
|
|
opensquilla sessions delete <session-key> --yes
|
|
```
|
|
|
|
Deleting a session is for cleanup. Export first if you may need the transcript
|
|
later.
|
|
|
|
## Web UI Workflow
|
|
|
|
The Web UI uses the same session system. In the control console, use the chat
|
|
session selector to switch sessions, inspect status, and continue recent work.
|
|
|
|
Open:
|
|
|
|
```text
|
|
http://127.0.0.1:18791/control/
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
If commands cannot reach the gateway:
|
|
|
|
```sh
|
|
opensquilla gateway status
|
|
opensquilla doctor
|
|
```
|
|
|
|
If old context appears summarized, the session may have compacted older
|
|
history. This is normal for long sessions under context pressure. Export the
|
|
session when exact text matters.
|
|
|
|
Read next:
|
|
|
|
- [`features/compaction-and-cache.md`](features/compaction-and-cache.md)
|
|
- [`web-ui.md`](web-ui.md)
|
|
- [`operations.md`](operations.md)
|
|
|
|
---
|
|
|
|
[Docs index](README.md) · [Product guide](../README.product.md) · [Improve this page](contributing-docs.md) · [Report a docs issue](https://github.com/opensquilla/opensquilla/issues/new?template=docs_report.yml)
|