@byok-sdk/client 0.13.0 → 0.15.0

package/README.md

@@ -1,5 +1,20 @@
 # @byok-sdk/client
 
+## Diagnostics and recovery integration
+
+Use the SDK-maintained [downstream guide](https://github.com/Ancienttwo/byok-sdk/blob/main/docs/agent-diagnostics-integration.md)
+to build diagnostic UI and local repair flows. `byok-agent doctor --json` is
+the current read-only CLI entrypoint; `--fix --yes` only quarantines confirmed-corrupt
+operational health state with the daemon stopped. It does not repair an Agent
+or rebuild its journal. The guide includes integration limits and acceptance
+scenarios; qualify them against the exact SDK artifact shipped by your product.
+
+The public `diagnoseDevice` API accepts the host's actual adapters.
+`repairDeviceEnrollmentMetadata` (or the named CLI `--repair restore-enrollment-metadata`
+action) restores missing/valid-stale non-secret enrollment metadata from its
+existing OS authority, with confirmation, exact expected tenant/device and
+exclusive store ownership. It does not renew credentials or prove Agent readiness.
+
 ## Exact provider-profile admission
 
 When `DaemonConfig.piByokLauncher` is configured, the daemon advertises the
@@ -354,4 +369,84 @@ plain watcher. Native Windows returns `unsupported_platform` for the tmux view.
 The launcher never uses `send-keys` or `capture-pane`; tmux displays the
 daemon-owned stream but is never message transport or protocol authority.
 
+### Automatic notification for two existing Codex sessions
+
+Configure two operator-owned Codex app-server sessions with their respective
+`team join` MCP grants. Record each exact native thread UUID and local endpoint.
+The relay does not create sessions or verify your member-to-session mapping.
+Write an absolute-path JSON file with mode `0600` (its contexts are bearer secrets):
+
+```json
+{"version":1,"bindings":[
+  {"context":"<member-a-context>","threadId":"<native-thread-a-uuid>","endpoint":"ws://127.0.0.1:9101","afterSeq":0},
+  {"context":"<member-b-context>","threadId":"<native-thread-b-uuid>","endpoint":"ws://127.0.0.1:9102","afterSeq":0}
+]}
+```
+
+```bash
+byok-agent team relay dev --bindings /absolute/private-bindings.json --codex-bin /absolute/codex --max-notifications 2 --config /absolute/agent.json
+```
+
+POSIX only; the executable must report `codex-cli 0.153.4`, the qualified native
+queue version. Endpoints must be explicit loopback `ws://127.0.0.1:<port>` /
+`ws://[::1]:<port>` or `unix:///absolute/socket`. No remote server discovery. Loopback app-server queue endpoints trust local
+processes; the relay does not add authentication to the native Codex endpoint.
+Keep the foreground command open and enter `pause`, `resume`, `status`, or `stop`;
+SIGINT/SIGTERM also stop. Output includes queue attempts/receipts and redacted
+state. A successful queue receipt means accepted notification, not completed work.
+The model reads, replies and acknowledges with the existing Team MCP tools.
+
+The required budget counts every attempt, capped at 100. Unknown delivery,
+revoked/expired grant or control failure stops without retry. An operator stop
+during enqueue can report `stopped` with `queue_delivery_unknown`: aborting the
+local queue process cannot prove the native server rejected the notification. Pause does not undo
+queued work. A room lock rejects concurrent relays; inspect the recorded owner
+before manually removing a stale `<storeDir>/team-relay-locks/<room>.lock`.
+Watermarks are process-local. On restart choose `afterSeq` explicitly from prior
+status and actual room receipts; do not assume automatic crash replay, exactly-once
+or guaranteed at-least-once delivery. Renewing grants requires explicitly updating
+both the session MCP grant and binding file. tmux remains an optional view.
+
+### Codex + Pi through a GUI host
+
+`team pi-relay` owns a fresh Pi **0.85.1** RPC child alongside your existing Codex
+session. Prepare a private `0600` absolute-path binding document:
+
+```json
+{"version":1,"codex":{"context":"<codex-grant>","threadId":"<uuid>","endpoint":"ws://127.0.0.1:9101","afterSeq":0},"pi":{"context":"<pi-grant>","afterSeq":0,"cwd":"/absolute/workspace","sessionDir":"/absolute/new-session-dir","provider":"<provider>","model":"<model>","systemPrompt":"<explicit instructions>","extensionPaths":[]}}
+```
+
+The session directory must not exist; its parent must exist. The SDK supplies the
+Pi Team MCP tools and guard extension. Additional absolute extension paths are
+operator-trusted code, loaded after the guard. Ambient extension loading is off.
+
+```bash
+byok-agent team pi-relay dev --bindings /absolute/private.json --codex-bin /absolute/codex --max-notifications 2 --config /absolute/agent.json
+```
+
+Connect a GUI backend to stdin/stdout JSONL. This command provides the interface;
+it does not include a GUI app. Keep stdin open while the session runs.
+
+```json
+{"command":"status"}
+{"command":"pause"}
+{"command":"resume"}
+{"command":"input","sessionId":"<pi_ready sessionId>","message":"<operator input>"}
+{"command":"respond","sessionId":"<ui_request sessionId>","requestId":"<request.id>","response":{"cancelled":true}}
+{"command":"stop"}
+```
+
+For confirm, use `{"confirmed":true}` or `false`; for select/input/editor, use
+`{"value":"..."}`. Exactly one response field is accepted. Wrong session, stale ID,
+duplicate answer or mismatched shape is rejected. `ui_response_sent` confirms pipe
+write only: Pi may have expired that ID. Expiry leaves the GUI item pending until
+you explicitly dismiss it. Render `ui_request.request` as untrusted display data.
+
+The first-loaded native guard holds input/provider admission during Pi UI spans.
+`pi_gate` reports that state; `pi_settled` reports completed native work. Busy Pi
+waits for readiness. A 30-second unresolved RPC stops the owned process, without
+retry. Budget exhaustion drains accepted Pi work for up to 120 seconds; explicit
+stop or stdin EOF terminates it. Neither pause nor a new dialog recalls already
+admitted work. Runtime/grants remain separate from the native Codex session.
+
 MIT licensed. Node.js 22.22.0 or newer.

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

@@ -7,6 +7,17 @@ export interface ClaudeProcessClientOptions {
     cwd: string;
     env: NodeJS.ProcessEnv;
     spawnFn?: SpawnFn;
+    /**
+     * DI seam scoped to ADOPTION only (`../process-tree.ts`'s
+     * `adoptOwnedProcessTree`), so the win32 job-object branch is exercisable
+     * from POSIX. Disposal keeps `process.platform` as its own authority — this
+     * must never silently reroute the taskkill sweep on a real host.
+     */
+    platform?: NodeJS.Platform;
+    /** DI seam for the win32 job-object backstop; see `../win32-job-object.ts`. */
+    jobObject?: {
+        assign(pid: number): Promise<void>;
+    };
 }
 /**
  * NDJSON process transport for `claude -p --input-format stream-json
@@ -55,6 +66,10 @@ export declare class ClaudeProcessClient {
     private readonly closedPromise;
     private resolveClosed;
     private disposalAttempt;
+    /** Resolves once this tree is backstopped (see `adoptOwnedProcessTree`); rejects with the adoption failure, having already terminated the tree. */
+    private readonly 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. */
+    private adoptionFailure;
     private readonly stderrRing;
     private readonly unmappedFrameCounts;
     private sessionId;
@@ -108,6 +123,15 @@ export declare class ClaudeProcessClient {
     waitClosed(): Promise<void>;
     dispose(): Promise<void>;
     private processTreeOptions;
+    /**
+     * 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.
+     */
+    private adoptOwnedTree;
     private onData;
     private onLine;
     private onStderr;

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

@@ -1,7 +1,9 @@
+import { type SdkHelperHostConfig } from '../../sdk-reserved-helper-host';
 import { type RuntimeAdapter, type RuntimeDetectResult, type RuntimeAdapterPrepareInput, type RuntimeAdapterPrepareResult } from '../../types';
 import { type ResolvedBin } from './resolve-bin';
 import { type SpawnFn } from './process-runner';
 export interface CodexAdapterOptions {
+    sdkHelperHost?: SdkHelperHostConfig;
     /** Override bin resolution — tests substitute the fake-codex fixture script. */
     resolveBin?: () => ResolvedBin;
     /** Override process spawning — tests substitute a fake spawn. */

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

@@ -1,3 +1,4 @@
+import { RuntimeExecutionFailure } from '../../runtime-failure';
 import { spawn } from 'node:child_process';
 export type SpawnFn = typeof spawn;
 /**
@@ -14,12 +15,28 @@ export interface CodexRawEvent {
 export interface CodexProcessOptions {
     command: string;
     args: string[];
+    instruction?: string;
     cwd: string;
     env: NodeJS.ProcessEnv;
     spawnFn?: SpawnFn;
     /** Called once per parsed JSONL line, in arrival order. */
     onEvent: (evt: CodexRawEvent) => void;
+    onFailure?: (error: RuntimeExecutionFailure) => void;
+    /**
+     * DI seam scoped to ADOPTION only (`../process-tree.ts`'s
+     * `adoptOwnedProcessTree`), so the win32 job-object branch is exercisable
+     * from POSIX. Disposal keeps `process.platform` as its own authority — this
+     * must never silently reroute the taskkill sweep on a real host.
+     */
+    platform?: NodeJS.Platform;
+    /** DI seam for the win32 job-object backstop; see `../win32-job-object.ts`. */
+    jobObject?: {
+        assign(pid: number): Promise<void>;
+    };
 }
+export declare const CODEX_MAX_FRAME_BYTES: number;
+export declare const CODEX_MAX_DEFERRED_BYTES: number;
+export declare const CODEX_MAX_STDERR_BYTES: number;
 /**
  * Spawns and streams ONE `codex exec` / `codex exec resume` invocation — i.e.
  * exactly one turn.
@@ -27,32 +44,24 @@ export interface CodexProcessOptions {
  * Unlike pi (a single long-lived RPC server process for a whole session's
  * lifetime — see `../pi/rpc-client.ts`), `codex exec` is a one-shot batch
  * process per turn with no persistent request/response channel: it takes its
- * prompt as an argv positional, streams JSONL to stdout for the one turn
+ * prompt from stdin with the documented `-` positional, streams JSONL to stdout for the one turn
  * it's running, and exits. `../codex-adapter.ts`'s `CodexSession` constructs
  * a fresh `CodexProcessRunner` for every turn (the initial `start()` and
  * every later `followUp()`), forwarding each one's lines into the same
  * long-lived event queue.
  *
- * stdin is deliberately never piped to the child (`stdio: ['ignore', 'pipe',
- * 'pipe']`): `codex exec --help` documents that a piped, non-TTY stdin is
- * read and appended to the prompt as a `<stdin>` block even when a prompt was
- * ALSO given as an argv positional, and empirically every single real
- * invocation made while building this adapter logged "Reading additional
- * input from stdin..." on stderr regardless of whether a prompt argument was
- * given. Leaving `stdio: ['pipe', ...]` open for stdin and never closing it
- * risks codex blocking on that read forever — exactly the hang class this
- * task was built to avoid (the pi adapter's own `agent_end`/`agent_settled`
- * mismatch left a task stuck `Running` forever in the M0/M1 GLM run).
- * `'ignore'` presents immediate EOF instead, which was verified live with a
- * dedicated Node `child_process` probe before this was written: no hang,
- * clean completion at normal model latency. This adapter never needs to
- * SEND codex anything over stdin — there is no in-band steer/approval
- * protocol (see `../codex-adapter.ts`'s `steer`/`resolveApproval`).
+ * Prompt stdin is closed with EOF immediately after writing. This is a one-shot
+ * input channel; steer and approvals are not multiplexed over it.
  */
 export declare class CodexProcessRunner {
     private readonly child;
     private readonly onEvent;
-    private buffer;
+    private readonly frameChunks;
+    private frameBytes;
+    private deferredBytes;
+    private stderrBytes;
+    private transportFailure;
+    private readonly onFailure;
     private readonly stderrRing;
     private closed;
     private exitCode;
@@ -60,6 +69,19 @@ export declare class CodexProcessRunner {
     private readonly closedPromise;
     private resolveClosed;
     private disposalAttempt;
+    /** Resolves once this tree is backstopped (see `adoptOwnedProcessTree`); rejects with the adoption failure, having already terminated the tree. */
+    private readonly adopted;
+    /** Set before the fail-closed termination starts; `buildExitError` reports it instead of the exit status of the kill we ourselves requested. */
+    private adoptionFailure;
+    private adoption;
+    /**
+     * 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.
+     */
+    private readonly deferredEvents;
     constructor(options: CodexProcessOptions);
     private finishClosing;
     /** Resolves once the child process has fully exited (both exit and stdio-flush guaranteed — see the `close` listener above). Never rejects. */
@@ -86,8 +108,30 @@ export declare class CodexProcessRunner {
     kill(): void;
     dispose(): Promise<void>;
     private processTreeOptions;
-    /** 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.
+     */
+    private adoptOwnedTree;
+    /** Arrival-order delivery, held back until the tree is backstopped (see `deferredEvents`). */
+    private deliver;
+    /**
+     * 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: string): Error;
+    private failTransport;
     private onData;
     private parseLine;
     private onStderr;

package/dist/adapters/detect-outcome.d.ts

@@ -0,0 +1,18 @@
+import type { RuntimeDetectResult } from '../types';
+type ProbeFailure = Exclude<RuntimeDetectResult, {
+    kind: 'available';
+}>;
+type VersionProbeResult = ProbeFailure | {
+    kind: 'available';
+    stdout: string;
+    stderr: string;
+};
+/** OS/process codes only. Arbitrary messages, streams and resolver paths never escape. */
+export declare function classifyDetectError(error: unknown): ProbeFailure;
+/**
+ * This probe owns both the deadline and the version child. A killed child is
+ * not by itself timeout evidence (execFile also kills on output overflow).
+ * Resolve only at execFile completion; SIGKILL bounds a TERM-ignoring probe.
+ */
+export declare function probeRuntimeVersion(command: string, timeoutMs: number): Promise<VersionProbeResult>;
+export {};

package/dist/adapters/index.d.ts

@@ -1,6 +1,6 @@
 export type { RuntimeAdapter, RuntimeAdapterDescriptor, RuntimeAdapterPrepareInput, RuntimeAdapterPrepareResult, RuntimeAdapterRejectedOperation, RuntimeAdapterPreparedOperation, PreparedRuntimeOperation, RuntimeOperationManifest, RuntimeOperationStartInput, RuntimeCapabilities, RuntimeDetectResult, } from '../types';
 export type { RuntimeEnvironmentRequirements } from '../daemon/environment';
-export { RuntimeDisposalFailure, RuntimeExecutionFailure } from '../runtime-failure';
+export { RuntimeDisposalFailure, RuntimeExecutionFailure, RuntimeStartupDisposalFailure } from '../runtime-failure';
 export type { RuntimeDisposalFailureInput, RuntimeDisposalStage, RuntimeExecutionFailureInput, RuntimeFailureCategory, RuntimeFailurePhase, RuntimeRetryDisposition, } from '../runtime-failure';
 export { PiAdapter } from './pi/pi-adapter';
 export type { PiAdapterOptions, PiByokLauncherConfig } from './pi/pi-adapter';