@byok-sdk/client 0.3.0 → 0.4.1

package/dist/runtime-failure.d.ts

@@ -0,0 +1,64 @@
+/** Closed lifecycle phases for failures after an offer has been admitted. */
+export type RuntimeFailurePhase = 'start' | 'run';
+/** Closed semantic axis. Retryability is explicit and is never inferred from this field. */
+export type RuntimeFailureCategory = 'semantic' | 'infrastructure' | 'authority';
+/** The adapter's explicit retry judgment consumed by TaskRunner. */
+export type RuntimeRetryDisposition = 'retryable' | 'non-retryable';
+/** Disposal is deliberately separate from start/run retryability authority. */
+export type RuntimeDisposalStage = 'signal' | 'quiescence' | 'cleanup';
+export interface RuntimeDisposalFailureInput {
+    stage: RuntimeDisposalStage;
+    /** Audit-safe operational reason. It must not contain task instructions or provider credentials. */
+    reason: string;
+}
+export interface RuntimeExecutionFailureInput {
+    phase: RuntimeFailurePhase;
+    category: RuntimeFailureCategory;
+    retry: RuntimeRetryDisposition;
+    /** Stable operator-facing reason. Provider diagnostics may be included, but are never parsed by TaskRunner. */
+    reason: string;
+}
+/**
+ * Expected failure of an owned runtime-resource disposal barrier. This never
+ * carries task retryability: semantic terminal authority may already have
+ * been published when disposal begins.
+ */
+export declare class RuntimeDisposalFailure extends Error {
+    readonly stage: RuntimeDisposalStage;
+    constructor(input: RuntimeDisposalFailureInput, options?: ErrorOptions);
+}
+export declare function isRuntimeDisposalFailure(value: unknown): value is RuntimeDisposalFailure;
+/**
+ * The only expected post-admission failure value accepted from a runtime
+ * adapter. Diagnostic AgentEvents remain observability; this value alone is
+ * terminal control authority.
+ */
+export declare class RuntimeExecutionFailure extends Error {
+    readonly phase: RuntimeFailurePhase;
+    readonly category: RuntimeFailureCategory;
+    readonly retry: RuntimeRetryDisposition;
+    constructor(input: RuntimeExecutionFailureInput, options?: ErrorOptions);
+}
+export declare function isRuntimeExecutionFailure(value: unknown): value is RuntimeExecutionFailure;
+export interface RuntimeFailureProjection {
+    reason: string;
+    retryable: boolean;
+}
+/**
+ * Exhaustive wire projection for a valid typed failure. A failure from the
+ * wrong phase is an invalid adapter state and must be handled as an untyped
+ * contract violation by the caller.
+ */
+export declare function projectRuntimeExecutionFailure(failure: RuntimeExecutionFailure): RuntimeFailureProjection;
+export declare const RUNTIME_ADAPTER_CONTRACT_VIOLATION_REASON: Readonly<{
+    start: string;
+    run: string;
+}>;
+/**
+ * Validate an adapter boundary. Unknown values and typed failures reported
+ * for the wrong phase fail closed; their source value is returned only as a
+ * local diagnostic cause and never influences wire semantics.
+ */
+export declare function projectRuntimeBoundaryFailure(value: unknown, expectedPhase: RuntimeFailurePhase): RuntimeFailureProjection & {
+    contractViolation: boolean;
+};

package/dist/types.d.ts

