@byok-sdk/server 0.11.0 → 0.13.0

package/dist/connections.d.ts

@@ -0,0 +1,71 @@
+import type { RuntimeInfo, ToolsetId } from '@byok-sdk/protocol';
+/**
+ * What this process has OBSERVED about a device's live connection.
+ *
+ * This is not a second authority over anything durable. The device row
+ * (`DeviceRecord`, `@byok-sdk/cloud`) owns identity and the capability list
+ * every admission gate reads; the mailbox owns delivery. What lives here is the
+ * part of `conn.hello` the kernel deliberately does not persist — the runtime
+ * DISCOVERY block and the client's self-reported version/toolset inventory —
+ * plus "when did we last hear from this device at all".
+ *
+ * Why the kernel does not persist it: `conn.hello.runtimes` describes what a
+ * device build could run, changes on every daemon restart, and authorizes
+ * nothing (the steer gate reads the CLAIM snapshot, never this). Storing it
+ * durably would create a stale second description of a device that outlives the
+ * process that saw it. Keeping it as an in-process observation is honest about
+ * its lifetime: restart the server and it is gone, exactly like the connection
+ * it describes.
+ *
+ * `connected` is therefore "observed alive and not since forgotten", not "a
+ * socket is open" — there are no sockets any more. Two observations set it: the
+ * device's own `conn.hello` over `POST /byok/messages`, and a `GET /byok/events`
+ * poll (a device that is polling is present even if it never announced). One
+ * clears it: revocation, which deletes the device row and everything scoped to
+ * it.
+ */
+export interface DeviceConnection {
+    connected: boolean;
+    /** ISO-8601 instant of the most recent observation. */
+    lastSeen: string;
+    clientVersion?: string;
+    runtimes?: RuntimeInfo[];
+    configuredToolsets?: ToolsetId[];
+}
+/** `conn.hello`'s discovery half, as observed on one accepted announcement. */
+export interface DeviceAnnouncement {
+    readonly clientVersion?: string;
+    readonly runtimes?: readonly RuntimeInfo[];
+    readonly configuredToolsets?: readonly ToolsetId[];
+}
+/**
+ * In-process device observations, in first-observation order.
+ *
+ * Insertion order is load-bearing for ambient dispatch selection
+ * (`device-selection.ts`): "the first connected device" must be stable and
+ * explainable, and a `Map` gives that for free without a second index.
+ */
+export declare class DeviceConnections {
+    #private;
+    /**
+     * Record an accepted `conn.hello`. Discovery fields are REPLACED wholesale,
+     * never merged: a daemon that restarted with a runtime removed must not keep
+     * advertising it because an older hello mentioned it.
+     */
+    announce(deviceId: string, announcement: DeviceAnnouncement, at: string): void;
+    /**
+     * Record any other sign of life (an inbound envelope, a long-poll read).
+     * Deliberately additive: it refreshes `lastSeen` and marks the device present
+     * without touching the discovery block, because none of those signals carry
+     * one and clearing it would lose what the last hello said.
+     */
+    touch(deviceId: string, at: string): void;
+    get(deviceId: string): DeviceConnection | undefined;
+    isConnected(deviceId: string): boolean;
+    connectedCount(): number;
+    /** Device ids in first-observation order — the order ambient selection walks. */
+    ids(): readonly string[];
+    /** Drop everything scoped to a device. Called when its registration is deleted (§6.3). */
+    forget(deviceId: string): void;
+    clear(): void;
+}

package/dist/device-selection.d.ts

