@byok-sdk/server 0.15.0 → 0.17.0

package/README.md

@@ -26,3 +26,80 @@ inventory contains every required ID. `machines.list()` projects that same
 logical-ID-only inventory; MCP commands and credentials remain device-local.
 
 MIT licensed. Node.js 22.22.0 or newer.
+
+## SQLite enrollment, receipts and schema adoption
+
+`storage: { kind: 'sqlite', path }` persists device enrollment, authenticated
+capabilities, request receipts and the six coordination interfaces. Pairing and
+authentication share the device directory. Receipt keys are tenant scoped and
+first-write-wins across connections and restart. Mailbox retention never deletes
+receipts: immutable offer, delivered and canonical terminal facts remain for the
+lifetime of the database. There is no receipt TTL or automatic pruning. Monitor
+disk usage; exhaustion is an error, not permission to delete identity fences.
+
+Unredeemed pairing codes, presence and other unmodified ports remain ephemeral.
+Keep daemon OS credentials, server URL and token signer stable across restart.
+This does not restore TaskHandle promises, subscriptions or provider processes.
+
+This candidate writes schema v3. Stop **all** writers and take a consistent
+SQLite backup (including WAL state or using SQLite's backup facility) before
+explicit adoption. An already-open old writer is not stopped by the version
+fence. Only legacy databases with no task, mailbox-message, agent-admission or
+advanced cursor history can migrate: old in-memory receipts cannot be recovered
+from task status or fabricated from a retry payload. A pristine poll cursor is
+allowed. Preserve rejected databases for separate reconciliation; do not delete
+history, reset cursors or edit version markers to make adoption pass.
+
+```ts
+const server = createByokServer({
+  productId,
+  tokenSigner,
+  storage: { kind: 'sqlite', path, migration: 'v2-to-v3' },
+});
+await server.close();
+```
+
+Use `v1-to-v3` for a v1 database meeting the same eligibility rules. Remove
+`migration` from normal startup. Adoption adds receipts, adds an empty device
+directory for v1, and updates the marker atomically; any failure rolls back.
+Existing v2 devices and artifacts remain. V1 enrollment was in-memory and needs
+explicit pairing. Unknown versions, missing authorities and malformed receipt
+columns/primary key fail closed. Broader validation of legacy table constraints
+is a separate tracked concern.
+
+**Breaking storage boundary:** published 0.16 (schema v1) and earlier schema-v2
+candidate writers refuse v3. The previous unpublished `v1-to-v2` selector is
+replaced, without a compatibility alias. Restore of a backup requires a separate
+recovery procedure because it can lose new state or restore old grants. This
+belongs to the next MINOR release; these local changes are not a published upgrade.
+
+
+## Persistent host request identity
+
+Before enqueue, durably bind the authenticated scope and external execution key
+(including cycle/pass where applicable) to one taskId, explicit deviceId and
+immutable dispatch input. Pass that taskId to `dispatch` or
+`dispatchFreshAgentEgress`. Omitting taskId retains fresh-task semantics.
+A caller taskId requires an explicit device; the façade never reselects an
+ambient device for that identity. Initial dispatch still requires a connected
+device. Concurrent calls for one caller identity in one façade are rejected
+while the first is in flight.
+
+After restart use `tasks.offer(taskId)` to read the kernel's immutable executable
+offer and delivered marker, and `tasks.get(taskId)` for its state and result.
+These reads work offline. Duplicate dispatch can still throw a kernel conflict:
+only treat it as recovery after matching the original scope/target/type/payload
+and durable delivery. Missing or mismatched readback is not success. A false
+delivered marker does not prove mailbox append never happened. `tasks.offer`
+returns no invented transport sequence or reconstructed TaskHandle. Host-only
+agentMessageContext is not part of this executable-offer projection; callers
+must preserve its original binding and its separate consumer authority.
+
+`await server.tasks.cancel(taskId, reason)` uses the same kernel cancellation
+and relay notification as a live handle; it does not require a connected device.
+Missing tasks reject. A host must separately persist cancellation intent if it
+can crash before this call, and prevent dispatch of a cancelled prepared request.
+
+The runnable public-package fixture is
+`docs/researches/2026-09-09-g1c-facade/public-consumer-probe.mjs`. It demonstrates
+pre-enqueue binding and recovery, not product authentication or consumer ACK.

package/dist/index.d.ts

@@ -4,6 +4,7 @@ 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, ByokServerStorage, CreateByokServerOptions, DispatchInput, FreshAgentEgressDispatchInput, HubStats, MachineInfo, ServerTaskEvent, TaskHandle, TaskResult, TaskSnapshot, } from './types';
+export type { TaskOfferReadback } from '@byok-sdk/cloud';
 /**
  * M5 (approval targeting, docs/protocol.md §5.3): `TaskHandle.approve`/`reject`'s
  * `opts.approvalId` targeting throws this when the id names an approval the
@@ -92,6 +93,10 @@ export interface ByokServer {
     readAgentHomeProjection(deviceId: string, agentRef: AgentRef, requestId: string): Promise<AgentHomeProjectionStatusReadback | undefined>;
     tasks: {
         get(taskId: string): Promise<TaskSnapshot | undefined>;
+        /** Immutable kernel offer readback for verifying a persisted host binding. No transport seq is inferred. */
+        offer(taskId: string): Promise<import('@byok-sdk/cloud').TaskOfferReadback | undefined>;
+        /** Request cancellation through the kernel without a process-owned TaskHandle. */
+        cancel(taskId: string, reason?: string): Promise<void>;
         /**
          * One bounded page, keyset-paged by task id. Paged rather than "all of
          * them" because the underlying store is: an unbounded `list()` would have
@@ -194,7 +199,7 @@ export interface ByokServer {
  * 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
+ * State is in-memory by default. Explicit SQLite mode persists request receipts, the device directory and six
  * coordination interfaces whose contracts cross a process restart; all other
  * ports remain process-local.
  */

