@byok-sdk/client 0.4.0 → 0.4.2

package/dist/adapters/pi/resolve-bin.d.ts

@@ -25,7 +25,7 @@ export interface ResolvedBin {
  * only ever constructs `new PiAdapter()` with no options (see `createDaemon`),
  * so an out-of-process substitution (e.g. examples/basic's e2e run swapping
  * in the fake-pi fixture, or a single-file product injecting its required
- * Node 22.19+ pi sidecar) has no other seam to use.
+ * Node 22.22+ pi sidecar) has no other seam to use.
  *
  * Deliberately does NOT use `createRequire(...).resolve()`: this package is
  * pure ESM with no `require` export condition (`exports["."]` only offers

package/dist/adapters/pi/rpc-client.d.ts

@@ -66,7 +66,13 @@ export declare class PiRpcClient {
      * a post-mortem on a failed/hung task has it without separate log scraping.
      */
     recordUnmappedFrame(type: 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/process-tree.d.ts

@@ -1,4 +1,5 @@
-import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+import { spawn, type ChildProcess, type SpawnOptions } from 'node:child_process';
+type KillFn = (pid: number, signal: NodeJS.Signals | number) => void;
 export interface OwnedProcessTreeOptions {
     child: ChildProcess;
     waitClosed: () => Promise<void>;
@@ -6,6 +7,12 @@ export interface OwnedProcessTreeOptions {
     label: string;
     termGraceMs?: number;
     killGraceMs?: number;
+    /** DI seam — defaults to `process.platform`. Lets the win32 branch be exercised from POSIX CI, mirroring `util/secure-dir.ts`'s identical convention. */
+    platform?: NodeJS.Platform;
+    /** DI seam for the win32 `taskkill` sweep — defaults to `node:child_process`'s `spawn`. */
+    spawnFn?: typeof spawn;
+    /** DI seam for liveness probing — defaults to `process.kill`. */
+    killFn?: KillFn;
 }
 /**
  * Every bundled runtime root is an owned process-group leader on POSIX. Pipes
@@ -13,7 +20,41 @@ export interface OwnedProcessTreeOptions {
  * the runtime outlive the daemon. Windows uses taskkill's `/T` tree authority.
  */
 export declare function withOwnedProcessTree<T extends SpawnOptions>(options: T): T;
-/** Immediate termination request used by interrupt paths; close remains the receipt. */
-export declare function requestOwnedProcessTreeTermination(options: OwnedProcessTreeOptions): void;
-/** Resolve only after the adapter-owned root and descendants are quiescent. */
+/**
+ * Immediate termination request used by interrupt paths; close remains the
+ * receipt. On win32 the request also RECORDS the pid set taskkill walked,
+ * which is what {@link disposeOwnedProcessTree} later measures — so an
+ * interrupt that is fired and forgotten still leaves disposal a measurable
+ * tree. A request that could not be spawned records nothing, which makes
+ * disposal re-issue it and surface `stage:'signal'` itself.
+ */
+export declare function requestOwnedProcessTreeTermination(options: OwnedProcessTreeOptions): Promise<void>;
+/**
+ * Resolve only after the adapter-owned root and descendants are quiescent.
+ *
+ * POSIX measures the owned process GROUP; win32 measures the pid set taskkill
+ * reported walking (`stage:'quiescence'` names how many of those were still
+ * alive at the deadline). Neither platform reads a terminator's exit status:
+ * on win32 `stage:'signal'` now means only that taskkill could not be spawned.
+ * `close` stays the final receipt on both — it is the stdio-flush guarantee,
+ * not the liveness proof.
+ *
+ * Grace budget: each phase carries its own full grace on both platforms. On
+ * win32 the quiescence poll gets `killGraceMs` and the close wait that follows
+ * gets a fresh `killGraceMs`; POSIX likewise gives the SIGTERM wait
+ * `termGraceMs`, the SIGKILL wait `killGraceMs`, and the close wait another
+ * `killGraceMs`. Worst-case disposal is therefore bounded by the sum, never by
+ * one shared deadline that could starve the close wait after a slow drain.
+ *
+ * Residual boundary, stated honestly. Three cases this mechanism cannot cover:
+ * a descendant whose intermediate parent died before any sweep observed it is
+ * unreachable, because Windows does not re-parent orphans — nothing in the
+ * surviving tree links back to it and `taskkill /T` cannot find it. The same
+ * window means a recycled pid could read as alive. And if taskkill's output is
+ * empty or unparseable, the walked set collapses to `{root}`: disposal then
+ * measures the root alone and reports quiescence on that basis, which is a
+ * narrower claim than the tree, not a false one. Preventing orphans left behind
+ * by a DAEMON crash is a separate job-object concern, explicitly out of scope.
+ */
 export declare function disposeOwnedProcessTree(options: OwnedProcessTreeOptions): Promise<void>;
+export {};

package/dist/adapters/taskkill-pid-set.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Windows-only: recovers the process-tree PID set that `taskkill /T /F`
+ * reports it walked, so `process-tree.ts` can MEASURE quiescence instead of
+ * trusting taskkill's exit status.
+ *
+ * Two constraints shape this parser:
+ *
+ * - taskkill's messages are LOCALIZED (the same run prints
+ *   `SUCCESS: The process with PID ...` on en-US and a translated sentence on
+ *   de-DE/zh-CN/ja-JP), so no word, prefix, or field label may be matched.
+ *   Only the integers and their CO-OCCURRENCE on one line are stable: every
+ *   line taskkill emits for a walked process names that process and its
+ *   parent together. Seeding with the root pid and closing over co-occurrence
+ *   therefore reaches exactly the walked tree, in any locale.
+ * - the text arrives in the console OEM codepage, not UTF-8. It is decoded as
+ *   latin1 (byte-preserving) rather than guessed: every OEM codepage taskkill
+ *   can use encodes ASCII digits as single bytes 0x30-0x39, and no DBCS trail
+ *   byte (CP932/CP936/CP949/CP950 all start their trail range at 0x40) can
+ *   land in that range. Undecodable non-ASCII bytes become mojibake, which is
+ *   irrelevant: they can never manufacture a digit.
+ *
+ * Line ORDER is deliberately not relied on (taskkill emits children before
+ * parents today); the walk iterates to a fixpoint instead.
+ */
+/**
+ * Returns the PID set reachable from `rootPid` by co-occurrence over `text`.
+ *
+ * `excludedPids` removes integers that must never enter the set even when
+ * they share a line with an accepted pid — taskkill names the ROOT's own
+ * parent (this daemon process) on the root's line, and accepting it would
+ * make quiescence unreachable by construction. `rootPid` is always seeded and
+ * is never subject to exclusion.
+ */
+export declare function walkTaskkillPidSet(text: string, rootPid: number, excludedPids?: Iterable<number>): Set<number>;