@byok-sdk/client 0.4.0 → 0.4.2

package/README.md

@@ -70,4 +70,4 @@ OS-backed refresh-token custody, a PKCE desktop Google OAuth flow, exact domain
 policy, a real read-only Gmail metadata adapter, and a closed metadata-only MCP
 result.
 
-MIT licensed. Node.js 22.19.0 or newer.
+MIT licensed. Node.js 22.22.0 or newer.

package/dist/adapters/claude/process-client.d.ts

@@ -97,7 +97,13 @@ export declare class ClaudeProcessClient {
      * post-mortem without separate log scraping.
      */
     recordUnmappedFrame(label: string): void;
-    /** Immediate process-tree termination request. `dispose()` is the settlement receipt. */
+    /**
+     * Immediate process-tree termination request. `dispose()` is the settlement
+     * receipt, so this stays fire-and-forget: an interrupt must not block on a
+     * terminator. A request that could not be spawned is left unrecorded, so
+     * `dispose()` re-issues it and raises the typed `stage:'signal'` failure —
+     * swallowing it here loses nothing.
+     */
     kill(): void;
     waitClosed(): Promise<void>;
     dispose(): Promise<void>;

package/dist/adapters/codex/process-runner.d.ts

@@ -77,6 +77,11 @@ export declare class CodexProcessRunner {
      * cleanly resumable afterward via `codex exec resume` (no corruption from
      * killing mid-turn). `taskkill /T /F` on Windows, mirroring
      * `../pi/rpc-client.ts`'s own cross-platform convention.
+     *
+     * Fire-and-forget by design: an interrupt must not block on a terminator,
+     * and `dispose()` is the settlement receipt. A request that could not be
+     * spawned is left unrecorded, so `dispose()` re-issues it and raises the
+     * typed `stage:'signal'` failure — swallowing it here loses nothing.
      */
     kill(): void;
     dispose(): Promise<void>;

package/dist/adapters/index.js

@@ -1,4 +1,4 @@
-import { execFile, spawn, spawnSync } from 'child_process';
+import { execFile, spawn } from 'child_process';
 import { promisify } from 'util';
 import { promises, existsSync, readFileSync, realpathSync } from 'fs';
 import path3 from 'path';
@@ -128,12 +128,12 @@ function resolvePiBin() {
     }
   } catch (cause) {
     throw new Error(
-      `Required ${PI_PACKAGE_NAME} could not be resolved; install @byok-sdk/client dependencies or set BYOK_PI_BIN to a Node 22.19+ pi sidecar`,
+      `Required ${PI_PACKAGE_NAME} could not be resolved; install @byok-sdk/client dependencies or set BYOK_PI_BIN to a Node 22.22+ pi sidecar`,
       { cause }
     );
   }
   throw new Error(
-    `Required ${PI_PACKAGE_NAME} does not expose the pi CLI; reinstall the pinned dependency or set BYOK_PI_BIN to a Node 22.19+ pi sidecar`
+    `Required ${PI_PACKAGE_NAME} does not expose the pi CLI; reinstall the pinned dependency or set BYOK_PI_BIN to a Node 22.22+ pi sidecar`
   );
 }
 
@@ -172,6 +172,24 @@ function mapPermissionPolicyToPiArgs(policy) {
 }
 
 // src/adapters/pi/events.ts
