Threads API

Threads are Pioneer’s durable conversation containers. A thread belongs to a workspace, has a mode, stores its turns, and appears in the workspace tree unless it is hidden. Chat clients render threads directly; task and subagent flows often create hidden threads that remain durable and auditable. The protocol separates thread data from sidebar layout. Use thread/get for one thread, thread/history for replay, and thread/tree for the complete workspace tree.

Methods

Method	Params	Result	Purpose
`thread/start`	`ThreadStartParams`	`ThreadStartResponse`	Create or open a thread.
`thread/get`	`ThreadGetParams`	`ThreadGetResponse`	Load one thread.
`thread/tree`	`ThreadTreeParams`	`ThreadTreeResponse`	Load threads, folders, and placements for a workspace.
`thread/history`	`ThreadHistoryParams`	`ThreadHistoryResponse`	Replay persisted thread events.
`thread/timeline/page`	`ThreadTimelinePageParams`	`ThreadTimelinePageResponse`	Load a paginated semantic timeline block page for a thread.
`thread/move`	`ThreadMoveParams`	`ThreadMoveResponse`	Move a thread within the tree.
`thread/folder/create`	`ThreadFolderCreateParams`	`ThreadFolderCreateResponse`	Create a folder.
`thread/folder/move`	`ThreadFolderMoveParams`	`ThreadFolderMoveResponse`	Move a folder.
`thread/folder/delete`	`ThreadFolderDeleteParams`	`ThreadFolderDeleteResponse`	Delete a folder.
`thread/unsubscribe`	`ThreadUnsubscribeParams`	`ThreadUnsubscribeResponse`	Stop receiving live notifications for a thread.

Starting a thread

Clients provide the thread id. This supports reconnect and optimistic UI flows: the client can create local state immediately and reconcile it with the gateway response.

{
  "jsonrpc": "2.0",
  "id": "aaaaaaaaaaaaaaaaaaaaa",
  "method": "thread/start",
  "params": {
    "thread_id": "thr_000000000000000001",
    "workspace_id": "ws_000000000000000001",
    "name": "Architecture review",
    "model": "gpt-5.1",
    "model_provider": "openai",
    "mode": "Agent",
    "sandbox": "FullAccess",
    "origin_kind": "user",
    "sidebar_visibility": "visible"
  }
}

Important fields:

Field	Meaning
`thread_id`	Client-provided stable id.
`workspace_id`	Workspace that owns the thread.
`name`	Optional display name.
`model`, `model_provider`	Optional defaults used by turns in this thread.
`mode`	`Chat` or `Agent`. Chat is plain assistant conversation; Agent enables tool and task orchestration.
`sandbox`	Legacy thread sandbox display field. Current value is `FullAccess`; turn-level permission and sandbox/resource behavior is controlled by `permission_profile` in Turns API.
`origin_kind`	`collaborative`, `direct_message`, `user`, `task_run`, or `system`. `collaborative` threads run Composer submissions as detached task work; the other origins use foreground Composer execution.
`sidebar_visibility`	`visible` or `hidden`. Hidden threads are useful for subagents and internal task runs.
`agent_nickname`, `agent_role`	Optional labels for agent/subagent threads.

mode and sandbox are PascalCase because they are Rust enum variants without snake-case renaming. origin_kind and sidebar_visibility are snake-case strings.

Thread modes

Chat and Agent are part of the thread model, not separate APIs. A client starts turns the same way in both modes through turn/start; the gateway decides which execution path to run. In Chat mode the gateway focuses on conversation with the selected model. In Agent mode the gateway can compile richer context, expose tools, call MCP servers, invoke skills, create tasks, and coordinate subagents. Clients should show the mode clearly because it changes what a user should expect from a turn.

Composer execution mode

Thread origin also determines how a Composer submission is admitted:

Thread origin	Composer execution	Product meaning
`collaborative`	`detached_task`	Each submitted request runs independently in a child conversation. The parent timeline receives a live task card and the result is delivered back when ready.
`direct_message`	`foreground_turn`	The Composer request runs in the current conversation.
`user`, `task_run`, `system`	`foreground_turn`	Compatibility and internal origins that keep foreground Composer behavior.

Clients should render the resolved execution behavior from the thread contract. Do not infer it from sidebar visibility: a hidden task thread and a visible collaborative thread have different roles, but both are gateway-owned execution state.

Reading one thread

{
  "jsonrpc": "2.0",
  "id": "bbbbbbbbbbbbbbbbbbbbb",
  "method": "thread/get",
  "params": {
    "thread_id": "thr_000000000000000001"
  }
}

Use thread/get when opening a thread by id or reconciling after a notification. The response contains the durable thread row with its workspace id, mode, model defaults, status fields, and timestamps.

Workspace tree

thread/tree is the primary method for a sidebar or thread picker. It returns related collections: threads, folders, placements, and AGENTS.md summaries. Do not sort threads by timestamps and call it a tree; folder placement is stored separately.

{
  "jsonrpc": "2.0",
  "id": "ccccccccccccccccccccc",
  "method": "thread/tree",
  "params": {
    "workspace_id": "ws_000000000000000001"
  }
}

