@byok-sdk/cloud 0.22.0 → 0.23.0

package/dist/capabilities.d.ts

@@ -73,7 +73,7 @@ export declare const CLOUD_CAPABILITIES: {
      * DEVICE's only way to discharge a mailbox row this same deployment handed
      * it — withholding it would strand the device's redelivery cursor rather
      * than degrade a feature. For the same reason the completion route asserts
-     * no DEVICE capability either: the device-level `agent-input-preparation-v7`
+     * no DEVICE capability either: the device-level `agent-input-preparation-v8`
      * flag gates ADMISSION (`enqueueInputPreparation`) and nothing else, so an
      * unconfigured device is refused a row instead of being handed one whose
      * only honest answer — `input_preparation_unconfigured` — it could not then

package/dist/cloud.d.ts

@@ -19,7 +19,7 @@ import { type RecurringExecutionInput } from './recurring';
 import { type BoardItem, type BoardItemInput, type BoardListQuery, type BoardPage, type CapabilityDeclaration, type Clock, type CoreStores, type PresenceHint, type SkillPackStore, type TenantId, type TenantReadiness } from '@byok-sdk/core';
 import type { ActivityTail } from './activity';
 import type { ApprovalTimelineTail } from './approval-timeline';
-import { type Envelope, type TaskOfferType, type AgentRef, type AgentContentReadPayload, type AgentMessageDispositionPayload, type AgentMessagePublishPayload, type AgentMessageServerContext, type AgentHomeProjectionCompletionRequest, type AgentHomeProjectionPayload, type AgentHomeProjectionReadback, type AgentInputPreparationPayload, type InputPreparationCompletionRequest, type InputPreparationReadback, type AgentMemoryProjectionEraseResult, type TaskOfferPayload, type TaskSteerPayload, type TaskOfferForAgentPayload, type TaskOfferPreparedPayload, type TaskOfferForAgentWithEgressPayload, type TaskOfferForAgentWithEgressFreshPayload, type TaskOfferWithToolsetsPayload } from '@byok-sdk/protocol';
+import { type Envelope, type TaskOfferType, type AgentRef, type AgentContentReadPayload, type AgentMessageDispositionPayload, type AgentMessagePublishPayload, type AgentMessageServerContext, type AgentHomeProjectionCompletionRequest, type AgentHomeProjectionPayload, type AgentHomeProjectionReadback, type AgentInputPreparationPayload, type ProviderProvisioningAvailablePayload, type InputPreparationCompletionRequest, type InputPreparationReadback, type AgentMemoryProjectionEraseResult, type TaskOfferPayload, type TaskSteerPayload, type TaskOfferForAgentPayload, type TaskOfferPreparedPayload, type TaskOfferForAgentWithEgressPayload, type TaskOfferForAgentWithEgressFreshPayload, type TaskOfferWithToolsetsPayload } from '@byok-sdk/protocol';
 import type { TokenSigner } from './auth/tokens';
 import type { CloudCrypto } from './crypto/port';
 import { type RouteDescriptor } from './router/registry';
@@ -197,6 +197,12 @@ export interface AgentContentReadInput {
 }
 /** Task-free exact-device projection desired state, intentionally unrelated to TaskAttempt. */
 export type AgentHomeProjectionInput = AgentHomeProjectionPayload;
+/**
+ * Task-free sealed provider provisioning notice: exactly `{ requestId }`. The
+ * sealed request itself stays in the Host's own store and is fetched by the
+ * device over Host routes; nothing else can be carried by this input.
+ */
+export type ProviderProvisioningNoticeInput = ProviderProvisioningAvailablePayload;
 /** Exact request identity a host must echo to read back durable projection status. */
 export type AgentHomeProjectionStatusInput = AgentHomeProjectionReceiptInput;
 /** Task-free exact-device remote preparation request, intentionally unrelated to TaskAttempt. */
@@ -285,7 +291,7 @@ export interface ByokCloud {
      * Host control plane: enqueue an offer for an already-counted preparation.
      *
      * Admission requires the device to durably advertise both the Agent-home
-     * contract and `agent-input-preparation-v7` — the second because only a device
+     * contract and `agent-input-preparation-v8` — the second because only a device
      * that can prepare holds the durable record this offer names. A device that
      * advertises neither never receives the message, and a device whose protocol
      * build predates the type skips it whole rather than running it as an
@@ -320,6 +326,19 @@ export interface ByokCloud {
      * and NO delivery row behind.
      */
     enqueueInputPreparation(tenant: TenantId, deviceId: string, input: InputPreparationInput): Promise<EnqueuedInputPreparation>;
+    /**
+     * Durable, task-free `provider.provisioning.available` notice for precisely
+     * one device that durably advertised `provider-provisioning.v1`. The payload
+     * is validated strictly before admission, and admission happens before the
+     * mailbox append, so a refused call leaves no delivery row behind.
+     *
+     * Idempotent per (tenant, device, requestId): the mailbox message id is
+     * derived from that identity, so a retried enqueue returns the existing row
+     * and its seq instead of appending a second notice. The completion and its
+     * durable readback are Host authority on Host routes; this plane records no
+     * provisioning receipt of its own.
+     */
+    enqueueProviderProvisioningNotice(tenant: TenantId, deviceId: string, input: ProviderProvisioningNoticeInput): Promise<EnqueuedAgentControl>;
     /** Tenant/device/request-bound durable desired-state and terminal-outcome readback. */
     getInputPreparationStatus(tenant: TenantId, deviceId: string, input: InputPreparationStatusInput): Promise<InputPreparationReadback | undefined>;
     /** Direct device completion endpoint authority; first exact terminal receipt wins. */

package/dist/index.d.ts

@@ -16,7 +16,7 @@ export { isTenantId, tenantId } from '@byok-sdk/core';
 export type { TenantId } from '@byok-sdk/core';
 export { createByokCloud } from './cloud';
 export type { TaskAgentMessage } from './task-agent-message';
-export type { ByokCloud, ByokCloudOptions, AgentDispatchInput, AgentEgressDispatchInput, AgentEgressFreshSessionDispatchInput, AgentContentReadInput, AgentHomeProjectionInput, AgentHomeProjectionStatusInput, InputPreparationInput, InputPreparationStatusInput, ApproveTaskOptions, EnqueueOfferInput, EnqueueToolsetOfferInput, RejectTaskOptions, EnqueuedAgentControl, EnqueuedAgentHomeProjection, EnqueuedInputPreparation, EnqueuedOffer, TaskOfferReadback, } from './cloud';
+export type { ByokCloud, ByokCloudOptions, AgentDispatchInput, AgentEgressDispatchInput, AgentEgressFreshSessionDispatchInput, AgentContentReadInput, AgentHomeProjectionInput, ProviderProvisioningNoticeInput, AgentHomeProjectionStatusInput, InputPreparationInput, InputPreparationStatusInput, ApproveTaskOptions, EnqueueOfferInput, EnqueueToolsetOfferInput, RejectTaskOptions, EnqueuedAgentControl, EnqueuedAgentHomeProjection, EnqueuedInputPreparation, EnqueuedOffer, TaskOfferReadback, } from './cloud';
 export { agentHomeProjectionCompletionKey, agentHomeProjectionRequestKey, readAgentHomeProjectionStatus, recordAgentHomeProjectionCompletion, } from './agent-home-projections';
 export type { AgentHomeProjectionReceiptInput } from './agent-home-projections';
 export { inputPreparationCompletionKey, inputPreparationRequestKey, readInputPreparationStatus, recordInputPreparationCompletion, sameInputPreparationRequest, } from './input-preparations';

package/dist/index.js

@@ -1,7 +1,7 @@
 import { BOARD_STATUSES, CapabilityDeclarationSchema, NONCE_SIGNING_DOMAIN, hasCapability, isTenantId, tenantId, principalTenant, parseDeviceProofEnvelope, deviceProofSigningInput, contentHash, parseCapabilityDeclaration, ByokCoreError, tenantKey, PRESENCE_LEVELS, createInMemoryCoreStores, authenticateDeviceAssertion, authenticateTaskAssertion, assertCapability, isCoreConflictError, isCoreError, DEVICE_PROOF_HEADER, TRUTH_RECORD_KINDS, STORAGE_ERROR_CODES, STORAGE_ERROR_HTTP_STATUS } from '@byok-sdk/core';
 export { DEVICE_PROOF_HEADER, NONCE_SIGNING_DOMAIN, isTenantId, tenantId } from '@byok-sdk/core';
 import { z } from 'zod';
-import { AgentEventOrUnknownSchema, AgentMessageServerContextSchema, AgentMessageEgressRequirementSchema, AgentRefSchema, TaskOfferForAgentWithEgressFreshPayloadSchema, PROTOCOL_VERSION, DAEMON_TO_SERVER_TYPES, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY, encodeEnvelope, decodeEnvelope, AgentHomeProjectionCompletionRequestSchema, AgentInputPreparationPayloadSchema, InputPreparationCompletionRequestSchema, BYOK_PAIR_PATH, BYOK_CHALLENGE_PATH, BYOK_TOKEN_PATH, BYOK_CAPABILITIES_PATH, BYOK_AGENT_MEMORY_PROJECTIONS_PATH, BYOK_EVENTS_PATH, BYOK_MESSAGES_PATH, BYOK_AGENT_HOME_PROJECTION_COMPLETION_ROUTE, BYOK_INPUT_PREPARATION_COMPLETION_ROUTE, BYOK_INPUT_PREPARATION_STATUS_ROUTE, BYOK_BOARD_PATH, BYOK_BOARD_CLAIM_ROUTE, BYOK_BOARD_UNCLAIM_ROUTE, BYOK_BOARD_STATUS_ROUTE, BYOK_BOARD_STREAM_PATH, BYOK_PRESENCE_PATH, BYOK_ACTIVITY_PATH, BYOK_RECORDS_PATH, BYOK_RECORD_ROUTE, BYOK_SKILL_PACKS_PATH, BYOK_SKILL_PACK_FILE_ROUTE, BYOK_BLOBS_PATH, BYOK_BLOB_FINALIZE_ROUTE, BYOK_BLOB_URL_ROUTE, BYOK_BLOB_CONTENT_ROUTE, AgentMessagePublishPayloadSchema, isTaskOfferType, MESSAGE_PAYLOAD_SCHEMAS, createEnvelope, AgentHomeProjectionPayloadSchema, AgentContentReadPayloadSchema, AGENT_EGRESS_POLICY_CAPABILITY, AGENT_MESSAGE_EGRESS_CAPABILITY, TERMINAL_PROJECTION_SELECTION_CAPABILITY, TaskOfferForAgentWithEgressPayloadSchema, AGENT_INPUT_PREPARATION_CAPABILITY, AGENT_EGRESS_FRESH_SESSION_CAPABILITY, TaskOfferPreparedPayloadSchema, TaskOfferForAgentPayloadSchema, AgentMemoryProjectionMutationSchema, AgentMemoryProjectionReceiptSchema, AGENT_MEMORY_PROJECTION_MAX_ORDERING_VALUE, AgentMemoryProjectionEraseResultSchema, HarnessIdSchema, STRICT_AGENT_ONLY_CAPABILITY, AGENT_CONTENT_ARTIFACT_READ_CAPABILITY, AGENT_CONTENT_TRANSCRIPT_READ_CAPABILITY, AGENT_CONTENT_WORKSPACE_READ_CAPABILITY, AGENT_HOME_PROJECTION_CAPABILITY, PairRequestSchema, PairResponseSchema, ChallengeRequestSchema, TokenRequestSchema, AgentMemoryProjectionCommitRequestSchema, agentMemoryProjectionBase64UrlByteLength, MAILBOX_READ_AHEAD_MAX_SEQS, MAILBOX_READ_AHEAD_CAPABILITY, MessagesSendRequestSchema, InputPreparationStatusQuerySchema, PresencePublishRequestSchema, CreateBlobRequestSchema, byokBlobContentPath, AgentMessageDispositionPayloadSchema, AgentEgressAckPayloadSchema, AgentContentReceiptPayloadSchema } from '@byok-sdk/protocol';
+import { AgentEventOrUnknownSchema, AgentMessageServerContextSchema, AgentMessageEgressRequirementSchema, AgentRefSchema, TaskOfferForAgentWithEgressFreshPayloadSchema, PROTOCOL_VERSION, DAEMON_TO_SERVER_TYPES, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY, encodeEnvelope, decodeEnvelope, AgentHomeProjectionCompletionRequestSchema, AgentInputPreparationPayloadSchema, InputPreparationCompletionRequestSchema, BYOK_PAIR_PATH, BYOK_CHALLENGE_PATH, BYOK_TOKEN_PATH, BYOK_CAPABILITIES_PATH, BYOK_AGENT_MEMORY_PROJECTIONS_PATH, BYOK_EVENTS_PATH, BYOK_MESSAGES_PATH, BYOK_AGENT_HOME_PROJECTION_COMPLETION_ROUTE, BYOK_INPUT_PREPARATION_COMPLETION_ROUTE, BYOK_INPUT_PREPARATION_STATUS_ROUTE, BYOK_BOARD_PATH, BYOK_BOARD_CLAIM_ROUTE, BYOK_BOARD_UNCLAIM_ROUTE, BYOK_BOARD_STATUS_ROUTE, BYOK_BOARD_STREAM_PATH, BYOK_PRESENCE_PATH, BYOK_ACTIVITY_PATH, BYOK_RECORDS_PATH, BYOK_RECORD_ROUTE, BYOK_SKILL_PACKS_PATH, BYOK_SKILL_PACK_FILE_ROUTE, BYOK_BLOBS_PATH, BYOK_BLOB_FINALIZE_ROUTE, BYOK_BLOB_URL_ROUTE, BYOK_BLOB_CONTENT_ROUTE, AgentMessagePublishPayloadSchema, isTaskOfferType, MESSAGE_PAYLOAD_SCHEMAS, createEnvelope, ProviderProvisioningAvailablePayloadSchema, AgentHomeProjectionPayloadSchema, AgentContentReadPayloadSchema, AGENT_EGRESS_POLICY_CAPABILITY, AGENT_MESSAGE_EGRESS_CAPABILITY, TERMINAL_PROJECTION_SELECTION_CAPABILITY, TaskOfferForAgentWithEgressPayloadSchema, AGENT_INPUT_PREPARATION_CAPABILITY, AGENT_EGRESS_FRESH_SESSION_CAPABILITY, TaskOfferPreparedPayloadSchema, TaskOfferForAgentPayloadSchema, AgentMemoryProjectionMutationSchema, AgentMemoryProjectionReceiptSchema, AGENT_MEMORY_PROJECTION_MAX_ORDERING_VALUE, AgentMemoryProjectionEraseResultSchema, HarnessIdSchema, STRICT_AGENT_ONLY_CAPABILITY, AGENT_CONTENT_ARTIFACT_READ_CAPABILITY, AGENT_CONTENT_TRANSCRIPT_READ_CAPABILITY, AGENT_CONTENT_WORKSPACE_READ_CAPABILITY, AGENT_HOME_PROJECTION_CAPABILITY, PROVIDER_PROVISIONING_CAPABILITY, PairRequestSchema, PairResponseSchema, ChallengeRequestSchema, TokenRequestSchema, AgentMemoryProjectionCommitRequestSchema, agentMemoryProjectionBase64UrlByteLength, MAILBOX_READ_AHEAD_MAX_SEQS, MAILBOX_READ_AHEAD_CAPABILITY, MessagesSendRequestSchema, InputPreparationStatusQuerySchema, PresencePublishRequestSchema, CreateBlobRequestSchema, byokBlobContentPath, AgentMessageDispositionPayloadSchema, AgentEgressAckPayloadSchema, AgentContentReceiptPayloadSchema } from '@byok-sdk/protocol';
 import { Hono } from 'hono';
 
 // src/index.ts
@@ -1217,7 +1217,7 @@ var CLOUD_CAPABILITIES = {
    * DEVICE's only way to discharge a mailbox row this same deployment handed
    * it — withholding it would strand the device's redelivery cursor rather
    * than degrade a feature. For the same reason the completion route asserts
-   * no DEVICE capability either: the device-level `agent-input-preparation-v7`
+   * no DEVICE capability either: the device-level `agent-input-preparation-v8`
    * flag gates ADMISSION (`enqueueInputPreparation`) and nothing else, so an
    * unconfigured device is refused a row instead of being handed one whose
    * only honest answer — `input_preparation_unconfigured` — it could not then
@@ -4060,6 +4060,35 @@ function createByokCloud(options) {
       return { ...control, status };
     },
     getInputPreparationStatus,
+    async enqueueProviderProvisioningNotice(tenant, deviceId, input) {
+      const payload = ProviderProvisioningAvailablePayloadSchema.parse(input);
+      await assertAgentCapabilities(tenant, deviceId, [PROVIDER_PROVISIONING_CAPABILITY]);
+      const messageId = uuidFromSha256(
+        await options.crypto.sha256(
+          new TextEncoder().encode(
+            JSON.stringify({
+              domain: "byok:provider-provisioning-notice",
+              tenant,
+              deviceId,
+              requestId: payload.requestId
+            })
+          )
+        )
+      );
+      const control = await enqueueAgentControlEnvelope(
+        tenant,
+        deviceId,
+        messageId,
+        (seq) => createEnvelope("provider.provisioning.available", payload, { id: messageId, seq })
+      );
+      if (control.envelope.type !== "provider.provisioning.available" || control.envelope.payload.requestId !== payload.requestId) {
+        throw new ByokCloudError(
+          "mailbox_receipt_mismatch",
+          `Mailbox message ${messageId} does not carry provider provisioning notice ${payload.requestId}.`
+        );
+      }
+      return control;
+    },
     completeInputPreparation,
     eraseAgentMemoryProjection,
     approveTask(tenant, taskId, opts) {