@@ -17,14 +17,14 @@ export interface RuntimeDetectResult {
 }
 /** What a runtime adapter can do, advertised so the daemon can pick/validate adapters. */
 export interface RuntimeCapabilities {
-    steer: boolean;
-    resume: boolean;
+    readonly steer: boolean;
+    readonly resume: boolean;
     /**
      * Whether this adapter can project task-scoped, locally configured MCP
      * servers into the runtime without accepting executable definitions from
      * the remote task. Omission is fail-closed and means unsupported.
      */
-    mcpToolsets?: boolean;
+    readonly mcpToolsets?: boolean;
     /**
      * Whether this adapter can genuinely pause a running session on
      * `needs_approval` and resume it from an out-of-band decision — i.e.
@@ -38,9 +38,9 @@ export interface RuntimeCapabilities {
      * declare it fails to compile rather than silently defaulting to a claim
      * it cannot back.
      */
-    approvalInteractive: boolean;
+    readonly approvalInteractive: boolean;
     /** Subset of {@link PermissionPolicy}'s `mode` values this adapter can express without widening. */
-    permissionModes: string[];
+    readonly permissionModes: readonly string[];
 }
 /** One local stdio MCP server definition. Remote task payloads can never supply this shape. */
 export interface McpStdioServerConfig {
@@ -53,8 +53,8 @@ export interface McpToolsetConfig {
 }
 /**
  * M4 Phase 3: the out-of-band approval channel `TaskRunner` (`daemon/
- * task-runner.ts`) hands to an adapter's `start()` via `TaskContext
- * .approvalChannel`, for a runtime whose approval mechanism genuinely needs
+ * task-runner.ts`) hands to a prepared operation's `start()` via
+ * `RuntimeOperationStartInput.approvalChannel`, for a runtime whose approval mechanism genuinely needs
  * to reach back into the daemon from OUTSIDE the adapter's own process — the
  * claude adapter's concrete case: `claude`'s `--permission-prompt-tool`
  * resolves a pending permission entirely inside a SEPARATE MCP-server child
@@ -85,30 +85,6 @@ export interface ApprovalChannel {
     /** Resolve the single currently-pending out-of-band approval for this task. Rejects if none is pending right now. */
     resolve(approved: boolean, reason?: string): Promise<void>;
 }
-/**
- * Per-task execution context handed to {@link RuntimeAdapter.start}. `policy`
- * is the already fail-closed-checked *effective* policy (offer policy merged
- * against the daemon's configured ceiling) — the adapter must obey this, not
- * whatever the raw task offer's own `policy` field said.
- */
-export interface TaskContext {
-    workspaceDir: string;
-    policy: PermissionPolicy;
-    env: NodeJS.ProcessEnv;
-    /**
-     * MCP servers resolved from this device's local registry for this task.
-     * The wire carries only logical toolset ids; command/args never originate
-     * from the SaaS task and are never copied into the task instruction.
-     */
-    mcpServers?: Readonly<Record<string, McpStdioServerConfig>>;
-    /** Prepared local checkpoint repository metadata; absent for legacy plain workspaces. */
-    gitWorkspace?: {
-        workspaceId: string;
-        baseline?: string;
-    };
-    /** M4 Phase 3 — see {@link ApprovalChannel}. Optional/adapter-agnostic: unset for every adapter that never requests an out-of-band approval. */
-    approvalChannel?: ApprovalChannel;
-}
 /**
  * A running (or resumable) unit of work on a runtime. One `Session` maps to
  * one underlying runtime process/session for the lifetime of a task.
@@ -124,7 +100,12 @@ export interface Session {
     followUp(task: TaskOfferPayload): Promise<void>;
     /** Best-effort abort of the current turn (used for `task.cancel`). */
     interrupt(): Promise<void>;
