@byok-sdk/cloud 0.8.1 → 0.9.0-rc.1

package/dist/agent-memory-projection.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Optional hosted Agent-memory projection ports and reference store.
+ *
+ * Local `MEMORY.md` and `notes/` remain the sole authoring authority. This
+ * module only accepts a redacted full snapshot after a host-owned authorizer
+ * grants the exact authenticated task identity; it never offers a read,
+ * import, merge, history, RAG, or product-fact surface.
+ */
+import type { TenantId } from '@byok-sdk/core';
+import { type AgentMemoryProjectionMutation, type AgentMemoryProjectionReceipt, type AgentMemoryProjectionEraseResult } from '@byok-sdk/protocol';
+export type { AgentMemoryProjectionMeteringReceipt, AgentMemoryProjectionMutation, AgentMemoryProjectionReceipt, AgentMemoryProjectionEraseResult, } from '@byok-sdk/protocol';
+export interface AgentMemoryProjectionAuthorizerInput {
+    readonly tenantId: TenantId;
+    readonly deviceId: string;
+    readonly taskId: string;
+    readonly agentRef: AgentMemoryProjectionMutation['agentRef'];
+    readonly sessionRef: AgentMemoryProjectionMutation['sessionRef'];
+    readonly runtimeId: AgentMemoryProjectionMutation['runtimeId'];
+    readonly grantRef: AgentMemoryProjectionMutation['grantRef'];
+    /** Server-granted active writer epoch; a client may not upgrade it unilaterally. */
+    readonly writerEpoch: AgentMemoryProjectionMutation['writerEpoch'];
+    readonly policyRevision: AgentMemoryProjectionMutation['policyRevision'];
+}
+export type AgentMemoryProjectionAuthorization = {
+    readonly outcome: 'authorized';
+} | {
+    readonly outcome: 'denied';
+    readonly reasonCode: string;
+};
+/**
+ * Embedder-owned consent and grant authority. A model never provides a
+ * consent flag: it presents only an opaque grantRef, which this port binds to
+ * the authenticated tenant/device/task/AgentRef/session/runtime/grant/policy
+ * identity. The host must retain an exact historical permit until its
+ * mutation is accepted, explicitly revoked, or superseded by a higher writer
+ * epoch; reaching task terminal state alone must not implicitly delete it.
+ */
+export interface AgentMemoryProjectionAuthorizer {
+    authorize(input: AgentMemoryProjectionAuthorizerInput): Promise<AgentMemoryProjectionAuthorization>;
+    /** Revoke hosted-projection authorization before the server asks the store to erase. */
+    revoke(input: {
+        readonly tenantId: TenantId;
+        readonly agentId: string;
+    }): Promise<void>;
+}
+/** Input to the durable projection store. `redactedBytes` has already been decoded from the portable base64url body. */
+export interface AgentMemoryProjectionCommitInput {
+    readonly tenantId: TenantId;
+    readonly deviceId: string;
+    readonly mutation: AgentMemoryProjectionMutation;
+    readonly redactedBytes: Uint8Array;
+}
+/**
+ * Durable hosted snapshot and immutable metering receipt authority.
+ *
+ * `commit` must hash the supplied bytes and compare them with the portable
+ * redacted hash before every write. It accepts a new epoch only at sourceSeq
+ * one, accepts same-epoch writes only gap-free, returns `idempotent` for an
+ * exact replay, and rejects stale/gap/binding/hash mismatches. The accepted
+ * snapshot and its metering receipt share one transaction boundary.
+ */
+export interface AgentMemoryProjectionStore {
+    commit(input: AgentMemoryProjectionCommitInput): Promise<AgentMemoryProjectionReceipt>;
+    /**
+     * Server-side deletion leaves a body-free epoch fence. The host must mint a
+     * later writer grant from `nextWriterEpoch`; no device/runtime is required.
+     */
+    erase(input: {
+        readonly tenantId: TenantId;
+        readonly agentId: string;
+    }): Promise<AgentMemoryProjectionEraseResult>;
+}

package/dist/capabilities.d.ts

@@ -61,6 +61,8 @@ export declare const CLOUD_CAPABILITIES: {
      * routes it would then 404.
      */
     readonly skillPacks: 'skills.pack';
+    /** Optional, one-way redacted Agent-memory snapshot mutation route. */
+    readonly agentMemoryProjection: 'agent.memory.projection';
 };
 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. */