Response shape:

{
  "workspace_id": "ws_000000000000000001",
  "threads": [],
  "folders": [],
  "placements": [],
  "agents_docs": []
}

Placements let the gateway preserve UI structure across clients. agents_docs contains content-free summaries for root and folder AGENTS.md files. If another client moves a thread or changes an AGENTS.md file, your client should refresh the tree after thread/tree/changed. See AGENTS.md API for reading and editing full file content.

Moving threads and folders

Use move methods for tree edits instead of mutating local order and hoping the gateway catches up.

{
  "jsonrpc": "2.0",
  "id": "ddddddddddddddddddddd",
  "method": "thread/move",
  "params": {
    "workspace_id": "ws_000000000000000001",
    "thread_id": "thr_000000000000000001",
    "folder_id": "fld_000000000000000001"
  }
}

Folder methods follow the same shape: create a folder under a workspace, move it to a different parent, or delete it. Folder deletion is a layout operation; clients should refresh thread/tree afterward to render the gateway’s resulting state.

Thread history

thread/history returns durable protocol events as well as final assistant messages. Use it to rebuild a thread timeline after reconnect, crash recovery, or opening a thread on another device.

{
  "jsonrpc": "2.0",
  "id": "eeeeeeeeeeeeeeeeeeeee",
  "method": "thread/history",
  "params": {
    "thread_id": "thr_000000000000000001",
    "limit": 200
  }
}

History events include turn starts, item starts, streamed deltas, item completions, retries, recovery events, tool-loop budget events, and terminal turn events. For current rendering, prefer thread/timeline/page for semantic thread blocks and Turns API turn/work/page for expanded turn work; use thread/history when you need to rebuild from the thread level. thread/history is not the semantic recall API. It gives clients durable events so they can render and recover UI. It should not be used to dump an entire old thread into a model prompt. For agent-side “what did we discuss earlier?” behavior, Pioneer uses thread episodic context internally: visible conversation material is indexed, searched, filtered, and inserted as bounded prompt snippets when recall decides it is useful. That layer is configured through settings and described in Thread Episodic Context.

Semantic timeline page

thread/timeline/page is the paginated, semantic timeline read API used by shared client timeline reducers. It returns display-oriented blocks rather than raw event rows.

{
  "method": "thread/timeline/page",
  "params": {
    "threadId": "thr_000000000000000001",
    "anchor": { "kind": "newest" },
    "limit": 40
  }
}

anchor is a TimelinePageAnchor: newest, oldest, before, after, or around. Cursor-based anchors carry a cursor.value. The response includes workspaceId, threadId, projectionVersion, blocks, and page. Blocks can represent:

Block kind	Meaning
`user_message`	User input, text, and attachment chips.
`turn_work`	Collapsible work block for a turn, with state and pagination cursors.
`detached_task_run`	A background Composer request represented as a task card, with task status and child-conversation linkage.
`assistant_message`	Assistant-visible answer block.
`turn_state`	Terminal or intermediate turn state block.
`pending_request`	Runtime-native pending request block, such as a CLI approval/input prompt.

Use thread/timeline/page for scrollable client timelines. Use thread/history when you need durable event replay. Generated schemas:

/schemas/thread_timeline_page_params.json
/schemas/thread_timeline_page_response.json
/schemas/thread_timeline_blocks_changed_notification.json
/schemas/timeline_page_anchor.json
/schemas/timeline_page_info.json
/schemas/timeline_block.json
/schemas/timeline_block_kind.json

Unsubscribing

{
  "jsonrpc": "2.0",
  "id": "fffffffffffffffffffff",
  "method": "thread/unsubscribe",
  "params": {
    "thread_id": "thr_000000000000000001"
  }
}

Use this when a client closes a thread view but keeps the WebSocket connection open. It reduces live event fan-out; it does not delete the thread or its history.

Notifications

Event	Meaning
`thread/started`	A thread was created/opened.
`thread/updated`	Thread metadata changed.
`thread/closed`	Thread was closed.
`thread/tree/changed`	The workspace thread tree changed and should be reloaded.
`thread/agents_doc/changed`	A root or folder AGENTS.md file changed and affected tree summaries or effective instructions.
`thread/timeline/blocks/changed`	A semantic timeline block page may be stale; reload affected blocks or the current page.

Thread notifications are not a replacement for read methods. Treat them as invalidation and streaming hints, then call thread/get, thread/tree, thread/history, thread/timeline/page, turn/work/page, or turn/work/items/get as needed.

Introduction

Workspace & Threads

Features

Methods

Starting a thread

Thread modes

Composer execution mode

Reading one thread

Workspace tree

Moving threads and folders

Thread history

Semantic timeline page

Unsubscribing

Notifications

​Methods

​Starting a thread

​Thread modes

​Composer execution mode

​Reading one thread

​Workspace tree

​Moving threads and folders

​Thread history

​Semantic timeline page

​Unsubscribing

​Notifications

Methods

Starting a thread

Thread modes

Composer execution mode

Reading one thread

Workspace tree

Moving threads and folders

Thread history

Semantic timeline page

Unsubscribing

Notifications