-    /** Tear down the underlying runtime process/session. Idempotent. */
+    /**
+     * Bounded, idempotent disposal receipt. Resolution proves every
+     * adapter-owned process and task-scoped resource is quiescent. Expected
+     * failure rejects with `RuntimeDisposalFailure` and never changes task
+     * semantics.
+     */
     close(): Promise<void>;
     /**
      * Resolve a session paused on `needs_approval` (protocol §5). The
@@ -142,58 +123,104 @@ export interface Session {
     resolveApproval(approved: boolean, reason?: string): Promise<void>;
 }
 /**
- * Uniform seam every concrete runtime (pi now; claude/codex in M2) implements.
+ * Immutable runtime facts shared by discovery and one prepared operation.
  *
- * Credential-isolation rule: an adapter spawns only the runtime's official
- * binary. It never reads, proxies, or forwards that runtime's own credential
- * storage (OAuth tokens, API keys on disk, `~/.claude`, `~/.codex`, `~/.pi`
- * auth state, etc). Presence checks are limited to environment variable
- * *names* (see {@link RuntimeDetectResult.authPresent}).
- *
- * M5: separately, {@link RuntimeAdapter.environmentRequirements} below
- * declares which environment variable NAMES (never values inspected here
- * either) this adapter's runtime needs forwarded into its own spawned
- * process — see that method's own doc comment and `daemon/environment.ts`.
+ * The SDK snapshots this value before each offer and never consults adapter
+ * capability authority again during admission, claim, environment projection,
+ * or start. Credential declarations are names only, never values.
+ */
+export interface RuntimeAdapterDescriptor {
+    readonly id: string;
+    readonly capabilities: RuntimeCapabilities;
+    readonly environmentRequirements: RuntimeEnvironmentRequirements;
+    /** Explicit opt-in to authoritative `task.offer.dispatchSelection` semantics. */
+    readonly supportsDispatchSelection: boolean;
+}
+/** The pure input to one adapter admission decision. It contains no credential values or workspace resources. */
+export interface RuntimeAdapterPrepareInput {
+    offer: TaskOfferPayload;
+    policy: PermissionPolicy;
+    descriptor: RuntimeAdapterDescriptor;
+    requiredToolsetIds: readonly string[];
+    /** Locally resolved MCP authority; available for pure admission validation only. */
+    mcpServers?: Readonly<Record<string, McpStdioServerConfig>>;
+}
+/** A permanent or currently-unavailable pre-claim admission rejection. */
+export interface RuntimeAdapterRejectedOperation {
+    kind: 'reject';
+    reason: string;
+    retryable: boolean;
+}
+/** The side-effect-free adapter decision made before TaskRunner claims an offer. */
+export interface RuntimeAdapterPreparedOperation {
+    kind: 'prepared';
+    operation: PreparedRuntimeOperation;
+}
+export type RuntimeAdapterPrepareResult = RuntimeAdapterRejectedOperation | RuntimeAdapterPreparedOperation;
+/**
+ * Credential-free immutable identity for one admitted runtime operation.
+ * It can be emitted, compared, and passed to a prepared operation, but never
+ * serializes environment values or credential material.
+ */
+export interface RuntimeOperationManifest {
+    readonly taskId: string;
+    /** Selected runtime id; lane/provider/model, when present, live only in `dispatchSelection`. */
+    readonly runtimeId: string;
+    readonly descriptor: RuntimeAdapterDescriptor;
+    readonly policy: PermissionPolicy;
+    readonly requiredToolsetIds: readonly string[];
+    /** The credential-free runtime/lane/provider/model authority for this operation. */
+    readonly dispatchSelection?: TaskOfferPayload['dispatchSelection'];
+    readonly sessionRef?: string;
+    readonly workspace: {
+        readonly workspaceDir: string;
+        readonly workspaceId?: string;
+        readonly baseline?: string;
+    };
+    /** Names are audit-safe; credential values intentionally never enter the manifest. */
+    readonly forwardedEnvironmentNames: readonly string[];
+}
+/** Runtime resources only available after TaskRunner has sealed the manifest and claimed the task. */
+export interface RuntimeOperationStartInput {
+    readonly manifest: RuntimeOperationManifest;
+    readonly instruction: string;
+    readonly env: NodeJS.ProcessEnv;
+    /** Local MCP authority resolved from logical wire ids. */
+    readonly mcpServers?: Readonly<Record<string, McpStdioServerConfig>>;
+    /** Optional, adapter-agnostic out-of-band approval channel. */
+    readonly approvalChannel?: ApprovalChannel;
+}
+/** A pinned provider/runtime decision. `start()` receives resources only, never a raw offer. */
+export interface PreparedRuntimeOperation {
+    start(input: RuntimeOperationStartInput): Promise<Session>;
+}
+/**
+ * Uniform public adapter seam. `prepare()` is required and must not spawn,
+ * create temp files, mutate a workspace, allocate a session id, or read a
+ * credential value. There is intentionally no direct `RuntimeAdapter.start`.
  */
 export interface RuntimeAdapter {
-    id: string;
-    /**
-     * Explicit opt-in to the authoritative `task.offer.dispatchSelection`
-     * contract. A custom adapter using a built-in runtime id must set this only
-     * when it validates and pins the exact lane/provider/model semantics; the
-     * daemon will otherwise withhold the connection-level capability so a
-     * server rejects the offer before sending it.
-     */
-    readonly supportsDispatchSelection?: true;
+    readonly descriptor: RuntimeAdapterDescriptor;
     detect(): Promise<RuntimeDetectResult>;
-    capabilities(): RuntimeCapabilities;
-    start(task: TaskOfferPayload, ctx: TaskContext): Promise<Session>;
-    /**
-     * M5: declares which environment variable names (exact, or `*`-suffixed
-     * prefix) this runtime's own CLI needs beyond the always-included
-     * platform baseline (`daemon/environment.ts`'s `buildRuntimeEnv`) —
-     * `task-runner.ts` builds each task's `TaskContext.env` from this instead
-     * of ever handing a spawned agent the daemon's raw `process.env` again.
-     * Optional and fail-closed by omission: an adapter that doesn't implement
-     * this gets the platform baseline ONLY, never an implicit "everything."
-     */
-    environmentRequirements?(): RuntimeEnvironmentRequirements;
+    prepare(input: RuntimeAdapterPrepareInput): Promise<RuntimeAdapterPrepareResult>;
 }
