@byok-sdk/server 0.23.0 → 0.24.0

package/README.md

@@ -25,7 +25,7 @@ live device advertises `toolset-selection` and its `configuredToolsets`
 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.
+MIT licensed. Node.js 24.15.0 or newer.
 
 ## SQLite enrollment, receipts and schema adoption
 
@@ -41,37 +41,47 @@ 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
+This candidate writes schema v4, including the write-once `claimedHarnessId`
+stored atomically with task ownership. 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.
+explicit adoption. An already-open old writer is not stopped by the version fence.
+
+- `v1-to-v4` and `v2-to-v4` require no task, mailbox-message, agent-admission or
+  advanced cursor history: old in-memory receipts cannot be recovered from task
+  status or fabricated from a retry payload. A pristine poll cursor is allowed.
+- `v3-to-v4` preserves receipts, unclaimed offers and claims with an identified
+  built-in runtime. It rejects any owned task with no `claimed_runtime`, including
+  terminal tasks: a lost custom-harness identity cannot be distinguished from an
+  identity-free legacy built-in claim. Neither the requested offer nor current
+  device inventory proves the actual claiming adapter. Existing rows receive a
+  null harness identity; migration never invents one.
+
+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' },
+  storage: { kind: 'sqlite', path, migration: 'v3-to-v4' },
 });
 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.
+Remove `migration` from normal startup. Adoption adds the nullable harness column,
+adds receipts for v1/v2 and an empty device directory for v1, and updates the marker
+atomically; any failure rolls back. Existing v2/v3 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:** schema-v1/v2/v3 writers refuse v4. The public
+`v1-to-v3` / `v2-to-v3` selectors are replaced by the corresponding target-v4
+selectors, with no alias or silent reinterpretation: callers must update their
+one-shot migration configuration after checking eligibility and backing up.
+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

package/dist/index.js

@@ -231,7 +231,9 @@ var TaskEventRelay = class {
   }
   /** The per-task feed backing `TaskHandle.events()`, replayed from the start of what is retained. */
   events(taskId) {
-    return this.#open(taskId).queue.subscribe();
+    const state = this.#tasks.get(taskId);
+    return state === void 0 ? { async *[Symbol.asyncIterator]() {
+    } } : state.queue.subscribe();
   }
   /** Settles when this task first reaches a terminal — the barrier `TaskHandle.result()` awaits. */
   terminal(taskId) {
@@ -879,7 +881,7 @@ 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 = "3";
+var SQLITE_SCHEMA_VERSION = "4";
 var RECEIPT_SCHEMA = `
 CREATE TABLE request_receipt (
   tenant_id TEXT NOT NULL,
@@ -923,6 +925,7 @@ CREATE TABLE IF NOT EXISTS task_attempt (
   agent_ref_json TEXT,
   owner_device_id TEXT,
   claimed_runtime TEXT,
+  claimed_harness_id TEXT,
   claimed_runtime_capabilities_json TEXT,
   status TEXT NOT NULL,
   terminal_cause TEXT,
@@ -985,8 +988,8 @@ var SqliteCoordinator = class {
         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.`);
+          if (version?.value !== SQLITE_SCHEMA_VERSION && !(version?.value === "1" && migration === "v1-to-v4" || version?.value === "2" && migration === "v2-to-v4" || version?.value === "3" && migration === "v3-to-v4")) {
+            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-v4' or 'v2-to-v4' for a receipt-free legacy database without task history, or 'v3-to-v4' for a database without ambiguous claimed identity. Target-v3 migration selectors are no longer supported.`);
           }
           for (const projection of [
             "tenant_id, device_id, next_seq, delivered_seq, acked_seq, updated_at FROM mailbox_cursor",
@@ -999,7 +1002,7 @@ var SqliteCoordinator = class {
           ]) {
             this.db.prepare(`SELECT ${projection} LIMIT 0`);
           }
-          if (version?.value !== SQLITE_SCHEMA_VERSION) {
+          if (version?.value === "1" || version?.value === "2") {
             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");
@@ -1019,6 +1022,10 @@ var SqliteCoordinator = class {
             this.db.exec(DEVICE_SCHEMA);
           }
           if (version?.value !== SQLITE_SCHEMA_VERSION) {
+            if (this.db.prepare("SELECT 1 FROM task_attempt WHERE owner_device_id IS NOT NULL AND claimed_runtime IS NULL LIMIT 1").get() !== void 0) {
+              throw new Error("Cannot migrate BYOK SQLite database with ambiguous claimed identity: historical harness identities are unavailable; preserve this database for reconciliation");
+            }
+            this.db.exec("ALTER TABLE task_attempt ADD COLUMN claimed_harness_id TEXT");
             this.db.prepare("UPDATE byok_sqlite_meta SET value = ? WHERE key = 'schema_version'").run(SQLITE_SCHEMA_VERSION);
           }
         } else {
@@ -1029,6 +1036,7 @@ var SqliteCoordinator = class {
           this.db.exec(DEVICE_SCHEMA);
           this.db.prepare("INSERT INTO byok_sqlite_meta (key, value) VALUES ('schema_version', ?)").run(SQLITE_SCHEMA_VERSION);
         }
+        this.db.prepare("SELECT claimed_harness_id FROM task_attempt LIMIT 0");
         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"];
@@ -1086,6 +1094,7 @@ function taskRow(row) {
     ...row.agent_ref_json === null ? {} : { agentRef: JSON.parse(row.agent_ref_json) },
     ...row.owner_device_id === null ? {} : { ownerDeviceId: row.owner_device_id },
     ...row.claimed_runtime === null ? {} : { claimedRuntime: row.claimed_runtime },
+    ...row.claimed_harness_id === null ? {} : { claimedHarnessId: row.claimed_harness_id },
     ...row.claimed_runtime_capabilities_json === null ? {} : { claimedRuntimeCapabilities: JSON.parse(row.claimed_runtime_capabilities_json) },
     status: row.status,
     ...row.terminal_cause === null ? {} : { terminalCause: row.terminal_cause },
@@ -1247,13 +1256,14 @@ var SqliteTaskAttemptStore = class {
   claim(tenant, input) {
     return this.coordinator.run((db) => {
       db.prepare(
-        `UPDATE task_attempt SET owner_device_id = ?, claimed_runtime = ?, claimed_runtime_capabilities_json = ?,
+        `UPDATE task_attempt SET owner_device_id = ?, claimed_runtime = ?, claimed_harness_id = ?, claimed_runtime_capabilities_json = ?,
           status = 'claimed', updated_at = ?
          WHERE tenant_id = ? AND task_id = ? AND device_id = ? AND owner_device_id IS NULL
            AND cancellation_requested_at IS NULL AND status = 'offered'`
       ).run(
         input.deviceId,
         input.runtime ?? null,
+        input.harnessId ?? null,
         input.capabilities === void 0 ? null : JSON.stringify(input.capabilities),
         this.#now(),
         tenant,