Sharing Sessions

TF Code can share an entire session — messages, tool parts, file diffs, and model metadata — to the ToothFairyAI Knowledge Hub, then retrieve it later from any machine. Shares are stored as JSON documents under the tfcodeSession folder, so they appear in the Knowledge Hub alongside your other uploaded files.

This replaces the older chat-only share with a lossless document-based flow: the round-tripped session reconstructs the full transcript, including tool calls and code changes.

What gets stored

A shared session is one JSON document:

Field	Contents
session	Session metadata (id, title, timestamps, …)
messages	Every message with its info and parts (tool calls)
session_diff	The cumulative file diff for the session
models	The models used across the session

Prerequisites

Sharing uses your ToothFairyAI workspace credentials (API key + workspace ID). Set them as environment variables, or configure them via tfcode setup:

export TF_WORKSPACE_ID="your-workspace-id"
export TF_API_KEY="your-api-key"
export TF_REGION="au"   # au | eu | us

Share from the TUI

In an interactive session:

/share

This uploads the full session to the tfcodeSession folder, records the share, and copies a link to your clipboard:

https://app.toothfairyai.com/workspaces/<workspaceid>/mrc_contents/<docId>

Stop sharing at any time:

/unshare

/unshare deletes the document (and its S3 object) from the Knowledge Hub.

Retrieve from the TUI

Available from the splash screen or inside any session, two slash commands bring shared sessions back:

• /shared opens a searchable picker listing every session in your tfcodeSession folder. Select one to import it and jump straight into the reconstructed session.
• /import prompts for a share URL or bare document ID, imports that session, and opens it.

Both reuse the same retrieve-and-write flow as the CLI, so the rehydrated session keeps its full message history, tool parts, and diffs.

Retrieve from the Web UI

In the web app command palette (and / slash menu), look for:

• Browse shared sessions — same picker as the TUI /shared, listing your Knowledge Hub sessions.
• Import shared session — paste a share URL or document ID to import it.

The imported session opens in a new session tab.

List and retrieve from the CLI

List every session you've shared:

tfcode session shared
tfcode session shared --format json

Retrieve a shared session into a local session — pass either the share URL or the bare document ID:

tfcode import https://app.toothfairyai.com/workspaces/<workspaceid>/mrc_contents/<docId>
tfcode import <docId>

The retrieved session rehydrates with its full message history and diffs.

HTTP API

When running in Server Mode, the shared-session endpoints are:

Method	Path	Description
POST	/session/:id/share	Share a session
DELETE	/session/:id/share	Unshare a session
GET	/shared	List shared session documents
GET	/shared/:docId	Retrieve a shared session
POST	/shared/:docId/import	Retrieve and import a shared session
DELETE	/shared/:docId	Delete a shared session document

GET /shared/:docId returns the full structured session ({ doc, data }) where data is the lossless payload above. POST /shared/:docId/import does the same retrieval, writes the session into the local database, and returns { id } — the new local session id. The TUI and Web commands call this endpoint.

How it works under the hood

Each share runs a presign → upload → register flow against the ToothFairyAI public API:

1. Presign — GET /documents/requestPreSignedURL?filename=<workspaceid>/<sessionID>.json&contentType=application/json
2. Upload — PUT the session JSON to the returned uploadURL
3. Register — POST /doc/create with external_path set to the S3 filePath, folderid: "tfcodeSession", and type: "readComprehensionFile"

Retrieval reverses it: look up the document (/doc/get/{id}), get a presigned download URL (/documents/requestDownloadURLByWorkspace), and fetch the JSON.

The tfcodeSession folder id is whitelisted by the training-data API as a system folder, so programmatic uploads group together in the Knowledge Hub without colliding with user-created folders.