@byok-sdk/client 0.10.2 → 0.12.0

package/README.md

@@ -14,6 +14,31 @@ Provider
 credentials are not read by the dispatch plane; `@byok-sdk/keys` is a separate
 install and keeps a zero dependency edge to this package.
 
+Single-file Bun/SEA products must explicitly re-enter SDK-reserved helpers
+before their own CLI parser. The SDK owns the reserved subcommand and helper
+implementation; the product does not resolve `dist/bin` paths:
+
+```ts
+import { createDaemon, runSdkReservedHelperCommand } from '@byok-sdk/client';
+
+if (await runSdkReservedHelperCommand()) process.exit(0);
+
+const daemon = createDaemon({
+  // ...normal device, Agent-home, and egress configuration
+  sdkHelperHost: { mode: 'self-executable' },
+});
+```
+
+Normal Node/Bun source hosts omit `sdkHelperHost` and continue to use the
+package's installed helper scripts. A required-message offer performs an exact
+stdio MCP initialize/tools-list handshake before adapter preparation; an
+unwired or unstartable single-file helper is declined before runtime execution.
+For Codex 0.149+, the adapter additionally proves the native per-MCP-tool
+approval contract before claim, then approves only the SDK-reserved
+`byokagentmessage/send_agent_message` tool. The global Codex
+`approval_policy=never` remains pinned and every other MCP/tool retains the
+normal non-interactive fail-closed posture.
+
 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
