@byok-sdk/cloud 0.7.0 → 0.8.0

package/dist/agent-home-projections.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Durable task-free Agent-home projection facts.
+ *
+ * Desired projection and completion are deliberately two immutable request
+ * receipts.  The receipt store is tenant-scoped and first-write-wins, so the
+ * composition does not need a second mutable projection authority merely to
+ * survive a process restart.
+ */
+import { type AgentHomeProjectionPayload, type AgentHomeProjectionCompletionRequest, type AgentHomeProjectionReadback } from '@byok-sdk/protocol';
+import type { TenantId } from '@byok-sdk/core';
+import type { TenantBoundReceipts } from './tenant-stores';
+export interface AgentHomeProjectionReceiptInput {
+    readonly requestId: string;
+    readonly agentRef: AgentHomeProjectionPayload['agentRef'];
+    readonly projectionHash: AgentHomeProjectionPayload['projectionHash'];
+}
+export declare function agentHomeProjectionRequestKey(deviceId: string, requestId: string): string;
+export declare function agentHomeProjectionCompletionKey(deviceId: string, requestId: string): string;
+export declare function sameAgentHomeProjectionRequest(expected: AgentHomeProjectionPayload, actual: AgentHomeProjectionPayload): boolean;
+export declare function receiptMatchesAgentHomeProjection(request: AgentHomeProjectionPayload, receipt: AgentHomeProjectionCompletionRequest): boolean;
+export declare function statusInputMatchesAgentHomeProjection(request: AgentHomeProjectionPayload, input: AgentHomeProjectionReceiptInput): boolean;
+export declare function readAgentHomeProjectionStatus(receipts: TenantBoundReceipts, tenant: TenantId, deviceId: string, input: AgentHomeProjectionReceiptInput): Promise<AgentHomeProjectionReadback | undefined>;
+export declare function recordAgentHomeProjectionCompletion(receipts: TenantBoundReceipts, tenant: TenantId, deviceId: string, receiptInput: AgentHomeProjectionCompletionRequest): Promise<AgentHomeProjectionReadback>;

package/dist/cloud.d.ts

@@ -17,10 +17,11 @@
 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 TaskOfferPayload, type TaskOfferForAgentPayload, type TaskOfferForAgentWithEgressPayload, type TaskOfferWithToolsetsPayload } from '@byok-sdk/protocol';
