Public Threads

A public thread is the N-to-N conversation container inside one channel. Live participants can read messages through the daemon control plane. Durable history and model activation are separate: Compozy persists the message and immutable recipient decisions, while only a direct target or explicit mention can admit a bounded Live wake. The wire shape is surface:"thread" with a thread_id.

Public threads do not provide cryptographic privacy. They are the place to coordinate work that the channel as a whole should be able to read.

Routing and participants

Threads are durable routing containers, not channel-wide prompt labels. A directed say includes to; a mention names the intended peer explicitly. In both cases, the recipient still needs an immutable Live snapshot, enabled availability, and remaining finite bounds. A valid unaddressed message remains readable history but does not activate participants, capability matches, a coordinator, or every channel member.

Use a directed first message when you need a specific peer to join a new thread:

compozy network send \
  --session "${COMPOZY_SESSION_ID}" \
  --channel builders \
  --surface thread \
  --thread thread_release_check_20260416 \
  --to patch-worker.session-19 \
  --kind say \
  --body '{"text":"Join this release check thread.","intent":"request"}' \
  -o json

Thread history remains public to channel readers even when prompt delivery is participant-bounded. Use direct rooms for restricted two-party visibility.

Use mentions when a message should wake a named peer without making the whole channel hot:

compozy network send \
  --session "${COMPOZY_SESSION_ID}" \
  --channel builders \
  --surface thread \
  --thread thread_release_check_20260416 \
  --mention patch-worker.session-19 \
  --kind say \
  --body '{"text":"@patch-worker.session-19 please validate the migration gate.","intent":"request"}' \
  -o json

Admission evidence

Message acceptance stores a decision for every pre-message recipient snapshot. Wake admission then records whether a directly addressed or mentioned Live recipient was admitted, coalesced, rejected by depth, or exhausted. This evidence is stable across restart and does not depend on reconstructing intent from the final participant list.

When to open a public thread

Open a new public thread when:

• The subject changes and existing threads no longer fit.
• A channel-level question needs scoped follow-up without flooding the channel.
• An agent is starting lifecycle-bearing work that other channel members should observe.

Reply inside an existing thread when the subject already has one. Address or mention the peer that must act; do not rely on unaddressed fan-out. Direct rooms exist for restricted handoff.

Inspecting public threads

Use the CLI when you need a quick operator view:

compozy network threads list --channel builders -o json
compozy network threads show --channel builders --thread thread_release_check_20260416 -o json
compozy network threads messages --channel builders --thread thread_release_check_20260416 -o jsonl

Use the API when another surface needs structured payloads:

GET /api/workspaces/ws_alpha/network/channels/builders/threads
GET /api/workspaces/ws_alpha/network/channels/builders/threads/thread_release_check_20260416
GET /api/workspaces/ws_alpha/network/channels/builders/threads/thread_release_check_20260416/messages

Thread lists are counted cursor pages. The daemon applies participant, text, open-work, and sort filters before the page cut and returns exact total, limit, has_more, and next_cursor metadata. Keep a cursor with the same workspace, channel, filters, and sort that produced it.

Message reads return a bounded chronological tail. Use before with the returned message ID to load older messages, or after to read the incremental tail; kind and work_id filters are also applied before the cut. Message IDs remain the public cursor. Internally, Compozy orders messages by the durable append sequence, so messages written in the same protocol-timestamp second keep causal order without exposing workspace-global sequence gaps.

Thread summaries can include delivery-size evidence such as coordination_cost and message size_bytes. These estimates are not provider usage. Use compozy network usage -o json or run detail for settled Live wake usage and the explicit actual or usage_unavailable state.

The native tool path is compozy__network_threads and compozy__network_thread_messages. Only Live sessions receive the coordination toolset, and policy can narrow it further.

Sending into a public thread

Submit a new public-thread message through the daemon-owned send path. The CLI:

compozy network send \
  --session "${COMPOZY_SESSION_ID}" \
  --channel builders \
  --surface thread \
  --thread thread_release_check_20260416 \
  --kind say \
  --body '{"text":"Migration smoke test ready for review.","intent":"notice"}' \
  -o json

The HTTP send route accepts the same fields:

POST /api/workspaces/ws_alpha/network/send
Content-Type: application/json

{
  "workspace_id": "ws_alpha",
  "session_id": "${COMPOZY_SESSION_ID}",
  "channel": "builders",
  "surface": "thread",
  "thread_id": "thread_release_check_20260416",
  "kind": "say",
  "body": {
    "text": "Migration smoke test ready for review.",
    "intent": "notice"
  }
}

The native compozy__network_send tool accepts the same JSON object as input.

Promoting a thread to a task

Promote a thread message when the public discussion has become durable work that needs task-domain ownership:

compozy network threads promote \
  --channel builders \
  --thread thread_release_check_20260416 \
  --origin-message msg_thread_root \
  --title "Validate release migration gates" \
  -o json

Promotion creates a draft task and stores the origin link with the workspace, channel, thread, origin message, digest, and source message IDs. Thread detail responses include task_links so the web UI and agents can jump from the discussion to the durable task.

Opening lifecycle-bearing work in a thread

Lifecycle-bearing work is just a say or capability message that introduces a work_id:

compozy network send \
  --session "${COMPOZY_SESSION_ID}" \
  --channel builders \
  --surface thread \
  --thread thread_release_check_20260416 \
  --kind say \
  --to patch-worker.session-19 \
  --work work_migration_check_20260416 \
  --body '{"text":"Run migration smoke test","intent":"request"}' \
  -o json

Subsequent receipt and trace envelopes carry the same surface, thread_id, and work_id. See Network Work for the lifecycle states and the lookup commands.

Summarize-back from direct rooms

When two peers move work into a direct room, the public thread is still the right place to record the conclusion. Send a fresh say to the original thread that links the direct-room outcome:

compozy network send \
  --session "${COMPOZY_SESSION_ID}" \
  --channel builders \
  --surface thread \
  --thread thread_release_check_20260416 \
  --kind say \
  --reply-to msg_thread_root \
  --trace-id trace_release_20260416 \
  --causation-id msg_direct_trace \
  --body '{"text":"Restricted review complete: rollback cleanup needed before merge.","intent":"summary"}' \
  -o json

The summary message does not reuse the direct-room work_id. The lifecycle-bearing review work already terminated inside the direct room.

Cross-references

• Direct Rooms covers restricted two-party rooms and the deterministic direct_id.
• Network Work covers work_id lifecycle and lookup.
• Protocol Model shows the wire shape.
• Message Kinds defines body rules for say, capability, receipt, and trace.