@@ -64,9 +89,31 @@ createDaemon({
 ```
 
 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.
+secrets behind the local MCP process's own credential broker.
+
+A projected toolset must also be *callable*, and neither runtime grants an MCP
+tool implicitly: Claude auto-denies an ungranted `mcp__<server>__<tool>` call
+under `--permission-mode default` and under `acceptEdits`, and Codex refuses
+every MCP tool call under its pinned `approval_policy=never`. So before an
+adapter is asked to admit a toolset offer, the daemon starts each projected
+server and reads that server's own `tools/list` answer. Those observed names —
+never a configured value, never a wildcard — are what each adapter grants:
+
+- Claude: `--allowedTools mcp__<server>__<tool>,…` under `readonly` and
+  `auto`, alongside the unchanged `--tools` (so `readonly` with
+  `allowTools: []` still runs with every built-in disabled). `confirm` and
+  `plan` never pre-grant: `confirm`'s approval channel must see each call, and
+  `plan` promises not to execute one.
+- Codex: `mcp_servers.<server>.enabled_tools` plus
+  `mcp_servers.<server>.tools.<tool>.approval_mode="approve"` for exactly
+  those tools. Global `approval_policy=never` and the mode's `sandbox_mode`
+  stay untouched, and Codex older than 0.149 is rejected before spawn.
+
+A projected server that cannot start, or that lists no tools, is declined
+pre-claim and retryably, rather than claimed and handed a toolset the model can
+list but never call. A server that answers with a tool name that cannot be
+expressed as a runtime grant is declined permanently (`retryable: false`), with
+the server and the offending tool named in the decline.
 
 The daemon derives one sorted `configuredToolsets` snapshot from this
 validated registry. Only those logical IDs are advertised in `conn.hello`
@@ -128,9 +175,21 @@ strict Agent execution has one workspace authority and never falls back to a
 task-scoped Git workspace.
 
 Successful startup with this configuration advertises `agent-home-contract`. Agent offers are distinct
-from legacy task offers and fail closed when identity, profile revision,
-session/runtime/cwd evidence, or the one-writer lease does not match. Agent
-files other than the SDK-reserved `.byok` namespace are opaque; there is no
+from legacy task offers and fail closed when identity, profile revision, or
+session/runtime/cwd evidence does not match. Within one daemon process,
+execution leases are scoped to `(agentId, sessionRef)`: different sessions of
+one Agent may run concurrently in the same canonical home, while the same
+session remains serialized. Fresh
+tasks bind their task-scoped admission lease to the runtime-created session
+before the SDK exposes that session. Shared `.byok` metadata mutations use a
+short per-home gate. Agent-memory hosted projection serializes the complete
+close-time outbox transaction per home because its durable outbox is one CAS
+authority; the publish wait remains timeout-bounded and does not serialize the
+sessions' runtime execution. The process-owned home activity marker remains
+held until the final active session exits so relocation stays fail-closed. A
+second daemon process remains excluded by that marker; cross-process session
+multiplexing is not provided. Agent files
+other than the SDK-reserved `.byok` namespace are opaque; there is no
 required `artifacts/` directory and the client does not parse or index their
 contents.
 
@@ -261,4 +320,25 @@ 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.
 
+## Local TeamWorkspace and tmux communication pane
+
+`byok-agent team` provides one local-only broadcast channel for Pi, Claude,
+and Codex harnesses. The daemon owns durable ordered messages, member receipts,
+quotas, and short-lived member leases under `<storeDir>/team-workspaces/v1`.
+`team join` prints the exact `byokagentteam` stdio MCP configuration for a
+member; model tool inputs never contain workspace or sender identity.
+
+```bash
+byok-agent team create dev --members pi,claude,codex --config /absolute/agent.json
+byok-agent team join dev --member pi --config /absolute/agent.json
+byok-agent team open dev --tmux-bin /opt/homebrew/bin/tmux --config /absolute/agent.json
+```
+
+The tmux view has one explicit native dependency: tmux must be installed and
+its absolute executable path supplied with `--tmux-bin`. It is intentionally
+not an npm dependency and is not required to run the daemon, MCP channel, or
+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.
+
 MIT licensed. Node.js 22.22.0 or newer.

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

@@ -2,8 +2,9 @@ import { type RuntimeAdapter, type RuntimeDetectResult, type RuntimeAdapterPrepa
 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";
+import { APPROVAL_MCP_SERVER_NAME } from '../../sdk-reserved-mcp';
+/** The MCP server NAME this adapter registers `byok-approval-mcp` under in the generated `--mcp-config` — combined with {@link APPROVAL_TOOL_NAME} (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. Defined in `sdk-reserved-mcp.ts` beside the other SDK-owned server names, and re-exported from here, its original home, so the host-config rejection and the toolset-grant rule read one list. */
+export { APPROVAL_MCP_SERVER_NAME };
 export interface ClaudeAdapterOptions {
     /** Override bin resolution — tests substitute the fake-claude fixture script. */
     resolveBin?: () => ResolvedBin;

package/dist/adapters/claude/permission-mapping.d.ts

@@ -1,4 +1,5 @@
 import type { PermissionPolicy } from '@byok-sdk/protocol';
+import type { McpToolsetGrant } from '../mcp-tool-grants';
 export interface ClaudePermissionMapping {
     ok: boolean;
     /** CLI args to append to `claude -p ...`. Only meaningful when `ok` is true. */
@@ -131,6 +132,52 @@ export interface ClaudePermissionMapping {
  *   "default set minus these" this mapper can construct. Refusing is the
  *   fail-closed choice over guessing a set that might not match reality.
  *
+ * ## Projected MCP toolset tools: `--allowedTools`, and ONLY for them
+ *
+ * The two flags above govern claude's BUILT-IN tools. A projected host
+ * toolset arrives by a third path entirely — `--mcp-config` (see
+ * `claude-adapter.ts`) — and empirically it is granted by neither: on the
+ * installed 2.1.251 binary, a `mcp__<server>__<tool>` call is auto-denied
+ * (`system:permission_denied`, `permission_denials` populated) under
+ * `--permission-mode default` AND under `--permission-mode acceptEdits`,
+ * whether or not `--tools` is present. `acceptEdits`' documented breadth
+ * (which really does cover Write and Bash — see `auto` above) stops at
+ * claude's own built-ins; MCP tools are never implicitly permitted.
+ *
+ * So a projected toolset is only actually callable if its tools appear in
+ * `--allowedTools`. Live-verified against 2.1.251 against a one-tool stdio
+ * echo server: with `--permission-mode default --tools "" --mcp-config …
+ * --strict-mcp-config`, `tools/list` reached the server and `tools/call`
+ * never did; appending `--allowedTools mcp__saleskoprobe__echo` (nothing
+ * else changed) produced `permission_denials: []`, a real `tools/call` on
+ * the server, and the tool's own result — while `system/init` still
+ * reported `tools: ["mcp__saleskoprobe__echo"]`, i.e. `--tools ""` kept
+ * every built-in disabled. This is the one use of `--allowedTools` this
+ * mapper makes, and it is a PERMISSION pre-grant (what the flag genuinely
+ * is), never a capability restriction (what the findings above prove it is
+ * not): the capability surface is still fixed by `--tools` alone.
+ *
+ * Which modes receive the grant, and why the others deliberately do not:
+ *
+ * - `readonly` and `auto`: granted. Both auto-deny MCP calls without it
+ *   (live-confirmed above for each), so withholding it would offer a task
+ *   a toolset it can list and never call. Nothing is widened: the granted
+ *   identifiers are exactly the tools the daemon OBSERVED on exactly the
+ *   servers this task projected (`daemon/mcp-tools-probe.ts`), an unobserved
+ *   name is never granted, and no server-scoped `mcp__<server>` wildcard is
+ *   ever emitted (that form was never verified, and it would silently grant
+ *   tools a server adds later).
+ * - `confirm`: NOT granted, deliberately. Confirm's whole point is that a
+ *   human answers each call through `--permission-prompt-tool`; a pre-grant
+ *   would resolve those calls before the channel ever sees them, silently
+ *   removing the decision the caller asked for.
+ * - `plan`: NOT granted, deliberately. Plan mode's contract is that the
+ *   mutating call never actually runs. This SDK cannot know whether an
+ *   opaque host toolset tool mutates anything, so pre-granting one would
+ *   turn plan into an executing mode for exactly the tools it knows least
+ *   about. A plan-mode task that needs its toolset callable belongs in
+ *   `readonly`.
+ *
  * `network: false` fails closed for the same reason as pi: no verified
  * network sandbox exists for claude's Bash tool either (`claude --help`
  * exposes no network/sandbox flag at all) — this was not independently
@@ -139,4 +186,4 @@ export interface ClaudePermissionMapping {
  * task didn't run), but is the same conservative, precedent-consistent
  * default pi already applies for an unverifiable constraint.
  */
-export declare function mapPermissionPolicyToClaudeArgs(policy: PermissionPolicy): ClaudePermissionMapping;
+export declare function mapPermissionPolicyToClaudeArgs(policy: PermissionPolicy, toolsetGrants?: readonly McpToolsetGrant[]): ClaudePermissionMapping;

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

@@ -1,7 +1,8 @@
+import { type SdkHelperHostConfig } from '../../sdk-reserved-helper-host';
 export interface ResolvedApprovalMcpBin {
     command: string;
     args: string[];
-    source: 'env' | 'dist';
+    source: 'env' | 'dist' | 'host';
 }
 /**
  * Resolve `byok-approval-mcp` — the small stdio MCP server
@@ -42,4 +43,4 @@ export interface ResolvedApprovalMcpBin {
  * (see `claude-adapter.test.ts`), exactly like `BYOK_CLAUDE_BIN` already
  * does for the real `claude` binary.
  */
-export declare function resolveApprovalMcpBin(): ResolvedApprovalMcpBin;
+export declare function resolveApprovalMcpBin(host?: SdkHelperHostConfig): ResolvedApprovalMcpBin;

package/dist/adapters/codex/permission-mapping.d.ts

@@ -103,5 +103,21 @@ export interface CodexPermissionMapping {
  *   `~/.codex/config.toml` default is more permissive than anything this
  *   adapter should ever grant implicitly. Every invocation pins both keys
  *   explicitly so behavior never depends on the end user's own codex config.
+ *   Codex 0.149's per-MCP-tool approval setting is a separate, narrower
+ *   control: `codex-adapter.ts` uses it for the SDK-reserved
+ *   `byokagentmessage/send_agent_message` terminal protocol tool, and for the
+ *   tools of the MCP servers a task's own `requiredToolsets` projected — each
+ *   with an exact `enabled_tools` allowlist naming those tools and nothing
+ *   else. Global approval stays `never` and `sandbox_mode` is untouched, so
+ *   shell/file authority remains exactly what the mode above selected.
+ *   Without that grant a projected toolset is dead weight: `approval_policy=
+ *   never` refuses every MCP tool call outright ("MCP tool call requires
+ *   approval, but approval policy is never"), under `workspace-write` and
+ *   `read-only` alike, so the model can list a toolset's tools and never call
+ *   one. The granted names are only ever the ones the daemon OBSERVED via
+ *   `tools/list` on that exact server (`daemon/mcp-tools-probe.ts`) — never a
+ *   configured value, never a wildcard, and never
+ *   `default_tools_approval_mode`, which codex reads back happily but which
+ *   was empirically ineffective under `approval_policy=never` on 0.149.0.
  */
 export declare function mapPermissionPolicyToCodexArgs(policy: PermissionPolicy): CodexPermissionMapping;