@byok-sdk/client 0.13.0 → 0.14.0

package/README.md

@@ -354,4 +354,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/process-runner.d.ts

@@ -19,6 +19,17 @@ export interface CodexProcessOptions {
     spawnFn?: SpawnFn;
     /** Called once per parsed JSONL line, in arrival order. */
     onEvent: (evt: CodexRawEvent) => 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>;
+    };
 }
 /**
  * Spawns and streams ONE `codex exec` / `codex exec resume` invocation — i.e.
@@ -60,6 +71,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,7 +110,28 @@ 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 onData;
     private parseLine;