T3 — Deferred tool-call coordination

{`
// Trong handleEvent switch:
case "tool-input-start": {
  const part = yield* session.updatePart({
    status: "pending",
    input: {}
  })
  ctx.toolcalls[value.id] = {
    done: yield* Deferred.make<void>(),  // ← sync point, chưa resolved
    partID: part.id,
    messageID: ...,
    sessionID: ...
  }
  return
}
`}

{`
// Trong tool executor (sau khi tool chạy xong):
const toolcall = ctx.toolcalls[toolCallId]
if (toolcall) {
  yield* Deferred.succeed(toolcall.done, undefined)
  // Bất kể tool thành công hay thất bại,
  // Deferred PHẢI được resolve để không block cleanup
}
`}

{`
// Trong cleanup():
yield* Effect.forEach(
  Object.values(ctx.toolcalls),
  (call) => Deferred.await(call.done).pipe(
    Effect.timeout("250 millis"),  // per-tool timeout
    Effect.ignore,                  // ignore timeout error (không throw)
  ),
  { concurrency: "unbounded" }      // await all in parallel
)
`}

{`
type ToolCall = {
  partID: MessageV2.ToolPart["id"]
  messageID: MessageV2.ToolPart["messageID"]
  sessionID: MessageV2.ToolPart["sessionID"]
  done: Deferred.Deferred<void>  // ← sync point
}

// ctx là per-stream state:
const ctx = {
  toolcalls: {} as Record<string, ToolCall>,
  // ...
}
`}

{`
// WRONG:
for await (const event of stream) {
  if (event.type === "tool-call") {
    executeToolAsync(event)  // fire-and-forget!
  }
}
// Stream done → loop tiếp → model không thấy tool result
// Tool vẫn đang chạy nhưng không có nơi để lưu kết quả
`}

{`
// WRONG: sequential
for (const call of Object.values(ctx.toolcalls)) {
  await waitForDeferred(call.done, 250)  // chờ từng cái
}
// Nếu có 5 tools: chờ 5 * 250ms = 1.25 giây worst case

// CORRECT: parallel
await Promise.all(
  Object.values(ctx.toolcalls).map(call =>
    Promise.race([call.promise, sleep(250)])
  )
)
// Chờ tối đa 250ms dù có bao nhiêu tools
`}

{`
// WRONG:
async function executeTool(tc: ToolCall) {
  const result = await runTool(tc)  // có thể throw!
  deferred.resolve()                 // không chạy nếu throw trên
}

// CORRECT: finally block
async function executeTool(tc: ToolCall) {
  try {
    const result = await runTool(tc)
    // lưu result
  } finally {
    deferred.resolve()  // luôn resolve, dù success hay error
  }
}
`}

{`
// Deferred factory using native Promise
function makeDeferred<T>() {
  let resolve!: (value: T) => void
  let reject!: (reason?: unknown) => void
  const promise = new Promise<T>((res, rej) => {
    resolve = res
    reject = rej
  })
  return { promise, resolve, reject }
}

// Track in-flight tool calls
const pendingTools = new Map<string, ReturnType<typeof makeDeferred<void>>>()

// Called when stream receives tool-input-start
function registerToolCall(id: string) {
  const deferred = makeDeferred<void>()
  pendingTools.set(id, deferred)
  return deferred
}

// Called when tool executor finishes (success OR error)
function resolveToolCall(id: string) {
  const deferred = pendingTools.get(id)
  if (deferred) {
    deferred.resolve()
    pendingTools.delete(id)
  }
}

// Called after stream drain — await all with timeout
async function waitForAllTools(timeoutMs = 250) {
  const entries = [...pendingTools.values()]
  if (entries.length === 0) return

  // Parallel await với per-entry timeout
  await Promise.all(
    entries.map((d) =>
      Promise.race([
        d.promise,
        new Promise<void>((res) => setTimeout(res, timeoutMs))
        // timeout resolves (not rejects) — không throw
      ])
    )
  )
  pendingTools.clear()
}

// Wiring trong stream consumer:
async function processStream(stream: AsyncIterable<StreamEvent>) {
  try {
    for await (const event of stream) {
      switch (event.type) {
        case "tool-input-start":
          registerToolCall(event.id)
          break
        case "tool-call":
          const deferred = pendingTools.get(event.toolCallId)
          // Fire async, resolve khi done
          runTool(event).finally(() => resolveToolCall(event.toolCallId))
          break
      }
    }
  } finally {
    // Cleanup — luôn chạy (try/finally)
    await waitForAllTools(250)
  }
}
`}