@@ -0,0 +1,30 @@
+import { type ToolsetId } from '@byok-sdk/protocol';
+/**
+ * Ambient device selection for a `dispatch()` that named no `deviceId`.
+ *
+ * `DispatchInput.deviceId` stays optional (ADR-034), so this rule survives the
+ * fold. It is a SCHEDULING convenience and nothing more: every admission gate
+ * that actually protects something — Agent capability, strict-agent-only,
+ * egress, toolset selection — runs afterwards against the durable device row
+ * inside the kernel, on the device this picked exactly as on one the caller
+ * named. Picking wrong therefore costs a refusal, never a wrongly-authorized
+ * dispatch.
+ *
+ * "First connected" means first OBSERVED (`connections.ts` preserves
+ * first-observation order), which is stable and explainable, unlike any
+ * load-shaped ordering this package has no information to compute.
+ */
+export interface DeviceCandidate {
+    readonly deviceId: string;
+    /** The durable capability list from the device's last accepted `conn.hello`. */
+    readonly capabilities: readonly string[] | undefined;
+    /** The logical toolset inventory the same announcement reported, if any. */
+    readonly configuredToolsets: readonly ToolsetId[] | undefined;
+}
+export interface AmbientSelectionQuery {
+    /** Every toolset must be present; an unknown inventory is never guessed at. */
+    readonly requiredToolsets?: readonly ToolsetId[];
+    /** Agent-bound dispatch is the only caller allowed to land on a strict-agent-only device. */
+    readonly allowStrictAgentOnly?: boolean;
+}
+export declare function pickFirstConnectedDevice(candidates: readonly DeviceCandidate[], query?: AmbientSelectionQuery): string | undefined;

package/dist/event-queue.d.ts

@@ -1,18 +1,53 @@
 /**
  * A tiny append-only, multi-reader async queue. `push` never blocks; `close`
  * marks the queue done. `subscribe()` returns a fresh async iterator that
- * always replays from the beginning of the buffer, so a consumer that calls
- * `events()` at any point still "sees everything" for that task's lifetime.
+ * always replays from the beginning of the retained buffer, so a consumer that
+ * calls `events()` at any point still sees everything still retained for that
+ * task's lifetime.
+ *
+ * Bounded, deliberately (WP3B §3): this queue is a NOTIFICATION relay, not a
+ * record of what happened — the durable facts live in the cloud stores a
+ * `ByokServer` reads back (`tasks.get`, `TaskHandle.result()`). A consumer that
+ * stops iterating must therefore cost bounded memory, not unbounded growth. On
+ * overflow the OLDEST entries are dropped and, exactly once per queue, a
+ * caller-supplied `truncationMarker` is appended so a reader can tell a
+ * complete feed from a clipped one instead of silently seeing a gap.
  *
  * Framework-agnostic on purpose (no Node/WS/Hono types here) so it can be
  * unit-tested and reused regardless of transport.
  */