package/dist/index.js

@@ -1,8 +1,8 @@
 import { Hono } from 'hono';
-import { createHmacTokenSigner, createByokCloud, fullCapabilityDeclaration, agentHomeProjectionRequestKey, pendingApproval, createWebCrypto, createInMemoryCloudStores, SteerRejectedError as SteerRejectedError$1, assertTaskAttemptListLimit } from '@byok-sdk/cloud';
+import { createHmacTokenSigner, createByokCloud, fullCapabilityDeclaration, agentHomeProjectionRequestKey, pendingApproval, createWebCrypto, createInMemoryCloudStores, SteerRejectedError as SteerRejectedError$1, InMemoryPairingCodeStore, assertTaskAttemptListLimit } from '@byok-sdk/cloud';
 export { StaleApprovalError, createHmacTokenSigner } from '@byok-sdk/cloud';
-import { TASK_STATES, AgentHomeProjectionPayloadSchema, AgentContentReadPayloadSchema, AgentRefSchema, AgentEgressPolicySchema, AgentMessageEgressRequirementSchema, TerminalProjectionSelectionSchema, AgentMessageServerContextSchema, DispatchSelectionSchema, RequiredToolsetsSchema, STRICT_AGENT_ONLY_CAPABILITY, byokBlobContentPath } from '@byok-sdk/protocol';
-import { tenantId, createInMemoryCoreStores, InMemoryQuotaStore, ByokCoreError, assertCanonicalTimestamp, isLegalObjectTransition, CoreConflictError } from '@byok-sdk/core';
+import { TASK_STATES, AgentHomeProjectionPayloadSchema, AgentContentReadPayloadSchema, AgentRefSchema, AgentEgressPolicySchema, AgentMessageEgressRequirementSchema, TerminalProjectionSelectionSchema, AgentMessageServerContextSchema, DispatchSelectionSchema, RequiredToolsetsSchema, STRICT_AGENT_ONLY_CAPABILITY, byokBlobContentPath, HarnessInventorySchema } from '@byok-sdk/protocol';
+import { tenantId, createInMemoryCoreStores, InMemoryQuotaStore, ByokCoreError, assertCanonicalTimestamp, isLegalObjectTransition, CoreConflictError, PRESENCE_LEVELS } from '@byok-sdk/core';
 import { mkdirSync, existsSync, chmodSync } from 'fs';
 import { createRequire } from 'module';
 import { dirname } from 'path';
