@byok-sdk/client 0.1.1 → 0.3.0

package/README.md

@@ -5,16 +5,56 @@ 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, Claude Code and Codex are user-installed runtimes. Install and authenticate
-the runtime CLI you choose; the SDK never packages its executable or
-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';
 ```
 
-MIT licensed. Node.js 20 or newer; SQLite-backed journaling requires a runtime
-with `node:sqlite` support.
+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.
+
+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

@@ -3,6 +3,8 @@ import { type RuntimeAdapter, type RuntimeCapabilities, type RuntimeDetectResult
 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,6 +114,7 @@ export interface ClaudeAdapterOptions {
  */
 export declare class ClaudeAdapter implements RuntimeAdapter {
     private readonly options;
+    readonly supportsDispatchSelection = true;
     readonly id = "claude";
     constructor(options?: ClaudeAdapterOptions);
     detect(): Promise<RuntimeDetectResult>;

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

@@ -6,7 +6,7 @@ export interface ResolvedBin {
  * Resolve the `claude` (Claude Code) CLI executable.
  *
  * Unlike pi (`../pi/resolve-bin.ts`), this package does NOT bundle a
- * matched `claude` build as an optionalDependency. Claude Code is the end
+ * matched `claude` build as a dependency. Claude Code is the end
  * user's own globally-installed, individually-authenticated CLI (`claude
  * auth login`, tied to their Anthropic/claude.ai account) — there is
  * nothing useful to vendor: a bundled copy could never carry the user's own
@@ -22,6 +22,6 @@ export interface ResolvedBin {
  * `fake-claude.mjs` fixture ahead of a real claude install, exactly as pi's
  * own override does), otherwise this falls back to the literal command name
  * `claude`, resolved via the child process's own PATH lookup — there is no
- * optionalDependency tier in between.
+ * package-resolution tier in between.
  */
 export declare function resolveClaudeBin(): ResolvedBin;

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

@@ -52,6 +52,7 @@ export interface CodexAdapterOptions {
  */
 export declare class CodexAdapter implements RuntimeAdapter {
     private readonly options;
+    readonly supportsDispatchSelection = true;
     readonly id = "codex";
     constructor(options?: CodexAdapterOptions);
     detect(): Promise<RuntimeDetectResult>;
@@ -66,9 +67,10 @@ export declare class CodexAdapter implements RuntimeAdapter {
      * Two independently-verified channel gotchas apply here, the "pi lesson"
      * yet again:
      *   - `codex login status`'s human-readable "Logged in using ChatGPT"
-     *     message prints on STDERR, not stdout (the opposite-channel
-     *     counterpart of pi's own `--version`-goes-to-stderr surprise) — both
-     *     streams are checked here for exactly that reason.
+     *     message prints on STDERR, not stdout — both streams are checked
+     *     here for exactly that reason. pi's `--version` is the same class of
+     *     hazard from the other direction: its channel has moved between pi
+     *     releases (see ../pi/pi-adapter.ts), so neither stream is assumed.
      *   - The NOT-logged-in message/exit-code shape was deliberately never
      *     empirically tested: this machine has a real, live ChatGPT login, and
      *     running `codex logout` to observe the negative case would have

package/dist/adapters/index.d.ts

@@ -1,7 +1,7 @@
 export type { RuntimeAdapter, RuntimeCapabilities, RuntimeDetectResult, } from '../types';
 export type { RuntimeEnvironmentRequirements } from '../daemon/environment';
 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';