Skip to content

Sessions

How sessions work

A session begins when you run fuseraft run. The orchestrator:

  1. Generates an 8-character hex session ID (e.g. a3f92c1d)
  2. Saves a checkpoint to ~/.fuseraft/sessions/<sessionId>.json after every agent turn
  3. Streams responses to the terminal as they arrive
  4. Marks the session complete when the termination strategy fires

If the run is interrupted for any reason (network error, Ctrl+C, process kill), the checkpoint is already saved up to the last completed turn.

Resuming a session

# Show a list of incomplete sessions and choose one
fuseraft run --resume

# Resume a specific session by ID
fuseraft run --resume a3f92c1d

The orchestrator re-injects the prior history into the group chat and continues from the next agent turn. The model receives the full conversation context (or a compacted summary if compaction fired).

You can resume with a different config or task — the session ID is what ties the checkpoint to the run, not the config file.

Session files

Sessions are stored at ~/.fuseraft/sessions/<sessionId>.json with owner-only read/write permissions (Unix mode 0600).

Checkpoint fields:

Field Description
SessionId 8-character hex identifier
Task Original task string
ConfigPath Path to the orchestration config used
Messages All agent messages produced so far
StartedAt UTC timestamp when session was first created
LastUpdatedAt UTC timestamp of the most recent update
IsComplete true once the session has run to completion

Message fields:

Field Description
AgentName Agent name, or "Human" for HITL injections
Content Text content of the response
Timestamp UTC timestamp
TurnIndex Zero-based turn index within the session
Role "assistant" for agent turns, "user" for HITL injections
Usage Token counts and estimated cost (null for HITL turns)
IsCompactionSummary true if this message is a compaction summary

Managing sessions

# List all incomplete sessions
fuseraft sessions

# List all sessions including completed
fuseraft sessions --all

# Delete a session by ID
fuseraft sessions --delete a3f92c1d

# Purge all completed sessions
fuseraft sessions --delete all

Human-in-the-loop (HITL)

Run with --hitl to pause after every agent turn and review before continuing:

fuseraft run --hitl "Refactor the payment module"

After each turn you see:

[HITL] Press Enter to continue, type a message to inject it, or 'q' to quit:
Input Effect
Enter Continue to the next agent turn
Any text Inject that text as a user message, then continue
q Save checkpoint and exit cleanly

Injected messages are saved in the session checkpoint with Role: "user" and AgentName: "Human". They are re-injected on resume so the conversation context is complete.

Token tracking and cost estimation

Token counts and estimated costs are tracked per turn and accumulated for the session.

Costs appear in --verbose mode and in the --output transcript. The total session cost is displayed when the run completes.

Per-turn data:

Field Description
InputTokens Tokens in the model's input (prompt + history)
OutputTokens Tokens in the model's output
CostUsd Estimated cost for this turn in USD

Cost cap: Set MaxCostUsd in the config to stop the run before the next turn if cumulative cost exceeds the limit. The session is saved and can be resumed later.

MaxCostUsd: 2.50

Custom pricing: Override or extend the built-in pricing table by creating ~/.fuseraft/pricing.json:

{
  "my-model-id": [0.001, 0.003]
}

Values are input and output price per 1,000 tokens in USD. If a model is not in the table, tokens are counted but cost shows as —.

Conversation compaction

Long-running sessions will eventually exceed the model's context window. Compaction automatically summarizes old turns to keep the session alive indefinitely.

Compaction:
  TriggerTurnCount: 30
  KeepRecentTurns: 8

How it works:

  1. When the message count reaches TriggerTurnCount, compaction fires.
  2. An LLM call summarizes all turns except the most recent KeepRecentTurns.
  3. The old turns are replaced by a single summary message.
  4. The checkpoint is saved with the compacted history.
  5. The session continues with the summary providing context for older work.

TriggerTurnCount must be greater than KeepRecentTurns. An error is thrown at startup if this constraint is violated.

Compaction model: By default, the first agent's model is used for generating summaries. Override with Compaction.Model:

Compaction:
  TriggerTurnCount: 50
  KeepRecentTurns: 10
  Model:
    ModelId: gpt-4o-mini

Cost accounting: The summary message's cumulative cost includes all the turns it replaced, so budget tracking remains accurate after compaction.

Saving transcripts

Write the full session transcript to a Markdown file:

fuseraft run --output my-session.md "Build a CLI todo app"

The file includes every agent turn with agent name, timestamp, content, and per-turn token/cost data. Useful for review, sharing, or archiving completed sessions.