+function requireToolCallId(msg) {
+  if (typeof msg.toolCallId === "string" && msg.toolCallId.trim().length > 0) return msg.toolCallId;
+  throw new RuntimeExecutionFailure({
+    phase: "run",
+    category: "authority",
+    retry: "non-retryable",
+    reason: `pi ${msg.type} frame had no authoritative tool call id`
+  });
+}
+function requireToolResultOutcome(msg) {
+  if (typeof msg.isError === "boolean") return msg.isError;
+  throw new RuntimeExecutionFailure({
+    phase: "run",
+    category: "authority",
+    retry: "non-retryable",
+    reason: "pi tool_execution_end frame had no authoritative isError outcome"
+  });
+}
 function mapPiMessageToAgentEvent(msg) {
   switch (msg.type) {
     case "message_update": {
@@ -182,16 +200,22 @@ function mapPiMessageToAgentEvent(msg) {
       return void 0;
     }
     case "tool_execution_start": {
+      const toolCallId = requireToolCallId(msg);
       if (typeof msg.toolName !== "string") return void 0;
-      return { type: "tool_use", tool: msg.toolName, input: msg.args };
+      return { type: "tool_use", tool: msg.toolName, input: msg.args, toolCallId };
     }
     case "tool_execution_end": {
+      const toolCallId = requireToolCallId(msg);
+      const isError = requireToolResultOutcome(msg);
       if (typeof msg.toolName !== "string") return void 0;
-      return {
+      const event = {
         type: "tool_result",
         tool: msg.toolName,
-        output: { result: msg.result, isError: msg.isError === true }
+        output: { result: msg.result },
+        toolCallId,
+        isError
       };
+      return event;
     }
     case "agent_settled":
       return { type: "turn_end" };
@@ -338,11 +362,54 @@ var AsyncQueue = class {
     };
   }
 };
+
+// src/adapters/taskkill-pid-set.ts
+var INTEGER_PATTERN = /\d+/g;
+function isCandidatePid(value) {
+  return Number.isSafeInteger(value) && value > 0;
+}
+function walkTaskkillPidSet(text, rootPid, excludedPids = []) {
+  const excluded = new Set(excludedPids);
+  const accepted = /* @__PURE__ */ new Set();
+  if (isCandidatePid(rootPid)) accepted.add(rootPid);
+  const lines = text.split(/\r?\n/).map((line) => {
+    const pids = [];
+    for (const match of line.matchAll(INTEGER_PATTERN)) {
+      const pid = Number(match[0]);
+      if (isCandidatePid(pid) && !excluded.has(pid)) pids.push(pid);
+    }
+    return pids;
+  });
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const pids of lines) {
+      if (!pids.some((pid) => accepted.has(pid))) continue;
+      for (const pid of pids) {
+        if (accepted.has(pid)) continue;
+        accepted.add(pid);
+        changed = true;
+      }
+    }
+  }
+  return accepted;
+}
+
+// src/adapters/process-tree.ts
 var DEFAULT_TERM_GRACE_MS = 750;
 var DEFAULT_KILL_GRACE_MS = 2e3;
 var POLL_MS = 20;
