@byok-sdk/client 0.3.0 → 0.4.1

package/dist/daemon/environment.d.ts

@@ -2,7 +2,7 @@
  * M5: per-runtime environment allowlist for spawned agent child processes.
  *
  * Before this module existed, `task-runner.ts` built every task's
- * `TaskContext.env` as `process.env` verbatim — the daemon's OWN full
+ * `RuntimeOperationStartInput.env` as `process.env` verbatim — the daemon's OWN full
  * environment, unfiltered, handed to whichever runtime CLI (`pi`/`claude`/
  * `codex`) `pickAdapter` selected. Any credential-shaped variable sitting in
  * the daemon's own environment for a completely unrelated reason (an
@@ -20,10 +20,9 @@
  *    behave sanely in a non-interactive shell.
  * 2. Whatever ADDITIONAL names the *specific* runtime adapter about to be
  *    spawned declares it actually needs
- *    (`RuntimeAdapter.environmentRequirements()` — see `../types.ts`). An
- *    adapter that declares nothing at all (doesn't implement the optional
- *    method) gets the platform baseline ONLY — fail-closed by construction,
- *    not by an extra check here.
+ *    (`RuntimeAdapter.descriptor.environmentRequirements` — see
+ *    `../types.ts`). A descriptor that declares no names gets the platform
+ *    baseline only; descriptors are required and frozen before claim.
  * 3. A per-device, per-runtime operator override (`DaemonConfig
  *    .runtimeEnvironment` — see `create-daemon.ts`) — a local escape hatch
  *    for a product/operator that knows it needs one more variable forwarded
