@frockbot/cloudflare 0.0.0 → 0.7.292

package/src/contracts.ts

@@ -0,0 +1,832 @@
+import type {
+  BotPluginsFrameV1,
+  PluginToolCommandV1,
+  SetBotPluginEnabledCommandV1,
+} from "@frockbot/app/plugins/page";
+import type { SetBotPluginEnabledReceiptV1 } from "@frockbot/app/plugins/bot";
+import type {
+  SecretListViewV1,
+  SecretSubmitCommandV1,
+  SecretSubmitReceiptV1,
+} from "@frockbot/app/secrets/shared";
+import type { BotPluginToolReceiptV1 } from "@frockbot/app/plugins/views-bot";
+import type {
+  CardActionCommandV1,
+  CardActionReceiptV1,
+  CardListViewV1,
+  CardViewV1,
+} from "@frockbot/app/shell/cards";
+import type {
+  SettingsFrame,
+  ConnectionsFrame,
+  SettingsChangeCommand,
+} from "@frockbot/core/protocol-schemas";
+import {
+  type AuthPackageV1,
+  type BotIsolateEnv,
+  type PluginWorkerEntrypoint,
+  type SessionEvent,
+} from "@frockbot/core/contracts";
+import type { MachineResultDeliveryV1 } from "@frockbot/app/machine/delivery";
+import type { DebugGatewaySurface } from "./debug.js";
+import type { BotTurnCommandRequestV1 } from "./durable-rpc.js";
+import type {
+  BotConfigurationExecuteRpcV1,
+  BotConfigurationReadRpcV1,
+  BotSettingsViewV1,
+  CompositionCommandReceiptV1,
+  CompositionGenerationListViewV1,
+  CompositionGenerationViewV1,
+  ConnectionView,
+  RevertCompositionCommandV1,
+  OperationReceiptV1,
+  UserConfigurationExecuteRpcV1,
+  UserConfigurationReadRpcV1,
+  UserSettingsViewV1,
+} from "@frockbot/core/configuration";
+import type {
+  ConnectionCommandReceiptV1,
+  ConnectionCommandV1,
+  ConnectionCompletionResult,
+  CredentialLeaseV1,
+  RevokeConnectionResult,
+  StartConnectionResult,
+} from "@frockbot/core/connection";
+import type { MemoryVector, MemoryVectorMatch } from "@frockbot/app/memory";
+// Flock DTOs cross only the authenticated hosted/backend seam.
+import type {
+  BotDirectoryViewV1,
+  BotLifecycleCommandV1,
+  BotLifecycleDirectoryViewV1,
+  BotLifecycleReceiptV1,
+  BotMembershipViewV1,
+  BotRegistrationV1,
+  CreateBotCommandV1,
+  FlockReceiptV1,
+  AvatarIdentityViewV1,
+  UpdateAvatarCommandV1,
+  VoiceIdentityViewV1,
+  UpdateVoiceCommandV1,
+  LookIdentityViewV1,
+  UpdateLookCommandV1,
+} from "@frockbot/app/flock/shared";
+import type {
+  ApprovalDecisionCommandV1,
+  ApprovalDecisionReceiptV1,
+  ApprovalListViewV1,
+} from "@frockbot/app/shell/approvals";
+import type {
+  RoutineCommandReceiptV1,
+  RoutineCommandV1,
+  RoutineInboxCommandV1,
+  RoutineInboxReceiptV1,
+  RoutineInboxViewV1,
+  RoutineListViewV1,
+  RoutineRunDetailViewV1,
+  RoutineRunListViewV1,
+} from "@frockbot/app/routines/shared";
+import type {
+  TaskListViewV1,
+  TaskViewV1,
+} from "@frockbot/app/subagents/shared";
+import type {
+  ClientRunLookupQueryV1,
+  ClientRunLookupV1,
+  ClientRunQuestionsV1,
+  ClientRunListQueryV1,
+  ClientRunListV1,
+  ClientRunStopCommandV1,
+  ClientRunStopReceiptV1,
+  ClientTurnV1,
+} from "@frockbot/app/shell/run-protocol";
+import type { ClientSkillCatalogV1 } from "@frockbot/app/shell/skill-protocol";
+import type {
+  AccountAdmissionDecisionV1,
+  AdmissionIdentityV1,
+} from "@frockbot/app/admin/shared";
+
+export interface BackendRouteContribution {
+  packageId: string;
+  publicRoute?(
+    request: Request,
+    url: URL,
+    context: {
+      userId?: string;
+      client: "browser" | "desktop";
+      /**
+       * The User the request's own session is, once admitted, or `undefined`
+       * — asked only by a public route that must act for nobody else.
+       */
+      sessionUserId?: () => Promise<string | undefined>;
+    },
+  ): Promise<Response | undefined>;
+  route(
+    request: Request,
+    url: URL,
+    context: {
+      userId?: string;
+      client: "browser" | "desktop";
+      isAdmin: boolean;
+    },
+  ): Promise<Response | undefined>;
+}
+
+export interface UserApplicationIdentity {
+  userId: string;
+  applicationHash: string;
+}
+
+export type StoredRunStatus =
+  "running" | "completed" | "failed" | "interrupted";
+
+export interface StoredRun {
+  runId: string;
+  sessionId: string;
+  acceptedAt: string;
+  input: string;
+  events: SessionEvent[];
+  status?: StoredRunStatus;
+  responseText?: string;
+  failure?: string;
+  phase?: "admitted" | "executing";
+  compositionGenerationId?: string;
+  configurationSnapshot?: BotSettingsViewV1;
+  previousEventCount?: number;
+}
+
+export interface BotTurnCommand {
+  runId: string;
+  sessionId: string;
+  acceptedAt: string;
+  text: string;
+}
+
+export interface BotNotificationIntent {
+  notificationId: string;
+  runId: string;
+  createdAt: string;
+  title: string;
+  body: string;
+  urgency?: "normal" | "critical";
+}
+
+export type BotTurnResult = ClientTurnV1;
+
+export interface BotStateBinding {
+  run(botId: string, command: BotTurnCommand): Promise<BotTurnResult>;
+  listRuns(
+    botId: string,
+    query: ClientRunListQueryV1,
+  ): Promise<ClientRunListV1>;
+  lookupRun(
+    botId: string,
+    query: ClientRunLookupQueryV1,
+  ): Promise<ClientRunLookupV1>;
+  runQuestions(
+    botId: string,
+    query: ClientRunLookupQueryV1,
+  ): Promise<ClientRunQuestionsV1>;
+  fenceRunAdmission(
+    botId: string,
+    query: ClientRunLookupQueryV1,
+  ): Promise<ClientRunLookupV1>;
+  listNotifications(botId: string): Promise<BotNotificationIntent[]>;
+  listApprovals(botId: string): Promise<ApprovalListViewV1>;
+  decideApproval(
+    botId: string,
+    approvalId: string,
+    command: ApprovalDecisionCommandV1,
+  ): Promise<ApprovalDecisionReceiptV1>;
+  listCards(botId: string): Promise<CardListViewV1>;
+  readCard(botId: string, surfaceId: string): Promise<CardViewV1>;
+  cardAction(
+    botId: string,
+    command: CardActionCommandV1,
+  ): Promise<CardActionReceiptV1>;
+  submitSecret(
+    botId: string,
+    requestId: string,
+    command: SecretSubmitCommandV1,
+  ): Promise<SecretSubmitReceiptV1>;
+  acknowledgeNotification(botId: string, notificationId: string): Promise<void>;
+  stopRun(
+    botId: string,
+    command: ClientRunStopCommandV1,
+  ): Promise<ClientRunStopReceiptV1>;
+}
+
+export interface MemoryBinding {
+  get(key: string): Promise<string | null>;
+  put(key: string, value: string, contentType?: string): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(
+    prefix: string,
+    cursor?: string,
+  ): Promise<{
+    objects: Array<{ key: string }>;
+    truncated: boolean;
+    cursor?: string;
+  }>;
+  vectorUpsert(vectors: MemoryVector[]): Promise<void>;
+  vectorQuery(
+    vector: number[],
+    options: { topK: number; namespace: string; returnMetadata: "all" },
+  ): Promise<{ matches: MemoryVectorMatch[] }>;
+  vectorDeleteByIds(ids: string[]): Promise<void>;
+  embed(model: string, texts: string[]): Promise<{ data: number[][] }>;
+}
+
+/**
+ * One durable-root file as the hosted client reads it. A declared variant,
+ * never an exception: a root the store cannot serve is an ordinary answer.
+ */
+export type ClientWorkspaceFileV1 =
+  | {
+      schemaVersion: 1;
+      status: "ok";
+      contentHash: string;
+      size: number;
+      bytesBase64: string;
+    }
+  | {
+      schemaVersion: 1;
+      status: "not-found" | "refused" | "conflict" | "unavailable";
+      reason: string;
+    };
+
+export interface UserBotStateBinding {
+  assertRegistered(input: { schemaVersion: 1; botId: string }): Promise<void>;
+  run(input: {
+    schemaVersion: 1;
+    botId: string;
+    command: BotTurnCommandRequestV1<BotTurnCommand>;
+  }): Promise<BotTurnResult>;
+  /**
+   * Durable acceptance of a composer command. The receipt is not the Turn's
+   * outcome; execution continues after this method returns.
+   */
+  admitRun(input: {
+    schemaVersion: 1;
+    botId: string;
+    command: BotTurnCommandRequestV1<BotTurnCommand>;
+  }): Promise<{ schemaVersion: 1; runId: string }>;
+  listRuns(input: {
+    schemaVersion: 1;
+    botId: string;
+    query: ClientRunListQueryV1;
+  }): Promise<ClientRunListV1>;
+  lookupRun(input: {
+    schemaVersion: 1;
+    botId: string;
+    query: ClientRunLookupQueryV1;
+  }): Promise<ClientRunLookupV1>;
+  /** The questions a running Turn is waiting on from other Bots. */
+  runQuestions(input: {
+    schemaVersion: 1;
+    botId: string;
+    query: ClientRunLookupQueryV1;
+  }): Promise<ClientRunQuestionsV1>;
+  fenceRunAdmission(input: {
+    schemaVersion: 1;
+    botId: string;
+    query: ClientRunLookupQueryV1;
+  }): Promise<ClientRunLookupV1>;
+  listSkills(input: {
+    schemaVersion: 1;
+    botId: string;
+  }): Promise<ClientSkillCatalogV1>;
+  readWorkspaceFileV1(input: {
+    schemaVersion: 1;
+    botId: string;
+    path: unknown;
+  }): Promise<ClientWorkspaceFileV1>;
+  listNotifications(input: {
+    schemaVersion: 1;
+    botId: string;
+  }): Promise<BotNotificationIntent[]>;
+  listApprovals(input: {
+    schemaVersion: 1;
+    botId: string;
+  }): Promise<ApprovalListViewV1>;
+  decideApproval(input: {
+    schemaVersion: 1;
+    botId: string;
+    approvalId: string;
+    command: ApprovalDecisionCommandV1;
+  }): Promise<ApprovalDecisionReceiptV1>;
+  listCards(input: {
+    schemaVersion: 1;
+    botId: string;
+  }): Promise<CardListViewV1>;
+  readCard(input: {
+    schemaVersion: 1;
+    botId: string;
+    surfaceId: string;
+  }): Promise<CardViewV1>;
+  cardAction(input: {
+    schemaVersion: 1;
+    botId: string;
+    command: CardActionCommandV1;
+  }): Promise<CardActionReceiptV1>;
+  /** A value typed on a secret-request card, sealed before this answers. */
+  submitSecret(input: {
+    schemaVersion: 1;
+    botId: string;
+    requestId: string;
+    command: SecretSubmitCommandV1;
+  }): Promise<SecretSubmitReceiptV1>;
+  acknowledgeNotification(input: {
+    schemaVersion: 1;
+    botId: string;
+    notificationId: string;
+  }): Promise<void>;
+  stopRun(input: {
+    schemaVersion: 1;
+    botId: string;
+    command: ClientRunStopCommandV1;
+  }): Promise<ClientRunStopReceiptV1>;
+}
+
+export interface UserApplicationEnv {
+  BOT_STATE: UserBotStateBinding;
+  DEPLOYMENT: UserApplicationIdentity;
+}
+
+/**
+ * The loader-side `WorkerCode`. `env` is generic because two kinds of isolate
+ * are loaded from this Worker: a user application (`UserApplicationEnv`) and a
+ * Plugin worker (`BotIsolateEnv`, from `@frockbot/core/contracts`), which sees
+ * only `IDENTITY` and the loopback `CAPABILITIES` service binding.
+ */
+export interface WorkerCode<Env = UserApplicationEnv> {
+  compatibilityDate: string;
+  mainModule: string;
+  modules: Record<string, string | { js: string }>;
+  globalOutbound?: null;
+  env: Env;
+  limits?: {
+    cpuMs?: number;
+    subRequests?: number;
+  };
+}
+
+export interface WorkerEntrypointStub {
+  fetch(request: Request): Promise<Response>;
+}
+
+export interface LoadedWorker<Entrypoint = WorkerEntrypointStub> {
+  getEntrypoint(name?: string | null): Entrypoint;
+}
+
+export interface WorkerLoader<
+  Env = UserApplicationEnv,
+  Entrypoint = WorkerEntrypointStub,
+> {
+  get(
+    id: string,
+    callback: () => Promise<WorkerCode<Env>>,
+  ): LoadedWorker<Entrypoint>;
+}
+
+/** The `BOT_PACKAGES` loader: Plugin workers, never user applications. */
+export type BotPackageLoader = WorkerLoader<
+  BotIsolateEnv,
+  PluginWorkerEntrypoint
+>;
+
+export interface ApplicationArtifactStore {
+  load(applicationHash: string): Promise<string>;
+  /** A Plugin's stored page, or undefined when there is none. */
+  loadPluginPage?(contentHash: string): Promise<string | undefined>;
+}
+
+export interface ConnectionBinding {
+  start(input: {
+    commandId: string;
+    connectionTypeId: string;
+    botId: string;
+    alias?: string;
+  }): Promise<StartConnectionResult>;
+  complete(input: {
+    connectionId: string;
+    connectedAccountId: string;
+  }): Promise<ConnectionCompletionResult>;
+  fail(
+    connectionId: string,
+    message: string,
+  ): Promise<ConnectionCompletionResult>;
+  revoke(connectionId: string): Promise<RevokeConnectionResult>;
+}
+
+export interface UserConfigurationBinding {
+  listBots(request: {
+    schemaVersion: 1;
+    userId: string;
+  }): Promise<BotDirectoryViewV1>;
+  listBotLifecycles(request: {
+    schemaVersion: 1;
+    userId: string;
+  }): Promise<BotLifecycleDirectoryViewV1>;
+  executeBotLifecycle(request: {
+    schemaVersion: 1;
+    userId: string;
+    command: BotLifecycleCommandV1;
+  }): Promise<BotLifecycleReceiptV1>;
+  createBot(request: {
+    schemaVersion: 1;
+    userId: string;
+    command: CreateBotCommandV1;
+  }): Promise<FlockReceiptV1>;
+  /**
+   * Changes what a Bot wears. The Bot's own object accepts or refuses the
+   * command; the User's directory is told afterwards, so a list of Bots shows
+   * the change rather than the appearance the Bot was created with.
+   */
+  updateBotAvatar(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    command: UpdateAvatarCommandV1;
+  }): Promise<FlockReceiptV1>;
+  /** How a Bot sounds, read and changed the way its avatar is (ADR 0031). */
+  readBotVoice(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+  }): Promise<VoiceIdentityViewV1>;
+  updateBotVoice(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    command: UpdateVoiceCommandV1;
+  }): Promise<FlockReceiptV1>;
+  readBotLook(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+  }): Promise<LookIdentityViewV1>;
+  updateBotLook(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    command: UpdateLookCommandV1;
+  }): Promise<FlockReceiptV1>;
+  mirrorBotLook(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    look: LookIdentityViewV1["look"];
+    document?: LookIdentityViewV1["document"];
+  }): Promise<BotDirectoryViewV1>;
+  getBotRegistration(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+  }): Promise<BotRegistrationV1>;
+  hasBot(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+  }): Promise<BotMembershipViewV1>;
+  readConfiguration(
+    request: UserConfigurationReadRpcV1,
+  ): Promise<UserSettingsViewV1>;
+  readConnectionsFrame(request: {
+    schemaVersion: 1;
+    userId: string;
+    catalog?: import("@frockbot/app/settings/frame").ConnectionsCatalogQueryV1;
+  }): Promise<ConnectionsFrame>;
+  /** The User's saved secrets: names and terms, never a value. */
+  listSecrets(request: {
+    schemaVersion: 1;
+    userId: string;
+  }): Promise<SecretListViewV1>;
+  deleteSecret(request: {
+    schemaVersion: 1;
+    userId: string;
+    secretId: string;
+  }): Promise<{ schemaVersion: 1; removed: boolean }>;
+  readSettingsFrame(
+    request: UserConfigurationReadRpcV1 & { home: "application" | "models" },
+  ): Promise<SettingsFrame>;
+  readSettingsOptions(
+    request: UserConfigurationReadRpcV1 & {
+      query: import("@frockbot/core/protocol-schemas").SettingsOptionsQuery;
+    },
+  ): Promise<import("@frockbot/core/protocol-schemas").SettingsOptionsPage>;
+  changeSettings(
+    request: UserConfigurationReadRpcV1 & {
+      home: "application" | "models";
+      command: SettingsChangeCommand;
+    },
+  ): Promise<OperationReceiptV1>;
+  executeConfiguration(
+    request: UserConfigurationExecuteRpcV1,
+  ): Promise<OperationReceiptV1>;
+  executeConnection(request: {
+    schemaVersion: 1;
+    userId: string;
+    command: ConnectionCommandV1;
+  }): Promise<ConnectionCommandReceiptV1>;
+  lookupConnectionCommand(request: {
+    schemaVersion: 1;
+    userId: string;
+    packageId: string;
+    commandId: string;
+  }): Promise<ConnectionCommandReceiptV1 | undefined>;
+  getConnection(request: {
+    schemaVersion: 1;
+    userId: string;
+    connectionId: string;
+  }): Promise<ConnectionView | undefined>;
+  leaseModelCredential(request: {
+    schemaVersion: 1;
+    userId: string;
+    connectionId: string;
+    providerModelId: string;
+    effectId: string;
+    connectionGeneration: string;
+  }): Promise<CredentialLeaseV1>;
+  settleModelCredential(request: {
+    schemaVersion: 1;
+    userId: string;
+    connectionId: string;
+    packageId: string;
+    effectId: string;
+  }): Promise<void>;
+}
+
+export interface BotConfigurationBinding {
+  readAvatar(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+  }): Promise<AvatarIdentityViewV1>;
+  updateAvatar(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    command: UpdateAvatarCommandV1;
+  }): Promise<FlockReceiptV1>;
+  readVoice(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+  }): Promise<VoiceIdentityViewV1>;
+  updateVoice(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    command: UpdateVoiceCommandV1;
+  }): Promise<FlockReceiptV1>;
+  readLook(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+  }): Promise<LookIdentityViewV1>;
+  updateLook(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    command: UpdateLookCommandV1;
+  }): Promise<FlockReceiptV1>;
+  persistAssembledDocument(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    document?: LookIdentityViewV1["document"];
+  }): Promise<LookIdentityViewV1>;
+  readConfiguration(
+    request: BotConfigurationReadRpcV1,
+  ): Promise<BotSettingsViewV1>;
+  executeConfiguration(
+    request: BotConfigurationExecuteRpcV1,
+  ): Promise<OperationReceiptV1>;
+  readBotPluginsFrame(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+  }): Promise<BotPluginsFrameV1>;
+  setBotPluginEnabled(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    command: SetBotPluginEnabledCommandV1;
+  }): Promise<SetBotPluginEnabledReceiptV1>;
+  /** A control on a Plugin's section, pressed: runs the tool it names. */
+  executeBotPluginTool(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    command: PluginToolCommandV1;
+  }): Promise<BotPluginToolReceiptV1>;
+  openFocusedPanel(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    /** The origin the read arrived on, which serves the Plugin's pages. */
+    appOrigin: string;
+  }): Promise<import("@frockbot/app/plugins/panels-bot").PanelOpenViewV1>;
+  setFocusedPanel(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    pluginId: string | null;
+    surfaceId?: string;
+  }): Promise<
+    | {
+        status: "applied";
+        focus: import("@frockbot/core/durable").FocusedPanelV1;
+      }
+    | { status: "error"; failure: string }
+  >;
+  recordPanelDeviceUse(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    use: import("@frockbot/app/audit").DeviceUseV1;
+  }): Promise<{ status: "recorded" } | { status: "refused"; reason: string }>;
+  recordPanelPageReport(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    report: import("@frockbot/app/plugins/page-reports").PluginPageReportCommandV1;
+  }): Promise<{ status: "recorded" } | { status: "refused"; reason: string }>;
+  listCompositionGenerations(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    query: { limit: number; cursor?: string };
+  }): Promise<CompositionGenerationListViewV1>;
+  getCompositionGeneration(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    generationId: string;
+  }): Promise<CompositionGenerationViewV1 | undefined>;
+  revertComposition(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    command: RevertCompositionCommandV1;
+  }): Promise<CompositionCommandReceiptV1>;
+  listRoutines(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+  }): Promise<RoutineListViewV1>;
+  /** The list and the inbox, one materialize. */
+  readRoutinesFrame(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+  }): Promise<{ list: RoutineListViewV1; inbox: RoutineInboxViewV1 }>;
+  /** The Bot's subagent tasks, answered by the parent Bot Durable Object. */
+  listTasks(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+  }): Promise<TaskListViewV1>;
+  readTask(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    taskId: string;
+  }): Promise<TaskViewV1>;
+  /** Explicit, authenticated cancellation of one task, by its User. */
+  stopTask(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    taskId: string;
+  }): Promise<TaskViewV1>;
+  executeRoutineCommand(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    command: RoutineCommandV1;
+  }): Promise<RoutineCommandReceiptV1>;
+  /**
+   * One finished machine command, handed to the Bot that asked for it. Called
+   * by the Worker that answered the machine, never by another Durable Object.
+   */
+  deliverMachineResult(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    delivery: MachineResultDeliveryV1;
+  }): Promise<{ status: "accepted" }>;
+  deliverRoutineHook(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    delivery: {
+      routineId: string;
+      keyVersion: number;
+      digest: string;
+      deliveryId: string;
+      body: string;
+      contentType?: string | null;
+      headers?: Record<string, string>;
+    };
+  }): Promise<
+    | { status: "accepted" | "duplicate"; fireId: string }
+    | { status: "dropped"; reason: string }
+  >;
+  listRoutineRuns(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    routineId: string;
+  }): Promise<RoutineRunListViewV1>;
+  readRoutineRun(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    routineId: string;
+    runId: string;
+  }): Promise<RoutineRunDetailViewV1>;
+  listRoutineInbox(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+  }): Promise<RoutineInboxViewV1>;
+  executeRoutineInboxCommand(request: {
+    schemaVersion: 1;
+    userId: string;
+    botId: string;
+    command: RoutineInboxCommandV1;
+  }): Promise<RoutineInboxReceiptV1>;
+}
+
+export interface GatewayDependencies {
+  registerPush?(userId: string, registration: unknown): Promise<unknown>;
+  /**
+   * The two things a person may delete outright: their account and their
+   * Computer. The gateway checks the confirmation; these only carry it out.
+   */
+  deletion?: {
+    deleteAccount(
+      userId: string,
+      command: { commandId: string; email?: string },
+    ): Promise<unknown>;
+    deleteComputer(userId: string, commandId: string): Promise<unknown>;
+  };
+  /** Explicit Slice 2 prototype; absent until signed-target qualification. */
+  nativeAuth?: import("./native-auth.js").NativeAuth;
+  loader: WorkerLoader;
+  artifacts: ApplicationArtifactStore;
+  auth: AuthPackageV1;
+  /**
+   * The beta-access authority, asked before browser requests reach a User;
+   * native requests reuse their admission answer. It may activate the account
+   * and throws only when it cannot answer at all.
+   */
+  admitAccount(
+    identity: AdmissionIdentityV1,
+  ): Promise<AccountAdmissionDecisionV1>;
+  /** Raw deployment secret; only the derived `isAdmin` boolean reaches clients. */
+  adminEmails?: string;
+  applicationHashFor(userId: string): Promise<string>;
+  botStateFor(userId: string): UserBotStateBinding;
+  userConfigurationFor(userId: string): UserConfigurationBinding;
+  botConfigurationFor(userId: string, botId: string): BotConfigurationBinding;
+  /** Authenticated observer transport into the Bot Durable Object. */
+  openBotStateChannel?(
+    userId: string,
+    botId: string,
+    request: Request,
+    context: { isAdmin: boolean; authMode: string },
+  ): Promise<Response>;
+  /** Absent, or with no token, when the deployment publishes no `/api/debug`. */
+  debug?: DebugGatewaySurface;
+  /**
+   * The voice doors. Absent in a deployment that has neither the dictation
+   * nor the assistant configured; the routes then answer what is missing.
+   */
+  voice?: VoiceGatewayDependencies;
+  backendContributions?: readonly BackendRouteContribution[];
+  /** Webview origins allowed to call `/api/*` cross-origin. */
+  allowedClientOrigins?: string[];
+  allowDevelopmentIdentity?: boolean;
+  compatibilityDate?: string;
+  /** The brand's What's New switch: off, the feed is empty. */
+  whatsNew: boolean;
+}
+
+/** The two voice sockets and the probe the clients read before offering them. */
+export interface VoiceGatewayDependencies {
+  capabilities(): { dictation: boolean; assistant: boolean };
+  /** The composer's dictation relay; the request is an authenticated upgrade. */
+  openDictation(userId: string, request: Request): Promise<Response>;
+  /**
+   * The account's voice session object. `deviceKey` names the client device
+   * so a socket it replaces rejoins its own call rather than superseding it.
+   */
+  openAssistant(
+    userId: string,
+    deviceKey: string,
+    request: Request,
+    context: { isAdmin: boolean; authMode: string },
+  ): Promise<Response>;
+}