Quickstart · Real agent cases · Harness support · Documentation · 简体中文
Stop babysitting parallel coding agents.
ThreadMesh routes completion, blockers, review findings, and verified dependency state to the right agent session at a safe checkpoint—without making you copy results, spend model turns polling status, or let one session silently take over another.
The agent supplies the initiative. ThreadMesh supplies the boundary.
Important
ThreadMesh is pre-alpha and disabled-by-default infrastructure. The current release is suitable for local, trusted-process experiments—not production authorization, hostile prompts, or multi-tenant deployment.
The walkthrough is generated from a fresh executable demo and retained real Codex evidence. It is not presented as a live screen recording. The local demo models the same four-handoff workflow two ways: the manual path requires at least one kickoff, four status checks, and four relay actions; the ThreadMesh path requires one kickoff and zero later relay or polling actions. Elapsed time and model tokens are deliberately marked not measured until a network-valid live baseline is retained. A real operator-triggered control arm has now measured the nine actions and completed with exact cleanup; its same-condition ThreadMesh arm failed closed at an ambiguous reviewer turn, so no speed or token-saving claim is made.
It also exercises the safety failure people worry about: when B is already
running, the completion stays pending in a checkpoint-offer; B remains
running, and the demo starts zero steer, interrupt, or native-turn operations.
Watch the MP4 · inspect asset provenance · run the proof yourself
Running several agents in parallel often gives the user three extra jobs:
- clipboard: notice A has the result B needs, then copy and explain it;
- poller: repeatedly ask whether review, verification, or a dependency is finished, consuming time and model quota even when nothing changed;
- traffic controller: decide whether to queue, wake, steer, or interrupt B without enough visibility into B's current work.
ThreadMesh makes that handoff an explicit, portable capability:
- the host authorizes a relationship between exact task incarnations;
- B publishes a minimal relationship-scoped summary—not its private history;
- A may inspect that summary and autonomously decide whether to act;
- A can send one typed, expiring suggestion with provenance;
- B's harness accepts, rejects, or defers it before model-context admission;
- the decision and delivery chain stays auditable.
The intelligence is not “agents can send messages.” Transport is increasingly available from harness-native APIs, ACP, and A2A. ThreadMesh focuses on selective initiative: speak when a dependency is real, remain quiet when it is not, verify before unlocking downstream work, and preserve the receiver's agency.
Our real Pi evaluation gave Agent A only two bounded ThreadMesh tools and tested three conditions:
| Condition | What Agent A chose | Receiver effect |
|---|---|---|
| Relevant dependency | discover once → suggest once | B accepted and completed |
| Unrelated task | discover once → stay silent | B was not activated |
| No related task (control) | use no ThreadMesh tool | zero interference |
The same relevant path then crossed products: Pi 0.84.2 → ThreadMesh →
Kimi Code 0.38.0. Pi chose to contact B; Kimi retained its own persistent
session and admission boundary; the coordinator recorded context-admitted;
and every temporary resource was deleted. A separate real Codex CLI 0.145.0
→ Kimi Code 0.38.0 case produced the same autonomous discover → suggest
sequence.
Read the case portfolio · Reproduce the Pi-to-Kimi path · Inspect the bounded evidence
The current deterministic fixture demonstrates a deeper form of session
initiative than a one-message handoff. The user starts A once; after that,
durable lifecycle attention drives the bounded chain
A → R → same-A → V → dependent. The fixture runner dispatches no phase,
submits no phase prompt, relays no message manually, and polls no session.
ThreadMesh routes only exact next events, while each receiving session selects
its registered decision and business tools. After the one kickoff, the pump
starts eight protected native turns: a decision and admitted business turn for
each of R, same-A, V, and dependent. An authorized but irrelevant session
receives no claim and runs no turn.
This matters because useful work can continue across session boundaries without the user noticing and copying every intermediate dependency. It is evidence of bounded, policy-mediated session initiative—not a claim of emergent intelligence. The dependent turn starts only after the accepted event and fixture-trusted finalization are durable; an injected finalization failure starts zero dependent turns. Every created role, journal, SQLite file, and private run directory is then checked and removed exactly.
The evidence boundary is intentionally narrow. The result reports
liveProductEvidence=false, deterministicPolicyOracle=true,
externalIndependentVerifier=false, and a fixture-owned ephemeral signer.
As of #122, selection and
publication recovery are durable per dispatch, with leased and fenced
publication. There is still no global cross-dispatch selection chain:
selectionChainValid=null.
The sixth real Codex event-pump attempt completed that same autonomous chain. After one kickoff, nine real bound native turns carried the work through R, the original A session, V, and the dependent. The runner supplied zero later phase prompts or direct activations; the irrelevant session ran zero turns; five of five temporary sessions and all coordinator artifacts were removed.
The completed result is deliberately classified state=blocked and
liveProductEvidence=false. #133
binds bounded Git worktrees and a process-isolated child verifier into the
correlated path on main. A process-scoped, certificate-
verified local proxy restored normal Codex connectivity on 2026-09-02. The
merged real-effects rerun now completed the full A → R → same-A → V →
dependent chain: one kickoff, nine bound native turns, zero later runner prompts
or direct activations, real bounded Git worktrees, process-isolated verification,
an irrelevant zero-turn control, and exact cleanup. The gate still reports
blocked/liveProductEvidence=false because the operator-supplied executable
lacks trusted binary provenance and the complete measured baseline plus
real-product repetition gates remain open; this is not presented as complete
M5.2 acceptance. The deterministic M5.3 relevant 3/3, irrelevant,
stale/unverified, restart/replay, and failure-cleanup matrix passes. New
harness, transport, and generalized protocol work remains frozen until the
measured manual/live baseline and three external setup attempts close.
Read the exact fixture evidence · Read the real Codex behavior · Read the real-effects checkpoint · Read the M5.2 scenario guide · Read the measured baseline attempt
npx --yes --package=github:fyaic/threadmesh threadmesh demoOr run from source:
git clone https://github.com/fyaic/threadmesh.git
cd threadmesh
npm ci
npm run demoThis deterministic demo creates four workflow sessions plus one isolated active-receiver safety task. It runs an implementation → review → fix → review → dependent-task sequence and exposes the event, routing reason, receiver decision, fixture-signed verified disposition, dependency effect, and cleanup state without spending model quota or touching your agent sessions.
Read the attention-router demo guide
Run the earlier model-selection control/relevant/irrelevant comparison next:
npm run validate:behavior:fakeRun the smallest cross-harness proof next:
npm run validate:cross-harness:fakeThe package is not on npm yet. Install the pre-alpha SDK directly from GitHub:
npm install github:fyaic/threadmeshConnect it to an authenticated ThreadMesh JSON-RPC transport, then create one bridge per native model turn:
import {
createProactiveToolBridge,
createThreadMeshClient,
} from "@fyaic/threadmesh";
const client = createThreadMeshClient({
authorization: `Bearer ${process.env.THREADMESH_TOKEN}`,
send: async (request, { authorization }) => {
const response = await fetch(process.env.THREADMESH_URL, {
method: "POST",
headers: { authorization, "content-type": "application/json" },
body: JSON.stringify(request),
});
return response.json();
},
});
const bridge = createProactiveToolBridge({
client,
source: currentTask,
relationships: [{ relationshipId, target: relatedTask }],
});
await harness.runModelTurn({
tools: bridge.tools,
onToolCall: bridge.handleToolCall,
});The host—not the model—selects the bounded relationship set. Discovery is required before sending; the default budget allows one lookup and one suggestion; the receiving harness still controls context admission.
30-minute integration guide · complete sender/receiver example · SDK reference by example
| Capability | What ThreadMesh provides today |
|---|---|
| Relationship-scoped discovery | Minimal summaries for exact host-authorized task relationships |
| Bounded proactive suggestion | Two model tools with per-turn discovery and send budgets |
| Receiver sovereignty | Mailbox checkpoint with explicit accept, reject, or defer |
| Freshness and replay defense | Exact task incarnation, expiry, revision, idempotency, and claim checks |
| Provenance and audit | Sender, relationship, reason, disposition, admission, and cleanup evidence |
| Harness portability | Transport-neutral SDK plus ACP, App Server, and subprocess adapter experiments |
| Fail-closed negotiation | Unsupported steer or interrupt behavior is not silently approximated |
The draft protocol distinguishes four coordination intents:
| Intent | Default behavior | Typical use |
|---|---|---|
notify |
Side-channel information; not active prompt context | Progress or dependency update |
suggest |
Receiver mailbox; explicit checkpoint decision | Peer advice or a missing input |
steer |
May change active direction; requires stronger authority | Parent-to-child correction |
interrupt |
Requests typed cancellation; highest privilege | Safety stop or invalidated work |
Only bounded suggest is enabled in the real product experiments.
ThreadMesh coordinates tasks, so the model provider and harness can differ on each side.
| Harness / integration | Role exercised | Evidence level |
|---|---|---|
Pi 0.84.2 extension |
Real proactive sender through the packaged public SDK | Real model pass |
Codex CLI 0.145.0 App Server |
Real proactive sender and receiver | Real model pass |
Kimi Code 0.38.0 ACP |
Persistent receiving session | Real model pass |
Gemini CLI 0.56.0 headless |
Subprocess receiver adapter | Deterministic + no-model preflight; live model not run |
| Custom JavaScript harness | Cooperative loop or native tool bridge | Packed consumer + conformance pass |
| Generic ACP agent | Persistent session receiver | Deterministic conformance; Kimi is the real ACP proof |
Claude Code, LangGraph, CrewAI, OpenAI Agents SDK, and other harnesses are plausible adapter targets, but they are not claimed as validated until an adapter publishes a version range, capability document, conformance result, and known gaps.
Full compatibility matrix · Implement an adapter
ThreadMesh complements rather than replaces adjacent agent infrastructure:
| Layer | Primary job |
|---|---|
| MCP and native tools | Connect one agent to tools and context |
| A2A-style transport | Exchange messages between agent endpoints |
| Workflow / graph runtimes | Schedule known steps and own the execution loop |
| ThreadMesh | Govern proactive contact between separate task contexts |
The reference shape is deliberately small:
Agent A ThreadMesh Agent B
│ discover authorized task │ │
├─────────────────────────>│ relationship-scoped summary │
│<─────────────────────────┤ │
│ suggest once │ policy → mailbox → consent │
├─────────────────────────>├─────────────────────────────>│
│ │ accepted / rejected / deferred│
│<─────────────────────────┴──────────────────────────────┤
ThreadMesh is designed around a simple rule: a task owns its objective and model-visible history.
- no global session search or shared transcript;
- least-authority intent and exact directional grants;
- mailbox before peer content becomes model-visible;
- expiry and objective/run freshness for consequential requests;
- visible source and reason instead of relabeling peer text as user intent;
- fail-closed capability negotiation and complete causal audit.
Current adapters still deliver accepted peer context through ordinary prompt surfaces and do not supply an OS sandbox. Do not use them with arbitrary hostile peer content or as a production security boundary.
Context sovereignty · permission model · threat model · security policy
- Protocol: executable
0.0-draft; changes are still expected. - Package:
@fyaic/threadmesh@0.1.0-alpha.0, installable from GitHub. The root export is the small harness SDK; explicit runtime subpaths and the CLI install Ajv and nativebetter-sqlite3. - Reference runtime: authenticated JSON-RPC + SQLite coordinator for local, trusted-process experiments.
- Validation: 388 tests, plus 55 schema cases and 7 transition cases; documentation lint passes. These are separate counts, not one combined total.
- Default: proactive coordination remains off unless a maintainer explicitly opts into the bounded experimental profile.
- Next mainline: make the real reviewer admitted-turn boundary repeatable, complete the same-condition baseline and real Codex relevant 3/3, then observe three independent 15-minute setup attempts. Kimi parity and broader hardening follow only after those product-proof gates.
Current status · roadmap · protocol draft · validation evidence
| If you want to… | Start here |
|---|---|
| Understand the product | What ThreadMesh is |
| Watch the 76-second proof | MP4 walkthrough |
| See real proactive behavior | Real agent case portfolio |
| Run the closed-loop local demo | Attention-router demo |
| Audit the user-value baseline | Manual relay/polling baseline |
| Audit non-interruption | Active-session checkpoint case |
| Try it as a new operator | 15-minute challenge |
| Compare selective model initiative | End-to-end demo |
| Add ThreadMesh to a harness | Adapter implementation guide |
| Evaluate a harness | Harness support matrix |
| Review safety and semantics | Protocol → safety |
| Inspect exact test evidence | Review and validation index |
| Contribute | Contributing guide |
ThreadMesh is not a human chat system, model gateway, workflow DAG engine, global agent directory, or license for one agent to control unrelated user sessions. It does not replace MCP or A2A.
- Ask design and integration questions in GitHub Discussions.
- Report reproducible defects or propose adapters through GitHub Issues.
- Read CONTRIBUTING.md, GOVERNANCE.md, SUPPORT.md, and the Code of Conduct.
- Report security issues privately as described in SECURITY.md.
ThreadMesh is available under the Apache License 2.0.