Files
Netcatty/infrastructure/ai/shared/sessionExecutionQueue.ts
T
陈大猫andClaude Opus 4.7 cab4fc36ab Serialize Catty terminal_execute per session to fix the parallel tool_use race (#1108)
* fix(ai): serialize Catty terminal_execute calls per session

Issue #1101 problem 3. When the LLM emits multiple tool_use blocks in
one assistant turn (DeepSeek's Anthropic-compat happily does this for
parallel info-gathering), the Vercel AI SDK dispatches every tool
through `Promise.all(toolCalls.map(execute))`. All of them then race
into the same per-session mutex inside the main-process bridge
(`mcpServerBridge.reserveSessionExecution`). One wins; the rest get
`{ ok: false, error: "Session already has another command in
progress..." }` synthesized back as the tool result. The LLM sees a
turn full of synthetic errors instead of the answers it asked for, the
UI cards look stuck on "executing", and the Anthropic API has
sometimes rejected the resulting trace as
`tool_use ids were found without tool_result blocks`.

Adds an in-renderer Promise-chain queue keyed by
`${chatSessionId}:${terminalSessionId}` so the actual
`bridge.aiExec()` calls are issued one at a time per terminal. The LLM
can still parallel-call as many tool_use blocks as it wants — they
just resolve sequentially with real output. Approval prompts are kept
*outside* the queue: three parallel tool_use blocks still surface
three approval cards together, so the user can dispatch them in any
order rather than waiting for each prior command to finish before the
next prompt appears. The bridge-side mutex stays as defense-in-depth
for non-LLM paths (terminal_start, MCP, etc.).

`chainBySessionKey` is a self-contained helper with cleanup logic so
the queue map doesn't leak across many short-lived sessions:
- Each task awaits the previous tail via `.then(task, task)` so a
  failure doesn't poison the chain.
- A non-rejecting wrapper is stored as the new tail to keep that
  contract regardless of how the task settles.
- The cleanup `finally` only deletes the map entry when the current
  tail is still ours, so a caller that arrived between
  `set` and `finally` doesn't have its tail evicted.

Four unit tests cover dispatch ordering, rejection isolation,
per-key parallelism, and the cleanup path. Full suite 1255/1255.

Refs #1101.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(ai): preserve LLM emission order + honor abort in serialized queue

Codex local review on the first cut of this branch flagged two real
issues plus a weak cleanup test:

1. **Approval order vs queue order** — the previous version awaited
   approval *before* reserving a queue slot. With three parallel
   tool_use blocks the user could approve B's prompt first, and B
   would slip into the queue ahead of A, running out of LLM emission
   order. Reserving the slot synchronously up front fixes that:
   `Promise.all`-dispatched executes each grab a slot at the same
   instant in their dispatch order, then wait on approval while
   holding it, then await `slot.ready` and run.

2. **Abort not honored** — once approvals were settled, queued-but-
   not-started commands ran to completion even after the user hit
   Stop. Their results were ignored by the SDK but the side effects
   still happened. Two `abortSignal` checks now short-circuit before
   the queue wait and again after.

3. **Cleanup test was vacuous** — the previous "drains" test would
   pass even if the cleanup logic were removed. Exposed
   `getSessionExecutionQueueSizeForTests` and assert the Map is empty
   after the only queued task settles.

Queue API now has two entry points: high-level `chainBySessionKey`
for run-it-when-it's-your-turn callers, and lower-level
`reserveSessionSlot` for callers (like `terminal_execute`) that
need to do non-blocking pre-work in parallel with the queue wait.

Two new tests cover the reservation-order-vs-prework-order guarantee
and the skip-without-serialized-work path.

Refs #1101.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(ai): re-issue cancel on abort to close IPC-transit race

Codex local review (round 2) flagged a small remaining race: between
the abort check after \`slot.ready\` and the main-process bridge
registering the new exec into \`activePtyExecs\`, the user can hit
Stop. \`handleStop\` does issue \`aiCattyCancelExec\`, but if that
cancel IPC arrives at main *before* the exec has finished
registering, the cancel finds nothing to cancel and the exec keeps
running. Result: the user already cancelled, but the command runs
anyway.

Plug the gap by re-issuing the cancel from the tool's own abort
listener. Once the exec has registered into \`activePtyExecs\` (a
synchronous step on the main side once the IPC lands), the duplicate
cancel finds the entry and cancels it. \`cancelPtyExecsForSession\`
is already idempotent — it iterates the live tracker and skips
entries with mismatched \`chatSessionId\` — so double-firing from
both \`handleStop\` and the tool is safe.

Extends \`NetcattyBridge\` with the optional
\`aiCattyCancelExec(chatSessionId)\` method. Already exposed in
\`electron/preload.cjs\` so the runtime call works on the live
bridge; the type addition just makes it visible to the tool.

Refs codex review on #1101 problem 3 fix.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(ai): register pending-cancel marker before SSH exec-channel opens

Codex local review (round 3) caught a remaining race in
`execViaChannel`: the cancellation marker is only registered inside
`sshClient.exec`'s open callback, which is async. If a cancel arrives
in the window between `sshClient.exec(...)` being dispatched and the
callback firing, `cancelPtyExecsForSession` finds nothing for the
session and is a no-op. The channel then opens, the marker
registers, and the command runs to completion — exactly the "user
already cancelled, but the command still ran" failure mode.

Plug the window by registering a *pending* marker synchronously
before `sshClient.exec`. The pending marker carries a `cancel()` that
just latches a `cancelled` flag and a `cleanup()` that is a no-op.
When the open callback fires it removes the pending marker and
checks the latch: if it tripped, close the just-opened stream and
resolve with `{ ok: false, error: "Cancelled" }`. If not, the normal
post-open registration takes over with the real `execStream` close.

The PTY (`execViaPty`) and raw-serial (`execViaRawPty`) paths
already register their marker before any async wait, so they don't
share this race.

Two regression tests in `ptyExec.test.cjs`:
- The pending marker is present immediately after `execViaChannel`
  returns, before the open callback runs.
- A cancel during the pre-open window short-circuits the eventual
  callback with `{ ok: false, error: "Cancelled" }` and closes the
  now-unwanted stream.

Refs codex review on #1101 problem 3 fix.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(ai): clean up pending-cancel marker when sshClient.exec throws sync

Codex local review (round 4) noted that if `sshClient.exec(...)`
itself throws synchronously — e.g. because the underlying ssh2 client
was destroyed between the session lookup and the actual `.exec`
call — the pending-cancel marker stays in `activePtyExecs`
indefinitely and the surrounding Promise rejects instead of
resolving with the normal `{ ok, error }` shape the tool layer
expects.

Wraps the `sshClient.exec` invocation in `try/catch` so:
- Pending marker is removed when the throw escapes.
- The Promise resolves cleanly with `{ ok: false, error: err.message }`
  so the tool layer gets the same shape it does for every other
  failure mode (closed stream, timeout, cancellation).

Adds a regression test covering this exact path: a fake client whose
`.exec` throws synchronously; the result is a clean failure and the
cancellation map is empty afterwards.

Refs codex review on #1101 problem 3 fix.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-27 00:45:37 +08:00

128 lines
4.7 KiB
TypeScript

/**
* Per-session execution queue for tool calls that target the same terminal
* session.
*
* Background — issue #1101 problem 3:
*
* Vercel AI SDK dispatches every tool_use block emitted in one assistant
* turn through `Promise.all(toolCalls.map(execute))`, so an LLM that asks
* for three commands "at once" sends three simultaneous `bridge.aiExec()`
* calls at the underlying PTY. The main-process session mutex
* (`mcpServerBridge.reserveSessionExecution`) only lets one through and
* rejects the rest with `{ ok: false, error: "Session already has another
* command in progress..." }`. The LLM then sees two synthetic errors plus
* one real result for a turn it expected to be all-or-nothing — and the
* Anthropic API has occasionally rejected the resulting trace with a
* `tool_use ids were found without tool_result blocks` 400.
*
* The cleanest fix is to never let those calls race in the first place:
* serialize at the renderer-side tool execute boundary so the bridge sees
* one command per session at a time. The bridge mutex stays as
* defense-in-depth for non-LLM IPC paths (terminal_start, MCP, etc.).
*
* The queue exposes both a high-level `chainBySessionKey(key, task)` for
* simple "run this when it's our turn" callers, and a lower-level
* `reserveSessionSlot(key)` for callers that need to do non-blocking work
* (e.g. await an approval prompt) *while* their queue slot is held — so
* the queue order matches the LLM's emission order independent of when
* each call's approval lands.
*/
const queues = new Map<string, Promise<unknown>>();
/**
* A reserved slot in a session's execution queue. The slot is added to
* the queue tail synchronously when {@link reserveSessionSlot} is called,
* so call order is fixed at reservation time — regardless of how long
* each caller spends on pre-work (approval prompts, abort checks, etc.)
* before they actually start.
*
* Lifecycle:
* 1. `reserveSessionSlot(key)` — synchronously snaps a place in line.
* 2. caller does whatever pre-work they want, in parallel with siblings.
* 3. `await slot.ready` — blocks until the previous slot has released.
* 4. caller does the serialized work.
* 5. `slot.release()` — frees the next slot. Idempotent.
*
* The slot **must** be released exactly once (typically from a `finally`)
* even if the caller decides to skip the serialized work — otherwise
* subsequent slots queued behind it never start.
*/
export interface SessionExecutionSlot {
/** Resolves when this slot is at the head of its queue. */
readonly ready: Promise<void>;
/** Releases this slot. Safe to call multiple times. */
release(): void;
}
export function reserveSessionSlot(key: string): SessionExecutionSlot {
const prev = queues.get(key) ?? Promise.resolve();
let resolveDone!: () => void;
const done = new Promise<void>((r) => {
resolveDone = r;
});
// The new tail of this key's queue: previous tail → our `done`.
// Wrap in a non-rejecting chain so a thrown task never poisons later
// callers waiting on this tail.
const tail: Promise<unknown> = prev.then(() => done).catch(() => undefined);
queues.set(key, tail);
// Best-effort cleanup once we're the last in line — keeps the map
// from growing without bound across many short-lived sessions. A
// later caller that arrived between `queues.set` and this finally
// will already have replaced the tail; we only clear when we're
// still it.
void tail.finally(() => {
if (queues.get(key) === tail) {
queues.delete(key);
}
});
let released = false;
return {
ready: prev.then(
() => undefined,
() => undefined,
),
release(): void {
if (released) return;
released = true;
resolveDone();
},
};
}
/**
* Run `task` after every previously-reserved slot with the same `key`
* has released. Returns the task's resolved value (or rejects if the
* task throws). A failure in one task does not poison the queue head
* for subsequent callers — the chain only waits on settlement, not
* success.
*
* For callers that need to interleave pre-work with the queue wait
* (e.g. approval prompts that should run in parallel even though the
* actual command must run serially), use {@link reserveSessionSlot}
* directly.
*/
export async function chainBySessionKey<T>(key: string, task: () => Promise<T>): Promise<T> {
const slot = reserveSessionSlot(key);
try {
await slot.ready;
return await task();
} finally {
slot.release();
}
}
/** Test-only: inspect the live queue. */
export function getSessionExecutionQueueSizeForTests(): number {
return queues.size;
}
/** Test-only: drop all queued work. */
export function resetSessionExecutionQueueForTests(): void {
queues.clear();
}