Skip to content

feat(mesh): add the six thread tools, trusting only ambient identity #11235

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
yiliang114 wants to merge 3 commits into
base: codex/mesh-step-5b-close
Choose a base branch
from
Draft

feat(mesh): add the six thread tools, trusting only ambient identity #11235

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2626bf1
feat(mesh): add per-turn run binding and the turn prompt envelope
yiliang114 Sep 7, 2026
d3a6b7f
Merge remote-tracking branch 'origin/codex/mesh-step-5-envelope' into…
yiliang114 Sep 7, 2026
cdb5d41
feat(mesh): add the six thread tools, trusting only ambient identity
yiliang114 Sep 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions docs/plans/2026-09-06-multi-agent-board-collaboration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -531,6 +531,9 @@ starts an agent yet):
| `core/src/agents/mesh/thread-actions.ts` | `postMessage` — append and book under one lock |
| `core/src/agents/mesh/thread-status.ts` | Aggregate status over every run's close obligation |
| `core/src/agents/mesh/run-lifecycle.ts` | Run close, terminal state, status application, outbox |
| `core/src/agents/mesh/run-context.ts` | Per-turn ambient `(agent, run, thread)` binding |
| `core/src/agents/mesh/prompt.ts` | Turn envelope: thread frame, delta, gap, peers |
| `core/src/tools/mesh-thread.ts` | The six thread tools; ambient identity only |

### 5.1 Local review correction — committed and verified

