@byok-sdk/server 0.12.0 → 0.14.0

package/dist/rate-limiter.d.ts

@@ -112,3 +112,41 @@ export declare class RateLimiter {
      */
     private evictOldestIfAtCapacity;
 }
+/**
+ * The counting `InboundRateLimiter` (`@byok-sdk/cloud`'s store port) this
+ * package composes the kernel with.
+ *
+ * Position matters and is not this adapter's choice: the kernel debits one
+ * token at step 0 of its inbound gate, BEFORE the type-allow check, for every
+ * envelope that reaches it. That is exactly the choke point the old
+ * `ConnectionHub.handleInbound` occupied, which is why both `envelopesIn` (one
+ * per envelope, every outcome) and `rateLimitEvents` (one per REJECTED
+ * envelope, never coalesced) are counted here and nowhere else.
+ *
+ * The `device.rate_limited` embedder event is the one thing that IS coalesced,
+ * matching the pre-fold rule: an episode fires exactly one event, and only a
+ * subsequent SUCCESSFUL consume by that device re-arms it. So a flood produces
+ * one event and N counter increments, and a device that recovers and floods
+ * again produces a second, distinct event.
+ */
+export interface InboundRateLimiterCounters {
+    /** Every envelope handed to the kernel's inbound gate, whatever the gate then decides. */
+    envelopesIn: number;
+    /** Envelopes the bucket refused. Per envelope — see the episode rule above. */
+    rateLimitEvents: number;
+}
+export interface CountingInboundRateLimiter {
+    /** The port `CloudStores.rateLimiter` is composed with. */
+    readonly limiter: {
+        consume(tenant: string, deviceId: string): Promise<boolean>;
+    };
+    readonly counters: InboundRateLimiterCounters;
+}
+/**
+ * Adapt a {@link RateLimiter} to the kernel's `(tenant, deviceId)` port.
+ *
+ * The bucket key is `${tenant}:${deviceId}` rather than the bare device id: a
+ * device id is only unique within its tenant, and a shared key space would let
+ * one tenant's flood spend another's budget for a colliding id.
+ */
+export declare function createCountingInboundRateLimiter(limiter: RateLimiter, onRateLimited: (deviceId: string, at: string) => void): CountingInboundRateLimiter;

package/dist/relay.d.ts