@@ -712,13 +712,183 @@ function secureSqliteFilePermissions(dbPath) {
     }
   }
 }
+var DEVICE_SCHEMA = `
+CREATE TABLE device_directory (
+  tenant_id TEXT NOT NULL,
+  device_id TEXT NOT NULL UNIQUE,
+  product_id TEXT NOT NULL,
+  machine_id TEXT,
+  device_name TEXT NOT NULL,
+  device_public_key TEXT NOT NULL,
+  proof_key_id TEXT NOT NULL,
+  proof_key_epoch INTEGER NOT NULL CHECK (proof_key_epoch >= 0),
+  capabilities_json TEXT,
+  harnesses_json TEXT,
+  PRIMARY KEY (tenant_id, device_id)
+);
+CREATE UNIQUE INDEX device_directory_machine
+  ON device_directory (tenant_id, product_id, machine_id) WHERE machine_id IS NOT NULL;
+`;
+function requiredString(row, field) {
+  const value = row[field];
+  if (typeof value !== "string" || value.length === 0) throw new Error(`Invalid SQLite device ${field}`);
+  return value;
+}
+function capabilities(value) {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error("Invalid SQLite device capabilities");
+  }
+  return Object.freeze([...value]);
+}
+function fromRow(row) {
+  const epoch = row.proof_key_epoch;
+  if (typeof epoch !== "number" || !Number.isSafeInteger(epoch) || epoch < 0) {
+    throw new Error("Invalid SQLite device proof_key_epoch");
+  }
+  return {
+    tenantId: requiredString(row, "tenant_id"),
+    deviceId: requiredString(row, "device_id"),
+    productId: requiredString(row, "product_id"),
+    deviceName: requiredString(row, "device_name"),
+    devicePublicKey: requiredString(row, "device_public_key"),
+    proofKeyId: requiredString(row, "proof_key_id"),
+    proofKeyEpoch: epoch,
+    revoked: false,
+    ...row.machine_id === null ? {} : { machineId: requiredString(row, "machine_id") },
+    ...row.capabilities_json === null ? {} : {
+      capabilities: capabilities(JSON.parse(requiredString(row, "capabilities_json")))
+    },
+    ...row.harnesses_json === null ? {} : {
+      harnesses: HarnessInventorySchema.parse(JSON.parse(requiredString(row, "harnesses_json")))
+    }
+  };
+}
+var SqliteDeviceDirectory = class {
+  constructor(coordinator) {
+    this.coordinator = coordinator;
+  }
+  coordinator;
+  register(tenant, input) {
+    return this.coordinator.transaction((db) => {
+      const owner = db.prepare("SELECT tenant_id FROM device_directory WHERE device_id = ?").get(input.deviceId);
+      if (owner !== void 0 && owner.tenant_id !== tenant) throw new Error("Device ID already belongs to another tenant");
+      if (input.machineId !== void 0) {
+        db.prepare("DELETE FROM device_directory WHERE tenant_id = ? AND product_id = ? AND machine_id = ? AND device_id <> ?").run(tenant, input.productId, input.machineId, input.deviceId);
+      }
+      db.prepare(`INSERT INTO device_directory
+        (tenant_id, device_id, product_id, machine_id, device_name, device_public_key, proof_key_id, proof_key_epoch)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (tenant_id, device_id) DO UPDATE SET
+          product_id = excluded.product_id, machine_id = excluded.machine_id,
+          device_name = excluded.device_name, device_public_key = excluded.device_public_key,
+          proof_key_id = excluded.proof_key_id, proof_key_epoch = excluded.proof_key_epoch,
+          capabilities_json = NULL, harnesses_json = NULL`).run(
+        tenant,
+        input.deviceId,
+        input.productId,
+        input.machineId ?? null,
+        input.deviceName,
+        input.devicePublicKey,
+        input.proofKeyId,
+        input.proofKeyEpoch
+      );
+      return fromRow(db.prepare("SELECT * FROM device_directory WHERE tenant_id = ? AND device_id = ?").get(tenant, input.deviceId));
+    });
+  }
+  get(tenant, deviceId) {
+    return this.coordinator.run((db) => {
+      const row = db.prepare("SELECT * FROM device_directory WHERE tenant_id = ? AND device_id = ?").get(tenant, deviceId);
+      return row === void 0 ? void 0 : fromRow(row);
+    });
+  }
+  revoke(tenant, deviceId) {
+    return this.coordinator.run((db) => {
+      db.prepare("DELETE FROM device_directory WHERE tenant_id = ? AND device_id = ?").run(tenant, deviceId);
+    });
+  }
+  list(tenant) {
+    return this.coordinator.run((db) => db.prepare("SELECT * FROM device_directory WHERE tenant_id = ? ORDER BY device_id").all(tenant).map(fromRow));
+  }
+  resolveByDeviceId(deviceId) {
+    return this.coordinator.run((db) => {
+      const row = db.prepare("SELECT * FROM device_directory WHERE device_id = ?").get(deviceId);
+      return row === void 0 ? void 0 : fromRow(row);
+    });
+  }
+  recordCapabilities(tenant, input) {
+    return this.coordinator.transaction((db) => {
+      const row = db.prepare("SELECT * FROM device_directory WHERE tenant_id = ? AND device_id = ?").get(tenant, input.deviceId);
+      if (row === void 0) return void 0;
+      fromRow(row);
+      const declaredCapabilities = capabilities(input.capabilities);
+      const harnesses = HarnessInventorySchema.parse(input.harnesses ?? []);
+      db.prepare("UPDATE device_directory SET capabilities_json = ?, harnesses_json = ? WHERE tenant_id = ? AND device_id = ?").run(JSON.stringify(declaredCapabilities), JSON.stringify(harnesses), tenant, input.deviceId);
+      return fromRow(db.prepare("SELECT * FROM device_directory WHERE tenant_id = ? AND device_id = ?").get(tenant, input.deviceId));
+    });
+  }
+  async readiness(tenant, presence) {
+    const devices = await this.list(tenant);
+    const livePresence = await presence.list(tenant);
+    const presenceByDevice = new Map(livePresence.map((hint) => [hint.deviceId, hint]));
+    const activeDeviceIds = new Set(
+      devices.filter((device) => !device.revoked).map((device) => device.deviceId)
+    );
+    const observedPresenceByLevel = Object.fromEntries(
+      PRESENCE_LEVELS.map((level) => [level, 0])
+    );
+    for (const hint of livePresence) {
+      if (!activeDeviceIds.has(hint.deviceId)) continue;
+      observedPresenceByLevel[hint.level] += 1;
+    }
+    return {
+      tenantId: tenant,
+      activePairedDeviceCount: devices.filter((device) => !device.revoked).length,
+      revokedDeviceCount: devices.filter((device) => device.revoked).length,
+      observedPresenceCount: Object.values(observedPresenceByLevel).reduce(
+        (total, count) => total + count,
+        0
+      ),
+      observedPresenceByLevel,
+      devices: [...devices].sort((left, right) => left.deviceId.localeCompare(right.deviceId)).map((device) => {
+        const hint = device.revoked ? void 0 : presenceByDevice.get(device.deviceId);
+        return {
+          deviceId: device.deviceId,
+          productId: device.productId,
+          deviceName: device.deviceName,
+          revoked: device.revoked,
+          ...hint === void 0 ? {} : {
+            presence: {
+              level: hint.level,
+              ...hint.detail === void 0 ? {} : { detail: hint.detail },
+              ...hint.configuredToolsets === void 0 ? {} : { configuredToolsets: hint.configuredToolsets },
+              ...hint.clientVersion === void 0 ? {} : { clientVersion: hint.clientVersion },
+              ...hint.protocolVersions === void 0 ? {} : { protocolVersions: hint.protocolVersions },
+              ...hint.runtimes === void 0 ? {} : { runtimes: hint.runtimes },
+              observedAt: hint.observedAt,
+              expiresAt: hint.expiresAt
+            }
+          }
+        };
+      })
+    };
+  }
+};
 
 // src/stores/sqlite/index.ts
 var DEFAULT_MAILBOX_READ_LIMIT = 50;
 var DEFAULT_OBJECT_LIST_LIMIT = 100;
 var DEFAULT_BLOB_URL_TTL_MS = 15 * 6e4;
 var SIGNING_SECRET_BYTES = 32;