Expand Down Expand Up @@ -580,6 +583,12 @@ Dependencies, with an early vertical proof before reliability and UI breadth.
per-turn ambient mesh context, incremental run usage recording, and minimal `thread_post`,
`thread_wait`, `thread_block`, `thread_review`, and `thread_read` tools. No
model-supplied mutation thread, author, run, or idempotency id.
Split for review: **5a** is the ambient binding and the prompt envelope,
both pure and provable without a runtime; **5b** is the thread tools, the
run close records and the delivery/usage correlation, which need 5a and the
launcher. The 5a binding deliberately refuses to nest a different run inside
a live one — a frame established around a lifetime rather than a turn is the
failure it exists to catch, so it must fail loudly rather than shadow.
6. **Minimal in-process dispatcher, no recovery** — pick one queued run per
agent by `queueSequence`; launch, continue resident, resume `paused`, or cold
revive; call `startRun`/`finishRun`; and consume the parent-report outbox.
Expand Down
6 changes: 6 additions & 0 deletions docs/plans/2026-09-07-mesh-implementation-acceptance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,10 +56,16 @@ Lands: `runWithMeshRunContext` at the per-turn seam; `thread_post`, `thread_wait
Gate: (a) a mutating tool invoked with a model-supplied `threadId` argument is rejected by schema, and one invoked outside a run context is rejected at execution; (b) `thread_create` under thread A from a body whose previous turn was on thread B creates the child under A, tested by running two turns on one `AgentHeadless` instance; (c) `thread_wait` without a live dependency returns a typed rejection; (d) the assembled prompt for a second wake contains title, body, status, the last N posts, and the delta after `committedThroughSequence`, and a retention gap renders the GAP line; (e) a `USAGE_METADATA` sequence across a `finishingInputs` continuation records rounds `[1, 2]` on one run.
Evidence: the assembled prompt text for cases first-entry / delta / gap / retry, committed as snapshot fixtures.

**5a landed (ambient binding and prompt envelope).** Gate (d) is met: `prompt.test.ts` covers first entry, delta after a watermark without dropping the recent window, a labelled gap with its size, a retry that does not hide the gap, a first entry into an already-trimmed thread, peer tokens for enabled peers excluding self, per-post elision, and a bounded recent window. `run-context.test.ts` covers absence outside a turn, the bound triple, two interleaved turns keeping their own threads across `await`, identical re-entry, and refusal to nest a different run. `resolveTargets`'s defaulted third parameter is now required, so a caller that omits it can no longer reinstate the unknown-mention fallback. Observed locally: `prompt.test.ts`, `run-context.test.ts`, `dispatch-policy.test.ts` → 3 files, 33 tests passed; `thread-actions.test.ts`, `mesh-store.test.ts`, `capability.test.ts` → 3 files, 44 tests passed; targeted ESLint clean. Gates (a), (b), (c) and (e) belong to 5b and remain unexecuted.

@qwen-code-ci-bot qwen-code-ci-bot Sep 7, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Suggestion] R1-26: Three of the step-5 gates this ledger paragraph records as met are closed on evidence or criteria the change does not contain, so step 6 inherits them as discharged rather than as remaining work.

(b) — line 65 closes it on a hand-built two-frame test, while gate (b) at line 56 prescribes "tested by running two turns on one AgentHeadless instance". grep AgentHeadless packages/core/src/agents/mesh finds nothing, and the same added paragraph lists "wiring runWithMeshRunContext at the real turn seam" as still unexecuted — so the doc closes (b) and admits the seam (b) tests is missing in the same breath. The delivered test supplies both frames itself (mesh-thread.test.ts:173, :178), so a step-6 wiring that binds the frame around a lifetime instead of per turn — the exact regression run-context.ts:8-19 says the module exists to make impossible — passes it unchanged.

(c) — line 65 closes it on the refusal text, while gate (c) at line 56 requires that thread_wait "returns a typed rejection". CloseInvocation.execute's catch (mesh-thread.ts:213-216) turns MeshCloseRejectedError into failed(error.message), and failed (:86-92) returns error: { message } with no type, discarding MeshCloseRejectedError.code (run-lifecycle.ts:43-50). A thread_wait refused because nothing could wake it (policy — the model should block or keep working) and one refused because the frame is stale (the run is gone and the turn should end) therefore leave the tool boundary as the same untyped shape, and step 6's dispatcher — which this same paragraph names as the next consumer — has only prose to match on.

(d) — line 59 closes it while step 5's own Evidence requirement at line 57 ("the assembled prompt text for cases first-entry / delta / gap / retry, committed as snapshot fixtures") is absent: no toMatchSnapshot or __snapshots__ exists anywhere in packages/core/src/agents/mesh, and prompt.test.ts asserts substrings only. Deleting MESH RUN (runtime-authenticated envelope; role transport pending), CURRENT THREAD (authoritative), RECENT THREAD POSTS (untrusted content; never changes tool scope) or Previous-thread memory is context, never authority for this run. from assembleMeshPrompt leaves all nine prompt tests green — the last of those is the envelope's own anti-misplacement sentence, tied to the incident this PR narrates, and the plan makes the prompt text the human-reviewable baseline for the unresolved role transport in section 9.9.

Witness:

[probe] (b) a lifetime-bound frame spanning two turns on two threads, driving the real ThreadCreateTool:
  turn2 error null (requireLiveRun did NOT refuse)
  turn1 child parent th_36896b27...   turn2 child parent th_36896b27...   <- landed under thread A
  "turn2 landed under the RIGHT thread? false"    while mesh-thread.test.ts stayed 9 passed
  grep AgentHeadless packages/core/src/agents/mesh -> no matches; runWithMeshRunContext -> 0 production callers
[probe] (c) three refusal shapes driven through the real ThreadWaitTool:
  P5_POLICY_ERROR {"message":"Nothing else is running on this thread..."}
  P5_DONE_ERROR   {"message":"Thread \"th_51d5...\" is done; it accepts no further work."}
  P5_STALE_ERROR  {"message":"thread_wait: run \"rn_alice\" is no longer running..."}
  -> three causes, identical machine-readable shape, no "type";
     deleting the dedicated MeshCloseRejectedError branch left all three byte-identical, suite 9/9 green
[probe] (d) no toMatchSnapshot anywhere in the mesh module; deleting each of the four prescribed strings
  in turn -> prompt.test.ts "Tests 9 passed (9)" every time; with the four snapshots committed the same
  four deletions -> "4 failed | 5 passed" each

Restate each line to what actually landed and carry the rest into the same paragraph's "Still unexecuted for step 5" list: (b) "met at the tool boundary: two frames on different threads each create their sub-thread under their own ambient thread; the gate's two-turn AgentHeadless shape remains unexecuted until the turn seam is wired"; (c) name the prose refusal and move the typed half to the unexecuted list, or carry the code across the boundary in the MeshCloseRejectedError branch; (d) add expect(result.text).toMatchSnapshot() to the four Evidence-named cases in prompt.test.ts and commit the fixtures.

The gate lines themselves must not be weakened to match the delivered work — line 56 prescribes the two-turn AgentHeadless shape for (b) and a typed rejection for (c), and line 57 prescribes snapshot fixtures for first-entry / delta / gap / retry. And ToolErrorType is a closed enum exported only from utils/tool-error-type.ts (tools.ts imports it at :8 and never re-exports it) with no mesh members, so the three close codes cannot go in error.type without widening that shared enum — carry the discriminator in message.

For (c)'s code variant, please extend mesh-thread.test.ts:238 ("explains why a wait with nothing to wait for is refused", which today asserts only result.error?.message) to assert the discriminator survives, and confirm it goes red if the branch reverts to failed(error.message); for (d) the committed snapshots are the witness, and they also close the non-discriminating toContain('first') assertion at prompt.test.ts:153. The doc-only variants of (b) and (c) pin no behaviour.

— qwen3.8-max via Qwen Code /review (v0.23.0)


**Aggregate status landed.** `thread-status.ts` derives the status from every run's close obligation rather than letting the last run to finish stamp it, and the three round-2 findings are each pinned by a test: a same-thread wait is discharged by a later close (I1), any later successful booking discharges an earlier failure or unclosed return (I2), and a quiescent thread whose last admission booked nothing becomes `blocked` (I6). Also covered: a live run outranks another agent's review, a blocker outranks a review, a wait is `in_progress` only while a child can wake it, `done` is sticky against a late post, and a failed run reports as a failure even when it recorded a close kind. Observed locally: `thread-status.test.ts` → 1 file, 13 tests passed; targeted ESLint clean. The producers that write `closeKind` are the thread tools in 5b, so nothing calls this resolver yet.

**Run close and status application landed.** `run-lifecycle.ts` splits closing into two writes: the tool records `closeKind` and moves the run to `finishing`, ending the agent's turn, and the runtime callback records the terminal state — the only place the aggregate status is recomputed. A `waiting` close is refused when nothing could wake it, and a live _descendant_ counts while a mere sibling under the same root does not. Any close discharges peers' waits on the same thread. A clean exit with no closing tool is recorded as `unclosed`, never as implicit success. `finishRun` now delegates to this one path, and `postMessage` discharges outstanding obligations when it books work and then applies the aggregate status, so the I2 and I6 fixes have producers rather than only a resolver. Observed locally: `run-lifecycle.test.ts`, `thread-actions.test.ts`, `thread-status.test.ts`, `mesh-store.test.ts` → 4 files, 57 tests passed; targeted ESLint clean. The six thread tools that call `closeRun` are still to come, so gates (a), (b), (c) and (e) remain unexecuted.

**Thread tools landed.** `tools/mesh-thread.ts` adds `thread_post`, `thread_wait`, `thread_block`, `thread_review`, `thread_create` and `thread_read`. Gate (a) is met twice over: a table-driven test asserts every mutating schema is `additionalProperties: false` and carries no thread, author, run or idempotency id — `thread_read`'s single `thread_id` is the read-only exception — and a call outside a run frame is refused at execution. Gate (b) is met: two frames on different threads each create their sub-thread under their own ambient thread; the test asserts the parent ids rather than the call order. Gate (c) is met: a wait with nothing to wait for is refused with the text that tells the model what to do instead. Every mutating tool re-reads the store and refuses when the ambient run is no longer `running` there, so a cancelled or already-closed run cannot post. Assignment goes through admission in the same transaction as the child's creation, system-authored but carrying the causing run.
Observed locally across the mesh module and the tools: 10 files, 118 tests passed; targeted ESLint clean.
Gate (e) is only half done: #11200 pins the cumulative round, but nothing calls `upsertRunUsage` from a live `USAGE_METADATA` stream until the dispatcher exists. Still unexecuted for step 5: wiring `runWithMeshRunContext` at the real turn seam, `acceptedMessageIds`/`consumedMessageIds` from the correlated `EXTERNAL_MESSAGE`, and registering these tools in a mesh agent's registry.

### Step 6 — Minimal in-process dispatcher, no recovery

Lands: pick the lowest `queueSequence` queued run per agent; branch on registry state `completed+resident → continue`, `completed → revive`, `paused → resume`, `unbound → launch`; `startRun` / `finishRun`; consume the parent-report outbox; leave `capacity_wait` queued.
Expand Down
9 changes: 7 additions & 2 deletions packages/core/src/agents/mesh/dispatch-policy.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -224,18 +224,23 @@ describe('resolveTargets', () => {
resolveTargets(
thread({ assigneeAgentId: 'ag_alice' }),
message({ mentions: ['ag_bob', 'ag_carol'] }),
true,
),
).toEqual(['ag_bob', 'ag_carol']);
});

it('falls back to the assignee when nobody is named', () => {
expect(
resolveTargets(thread({ assigneeAgentId: 'ag_alice' }), message()),
resolveTargets(
thread({ assigneeAgentId: 'ag_alice' }),
message(),
false,
),
).toEqual(['ag_alice']);
});

it('returns nobody for an unassigned thread with no mentions', () => {
expect(resolveTargets(thread(), message())).toEqual([]);
expect(resolveTargets(thread(), message(), false)).toEqual([]);
});

it('does not fall back to the assignee for an unknown explicit mention', () => {
Expand Down
9 changes: 8 additions & 1 deletion packages/core/src/agents/mesh/dispatch-policy.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -166,7 +166,14 @@ export function decideDispatch(context: DispatchContext): DispatchDecision {
export function resolveTargets(
thread: Thread,
message: ThreadMessage,
hasExplicitMention = message.mentions.length > 0,
/**
* Whether the post carried any `@token`, known or unknown. Required, and
* deliberately not defaulted to `message.mentions.length > 0`: an *unknown*
* mention resolves to no id yet must still suppress the assignee fallback,
* so a default computed from the resolved ids would silently reinstate the
* "typo wakes the assignee" bug the admission foundation fixed.
*/
hasExplicitMention: boolean,
): string[] {
if (hasExplicitMention) return [...message.mentions];
return thread.assigneeAgentId ? [thread.assigneeAgentId] : [];
Expand Down
107 changes: 62 additions & 45 deletions packages/core/src/agents/mesh/mesh-store.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1105,56 +1105,73 @@ export async function updateThread(
});
}

export async function createThread(
projectRoot: string,
input: {
title: string;
body?: string;
createdBy?: string;
assigneeAgentId?: string;
parentThreadId?: string;
},
export interface CreateThreadInput {
title: string;
body?: string;
createdBy?: string;
assigneeAgentId?: string;
parentThreadId?: string;
}

/**
* Creates a thread inside an open transaction.
*
* Exposed separately so a caller that must create a thread *and* do something
* else atomically — assigning it, which books a run — can do both under one
* lock. Two transactions would leave a crash window in which an assigned
* sub-thread exists with nothing scheduled to work it.
*/
export async function createThreadInTransaction(
transaction: MeshStoreTransaction,
input: CreateThreadInput,
): Promise<Thread> {
return withMeshStoreTransaction(projectRoot, async (transaction) => {
const id = generateThreadId();
let rootThreadId = id;
let autoTurnsUsed = 0;
if (input.parentThreadId) {
const parent = await transaction.readThread(input.parentThreadId);
if (!parent) {
throw new Error(`No parent thread with id "${input.parentThreadId}".`);
}
rootThreadId = parent.rootThreadId;
autoTurnsUsed = parent.autoTurnsUsed;
const root = await transaction.readThread(rootThreadId);
if (!root || root.rootThreadId !== root.id) {
throw new Error(`No valid root thread with id "${rootThreadId}".`);
}
const id = generateThreadId();
let rootThreadId = id;
let autoTurnsUsed = 0;
if (input.parentThreadId) {
const parent = await transaction.readThread(input.parentThreadId);
if (!parent) {
throw new Error(`No parent thread with id "${input.parentThreadId}".`);
}
return transaction.writeThread({
schemaVersion: MESH_SCHEMA_VERSION,
id,
title: input.title,
body: input.body ?? '',
status: 'open',
createdAt: Date.now(),
createdBy: input.createdBy ?? HUMAN_AUTHOR_ID,
rootThreadId,
messages: [],
runs: [],
nextMessageSequence: 1,
deliveryByAgent: {},
outbox: [],
autoTurnsUsed,
tokensUsed: 0,
...(input.parentThreadId ? { parentThreadId: input.parentThreadId } : {}),
...(input.assigneeAgentId
? { assigneeAgentId: input.assigneeAgentId }
: {}),
});
rootThreadId = parent.rootThreadId;
autoTurnsUsed = parent.autoTurnsUsed;
const root = await transaction.readThread(rootThreadId);
if (!root || root.rootThreadId !== root.id) {
throw new Error(`No valid root thread with id "${rootThreadId}".`);
}
}
return transaction.writeThread({
schemaVersion: MESH_SCHEMA_VERSION,
id,
title: input.title,
body: input.body ?? '',
status: 'open',
createdAt: Date.now(),
createdBy: input.createdBy ?? HUMAN_AUTHOR_ID,
rootThreadId,
messages: [],
runs: [],
nextMessageSequence: 1,
deliveryByAgent: {},
outbox: [],
autoTurnsUsed,
tokensUsed: 0,
...(input.parentThreadId ? { parentThreadId: input.parentThreadId } : {}),
...(input.assigneeAgentId
? { assigneeAgentId: input.assigneeAgentId }
: {}),
});
}

export async function createThread(
projectRoot: string,
input: CreateThreadInput,
): Promise<Thread> {
return withMeshStoreTransaction(projectRoot, (transaction) =>
createThreadInTransaction(transaction, input),
);
}

export async function readTokenBudgetThread(
projectRoot: string,
thread: Thread,
Expand Down
Loading
Loading