+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 { 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 { BlobContentProxy, CloudStores, DeviceRecord, AgentEgressRecord, PairingCodeInfo, RequestReceipt, TaskAttempt } from './stores/ports';
 import { type TerminalResult } from './terminal-result';
 import type { TruthCommitter, TruthObjectDownloads } from './truth/contract';
@@ -114,14 +115,28 @@ export interface AgentEgressDispatchInput {
     readonly taskId?: string;
     readonly payload: TaskOfferForAgentWithEgressPayload;
 }
+/** Strict Agent dispatch whose selected runtime mints its session after start. */
+export interface AgentEgressFreshSessionDispatchInput {
+    /** Supply one to make the enqueue addressable by the host's own id; otherwise cloud mints one. */
+    readonly taskId?: string;
+    /** Deliberately session-free strict payload for the fresh-runtime path. */
+    readonly payload: TaskOfferForAgentWithEgressFreshPayload;
+}
 /** A task-free, independently capability-gated Agent content read. */
 export interface AgentContentReadInput {
     readonly payload: AgentContentReadPayload;
 }
+/** Task-free exact-device projection desired state, intentionally unrelated to TaskAttempt. */
+export type AgentHomeProjectionInput = AgentHomeProjectionPayload;
+/** Exact request identity a host must echo to read back durable projection status. */
+export type AgentHomeProjectionStatusInput = AgentHomeProjectionReceiptInput;
 export interface EnqueuedAgentControl {
     readonly seq: number;
     readonly envelope: Envelope;
 }
+export interface EnqueuedAgentHomeProjection extends EnqueuedAgentControl {
+    readonly status: AgentHomeProjectionReadback;
+}
 export interface EnqueuedOffer {
     readonly taskId: string;
     /** The per-(tenant, device) delivery seq — the daemon's redelivery cursor position for this envelope. */
@@ -165,8 +180,20 @@ export interface ByokCloud {
      * egress/reliable-ack capabilities reject before a mailbox row is allocated.
      */
     enqueueAgentEgressOffer(tenant: TenantId, deviceId: string, input: AgentEgressDispatchInput): Promise<EnqueuedOffer>;
+    /**
+     * Host control plane: enqueue the distinct fresh-session egress offer.
+     * The device must durably advertise fresh-session support before task or
+     * mailbox reservation, so older resume-only daemons never receive it.
+     */
+    enqueueFreshAgentEgressOffer(tenant: TenantId, deviceId: string, input: AgentEgressFreshSessionDispatchInput): Promise<EnqueuedOffer>;
     /** Host control plane: request one policy-bound content read without a task fallback. */
     enqueueAgentContentRead(tenant: TenantId, deviceId: string, input: AgentContentReadInput): Promise<EnqueuedAgentControl>;
+    /** Durable, task-free projection request for precisely one admitted device. */
+    enqueueAgentHomeProjection(tenant: TenantId, deviceId: string, input: AgentHomeProjectionInput): Promise<EnqueuedAgentHomeProjection>;
+    /** Tenant/device/request-bound durable desired-state and terminal-outcome readback. */
+    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>;
     /** 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/errors.d.ts

@@ -53,6 +53,16 @@ export declare const CLOUD_ERROR_CODES: {
     readonly agent_content_request_mismatch: 'agent_content_request_mismatch';
     /** A durable mailbox receipt id resolved to an envelope other than its exact acknowledgement. */
     readonly mailbox_receipt_mismatch: 'mailbox_receipt_mismatch';
+    /** A task-free Agent-home request id already names a different immutable desired projection. */
+    readonly agent_home_projection_request_conflict: 'agent_home_projection_request_conflict';
+    /** A direct Agent-home completion did not identify a stored desired request for this exact device. */
+    readonly agent_home_projection_request_not_found: 'agent_home_projection_request_not_found';
+    /** A direct Agent-home completion changed the first durable terminal outcome. */
+    readonly agent_home_projection_completion_conflict: 'agent_home_projection_completion_conflict';
+    /** A task-free completion did not exactly echo its immutable desired projection binding. */
+    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';
 };
 export type CloudErrorCode = (typeof CLOUD_ERROR_CODES)[keyof typeof CLOUD_ERROR_CODES];
 export declare class ByokCloudError extends Error {

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

@@ -0,0 +1,9 @@
+/** Device-authenticated exact completion readback for task-free Agent-home projections. */
+import type { Context } from 'hono';
+import { type AgentHomeProjectionCompletionRequest, type AgentHomeProjectionReadback } from '@byok-sdk/protocol';
+import { type DeviceRouteDeps } from './shared';
+import type { TenantStores } from '../tenant-stores';
+export interface AgentHomeProjectionRouteDeps extends DeviceRouteDeps {
+    readonly complete: (stores: TenantStores, deviceId: string, receipt: AgentHomeProjectionCompletionRequest) => Promise<AgentHomeProjectionReadback>;
+}
+export declare function agentHomeProjectionCompletionHandler(deps: AgentHomeProjectionRouteDeps): (c: Context) => Promise<Response>;

package/dist/index.d.ts

@@ -15,7 +15,9 @@
 export { isTenantId, tenantId } from '@byok-sdk/core';
 export type { TenantId } from '@byok-sdk/core';
 export { createByokCloud } from './cloud';
-export type { ByokCloud, ByokCloudOptions, AgentDispatchInput, AgentEgressDispatchInput, AgentContentReadInput, EnqueueOfferInput, EnqueueToolsetOfferInput, EnqueuedAgentControl, EnqueuedOffer, } from './cloud';
+export type { ByokCloud, ByokCloudOptions, AgentDispatchInput, AgentEgressDispatchInput, AgentEgressFreshSessionDispatchInput, AgentContentReadInput, AgentHomeProjectionInput, AgentHomeProjectionStatusInput, EnqueueOfferInput, EnqueueToolsetOfferInput, EnqueuedAgentControl, EnqueuedAgentHomeProjection, EnqueuedOffer, } from './cloud';
+export { agentHomeProjectionCompletionKey, agentHomeProjectionRequestKey, readAgentHomeProjectionStatus, recordAgentHomeProjectionCompletion, } from './agent-home-projections';
+export type { AgentHomeProjectionReceiptInput } from './agent-home-projections';
 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';

package/dist/index.js

@@ -1,6 +1,6 @@
 import { BOARD_STATUSES, CapabilityDeclarationSchema, NONCE_SIGNING_DOMAIN, hasCapability, isTenantId, tenantId, principalTenant, parseDeviceProofEnvelope, deviceProofSigningInput, contentHash, parseCapabilityDeclaration, ByokCoreError, tenantKey, PRESENCE_LEVELS, createInMemoryCoreStores, authenticateDeviceAssertion, 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 { AgentEventOrUnknownSchema, PROTOCOL_VERSION, DAEMON_TO_SERVER_TYPES, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY, encodeEnvelope, decodeEnvelope, BYOK_PAIR_PATH, BYOK_CHALLENGE_PATH, BYOK_TOKEN_PATH, BYOK_CAPABILITIES_PATH, BYOK_EVENTS_PATH, BYOK_MESSAGES_PATH, 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, createEnvelope, AgentContentReadPayloadSchema, AGENT_EGRESS_POLICY_CAPABILITY, TaskOfferForAgentWithEgressPayloadSchema, TaskOfferForAgentPayloadSchema, AGENT_CONTENT_ARTIFACT_READ_CAPABILITY, AGENT_CONTENT_TRANSCRIPT_READ_CAPABILITY, AGENT_CONTENT_WORKSPACE_READ_CAPABILITY, PairRequestSchema, PairResponseSchema, ChallengeRequestSchema, TokenRequestSchema, MessagesSendRequestSchema, PresencePublishRequestSchema, CreateBlobRequestSchema, byokBlobContentPath, AgentEgressAckPayloadSchema, AgentContentReceiptPayloadSchema } from '@byok-sdk/protocol';
+import { AgentEventOrUnknownSchema, PROTOCOL_VERSION, DAEMON_TO_SERVER_TYPES, AGENT_EGRESS_RELIABLE_ACK_CAPABILITY, encodeEnvelope, AgentHomeProjectionCompletionRequestSchema, decodeEnvelope, BYOK_PAIR_PATH, BYOK_CHALLENGE_PATH, BYOK_TOKEN_PATH, BYOK_CAPABILITIES_PATH, BYOK_EVENTS_PATH, BYOK_MESSAGES_PATH, BYOK_AGENT_HOME_PROJECTION_COMPLETION_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, createEnvelope, AgentHomeProjectionPayloadSchema, AgentContentReadPayloadSchema, AGENT_EGRESS_POLICY_CAPABILITY, TaskOfferForAgentWithEgressFreshPayloadSchema, TaskOfferForAgentWithEgressPayloadSchema, TaskOfferForAgentPayloadSchema, AGENT_CONTENT_ARTIFACT_READ_CAPABILITY, AGENT_CONTENT_TRANSCRIPT_READ_CAPABILITY, AGENT_CONTENT_WORKSPACE_READ_CAPABILITY, AGENT_HOME_PROJECTION_CAPABILITY, AGENT_EGRESS_FRESH_SESSION_CAPABILITY, PairRequestSchema, PairResponseSchema, ChallengeRequestSchema, TokenRequestSchema, MessagesSendRequestSchema, PresencePublishRequestSchema, CreateBlobRequestSchema, byokBlobContentPath, AgentEgressAckPayloadSchema, AgentContentReceiptPayloadSchema } from '@byok-sdk/protocol';
 import { z } from 'zod';
 import { Hono } from 'hono';
 
@@ -329,7 +329,17 @@ var CLOUD_ERROR_CODES = {
   /** A first-write-wins Agent control record was replayed with a different body. */
   agent_content_request_mismatch: "agent_content_request_mismatch",
   /** A durable mailbox receipt id resolved to an envelope other than its exact acknowledgement. */
-  mailbox_receipt_mismatch: "mailbox_receipt_mismatch"
+  mailbox_receipt_mismatch: "mailbox_receipt_mismatch",
+  /** A task-free Agent-home request id already names a different immutable desired projection. */
+  agent_home_projection_request_conflict: "agent_home_projection_request_conflict",
+  /** A direct Agent-home completion did not identify a stored desired request for this exact device. */
+  agent_home_projection_request_not_found: "agent_home_projection_request_not_found",
+  /** A direct Agent-home completion changed the first durable terminal outcome. */
+  agent_home_projection_completion_conflict: "agent_home_projection_completion_conflict",
+  /** A task-free completion did not exactly echo its immutable desired projection binding. */
+  agent_home_projection_receipt_mismatch: "agent_home_projection_receipt_mismatch",
+  /** A receipt-store row at the projection namespace violated the frozen projection schema. */
+  agent_home_projection_receipt_invalid: "agent_home_projection_receipt_invalid"
 };
 var ByokCloudError = class extends Error {
   code;
@@ -791,8 +801,10 @@ function tokenHandler(deps) {
 var CLOUD_PROTOCOL_CAPABILITIES = [
   "result-document",
   "agent-home-contract",
+  "agent-home-projection",
   "agent-egress-policy",
   "agent-egress-reliable-ack",
+  "agent-egress-fresh-session",
   "agent-content-workspace-read",
   "agent-content-transcript-read",
   "agent-content-artifact-read"
@@ -828,13 +840,13 @@ function eventsHandler(deps) {
         if (page.messages.length === 0) break;
         const decoded = page.messages.map((message) => decodeEnvelope(message.body));
         const offeredTaskIds = decoded.flatMap(
-          (event) => (event.type === "task.offer" || event.type === "task.offer_with_toolsets" || event.type === "task.offer_for_agent" || event.type === "task.offer_for_agent_with_egress") && event.task_id !== void 0 ? [event.task_id] : []
+          (event) => (event.type === "task.offer" || event.type === "task.offer_with_toolsets" || event.type === "task.offer_for_agent" || event.type === "task.offer_for_agent_with_egress" || event.type === "task.offer_for_agent_with_egress_fresh") && event.task_id !== void 0 ? [event.task_id] : []
         );
         const attemptsByTaskId = Object.fromEntries(
           (await stores.tasks.getMany(offeredTaskIds)).map((attempt2) => [attempt2.taskId, attempt2])
         );
         const events = decoded.filter((event) => {
-          if (event.type !== "task.offer" && event.type !== "task.offer_with_toolsets" && event.type !== "task.offer_for_agent" && event.type !== "task.offer_for_agent_with_egress") {
+          if (event.type !== "task.offer" && event.type !== "task.offer_with_toolsets" && event.type !== "task.offer_for_agent" && event.type !== "task.offer_for_agent_with_egress" && event.type !== "task.offer_for_agent_with_egress_fresh") {
             return true;
           }
           return event.task_id === void 0 || attemptsByTaskId[event.task_id]?.cancellation === void 0;
@@ -1222,6 +1234,35 @@ function messagesHandler(deps) {
     return c.json(response, 200);
   };
 }
+function agentHomeProjectionCompletionHandler(deps) {
+  return async (c) => {
+    const authenticated = await authenticateDevice(c, deps);
+    if (authenticated === void 0) return c.json({ error: "unauthorized" }, 401);
+    const parsed = AgentHomeProjectionCompletionRequestSchema.safeParse(await readJsonBody(c));
+    if (!parsed.success) return c.json({ error: "invalid Agent-home projection completion" }, 422);
+    const requestId = c.req.param("requestId");
+    if (requestId === void 0 || requestId !== parsed.data.requestId) {
+      return c.json({ error: "agent_home_projection_receipt_mismatch" }, 422);
+    }
+    try {
+      return c.json(
+        await deps.complete(authenticated.stores, authenticated.device.deviceId, parsed.data),
+        200
+      );
+    } catch (error) {
+      if (isCloudError(error, "agent_home_projection_request_not_found")) {
+        return c.json({ error: error.code }, 404);
+      }
+      if (isCloudError(error, "agent_home_projection_receipt_mismatch") || isCloudError(error, "agent_home_projection_receipt_invalid")) {
+        return c.json({ error: error.code }, 422);
+      }
+      if (isCloudError(error, "agent_home_projection_request_conflict") || isCloudError(error, "agent_home_projection_completion_conflict") || isCloudError(error, "agent_capability_missing")) {
+        return c.json({ error: error.code }, 409);
+      }
+      throw error;
+    }
+  };
+}
 var DEFAULT_BOARD_PAGE_LIMIT = 50;
 var DEFAULT_BOARD_STREAM_QUERY_INTERVAL_MS = 5e3;
 var DEFAULT_BOARD_STREAM_HEARTBEAT_INTERVAL_MS = 15e3;
@@ -1966,6 +2007,118 @@ var CloudRouteRegistry = class {
     return this.#app.fetch;
   }
 };
+function agentHomeProjectionRequestKey(deviceId, requestId) {
+  return `agent-home-projection:v1:${deviceId}:${requestId}:request`;
+}
+function agentHomeProjectionCompletionKey(deviceId, requestId) {
+  return `agent-home-projection:v1:${deviceId}:${requestId}:completion`;
+}
+function sameAgentHomeProjectionRequest(expected, actual) {
+  return expected.requestId === actual.requestId && expected.agentRef.agentId === actual.agentRef.agentId && expected.agentRef.profileRevision === actual.agentRef.profileRevision && expected.projectionHash === actual.projectionHash && JSON.stringify(expected.projection) === JSON.stringify(actual.projection);
+}
+function receiptMatchesAgentHomeProjection(request, receipt) {
+  return receipt.requestId === request.requestId && receipt.agentRef.agentId === request.agentRef.agentId && receipt.agentRef.profileRevision === request.agentRef.profileRevision && receipt.projectionHash === request.projectionHash;
+}
+function statusInputMatchesAgentHomeProjection(request, input) {
+  return input.requestId === request.requestId && input.agentRef.agentId === request.agentRef.agentId && input.agentRef.profileRevision === request.agentRef.profileRevision && input.projectionHash === request.projectionHash;
+}
+function parseRequestBody(body) {
+  try {
+    return AgentHomeProjectionPayloadSchema.parse(JSON.parse(body));
+  } catch (error) {
+    throw new ByokCloudError(
+      "agent_home_projection_receipt_invalid",
+      "Stored Agent-home projection request is not a valid immutable projection fact.",
+      { cause: error }
+    );
+  }
+}
+function parseCompletionBody(body) {
+  try {
+    return AgentHomeProjectionCompletionRequestSchema.parse(JSON.parse(body));
+  } catch (error) {
+    throw new ByokCloudError(
+      "agent_home_projection_receipt_invalid",
+      "Stored Agent-home projection completion is not a valid immutable receipt fact.",
+      { cause: error }
+    );
+  }
+}
+async function readAgentHomeProjectionStatus(receipts, tenant, deviceId, input) {
+  const storedRequest = await receipts.get(agentHomeProjectionRequestKey(deviceId, input.requestId));
+  if (storedRequest === void 0) return void 0;
+  const request = parseRequestBody(storedRequest.body);
+  if (!statusInputMatchesAgentHomeProjection(request, input)) {
+    throw new ByokCloudError(
+      "agent_home_projection_request_conflict",
+      `Agent-home projection request ${input.requestId} does not match its immutable desired fact.`
+    );
+  }
+  const storedCompletion = await receipts.get(agentHomeProjectionCompletionKey(deviceId, input.requestId));
+  if (storedCompletion === void 0) {
+    return {
+      tenantId: tenant,
+      deviceId,
+      requestId: request.requestId,
+      agentRef: request.agentRef,
+      projectionHash: request.projectionHash,
+      status: "pending"
+    };
+  }
+  const completion = parseCompletionBody(storedCompletion.body);
+  if (!receiptMatchesAgentHomeProjection(request, completion)) {
+    throw new ByokCloudError(
+      "agent_home_projection_receipt_mismatch",
+      `Agent-home projection completion ${input.requestId} does not match its immutable desired fact.`
+    );
+  }
+  return {
+    tenantId: tenant,
+    deviceId,
+    requestId: request.requestId,
+    agentRef: request.agentRef,
+    projectionHash: request.projectionHash,
+    status: completion.outcome,
+    completedAt: storedCompletion.recordedAt
+  };
+}
+async function recordAgentHomeProjectionCompletion(receipts, tenant, deviceId, receiptInput) {
+  const receipt = AgentHomeProjectionCompletionRequestSchema.parse(receiptInput);
+  const storedRequest = await receipts.get(agentHomeProjectionRequestKey(deviceId, receipt.requestId));
+  if (storedRequest === void 0) {
+    throw new ByokCloudError(
+      "agent_home_projection_request_not_found",
+      `Agent-home projection request ${receipt.requestId} was not found for this device.`
+    );
+  }
+  const request = parseRequestBody(storedRequest.body);
+  if (!receiptMatchesAgentHomeProjection(request, receipt)) {
+    throw new ByokCloudError(
+      "agent_home_projection_receipt_mismatch",
+      `Agent-home projection completion ${receipt.requestId} does not exactly match its desired fact.`
+    );
+  }
+  const body = JSON.stringify(receipt);
+  const storedCompletion = await receipts.record({
+    key: agentHomeProjectionCompletionKey(deviceId, receipt.requestId),
+    body
+  });
+  if (!storedCompletion.created && storedCompletion.receipt.body !== body) {
+    throw new ByokCloudError(
+      "agent_home_projection_completion_conflict",
+      `Agent-home projection request ${receipt.requestId} already has a different terminal completion.`
+    );
+  }
+  return {
+    tenantId: tenant,
+    deviceId,
+    requestId: request.requestId,
+    agentRef: request.agentRef,
+    projectionHash: request.projectionHash,
+    status: receipt.outcome,
+    completedAt: storedCompletion.receipt.recordedAt
+  };
+}
 function projectTerminalResult(taskId, receipt) {
   let envelope;
   try {
@@ -2085,6 +2238,13 @@ function createByokCloud(options) {
       })
     );
   }
+  registry.register(
+    { method: "PUT", path: BYOK_AGENT_HOME_PROJECTION_COMPLETION_ROUTE, class: "device" },
+    agentHomeProjectionCompletionHandler({
+      ...deviceRouteDeps,
+      complete: (stores, deviceId, receipt) => completeAgentHomeProjectionFromStores(stores, deviceId, receipt)
+    })
+  );
   if (declares(declaration, CLOUD_CAPABILITIES.boardCoordination)) {
     const boardDeps = {
       ...deviceRouteDeps,
@@ -2309,6 +2469,34 @@ function createByokCloud(options) {
     }
     return { seq: message.seq, envelope };
   }
+  async function getAgentHomeProjectionStatus(tenant, deviceId, input) {
+    return readAgentHomeProjectionStatus(
+      tenantStoresFor(controlPlane(tenant), root).receipts,
+      tenant,
+      deviceId,
+      input
+    );
+  }
+  async function completeAgentHomeProjection(tenant, deviceId, receiptInput) {
+    return completeAgentHomeProjectionFromStores(
+      tenantStoresFor(controlPlane(tenant), root),
+      deviceId,
+      receiptInput
+    );
+  }
+  async function completeAgentHomeProjectionFromStores(stores, deviceId, receiptInput) {
+    const receipt = AgentHomeProjectionCompletionRequestSchema.parse(receiptInput);
+    await assertAgentCapabilities(stores.tenant, deviceId, [
+      AGENT_HOME_CONTRACT_CAPABILITY,
+      AGENT_HOME_PROJECTION_CAPABILITY
+    ]);
+    return recordAgentHomeProjectionCompletion(
+      stores.receipts,
+      stores.tenant,
+      deviceId,
+      receipt
+    );
+  }
   async function enqueueReliableEgressAck(stores, record) {
     const payload = AgentEgressAckPayloadSchema.parse({
       agentRef: record.payload.agentRef,
@@ -2428,6 +2616,22 @@ function createByokCloud(options) {
         (taskId, seq, messageId) => createEnvelope("task.offer_for_agent_with_egress", payload, { id: messageId, taskId, seq })
       );
     },
+    async enqueueFreshAgentEgressOffer(tenant, deviceId, input) {
+      await assertAgentCapabilities(tenant, deviceId, [
+        AGENT_HOME_CONTRACT_CAPABILITY,
+        AGENT_EGRESS_POLICY_CAPABILITY,
+        AGENT_EGRESS_RELIABLE_ACK_CAPABILITY,
+        AGENT_EGRESS_FRESH_SESSION_CAPABILITY
+      ]);
+      const payload = TaskOfferForAgentWithEgressFreshPayloadSchema.parse(input.payload);
+      return enqueueTaskEnvelope(
+        tenant,
+        deviceId,
+        input.taskId,
+        payload.agentRef,
+        (taskId, seq, messageId) => createEnvelope("task.offer_for_agent_with_egress_fresh", payload, { id: messageId, taskId, seq })
+      );
+    },
     async enqueueAgentContentRead(tenant, deviceId, input) {
       const payload = AgentContentReadPayloadSchema.parse(input.payload);
       await assertAgentCapabilities(tenant, deviceId, [
@@ -2461,6 +2665,52 @@ function createByokCloud(options) {
       }
       return control;
     },
+    async enqueueAgentHomeProjection(tenant, deviceId, input) {
+      const payload = AgentHomeProjectionPayloadSchema.parse(input);
+      await assertAgentCapabilities(tenant, deviceId, [
+        AGENT_HOME_CONTRACT_CAPABILITY,
+        AGENT_HOME_PROJECTION_CAPABILITY
+      ]);
+      const stores = tenantStoresFor(controlPlane(tenant), root);
+      const requestBody = JSON.stringify(payload);
+      const persisted = await stores.receipts.record({
+        key: agentHomeProjectionRequestKey(deviceId, payload.requestId),
+        body: requestBody
+      });
+      const persistedPayload = AgentHomeProjectionPayloadSchema.parse(JSON.parse(persisted.receipt.body));
+      if (!sameAgentHomeProjectionRequest(payload, persistedPayload)) {
+        throw new ByokCloudError(
+          "agent_home_projection_request_conflict",
+          `Agent-home projection request ${payload.requestId} already exists with a different immutable desired body.`
+        );
+      }
+      const control = await enqueueAgentControlEnvelope(
+        tenant,
+        deviceId,
+        payload.requestId,
+        (seq) => createEnvelope("agent.home.projection", payload, { id: payload.requestId, seq })
+      );
+      if (control.envelope.type !== "agent.home.projection" || !sameAgentHomeProjectionRequest(payload, control.envelope.payload)) {
+        throw new ByokCloudError(
+          "agent_home_projection_request_conflict",
+          `Mailbox request ${payload.requestId} does not match its immutable Agent-home projection fact.`
+        );
+      }
+      const status = await getAgentHomeProjectionStatus(tenant, deviceId, {
+        requestId: payload.requestId,
+        agentRef: payload.agentRef,
+        projectionHash: payload.projectionHash
+      });
+      if (status === void 0) {
+        throw new ByokCloudError(
+          "agent_home_projection_receipt_invalid",
+          `Agent-home projection request ${payload.requestId} disappeared after durable allocation.`
+        );
+      }
+      return { ...control, status };
+    },
+    getAgentHomeProjectionStatus,
+    completeAgentHomeProjection,
     async cancelTask(tenant, taskId, reason) {
       const stores = tenantStoresFor(controlPlane(tenant), root);
       const proposedMessageId = options.crypto.randomUuid();
@@ -3591,6 +3841,6 @@ var CLOUD_PORT_INTERFACES = {
   rateLimiter: "InboundRateLimiter"
 };
 
-export { ACCESS_TOKEN_TTL_SECONDS, AGENT_HOME_CONTRACT_CAPABILITY, APPROVAL_SUMMARY_MAX_BYTES, ActivityAppendRequestSchema, AllowAllRateLimiter, ApprovalObservationSchema, ApprovalTimelineEventSchema, BLOB_READ_ERROR_CODES, BLOB_URL_TTL_MS, BoardFeedClient, BoardFeedRetryableError, BoardFeedStoppedError, ByokCloudError, CLOUD_CAPABILITIES, CLOUD_ERROR_CODES, CLOUD_PORT_INTERFACES, CLOUD_PORT_METHODS, CLOUD_STORE_NAMES, CapabilitiesResponseSchema, CloudRouteRegistry, DEDUP_RING_CAPACITY, DEFAULT_ACTIVITY_BOUNDS, DEFAULT_ACTIVITY_CAPACITY, DEFAULT_ACTIVITY_MAX_BYTES, DEFAULT_ACTIVITY_MAX_EVENTS, DEFAULT_ACTIVITY_TTL_MS, DEFAULT_APPROVAL_TIMELINE_CAPACITY, DEFAULT_APPROVAL_TIMELINE_TTL_MS, DEFAULT_BOARD_CHANNEL_MAX_BYTES, DEFAULT_BOARD_PAGE_LIMIT, DEFAULT_BOARD_STREAM_HEARTBEAT_INTERVAL_MS, DEFAULT_BOARD_STREAM_QUERY_INTERVAL_MS, DEFAULT_BOARD_STREAM_RECONCILIATION_INTERVAL_MS, DEFAULT_BOARD_TITLE_MAX_BYTES, DEFAULT_DEVICE_PROOF_CLOCK_SKEW_MS, DEFAULT_DEVICE_PROOF_MAX_LIFETIME_MS, DEFAULT_EVENTS_PAGE_LIMIT, DEFAULT_LONG_POLL_HOLD_MS, DEFAULT_LONG_POLL_INTERVAL_MS, DEFAULT_MAX_BLOB_SIZE_BYTES, DEFAULT_MAX_TRUTH_REQUEST_BYTES, DEFAULT_PRESENCE_DETAIL_MAX_BYTES, DEFAULT_PRESENCE_MINIMUM_INTERVAL_MS, DEFAULT_PRESENCE_TTL_MS, DEFAULT_SKILL_PACK_PAGE_LIMIT, DEVICE_IDENTITY_PROOF_KEY_EPOCH, DEVICE_IDENTITY_PROOF_KEY_ID, InMemoryActivityStore, InMemoryAgentEgressStore, InMemoryBlobContentProxy, InMemoryCloudBlobStore, InMemoryDeviceDirectory, InMemoryInboundDedupStore, InMemoryNonceStore, InMemoryPairingCodeStore, InMemoryProofRequestReceiptStore, InMemoryRequestReceiptStore, InMemoryTaskAttemptStore, InMemoryTaskCancellationStore, MAX_DEVICE_PROOF_CLOCK_SKEW_MS, MAX_DEVICE_PROOF_HEADER_BYTES, MAX_DEVICE_PROOF_MAX_LIFETIME_MS, NONCE_TTL_MS, PAIRING_CODE_TTL_MS, ROUTE_CLASSES, ROUTE_METHODS, TASK_ATTEMPT_STATUSES, TRUTH_BATCH_MAX_RECORDS, TRUTH_INLINE_CONTENT_TYPE, TRUTH_LABEL_MAX_LENGTH, TRUTH_MANIFEST_MAX_LIMIT, TRUTH_RECORD_CAPABILITY, TRUTH_RECORD_KEY_MAX_LENGTH, TRUTH_REQUEST_ID_MAX_LENGTH, TimelineEventSchema, TruthBodyInputSchema, TruthCommitError, TruthCommitResponseSchema, TruthRecordKeySchema, TruthRecordMetadataSchema, TruthWriteRequestSchema, activityCursor, approvalTimelineCursor, authenticateBearer, authenticateDeviceProof, authenticateHostedDeviceAssertion, createAuthPlane, createByokCloud, createHmacTokenSigner, createInMemoryBlobs, createInMemoryByokCloud, createInMemoryCloudStores, createWebCrypto, declares, extractBearerToken, fullCapabilityDeclaration, handleInboundEnvelope, isCloudError, isTruthCommitError, parseApprovalObservations, parseTimelineEvents, projectTerminalResult, projectTimelineEvents, routeKey, tenantStoresFor, terminalReceiptKey, truthManifestMetadata, truthRecordMetadata, validateActivityAppend, validateApprovalTimelineAppend, verifyNonceSignature };
+export { ACCESS_TOKEN_TTL_SECONDS, AGENT_HOME_CONTRACT_CAPABILITY, APPROVAL_SUMMARY_MAX_BYTES, ActivityAppendRequestSchema, AllowAllRateLimiter, ApprovalObservationSchema, ApprovalTimelineEventSchema, BLOB_READ_ERROR_CODES, BLOB_URL_TTL_MS, BoardFeedClient, BoardFeedRetryableError, BoardFeedStoppedError, ByokCloudError, CLOUD_CAPABILITIES, CLOUD_ERROR_CODES, CLOUD_PORT_INTERFACES, CLOUD_PORT_METHODS, CLOUD_STORE_NAMES, CapabilitiesResponseSchema, CloudRouteRegistry, DEDUP_RING_CAPACITY, DEFAULT_ACTIVITY_BOUNDS, DEFAULT_ACTIVITY_CAPACITY, DEFAULT_ACTIVITY_MAX_BYTES, DEFAULT_ACTIVITY_MAX_EVENTS, DEFAULT_ACTIVITY_TTL_MS, DEFAULT_APPROVAL_TIMELINE_CAPACITY, DEFAULT_APPROVAL_TIMELINE_TTL_MS, DEFAULT_BOARD_CHANNEL_MAX_BYTES, DEFAULT_BOARD_PAGE_LIMIT, DEFAULT_BOARD_STREAM_HEARTBEAT_INTERVAL_MS, DEFAULT_BOARD_STREAM_QUERY_INTERVAL_MS, DEFAULT_BOARD_STREAM_RECONCILIATION_INTERVAL_MS, DEFAULT_BOARD_TITLE_MAX_BYTES, DEFAULT_DEVICE_PROOF_CLOCK_SKEW_MS, DEFAULT_DEVICE_PROOF_MAX_LIFETIME_MS, DEFAULT_EVENTS_PAGE_LIMIT, DEFAULT_LONG_POLL_HOLD_MS, DEFAULT_LONG_POLL_INTERVAL_MS, DEFAULT_MAX_BLOB_SIZE_BYTES, DEFAULT_MAX_TRUTH_REQUEST_BYTES, DEFAULT_PRESENCE_DETAIL_MAX_BYTES, DEFAULT_PRESENCE_MINIMUM_INTERVAL_MS, DEFAULT_PRESENCE_TTL_MS, DEFAULT_SKILL_PACK_PAGE_LIMIT, DEVICE_IDENTITY_PROOF_KEY_EPOCH, DEVICE_IDENTITY_PROOF_KEY_ID, InMemoryActivityStore, InMemoryAgentEgressStore, InMemoryBlobContentProxy, InMemoryCloudBlobStore, InMemoryDeviceDirectory, InMemoryInboundDedupStore, InMemoryNonceStore, InMemoryPairingCodeStore, InMemoryProofRequestReceiptStore, InMemoryRequestReceiptStore, InMemoryTaskAttemptStore, InMemoryTaskCancellationStore, MAX_DEVICE_PROOF_CLOCK_SKEW_MS, MAX_DEVICE_PROOF_HEADER_BYTES, MAX_DEVICE_PROOF_MAX_LIFETIME_MS, NONCE_TTL_MS, PAIRING_CODE_TTL_MS, ROUTE_CLASSES, ROUTE_METHODS, TASK_ATTEMPT_STATUSES, TRUTH_BATCH_MAX_RECORDS, TRUTH_INLINE_CONTENT_TYPE, TRUTH_LABEL_MAX_LENGTH, TRUTH_MANIFEST_MAX_LIMIT, TRUTH_RECORD_CAPABILITY, TRUTH_RECORD_KEY_MAX_LENGTH, TRUTH_REQUEST_ID_MAX_LENGTH, TimelineEventSchema, TruthBodyInputSchema, TruthCommitError, TruthCommitResponseSchema, TruthRecordKeySchema, TruthRecordMetadataSchema, TruthWriteRequestSchema, activityCursor, agentHomeProjectionCompletionKey, agentHomeProjectionRequestKey, approvalTimelineCursor, authenticateBearer, authenticateDeviceProof, authenticateHostedDeviceAssertion, createAuthPlane, createByokCloud, createHmacTokenSigner, createInMemoryBlobs, createInMemoryByokCloud, createInMemoryCloudStores, createWebCrypto, declares, extractBearerToken, fullCapabilityDeclaration, handleInboundEnvelope, isCloudError, isTruthCommitError, parseApprovalObservations, parseTimelineEvents, projectTerminalResult, projectTimelineEvents, readAgentHomeProjectionStatus, recordAgentHomeProjectionCompletion, routeKey, tenantStoresFor, terminalReceiptKey, truthManifestMetadata, truthRecordMetadata, validateActivityAppend, validateApprovalTimelineAppend, verifyNonceSignature };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map