-var SQLITE_SCHEMA_VERSION = "1";
+var SQLITE_SCHEMA_VERSION = "3";
+var RECEIPT_SCHEMA = `
+CREATE TABLE request_receipt (
+  tenant_id TEXT NOT NULL,
+  key TEXT NOT NULL,
+  body TEXT NOT NULL,
+  recorded_at TEXT NOT NULL,
+  PRIMARY KEY (tenant_id, key)
+);
+`;
 var SCHEMA = `
 CREATE TABLE IF NOT EXISTS byok_sqlite_meta (
   key TEXT PRIMARY KEY,
@@ -807,21 +977,68 @@ var SqliteCoordinator = class {
   #tail = Promise.resolve();
   #closing = false;
   #closePromise;
-  constructor(path) {
+  constructor(path, migration) {
     this.db = openSqliteDatabase(path);
     try {
-      const hasMetadata = this.db.prepare("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = 'byok_sqlite_meta'").get();
-      if (hasMetadata !== void 0) {
-        const schemaVersion = this.db.prepare("SELECT value FROM byok_sqlite_meta WHERE key = 'schema_version'").get();
-        if (schemaVersion?.value !== SQLITE_SCHEMA_VERSION) {
-          throw new Error(
-            `Unsupported BYOK SQLite schema version ${JSON.stringify(schemaVersion?.value)}; this build requires ${SQLITE_SCHEMA_VERSION}`
-          );
+      this.db.exec("BEGIN IMMEDIATE");
+      try {
+        const hasMetadata = this.db.prepare("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = 'byok_sqlite_meta'").get();
+        if (hasMetadata !== void 0) {
+          const version = this.db.prepare("SELECT value FROM byok_sqlite_meta WHERE key = 'schema_version'").get();
+          if (version?.value !== SQLITE_SCHEMA_VERSION && !(version?.value === "1" && migration === "v1-to-v3" || version?.value === "2" && migration === "v2-to-v3")) {
+            throw new Error(`Unsupported BYOK SQLite schema version ${JSON.stringify(version?.value)}; this build requires ${SQLITE_SCHEMA_VERSION}. Stop all writers, back up the database and explicitly select migration: 'v1-to-v3' or 'v2-to-v3' for a receipt-free legacy database without task history.`);
+          }
+          for (const projection of [
+            "tenant_id, device_id, next_seq, delivered_seq, acked_seq, updated_at FROM mailbox_cursor",
+            "tenant_id, device_id, seq, message_id, body, body_hash, byte_size, state, appended_at FROM mailbox_message",
+            "tenant_id, task_id, device_id, agent_ref_json, owner_device_id, claimed_runtime, claimed_runtime_capabilities_json, status, terminal_cause, cancellation_requested_at, cancellation_reason, cancellation_message_id, updated_at FROM task_attempt",
+            "tenant_id, task_id, message_id, payload_body, terminal_body FROM agent_message_admission",
+            "tenant_id, hash, byte_size, content_type, state, created_at, updated_at, delete_pending_at FROM object_manifest",
+            "tenant_id, hash, ref_kind, ref_id, created_at FROM object_reference",
+            "blob_id, tenant_id, reservation_id, content_hash, byte_size, content_type, uploaded, data FROM blob"
+          ]) {
+            this.db.prepare(`SELECT ${projection} LIMIT 0`);
+          }
+          if (version?.value !== SQLITE_SCHEMA_VERSION) {
+            for (const table of ["task_attempt", "mailbox_message", "agent_message_admission"]) {
+              if (this.db.prepare(`SELECT 1 FROM ${table} LIMIT 1`).get() !== void 0) {
+                throw new Error("Cannot migrate BYOK SQLite database with task history: historical receipts are unavailable; preserve this database for reconciliation");
+              }
+            }
+            if (this.db.prepare("SELECT 1 FROM mailbox_cursor WHERE next_seq <> 1 OR delivered_seq <> 0 OR acked_seq <> 0 LIMIT 1").get() !== void 0) {
+              throw new Error("Cannot migrate BYOK SQLite database with delivery history: historical receipts are unavailable; preserve this database for reconciliation");
+            }
+            if (this.db.prepare("SELECT 1 FROM sqlite_master WHERE name = 'request_receipt'").get() !== void 0) {
+              throw new Error("Unexpected request receipt authority in legacy BYOK SQLite schema");
+            }
+            this.db.exec(RECEIPT_SCHEMA);
+          }
+          if (version?.value === "1") {
+            const unexpected = this.db.prepare("SELECT 1 FROM sqlite_master WHERE name = 'device_directory'").get();
+            if (unexpected !== void 0) throw new Error("Unexpected device directory in BYOK SQLite schema v1");
+            this.db.exec(DEVICE_SCHEMA);
+          }
+          if (version?.value !== SQLITE_SCHEMA_VERSION) {
+            this.db.prepare("UPDATE byok_sqlite_meta SET value = ? WHERE key = 'schema_version'").run(SQLITE_SCHEMA_VERSION);
+          }
+        } else {
+          const existing = this.db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").get();
+          if (existing !== void 0) throw new Error("Existing SQLite database has no BYOK schema metadata");
+          this.db.exec(SCHEMA);
+          this.db.exec(RECEIPT_SCHEMA);
+          this.db.exec(DEVICE_SCHEMA);
+          this.db.prepare("INSERT INTO byok_sqlite_meta (key, value) VALUES ('schema_version', ?)").run(SQLITE_SCHEMA_VERSION);
         }
-      }
-      this.db.exec(SCHEMA);
-      if (hasMetadata === void 0) {
-        this.db.prepare("INSERT INTO byok_sqlite_meta (key, value) VALUES ('schema_version', ?)").run(SQLITE_SCHEMA_VERSION);
+        this.db.prepare("SELECT tenant_id, device_id, product_id, machine_id, device_name, device_public_key, proof_key_id, proof_key_epoch, capabilities_json, harnesses_json FROM device_directory LIMIT 0");
+        const receiptColumns = this.db.prepare("PRAGMA table_info(request_receipt)").all();
+        const expectedColumns = ["tenant_id", "key", "body", "recorded_at"];
+        if (receiptColumns.length !== expectedColumns.length || receiptColumns.some((column, index) => column.name !== expectedColumns[index] || column.type !== "TEXT" || column.notnull !== 1 || column.pk !== (index < 2 ? index + 1 : 0))) {
+          throw new Error("Invalid BYOK SQLite request receipt schema");
+        }
+        this.db.exec("COMMIT");
+      } catch (error) {
+        this.db.exec("ROLLBACK");
+        throw error;
       }
       secureSqliteFilePermissions(path);
     } catch (error) {
@@ -888,6 +1105,30 @@ function readTask(db, tenant, taskId) {
 function sameAgentRef(left, right) {
   return left?.agentId === right?.agentId && left?.profileRevision === right?.profileRevision;
 }
+var SqliteRequestReceiptStore = class {
+  constructor(coordinator, clock) {
+    this.coordinator = coordinator;
+    this.clock = clock;
+  }
+  coordinator;
+  clock;
+  record(tenant, input) {
+    return this.coordinator.run((db) => {
+      const result = db.prepare(
+        `INSERT INTO request_receipt (tenant_id, key, body, recorded_at) VALUES (?, ?, ?, ?)
+         ON CONFLICT (tenant_id, key) DO NOTHING`
+      ).run(tenant, input.key, input.body, this.clock.now().toISOString());
+      return { receipt: this.#read(db, tenant, input.key), created: Number(result.changes) === 1 };
+    });
+  }
+  get(tenant, key) {
+    return this.coordinator.run((db) => this.#read(db, tenant, key));
+  }
+  #read(db, tenant, key) {
+    const row = db.prepare("SELECT body, recorded_at FROM request_receipt WHERE tenant_id = ? AND key = ?").get(tenant, key);
+    return row === void 0 ? void 0 : { tenantId: tenant, key, body: row.body, recordedAt: row.recorded_at };
+  }
+};
 var SqliteTaskAttemptStore = class {
   constructor(coordinator, clock) {
     this.coordinator = coordinator;
@@ -1506,7 +1747,7 @@ var SqliteBlobContentProxy = class {
   }
 };
 function createSqliteEmbeddedStores(options, dependencies) {
-  const coordinator = new SqliteCoordinator(options.path);
+  const coordinator = new SqliteCoordinator(options.path, options.migration);
   const objects = new SqliteObjectStore(coordinator, dependencies.clock);
   const mailbox = new SqliteMailboxStore(coordinator, dependencies.clock);
   const tasks = new SqliteTaskAttemptStore(coordinator, dependencies.clock);
@@ -1532,9 +1773,15 @@ function createSqliteEmbeddedStores(options, dependencies) {
     objects,
     mailbox
   );
+  const devices = new SqliteDeviceDirectory(coordinator);
+  const pairing = new InMemoryPairingCodeStore(dependencies.clock, devices);
   const cloud = {
     ...inMemoryCloud.stores,
+    devices,
+    pairingCodes: { issue: pairing.issue.bind(pairing) },
+    pairing: { redeemAndRegister: pairing.redeemAndRegister.bind(pairing) },
     tasks,
+    receipts: new SqliteRequestReceiptStore(coordinator, dependencies.clock),
     cancellations,
     blobs
   };
@@ -1555,6 +1802,7 @@ function composeFacadeStores(options) {
   const sqlite = options.storage?.kind === "sqlite" ? createSqliteEmbeddedStores(
     {
       path: options.storage.path,
+      ...options.storage.migration === void 0 ? {} : { migration: options.storage.migration },
       ...options.storage.urlTtlMs === void 0 ? {} : { urlTtlMs: options.storage.urlTtlMs }
     },
     { clock, crypto }
@@ -1830,6 +2078,21 @@ function createByokServer(opts) {
   async function requireConnected(deviceId) {
     if (!connections.isConnected(deviceId)) throw new Error(`device ${deviceId} is not connected`);
   }
+  const dispatching = /* @__PURE__ */ new Set();
+  async function dispatchWithIdentity(input, fresh) {
+    const submission = { ...input };
+    const taskId = submission.taskId;
+    if (taskId === void 0) return dispatchInternal(submission, fresh);
+    if (typeof taskId !== "string" || taskId.length === 0) throw new Error("taskId must be a non-empty string");
+    if (input.deviceId === void 0) throw new Error("caller taskId requires an explicit deviceId");
+    if (dispatching.has(taskId)) throw new Error("dispatch for this taskId is already in progress; retain the original binding");
+    dispatching.add(taskId);
+    try {
+      return await dispatchInternal(submission, fresh);
+    } finally {
+      dispatching.delete(taskId);
+    }
+  }
   async function dispatchInternal(input, freshAgentEgress) {
     const sessionRef = "sessionRef" in input ? input.sessionRef : void 0;
     const agentRef = input.agentRef === void 0 ? void 0 : AgentRefSchema.parse(input.agentRef);
@@ -1859,14 +2122,14 @@ function createByokServer(opts) {
       throw new Error("no connected device to dispatch to (M0 does not queue tasks until a device connects)");
     }
     await requireConnected(deviceId);
-    const capabilities = await deviceCapabilities(deviceId);
-    if (dispatchSelection !== void 0 && !(capabilities?.includes("dispatch-selection") ?? false)) {
+    const capabilities2 = await deviceCapabilities(deviceId);
+    if (dispatchSelection !== void 0 && !(capabilities2?.includes("dispatch-selection") ?? false)) {
       throw new Error(
         `device ${deviceId} did not advertise dispatch-selection capability; refusing authoritative provider/model dispatch`
       );
     }
     if (requiredToolsets !== void 0) {
-      if (!(capabilities?.includes("toolset-selection") ?? false)) {
+      if (!(capabilities2?.includes("toolset-selection") ?? false)) {
         throw new Error(
           `device ${deviceId} did not advertise toolset-selection capability; refusing a task whose semantics require local MCP tools`
         );
@@ -1888,7 +2151,7 @@ function createByokServer(opts) {
         `dispatch runtime ${input.runtime} does not match dispatchSelection.runtimeId ${dispatchSelection.runtimeId}`
       );
     }
-    if (agentRef === void 0 && capabilities?.includes(STRICT_AGENT_ONLY_CAPABILITY) === true) {
+    if (agentRef === void 0 && capabilities2?.includes(STRICT_AGENT_ONLY_CAPABILITY) === true) {
       throw new Error(
         `device ${deviceId} advertises strict-agent-only; legacy task dispatch is refused before enqueue`
       );
@@ -1902,7 +2165,7 @@ function createByokServer(opts) {
       ...runtime === void 0 ? {} : { runtime },
       ...dispatchSelection === void 0 ? {} : { dispatchSelection }
     };
-    const taskId = globalThis.crypto.randomUUID();
+    const taskId = input.taskId ?? globalThis.crypto.randomUUID();
     relay.provision(taskId);
     let enqueued;
     try {
@@ -2006,7 +2269,7 @@ function createByokServer(opts) {
       }
     },
     dispatch(input) {
-      return dispatchInternal(input, false);
+      return dispatchWithIdentity(input, false);
     },
     dispatchFreshAgentEgress(input) {
       if (Object.prototype.hasOwnProperty.call(input, "sessionRef")) {
@@ -2018,7 +2281,7 @@ function createByokServer(opts) {
       if (input.agentRef === void 0 || input.egressPolicy === void 0) {
         throw new Error("fresh Agent egress dispatch requires exact AgentRef and egress policy");
       }
-      return dispatchInternal(input, true);
+      return dispatchWithIdentity(input, true);
     },
     async requestAgentContentRead(input) {
       const payload = AgentContentReadPayloadSchema.parse(input.payload);
@@ -2049,6 +2312,15 @@ function createByokServer(opts) {
       });
     },
     tasks: {
+      offer(taskId) {
+        return cloud.readTaskOffer(tenant, taskId);
+      },
+      async cancel(taskId, reason) {
+        const attempt = await cloud.cancelTask(tenant, taskId, reason);
+        if (attempt.cancellation !== void 0) {
+          relay.noteHostTransition(taskId, "Cancelled", attempt.cancellation.requestedAt);
+        }
+      },
       async get(taskId) {
         const attempt = await cloud.readTaskAttempt(tenant, taskId);
         return attempt === void 0 ? void 0 : projectTask(attempt);