@@ -39,8 +38,8 @@
  */
 /**
  * What one runtime adapter declares it needs beyond the always-included
- * platform baseline. Returned from the optional
- * `RuntimeAdapter.environmentRequirements()` method (`../types.ts`).
+ * platform baseline. Declared in the required frozen
+ * `RuntimeAdapter.descriptor.environmentRequirements` (`../types.ts`).
  */
 export interface RuntimeEnvironmentRequirements {
     /**
@@ -69,8 +68,9 @@ export interface BuildRuntimeEnvOptions {
     ambient: NodeJS.ProcessEnv;
     /**
      * The selected runtime adapter's own declared requirements —
-     * `undefined` (no `environmentRequirements()` implementation on that
-     * adapter) means "platform baseline only," fail-closed.
+     * `undefined` means "platform baseline only" for this helper. The public
+     * RuntimeAdapter descriptor always supplies this object before TaskRunner
+     * invokes the helper.
      */
     requirements?: RuntimeEnvironmentRequirements;
     /**

package/dist/daemon/git-workspace.d.ts

@@ -2,6 +2,27 @@ export interface GitWorkspaceConfig {
     mode: 'local-checkpoints';
 }
 export type GitErrorCategory = 'git-unavailable' | 'git-timeout' | 'git-output-limit' | 'git-command-failed' | 'workspace-root-invalid' | 'workspace-root-conflict' | 'workspace-not-owned' | 'repository-root-mismatch' | 'repository-invalid' | 'lease-busy' | 'ledger-invalid';
+/**
+ * Runtime projection of {@link GitErrorCategory}: every union member, once,
+ * in union order — the single source of truth the CLI's stable-output
+ * validators (`bin/format.ts`, `bin/audit-log.ts`, `bin/tasks-view.ts`,
+ * `bin/commands/workspaces.ts`) project from when deciding which category
+ * strings from ledger records are stable enough to render, so those filters
+ * can never drift from the union. The `satisfies` half rejects a string
+ * that isn't a union member; the `AssertExhaustive` proof below rejects a
+ * union member missing from this list — extending either side alone is a
+ * compile error. The runtime half (no duplicates, every consumer projects
+ * exactly this list) is `__tests__/git-category-drift.test.ts`.
+ */
+export declare const GIT_ERROR_CATEGORIES: readonly ["git-unavailable", "git-timeout", "git-output-limit", "git-command-failed", "workspace-root-invalid", "workspace-root-conflict", "workspace-not-owned", "repository-root-mismatch", "repository-invalid", "lease-busy", "ledger-invalid"];
+/**
+ * Runtime projection of `GitWorkspacePhase` (the type itself lives in
+ * `git-workspace-store.ts`; the projection lives here beside
+ * {@link GIT_ERROR_CATEGORIES} so both category/phase single sources ship
+ * from one module) — same exhaustiveness contract, consumed by
+ * `bin/tasks-view.ts`'s phase filter.
+ */
+export declare const GIT_WORKSPACE_PHASES: readonly ["preparing", "active", "completed", "failed", "cancelled", "interrupted", "salvage"];
 export declare class GitWorkspaceError extends Error {
     readonly category: GitErrorCategory;
     constructor(category: GitErrorCategory, message?: string);

package/dist/daemon/long-poll-transport.d.ts

@@ -5,6 +5,12 @@ export interface LongPollClientOptions {
     auth: AuthManager;
     getCursor: () => number | undefined;
     onEnvelope: (envelope: Envelope) => void;
+    /**
+     * Capabilities advertised by the server that produced the current poll
+     * response. Called before any envelopes from that response are delivered.
+     * An older responder omitting the additive field is reported as `[]`.
+     */
+    onServerCapabilities?: (capabilities: string[]) => void;
     /** Called once the device is found to be revoked (401 surfaced through {@link AuthManager}) — the loop stops itself rather than retrying. */
     onRevoked?: () => void;
     /**

package/dist/daemon/observer.d.ts

@@ -188,6 +188,13 @@ export type DaemonEvent = {
         conflicted: number;
     };
     errorCategory?: string;
+} | {
+    kind: 'runtime-disposal-failed';
+    ts: string;
+    taskId: string;
+    runtimeId: string;
+    stage: 'signal' | 'quiescence' | 'cleanup';
+    reason: string;
 }
 /**
  * Plan `device-assertion-broker`: one `assertion.issue` control call
@@ -350,6 +357,12 @@ export declare class DaemonObserver {
         };
         errorCategory?: string;
     }): void;
+    noteRuntimeDisposalFailure(event: {
+        taskId: string;
+        runtimeId: string;
+        stage: 'signal' | 'quiescence' | 'cleanup';
+        reason: string;
+    }): void;
     /**
      * Finding F4: wired from `TaskRunnerDeps.onApprovalDispatched`, called
      * synchronously by `TaskRunner.dispatchApproval` BEFORE its own

package/dist/daemon/presence-publisher.d.ts

@@ -1,3 +1,30 @@
+/**
+ * Presence producer (§12.3): a periodic `{ level: 'online' }` heartbeat to
+ * `PUT /byok/presence`, started only when the deployment's capability
+ * declaration contains `presence.hints` (ADR-010 — see `capabilities-client.ts`).
+ *
+ * Three properties this module deliberately holds:
+ *
+ *  - **Only `online`.** The five levels exist in core, but nothing downstream
+ *    consumes a `thinking`/`working`/`error` mapping yet, so none is invented
+ *    here. That also keeps the rule below trivially true.
+ *  - **It never reads or writes task state.** Presence is a lossy, unsigned,
+ *    TTL-bounded hint that must never become coordination or execution state
+ *    (`@byok-sdk/core`'s `presence.ts` module doc). This publisher's only input
+ *    is a clock.
+ *  - **Stopping IS the offline signal.** No explicit `offline` publish on
+ *    shutdown: the hosted hint carries a TTL and expiry means *absence*, so a
+ *    daemon that stops beating disappears on its own. Publishing `offline` too
+ *    would express the same fact through a second channel that a crashed daemon
+ *    could never use anyway.
+ *
+ * Auth reuses the daemon's one device-token lifecycle: {@link authedFetch}
+ * attaches the current bearer and, on a 401, renews once through `AuthManager`
+ * and retries exactly once. A revoked device (`DeviceRevokedError`) stops this
+ * publisher permanently — there is no recourse but a fresh `pair()`, so
+ * retrying would be a pure spin.
+ */
+import { type ToolsetId } from '@byok-sdk/protocol';
 import type { AuthManager } from './auth-manager';
 /**
  * Client-side defaults, chosen against the hosted defaults
@@ -30,6 +57,8 @@ export declare function assertPresenceHeartbeatCadence(cadence: {
 export interface PresencePublisherOptions {
     serverUrl: string;
     auth: AuthManager;
+    /** Sorted logical IDs only. Executable MCP definitions and credentials remain device-local. */
+    configuredToolsets?: readonly ToolsetId[];
     /** Heartbeat cadence. Must sit strictly between {@link PresencePublisherOptions.minimumIntervalMs} and {@link PresencePublisherOptions.ttlMs}. */
     intervalMs?: number;
     /** The deployment's presence hint TTL, as this daemon understands it. Only used to validate the cadence. */

package/dist/daemon/runtime-capabilities.d.ts

@@ -1,7 +1,7 @@
 import type { RuntimeCapabilities as ProtocolRuntimeCapabilities } from '@byok-sdk/protocol';
 import type { RuntimeCapabilities } from '../types';
 /**
- * Maps a `RuntimeAdapter`'s own internal `capabilities()` result
+ * Maps a frozen `RuntimeAdapterDescriptor`'s internal `capabilities` value
  * (`../types.ts`'s `RuntimeCapabilities` — `{steer, resume,
  * approvalInteractive, permissionModes}`, always-required fields) onto the
  * wire's `RuntimeCapabilities` shape (`@byok-sdk/protocol` — the same field names,

package/dist/daemon/task-runner.d.ts

@@ -1,5 +1,6 @@
 import { type Envelope, type PermissionPolicy, type RuntimeId, type TaskOfferPayload, type TaskOfferWithToolsetsPayload } from '@byok-sdk/protocol';
 import { type McpToolsetConfig, type RuntimeAdapter } from '../types';
+import { type RuntimeDisposalStage } from '../runtime-failure';
 import { type ApprovalDecision, type ApprovalOrigin, type ApprovalRegistry } from './approvals';
 import type { BlobResolver } from './blob-client';
 import type { TaskQueueWatermark } from './control-protocol';
@@ -205,13 +206,20 @@ export interface TaskRunnerDeps {
         observation?: GitWorkspaceObservation;
         errorCategory?: string;
     }) => void;
+    /** Local-only evidence that a semantic terminal outcome could not yet release its runtime ownership. */
+    onRuntimeDisposalFailure?: (event: {
+        taskId: string;
+        runtimeId: string;
+        stage: RuntimeDisposalStage;
+        reason: string;
+    }) => void;
     /**
      * M4 Phase 3: this daemon's control-socket identity + the shared registry
      * backing the control socket's own `approvals.list`/`approvals.resolve`
      * methods (`create-daemon.ts` constructs ONE `ApprovalRegistry` and passes
      * the SAME instance here) — see `requestApproval`'s own doc comment for
      * why `TaskRunner` needs a handle on all three. `storeDir`/`productId` are
-     * copied verbatim into every task's `TaskContext.approvalChannel`.
+     * copied verbatim into every prepared operation's approval channel.
      */
     approvalRegistry: ApprovalRegistry;
     storeDir: string;
@@ -244,7 +252,7 @@ export interface TaskRunnerDeps {
      * to supply one — mirrors `onStaleApprovalDecision`'s own contract.
      */
     onApprovalDispatched?: (taskId: string, approvalId: string) => void;
-    /** Finding F5(a): overrides {@link DEFAULT_SHUTDOWN_INTERRUPT_TIMEOUT_MS} — see `teardownActiveTask`'s own doc comment. Also the grace window `teardownActiveTask`'s hard-kill escalation (`session.close()`) gets once `session.interrupt()` itself fails to settle in time — see that method's own doc comment for why the same window is reused for both steps. */
+    /** Overrides the bounded soft-interrupt window before authoritative `Session.close()` disposal begins. */
     shutdownInterruptTimeoutMs?: number;
     /**
      * M5 batch-3 (workstream 2): overrides {@link DEFAULT_MAX_TASK_OUTPUT_BYTES}
@@ -256,9 +264,10 @@ export interface TaskRunnerDeps {
      */
     maxTaskOutputBytes?: number;
     /**
-     * M4 (additive-minor, `task.approval_resolved`): the negotiated
-     * `conn.ack.capabilities` of the CURRENTLY (or most recently) connected
-     * server — read fresh at call time (mirrors `getCursor`/`getToken`'s own
+     * M4 (additive-minor, `task.approval_resolved`): the capabilities advertised
+     * by the CURRENT transport's server (`conn.ack` on WS, the latest successful
+     * events response on long-poll) — read fresh at call time (mirrors
+     * `getCursor`/`getToken`'s own
      * "read fresh, not captured once" convention elsewhere in this codebase),
      * since the capability is learned asynchronously, after this `TaskRunner`
      * is already constructed (`create-daemon.ts`'s `start()` builds `deps`
@@ -319,8 +328,8 @@ export type AdmissionGuardDecision = {
 };
 type AcceptedOfferPayload = TaskOfferPayload | TaskOfferWithToolsetsPayload;
 /**
- * Per-connection task orchestration: offer -> (decline | claim -> adapter
- * session -> started) -> seq-ordered progress batches -> complete/fail/
+ * Per-connection task orchestration: offer -> (decline | prepare -> seal ->
+ * claim -> prepared operation -> started) -> seq-ordered progress batches -> complete/fail/
  * cancelled, plus approve/reject/cancel/steer handling.
  *
  * M1 rework (docs/protocol.md §3, §5, §10 — `packages/protocol` is frozen,
@@ -340,13 +349,13 @@ export declare class TaskRunner {
      * Finding F4 (cancel lost during the offer-processing window): a
      * `task.cancel` for a taskId that hasn't finished `handleOffer` yet (still
      * awaiting adapter detection / instruction resolution / workspace setup /
-     * `adapter.start()`) has no `this.tasks` entry to land on — it used to be
+     * prepared operation `start()`) has no `this.tasks` entry to land on — it used to be
      * silently dropped, and the runtime session `handleOffer` was about to
      * register would then run an unsupervised ("zombie") turn nobody asked
      * for anymore. Recording the taskId here lets `handleOffer` consult it at
      * the two points where it can still safely react (see its body): before
      * claiming at all (decline instead of ever starting a session), and right
-     * after `adapter.start()` resolves but before this task is registered as
+     * after the prepared operation resolves but before this task is registered as
      * active (tear the just-started session down immediately, before its
      * event loop ever pumps a single event). Consumed (deleted) at whichever
      * checkpoint handles it; a cancel for a taskId that's already active,
@@ -372,12 +381,12 @@ export declare class TaskRunner {
      * checkpoint-2 cancel-teardown, or successful registration into
      * `this.tasks`). Bounded eviction on `pendingCancelled` (below) must never
      * remove an entry for a taskId in this set: doing so is exactly the bug —
-     * block task A in `adapter.start()`, deliver A's own `task.cancel` (so
+     * block task A in prepared-operation `start()`, deliver A's own `task.cancel` (so
      * `pendingCancelled` gets an entry for A while A is still in-flight),
      * then deliver `MAX_TRACKED_TASK_IDS` more cancels for unrelated taskIds
      * nobody ever offered — under naive oldest-wins eviction, A's entry (the
      * single oldest) gets evicted purely because of unrelated churn, so when
-     * `adapter.start()` finally resolves, checkpoint 2 finds no cancel marker
+     * the prepared operation finally resolves, checkpoint 2 finds no cancel marker
      * and the already-cancelled task starts a real session. See
      * `evictPendingCancelled` below for the fix, and
      * `task-runner-bounded-collections.test.ts` for a test mirroring this
@@ -397,7 +406,7 @@ export declare class TaskRunner {
      * explicitly relies on redelivered handlers being idempotent for exactly
      * this reason). `handleOffer` must treat a redelivered offer for a taskId
      * that's already active (`this.tasks`) or already finished (this set) as
-     * a no-op — never a second `adapter.start()` call, which would orphan the
+     * a no-op — never a second prepared-operation `start()` call, which would orphan the
      * first session.
      *
      * M3-B: unbounded otherwise — a long-lived daemon that's finished many
@@ -455,10 +464,9 @@ export declare class TaskRunner {
     /** M4 Phase 2: stop claiming any FUTURE `task.offer` — see `stoppingOffers`'s own doc comment. Idempotent. */
     stopAcceptingOffers(): void;
     /**
-     * M4 Phase 2: best-effort shutdown of every currently ACTIVE task, for the
-     * control socket's `shutdown` RPC. Mirrors `handleCancel`'s best-effort
-     * `session.interrupt()` style (an interrupt failure is swallowed; the
-     * terminal message is sent either way) but reports `task.fail` rather than
+     * Shutdown of every currently ACTIVE task for the control socket's
+     * `shutdown` RPC. Soft interrupt remains bounded, but each task's
+     * authoritative close receipt must settle successfully. Reports `task.fail` rather than
      * `task.cancelled` — these tasks aren't ending because the SERVER
      * cancelled them, they're ending because this device is shutting down.
      * `retryable: true` throughout: nothing about the task/policy itself was
@@ -509,28 +517,13 @@ export declare class TaskRunner {
      * unconditionally, so a hung `interrupt()` (a misbehaving adapter) can
      * never block `task.fail` from being sent at all.
      *
-     * New in this batch — hard-kill escalation: when `interrupt()` does NOT
-     * settle within that same grace window, `session.close()` is tried next
-     * (ALSO raced against `timeoutMs`, for the identical reason: a hung
-     * `close()` must not be able to block this forever either — which matters
-     * far more here than it used to for the pre-existing graceful-shutdown-only
-     * caller, since THAT path is additionally bounded by an outer deadline
-     * (`SHUTDOWN_TASK_TEARDOWN_DEADLINE_MS`/`DaemonConfig.shutdownGraceMs`,
-     * `create-daemon.ts`), while resource-limit enforcement fires during
-     * ordinary operation with no such outer bound watching it). `close()` is
-     * every adapter's harder teardown primitive — an actual process-level kill
-     * (SIGTERM, or `taskkill /F` on Windows — see e.g.
-     * `ClaudeProcessClient.kill()`/`PiRpcClient.kill()`) as opposed to pi's own
-     * soft in-band `interrupt()` (an RPC `abort` message that leaves the
-     * process alive and resumable) — so escalating to it is the closest thing
-     * to a "hard kill" the `Session` interface exposes. `finish()` below calls
-     * `session.close()` again regardless (documented idempotent) — this isn't
-     * a substitute for that, only an earlier, bounded attempt at actually
-     * stopping a stuck runtime before this method gives up and reports failure
-     * anyway.
+     * After the bounded soft interrupt, `finish()` always awaits the authoritative
+     * `Session.close()` receipt. A failed receipt retains active/Git ownership;
+     * shutdown surfaces the rejection while resource enforcement leaves local
+     * evidence for a later retry.
      *
      * Re-checks task identity (`this.tasks.get(...) === active`) immediately
-     * before sending `task.fail`: the interrupt/hard-kill race above has await
+     * before sending `task.fail`: the interrupt race above has await
      * points during which a DIFFERENT path (a racing `task.cancel`/
      * `task.reject`, or the session completing normally on its own) may have
      * already finished this exact task and sent its own terminal message.
@@ -623,7 +616,7 @@ export declare class TaskRunner {
      *
      * `inFlightOffers` is naturally tiny (bounded by this device's real
      * concurrent-offer-processing count — normally single digits, driven by
-     * how many `task.offer`s are simultaneously mid-`adapter.start()` — nowhere
+     * how many `task.offer`s are simultaneously mid-prepared-operation start() — nowhere
      * near `MAX_TRACKED_TASK_IDS`), so this scan is cheap in practice: it
      * finds a safe entry at or near the front almost always. The only case
      * where NO entry is safe to evict is every single tracked cancel
@@ -943,15 +936,16 @@ export declare class TaskRunner {
     /**
      * Whether the CURRENTLY connected server advertised `result-document` —
      * read fresh on every call, never captured, because the answer changes
-     * across a reconnect (`ConnectionManager.getServerCapabilities` returns
-     * `[]` from the moment an acked connection closes until a fresh
-     * `conn.ack` repopulates it). An absent `getServerCapabilities` seam is
+     * across a reconnect or transport switch (`ConnectionManager` clears the
+     * old advertisement at the boundary, then repopulates it from a fresh WS
+     * ack or successful poll response). An absent `getServerCapabilities` seam is
      * "no capabilities", the fail-closed reading.
      */
     private hasResultDocumentCapability;
     private observeGit;
     private updateGitPhaseBestEffort;
     private finish;
+    private reserveSemanticTerminal;
     /** M3-B: bounded insert for `finishedTaskIds` — see its class-level doc comment and `MAX_TRACKED_TASK_IDS`. Evicts the oldest (first-inserted) entry once over cap, same idiom as `ConnectionHub.checkAndRecordDuplicate` (packages/server/src/hub.ts). */
     private addFinishedTaskId;
     /** `reuseDir`, when set (a known sessionRef's recorded workspace), is used verbatim instead of a fresh `workspaceRoot/<taskId>` directory — `mkdir recursive` is idempotent either way, so ensuring-exists is safe to do unconditionally. */

package/dist/daemon/ws-transport.d.ts

@@ -1,4 +1,4 @@
-import { type CapabilityFlag, type Envelope, type RuntimeInfo } from '@byok-sdk/protocol';
+import { type CapabilityFlag, type Envelope, type RuntimeInfo, type ToolsetId } from '@byok-sdk/protocol';
 export type ConnectionState = 'connecting' | 'open' | 'closed' | 'degraded' | 'revoked';
 /** The WS upgrade itself was rejected with a non-101 HTTP status (e.g. 401 for an expired/invalid bearer token). Surfaced via `onConnectOutcome` so `ConnectionManager` can force a reactive token renewal before the next attempt (protocol §6.2, "reactively on 401"). */
 export declare class WsUnexpectedStatusError extends Error {
@@ -25,6 +25,8 @@ export interface WsTransportOptions {
     capabilities: CapabilityFlag[];
     /** Detected runtimes, sent on every `conn.hello` (protocol §10 gap #4/#11). */
     runtimes?: RuntimeInfo[];
+    /** Sorted logical IDs configured locally; no MCP executable definition crosses the wire. */
+    configuredToolsets?: readonly ToolsetId[];
     /** The redelivery cursor to send as `conn.hello.cursor` (protocol §9) — read fresh on every connect so a value learned mid-connection is used on the next reconnect. */
     getCursor?: () => number | undefined;
     onEnvelope: (envelope: Envelope) => void;

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-export type { RuntimeAdapter, RuntimeCapabilities, RuntimeDetectResult, Session, TaskContext, GitWorkspaceConfig, McpStdioServerConfig, McpToolsetConfig, } from './types';
-export { PolicyUnsupportedError, SteerUnsupportedError } from './types';
+export type { RuntimeAdapter, RuntimeAdapterDescriptor, RuntimeAdapterPrepareInput, RuntimeAdapterPrepareResult, RuntimeAdapterRejectedOperation, RuntimeAdapterPreparedOperation, PreparedRuntimeOperation, RuntimeOperationManifest, RuntimeOperationStartInput, RuntimeCapabilities, RuntimeDetectResult, Session, GitWorkspaceConfig, McpStdioServerConfig, McpToolsetConfig, } from './types';
+export { PolicyUnsupportedError, SteerUnsupportedError, freezeRuntimeAdapterDescriptor, sealRuntimeOperationManifest } from './types';
 export type { RuntimeEnvironmentRequirements } from './daemon/environment';
+export { RuntimeExecutionFailure, RuntimeDisposalFailure, RUNTIME_ADAPTER_CONTRACT_VIOLATION_REASON, isRuntimeDisposalFailure, isRuntimeExecutionFailure, projectRuntimeBoundaryFailure, projectRuntimeExecutionFailure, } from './runtime-failure';
+export type { RuntimeExecutionFailureInput, RuntimeDisposalFailureInput, RuntimeDisposalStage, RuntimeFailureCategory, RuntimeFailurePhase, RuntimeFailureProjection, RuntimeRetryDisposition, } from './runtime-failure';
 export { GitWorkspaceManager, GitWorkspaceError, isGitWorkspaceConfig, prependGitWorkspaceGuidance } from './daemon/git-workspace';
 export type { GitWorkspaceObservation, GitWorkspaceLease, GitWorkspaceOptions, GitErrorCategory } from './daemon/git-workspace';
 export { GitWorkspaceStore } from './daemon/git-workspace-store';