@@ -0,0 +1,86 @@
+import type { InboundCommitted, ByokCloudObserver } from '@byok-sdk/cloud';
+import type { TaskState } from '@byok-sdk/protocol';
+import type { DeviceConnections } from './connections';
+import type { ByokServerEvent, ServerTaskEvent } from './types';
+/** Per-task {@link ServerTaskEvent} retention before drop-oldest engages. */
+export declare const DEFAULT_TASK_EVENT_BUFFER_LIMIT = 1000;
+/** How long a terminal task's relay state is retained before reclamation, ms. */
+export declare const DEFAULT_TASK_EVENT_RETENTION_MS: number;
+export interface TaskEventRelayOptions {
+    readonly connections: DeviceConnections;
+    readonly taskEventBufferLimit?: number;
+    readonly taskEventRetentionMs?: number;
+}
+/**
+ * Post-commit fan-out: cloud kernel envelopes -> `ServerTaskEvent` /
+ * `ByokServerEvent`.
+ *
+ * The invariant this file exists to keep (WP3B §3): **the relay holds
+ * notifications, never state**. It never answers "what is this task", "what did
+ * it produce" or "who owns it" — every one of those is read back from the
+ * kernel's durable stores on demand. What it owns is per-task delivery
+ * plumbing: a bounded replayable queue, and one promise that settles when the
+ * task reaches a terminal so `TaskHandle.result()` has something to await
+ * before it reads the answer back.
+ *
+ * The two small facts it does carry are delivery bookkeeping, not a read model:
+ * `terminalSettled` (so the FIRST terminal is the one that settles the promise,
+ * matching the store's own first-terminal-wins rule, and a later stale terminal
+ * is not announced as a second one) and `claimedRuntime` (echoed onto the
+ * `task.state` event stream because the pre-fold feed carried it there; the
+ * authoritative copy is `TaskAttempt.claimedRuntime`).
+ *
+ * Dispatch first {@link provision}s a known task id, then activates it with
+ * {@link noteDispatched} after the kernel has accepted its offer. Envelopes
+ * that arrive in that narrow interval are buffered, not dropped. An envelope
+ * naming a task this server never dispatched is folded for nobody and allocates nothing —
+ * otherwise a device could grow this map without bound by guessing task ids,
+ * and the kernel's gate deliberately treats such an envelope as a harmless
+ * store no-op rather than a rejection.
+ *
+ * `onInboundCommitted` runs inline on the kernel's request path and must stay
+ * synchronous and cheap; anything needing a store read goes through
+ * {@link onTaskActivity}, which the composition sets and which owns its own
+ * failure handling.
+ */
+export declare class TaskEventRelay implements ByokCloudObserver {
+    #private;
+    /**
+     * Called once per committed task-progress observation for a dispatched task.
+     * The composition uses it to run the implicit-approval-resume check, which
+     * needs a store read and therefore cannot happen inline here.
+     */
+    onTaskActivity: ((taskId: string, pendingRequestSourceEnvelopeId: string | undefined, activitySourceEnvelopeId: string, activityAt: string) => void) | undefined;
+    constructor(options: TaskEventRelayOptions);
+    /** The cross-task embedder feed backing `ByokServer.events.subscribe()`. */
+    serverEvents(): AsyncIterable<ByokServerEvent>;
+    /** Publish one cross-task event (rate-limit episodes, host-side transitions). */
+    emitServerEvent(event: ByokServerEvent): void;
+    /** Pre-register a task id before its offer enqueue can become observable. */
+    provision(taskId: string): void;
+    /** Forget an enqueue that failed before it produced an offer. */
+    abort(taskId: string): void;
+    /**
+     * Open the relay for a task this server just dispatched, and publish its
+     * `Offered` origin on both feeds. `at` is the offer envelope's own timestamp,
+     * so the feed and the snapshot agree on when the task began.
+     */
+    noteDispatched(taskId: string, at: string): void;
+    /** The per-task feed backing `TaskHandle.events()`, replayed from the start of what is retained. */
+    events(taskId: string): AsyncIterable<ServerTaskEvent>;
+    /** Settles when this task first reaches a terminal — the barrier `TaskHandle.result()` awaits. */
+    terminal(taskId: string): Promise<void>;
+    /**
+     * Host-side transitions the wire never carries: an accepted cancellation, and
+     * an approval the operator resolved through `TaskHandle.approve`/`reject`.
+     * Published here so the two feeds report the same task history whichever side
+     * moved it, and (for a terminal) so `result()` is not left waiting on a device
+     * message that a cancelled task will never send.
+     */
+    noteHostTransition(taskId: string, state: TaskState, at: string): void;
+    onInboundCommitted(input: InboundCommitted): void;
+    /** Publish an implicit resolution the composition inferred from later task traffic. */
+    emitImplicitApprovalResolved(taskId: string, at: string): void;
+    /** Close every feed and drop every timer. Safe to call more than once. */
+    stop(): void;
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,64 @@
+import type { DeviceRecord, PendingApproval, TaskAttempt, TerminalResult } from '@byok-sdk/cloud';
+import type { TaskState } from '@byok-sdk/protocol';
+import type { DeviceConnection } from './connections';
+import type { MachineInfo, TaskResult, TaskSnapshot } from './types';
+/**
+ * Projections from the cloud kernel's read model onto this package's public
+ * shapes. Pure functions, deliberately: every input is a value the caller has
+ * already read from a store, so there is exactly one place the mapping lives
+ * and no way for a second copy of it to drift.
+ */
+/**
+ * What this server calls a task the kernel calls a `TaskAttempt`.
+ *
+ * The order of the gates is the whole contract, and it mirrors the kernel's own
+ * (`ByokCloud.readTaskResult`):
+ *
+ * 1. an accepted host cancellation OUTRANKS everything a runtime reports later.
+ *    `cancel()` is authoritative the moment the kernel records it, so the task
+ *    reads `Cancelled` immediately and a late `task.complete` — which the wire
+ *    still answers as a success — cannot move it;
+ * 2. a terminal attempt is its own terminal;
+ * 3. an unresolved approval on the task's timeline is `AwaitApproval`. The
+ *    kernel has no such attempt STATUS on purpose (ADR-028: no execution state
+ *    in the cloud) — the pause is derived from the durable approval timeline,
+ *    which is the same single authority `approveTask`'s staleness gate reads;
+ * 4. otherwise the attempt's own coarse status.
+ */
+export declare function toTaskState(attempt: TaskAttempt, pending: PendingApproval | undefined): TaskState;
+/**
+ * The kernel's typed terminal read model, narrowed to this package's
+ * {@link TaskResult}.
+ *
+ * Deliberately LOSSY in one direction: `taskId`, `recordedAt`, `agentRef`,
+ * `usage` and `terminalCause` exist on `TerminalResult` and have no place here.
+ * They are all reachable through the kernel (`readTaskResult`), and copying
+ * them into a second shape would make this projection something a caller has to
+ * keep in sync rather than a narrowing of one authority.
+ */
+export declare function toTaskResult(terminal: TerminalResult | undefined): TaskResult | undefined;
+/**
+ * The dispatch-time facts the kernel does not persist.
+ *
+ * `TaskAttempt` records ownership and disposition, not the request that opened
+ * it — it carries no `createdAt` and no `sessionRef`. Both are needed by the
+ * public snapshot, and both are known exactly once, at dispatch, so this
+ * process keeps them keyed by task id rather than inventing a durable column or
+ * quietly reporting the attempt's last-mutation time as its creation time.
+ * Deliberately not TTL-reclaimed: it is the exact peer of the in-memory attempt
+ * store this composition is built on, and it must not forget a task that store
+ * still answers for.
+ */
+export interface DispatchFacts {
+    readonly createdAt: string;
+    readonly sessionRef?: string;
+}
+export declare function toTaskSnapshot(attempt: TaskAttempt, pending: PendingApproval | undefined, terminal: TerminalResult | undefined, dispatched: DispatchFacts | undefined): TaskSnapshot;
+/**
+ * A device row joined with what this process observed of its connection.
+ *
+ * The identity half is durable and tenant-owned; the connection half is an
+ * in-process observation that dies with the server — see `connections.ts` for
+ * why `conn.hello`'s runtime discovery block is deliberately not persisted.
+ */
+export declare function toMachineInfo(device: DeviceRecord, connection: DeviceConnection | undefined): MachineInfo;

package/dist/sqlite-support.d.ts

@@ -16,12 +16,12 @@ export declare function closeSqliteDatabaseAfterInitializationFailure(db: Databa
  * Thrown when `node:sqlite` isn't available in the running Node.js binary.
  * `node:sqlite` shipped in Node.js 22.5.0 (https://nodejs.org/api/sqlite.html)
  * and remains marked experimental there (an `ExperimentalWarning` on stderr
- * is expected and harmless — not an error). The SQLite-backed reference
- * stores in this package (`SqliteTaskStore`, `SqliteBlobStore`) deliberately
+ * is expected and harmless — not an error). The SQLite-backed embedded store
+ * composition deliberately
  * depend on nothing else — no `better-sqlite3` or other native module —
  * because staying at zero native dependencies is required to keep
  * `@byok-sdk/server` trivially packageable across platforms. The tradeoff is
- * that these stores simply don't work below Node 22.5; this error says so
+ * that this composition simply doesn't work below Node 22.5; this error says so
  * clearly and up front, instead of letting a cryptic `Cannot find module
  * 'node:sqlite'` surface from deep inside a query.
  */

package/dist/stores/sqlite/__tests__/atomic-restart.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/stores/sqlite/__tests__/conformance.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/stores/sqlite/index.d.ts

@@ -0,0 +1,140 @@
+import { type Clock, type ContentHash, type CoreStores, type MailboxAppendInput, type MailboxCursorState, type MailboxMessage, type MailboxPage, type MailboxReadQuery, type MailboxRecordDeliveryInput, type MailboxAdvanceCursorInput, type MailboxRetentionInput, type MailboxRetentionResult, type MailboxStore, type ObjectCommitInput, type ObjectListQuery, type ObjectManifestEntry, type ObjectManifestInput, type ObjectReferenceInput, type ObjectStore, type StorageReservation, type TenantId } from '@byok-sdk/core';
+import { type AgentMessageAdmission, type AgentRef, type BlobContentProxy, type CloudBlobStore, type BlobObservation, type BlobReadResult, type BlobWriteResult, type CloudCrypto, type CloudStores, type TaskAttempt, type TaskAttemptListQuery, type TaskAttemptPage, type TaskAttemptStatus, type TaskAttemptStore, type TaskCancellationMutation, type TaskCancellationRequest, type TaskCancellationStore } from '@byok-sdk/cloud';
+import { type RuntimeCapabilities, type RuntimeId } from '@byok-sdk/protocol';
+import type { DatabaseSync } from 'node:sqlite';
+export interface SqliteEmbeddedStoreOptions {
+    readonly path: string;
+    readonly urlTtlMs?: number;
+}
+export interface SqliteEmbeddedStores {
+    readonly core: CoreStores;
+    readonly cloud: CloudStores;
+    readonly blobContentProxy: BlobContentProxy;
+    close(): Promise<void>;
+}
+/** One serialized owner for the synchronous SQLite handle and every transaction on it. */
+declare class SqliteCoordinator {
+    #private;
+    readonly db: DatabaseSync;
+    constructor(path: string);
+    run<T>(operation: (db: DatabaseSync) => T | Promise<T>): Promise<T>;
+    transaction<T>(operation: (db: DatabaseSync) => T | Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+export declare class SqliteTaskAttemptStore implements TaskAttemptStore {
+    #private;
+    private readonly coordinator;
+    private readonly clock;
+    constructor(coordinator: SqliteCoordinator, clock: Clock);
+    open(tenant: TenantId, input: {
+        taskId: string;
+        deviceId: string;
+        agentRef?: AgentRef;
+    }): Promise<TaskAttempt>;
+    reserveAgentOffer(tenant: TenantId, input: {
+        taskId: string;
+        deviceId: string;
+        agentRef: AgentRef;
+    }): Promise<{
+        attempt: TaskAttempt;
+        created: boolean;
+    }>;
+    reserveAgentMessage(tenant: TenantId, input: {
+        taskId: string;
+        deviceId: string;
+        messageId: string;
+        payloadBody: string;
+    }): Promise<'reserved' | 'pending' | 'rejected'>;
+    readAgentMessage(tenant: TenantId, input: {
+        taskId: string;
+        deviceId: string;
+        messageId: string;
+        payloadBody: string;
+    }): Promise<AgentMessageAdmission | undefined>;
+    finalizeAgentMessage(tenant: TenantId, input: {
+        taskId: string;
+        deviceId: string;
+        messageId: string;
+        payloadBody: string;
+        terminalBody: string;
+    }): Promise<AgentMessageAdmission | undefined>;
+    get(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;
+    getMany(tenant: TenantId, taskIds: readonly string[]): Promise<readonly TaskAttempt[]>;
+    list(tenant: TenantId, query: TaskAttemptListQuery): Promise<TaskAttemptPage>;
+    claim(tenant: TenantId, input: {
+        taskId: string;
+        deviceId: string;
+        runtime?: RuntimeId;
+        capabilities?: RuntimeCapabilities;
+    }): Promise<TaskAttempt | undefined>;
+    recordStatus(tenant: TenantId, input: {
+        taskId: string;
+        status: TaskAttemptStatus;
+        agentRef?: AgentRef;
+        terminalCause?: string;
+    }): Promise<TaskAttempt | undefined>;
+}
+export declare class SqliteMailboxStore implements MailboxStore {
+    private readonly coordinator;
+    private readonly clock;
+    constructor(coordinator: SqliteCoordinator, clock: Clock);
+    append(tenant: TenantId, input: MailboxAppendInput): Promise<MailboxMessage>;
+    readAfter(tenant: TenantId, query: MailboxReadQuery): Promise<MailboxPage>;
+    recordDelivery(tenant: TenantId, input: MailboxRecordDeliveryInput): Promise<MailboxCursorState>;
+    advanceCursor(tenant: TenantId, input: MailboxAdvanceCursorInput): Promise<MailboxCursorState>;
+    readCursor(tenant: TenantId, deviceId: string): Promise<MailboxCursorState>;
+    collectRetired(tenant: TenantId, input: MailboxRetentionInput): Promise<MailboxRetentionResult>;
+}
+export declare class SqliteTaskCancellationStore implements TaskCancellationStore {
+    private readonly coordinator;
+    private readonly clock;
+    constructor(coordinator: SqliteCoordinator, clock: Clock);
+    request(tenant: TenantId, input: TaskCancellationRequest): Promise<TaskCancellationMutation | undefined>;
+}
+export declare class SqliteObjectStore implements ObjectStore {
+    #private;
+    private readonly coordinator;
+    private readonly clock;
+    constructor(coordinator: SqliteCoordinator, clock: Clock);
+    putManifest(tenant: TenantId, input: ObjectManifestInput): Promise<ObjectManifestEntry>;
+    commit(tenant: TenantId, input: ObjectCommitInput): Promise<ObjectManifestEntry>;
+    get(tenant: TenantId, hash: ContentHash): Promise<ObjectManifestEntry | undefined>;
+    list(tenant: TenantId, query: ObjectListQuery): Promise<readonly ObjectManifestEntry[]>;
+    addReference(tenant: TenantId, input: ObjectReferenceInput): Promise<ObjectManifestEntry>;
+    removeReference(tenant: TenantId, input: ObjectReferenceInput): Promise<ObjectManifestEntry>;
+    markDeletePending(tenant: TenantId, hash: ContentHash): Promise<ObjectManifestEntry>;
+    markDeleted(tenant: TenantId, hash: ContentHash): Promise<ObjectManifestEntry>;
+}
+declare class SqliteBlobRegistry {
+    readonly coordinator: SqliteCoordinator;
+    readonly clock: Clock;
+    readonly crypto: CloudCrypto;
+    readonly secret: Uint8Array;
+    readonly urlTtlMs: number;
+    constructor(coordinator: SqliteCoordinator, clock: Clock, crypto: CloudCrypto, urlTtlMs: number);
+    signUrl(blobId: string, action: 'put' | 'get'): Promise<string>;
+}
+export declare class SqliteCloudBlobStore implements CloudBlobStore {
+    private readonly registry;
+    constructor(registry: SqliteBlobRegistry);
+    createUpload(tenant: TenantId, reservation: StorageReservation): Promise<{
+        blobId: string;
+        uploadUrl: string;
+    }>;
+    observeUpload(tenant: TenantId, blobId: string, reservation: StorageReservation): Promise<BlobObservation | undefined>;
+    getDownloadUrl(tenant: TenantId, blobId: string): Promise<string | undefined>;
+}
+export declare class SqliteBlobContentProxy implements BlobContentProxy {
+    private readonly registry;
+    constructor(registry: SqliteBlobRegistry);
+    verifySignedUrl(blobId: string, action: 'put' | 'get', sig: string, exp: number): Promise<boolean>;
+    expectedUploadBytes(blobId: string): Promise<bigint | undefined>;
+    writeContent(blobId: string, data: Uint8Array): Promise<BlobWriteResult>;
+    readContent(blobId: string): Promise<BlobReadResult | undefined>;
+}
+/** Mixed embedded composition: exactly six durable interfaces, every other port unchanged in-memory. */
+export declare function createSqliteEmbeddedStores(options: SqliteEmbeddedStoreOptions, dependencies: {
+    readonly clock: Clock;
+    readonly crypto: CloudCrypto;
+}): SqliteEmbeddedStores;
+export {};

package/dist/stores.d.ts

@@ -0,0 +1,65 @@
+import { type Clock, type CoreStores, type TenantId } from '@byok-sdk/core';
+import { type BlobContentProxy, type CloudCrypto, type CloudStores } from '@byok-sdk/cloud';
+import { type RateLimiterOptions } from './rate-limiter';
+import type { DeviceConnections } from './connections';
+import type { ByokServerStorage } from './types';
+/**
+ * The store composition this façade hands the cloud kernel.
+ *
+ * Same parts as `@byok-sdk/cloud`'s own in-memory composition, with three
+ * decorators layered on ports the kernel already calls, and nothing else:
+ *
+ * - `rateLimiter` becomes this package's token bucket, which is also where
+ *   `envelopesIn` and `rateLimitEvents` are counted (the kernel debits it at
+ *   gate step 0, for every envelope, before any other decision — the exact
+ *   choke point `ConnectionHub.handleInbound` used to be);
+ * - `dedup` counts the already-seen answers that back `dedupDrops`;
+ * - `mailbox` reports each device-scoped read, which is how a device that only
+ *   ever long-polls still counts as present.
+ *
+ * Decorators rather than kernel changes, deliberately: each counter is a fact
+ * about a call this composition already makes, so it is observable from the
+ * outside, and the kernel keeps no observability surface it would then have to
+ * keep honest for every other deployment.
+ */
+/** Per-product blob size ceiling (§7): 100MB unless overridden. */
+export declare const DEFAULT_MAX_BLOB_SIZE_BYTES: number;
+/**
+ * The one tenant an embedded server serves.
+ *
+ * An embedded `createByokServer` is a single product's coordinator, not a
+ * multi-tenant control plane: there is no surface on it that could name a
+ * second tenant and no request that could carry one. Deriving the id from
+ * `productId` keeps that visible — one product, one tenant, and a device paired
+ * into this instance can only ever land in it.
+ */
+export declare function serverTenantId(productId: string): TenantId;
+/** Live counter reads; every field is derived from a call the kernel already makes. */
+export interface FacadeCounters {
+    /** Every envelope the kernel's inbound gate was handed, whatever it decided. */
+    readonly envelopesIn: number;
+    /** Inbound envelopes recognized as an already-seen `(device, envelope id)` pair. */
+    readonly dedupDrops: number;
+    /** Inbound envelopes the bucket refused — one per envelope, never coalesced. */
+    readonly rateLimitEvents: number;
+}
+export interface FacadeStoreComposition {
+    readonly core: CoreStores;
+    readonly cloud: CloudStores;
+    readonly blobContentProxy: BlobContentProxy;
+    readonly clock: Clock;
+    readonly crypto: CloudCrypto;
+    readonly counters: FacadeCounters;
+    close(): Promise<void>;
+}
+export interface FacadeStoreOptions {
+    readonly tenant: TenantId;
+    readonly maxBlobSizeBytes: number;
+    readonly storage?: ByokServerStorage;
+    readonly rateLimit?: RateLimiterOptions;
+    /** Where a device's own liveness observations are recorded. */
+    readonly connections: DeviceConnections;
+    /** Fired once per rate-limit EPISODE, not per refused envelope. */
+    readonly onRateLimited: (deviceId: string, at: string) => void;
+}
+export declare function composeFacadeStores(options: FacadeStoreOptions): FacadeStoreComposition;

package/dist/task-handle.d.ts

@@ -0,0 +1,61 @@
+import { type ByokCloud, type SteerRejectionCode, type TenantId } from '@byok-sdk/cloud';
+import type { RuntimeId, TaskState } from '@byok-sdk/protocol';
+import type { TaskEventRelay } from './relay';
+import type { TaskHandle, TaskResult } from './types';
+/**
+ * Thrown by {@link TaskHandle.steer} when the kernel refuses the steer.
+ *
+ * This package keeps its OWN class rather than re-exporting the kernel's, and
+ * that is deliberate rather than a leftover. The two carry the same `taskId`,
+ * `code` and `runtime`, and differ in exactly one field: the kernel reports
+ * `status: TaskAttemptStatus` — its coarse, execution-free attempt disposition
+ * (`running`, `offered`, …) — while this surface reports `state: TaskState`,
+ * the WIRE vocabulary every other member of this package speaks
+ * (`TaskSnapshot.state`, `ServerTaskEvent`, `HubStats.taskCountsByState`).
+ * `AwaitApproval` is the reason they cannot be the same field: it is derived
+ * from the durable approval timeline and has no attempt status at all
+ * (ADR-028), so a `TaskAttemptStatus -> TaskState` mapping inside the kernel
+ * would have to report `Running` for a task this façade calls `AwaitApproval`.
+ *
+ * So the state here is not translated from the kernel's field — it is READ,
+ * through the very projection `byok.tasks.get(taskId)` answers with, at the
+ * moment of the refusal. One authority, two readers, no second mapping.
+ *
+ * Deviation from design packet §1.2, which had this class move to
+ * `@byok-sdk/cloud` with the server re-exporting it: the wire `TaskState`
+ * vocabulary is host-facing and lives here, so the class that carries it does
+ * too. `SteerRejectionCode` and `StaleApprovalError` are unaffected and stay
+ * kernel re-exports.
+ */
+export declare class SteerRejectedError extends Error {
+    readonly taskId: string;
+    readonly code: SteerRejectionCode;
+    /** The task's state at the moment the steer was refused. */
+    readonly state: TaskState;
+    /** `TaskSnapshot.claimedRuntime` — `undefined` when nothing was ever recorded, which is itself a reason `steer_unsupported_runtime` can fire. */
+    readonly runtime: RuntimeId | undefined;
+    constructor(taskId: string, code: SteerRejectionCode, state: TaskState, runtime: RuntimeId | undefined);
+}
+export interface TaskHandleDeps {
+    readonly tenant: TenantId;
+    readonly cloud: ByokCloud;
+    readonly relay: TaskEventRelay;
+    /**
+     * The task's current `TaskSnapshot.state`, or `undefined` when the attempt is
+     * gone. The snapshot projection itself — never a second derivation.
+     */
+    readonly readState: (taskId: string) => Promise<TaskState | undefined>;
+    /** The read-back this handle's `result()` answers with. */
+    readonly readResult: (taskId: string) => Promise<TaskResult | undefined>;
+}
+/**
+ * One in-flight task's control surface.
+ *
+ * The §3 invariant it exists to keep: **the handle is not a second authority.**
+ * Every mutation is a kernel call, and `result()` is a READ-BACK — it waits for
+ * the relay's terminal barrier and then asks the store what the terminal was,
+ * so `handle.result()` and `byok.tasks.get(taskId).result` are physically the
+ * same fact rather than two copies that can disagree. Nothing about the task is
+ * cached here.
+ */
+export declare function createTaskHandle(taskId: string, deps: TaskHandleDeps): TaskHandle;