@byok-sdk/server 0.23.0 → 0.25.0-rc.1

package/README.md

@@ -15,7 +15,6 @@ const task = await server.dispatch({
   deviceId,
   instruction: 'Find five qualified prospects and draft follow-ups.',
   runtime: 'claude',
-  policy: { mode: 'auto' },
   requiredToolsets: ['salesko.prospecting'],
 });
 ```
@@ -25,7 +24,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 +40,57 @@ 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.
+
+Every refusal at open is a `SqliteSchemaError` with `foundVersion` and
+`requiredVersion`, so a host can check the file at startup and branch on `code`:
+
+- `SQLITE_SCHEMA_UNSUPPORTED`: the file needs an explicit `migration` selector
+  (older version) or a newer build (newer version).
+- `SQLITE_MIGRATION_REFUSED`: the selected migration would lose history;
+  preserve the file.
+- `SQLITE_SCHEMA_INVALID`: the file contradicts its declared schema or is not a
+  BYOK database.
 
 ```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.d.ts

@@ -35,7 +35,8 @@ export type { AccessTokenClaims, DeviceRecord, PairingCodeInfo, TenantId, TokenS
 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 { SqliteSchemaError, SqliteUnavailableError } from './sqlite-support';
+export type { SqliteSchemaErrorCode } 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. */

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) {
@@ -652,6 +654,20 @@ var SqliteUnavailableError = class extends Error {
     this.cause = cause;
   }
 };
+var SqliteSchemaError = class extends Error {
+  code;
+  /** The stored `schema_version`; `undefined` when the file has none. */
+  foundVersion;
+  /** The schema version this build writes. */
+  requiredVersion;
+  constructor(code, message, foundVersion, requiredVersion, options) {
+    super(message, options);
+    this.name = "SqliteSchemaError";
+    this.code = code;
+    this.foundVersion = foundVersion;
+    this.requiredVersion = requiredVersion;
+  }
+};
 var MIN_NODE_MAJOR = 22;
 var MIN_NODE_MINOR = 5;
 function isSqliteCapableNodeVersion(nodeVersion) {
@@ -879,7 +895,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 +939,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,
@@ -979,14 +996,24 @@ var SqliteCoordinator = class {
   #closePromise;
   constructor(path, migration) {
     this.db = openSqliteDatabase(path);
+    let foundVersion;
+    const schemaError = (code, message, options) => new SqliteSchemaError(code, message, foundVersion, SQLITE_SCHEMA_VERSION, options);
+    const assertProjection = (projection) => {
+      try {
+        this.db.prepare(`SELECT ${projection} LIMIT 0`);
+      } catch (error) {
+        throw schemaError("SQLITE_SCHEMA_INVALID", `Missing BYOK SQLite durable authority: SELECT ${projection}`, { cause: error });
+      }
+    };
     try {
       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.`);
+          foundVersion = version?.value;
+          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 schemaError("SQLITE_SCHEMA_UNSUPPORTED", `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",
@@ -997,43 +1024,48 @@ var SqliteCoordinator = class {
             "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`);
+            assertProjection(projection);
           }
-          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");
+                throw schemaError("SQLITE_MIGRATION_REFUSED", "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");
+              throw schemaError("SQLITE_MIGRATION_REFUSED", "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");
+              throw schemaError("SQLITE_SCHEMA_INVALID", "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");
+            if (unexpected !== void 0) throw schemaError("SQLITE_SCHEMA_INVALID", "Unexpected device directory in BYOK SQLite schema v1");
             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 schemaError("SQLITE_MIGRATION_REFUSED", "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 {
           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");
+          if (existing !== void 0) throw schemaError("SQLITE_SCHEMA_INVALID", "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.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");
+        assertProjection("claimed_harness_id FROM task_attempt");
+        assertProjection("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");
         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");
+          throw schemaError("SQLITE_SCHEMA_INVALID", "Invalid BYOK SQLite request receipt schema");
         }
         this.db.exec("COMMIT");
       } catch (error) {
@@ -1086,6 +1118,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 +1280,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,
@@ -2170,12 +2204,10 @@ function createByokServer(opts) {
         `device ${deviceId} advertises strict-agent-only; legacy task dispatch is refused before enqueue`
       );
     }
-    const policy = input.policy ?? { mode: "confirm" };
     const runtime = dispatchSelection?.runtimeId ?? input.runtime;
     const common = {
       ...input.harnessId === void 0 ? {} : { harnessId: input.harnessId },
       instruction: input.instruction,
-      policy,
       ...runtime === void 0 ? {} : { runtime },
       ...dispatchSelection === void 0 ? {} : { dispatchSelection }
     };
@@ -2443,6 +2475,6 @@ function longPollInterval(holdMs) {
   return Math.max(MIN_LONG_POLL_INTERVAL_MS, Math.min(MAX_LONG_POLL_INTERVAL_MS, derived));
 }
 
-export { DEFAULT_TASK_EVENT_BUFFER_LIMIT, DEFAULT_TASK_EVENT_RETENTION_MS, DEFAULT_TASK_PAGE_LIMIT, SqliteUnavailableError, SteerRejectedError, createByokServer };
+export { DEFAULT_TASK_EVENT_BUFFER_LIMIT, DEFAULT_TASK_EVENT_RETENTION_MS, DEFAULT_TASK_PAGE_LIMIT, SqliteSchemaError, SqliteUnavailableError, SteerRejectedError, createByokServer };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map