@byok-sdk/client 0.13.0 → 0.14.0

package/dist/adapters/index.js

@@ -1,4 +1,4 @@
-import { execFile, spawn } from 'child_process';
+import { execFile, spawn, spawnSync } from 'child_process';
 import { promises, existsSync, readFileSync, realpathSync } from 'fs';
 import os from 'os';
 import path5, { isAbsolute } from 'path';
@@ -6,6 +6,131 @@ import { promisify } from 'util';
 import { fileURLToPath } from 'url';
 import 'readline';
 
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/adapters/win32-job-object.ts
+var win32_job_object_exports = {};
+__export(win32_job_object_exports, {
+  Win32JobObjectFailure: () => Win32JobObjectFailure,
+  assignOwnedProcessToJob: () => assignOwnedProcessToJob,
+  isWin32JobObjectFailure: () => isWin32JobObjectFailure,
+  loadBindings: () => loadBindings
+});
+function isWin32JobObjectFailure(value) {
+  return value instanceof Error && value.name === "Win32JobObjectFailure";
+}
+function isNullHandle(value) {
+  return value === null || value === void 0 || value === 0n || value === 0;
+}
+async function loadBindings() {
+  if (cachedBindings !== void 0) return cachedBindings;
+  let koffi;
+  try {
+    const imported = await import('koffi');
+    koffi = imported.default ?? imported;
+  } catch (cause) {
+    throw new Win32JobObjectFailure({
+      step: "loadKoffi",
+      reason: "win32 runtime process ownership requires the koffi optional dependency, which could not be loaded"
+    }, { cause });
+  }
+  const kernel32 = koffi.load("kernel32.dll");
+  const PVOID = koffi.pointer("void");
+  const bind = (name, result, args) => kernel32.func("__stdcall", name, result, args);
+  cachedBindings = {
+    createJobObjectW: bind("CreateJobObjectW", PVOID, [PVOID, "str16"]),
+    setInformationJobObject: bind("SetInformationJobObject", "int", [PVOID, "int", PVOID, "uint32"]),
+    openProcess: bind("OpenProcess", PVOID, ["uint32", "int", "uint32"]),
+    assignProcessToJobObject: bind("AssignProcessToJobObject", "int", [PVOID, PVOID]),
+    closeHandle: bind("CloseHandle", "int", [PVOID]),
+    getLastError: bind("GetLastError", "uint32", [])
+  };
+  return cachedBindings;
+}
+function killOnCloseLimitInformation() {
+  const information = Buffer.alloc(JOBOBJECT_EXTENDED_LIMIT_SIZE);
+  information.writeUInt32LE(JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE, JOBOBJECT_EXTENDED_LIMIT_FLAGS_OFFSET);
+  return information;
+}
+function daemonJob(bindings) {
+  const existing = jobsByBindings.get(bindings);
+  if (existing !== void 0) return existing;
+  const job = bindings.createJobObjectW(null, null);
+  if (isNullHandle(job)) {
+    throw new Win32JobObjectFailure({
+      step: "CreateJobObjectW",
+      reason: "win32 runtime process ownership could not create the daemon kill-on-close job object",
+      win32Code: bindings.getLastError()
+    });
+  }
+  const information = killOnCloseLimitInformation();
+  if (bindings.setInformationJobObject(job, JobObjectExtendedLimitInformation, information, information.length) === 0) {
+    const win32Code = bindings.getLastError();
+    bindings.closeHandle(job);
+    throw new Win32JobObjectFailure({
+      step: "SetInformationJobObject",
+      reason: "win32 runtime process ownership could not make the daemon job object kill-on-close",
+      win32Code
+    });
+  }
+  jobsByBindings.set(bindings, job);
+  return job;
+}
+async function assignOwnedProcessToJob(pid, options) {
+  const bindings = options?.bindings ?? await loadBindings();
+  const job = daemonJob(bindings);
+  const processHandle = bindings.openProcess(OWNED_PROCESS_ACCESS, 0, pid);
+  if (isNullHandle(processHandle)) {
+    throw new Win32JobObjectFailure({
+      step: "OpenProcess",
+      reason: `win32 runtime process ownership could not open process ${pid} for job assignment`,
+      win32Code: bindings.getLastError()
+    });
+  }
+  try {
+    if (bindings.assignProcessToJobObject(job, processHandle) === 0) {
+      throw new Win32JobObjectFailure({
+        step: "AssignProcessToJobObject",
+        reason: `win32 runtime process ownership could not assign process ${pid} to the daemon kill-on-close job object`,
+        win32Code: bindings.getLastError()
+      });
+    }
+  } finally {
+    bindings.closeHandle(processHandle);
+  }
+}
+var JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE, JobObjectExtendedLimitInformation, JOBOBJECT_EXTENDED_LIMIT_SIZE, JOBOBJECT_EXTENDED_LIMIT_FLAGS_OFFSET, PROCESS_SET_QUOTA, PROCESS_TERMINATE, OWNED_PROCESS_ACCESS, Win32JobObjectFailure, cachedBindings, jobsByBindings;
+var init_win32_job_object = __esm({
+  "src/adapters/win32-job-object.ts"() {
+    JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 8192;
+    JobObjectExtendedLimitInformation = 9;
+    JOBOBJECT_EXTENDED_LIMIT_SIZE = 144;
+    JOBOBJECT_EXTENDED_LIMIT_FLAGS_OFFSET = 16;
+    PROCESS_SET_QUOTA = 256;
+    PROCESS_TERMINATE = 1;
+    OWNED_PROCESS_ACCESS = PROCESS_SET_QUOTA | PROCESS_TERMINATE;
+    Win32JobObjectFailure = class extends Error {
+      step;
+      win32Code;
+      constructor(input, options) {
+        super(input.reason, options);
+        this.name = "Win32JobObjectFailure";
+        this.step = input.step;
+        this.win32Code = input.win32Code;
+      }
+    };
+    jobsByBindings = /* @__PURE__ */ new WeakMap();
+  }
+});
+
 // src/runtime-failure.ts
 var RUNTIME_EXECUTION_FAILURE_BRAND = /* @__PURE__ */ Symbol.for("@byok-sdk/client/RuntimeExecutionFailure/v1");
 var RUNTIME_DISPOSAL_FAILURE_BRAND = /* @__PURE__ */ Symbol.for("@byok-sdk/client/RuntimeDisposalFailure/v1");
