@byok-sdk/client 0.3.0 → 0.4.1

package/dist/adapters/pi/pi-adapter.d.ts

@@ -1,5 +1,4 @@
-import type { TaskOfferPayload } from '@byok-sdk/protocol';
-import { type RuntimeAdapter, type RuntimeCapabilities, type RuntimeDetectResult, type RuntimeEnvironmentRequirements, type Session, type TaskContext } from '../../types';
+import { type RuntimeAdapter, type RuntimeDetectResult, type RuntimeAdapterPrepareInput, type RuntimeAdapterPrepareResult } from '../../types';
 import { type ResolvedBin } from './resolve-bin';
 import { type SpawnFn } from './rpc-client';
 /**
@@ -31,21 +30,9 @@ export interface PiByokLauncherConfig {
 }
 export declare class PiAdapter implements RuntimeAdapter {
     private readonly options;
-    readonly id = "pi";
-    readonly supportsDispatchSelection = true;
+    readonly descriptor: import("..").RuntimeAdapterDescriptor;
     constructor(options?: PiAdapterOptions);
     detect(): Promise<RuntimeDetectResult>;
-    capabilities(): RuntimeCapabilities;
-    /**
-     * M5: pi authenticates to its ~30 supported providers via env-var API
-     * keys — `detect()`'s own `authPresent` probe above checks this identical
-     * list — so these MUST keep flowing into pi's spawned process or pi auth
-     * breaks entirely. `KNOWN_PROVIDER_ENV_VARS` above is the single source
-     * of truth, reused here rather than duplicated. No `baseNames`: nothing
-     * in this adapter or `rpc-client.ts` reads a pi-specific config-discovery
-     * variable beyond the platform baseline (`daemon/environment.ts`).
-     */
-    environmentRequirements(): RuntimeEnvironmentRequirements;
-    start(task: TaskOfferPayload, ctx: TaskContext): Promise<Session>;
+    prepare(input: RuntimeAdapterPrepareInput): Promise<RuntimeAdapterPrepareResult>;
     private resolveBin;
 }

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

@@ -39,6 +39,9 @@ export declare class PiRpcClient {
     private readonly eventQueue;
     private closed;
     private exitError;
+    private readonly closedPromise;
+    private resolveClosed;
+    private 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`. */
     private readonly 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`. */
@@ -51,6 +54,8 @@ export declare class PiRpcClient {
     }): Promise<PiRpcMessage>;
     /** Every non-response, non-`extension_ui_request` line — the latter is answered directly by this client (see `respondToExtensionUiRequest`) and never enqueued. */
     get events(): AsyncIterable<PiRpcMessage>;
+    /** Local transport diagnostic retained when the process closes; consumers must classify it explicitly. */
+    get terminalError(): Error | undefined;
     /**
      * Record a pi RPC message `type` that `PiSession` (pi-adapter.ts) decided
      * has no `AgentEvent` mapping and isn't routine bookkeeping (see
@@ -61,8 +66,17 @@ export declare class PiRpcClient {
      * a post-mortem on a failed/hung task has it without separate log scraping.
      */
     recordUnmappedFrame(type: string): void;
-    /** Best-effort teardown. SIGTERM on POSIX; `taskkill /T /F` on Windows to also reap child processes pi itself spawned (e.g. bash). */
+    /**
+     * 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>;
+    private processTreeOptions;
     private onData;
     private onLine;
     /**

package/dist/adapters/process-tree.d.ts

@@ -0,0 +1,60 @@
+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>;
+    isClosed: () => boolean;
+    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
+ * remain referenced, so `detached` changes ownership topology without making
+ * 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. 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>;

package/dist/bin/audit-log.d.ts

@@ -118,6 +118,18 @@ export declare const AUDIT_LOG_TRIM_TARGET_LINES = 5000;
  * tail) rather than the file growing without bound.
  */
 export declare const MAX_LIVE_TASK_ANCHORS = 500;
+/**
+ * Git failures are serialized only as this closed, stable category set —
+ * never raw Git errors or command output. Projected from
+ * `daemon/git-workspace.ts`'s `GIT_ERROR_CATEGORIES` (the single source of
+ * truth for the `GitErrorCategory` union) rather than carrying a literal
+ * copy that could drift from it; the runtime half of that guarantee is
+ * `__tests__/git-category-drift.test.ts`.
+ *
+ * @internal Exported for the drift-guard test only (never re-exported from
+ * `index.ts`).
+ */
+export declare const STABLE_GIT_ERROR_CATEGORIES: Set<string>;
 /**
  * Appends one `DaemonEvent` as a single redacted JSON line (finding P1 #3 —
  * see this file's module doc comment) at 0600, and rotates the file if it's