@byok-sdk/cloud 0.18.0 → 0.20.0

package/dist/auth/device-assertion.d.ts

@@ -1,4 +1,4 @@
-import { type AuthenticatedDeviceAssertion, type Clock, type DeviceAssertionExpectedBinding, type DeviceAssertionReplayAuthority } from '@byok-sdk/core';
+import { type AuthenticatedDeviceAssertion, type AuthenticatedTaskAssertion, type Clock, type DeviceAssertionExpectedBinding, type DeviceAssertionReplayAuthority } from '@byok-sdk/core';
 import type { CloudCrypto } from '../crypto/port';
 import type { DeviceDirectory } from '../stores/ports';
 export interface HostedDeviceAssertionAuthDeps {
@@ -16,3 +16,43 @@ export interface HostedDeviceAssertionAuthDeps {
  * host-owned and are never represented by this short-lived credential.
  */
 export declare function authenticateHostedDeviceAssertion(input: unknown, deps: HostedDeviceAssertionAuthDeps): Promise<AuthenticatedDeviceAssertion | undefined>;
+/**
+ * The task lane needs exactly the same hosted authorities as the device lane —
+ * the same directory rows, the same verifier, the same replay ledger, the same
+ * clock and the same expected binding. An alias rather than a second interface,
+ * because two structurally identical declarations are two places for the
+ * hosted composition's requirements to drift apart.
+ */
+export type HostedTaskAssertionAuthDeps = HostedDeviceAssertionAuthDeps;
+/**
+ * Hosted composition for the task-scoped tool-authority exchange
+ * (`byok-task-assertion-v1`, contract §8.1 / §8.2(2)).
+ *
+ * Everything §8.2(2) puts on this side is here or in the core function it
+ * composes: strict parse, the CURRENT device row (exists, not revoked, legal
+ * key), signature, exact issuer/product/audience, valid time window, the TTL
+ * ceiling, and one atomic `jti` consumption under the task lane's own `schema`
+ * segment — so the same `jti` presented as a device assertion and as a task
+ * assertion occupies two key slots and neither lane can burn the other's. The
+ * replay segment is chosen inside core from the envelope kind; this function
+ * deliberately has no say in it, because a caller able to name the segment
+ * would be a caller able to spend the other lane's key.
+ *
+ * A DEVICE envelope presented here authenticates as `undefined`, always: §8.1
+ * gives the task lane zero acceptance and zero fallback, and that is a property
+ * of core's parser (`parseTaskAssertionEnvelope`), not a branch anyone here
+ * could relax.
+ *
+ * A replay store that cannot answer REJECTS the promise rather than resolving
+ * to a principal — §8.2(2)'s "an unavailable replay store fails, it does not
+ * downgrade authentication". A host turns that into an availability error; it
+ * must never turn it into signature-only acceptance.
+ *
+ * What this deliberately does NOT do is the frozen-offer check — that the
+ * task, AgentRef and toolset in the claims belong to THIS Execution, and that
+ * the Execution still permits a new tool call. That authority is the host's
+ * (§8.2(3)), and a parameter for it here would be an invitation to synthesize
+ * it. This function's answer is "these claims are authentic and spent once",
+ * never "this invocation is admitted".
+ */
+export declare function authenticateHostedTaskAssertion(input: unknown, deps: HostedTaskAssertionAuthDeps): Promise<AuthenticatedTaskAssertion | undefined>;

package/dist/capabilities.d.ts

@@ -63,6 +63,42 @@ export declare const CLOUD_CAPABILITIES: {
     readonly skillPacks: 'skills.pack';
     /** Optional, one-way redacted Agent-memory snapshot mutation route. */
     readonly agentMemoryProjection: 'agent.memory.projection';
+    /**
+     * Remote authenticated runtime input preparation (C07 G4): the host control
+     * plane enqueues `agent.input.preparation` and the device discharges it
+     * through the completion/status pair.
+     *
+     * Informational like `host-mcp-task-context`, not route-gating. Both routes
+     * mount unconditionally (`cloud.ts`) because the completion route is the
+     * 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-v5`
+     * 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
+     * record. What declaring THIS capability promises is that this deployment's
+     * host side actually drives the lane, which is what a Host reads before
+     * calling `enqueueInputPreparation` instead of probing.
+     */
+    readonly inputPreparation: 'agent.input.preparation';
+    /**
+     * Contract §8.1's capability gate for task-scoped tool authority
+     * (`byok-task-assertion-v1`), deployment-level channel.
+     *
+     * The SAME literal name `@byok-sdk/protocol`'s
+     * `HOST_MCP_TASK_CONTEXT_CAPABILITY` carries on the device-level channel —
+     * §8.1 requires both to be in place, and a name spelled differently in the
+     * two would make "both" unverifiable.
+     *
+     * Unlike its siblings above this capability mounts no route in this package:
+     * what a deployment promises by declaring it is that its host side actually
+     * VERIFIES task assertions (`authenticateHostedTaskAssertion` plus the frozen
+     * offer check that only the host can make). That is why it is default-off
+     * below and not derivable from anything this package can inspect — §8.2(1):
+     * the capability is declared only once it is completely implemented.
+     */
+    readonly hostMcpTaskContext: 'host-mcp-task-context';
 };
 export type CloudCapability = (typeof CLOUD_CAPABILITIES)[keyof typeof CLOUD_CAPABILITIES];
 /** The wire DTO for `GET /byok/capabilities` — core's shape, bound to a cloud-owned route. */
@@ -91,6 +127,13 @@ export interface FullCapabilityDeclarationOptions {
      * mutation route.
      */
     readonly includeAgentMemoryProjection?: boolean;
+    /**
+     * Contract §8.2(1): the task lane is declared only by a deployment whose host
+     * side verifies task assertions end to end. There is nothing this package can
+     * probe to decide that for an embedder, and guessing would declare a gate the
+     * deployment does not hold — so it is off unless a composition says otherwise.
+     */
+    readonly includeHostMcpTaskContext?: boolean;
 }
 /** Every capability the standard composition can serve, plus explicitly wired composition-bound ones. */
 export declare function fullCapabilityDeclaration(version?: number, options?: FullCapabilityDeclarationOptions): CapabilityDeclaration;

package/dist/cloud.d.ts

@@ -19,12 +19,13 @@ 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 AgentMemoryProjectionEraseResult, type TaskOfferPayload, type TaskSteerPayload, type TaskOfferForAgentPayload, 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 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';
 import { type ByokCloudObserver } from './inbound';
 import { type AgentHomeProjectionReceiptInput } from './agent-home-projections';
+import { type InputPreparationReceiptInput } from './input-preparations';
 import type { AgentMemoryProjectionAuthorizer, AgentMemoryProjectionStore } from './agent-memory-projection';
 import type { BlobContentProxy, CloudStores, DeviceRecord, AgentEgressRecord, PairingCodeInfo, RequestReceipt, TaskAttempt, TaskAttemptListQuery, TaskAttemptPage } from './stores/ports';
 import { type DeviceTerminal, type TerminalResult } from './terminal-result';
@@ -155,6 +156,22 @@ export interface AgentDispatchInput {
     /** Strict Agent payload carrying the exact opaque AgentRef. */
     readonly payload: TaskOfferForAgentPayload;
 }
+/**
+ * Strict dispatch of an already-counted preparation back to the device that
+ * counted it.
+ *
+ * Deliberately NOT an optional field on {@link AgentDispatchInput}: the wire
+ * message is distinct for the freeze-rule reason documented on
+ * `TaskOfferPreparedPayloadSchema`, and a host API that could express both
+ * through one input would let a caller reach the ordinary lane by omitting one
+ * property.
+ */
+export interface PreparedDispatchInput {
+    /** Supply one to make the enqueue addressable by the host's own id; otherwise cloud mints one. */
+    readonly taskId?: string;
+    /** Instruction-free strict payload naming the preparation this Execution consumes. */
+    readonly payload: TaskOfferPreparedPayload;
+}
 /** Strict Agent dispatch that supplies the policy consumed by the typed egress lanes. */
 export interface AgentEgressDispatchInput {
     /** Supply one to make the enqueue addressable by the host's own id; otherwise cloud mints one. */
@@ -180,6 +197,10 @@ export interface AgentContentReadInput {
 export type AgentHomeProjectionInput = AgentHomeProjectionPayload;
 /** 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. */
+export type InputPreparationInput = AgentInputPreparationPayload;
+/** Exact request identity a host must echo to read back durable preparation status. */
+export type InputPreparationStatusInput = InputPreparationReceiptInput;
 /** Optional targeting for {@link ByokCloud.approveTask}. */
 export interface ApproveTaskOptions {
     /**
@@ -201,6 +222,9 @@ export interface EnqueuedAgentControl {
 export interface EnqueuedAgentHomeProjection extends EnqueuedAgentControl {
     readonly status: AgentHomeProjectionReadback;
 }
+export interface EnqueuedInputPreparation extends EnqueuedAgentControl {
+    readonly status: InputPreparationReadback;
+}
 /** Immutable executable offer authority, independent of mailbox retention. */
 export type TaskOfferReadback = {
     [T in TaskOfferType]: {
@@ -255,6 +279,17 @@ export interface ByokCloud {
      * before either the mailbox append or task-attempt open.
      */
     enqueueAgentOffer(tenant: TenantId, deviceId: string, input: AgentDispatchInput): Promise<EnqueuedOffer>;
+    /**
+     * 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-v5` — 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
+     * ordinary instruction offer.
+     */
+    enqueuePreparedOffer(tenant: TenantId, deviceId: string, input: PreparedDispatchInput): Promise<EnqueuedOffer>;
     /**
      * Host control plane: enqueue the typed egress-policy Agent offer. Missing
      * egress/reliable-ack capabilities reject before a mailbox row is allocated.
@@ -276,6 +311,17 @@ export interface ByokCloud {
     getAgentHomeProjectionStatus(tenant: TenantId, deviceId: string, input: AgentHomeProjectionStatusInput): Promise<AgentHomeProjectionReadback | undefined>;
     /** Direct device completion endpoint authority; first exact terminal receipt wins. */
     completeAgentHomeProjection(tenant: TenantId, deviceId: string, receipt: AgentHomeProjectionCompletionRequest): Promise<AgentHomeProjectionReadback>;
+    /**
+     * Durable, task-free remote input preparation for precisely one admitted
+     * device. Capability admission, the immutable desired receipt and the
+     * mailbox append happen in that order, so a refused call leaves NO receipt
+     * and NO delivery row behind.
+     */
+    enqueueInputPreparation(tenant: TenantId, deviceId: string, input: InputPreparationInput): Promise<EnqueuedInputPreparation>;
+    /** 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. */
+    completeInputPreparation(tenant: TenantId, deviceId: string, receipt: InputPreparationCompletionRequest): Promise<InputPreparationReadback>;
     /**
      * Server-side consent revocation and hosted projection erasure. It does not
      * depend on a device being online and never imports anything back locally.

package/dist/errors.d.ts

@@ -72,6 +72,16 @@ export declare const CLOUD_ERROR_CODES: {
     readonly agent_home_projection_receipt_mismatch: 'agent_home_projection_receipt_mismatch';
     /** A receipt-store row at the projection namespace violated the frozen projection schema. */
     readonly agent_home_projection_receipt_invalid: 'agent_home_projection_receipt_invalid';
+    /** A remote input-preparation request id already names a different immutable desired request. */
+    readonly input_preparation_request_conflict: 'input_preparation_request_conflict';
+    /** A device completion did not identify a stored desired request for this exact device. */
+    readonly input_preparation_request_not_found: 'input_preparation_request_not_found';
+    /** A device completion changed the first durable terminal outcome. */
+    readonly input_preparation_completion_conflict: 'input_preparation_completion_conflict';
+    /** A completion did not exactly echo its immutable desired request/Agent/policy binding. */
+    readonly input_preparation_receipt_mismatch: 'input_preparation_receipt_mismatch';
+    /** A receipt-store row at the preparation namespace violated the frozen schema. */
+    readonly input_preparation_receipt_invalid: 'input_preparation_receipt_invalid';
     /** A hosted Agent-memory mutation did not match the durable task/device/AgentRef binding. */
     readonly agent_memory_projection_task_mismatch: 'agent_memory_projection_task_mismatch';
     /** The embedder-owned grant/consent authority denied a hosted memory mutation. */

package/dist/handlers/input-preparations.d.ts

@@ -0,0 +1,17 @@
+/** Device-authenticated completion and readback for remote input preparations. */
+import type { Context } from 'hono';
+import { type InputPreparationCompletionRequest, type InputPreparationReadback } from '@byok-sdk/protocol';
+import { type DeviceRouteDeps } from './shared';
+import type { TenantStores } from '../tenant-stores';
+export interface InputPreparationRouteDeps extends DeviceRouteDeps {
+    readonly complete: (stores: TenantStores, deviceId: string, receipt: InputPreparationCompletionRequest) => Promise<InputPreparationReadback>;
+    readonly status: (stores: TenantStores, deviceId: string, input: {
+        readonly requestId: string;
+        readonly agentRef: {
+            readonly agentId: string;
+            readonly profileRevision: string;
+        };
+    }) => Promise<InputPreparationReadback | undefined>;
+}
+export declare function inputPreparationCompletionHandler(deps: InputPreparationRouteDeps): (c: Context) => Promise<Response>;
+export declare function inputPreparationStatusHandler(deps: InputPreparationRouteDeps): (c: Context) => Promise<Response>;

package/dist/index.d.ts

@@ -16,9 +16,11 @@ 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, ApproveTaskOptions, EnqueueOfferInput, EnqueueToolsetOfferInput, RejectTaskOptions, EnqueuedAgentControl, EnqueuedAgentHomeProjection, EnqueuedOffer, TaskOfferReadback, } from './cloud';
+export type { ByokCloud, ByokCloudOptions, AgentDispatchInput, AgentEgressDispatchInput, AgentEgressFreshSessionDispatchInput, AgentContentReadInput, AgentHomeProjectionInput, 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';
+export type { InputPreparationReceiptInput } from './input-preparations';
 export { AGENT_HOME_CONTRACT_CAPABILITY, DEFAULT_EVENTS_PAGE_LIMIT, DEFAULT_LONG_POLL_HOLD_MS, DEFAULT_LONG_POLL_INTERVAL_MS, DEFAULT_MAX_BLOB_SIZE_BYTES, } from './cloud';
 export { DEFAULT_BOARD_PAGE_LIMIT, DEFAULT_BOARD_STREAM_HEARTBEAT_INTERVAL_MS, DEFAULT_BOARD_STREAM_QUERY_INTERVAL_MS, DEFAULT_BOARD_STREAM_RECONCILIATION_INTERVAL_MS, } from './handlers/board';
 export { DEFAULT_SKILL_PACK_PAGE_LIMIT } from './handlers/skill-packs';
@@ -39,8 +41,8 @@ export { authenticateBearer, extractBearerToken } from './auth/bearer';
 export type { BearerAuthDeps } from './auth/bearer';
 export { DEFAULT_DEVICE_PROOF_CLOCK_SKEW_MS, DEFAULT_DEVICE_PROOF_MAX_LIFETIME_MS, MAX_DEVICE_PROOF_CLOCK_SKEW_MS, MAX_DEVICE_PROOF_MAX_LIFETIME_MS, authenticateDeviceProof, } from './auth/device-proof';
 export type { AuthenticatedDeviceProof, DeviceProofAuthDeps, DeviceProofRequestBinding, } from './auth/device-proof';
-export { authenticateHostedDeviceAssertion } from './auth/device-assertion';
-export type { HostedDeviceAssertionAuthDeps } from './auth/device-assertion';
+export { authenticateHostedDeviceAssertion, authenticateHostedTaskAssertion } from './auth/device-assertion';
+export type { HostedDeviceAssertionAuthDeps, HostedTaskAssertionAuthDeps } from './auth/device-assertion';
 export { DEVICE_IDENTITY_PROOF_KEY_EPOCH, DEVICE_IDENTITY_PROOF_KEY_ID, PAIRING_CODE_TTL_MS, createAuthPlane, } from './auth/plane';
 export type { AuthPlane, AuthPlaneDeps, MintedAccessToken, PairInput } from './auth/plane';
 export { createWebCrypto } from './crypto/web-crypto';