@byok-sdk/client 0.2.0 → 0.4.0

package/README.md

@@ -5,16 +5,69 @@ WebSocket or long poll, dispatches to local Claude Code, Codex, or pi adapters,
 and exposes authenticated local diagnostics/control commands.
 
 The package installs `byok-agent` and `byok-approval-mcp` binaries. Provider
-credentials are not read by the dispatch plane; `@byok-sdk/keys` is separate.
+credentials are not read by the dispatch plane; `@byok-sdk/keys` is a separate
+install and keeps a zero dependency edge to this package.
 
-Pi is a required exact npm dependency and runs as an external Node subprocess;
-authenticate it with your own provider credentials. Claude Code and Codex
-remain user-installed runtimes. The SDK never reads or packages provider
-credentials. Hosts that only need runtime detection/composition can import the
+Pi is a required exact npm dependency and runs as an external Node subprocess.
+For an authoritative BYOK `dispatchSelection`, configure `piByokLauncher` with
+the separately installed `byok-pi-provider-launcher`, the local non-secret
+profile database path, and a stable Pi session directory. The client passes
+only those paths plus provider/model ids; the launcher alone reads the OS
+credential when required and spawns Pi. Both custody paths must be absolute;
+missing launcher configuration fails closed.
+
+Claude Code and Codex remain user-installed runtimes and use their own login
+state. Hosts that only need runtime detection/composition can import the
 transport-free adapter surface:
 
 ```ts
 import { PiAdapter, ClaudeAdapter, CodexAdapter } from '@byok-sdk/client/adapters';
 ```
 
+Version 0.4.0 intentionally breaks custom adapters: they expose a frozen
+descriptor and side-effect-free `prepare()` that returns one prepared
+operation; the old direct `start()` surface is removed. A published
+`Session.close()` is a bounded quiescent-disposal receipt. It resolves only
+after the adapter-owned process tree and task resources are gone, or rejects
+with `RuntimeDisposalFailure`. The daemon keeps active/Git ownership after a
+rejection and never rewrites the task's already-established terminal result.
+
+Claude tasks can select operator-owned local stdio MCP servers by logical id.
+The toolset selector carries no MCP command or connector credential:
+
+```ts
+import { createDaemon } from '@byok-sdk/client';
+
+createDaemon({
+  // ...normal device and transport configuration
+  mcpToolsets: {
+    'salesko.prospecting': {
+      mcpServers: {
+        'salesko-connectors': {
+          command: '/opt/salesko/bin/connector-mcp',
+          args: ['--profile', 'default'],
+        },
+      },
+    },
+  },
+});
+```
+
+The map accepts only `command` and `args`; put OAuth tokens, cookies, and other
+secrets behind the local MCP process's own credential broker. Toolset offers
+for Pi or Codex are declined because those adapters do not yet expose a strict
+task-scoped MCP configuration boundary.
+
+The daemon derives one sorted `configuredToolsets` snapshot from this
+validated registry. Only those logical IDs are advertised in `conn.hello`
+and hosted presence; command, args, environment, headers, and credentials
+remain local.
+
+For a concrete private host composition, see the
+[`examples/salesko-connector-broker`](../../examples/salesko-connector-broker)
+reference. It keeps `@byok-sdk/client` credential-blind while combining
+OS-backed refresh-token custody, a PKCE desktop Google OAuth flow, exact domain
+policy, a real read-only Gmail metadata adapter, and a closed metadata-only MCP
+result.
+
 MIT licensed. Node.js 22.19.0 or newer.

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

@@ -1,8 +1,9 @@
-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 ResolvedApprovalMcpBin } from './resolve-approval-mcp-bin';
 import { type SpawnFn } from './process-client';
