Conversations

Everything you do in Fabric Agents happens inside a session. A session is one conversation: your messages, the agent's responses, the tools it ran, and the state around them (labels, status, permissions, the current model). Sessions live per workspace.

Anatomy of a session

Each session has:

• An ID generated as a human-friendly slug — 260111-swift-river, 260420-amber-forest. Dates are YYMMDD.
• A title — auto-generated from your first message (3-5 words) or manually set.
• A status — todo, in-progress, needs-review, done, cancelled, or any custom status defined in your workspace. See Statuses.
• Labels — tags with optional typed values. See Labels.
• A permission mode — Explore, Ask to Edit, or Execute. Can change mid-session.
• A model and connection — the LLM provider/model this session runs on. The connection is locked after the first message; the model can change freely.
• A thinking level — off, low, medium, high, or max. Maps to Anthropic's extended thinking or Pi's reasoning_effort.
• A working directory — where shell commands and file tools resolve paths.

A flag, a read pointer, and timestamps for created / last-used / last-message round things out.

Turns

A turn is one user → assistant round trip. You send a message; the agent streams back text, may call tools (Read, Edit, Bash, MCP tools, API tools), receives the tool results, and continues until it's done. The whole thing is one turn in the UI. The next user message starts the next turn.

There's no fixed turn object on disk — turns are implied by the sequence of message roles: user → assistant (optionally with tool / tool-result messages interleaved) → next user.

Where conversations live

Every session is stored at:

~/.fabric-agent/workspaces/{workspace-id}/sessions/{session-id}/

Inside that folder:

Because it's JSONL, the app can list hundreds of sessions instantly by reading only the first ~8 KB of each file (the header line). Messages only load when you open the session.

Writes are atomic — the app writes to a temp file and renames. If the app crashes mid-write, you get the old session, never a half-written one.

Streaming and interruption

The agent's response streams to the UI over a WebSocket as it's generated. You can interrupt at any point:

• Stop button in the chat — clears isProcessing once the current event loop drains.
• Shift+Tab to cycle the permission mode — some mode transitions pause for a handoff (e.g., Explore → Execute can route through plan approval).
• Plan submission in Safe mode pauses execution until you approve or decline.
• Credential / OAuth prompts pause until you paste the credential or complete the OAuth dance.

If you interrupt mid-turn, the next message you send carries a "user interrupted" hint in the context so the agent knows to adapt.

Resumption

Fabric Agents remembers where every session was. When you restart the app, the inbox repopulates from disk, any in-flight isProcessing state is cleared, and you can keep going.

If the session already had an SDK session ID (assigned by Claude or Pi on the first turn), the agent resumes from that point — you don't lose context. Queued messages that arrived during a crash are re-delivered.

Sleep / wake doesn't reload sessions; it reconnects the WebSocket to the server. For long-running work, pair this with a remote workspace so the server keeps running even when your laptop closes.

Archive vs delete

• Archive — the session disappears from the inbox but stays on disk. You can unarchive later; nothing is lost.
• Delete — wipes the session directory completely. Not recoverable.
• Clear messages — keeps the session (name, status, settings) but starts a fresh conversation with a new SDK session ID.

The app can also archive sessions automatically once they go idle past a threshold (off by default). See Auto Behaviours → Auto-archive idle sessions.

Titles

When you send the first message of a session, Fabric Agents asks a small model to generate a 3-5 word title from the message, then sanitises it for filesystem safety. If you set a title yourself before the first message, that's what you get — the app won't overwrite it.

You can rename a session any time from the session menu.

Per-session settings

These persist with the session and can change mid-conversation unless noted:

Branching

You can fork a session at any message — creates a new session that shares history up to the cutoff. Useful for exploring a "what if" without losing the original thread.

Context overflow

Long conversations eventually run past the model's context window. Anthropic-direct sessions auto-compact at ~77.5% via the SDK; Pi-routed sessions (OpenAI, Codex, Gemini, OpenAI-compat) are recovered automatically by Fabric Agents — the failed message is removed from history, /compact runs, the message resends. See Auto Behaviours → Auto-compact.

Oversized tool results (base64-heavy files)

A single Read of a base64-heavy file used to push a session past the model's window in one go, after which every retry came back invalid_request. Fabric Agents now estimates tokens density-aware (chars/1.5 when ≥70% of a ≥20 KB tool result is unbroken base64), spills earlier (12 000-token threshold), and routes generic context overflows to a dedicated "Context Window Exceeded" error that recommends /compact or starting a new session — instead of the older misleading "remove attachments" advice. Attachment-related hints only fire now when the API actually mentions image/format problems or your last turn included attachments.

1M-context tier

The 1M-context tier-specific hints (context-1m / tier) are routed separately and ask you to either disable Extended Context (1M) under Settings → AI → Performance or upgrade your Anthropic tier — they no longer collide with generic overflows.

Related

• Interactions — how to drive the conversation from the keyboard
• Auto Behaviours — prompt enhancer, auto-compact, auto-archive, auto-status-transition
• Permissions — Explore vs Ask vs Execute behaviour
• Sharing — publish a session to a public /s/{id} link