+/** Copy then deeply freeze descriptor authority so callers cannot retain a mutable source reference. */
+export declare function freezeRuntimeAdapterDescriptor(descriptor: RuntimeAdapterDescriptor): RuntimeAdapterDescriptor;
+/** Copy then freeze the complete safe operation authority just before claim. */
+export declare function sealRuntimeOperationManifest(manifest: RuntimeOperationManifest): RuntimeOperationManifest;
 /**
- * Thrown by `RuntimeAdapter.start` when the task can never succeed on this
- * adapter as offered — an unsupported `PermissionPolicy` (fail-closed) or an
- * instruction shape the adapter can't handle (e.g. a blob-ref in M0) — as
- * opposed to a transient/environmental failure (spawn error, missing
- * credentials) that might succeed on a later retry. The daemon uses this
- * distinction to set `task.fail`'s `retryable` flag correctly instead of
- * treating every `start()` failure the same way.
+ * Thrown by a prepared operation's `start()` when an already admitted task
+ * cannot continue because an internal invariant was violated. Permanent
+ * offer semantics are rejected by `RuntimeAdapter.prepare()` before claim;
+ * this class remains for post-claim operational/session failures whose
+ * retryability is already part of the frozen task behavior.
  */
 export declare class PolicyUnsupportedError extends Error {
     constructor(message: string);
 }
 /**
  * Thrown by {@link Session.steer} on an adapter whose runtime has no
- * mid-turn steering channel at all (`capabilities().steer === false`) — a
+ * mid-turn steering channel at all (`descriptor.capabilities.steer === false`) — a
  * permanent property of the runtime, never a transient failure. Typed
  * rather than a bare `Error` so the daemon can classify an inbound
  * `task.steer` for such a runtime as non-retryable (record + ack, cursor
@@ -201,7 +228,7 @@ export declare class PolicyUnsupportedError extends Error {
  * on message strings.
  */
 export declare class SteerUnsupportedError extends Error {
-    /** The `RuntimeAdapter.id` that cannot steer (e.g. `claude`, `codex`). */
+    /** The `RuntimeAdapter.descriptor.id` that cannot steer (e.g. `claude`, `codex`). */
     readonly runtimeId: string;
     constructor(runtimeId: string, message: string);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byok-sdk/client",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "BYOK SDK client daemon: runs on the end user's machine, pairs with a SaaS server, and drives a local coding-agent runtime",
   "type": "module",
   "license": "MIT",
@@ -14,7 +14,7 @@
   },
   "homepage": "https://github.com/Ancienttwo/byok-sdk#readme",
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=22.22.0"
   },
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -43,17 +43,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.1",
-    "ws": "^8.21.1",
-    "@byok-sdk/core": "0.3.0",
-    "@byok-sdk/protocol": "0.3.0"
-  },
-  "devDependencies": {
-    "@types/ws": "^8.18.1",
-    "@hono/node-server": "^2.0.10",
-    "@byok-sdk/server": "0.3.0"
-  },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json && node scripts/check-adapters-entry.mjs",
     "dev": "tsup --watch",
@@ -64,5 +53,16 @@
     "audit:adapter-task-smoke": "node scripts/adapter-task-smoke.mjs",
     "audit:credentials": "node scripts/linux-credential-audit.mjs",
     "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@byok-sdk/core": "0.4.0",
+    "@byok-sdk/protocol": "0.4.0",
+    "ws": "^8.21.1"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "@byok-sdk/server": "0.4.0",
+    "@hono/node-server": "^2.0.10"
   }
-}
+}