+export interface AsyncEventQueueOptions<T> {
+    /**
+     * Maximum entries retained before drop-oldest engages. Omitted means
+     * unbounded — only appropriate for a queue whose producer is itself bounded.
+     */
+    readonly maxBuffered?: number;
+    /**
+     * Appended once, after the first drop, so the truncation is observable.
+     * Omitted means a bounded queue that drops silently.
+     */
+    readonly truncationMarker?: T;
+}
 export declare class AsyncEventQueue<T> {
     private readonly buffer;
+    private nextSequence;
     private closed;
     private waiters;
+    private readonly maxBuffered;
+    private readonly truncationMarker;
+    private truncationNoted;
+    constructor(options?: AsyncEventQueueOptions<T>);
+    /** True once this queue has dropped at least one entry. */
+    get truncated(): boolean;
     push(value: T): void;
     close(): void;
+    /**
+     * Drop the oldest entries back down to the bound. The marker is queue
+     * metadata, not a buffered entry: every subscriber observes it at most once
+     * after the first drop, while all retained capacity remains available to
+     * real events.
+     */
+    private enforceBound;
     private wake;
     private waitForMore;
     /** Async-iterate the buffer from index 0, waiting for new pushes until closed. */

package/dist/index.d.ts

@@ -1,65 +1,85 @@
-import type { Server as HttpServer } from 'node:http';
-import type { Hono } from 'hono';
-import { type TenantId } from './auth';
-import { type PairingCodeClaims, type PairingCodeInfo } from './pairing';
+import { Hono } from 'hono';
+import { type PairingCodeInfo } from '@byok-sdk/cloud';
+import { type AgentRef } from '@byok-sdk/protocol';
+import type { MailboxRetentionInput, MailboxRetentionResult } from '@byok-sdk/core';
 import type { ByokServerEvent, AgentContentReadRequest, AgentHomeProjectionRequest, AgentHomeProjectionStatusReadback, AgentEgressReceipt, CreateByokServerOptions, DispatchInput, FreshAgentEgressDispatchInput, HubStats, MachineInfo, TaskHandle, TaskSnapshot } from './types';
-export type { ByokServerEvent, AgentContentReadRequest, AgentHomeProjectionRequest, AgentHomeProjectionStatusReadback, AgentEgressReceipt, CreateByokServerOptions, DispatchInput, FreshAgentEgressDispatchInput, HubStats, MachineInfo, ServerTaskEvent, TaskHandle, TaskResult, TaskSnapshot, } from './types';
-export type { CreateTaskInput, TaskRecord, TaskStore } from './task-store';
-export { IllegalTaskTransitionError, InMemoryTaskStore } from './task-store';
+export type { ByokServerEvent, AgentContentReadRequest, AgentHomeProjectionRequest, AgentHomeProjectionStatusReadback, AgentEgressReceipt, ByokServerStorage, CreateByokServerOptions, DispatchInput, FreshAgentEgressDispatchInput, HubStats, MachineInfo, ServerTaskEvent, TaskHandle, TaskResult, TaskSnapshot, } from './types';
 /**
- * M5 (approval targeting, docs/protocol.md §5.3): previously unreachable via
- * this package's public entry point (only importable from the internal
- * `./hub` path) — `TaskHandle.approve`/`reject`'s `opts.approvalId` targeting
- * (`types.ts`) throws this, so a caller needs it exported here to
- * `instanceof`-check/inspect it. See `hub.ts`'s own doc comment for the full
- * staleness semantics.
+ * M5 (approval targeting, docs/protocol.md §5.3): `TaskHandle.approve`/`reject`'s
+ * `opts.approvalId` targeting throws this when the id names an approval the
+ * task has already superseded, so a caller needs it to `instanceof`-check and
+ * inspect the two ids. Re-exported from `@byok-sdk/cloud`, which owns the gate
+ * both the embedded and the hosted surface are decided by — one class, one
+ * `instanceof` that works across both.
  */
-export { StaleApprovalError } from './hub';
+export { StaleApprovalError } from '@byok-sdk/cloud';
 /**
- * S0 (GAP-002): `TaskHandle.steer` (`types.ts`) throws this when the runtime
- * that claimed the task cannot be steered, when the task isn't running, or
- * when it's already terminal — a caller needs the class to `instanceof`-check
- * it and the code union to switch on. See `hub.ts`'s own doc comments for the
- * full gate order and the fail-closed-on-unknown rationale.
+ * S0 (GAP-002): `TaskHandle.steer` throws this when the runtime that claimed
+ * the task cannot be steered, when the task isn't running, or when it's already
+ * terminal. The GATE is the kernel's — it reads the claim-time capability
+ * snapshot and nothing else — and so is the `code`. The CLASS is this
+ * package's, because it carries `state: TaskState`, the wire vocabulary this
+ * surface speaks and the kernel deliberately has no field for. See
+ * `task-handle.ts` for the full reasoning and for why `SteerRejectionCode` and
+ * {@link StaleApprovalError} stay kernel re-exports.
  */
-export { SteerRejectedError } from './hub';
-export type { SteerRejectionCode } from './hub';
-export { AgentHomeProjectionCompletionError } from './hub';
-export type { AgentHomeProjectionCompletionErrorCode } from './hub';
-export { PairingCodeInvalidError } from './pairing';
-export type { PairingCodeClaims, PairingCodeInfo } from './pairing';
-export type { AccessTokenClaims, AuthenticatedDevice, DeviceRecord, TenantId, TokenSigner, } from './auth';
+export { SteerRejectedError } from './task-handle';
+export type { SteerRejectionCode } from '@byok-sdk/cloud';
 /**
- * S1: `DeviceRegistry` itself is deliberately NOT exported. Its
- * tenant-scoped surface is reachable through `ByokServer.devices` (below),
- * and the one method that resolves a device without a tenant in scope
- * (`resolveByDeviceId`, for the two pre-tenant wire endpoints) exists only
- * inside this package — exporting the class would hand every embedder a
- * cross-tenant device oracle for free.
+ * Auth v2 types an embedder needs to talk about devices and tokens. All owned
+ * by `@byok-sdk/cloud` now — this package no longer has an auth plane of its
+ * own to keep in agreement with one.
  */
-export { createHmacTokenSigner } from './auth';
-export type { BlobStore, CreateUploadInput, ReadContentResult, WriteContentResult, } from './blob-store';
-export { LocalDiskBlobStore } from './blob-store';
-export type { SqliteTaskStoreOptions } from './sqlite-task-store';
-export { SqliteTaskStore } from './sqlite-task-store';
-export type { SqliteBlobStoreOptions } from './sqlite-blob-store';
-export { SqliteBlobStore } from './sqlite-blob-store';
+export type { AccessTokenClaims, DeviceRecord, PairingCodeInfo, TenantId, TokenSigner } from '@byok-sdk/cloud';
+export { createHmacTokenSigner } from '@byok-sdk/cloud';
+/** Cutoffs and result of {@link ByokServer.mailbox.collectRetired}, owned by `@byok-sdk/core`. */
+export type { MailboxRetentionInput, MailboxRetentionResult } from '@byok-sdk/core';
 export { SqliteUnavailableError } from './sqlite-support';
 export type { RateLimiterOptions } from './rate-limiter';
+export { DEFAULT_TASK_EVENT_BUFFER_LIMIT, DEFAULT_TASK_EVENT_RETENTION_MS } from './relay';
+/** Page size `tasks.list()` uses when the caller names none. */
+export declare const DEFAULT_TASK_PAGE_LIMIT = 100;
+/** Input to {@link ByokServer.pairing.createPairingCode}. */
+export interface CreatePairingCodeInput {
+    /**
+     * The product the redeeming device pairs into. Must be this instance's own
+     * `productId`: an embedded server serves exactly one product, and a code for
+     * some other product would mint a device every bearer-authed route then
+     * refuses (`instanceProductId`, `@byok-sdk/cloud`). Fail closed rather than
+     * silently issuing an unusable code.
+     *
+     * The TENANT is not a parameter: it is derived from `productId` once, at
+     * construction (`serverTenantId`, `stores.ts`), because this surface has no
+     * second tenant to name.
+     */
+    readonly productId: string;
+    /** Overrides the default single-use code lifetime. */
+    readonly ttlMs?: number;
+}
+/** One bounded page of this server's tasks. */
+export interface TaskPage {
+    readonly tasks: readonly TaskSnapshot[];
+    /**
+     * Pass as the next call's `cursor`. ABSENT means the walk is over — a caller
+     * stops on absence, not on an empty page, so a page that exactly fills
+     * `limit` with nothing after it still terminates.
+     */
+    readonly nextCursor?: string;
+}
+/** Query for {@link ByokServer.tasks.list}. */
+export interface TaskListQuery {
+    /** Maximum snapshots in the page. Defaults to {@link DEFAULT_TASK_PAGE_LIMIT}. */
+    readonly limit?: number;
+    /** The `nextCursor` from the previous page; absent starts at the beginning. */
+    readonly cursor?: string;
+}
 /** The object `createByokServer` returns — the SaaS-embedder-facing surface. */
 export interface ByokServer {
-    /** Hono app exposing the pair/challenge/token/blob/events HTTP routes. Mount it, or use its `.fetch` with `@hono/node-server`. */
+    /** Hono app exposing every device route, plus the opt-in `/healthz`. Mount it, or use its `.fetch` with `@hono/node-server`. */
     hono: Hono;
-    /** Wire up the `GET /byok/ws` upgrade on the raw Node HTTP server serving `hono`. */
-    attachWebSocket(server: HttpServer): void;
     pairing: {
-        /**
-         * S1: minting a code REQUIRES the tenant and product the redeeming
-         * device will be paired into (docs/protocol.md §6.1) — the SaaS's own
-         * auth/device-flow UI is the only party that knows them, and the device
-         * never gets to name its own. There is no claimless overload.
-         */
-        createPairingCode(claims: PairingCodeClaims): PairingCodeInfo;
+        /** Mint a single-use pairing code for this server's product and tenant (docs/protocol.md §6.1). */
+        createPairingCode(input: CreatePairingCodeInput): Promise<PairingCodeInfo>;
     };
     dispatch(input: DispatchInput): Promise<TaskHandle>;
     /** Dispatch a fresh Agent execution whose runtime will mint its session after start. */
@@ -68,18 +88,28 @@ export interface ByokServer {
     requestAgentContentRead(input: AgentContentReadRequest): Promise<void>;
     /** Enqueue one task-free, exact-device Agent-home projection. */
     enqueueAgentHomeProjection(input: AgentHomeProjectionRequest): Promise<AgentHomeProjectionStatusReadback>;
-    /** Reference-only in-process status readback; production durability belongs to @byok-sdk/cloud stores. */
-    readAgentHomeProjection(deviceId: string, requestId: string): AgentHomeProjectionStatusReadback | undefined;
+    /** Durable desired-state and terminal-outcome readback for one exact device-and-Agent request. */
+    readAgentHomeProjection(deviceId: string, agentRef: AgentRef, requestId: string): Promise<AgentHomeProjectionStatusReadback | undefined>;
     tasks: {
-        get(taskId: string): TaskSnapshot | undefined;
-        list(): TaskSnapshot[];
+        get(taskId: string): Promise<TaskSnapshot | undefined>;
+        /**
+         * One bounded page, keyset-paged by task id. Paged rather than "all of
+         * them" because the underlying store is: an unbounded `list()` would have
+         * to walk every page internally and hand back a snapshot that was never
+         * consistent at any single instant.
+         */
+        list(query?: TaskListQuery): Promise<TaskPage>;
+    };
+    /** Trusted embedder access to committed blob download grants. */
+    blobs: {
+        getDownloadUrl(blobId: string): Promise<string | undefined>;
     };
-    /** Reference-server reliable egress receipt readback. */
+    /** Reliable Agent egress receipt readback. */
     egress: {
-        get(deviceId: string, eventId: string): AgentEgressReceipt | undefined;
+        get(deviceId: string, agentRef: AgentRef, eventId: string): Promise<AgentEgressReceipt | undefined>;
     };
     machines: {
-        list(): MachineInfo[];
+        list(): Promise<MachineInfo[]>;
     };
     events: {
         subscribe(): AsyncIterable<ByokServerEvent>;
@@ -87,48 +117,85 @@ export interface ByokServer {
     /**
      * Device revocation (§6.3) — server-side only, no wire message. Revoking a
      * device DELETES its registration, so its next `/byok/challenge`,
-     * `/byok/token`, WSS connect, or authed HTTP call gets a 401 — the same
-     * answer as for a device id that was never registered — and its only
-     * recourse is to re-run `/byok/pair`. The device-scoped state the row
-     * owned (outstanding challenge nonces, presence, inbound dedup) is deleted
-     * with it; what the device DID (tasks, receipts) is history and survives.
+     * `/byok/token`, or authed HTTP call gets a 401 — the same answer as for a
+     * device id that was never registered — and its only recourse is to re-run
+     * `/byok/pair`. The device-scoped state the row owned (outstanding challenge
+     * nonces, presence, inbound dedup) is deleted with it; what the device DID
+     * (tasks, receipts) is history and survives.
      *
-     * S1: tenant-first, and a tenant can only revoke a device it owns — a
-     * `(tenantId, deviceId)` pair belonging to someone else resolves to
-     * nothing and this is a silent no-op rather than a cross-tenant write.
+     * DEVICE-ID ONLY. The hosted control plane's own revocation is tenant-first
+     * (a tenant may only revoke a device it owns), but an embedded server owns
+     * exactly ONE tenant and binds it here itself: `TenantId` is a branded type an
+     * embedder cannot mint, and nothing on this surface — `ByokServer`,
+     * `MachineInfo`, `PairingCodeInfo` — hands one back, so a tenant-first
+     * parameter would make this method uncallable from outside the package rather
+     * than safer. The scoping it provided is unchanged, just not the caller's to
+     * state: a device id this server does not know resolves to nothing and is a
+     * silent no-op.
      */
     devices: {
-        revoke(tenantId: TenantId, deviceId: string): void;
+        revoke(deviceId: string): Promise<void>;
     };
     /**
-     * Stop background timers owned by this server instance — currently just
-     * the task-lease reaper (`ConnectionHub.stopLeaseReaper`, `hub.ts`). Call
-     * this on shutdown so nothing keeps the process alive or leaks a handle in
-     * tests; safe to call more than once.
+     * Mailbox retention for this server's tenant — the host control-plane
+     * operation core defines (`MailboxStore.collectRetired`), forwarded verbatim.
+     *
+     * A pass-through, deliberately, and NOT a retention policy: the caller names
+     * both cutoffs, so this package invents no TTL, runs no timer, and holds no
+     * second opinion about when a device's undelivered work is declared lost.
+     * Nothing in `@byok-sdk/core`, `@byok-sdk/cloud` or this façade drives the
+     * sweep on its own, which is exactly why an embedder needs a way to reach it:
+     * without one, an embedded server retires nothing, ever, and the
+     * `cursor_too_old` floor can never move.
+     *
+     * Acked rows appended before `ackedBefore` are DELETED; unacked rows appended
+     * before `expireUnackedBefore` are dead-lettered as `expired` and stay
+     * visible, which is what moves `recoverableFrom` and turns a device polling
+     * from a lost cursor into a `409 cursor_too_old` resync instead of a silently
+     * short page. Both cutoffs must be canonical ISO-8601 UTC.
+     */
+    mailbox: {
+        collectRetired(input: MailboxRetentionInput): Promise<MailboxRetentionResult>;
+    };
+    /**
+     * Release what this instance holds: the relay's per-task feeds and their
+     * reclamation timers, and the connection observations. Call it on shutdown so
+     * nothing keeps the process alive or leaks a handle in tests; safe to call
+     * more than once. SQLite embedders that need to await handle release should
+     * call {@link ByokServer.close} instead.
      */
     stop(): void;
+    /** Drain pending store calls and release the selected storage authority. */
+    close(): Promise<void>;
     /**
-     * M4 Phase 4 (part B.1): a plain, serializable in-process snapshot of this
-     * hub's current state — connected device count, task counts by state,
-     * envelope in/out totals, dedup drops, rate-limit events, and uptime. See
-     * {@link HubStats} for the full contract. Deliberately in-process only —
-     * never exposed over HTTP by this SDK itself (see
-     * `CreateByokServerOptions.healthzRoute`'s doc comment); an embedder that
-     * wants any of this surfaced remotely builds its own authenticated route
-     * around this method.
+     * A plain, serializable snapshot of this server's current state. See
+     * {@link HubStats} for the field-by-field contract.
+     *
+     * Async because `taskCountsByState` is COMPUTED from the durable task store
+     * on every call rather than mirrored into a counter this package would then
+     * have to keep in agreement with it — that mirror was the second task
+     * authority the fold exists to remove. Deliberately in-process only: never
+     * exposed over HTTP by this SDK itself (see
+     * `CreateByokServerOptions.healthzRoute`); an embedder that wants any of it
+     * surfaced remotely builds its own authenticated route around this method.
      */
-    stats(): HubStats;
+    stats(): Promise<HubStats>;
 }
 /**
- * In-memory reference implementation of the SaaS-side coordinator: Auth v2
- * device pairing/renewal/revocation, a WS + long-poll connection hub with
- * at-least-once redelivery, a local-disk blob store, and task dispatch/
- * lifecycle tracking. See the per-module doc comments (`auth.ts`,
- * `blob-store.ts`, `hub.ts`, `pairing.ts`, `ws-server.ts`) for what's a
- * pinned wire/HTTP contract (docs/protocol.md) versus a reference-impl
- * choice a SaaS embedder might swap out (`tokenSigner`, `blobStore`,
- * `taskStore` — the latter two default to in-memory/local-disk and lose all
- * state on restart; see `sqlite-task-store.ts`/`sqlite-blob-store.ts` for
- * persistent M3 alternatives implementing the same interfaces).
+ * Embedded reference coordinator: a thin façade over `@byok-sdk/cloud`'s
+ * kernel, composed against the explicitly selected embedded stores.
+ *
+ * What that means concretely — and it is the whole point of WP3B — is that this
+ * package owns NO coordination semantics any more. Pairing, tokens, the inbound
+ * gate, task ownership, first-terminal-wins, approvals, steering, cancellation,
+ * long-poll redelivery and the `cursor_too_old` floor are all the kernel's, and
+ * a device cannot tell this from a hosted deployment. What is left here is the
+ * embedded shape: one product, one tenant, a `TaskHandle` for hosts that want
+ * one, an in-process notification relay, and the observability an embedder used
+ * to get from the hub.
+ *
+ * State is in-memory by default. Explicit SQLite mode persists the six
+ * coordination interfaces whose contracts cross a process restart; all other
+ * ports remain process-local.
  */
 export declare function createByokServer(opts: CreateByokServerOptions): ByokServer;