+/** The MCP server NAME this adapter registers `byok-approval-mcp` under in the generated `--mcp-config` (arbitrary, local to this file) — combined with {@link APPROVAL_TOOL_NAME} (imported, single-sourced from `bin/approval-mcp-server.ts` so the two can never independently drift) to form the `mcp__<server>__<tool>` identifier `--permission-prompt-tool` expects. */
+export declare const APPROVAL_MCP_SERVER_NAME = "byokapproval";
 export interface ClaudeAdapterOptions {
     /** Override bin resolution — tests substitute the fake-claude fixture script. */
     resolveBin?: () => ResolvedBin;
@@ -112,25 +113,11 @@ export interface ClaudeAdapterOptions {
  */
 export declare class ClaudeAdapter implements RuntimeAdapter {
     private readonly options;
-    readonly id = "claude";
+    readonly descriptor: import("..").RuntimeAdapterDescriptor;
     constructor(options?: ClaudeAdapterOptions);
     detect(): Promise<RuntimeDetectResult>;
-    capabilities(): RuntimeCapabilities;
-    /**
-     * M5: deliberate product-boundary decision, not an oversight — byok's
-     * current ToS posture for claude is login-state-only (`claude auth
-     * login`'s own OAuth session — see `probeAuthPresent` below), so this
-     * adapter declares NO credential env vars at all; env-based API-key
-     * passthrough for claude is a separate, still-pending product decision.
-     * A product that genuinely needs it can opt in locally per-device via
-     * `DaemonConfig.runtimeEnvironment.claude.allow` (`create-daemon.ts`).
-     * `baseNames` is empty too: nothing in this adapter reads a
-     * claude-specific config-discovery variable (e.g. `CLAUDE_CONFIG_DIR`)
-     * today — if a future version of this adapter starts reading one, it
-     * belongs here, not left to rely on the platform baseline alone.
-     */
-    environmentRequirements(): RuntimeEnvironmentRequirements;
-    start(task: TaskOfferPayload, ctx: TaskContext): Promise<Session>;
+    prepare(input: RuntimeAdapterPrepareInput): Promise<RuntimeAdapterPrepareResult>;
+    private startPrepared;
     /**
      * `claude auth status --json` is claude's OWN non-secret login-state
      * signal (see the credential-isolation rule on `RuntimeAdapter` in

package/dist/adapters/claude/events.d.ts

@@ -1,4 +1,5 @@
 import type { AgentEvent } from '@byok-sdk/protocol';
+import { RuntimeExecutionFailure } from '../../runtime-failure';
 /**
  * A raw parsed line from `claude --output-format stream-json`. Shapes vary
  * a lot by `type` (and, for `system`, by `subtype`) — see the doc comments
@@ -38,6 +39,8 @@ export interface MapClaudeMessageOptions {
 }
 export interface MapClaudeMessageResult {
     events: AgentEvent[];
+    /** Present only when this frame is authoritative terminal failure evidence. */
+    terminalFailure?: RuntimeExecutionFailure;
     /**
      * Set when this exact frame (or, for `assistant`/`user` frames, one
      * content block inside it) was genuinely unrecognized — a frame/subtype/

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

@@ -52,6 +52,9 @@ export declare class ClaudeProcessClient {
     private readonly eventQueue;
     private closed;
     private exitError;
+    private readonly closedPromise;
+    private resolveClosed;
+    private disposalAttempt;
     private readonly stderrRing;
     private readonly unmappedFrameCounts;
     private sessionId;
@@ -81,6 +84,8 @@ export declare class ClaudeProcessClient {
     waitForInit(): Promise<string>;
     /** Every parsed stream-json line — `system/init` is consumed internally (see `waitForInit`) but is also forwarded here like any other frame, so routine-frame accounting in `ClaudeSession`'s mapper stays uniform. */
     get events(): AsyncIterable<ClaudeStreamMessage>;
+    /** Local transport diagnostic retained when the process closes; consumers classify it at the session boundary. */
+    get terminalError(): Error | undefined;
     /**
      * Record a claude stream-json frame/subtype/content-block label that
      * `ClaudeSession`'s event iterator (`../claude-adapter.ts`) decided has
@@ -92,8 +97,11 @@ export declare class ClaudeProcessClient {
      * post-mortem without separate log scraping.
      */
     recordUnmappedFrame(label: string): void;
-    /** Best-effort teardown. SIGTERM on POSIX; `taskkill /T /F` on Windows to also reap child processes claude itself spawned (e.g. Bash) — mirrors pi's cross-platform `kill()` exactly. Empirically confirmed on this (POSIX) machine: a running claude process exits cleanly within ~1s of SIGTERM (observed exit code 143 = 128+SIGTERM, i.e. claude catches and handles the signal itself rather than needing a harder kill). */
+    /** Immediate process-tree termination request. `dispose()` is the settlement receipt. */
     kill(): void;
+    waitClosed(): Promise<void>;
+    dispose(): Promise<void>;
+    private processTreeOptions;
     private onData;
     private onLine;
     private onStderr;

package/dist/adapters/codex/codex-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 './process-runner';
 export interface CodexAdapterOptions {
@@ -52,7 +51,7 @@ export interface CodexAdapterOptions {
  */
 export declare class CodexAdapter implements RuntimeAdapter {
     private readonly options;
-    readonly id = "codex";
+    readonly descriptor: import("..").RuntimeAdapterDescriptor;
     constructor(options?: CodexAdapterOptions);
     detect(): Promise<RuntimeDetectResult>;
     /**
@@ -82,17 +81,7 @@ export declare class CodexAdapter implements RuntimeAdapter {
      *     empirical pass on a logged-out machine, not asserted as verified.
      */
     private probeAuthPresent;
-    capabilities(): RuntimeCapabilities;
-    /**
-     * M5: same deliberate posture as the claude adapter (see its own doc
-     * comment) — codex authenticates via its own `codex login`-managed
-     * ChatGPT OAuth session (`probeAuthPresent` above), not an env var, so
-     * there is no credential env var this adapter needs forwarded; env-based
-     * API-key passthrough remains a separate, pending product decision. No
-     * `baseNames` either: nothing in this adapter reads a codex-specific
-     * config-discovery variable (e.g. `CODEX_HOME`) today.
-     */
-    environmentRequirements(): RuntimeEnvironmentRequirements;
-    start(task: TaskOfferPayload, ctx: TaskContext): Promise<Session>;
+    prepare(input: RuntimeAdapterPrepareInput): Promise<RuntimeAdapterPrepareResult>;
+    private startPrepared;
     private resolveBin;
 }

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

@@ -59,13 +59,14 @@ export declare class CodexProcessRunner {
     private exitSignal;
     private readonly closedPromise;
     private resolveClosed;
+    private disposalAttempt;
     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. */
     waitClosed(): Promise<void>;
     get isClosed(): boolean;
     /**
-     * Best-effort teardown. SIGTERM on POSIX: SIGINT was empirically confirmed
+     * Immediate tree termination request. SIGTERM on POSIX: SIGINT was empirically confirmed
      * to be silently ignored by `codex exec` (a real, direct test — a 60s
      * shell `sleep` ran to full, unaffected completion despite SIGINT sent at
      * t=4s) — a genuine, evidence-based correction to this task's own initial
@@ -78,6 +79,8 @@ export declare class CodexProcessRunner {
      * `../pi/rpc-client.ts`'s own cross-platform convention.
      */
     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. */
     buildExitError(context: string): Error;
     private onData;

package/dist/adapters/index.d.ts

@@ -1,7 +1,9 @@
-export type { RuntimeAdapter, RuntimeCapabilities, RuntimeDetectResult, } from '../types';
+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 type { RuntimeDisposalFailureInput, RuntimeDisposalStage, RuntimeExecutionFailureInput, RuntimeFailureCategory, RuntimeFailurePhase, RuntimeRetryDisposition, } from '../runtime-failure';
 export { PiAdapter } from './pi/pi-adapter';
-export type { PiAdapterOptions } from './pi/pi-adapter';
+export type { PiAdapterOptions, PiByokLauncherConfig } from './pi/pi-adapter';
 export { PI_PACKAGE_NAME } from './pi/resolve-bin';
 export { ClaudeAdapter } from './claude/claude-adapter';
 export type { ClaudeAdapterOptions } from './claude/claude-adapter';