@@ -436,6 +561,55 @@ function withOwnedProcessTree(options) {
     ...process.platform === "win32" ? { windowsHide: true } : { detached: true }
   };
 }
+var hostExitTargets = /* @__PURE__ */ new Map();
+var hostExitHandlerInstalled = false;
+function terminateOwnedTreesForHostExit() {
+  for (const target of hostExitTargets.values()) {
+    try {
+      if (target.platform === "win32") {
+        target.spawnSyncFn("taskkill", ["/PID", String(target.pid), "/T", "/F"], {
+          stdio: "ignore",
+          windowsHide: true
+        });
+      } else {
+        target.kill(-target.pid, "SIGKILL");
+      }
+    } catch {
+    }
+  }
+  hostExitTargets.clear();
+}
+function ensureHostExitHandler() {
+  if (hostExitHandlerInstalled) return;
+  hostExitHandlerInstalled = true;
+  process.prependListener("exit", terminateOwnedTreesForHostExit);
+}
+var defaultJobObject = {
+  async assign(pid) {
+    const { assignOwnedProcessToJob: assignOwnedProcessToJob2 } = await Promise.resolve().then(() => (init_win32_job_object(), win32_job_object_exports));
+    await assignOwnedProcessToJob2(pid);
+  }
+};
+async function adoptOwnedProcessTree(options) {
+  const pid = positivePid(options.child, options.label);
+  if (pid === void 0) return;
+  const platform = options.platform ?? process.platform;
+  ensureHostExitHandler();
+  hostExitTargets.set(options.child, {
+    pid,
+    label: options.label,
+    platform,
+    kill: options.killFn ?? defaultKill,
+    spawnSyncFn: options.spawnSyncFn ?? spawnSync
+  });
+  const forget = () => {
+    hostExitTargets.delete(options.child);
+  };
+  options.child.once("close", forget);
+  options.child.once("exit", forget);
+  if (platform !== "win32") return;
+  await (options.jobObject ?? defaultJobObject).assign(pid);
+}
 function positivePid(child, label) {
   const pid = child.pid;
   if (pid === void 0) return void 0;
@@ -647,21 +821,8 @@ async function disposeOwnedProcessTree(options) {
 var STDERR_RING_CAPACITY = 20;
 var DIALOG_UI_METHODS = /* @__PURE__ */ new Set(["select", "confirm", "input", "editor"]);
 var PiRpcClient = class {
-  child;
-  buffer = "";
-  nextId = 1;
-  pending = /* @__PURE__ */ new Map();
-  eventQueue = new AsyncQueue();
-  closed = false;
-  exitError;
-  closedPromise;
-  resolveClosed;
-  disposalAttempt;
-  /** Bounded tail of recent stderr lines — pi discarded this entirely before (nothing ever read `child.stderr`), which is exactly why finding #1 (`Error: Unknown option: --session-id`, exit 1) had to be root-caused by hand instead of reading it off a thrown error. See `buildExitError`. */
-  stderrRing = [];
-  /** Count of pi RPC message types `PiSession` (pi-adapter.ts) has told us have no `AgentEvent` mapping and aren't routine bookkeeping — see `recordUnmappedFrame`. */
-  unmappedFrameCounts = /* @__PURE__ */ new Map();
   constructor(options) {
+    this.options = options;
     const spawnFn = options.spawnFn ?? spawn;
     this.child = spawnFn(options.command, options.args, withOwnedProcessTree({
       cwd: options.cwd,
@@ -671,6 +832,9 @@ var PiRpcClient = class {
     this.closedPromise = new Promise((resolve) => {
       this.resolveClosed = resolve;
     });
+    this.adopted = this.adoptOwnedTree(options);
+    this.adopted.catch(() => {
+    });
     this.child.stdout.setEncoding("utf8");
     this.child.stdout.on("data", (chunk) => this.onData(chunk));
     this.child.stderr.setEncoding("utf8");
@@ -682,10 +846,37 @@ var PiRpcClient = class {
       this.onClosed(err);
     });
   }
-  /** Send a command, resolved with its correlated `response` message. */
-  send(command) {
+  options;
+  child;
+  buffer = "";
+  nextId = 1;
+  pending = /* @__PURE__ */ new Map();
+  eventQueue = new AsyncQueue();
+  closed = false;
+  exitError;
+  closedPromise;
+  resolveClosed;
+  disposalAttempt;
+  /** Resolves once this tree is backstopped (see `adoptOwnedProcessTree`); rejects with the adoption failure, having already terminated the tree. */
+  adopted;
+  /** Set before the fail-closed termination starts, so it — not the exit code of the kill we ourselves requested — becomes this client's exit error. */
+  adoptionFailure;
+  /** Bounded tail of recent stderr lines — pi discarded this entirely before (nothing ever read `child.stderr`), which is exactly why finding #1 (`Error: Unknown option: --session-id`, exit 1) had to be root-caused by hand instead of reading it off a thrown error. See `buildExitError`. */
+  stderrRing = [];
+  /** Count of pi RPC message types `PiSession` (pi-adapter.ts) has told us have no `AgentEvent` mapping and aren't routine bookkeeping — see `recordUnmappedFrame`. */
+  unmappedFrameCounts = /* @__PURE__ */ new Map();
+  /**
+   * Send a command, resolved with its correlated `response` message.
+   *
+   * Adoption is awaited FIRST — this is `PiAdapter.start()`'s first awaited
+   * operation, so an unbackstopped tree never receives the initial prompt and
+   * never yields a session. The wait costs one settled-promise turn once the
+   * tree is adopted; every later command sees it already resolved.
+   */
+  async send(command) {
+    await this.adopted;
     if (this.closed) {
-      return Promise.reject(this.exitError ?? new Error("pi process is closed"));
+      throw this.exitError ?? new Error("pi process is closed");
     }
     const id = command.id ?? `req-${this.nextId++}`;
     const full = { ...command, id };
@@ -758,6 +949,32 @@ var PiRpcClient = class {
       label: "pi"
     };
   }
+  /**
+   * Backstop this tree, or tear it down. Adoption failure is a start-time
+   * precondition, not a degraded mode: the child is terminated through the one
+   * disposal authority and the failure is re-thrown, which is what makes the
+   * first `send()` — and therefore `PiAdapter.start()` — fail before any
+   * session is published. Both cleanup attempts are best-effort because the
+   * adoption failure, not a terminator's own complaint, is the reason to report.
+   */
+  async adoptOwnedTree(options) {
+    try {
+      await adoptOwnedProcessTree({
+        child: this.child,
+        label: "pi",
+        platform: options.platform,
+        jobObject: options.jobObject
+      });
+    } catch (cause) {
+      const failure = cause instanceof Error ? cause : new Error(String(cause));
+      this.adoptionFailure = failure;
+      await requestOwnedProcessTreeTermination(this.processTreeOptions()).catch(() => {
+      });
+      await disposeOwnedProcessTree(this.processTreeOptions()).catch(() => {
+      });
+      throw failure;
+    }
+  }
   onData(chunk) {
     this.buffer += chunk;
     let newlineIndex = this.buffer.indexOf("\n");
@@ -776,6 +993,7 @@ var PiRpcClient = class {
     } catch {
       return;
     }
+    this.options.onFrame?.(msg);
     if (msg.type === "response" && typeof msg.id === "string" && this.pending.has(msg.id)) {
       const waiter = this.pending.get(msg.id);
       this.pending.delete(msg.id);
@@ -783,11 +1001,20 @@ var PiRpcClient = class {
       return;
     }
     if (msg.type === "extension_ui_request" && typeof msg.id === "string" && typeof msg.method === "string") {
-      this.respondToExtensionUiRequest(msg.id, msg.method);
+      if (this.options.extensionUi?.mode === "hold") this.options.extensionUi.onRequest(msg);
+      else this.respondToExtensionUiRequest(msg.id, msg.method);
       return;
     }
     this.eventQueue.push(msg);
   }
+  /** Write an explicit host-owned response; completion is a transport receipt only. */
+  async respondExtensionUi(response) {
+    if (this.options.extensionUi?.mode !== "hold") throw new Error("Pi interactions are not host-owned");
+    await this.adopted;
+    if (this.closed) throw new Error("Pi process is closed");
+    await new Promise((resolve, reject) => this.child.stdin.write(`${JSON.stringify({ type: "extension_ui_response", ...response })}
+`, (error) => error ? reject(error) : resolve()));
+  }
   /**
    * Answer pi's extension-UI blocking protocol headlessly (rpc.md's
    * "Extension UI Protocol"). Fail-closed policy, stated explicitly because
@@ -841,9 +1068,10 @@ var PiRpcClient = class {
   onClosed(err) {
     if (this.closed) return;
     this.closed = true;
-    this.exitError = err;
+    const terminal = this.adoptionFailure ?? err;
+    this.exitError = terminal;
     this.resolveClosed();
-    for (const [, waiter] of this.pending) waiter.reject(err);
+    for (const [, waiter] of this.pending) waiter.reject(terminal);
     this.pending.clear();
     this.eventQueue.end();
   }
@@ -877,6 +1105,8 @@ var PROVIDER_CREDENTIAL_ENV_DENY_NAMES = [
   "TOGETHER_API_KEY",
   "BASETEN_API_KEY",
   "KIMI_API_KEY",
+  "HF_TOKEN",
+  "MOONSHOT_API_KEY",
   "MINIMAX_API_KEY",
   "MINIMAX_CN_API_KEY",
   "QWEN_TOKEN_PLAN_API_KEY",
@@ -1753,6 +1983,10 @@ var ClaudeProcessClient = class {
   closedPromise;
   resolveClosed;
   disposalAttempt;
+  /** Resolves once this tree is backstopped (see `adoptOwnedProcessTree`); rejects with the adoption failure, having already terminated the tree. */
+  adopted;
+  /** Set before the fail-closed termination starts, so it — not the exit code of the kill we ourselves requested — becomes this client's exit error. */
+  adoptionFailure;
   stderrRing = [];
   unmappedFrameCounts = /* @__PURE__ */ new Map();
   sessionId;
@@ -1767,6 +2001,9 @@ var ClaudeProcessClient = class {
     this.closedPromise = new Promise((resolve) => {
       this.resolveClosed = resolve;
     });
+    this.adopted = this.adoptOwnedTree(options);
+    this.adopted.catch(() => {
+    });
     this.child.stdout.setEncoding("utf8");
     this.child.stdout.on("data", (chunk) => this.onData(chunk));
     this.child.stderr.setEncoding("utf8");
@@ -1810,9 +2047,10 @@ var ClaudeProcessClient = class {
    * same id; if the process already closed before init ever arrived,
    * every call rejects with that same exit error.
    */
-  waitForInit() {
-    if (this.sessionId !== void 0) return Promise.resolve(this.sessionId);
-    if (this.closed) return Promise.reject(this.exitError ?? new Error("claude process is closed"));
+  async waitForInit() {
+    await this.adopted;
+    if (this.sessionId !== void 0) return this.sessionId;
+    if (this.closed) throw this.exitError ?? new Error("claude process is closed");
     return new Promise((resolve, reject) => {
       this.initWaiter = { resolve, reject };
     });
@@ -1876,6 +2114,32 @@ var ClaudeProcessClient = class {
       label: "claude"
     };
   }
+  /**
+   * Backstop this tree, or tear it down. Adoption failure is a start-time
+   * precondition, not a degraded mode: the child is terminated through the one
+   * disposal authority and the failure is re-thrown, which is what makes
+   * `waitForInit()` — and therefore `ClaudeAdapter.start()` — fail before any
+   * session is published. Both cleanup attempts are best-effort because the
+   * adoption failure, not a terminator's own complaint, is the reason to report.
+   */
+  async adoptOwnedTree(options) {
+    try {
+      await adoptOwnedProcessTree({
+        child: this.child,
+        label: "claude",
+        platform: options.platform,
+        jobObject: options.jobObject
+      });
+    } catch (cause) {
+      const failure = cause instanceof Error ? cause : new Error(String(cause));
+      this.adoptionFailure = failure;
+      await requestOwnedProcessTreeTermination(this.processTreeOptions()).catch(() => {
+      });
+      await disposeOwnedProcessTree(this.processTreeOptions()).catch(() => {
+      });
+      throw failure;
+    }
+  }
   onData(chunk) {
     this.buffer += chunk;
     let newlineIndex = this.buffer.indexOf("\n");
@@ -1924,9 +2188,10 @@ var ClaudeProcessClient = class {
   onClosed(err) {
     if (this.closed) return;
     this.closed = true;
-    this.exitError = err;
+    const terminal = this.adoptionFailure ?? err;
+    this.exitError = terminal;
     this.resolveClosed();
-    this.initWaiter?.reject(err);
+    this.initWaiter?.reject(terminal);
     this.initWaiter = void 0;
     this.eventQueue.end();
   }
@@ -2662,6 +2927,19 @@ var CodexProcessRunner = class {
   closedPromise;
   resolveClosed;
   disposalAttempt;
+  /** Resolves once this tree is backstopped (see `adoptOwnedProcessTree`); rejects with the adoption failure, having already terminated the tree. */
+  adopted;
+  /** Set before the fail-closed termination starts; `buildExitError` reports it instead of the exit status of the kill we ourselves requested. */
+  adoptionFailure;
+  adoption = "pending";
+  /**
+   * Lines parsed before adoption settled. Unlike pi and claude, this runner has
+   * no first awaited operation of its own to gate on — its caller reads the
+   * FIRST event as the authoritative thread id. Holding events until the tree
+   * is backstopped is what keeps that caller from publishing a session for a
+   * tree the job object never took.
+   */
+  deferredEvents = [];
   constructor(options) {
     this.onEvent = options.onEvent;
     const spawnFn = options.spawnFn ?? spawn;
@@ -2673,6 +2951,9 @@ var CodexProcessRunner = class {
     this.closedPromise = new Promise((resolve) => {
       this.resolveClosed = resolve;
     });
+    this.adopted = this.adoptOwnedTree(options);
+    this.adopted.catch(() => {
+    });
     this.child.stdout.setEncoding("utf8");
     this.child.stdout.on("data", (chunk) => this.onData(chunk));
     this.child.stderr.setEncoding("utf8");
@@ -2738,8 +3019,58 @@ var CodexProcessRunner = class {
       label: "codex"
     };
   }
-  /** Builds a descriptive error folding in the exit code/signal and the stderr tail — mirrors `PiRpcClient.buildExitError`'s reasoning: a post-mortem on a failed start/resume should never need separately re-running codex by hand with a raw JSONL logger to learn why. */
+  /**
+   * Backstop this tree, or tear it down. Adoption failure is a start-time
+   * precondition, not a degraded mode: the child is terminated through the one
+   * disposal authority, every parsed line is dropped instead of delivered, and
+   * the resulting close makes the caller's own `waitClosed()` race reject with
+   * the adoption failure (`buildExitError`) before a thread id is published.
+   * Both cleanup attempts are best-effort because the adoption failure, not a
+   * terminator's own complaint, is the reason to report.
+   */
+  async adoptOwnedTree(options) {
+    try {
+      await adoptOwnedProcessTree({
+        child: this.child,
+        label: "codex",
+        platform: options.platform,
+        jobObject: options.jobObject
+      });
+    } catch (cause) {
+      const failure = cause instanceof Error ? cause : new Error(String(cause));
+      this.adoptionFailure = failure;
+      this.adoption = "failed";
+      this.deferredEvents.length = 0;
+      await requestOwnedProcessTreeTermination(this.processTreeOptions()).catch(() => {
+      });
+      await disposeOwnedProcessTree(this.processTreeOptions()).catch(() => {
+      });
+      throw failure;
+    }
+    this.adoption = "adopted";
+    for (const evt of this.deferredEvents.splice(0)) this.onEvent(evt);
+  }
+  /** Arrival-order delivery, held back until the tree is backstopped (see `deferredEvents`). */
+  deliver(evt) {
+    if (this.adoption === "failed") return;
+    if (this.adoption === "pending") {
+      this.deferredEvents.push(evt);
+      return;
+    }
+    this.onEvent(evt);
+  }
+  /**
+   * Builds a descriptive error folding in the exit code/signal and the stderr
+   * tail — mirrors `PiRpcClient.buildExitError`'s reasoning: a post-mortem on a
+   * failed start/resume should never need separately re-running codex by hand
+   * with a raw JSONL logger to learn why.
+   *
+   * A tree this runner could not backstop is the one exception: that process
+   * exited because THIS runner killed it, so `exit code=null, signal=SIGKILL`
+   * plus an empty stderr tail would bury the only reason anyone can act on.
+   */
   buildExitError(context) {
+    if (this.adoptionFailure !== void 0) return this.adoptionFailure;
     const parts = [`${context} (exit code=${this.exitCode}, signal=${this.exitSignal})`];
     if (this.stderrRing.length > 0) {
       parts.push(`stderr: ${this.stderrRing.join(" | ")}`);
@@ -2767,7 +3098,7 @@ var CodexProcessRunner = class {
     if (!parsed || typeof parsed !== "object" || typeof parsed.type !== "string") {
       return;
     }
-    this.onEvent(parsed);
+    this.deliver(parsed);
   }
   onStderr(chunk) {
     for (const rawLine of chunk.split("\n")) {