@@ -83,6 +85,12 @@ export interface FullCapabilityDeclarationOptions {
      * existing deployment refuse to construct.
      */
     readonly includeSkillPacks?: boolean;
+    /**
+     * Hosted Agent memory is default-off: a composition needs both an embedder
+     * grant authorizer and a durable projection store before it may declare the
+     * mutation route.
+     */
+    readonly includeAgentMemoryProjection?: 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

@@ -17,11 +17,12 @@
 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 AgentContentReadPayload, type AgentHomeProjectionCompletionRequest, type AgentHomeProjectionPayload, type AgentHomeProjectionReadback, type TaskOfferPayload, type TaskOfferForAgentPayload, type TaskOfferForAgentWithEgressPayload, type TaskOfferForAgentWithEgressFreshPayload, type TaskOfferWithToolsetsPayload } from '@byok-sdk/protocol';
+import { type Envelope, type AgentContentReadPayload, type AgentMessagePublishPayload, type AgentMessageServerContext, type AgentHomeProjectionCompletionRequest, type AgentHomeProjectionPayload, type AgentHomeProjectionReadback, type AgentMemoryProjectionEraseResult, type TaskOfferPayload, type TaskOfferForAgentPayload, 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 AgentHomeProjectionReceiptInput } from './agent-home-projections';
+import type { AgentMemoryProjectionAuthorizer, AgentMemoryProjectionStore } from './agent-memory-projection';
 import type { BlobContentProxy, CloudStores, DeviceRecord, AgentEgressRecord, PairingCodeInfo, RequestReceipt, TaskAttempt } from './stores/ports';
 import { type TerminalResult } from './terminal-result';
 import type { TruthCommitter, TruthObjectDownloads } from './truth/contract';