-var terminationRequested = /* @__PURE__ */ new WeakSet();
-var terminationRequestFailed = /* @__PURE__ */ new WeakSet();
+var terminationState = /* @__PURE__ */ new WeakMap();
+function stateFor(child) {
+  const existing = terminationState.get(child);
+  if (existing) return existing;
+  const created = { requested: false, acceptedPids: /* @__PURE__ */ new Set() };
+  terminationState.set(child, created);
+  return created;
+}
+function defaultKill(pid, signal) {
+  process.kill(pid, signal);
+}
 function withOwnedProcessTree(options) {
   return {
     ...options,
@@ -360,9 +427,9 @@ function positivePid(child, label) {
   }
   return pid;
 }
-function groupExists(pid, label) {
+function groupExists(pid, label, kill) {
   try {
-    process.kill(-pid, 0);
+    kill(-pid, 0);
     return true;
   } catch (cause) {
     const code = cause.code;
@@ -374,9 +441,23 @@ function groupExists(pid, label) {
     }, { cause });
   }
 }
-function signalGroup(pid, signal, label) {
+function processExists(pid, label, kill) {
   try {
-    process.kill(-pid, signal);
+    kill(pid, 0);
+    return true;
+  } catch (cause) {
+    const code = cause.code;
+    if (code === "ESRCH") return false;
+    if (code === "EPERM") return true;
+    throw new RuntimeDisposalFailure({
+      stage: "quiescence",
+      reason: `${label} runtime process ${pid} state could not be verified`
+    }, { cause });
+  }
+}
+function signalGroup(pid, signal, label, kill) {
+  try {
+    kill(-pid, signal);
   } catch (cause) {
     const code = cause.code;
     if (code === "ESRCH" || code === "EPERM") return;
@@ -386,6 +467,39 @@ function signalGroup(pid, signal, label) {
     }, { cause });
   }
 }
+async function runTaskkill(pid, options) {
+  const spawnFn = options.spawnFn ?? spawn;
+  return new Promise((resolve, reject) => {
+    const signalFailure = (cause) => {
+      reject(new RuntimeDisposalFailure({
+        stage: "signal",
+        reason: `${options.label} runtime process tree termination could not be requested`
+      }, { cause }));
+    };
+    let taskkill;
+    try {
+      taskkill = spawnFn("taskkill", ["/PID", String(pid), "/T", "/F"], {
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+    } catch (cause) {
+      signalFailure(cause);
+      return;
+    }
+    const chunks = [];
+    taskkill.stdout?.on("data", (chunk) => chunks.push(chunk));
+    taskkill.stderr?.on("data", (chunk) => chunks.push(chunk));
+    taskkill.once("error", signalFailure);
+    taskkill.once("close", () => resolve(Buffer.concat(chunks).toString("latin1")));
+  });
+}
+function liveAcceptedPids(accepted, label, kill) {
+  const live = [];
+  for (const pid of accepted) {
+    if (processExists(pid, label, kill)) live.push(pid);
+  }
+  return live;
+}
 async function waitUntil(predicate, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   while (predicate()) {
@@ -423,29 +537,27 @@ async function waitWithDeadline(promise, timeoutMs) {
     );
   });
 }
-function requestOwnedProcessTreeTermination(options) {
-  if (options.isClosed()) return;
+async function requestOwnedProcessTreeTermination(options) {
+  const platform = options.platform ?? process.platform;
+  if (platform !== "win32" && options.isClosed()) return;
   const pid = positivePid(options.child, options.label);
   if (pid === void 0) return;
-  if (process.platform === "win32") {
-    const result = spawnSync("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true });
-    if (result.error) {
-      throw new RuntimeDisposalFailure({
-        stage: "signal",
-        reason: `${options.label} runtime process tree could not be terminated`
-      }, { cause: result.error });
-    }
-    terminationRequested.add(options.child);
-    if (result.status !== 0) terminationRequestFailed.add(options.child);
+  if (platform === "win32") {
+    const output = await runTaskkill(pid, options);
+    const state = stateFor(options.child);
+    for (const walked of walkTaskkillPidSet(output, pid, [process.pid])) state.acceptedPids.add(walked);
+    state.requested = true;
     return;
   }
-  signalGroup(pid, "SIGTERM", options.label);
-  terminationRequested.add(options.child);
+  signalGroup(pid, "SIGTERM", options.label, options.killFn ?? defaultKill);
+  stateFor(options.child).requested = true;
 }
 async function disposeOwnedProcessTree(options) {
   const pid = positivePid(options.child, options.label);
   const termGraceMs = options.termGraceMs ?? DEFAULT_TERM_GRACE_MS;
   const killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+  const platform = options.platform ?? process.platform;
+  const kill = options.killFn ?? defaultKill;
   if (pid === void 0) {
     if (await waitWithDeadline(options.waitClosed(), killGraceMs)) return;
     throw new RuntimeDisposalFailure({
@@ -453,27 +565,50 @@ async function disposeOwnedProcessTree(options) {
       reason: `${options.label} runtime process did not settle after spawn failure`
     });
   }
-  if (process.platform === "win32") {
-    if (!options.isClosed() && !terminationRequested.has(options.child)) requestOwnedProcessTreeTermination(options);
-    if (await waitWithDeadline(options.waitClosed(), killGraceMs)) return;
-    if (terminationRequestFailed.has(options.child)) {
+  if (platform === "win32") {
+    if (!terminationState.get(options.child)?.requested) {
+      await requestOwnedProcessTreeTermination(options);
+    }
+    const accepted = terminationState.get(options.child)?.acceptedPids ?? /* @__PURE__ */ new Set();
+    const deadline = Date.now() + killGraceMs;
+    const resweepAt = Date.now() + Math.floor(killGraceMs / 2);
+    let reswept = false;
+    let live = liveAcceptedPids(accepted, options.label, kill);
+    while (live.length > 0) {
+      if (Date.now() >= deadline) {
+        throw new RuntimeDisposalFailure({
+          stage: "quiescence",
+          reason: `${options.label} runtime process tree did not quiesce: ${live.length} of ${accepted.size} walked process ids were still alive at the disposal deadline`
+        });
+      }
+      if (!reswept && Date.now() >= resweepAt) {
+        reswept = true;
+        for (const livePid of live) {
+          for (const walked of walkTaskkillPidSet(await runTaskkill(livePid, options), livePid, [process.pid])) {
+            accepted.add(walked);
+          }
+        }
+      }
+      await new Promise((resolve) => {
+        setTimeout(resolve, POLL_MS);
+      });
+      live = liveAcceptedPids(accepted, options.label, kill);
+    }
+    if (!await waitWithDeadline(options.waitClosed(), killGraceMs)) {
       throw new RuntimeDisposalFailure({
-        stage: "signal",
-        reason: `${options.label} runtime process tree could not be terminated`
+        stage: "quiescence",
+        reason: `${options.label} runtime root did not emit close after its process tree quiesced`
       });
     }
-    throw new RuntimeDisposalFailure({
-      stage: "quiescence",
-      reason: `${options.label} runtime process tree did not close before the disposal deadline`
-    });
+    return;
   }
-  if (groupExists(pid, options.label) && !terminationRequested.has(options.child)) {
-    signalGroup(pid, "SIGTERM", options.label);
-    terminationRequested.add(options.child);
+  if (groupExists(pid, options.label, kill) && !terminationState.get(options.child)?.requested) {
+    signalGroup(pid, "SIGTERM", options.label, kill);
+    stateFor(options.child).requested = true;
   }
-  if (!await waitUntil(() => groupExists(pid, options.label), termGraceMs)) {
-    signalGroup(pid, "SIGKILL", options.label);
-    if (!await waitUntil(() => groupExists(pid, options.label), killGraceMs)) {
+  if (!await waitUntil(() => groupExists(pid, options.label, kill), termGraceMs)) {
+    signalGroup(pid, "SIGKILL", options.label, kill);
+    if (!await waitUntil(() => groupExists(pid, options.label, kill), killGraceMs)) {
       throw new RuntimeDisposalFailure({
         stage: "quiescence",
         reason: `${options.label} runtime process group remained live after SIGKILL`
@@ -571,9 +706,16 @@ var PiRpcClient = class {
       );
     }
   }
-  /** Immediate process-tree termination request. `dispose()` is the settlement receipt. */
+  /**
+   * Immediate process-tree termination request. `dispose()` is the settlement
+   * receipt, so this stays fire-and-forget: an interrupt must not block on a
+   * terminator. A request that could not be spawned is left unrecorded, so
+   * `dispose()` re-issues it and raises the typed `stage:'signal'` failure —
+   * swallowing it here loses nothing.
+   */
   kill() {
-    requestOwnedProcessTreeTermination(this.processTreeOptions());
+    void requestOwnedProcessTreeTermination(this.processTreeOptions()).catch(() => {
+    });
   }
   waitClosed() {
     return this.closedPromise;
@@ -1085,6 +1227,17 @@ function subtractDenied(tools, denyTools) {
 function createToolUseCorrelation() {
   return { toolNameByUseId: /* @__PURE__ */ new Map() };
 }
+function missingToolCallIdFailure(frame) {
+  return new RuntimeExecutionFailure({
+    phase: "run",
+    category: "authority",
+    retry: "non-retryable",
+    reason: `claude ${frame} frame had no authoritative tool call id`
+  });
+}
+function isAuthoritativeToolCallId(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
 var ROUTINE_CLAUDE_SYSTEM_SUBTYPES = /* @__PURE__ */ new Set([
   "init",
   "hook_started",
@@ -1128,9 +1281,12 @@ function mapAssistant(msg, correlation) {
         }
         break;
       case "tool_use":
-        if (typeof block.id === "string" && typeof block.name === "string") {
+        if (!isAuthoritativeToolCallId(block.id)) {
+          return { events: [], terminalFailure: missingToolCallIdFailure("tool_use") };
+        }
+        if (typeof block.name === "string") {
           correlation.toolNameByUseId.set(block.id, block.name);
-          events.push({ type: "tool_use", tool: block.name, input: block.input });
+          events.push({ type: "tool_use", tool: block.name, input: block.input, toolCallId: block.id });
         }
         break;
       // Deliberately NOT mapped to `progress` — mirrors pi's own choice to
@@ -1166,11 +1322,20 @@ function mapUser(msg, correlation, options) {
       unmappedLabel = unmappedLabel ?? `user-block:${String(block.type)}`;
       continue;
     }
-    const toolUseId = typeof block.tool_use_id === "string" ? block.tool_use_id : void 0;
-    const tool = toolUseId && correlation.toolNameByUseId.get(toolUseId) || "unknown";
-    const isError = block.is_error === true;
-    events.push({ type: "tool_result", tool, output: { content: block.content, isError } });
-    if (!isError && FILE_WRITING_TOOLS.has(tool)) {
+    if (!isAuthoritativeToolCallId(block.tool_use_id)) {
+      return { events: [], terminalFailure: missingToolCallIdFailure("tool_result") };
+    }
+    const tool = correlation.toolNameByUseId.get(block.tool_use_id) ?? "unknown";
+    const isError = typeof block.is_error === "boolean" ? block.is_error : void 0;
+    const event = {
+      type: "tool_result",
+      tool,
+      output: { content: block.content },
+      toolCallId: block.tool_use_id
+    };
+    if (isError !== void 0) event.isError = isError;
+    events.push(event);
+    if (isError === false && FILE_WRITING_TOOLS.has(tool)) {
       const artifact = tryBuildArtifactEvent(msg, options.workspaceDir);
       if (artifact) events.push(artifact);
     }
@@ -1376,9 +1541,16 @@ var ClaudeProcessClient = class {
       );
     }
   }
-  /** Immediate process-tree termination request. `dispose()` is the settlement receipt. */
+  /**
+   * Immediate process-tree termination request. `dispose()` is the settlement
+   * receipt, so this stays fire-and-forget: an interrupt must not block on a
+   * terminator. A request that could not be spawned is left unrecorded, so
+   * `dispose()` re-issues it and raises the typed `stage:'signal'` failure —
+   * swallowing it here loses nothing.
+   */
   kill() {
-    requestOwnedProcessTreeTermination(this.processTreeOptions());
+    void requestOwnedProcessTreeTermination(this.processTreeOptions()).catch(() => {
+    });
   }
   waitClosed() {
     return this.closedPromise;
@@ -1786,8 +1958,8 @@ var ClaudeSession = class {
             for (; ; ) {
               const buffered = pending.shift();
               if (buffered) return { value: buffered, done: false };
+              if (terminalFailure) throw terminalFailure;
               if (turnSettled) {
-                if (terminalFailure) throw terminalFailure;
                 return { value: void 0, done: true };
               }
               let raw;
@@ -1989,6 +2161,15 @@ function extractCodexUsageEvent(rawUsage) {
 function toNonNegativeInt2(value) {
   return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : void 0;
 }
+function requireToolCallId2(item) {
+  if (typeof item.id === "string" && item.id.trim().length > 0) return item.id;
+  throw new RuntimeExecutionFailure({
+    phase: "run",
+    category: "authority",
+    retry: "non-retryable",
+    reason: "codex tool item had no authoritative tool call id"
+  });
+}
 function mapItem(rawItem, phase, workspaceDir) {
   if (!rawItem || typeof rawItem !== "object") return [];
   const item = rawItem;
@@ -1999,9 +2180,10 @@ function mapItem(rawItem, phase, workspaceDir) {
       return typeof item.text === "string" ? [{ type: "progress", text: item.text }] : [];
     }
     case "command_execution": {
+      const toolCallId = requireToolCallId2(item);
       const command = typeof item.command === "string" ? item.command : void 0;
       if (phase === "started") {
-        return command !== void 0 ? [{ type: "tool_use", tool: "command_execution", input: { command } }] : [];
+        return command !== void 0 ? [{ type: "tool_use", tool: "command_execution", input: { command }, toolCallId }] : [];
       }
       return [
         {
@@ -2012,17 +2194,19 @@ function mapItem(rawItem, phase, workspaceDir) {
             aggregatedOutput: item.aggregated_output,
             exitCode: item.exit_code,
             status: item.status
-          }
+          },
+          toolCallId
         }
       ];
     }
     case "file_change": {
+      const toolCallId = requireToolCallId2(item);
       const changes = Array.isArray(item.changes) ? item.changes : [];
       if (phase === "started") {
-        return [{ type: "tool_use", tool: "file_change", input: { changes } }];
+        return [{ type: "tool_use", tool: "file_change", input: { changes }, toolCallId }];
       }
       return [
-        { type: "tool_result", tool: "file_change", output: { changes, status: item.status } },
+        { type: "tool_result", tool: "file_change", output: { changes, status: item.status }, toolCallId },
         ...extractArtifactEvents(changes, workspaceDir)
       ];
     }
@@ -2143,9 +2327,15 @@ var CodexProcessRunner = class {
    * cleanly resumable afterward via `codex exec resume` (no corruption from
    * killing mid-turn). `taskkill /T /F` on Windows, mirroring
    * `../pi/rpc-client.ts`'s own cross-platform convention.
+   *
+   * Fire-and-forget by design: an interrupt must not block on a terminator,
+   * and `dispose()` is the settlement receipt. A request that could not be
+   * spawned is left unrecorded, so `dispose()` re-issues it and raises the
+   * typed `stage:'signal'` failure — swallowing it here loses nothing.
    */
   kill() {
-    requestOwnedProcessTreeTermination(this.processTreeOptions());
+    void requestOwnedProcessTreeTermination(this.processTreeOptions()).catch(() => {
+    });
   }
   dispose() {
     if (!this.disposalAttempt) {
@@ -2439,7 +2629,15 @@ async function runCodexTurn(params) {
           }
           return;
         }
-        const mapped = mapCodexEventToAgentEvents(evt, params.workspaceDir);
+        let mapped;
+        try {
+          mapped = mapCodexEventToAgentEvents(evt, params.workspaceDir);
+        } catch (cause) {
+          if (!isRuntimeExecutionFailure(cause)) throw cause;
+          params.terminal.failure = cause;
+          params.queue.end();
+          return;
+        }
         for (const agentEvent of mapped) {
           if (agentEvent.type === "turn_end") turnEnded = true;
           params.queue.push(agentEvent);