@byok-sdk/cloud 0.11.0 → 0.12.0

package/dist/index.js

@@ -182,10 +182,8 @@ function createAuthPlane(deps) {
       });
     },
     async redeemAndRegister(input) {
-      const claims = await stores.pairingCodes.redeem(input.pairingCode);
-      if (claims === void 0) return void 0;
-      return stores.devices.register(claims.tenantId, {
-        productId: claims.productId,
+      return stores.pairing.redeemAndRegister({
+        pairingCode: input.pairingCode,
         deviceId: `dev_${crypto2.randomUuid()}`,
         deviceName: input.deviceName,
         devicePublicKey: input.devicePublicKey,
@@ -202,11 +200,8 @@ function createAuthPlane(deps) {
     issueNonce(device) {
       return stores.nonces.issue(device.tenantId, device.deviceId);
     },
-    validateNonce(device, nonce) {
-      return stores.nonces.validate(device.tenantId, device.deviceId, nonce);
-    },
-    consumeNonce(device, nonce) {
-      return stores.nonces.markUsed(device.tenantId, nonce);
+    consumeNonceIfValid(device, nonce) {
+      return stores.nonces.consumeIfValid(device.tenantId, device.deviceId, nonce);
     },
     verifySignature(device, nonce, signature) {
       return verifyNonceSignature(crypto2, device.devicePublicKey, nonce, signature);
@@ -541,6 +536,7 @@ function tenantStoresFor(principal, root) {
     mailbox: {
       append: (input) => core.mailbox.append(tenant, input),
       readAfter: (query) => core.mailbox.readAfter(tenant, query),
+      recordDelivery: (input) => core.mailbox.recordDelivery(tenant, input),
       advanceCursor: (input) => core.mailbox.advanceCursor(tenant, input),
       readCursor: (deviceId) => core.mailbox.readCursor(tenant, deviceId)
     },
@@ -578,6 +574,9 @@ function tenantStoresFor(principal, root) {
     tasks: {
       open: (input) => cloud.tasks.open(tenant, input),
       reserveAgentOffer: (input) => cloud.tasks.reserveAgentOffer(tenant, input),
+      reserveAgentMessage: (input) => cloud.tasks.reserveAgentMessage(tenant, input),
+      readAgentMessage: (input) => cloud.tasks.readAgentMessage(tenant, input),
+      finalizeAgentMessage: (input) => cloud.tasks.finalizeAgentMessage(tenant, input),
       get: (taskId) => cloud.tasks.get(tenant, taskId),
       getMany: (taskIds) => cloud.tasks.getMany(tenant, taskIds),
       claim: (input) => cloud.tasks.claim(tenant, input),
@@ -627,6 +626,7 @@ async function readBoundedJsonBody(c, maximum) {
   if (declaredLength !== void 0) {
     const parsedLength = parseContentLength(declaredLength);
     if (parsedLength !== void 0 && parsedLength > BigInt(maximum)) {
+      cancelBody(c.req.raw.body);
       return { body: void 0, tooLarge: true };
     }
   }
@@ -640,10 +640,7 @@ async function readBoundedJsonBody(c, maximum) {
       const { done, value } = await reader.read();
       if (done) break;
       if (value.byteLength > maximum - total) {
-        try {
-          await reader.cancel();
-        } catch {
-        }
+        cancelBody(reader);
         return { body: void 0, tooLarge: true };
       }
       if (value.byteLength === 0) continue;
@@ -663,6 +660,14 @@ async function readBoundedJsonBody(c, maximum) {
   }
   return { body: parseJsonBytes(bytes), tooLarge: false };
 }
+function cancelBody(body) {
+  if (body === null) return;
+  try {
+    void Promise.resolve(body.cancel()).catch(() => {
+    });
+  } catch {
+  }
+}
 function parseContentLength(value) {
   const normalized = value.trim();
   if (!/^\d+$/u.test(normalized)) return void 0;
@@ -781,11 +786,43 @@ function blobUploadContentHandler(deps) {
     if (!query.success || !await deps.contentProxy.verifySignedUrl(blobId, "put", query.data.sig, query.data.exp)) {
       return c.json({ error: "invalid or expired signature" }, 401);
     }
-    const result = await deps.contentProxy.writeContent(blobId, new Uint8Array(await c.req.arrayBuffer()));
+    const expectedBytes = await deps.contentProxy.expectedUploadBytes(blobId);
+    if (expectedBytes === void 0) return c.json({ error: "blob not found" }, 404);
+    const absoluteCeiling = BigInt(deps.maxUploadBytes);
+    if (expectedBytes > absoluteCeiling) return c.json({ error: "upload exceeds size limit" }, 413);
+    const contentLength = c.req.header("content-length");
+    if (contentLength !== void 0 && /^\d+$/u.test(contentLength) && BigInt(contentLength) > expectedBytes) {
+      return c.json({ error: "upload exceeds declared size" }, 413);
+    }
+    const body = await readBoundedBody(c.req.raw.body, Number(expectedBytes));
+    if (body.tooLarge) return c.json({ error: "upload exceeds declared size" }, 413);
+    const result = await deps.contentProxy.writeContent(blobId, body.data);
     if (!result.ok) return c.json({ error: result.reason }, 422);
     return c.body(null, 204);
   };
 }
+async function readBoundedBody(body, ceiling) {
+  if (body === null) return { tooLarge: false, data: new Uint8Array() };
+  const reader = body.getReader();
+  const data = new Uint8Array(ceiling);
+  let offset = 0;
+  try {
+    for (; ; ) {
+      const next = await reader.read();
+      if (next.done) break;
+      const chunk = next.value;
+      if (chunk.byteLength > ceiling - offset) {
+        void reader.cancel().catch(() => void 0);
+        return { tooLarge: true };
+      }
+      data.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  return { tooLarge: false, data: data.subarray(0, offset) };
+}
 function blobDownloadContentHandler(deps) {
   return async (c) => {
     const blobId = c.req.param("id") ?? "";
@@ -830,9 +867,12 @@ function renderStorageError(c, error) {
 function capabilitiesHandler(deps) {
   return async (c) => c.json(deps.declaration, 200);
 }
+var AUTH_JSON_BODY_MAX_BYTES = 16 * 1024;
 function pairHandler(deps) {
   return async (c) => {
-    const parsed = PairRequestSchema.safeParse(await readJsonBody(c));
+    const body = await readBoundedJsonBody(c, AUTH_JSON_BODY_MAX_BYTES);
+    if (body.tooLarge) return c.json({ error: "request body too large" }, 413);
+    const parsed = PairRequestSchema.safeParse(body.body);
     if (!parsed.success) {
       return c.json(
         {
@@ -855,7 +895,9 @@ function pairHandler(deps) {
 }
 function challengeHandler(deps) {
   return async (c) => {
-    const parsed = ChallengeRequestSchema.safeParse(await readJsonBody(c));
+    const body = await readBoundedJsonBody(c, AUTH_JSON_BODY_MAX_BYTES);
+    if (body.tooLarge) return c.json({ error: "request body too large" }, 413);
+    const parsed = ChallengeRequestSchema.safeParse(body.body);
     if (!parsed.success) return c.json({ error: "deviceId is required" }, 400);
     const device = await deps.auth.resolveDevice(parsed.data.deviceId);
     if (device === void 0) return c.json({ error: "unknown or revoked device" }, 401);
@@ -865,18 +907,19 @@ function challengeHandler(deps) {
 }
 function tokenHandler(deps) {
   return async (c) => {
-    const parsed = TokenRequestSchema.safeParse(await readJsonBody(c));
+    const body = await readBoundedJsonBody(c, AUTH_JSON_BODY_MAX_BYTES);
+    if (body.tooLarge) return c.json({ error: "request body too large" }, 413);
+    const parsed = TokenRequestSchema.safeParse(body.body);
     if (!parsed.success) return c.json({ error: "deviceId, nonce, and signature are required" }, 400);
     const { deviceId, nonce, signature } = parsed.data;
     const device = await deps.auth.resolveDevice(deviceId);
     if (device === void 0) return c.json({ error: "unknown or revoked device" }, 401);
-    if (!await deps.auth.validateNonce(device, nonce)) {
-      return c.json({ error: "invalid, expired, or already-used nonce" }, 401);
-    }
     if (!await deps.auth.verifySignature(device, nonce, signature)) {
       return c.json({ error: "invalid signature" }, 401);
     }
-    await deps.auth.consumeNonce(device, nonce);
+    if (!await deps.auth.consumeNonceIfValid(device, nonce)) {
+      return c.json({ error: "invalid, expired, or already-used nonce" }, 401);
+    }
     const { accessToken, expiresAt } = await deps.auth.mintAccessToken(device);
     const response = { accessToken, expiresAt };
     return c.json(response, 200);
@@ -905,12 +948,21 @@ function eventsHandler(deps) {
     let cursor = 0;
     if (cursorRaw !== void 0) {
       const parsedCursor = Number(cursorRaw);
-      if (!Number.isInteger(parsedCursor) || parsedCursor < 0) return c.json({ error: "invalid cursor" }, 400);
+      if (!Number.isSafeInteger(parsedCursor) || parsedCursor < 0) {
+        return c.json({ error: "invalid cursor" }, 400);
+      }
       cursor = parsedCursor;
     }
     const acked = await stores.mailbox.readCursor(device.deviceId);
     if (cursor > acked.ackedSeq) {
-      await stores.mailbox.advanceCursor({ deviceId: device.deviceId, ackedSeq: cursor });
+      try {
+        await stores.mailbox.advanceCursor({ deviceId: device.deviceId, ackedSeq: cursor });
+      } catch (caught) {
+        if (isCoreConflictError(caught, "mailbox_cursor_ahead_of_delivery")) {
+          return c.json({ error: "cursor exceeds delivered watermark" }, 409);
+        }
+        throw caught;
+      }
     }
     const attempts = Math.max(1, Math.ceil(deps.longPollHoldMs / deps.longPollIntervalMs));
     for (let attempt = 0; attempt < attempts; attempt += 1) {
@@ -945,6 +997,10 @@ function eventsHandler(deps) {
           cursor: page.nextSeq,
           capabilities: CLOUD_PROTOCOL_CAPABILITIES
         };
+        await stores.mailbox.recordDelivery({
+          deviceId: device.deviceId,
+          deliveredSeq: response2.cursor
+        });
         return c.json(response2, 200);
       }
       if (attempt < attempts - 1) await sleep(deps.longPollIntervalMs);
@@ -1042,11 +1098,11 @@ async function projectTerminalToReview(board, taskId) {
 }
 
 // src/inbound.ts
-async function handleAgentMessagePublish(stores, deviceId, taskId, payload, consume) {
+async function handleAgentMessagePublish(stores, deviceId, taskId, payload, consume, alreadyDeduplicated) {
   const device = await stores.devices.get(deviceId);
   const attempt = await stores.tasks.get(taskId);
   const binding = await stores.receipts.get(`agent-message-offer:${deviceId}:${taskId}`);
-  if (device === void 0 || device.revoked || !hasCapabilities(device.capabilities, [AGENT_MESSAGE_EGRESS_CAPABILITY]) || attempt === void 0 || attempt.deviceId !== deviceId || binding === void 0 || !sameAgentRef(attempt.agentRef, payload.agentRef)) return { outcome: "rejected" };
+  if (device === void 0 || device.revoked || !hasCapabilities(device.capabilities, [AGENT_MESSAGE_EGRESS_CAPABILITY]) || attempt === void 0 || attempt.deviceId !== deviceId || binding === void 0 || attempt.agentRef === void 0 || !sameAgentRef(attempt.agentRef, payload.agentRef)) return { outcome: "rejected" };
   let frozen;
   try {
     frozen = JSON.parse(binding.body);
@@ -1054,19 +1110,41 @@ async function handleAgentMessagePublish(stores, deviceId, taskId, payload, cons
     return { outcome: "rejected" };
   }
   if (!sameAgentRef(frozen.agentRef, payload.agentRef) || frozen.context === void 0 || frozen.requirement?.contract !== payload.contract || frozen.sessionRef !== void 0 && frozen.sessionRef !== payload.sessionRef || frozen.requirement.contentType !== payload.contentType || typeof frozen.requirement.maxBytes !== "number" || payload.byteCount > frozen.requirement.maxBytes) return { outcome: "rejected" };
-  const taskMessageKey = `agent-message-task:${deviceId}:${taskId}`;
-  const taskMessageBody = JSON.stringify(payload);
-  const lockedTaskMessage = await stores.receipts.record({ key: taskMessageKey, body: taskMessageBody });
-  if (!lockedTaskMessage.created && lockedTaskMessage.receipt.body !== taskMessageBody) return { outcome: "rejected" };
-  const receiptKey2 = `agent-message:${deviceId}:${payload.messageId}`;
-  const previous = await stores.receipts.get(receiptKey2);
-  if (previous !== void 0) {
-    const decoded = JSON.parse(previous.body);
-    if (JSON.stringify(decoded.payload) !== JSON.stringify(payload)) return { outcome: "rejected" };
-    return { outcome: "duplicate", disposition: decoded.disposition };
-  }
-  const decision = consume === void 0 ? { outcome: "held", reasonCode: "consumer_unavailable" } : await consume({ tenant: stores.tenant, deviceId, taskId, context: frozen.context, payload });
-  const disposition = {
+  const priorDisposition = await readAgentMessageDisposition(stores, deviceId, taskId, payload);
+  if (priorDisposition !== void 0) return { outcome: "duplicate", disposition: priorDisposition };
+  if (alreadyDeduplicated) return { outcome: "rejected" };
+  const payloadBody = JSON.stringify(payload);
+  const reservation = await stores.tasks.reserveAgentMessage({
+    taskId,
+    deviceId,
+    messageId: payload.messageId,
+    payloadBody
+  });
+  if (reservation === "pending") return { outcome: "rejected" };
+  if (reservation !== "reserved") return { outcome: "rejected" };
+  let decision;
+  if (consume === void 0) {
+    decision = { outcome: "held", reasonCode: "consumer_unavailable" };
+  } else {
+    try {
+      decision = await consume({ tenant: stores.tenant, deviceId, taskId, context: frozen.context, payload });
+    } catch {
+      decision = { outcome: "held", reasonCode: "consumer_failed" };
+    }
+  }
+  const disposition = agentMessageDisposition(payload, decision);
+  const admission = await stores.tasks.finalizeAgentMessage({
+    taskId,
+    deviceId,
+    messageId: payload.messageId,
+    payloadBody,
+    terminalBody: JSON.stringify({ payload, disposition })
+  });
+  const terminal = admission?.terminalBody === void 0 ? void 0 : parseAgentMessageDisposition(payload, admission.terminalBody);
+  return terminal === void 0 ? { outcome: "rejected" } : { outcome: "accepted", disposition: terminal };
+}
+function agentMessageDisposition(payload, decision) {
+  return {
     agentRef: payload.agentRef,
     sessionRef: payload.sessionRef,
     contract: payload.contract,
@@ -1077,9 +1155,23 @@ async function handleAgentMessagePublish(stores, deviceId, taskId, payload, cons
     receiptId: crypto.randomUUID(),
     ...decision.reasonCode === void 0 ? {} : { reasonCode: decision.reasonCode }
   };
-  const recorded = await stores.receipts.record({ key: receiptKey2, body: JSON.stringify({ payload, disposition }) });
-  if (!recorded.created && recorded.receipt.body !== JSON.stringify({ payload, disposition })) return { outcome: "rejected" };
-  return { outcome: "accepted", disposition };
+}
+async function readAgentMessageDisposition(stores, deviceId, taskId, payload) {
+  const admission = await stores.tasks.readAgentMessage({
+    taskId,
+    deviceId,
+    messageId: payload.messageId,
+    payloadBody: JSON.stringify(payload)
+  });
+  return admission?.terminalBody === void 0 ? void 0 : parseAgentMessageDisposition(payload, admission.terminalBody);
+}
+function parseAgentMessageDisposition(payload, terminalBody) {
+  try {
+    const decoded = JSON.parse(terminalBody);
+    return decoded.disposition !== void 0 && JSON.stringify(decoded.payload) === JSON.stringify(payload) ? decoded.disposition : void 0;
+  } catch {
+    return void 0;
+  }
 }
 function terminalReceiptKey(taskId) {
   return `task:${taskId}:terminal`;
@@ -1136,7 +1228,7 @@ function inboundAgentRef(envelope) {
 function agentRefEchoRequired(envelope) {
   return envelope.type === "task.claim" || envelope.type === "task.decline" || envelope.type === "task.complete" || envelope.type === "task.fail" || envelope.type === "task.cancelled";
 }
-async function handleInboundEnvelope(stores, deviceId, envelope, activityBounds = DEFAULT_ACTIVITY_BOUNDS) {
+async function handleInboundEnvelope(stores, deviceId, envelope, activityBounds = DEFAULT_ACTIVITY_BOUNDS, agentMessageConsume) {
   if (!await stores.rateLimiter.consume(deviceId)) return "rate_limited";
   if (envelope.type === "conn.hello") {
     if (envelope.payload.deviceId !== deviceId) return "rejected";
@@ -1149,6 +1241,17 @@ async function handleInboundEnvelope(stores, deviceId, envelope, activityBounds
     return await stores.devices.recordCapabilities({ capabilities: envelope.payload.capabilities }) === void 0 ? "rejected" : "accepted";
   }
   if (!DAEMON_TO_SERVER_TYPES.includes(envelope.type)) return "rejected";
+  if (envelope.type === "agent.message.publish") {
+    const alreadyDeduplicated = await stores.dedup.checkAndRecord(deviceId, envelope.id);
+    return (await handleAgentMessagePublish(
+      stores,
+      deviceId,
+      envelope.task_id,
+      envelope.payload,
+      agentMessageConsume,
+      alreadyDeduplicated
+    )).outcome;
+  }
   if (envelope.type === "agent.egress.reliable") {
     const device = await stores.devices.get(deviceId);
     if (device === void 0 || device.revoked || !hasCapabilities(device.capabilities, [AGENT_EGRESS_POLICY_CAPABILITY, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY])) {
@@ -1323,32 +1426,32 @@ async function recordTerminal(stores, taskId, envelope, status) {
 }
 
 // src/handlers/messages.ts
+var MESSAGES_JSON_BODY_MAX_BYTES = 2 * 1024 * 1024;
 function messagesHandler(deps) {
   return async (c) => {
     const authenticated = await authenticateDevice(c, deps);
     if (authenticated === void 0) return c.json({ error: "unauthorized" }, 401);
     const { device, stores } = authenticated;
-    const parsed = MessagesSendRequestSchema.safeParse(await readJsonBody(c));
+    const body = await readBoundedJsonBody(c, MESSAGES_JSON_BODY_MAX_BYTES);
+    if (body.tooLarge) return c.json({ error: "request body too large" }, 413);
+    const parsed = MessagesSendRequestSchema.safeParse(body.body);
     if (!parsed.success) return c.json({ error: "messages must be an array of envelopes" }, 400);
     let accepted = 0;
     let rejected = 0;
     for (const envelope of parsed.data.messages) {
-      const messageResult = envelope.type === "agent.message.publish" ? await handleAgentMessagePublish(
-        stores,
-        device.deviceId,
-        envelope.task_id,
-        envelope.payload,
-        deps.agentMessage?.consume
-      ) : void 0;
-      const outcome = messageResult?.outcome ?? await handleInboundEnvelope(
+      const outcome = await handleInboundEnvelope(
         stores,
         device.deviceId,
         envelope,
-        deps.activityBounds
+        deps.activityBounds,
+        envelope.type === "agent.message.publish" ? deps.agentMessage?.consume : void 0
       );
       if (outcome === "rate_limited") return c.json({ error: "rate limit exceeded" }, 429);
-      if (envelope.type === "agent.message.publish" && messageResult?.disposition !== void 0) {
-        await deps.appendAgentMessageDisposition(stores, device.deviceId, envelope.task_id, messageResult.disposition);
+      if (envelope.type === "agent.message.publish") {
+        const disposition = await readAgentMessageDisposition(stores, device.deviceId, envelope.task_id, envelope.payload);
+        if (disposition !== void 0) {
+          await deps.appendAgentMessageDisposition(stores, device.deviceId, envelope.task_id, disposition);
+        }
       }
       if (envelope.type === "agent.egress.reliable" && (outcome === "accepted" || outcome === "duplicate")) {
         const record = await stores.egress.get(device.deviceId, envelope.payload.eventId);
@@ -1961,7 +2064,7 @@ function truthGetHandler(deps) {
 }
 function truthPutHandler(deps) {
   return async (c) => {
-    const body = await readBoundedBody(c, deps.maxRequestBytes);
+    const body = await readBoundedBody2(c, deps.maxRequestBytes);
     if (body === "too_large") return c.json({ error: "truth request body too large" }, 413);
     if (body === void 0) return c.json({ error: "invalid truth request body" }, 400);
     const authenticated = await authenticateTruthRequest(c, deps, {
@@ -2093,7 +2196,7 @@ function decodeProofHeader(value) {
     return void 0;
   }
 }
-async function readBoundedBody(c, maximum) {
+async function readBoundedBody2(c, maximum) {
   const length = c.req.header("content-length");
   if (length !== void 0) {
     const parsed = Number(length);
@@ -2522,7 +2625,10 @@ function createByokCloud(options) {
   }
   const contentProxy = options.blobContentProxy;
   if (contentProxy !== void 0 && declares(declaration, CLOUD_CAPABILITIES.blobsContentProxy)) {
-    const contentDeps = { contentProxy };
+    const contentDeps = {
+      contentProxy,
+      maxUploadBytes: options.maxBlobSizeBytes ?? DEFAULT_MAX_BLOB_SIZE_BYTES
+    };
     registry.register(
       { method: "PUT", path: BYOK_BLOB_CONTENT_ROUTE, class: "presigned" },
       blobUploadContentHandler(contentDeps)
@@ -3256,6 +3362,9 @@ var InMemoryBlobContentProxy = class {
     const expected = await this.#registry.computeSig(blobId, action, exp);
     return this.#registry.crypto.timingSafeEqual(expected, sig);
   }
+  async expectedUploadBytes(blobId) {
+    return this.#registry.blobs.get(blobId)?.byteSize;
+  }
   async writeContent(blobId, data) {
     const record = this.#registry.blobs.get(blobId);
     if (record === void 0) return { ok: false, reason: "unknown blobId" };
@@ -3469,27 +3578,38 @@ var InMemoryNonceStore = class {
     });
     return nonce;
   }
-  async validate(tenant, deviceId, nonce) {
+  async consumeIfValid(tenant, deviceId, nonce) {
     const record = this.#nonces.get(nonce);
     if (record === void 0) return false;
     if (record.used) return false;
     if (record.owner !== tenantKey(tenant, deviceId)) return false;
-    return this.#clock.now().getTime() <= record.expiresAtMs;
-  }
-  async markUsed(tenant, nonce) {
-    const record = this.#nonces.get(nonce);
-    if (record === void 0) return;
-    if (!record.owner.startsWith(tenantKey(tenant, ""))) return;
+    if (this.#clock.now().getTime() > record.expiresAtMs) return false;
     record.used = true;
+    return true;
   }
 };
 
 // src/stores/in-memory/pairing-codes.ts
+function bindingOf(input) {
+  return {
+    deviceName: input.deviceName,
+    devicePublicKey: input.devicePublicKey,
+    proofKeyId: input.proofKeyId,
+    proofKeyEpoch: input.proofKeyEpoch,
+    ...input.machineId === void 0 ? {} : { machineId: input.machineId }
+  };
+}
+function sameBinding(left, right) {
+  return left.deviceName === right.deviceName && left.devicePublicKey === right.devicePublicKey && left.proofKeyId === right.proofKeyId && left.proofKeyEpoch === right.proofKeyEpoch && left.machineId === right.machineId;
+}
 var InMemoryPairingCodeStore = class {
   #codes = /* @__PURE__ */ new Map();
+  #enrollmentTails = /* @__PURE__ */ new Map();
   #clock;
-  constructor(clock) {
+  #devices;
+  constructor(clock, devices) {
     this.#clock = clock;
+    this.#devices = devices;
   }
   async issue(tenant, input) {
     this.#codes.set(input.code, {
@@ -3499,13 +3619,42 @@ var InMemoryPairingCodeStore = class {
     });
     return { code: input.code, expiresAt: input.expiresAt };
   }
-  async redeem(code) {
-    const record = this.#codes.get(code);
-    if (record === void 0) return void 0;
-    if (record.used) return void 0;
-    if (this.#clock.now().getTime() > record.expiresAtMs) return void 0;
-    record.used = true;
-    return record.claims;
+  async redeemAndRegister(input) {
+    const previous = this.#enrollmentTails.get(input.pairingCode) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => {
+      release = resolve;
+    });
+    this.#enrollmentTails.set(input.pairingCode, current);
+    await previous;
+    try {
+      const record = this.#codes.get(input.pairingCode);
+      if (record === void 0) return void 0;
+      if (record.used) {
+        const completion = record.completion;
+        if (completion === void 0 || !sameBinding(completion.binding, bindingOf(input))) return void 0;
+        const active = await this.#devices.get(completion.device.tenantId, completion.device.deviceId);
+        return active === void 0 ? void 0 : completion.device;
+      }
+      if (this.#clock.now().getTime() > record.expiresAtMs) return void 0;
+      const device = await this.#devices.register(record.claims.tenantId, {
+        productId: record.claims.productId,
+        deviceId: input.deviceId,
+        deviceName: input.deviceName,
+        devicePublicKey: input.devicePublicKey,
+        proofKeyId: input.proofKeyId,
+        proofKeyEpoch: input.proofKeyEpoch,
+        ...input.machineId === void 0 ? {} : { machineId: input.machineId }
+      });
+      record.used = true;
+      record.completion = { device, binding: bindingOf(input) };
+      return device;
+    } finally {
+      release();
+      if (this.#enrollmentTails.get(input.pairingCode) === current) {
+        this.#enrollmentTails.delete(input.pairingCode);
+      }
+    }
   }
 };
 var InMemoryRequestReceiptStore = class {
@@ -3553,6 +3702,36 @@ var InMemoryProofRequestReceiptStore = class {
     return this.#receipts.get(tenantKey(tenant, deviceId, requestId));
   }
 };
+
+// src/stores/ports.ts
+var TASK_ATTEMPT_STATUSES = [
+  "offered",
+  "claimed",
+  "running",
+  "cancel_requested",
+  "complete",
+  "failed",
+  "cancelled"
+];
+var BLOB_READ_ERROR_CODES = ["blob_upstream_unavailable", "blob_upstream_stream_interrupted"];
+var CLOUD_STORE_NAMES = [
+  "activity",
+  "approvals",
+  "devices",
+  "pairingCodes",
+  "pairing",
+  "nonces",
+  "dedup",
+  "tasks",
+  "cancellations",
+  "receipts",
+  "egress",
+  "proofReceipts",
+  "blobs",
+  "rateLimiter"
+];
+
+// src/stores/in-memory/task-attempts.ts
 function sameAgentRef3(left, right) {
   return left?.agentId === right?.agentId && left?.profileRevision === right?.profileRevision;
 }
@@ -3595,6 +3774,40 @@ var InMemoryTaskAttemptStore = class {
       return { attempt, created: true };
     });
   }
+  async reserveAgentMessage(tenant, input) {
+    const key = tenantKey(tenant, input.taskId);
+    return this.#state.mutate(key, () => {
+      const attempt = this.#state.attempts.get(key);
+      if (attempt === void 0 || attempt.deviceId !== input.deviceId || attempt.cancellation !== void 0 || !["offered", "claimed", "running"].includes(attempt.status)) return "rejected";
+      const existing = this.#state.messageAdmissions.get(key);
+      if (existing === void 0) {
+        this.#state.messageAdmissions.set(key, {
+          messageId: input.messageId,
+          payloadBody: input.payloadBody
+        });
+        return "reserved";
+      }
+      return existing.messageId === input.messageId && existing.payloadBody === input.payloadBody ? "pending" : "rejected";
+    });
+  }
+  async readAgentMessage(tenant, input) {
+    const admission = this.#state.messageAdmissions.get(tenantKey(tenant, input.taskId));
+    return admission !== void 0 && admission.messageId === input.messageId && admission.payloadBody === input.payloadBody ? admission : void 0;
+  }
+  async finalizeAgentMessage(tenant, input) {
+    const key = tenantKey(tenant, input.taskId);
+    return this.#state.mutate(key, () => this.#terminalize(key, input));
+  }
+  #terminalize(key, input) {
+    const admission = this.#state.messageAdmissions.get(key);
+    if (admission === void 0 || admission.messageId !== input.messageId || admission.payloadBody !== input.payloadBody) {
+      return void 0;
+    }
+    if (admission.terminalBody !== void 0) return admission;
+    const terminal = { ...admission, terminalBody: input.terminalBody };
+    this.#state.messageAdmissions.set(key, terminal);
+    return terminal;
+  }
   async get(tenant, taskId) {
     return this.#state.attempts.get(tenantKey(tenant, taskId));
   }
@@ -3647,6 +3860,7 @@ var InMemoryTaskAttemptStore = class {
 };
 var InMemoryTaskAttemptState = class {
   attempts = /* @__PURE__ */ new Map();
+  messageAdmissions = /* @__PURE__ */ new Map();
   #clock;
   #mutationTails = /* @__PURE__ */ new Map();
   constructor(clock) {
@@ -3866,12 +4080,17 @@ function createInMemoryCloudStores(clock, crypto2, objects, mailbox) {
   const blobs = createInMemoryBlobs(clock, crypto2, objects);
   const taskState = new InMemoryTaskAttemptState(clock);
   const tasks = new InMemoryTaskAttemptStore(clock, taskState);
+  const devices = new InMemoryDeviceDirectory();
+  const pairing = new InMemoryPairingCodeStore(clock, devices);
   return {
     stores: {
       activity: new InMemoryActivityStore(clock),
       approvals: new InMemoryApprovalTimelineStore(clock),
-      devices: new InMemoryDeviceDirectory(),
-      pairingCodes: new InMemoryPairingCodeStore(clock),
+      devices,
+      // One code/device authority, projected into issuance and consumption
+      // ports so neither side exposes the other's methods.
+      pairingCodes: { issue: pairing.issue.bind(pairing) },
+      pairing: { redeemAndRegister: pairing.redeemAndRegister.bind(pairing) },
       nonces: new InMemoryNonceStore(clock, crypto2),
       dedup: new InMemoryInboundDedupStore(),
       tasks,
@@ -4283,42 +4502,26 @@ function parseSseFrame(frame) {
   return { type: "board", item: BoardFeedItemSchema.parse(JSON.parse(data.join("\n"))) };
 }
 
-// src/stores/ports.ts
-var TASK_ATTEMPT_STATUSES = [
-  "offered",
-  "claimed",
-  "running",
-  "cancel_requested",
-  "complete",
-  "failed",
-  "cancelled"
-];
-var BLOB_READ_ERROR_CODES = ["blob_upstream_unavailable", "blob_upstream_stream_interrupted"];
-var CLOUD_STORE_NAMES = [
-  "activity",
-  "approvals",
-  "devices",
-  "pairingCodes",
-  "nonces",
-  "dedup",
-  "tasks",
-  "cancellations",
-  "receipts",
-  "egress",
-  "proofReceipts",
-  "blobs",
-  "rateLimiter"
-];
-
 // src/stores/ports-contract.ts
 var CLOUD_PORT_METHODS = {
   activity: ["append", "read"],
   approvals: ["append", "read"],
   devices: ["register", "get", "revoke", "list", "readiness", "recordCapabilities", "resolveByDeviceId"],
-  pairingCodes: ["issue", "redeem"],
-  nonces: ["issue", "validate", "markUsed"],
+  pairingCodes: ["issue"],
+  pairing: ["redeemAndRegister"],
+  nonces: ["issue", "consumeIfValid"],
   dedup: ["checkAndRecord"],
-  tasks: ["open", "reserveAgentOffer", "get", "getMany", "claim", "recordStatus"],
+  tasks: [
+    "open",
+    "reserveAgentOffer",
+    "reserveAgentMessage",
+    "readAgentMessage",
+    "finalizeAgentMessage",
+    "get",
+    "getMany",
+    "claim",
+    "recordStatus"
+  ],
   cancellations: ["request"],
   receipts: ["record", "get"],
   egress: ["record", "get"],
@@ -4334,6 +4537,7 @@ var CLOUD_PORT_INTERFACES = {
   approvals: "ApprovalTimelineStore",
   devices: "DeviceDirectory",
   pairingCodes: "PairingCodeStore",
+  pairing: "PairingEnrollment",
   nonces: "NonceStore",
   dedup: "InboundDedupStore",
   tasks: "TaskAttemptStore",