@@ -66,6 +67,23 @@ export interface ByokCloudOptions {
     readonly capabilities: CapabilityDeclaration;
     /** Recorded on the control-plane principal every host-side call is made under. */
     readonly operatorId?: string;
+    /** Product-owned consumer; destination lookup is keyed by authenticated task context, never model input. */
+    readonly agentMessage?: {
+        consume(input: {
+            readonly tenant: TenantId;
+            readonly deviceId: string;
+            readonly taskId: string;
+            readonly context: AgentMessageServerContext;
+            readonly payload: AgentMessagePublishPayload;
+        }): Promise<{
+            readonly outcome: 'accepted' | 'held' | 'refused';
+            readonly reasonCode?: string;
+        }>;
+    };
+    /** Embedder-owned grant and consent authority for optional hosted Agent-memory projection. */
+    readonly agentMemoryProjectionAuthorizer?: AgentMemoryProjectionAuthorizer;
+    /** Durable snapshot + immutable metering receipt authority for optional hosted Agent-memory projection. */
+    readonly agentMemoryProjectionStore?: AgentMemoryProjectionStore;
     readonly maxBlobSizeBytes?: number;
     readonly longPollHoldMs?: number;
     readonly longPollIntervalMs?: number;
@@ -114,6 +132,8 @@ export interface AgentEgressDispatchInput {
     /** Supply one to make the enqueue addressable by the host's own id; otherwise cloud mints one. */
     readonly taskId?: string;
     readonly payload: TaskOfferForAgentWithEgressPayload;
+    /** Host-only product destination/freshness authority; never serialized to the daemon. */
+    readonly agentMessageContext?: AgentMessageServerContext;
 }
 /** Strict Agent dispatch whose selected runtime mints its session after start. */
 export interface AgentEgressFreshSessionDispatchInput {
@@ -121,6 +141,8 @@ export interface AgentEgressFreshSessionDispatchInput {
     readonly taskId?: string;
     /** Deliberately session-free strict payload for the fresh-runtime path. */
     readonly payload: TaskOfferForAgentWithEgressFreshPayload;
+    /** Host-only product destination/freshness authority; never serialized to the daemon. */
+    readonly agentMessageContext?: AgentMessageServerContext;
 }
 /** A task-free, independently capability-gated Agent content read. */
 export interface AgentContentReadInput {
@@ -194,6 +216,11 @@ 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>;
+    /**
+     * Server-side consent revocation and hosted projection erasure. It does not
+     * depend on a device being online and never imports anything back locally.
+     */
+    eraseAgentMemoryProjection(tenant: TenantId, agentId: string): Promise<AgentMemoryProjectionEraseResult>;
     /** Host control plane: durably request cancellation by tenant/task id. Idempotent. */
     cancelTask(tenant: TenantId, taskId: string, reason?: string): Promise<TaskAttempt>;
     readTaskAttempt(tenant: TenantId, taskId: string): Promise<TaskAttempt | undefined>;

package/dist/composition/in-memory.d.ts

@@ -10,9 +10,10 @@
 import { type CapabilityDeclaration, type Clock, type CoreStores, type SkillPackStore } from '@byok-sdk/core';
 import { type TokenSigner } from '../auth/tokens';
 import type { CloudCrypto } from '../crypto/port';
-import { type ByokCloud } from '../cloud';
+import { type ByokCloud, type ByokCloudOptions } from '../cloud';
 import type { BlobContentProxy, CloudStores } from '../stores/ports';
 import type { TruthCommitter, TruthObjectDownloads } from '../truth/contract';
+import type { AgentMemoryProjectionAuthorizer, AgentMemoryProjectionStore } from '../agent-memory-projection';
 export interface InMemoryByokCloudOptions {
     readonly clock?: Clock;
     readonly crypto?: CloudCrypto;
@@ -49,6 +50,9 @@ export interface InMemoryByokCloudOptions {
      */
     readonly skillPacks?: SkillPackStore;
     readonly skillPackPageLimit?: number;
+    readonly agentMessage?: ByokCloudOptions['agentMessage'];
+    readonly agentMemoryProjectionAuthorizer?: AgentMemoryProjectionAuthorizer;
+    readonly agentMemoryProjectionStore?: AgentMemoryProjectionStore;
 }
 export interface InMemoryByokCloud {
     readonly cloud: ByokCloud;

package/dist/errors.d.ts

@@ -63,6 +63,22 @@ 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 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. */
+    readonly agent_memory_projection_authorization_denied: 'agent_memory_projection_authorization_denied';
+    /** A redacted snapshot's decoded bytes did not match its declared hash or byte count. */
+    readonly agent_memory_projection_hash_mismatch: 'agent_memory_projection_hash_mismatch';
+    /** A writer epoch/source sequence already names a different immutable projection mutation. */
+    readonly agent_memory_projection_replay_mismatch: 'agent_memory_projection_replay_mismatch';
+    /** A hosted memory mutation came from an older writer epoch. */
+    readonly agent_memory_projection_stale_epoch: 'agent_memory_projection_stale_epoch';
+    /** A server-side erase fence prevents a deleted writer epoch from re-entering. */
+    readonly agent_memory_projection_erased_epoch: 'agent_memory_projection_erased_epoch';
+    /** A prior erase reached the protocol writer-epoch ceiling and cannot mint a later writer. */
+    readonly agent_memory_projection_epoch_exhausted: 'agent_memory_projection_epoch_exhausted';
+    /** A hosted memory mutation skipped or reset a required source sequence. */
+    readonly agent_memory_projection_sequence_gap: 'agent_memory_projection_sequence_gap';
 };
 export type CloudErrorCode = (typeof CLOUD_ERROR_CODES)[keyof typeof CLOUD_ERROR_CODES];
 export declare class ByokCloudError extends Error {

package/dist/handlers/agent-memory-projections.d.ts

@@ -0,0 +1,15 @@
+/** Device-authenticated write route for the optional one-way hosted memory projection. */
+import type { Context } from 'hono';
+import { type AgentMemoryProjectionCommitResponse } from '@byok-sdk/protocol';
+import { type DeviceRouteDeps } from './shared';
+import type { TenantStores } from '../tenant-stores';
+/**
+ * The protocol's 512 KiB redacted ceiling encodes to about 700 KiB of
+ * base64url. A finite 1 MiB request ceiling leaves room for the bounded JSON
+ * envelope and rejects oversized input before JSON.parse allocates it.
+ */
+export declare const DEFAULT_MAX_AGENT_MEMORY_PROJECTION_REQUEST_BYTES: number;
+export interface AgentMemoryProjectionRouteDeps extends DeviceRouteDeps {
+    readonly commit: (stores: TenantStores, deviceId: string, mutation: import('@byok-sdk/protocol').AgentMemoryProjectionCommitRequest, redactedBytes: Uint8Array) => Promise<AgentMemoryProjectionCommitResponse>;
+}
+export declare function agentMemoryProjectionHandler(deps: AgentMemoryProjectionRouteDeps): (c: Context) => Promise<Response>;

package/dist/handlers/messages.d.ts

@@ -20,7 +20,7 @@
  * `duplicate` for whatever already landed.
  */
 import type { Context } from 'hono';
-import { type AgentContentReceiptPayload } from '@byok-sdk/protocol';
+import { type AgentContentReceiptPayload, type AgentMessageDispositionPayload, type AgentMessagePublishPayload } from '@byok-sdk/protocol';
 import type { ActivityBounds } from '../coordination';
 import type { AgentEgressRecord } from '../stores/ports';
 import type { TenantStores } from '../tenant-stores';
@@ -35,5 +35,18 @@ export interface MessagesRouteDeps extends DeviceRouteDeps {
     readonly appendReliableEgressAck: (stores: TenantStores, record: AgentEgressRecord) => Promise<void>;
     /** Content receipt rows share the reliable spool/ack protocol but preserve their own exact payload authority. */
     readonly appendContentReceiptAck: (stores: TenantStores, deviceId: string, payload: AgentContentReceiptPayload) => Promise<void>;
+    readonly agentMessage?: {
+        consume(input: {
+            readonly tenant: TenantStores['tenant'];
+            readonly deviceId: string;
+            readonly taskId: string;
+            readonly context: import('@byok-sdk/protocol').AgentMessageServerContext;
+            readonly payload: AgentMessagePublishPayload;
+        }): Promise<{
+            readonly outcome: 'accepted' | 'held' | 'refused';
+            readonly reasonCode?: string;
+        }>;
+    };
+    readonly appendAgentMessageDisposition: (stores: TenantStores, deviceId: string, taskId: string, payload: AgentMessageDispositionPayload) => Promise<void>;
 }
 export declare function messagesHandler(deps: MessagesRouteDeps): (c: Context) => Promise<Response>;

package/dist/handlers/shared.d.ts

@@ -14,6 +14,18 @@ export interface ErrorBody {
     readonly error: string;
 }
 export declare function readJsonBody(c: Context): Promise<unknown>;
+export interface BoundedJsonBodyResult {
+    readonly body: unknown;
+    readonly tooLarge: boolean;
+}
+/**
+ * Read and parse one JSON request while retaining a hard byte ceiling before
+ * JSON.parse. The declared length is only an early rejection; the stream is
+ * still counted because chunked requests may omit Content-Length or lie about
+ * it. Invalid JSON remains represented by `body: undefined` for the caller's
+ * existing validation status.
+ */
+export declare function readBoundedJsonBody(c: Context, maximum: number): Promise<BoundedJsonBodyResult>;
 export interface DeviceRouteDeps {
     readonly bearer: BearerAuthDeps;
     readonly root: CloudRootStores;

package/dist/inbound.d.ts

@@ -27,10 +27,23 @@
  * A duplicate is still a wire-level success (§8.2): it just did not re-run
  * anything. Only `rejected`/`rate_limited` are excluded from `accepted`.
  */
-import { type Envelope } from '@byok-sdk/protocol';
+import { type AgentMessageDispositionPayload, type AgentMessagePublishPayload, type AgentMessageServerContext, type Envelope } from '@byok-sdk/protocol';
 import { type ActivityBounds } from './coordination';
 import type { TenantStores } from './tenant-stores';
 export type InboundOutcome = 'accepted' | 'duplicate' | 'rejected' | 'rate_limited';
+export declare function handleAgentMessagePublish(stores: TenantStores, deviceId: string, taskId: string, payload: AgentMessagePublishPayload, consume: ((input: {
+    readonly tenant: TenantStores['tenant'];
+    readonly deviceId: string;
+    readonly taskId: string;
+    readonly context: AgentMessageServerContext;
+    readonly payload: AgentMessagePublishPayload;
+}) => Promise<{
+    readonly outcome: 'accepted' | 'held' | 'refused';
+    readonly reasonCode?: string;
+}>) | undefined): Promise<{
+    readonly outcome: InboundOutcome;
+    readonly disposition?: AgentMessageDispositionPayload;
+}>;
 /** Receipt key a task's terminal is recorded under — the idempotency seam S3b's journal will share. */
 export declare function terminalReceiptKey(taskId: string): string;
 export declare function handleInboundEnvelope(stores: TenantStores, deviceId: string, envelope: Envelope, activityBounds?: ActivityBounds): Promise<InboundOutcome>;

package/dist/index.d.ts

@@ -25,6 +25,8 @@ export { createInMemoryByokCloud } from './composition/in-memory';
 export type { InMemoryByokCloud, InMemoryByokCloudOptions } from './composition/in-memory';
 export { ByokCloudError, CLOUD_ERROR_CODES, isCloudError } from './errors';
 export type { CloudErrorCode } from './errors';
+export { InMemoryAgentMemoryProjectionAuthorizer, InMemoryAgentMemoryProjectionStore, } from './stores/in-memory/agent-memory-projection';
+export type { AgentMemoryProjectionAuthorization, AgentMemoryProjectionEraseResult, AgentMemoryProjectionAuthorizer, AgentMemoryProjectionAuthorizerInput, AgentMemoryProjectionCommitInput, AgentMemoryProjectionMeteringReceipt, AgentMemoryProjectionMutation, AgentMemoryProjectionReceipt, AgentMemoryProjectionStore, } from './agent-memory-projection';
 export { CLOUD_CAPABILITIES, CapabilitiesResponseSchema, declares, fullCapabilityDeclaration, } from './capabilities';
 export type { CapabilitiesResponse, CloudCapability, FullCapabilityDeclarationOptions, } from './capabilities';
 export { CloudRouteRegistry, ROUTE_CLASSES, ROUTE_METHODS, routeKey } from './router/registry';