Thread Management in AgentServer v2.0

January 03, 2026

This document clarifies the thread ID system, subthreading mechanics, and internals. It supplements the Core Architectural Principles — hierarchical dot notation examples there reflect the wire format.

Wire Format: Hierarchical String IDs

Mandatory <thread/> contains a server-assigned hierarchical string (dot notation, e.g., "root", "root.research", "root.research.images").
Root IDs: Short, opaque, server-generated (e.g., "sess-abcd1234").
Sub-IDs: Relative extensions for readability.
Benefits: LLM/human-friendly copying, natural tree structure for logs/GUI.

Server Assignment Only

The organism assigns all final IDs — agents never invent them.

Root initiation: Client suggests or server auto-generates on first message; uniqueness enforced.

Subthread spawning: Explicit reserved payload for intent clarity:

<spawn-thread suggested_sub_id="research">  <!-- optional relative label -->
  <initial-payload>  <!-- optional bootstrap fragment -->
    <!-- any valid payload -->
  </initial-payload>
</spawn-thread>

Core handler:

Appends label (or auto-short if omitted).
Resolves uniqueness conflicts (append "-1" etc.).
Creates queue + seeds bootstrap.

Always responds in current thread:

<thread-spawned 
  assigned_id="root.research" 
  parent_id="root"
  message="Thread spawned successfully."/>

Error Handling (No Silent Failure)

Unknown <thread/> ID → no implicit creation.

Always inject system error into parent thread (or root):

<system-thread-error 
  unknown_id="root.badname"
  code="unknown_thread"
  message="Unknown thread; emit <spawn-thread/> to create or correct ID."/>

LLM sees error immediately, retries without hanging.
Logs warning for monitoring.

Internals

Per-thread queues: dict[str, Queue].

Scheduling via organism.yaml:

thread_scheduling: "breadth-first"  # or "depth-first" (default: breadth-first)

Depth from dot count.

Optional hidden UUID mapping for extra safety (implementation detail).

Design Rationale

Explicit spawn = clear intent + bootstrap hook.
Mandatory feedback = no LLM limbo.
Readable IDs = easy copying without UUID mangling.
Server control = sovereignty + no collisions.

Future: Alias registry, thread metadata primitives.

The organism branches reliably, visibly, and recoverably.

2.4 KiB Raw Blame History