@effect-agent/platform-cloudflare 0.1.0-beta.23 → 0.1.0-beta.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-agent/platform-cloudflare",
-  "version": "0.1.0-beta.23",
+  "version": "0.1.0-beta.25",
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -8,11 +8,11 @@
     }
   },
   "dependencies": {
-    "@effect-agent/core": "0.1.0-beta.23",
-    "@effect-agent/engine": "0.1.0-beta.23",
-    "@effect-agent/sandbox": "0.1.0-beta.23",
-    "@effect-agent/session": "0.1.0-beta.23",
-    "@effect-agent/storage-cloudflare": "0.1.0-beta.23",
+    "@effect-agent/core": "0.1.0-beta.25",
+    "@effect-agent/engine": "0.1.0-beta.25",
+    "@effect-agent/sandbox": "0.1.0-beta.25",
+    "@effect-agent/session": "0.1.0-beta.25",
+    "@effect-agent/storage-cloudflare": "0.1.0-beta.25",
     "@effect/platform-browser": "4.0.0-rc.110",
     "@effect/sql-sqlite-do": "4.0.0-rc.110",
     "effect": "4.0.0-rc.110"
@@ -43,8 +43,8 @@
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "0.21.3",
     "@cloudflare/workers-types": "5.20260813.1",
-    "@effect-agent/capabilities": "0.1.0-beta.22",
-    "@effect-agent/testing": "0.1.0-beta.22",
+    "@effect-agent/capabilities": "0.1.0-beta.23",
+    "@effect-agent/testing": "0.1.0-beta.23",
     "@effect/vitest": "4.0.0-rc.110",
     "effect-cf": "0.27.0",
     "esbuild": "0.28.1",

package/src/alarm.ts

@@ -21,6 +21,7 @@ import {
 } from "effect";
 
 import { ConversationObjectIdentity, DurableObjectContext } from "./bindings.ts";
+import { safeCauseMessage } from "./boundary.ts";
 import { CloudflareDurableRuntimeConfig } from "./config.ts";
 
 /**
@@ -50,7 +51,7 @@ const alarmFailure =
   (cause: unknown): DurableAlarmError =>
     DurableAlarmError.make({
       operation,
-      message: cause instanceof Error ? cause.message : String(cause),
+      message: safeCauseMessage(cause, "The Cloudflare alarm API failed without a diagnostic"),
       cause,
     });
 

package/src/bindings.ts

@@ -1,6 +1,6 @@
 import type { ConversationId } from "@effect-agent/core";
 import type { ProducerId } from "@effect-agent/session";
-import { Context, Effect, Layer, Schema } from "effect";
+import { Context, Effect, Layer, Predicate, Schema } from "effect";
 
 /**
  * Cloudflare platform bindings as Effect services (DEPLOY-010: "Cloudflare platform bindings
@@ -73,41 +73,42 @@ export class ConversationObjectNamespace extends Context.Service<
  * narrowest-boundary check (structural probe for the namespace surface the transport uses);
  * a missing or misshaped binding fails typed before any Layer is built.
  */
-export const conversationNamespaceFromEnv = (
+export const conversationNamespaceFromEnv = Effect.fn("conversationNamespaceFromEnv")(function* (
   env: unknown,
   binding: string,
-): Effect.Effect<DurableObjectNamespace<ConversationObjectRpc>, CloudflareBindingError> =>
-  Effect.suspend(() => {
-    if (typeof env !== "object" || env === null) {
-      return Effect.fail(
-        CloudflareBindingError.make({
-          binding,
-          message: "The Worker environment is not an object; no bindings are available.",
-        }),
-      );
-    }
-    const candidate: unknown = (env as Record<string, unknown>)[binding];
-    if (
-      typeof candidate === "object" &&
-      candidate !== null &&
-      "idFromName" in candidate &&
-      typeof candidate.idFromName === "function" &&
-      "get" in candidate &&
-      typeof candidate.get === "function"
-    ) {
-      // The structural probe above is the entire runtime contract this package relies on;
-      // the assertion records that `idFromName`/`get` name a DurableObjectNamespace.
-      return Effect.succeed(candidate as DurableObjectNamespace<ConversationObjectRpc>);
-    }
-    return Effect.fail(
+): Effect.fn.Return<DurableObjectNamespace<ConversationObjectRpc>, CloudflareBindingError> {
+  if (!Predicate.isObjectKeyword(env)) {
+    return yield* CloudflareBindingError.make({
+      binding,
+      message: "The Worker environment is not an object; no bindings are available.",
+    });
+  }
+  const candidate = yield* Effect.try({
+    try: () => {
+      const value: unknown = Reflect.get(env, binding);
+      if (!Predicate.isObjectKeyword(value)) return undefined;
+      const idFromName: unknown = Reflect.get(value, "idFromName");
+      const get: unknown = Reflect.get(value, "get");
+      return typeof idFromName === "function" && typeof get === "function" ? value : undefined;
+    },
+    catch: () =>
       CloudflareBindingError.make({
         binding,
-        message:
-          `env.${binding} is not a DurableObjectNamespace binding; declare the Conversation ` +
-          "Object class under this binding in the Worker configuration.",
+        message: `env.${binding} could not be inspected as a DurableObjectNamespace binding.`,
       }),
-    );
   });
+  if (candidate !== undefined) {
+    // The structural probe above is the entire runtime contract this package relies on;
+    // the assertion records that `idFromName`/`get` name a DurableObjectNamespace.
+    return candidate as unknown as DurableObjectNamespace<ConversationObjectRpc>;
+  }
+  return yield* CloudflareBindingError.make({
+    binding,
+    message:
+      `env.${binding} is not a DurableObjectNamespace binding; declare the Conversation ` +
+      "Object class under this binding in the Worker configuration.",
+  });
+});
 
 /** `ConversationObjectNamespace` built from the untyped Worker `env` (fails typed). */
 export const conversationNamespaceLayer = (

package/src/boundary.ts

@@ -0,0 +1,51 @@
+import { Predicate } from "effect";
+
+const MAX_FOREIGN_DIAGNOSTIC_LENGTH = 8_192;
+
+const boundForeignDiagnostic = (message: string): string =>
+  message.slice(0, MAX_FOREIGN_DIAGNOSTIC_LENGTH);
+
+/** Render a foreign failure without trusting accessors or coercion hooks on the value. */
+export const safeCauseMessage = (cause: unknown, fallback: string): string => {
+  try {
+    const message = cause instanceof Error ? cause.message : cause;
+    return boundForeignDiagnostic(typeof message === "string" ? message : String(message));
+  } catch {
+    return boundForeignDiagnostic(fallback);
+  }
+};
+
+/** Include an Error name when worker-failure classification needs it. */
+export const safeCauseDiagnostic = (cause: unknown, fallback: string): string => {
+  try {
+    return cause instanceof Error
+      ? boundForeignDiagnostic(`${cause.name}: ${cause.message}`)
+      : safeCauseMessage(cause, fallback);
+  } catch {
+    return boundForeignDiagnostic(fallback);
+  }
+};
+
+export interface CloudflareFailureSignals {
+  readonly retryable?: boolean | undefined;
+  readonly overloaded?: boolean | undefined;
+}
+
+/** Read Cloudflare RPC classifications without letting a hostile proxy defect the client. */
+export const cloudflareFailureSignals = (cause: unknown): CloudflareFailureSignals => {
+  if (!Predicate.isObjectKeyword(cause)) return {};
+  try {
+    const retryableValue = Reflect.get(cause, "retryable");
+    const overloadedValue = Reflect.get(cause, "overloaded");
+    const resetValue = Reflect.get(cause, "durableObjectReset");
+    const retryable =
+      typeof retryableValue === "boolean" ? retryableValue : resetValue === true ? true : undefined;
+    const overloaded = typeof overloadedValue === "boolean" ? overloadedValue : undefined;
+    return {
+      ...(retryable === undefined ? {} : { retryable }),
+      ...(overloaded === undefined ? {} : { overloaded }),
+    };
+  } catch {
+    return {};
+  }
+};

package/src/client.ts

@@ -34,6 +34,7 @@ import { Context, Crypto, Duration, Effect, Layer, Schema } from "effect";
 
 import { DurableAlarmError } from "./alarm.ts";
 import { ConversationObjectNamespace, type ConversationObjectRpc } from "./bindings.ts";
+import { cloudflareFailureSignals, safeCauseMessage } from "./boundary.ts";
 import { AdmissionLimitExceeded } from "./config.ts";
 
 /**
@@ -249,123 +250,62 @@ export const decodeHostResponse = Schema.decodeUnknownEffect(HostResponse);
 // ---------------------------------------------------------------------------
 
 /** Failure surface of `CloudflareConversationClient.submit`. */
-export type ClientSubmitFailure =
-  | AgentInputError
-  | DigestError
-  | AdmissionConflict
-  | LedgerError
-  | ConversationStoreError
-  | ConversationNotMaterialized
-  | AppendConflict
-  | FenceRejected
-  | DurableRuntimeFailpointError
-  | AdmissionLimitExceeded
-  | DurableAlarmError
-  | HostProtocolError
-  | ConversationClientError;
-
-export type ClientAwaitFailure =
-  | LedgerError
-  | SettlementConflict
-  | HostProtocolError
-  | ConversationClientError;
-
-export type ClientObserveFailure =
-  | ConversationStoreError
-  | ConversationNotMaterialized
-  | OperationDenied
-  | HostProtocolError
-  | ConversationClientError;
-
-export type ClientProgressFailure =
-  | ConversationStoreError
-  | ConversationNotMaterialized
-  | OperationDenied
-  | HostProtocolError
-  | ConversationClientError;
-
-export type ClientAbortFailure =
-  | LedgerError
-  | SettlementConflict
-  | JoinedToHost
-  | DurableRuntimeFailpointError
-  | DurableAlarmError
-  | HostProtocolError
-  | ConversationClientError;
-
-export type ClientApprovalFailure =
-  | LedgerError
-  | SettlementConflict
-  | ApprovalConflict
-  | OperationDenied
-  | DurableAlarmError
-  | HostProtocolError
-  | ConversationClientError;
-
-export type ClientUnknownFailure =
-  | LedgerError
-  | SettlementConflict
-  | UnknownResolutionConflict
-  | JoinedToHost
-  | DurableRuntimeFailpointError
-  | OperationDenied
-  | DurableAlarmError
-  | HostProtocolError
-  | ConversationClientError;
-
-const SUBMIT_FAILURE_TAGS: ReadonlySet<string> = new Set([
-  "AgentInputError",
-  "DigestError",
-  "AdmissionConflict",
-  "LedgerError",
-  "ConversationStoreError",
-  "ConversationNotMaterialized",
-  "AppendConflict",
-  "FenceRejected",
-  "DurableRuntimeFailpointError",
-  "AdmissionLimitExceeded",
-  "DurableAlarmError",
-  "HostProtocolError",
-]);
-const AWAIT_FAILURE_TAGS: ReadonlySet<string> = new Set([
-  "LedgerError",
-  "SettlementConflict",
-  "HostProtocolError",
+const ClientSubmitHostFailure = Schema.Union([
+  AgentInputError,
+  DigestError,
+  AdmissionConflict,
+  LedgerError,
+  ConversationStoreError,
+  ConversationNotMaterialized,
+  AppendConflict,
+  FenceRejected,
+  DurableRuntimeFailpointError,
+  AdmissionLimitExceeded,
+  DurableAlarmError,
+  HostProtocolError,
 ]);
-const OBSERVE_FAILURE_TAGS: ReadonlySet<string> = new Set([
-  "ConversationStoreError",
-  "ConversationNotMaterialized",
-  "OperationDenied",
-  "HostProtocolError",
+const ClientAwaitHostFailure = Schema.Union([LedgerError, SettlementConflict, HostProtocolError]);
+const ClientObserveHostFailure = Schema.Union([
+  ConversationStoreError,
+  ConversationNotMaterialized,
+  OperationDenied,
+  HostProtocolError,
 ]);
-const PROGRESS_FAILURE_TAGS = OBSERVE_FAILURE_TAGS;
-const ABORT_FAILURE_TAGS: ReadonlySet<string> = new Set([
-  "LedgerError",
-  "SettlementConflict",
-  "JoinedToHost",
-  "DurableRuntimeFailpointError",
-  "DurableAlarmError",
-  "HostProtocolError",
+const ClientAbortHostFailure = Schema.Union([
+  LedgerError,
+  SettlementConflict,
+  JoinedToHost,
+  DurableRuntimeFailpointError,
+  DurableAlarmError,
+  HostProtocolError,
 ]);
-const APPROVAL_FAILURE_TAGS: ReadonlySet<string> = new Set([
-  "LedgerError",
-  "SettlementConflict",
-  "ApprovalConflict",
-  "OperationDenied",
-  "DurableAlarmError",
-  "HostProtocolError",
+const ClientApprovalHostFailure = Schema.Union([
+  LedgerError,
+  SettlementConflict,
+  ApprovalConflict,
+  OperationDenied,
+  DurableAlarmError,
+  HostProtocolError,
 ]);
-const UNKNOWN_FAILURE_TAGS: ReadonlySet<string> = new Set([
-  "LedgerError",
-  "SettlementConflict",
-  "UnknownResolutionConflict",
-  "JoinedToHost",
-  "DurableRuntimeFailpointError",
-  "OperationDenied",
-  "DurableAlarmError",
-  "HostProtocolError",
+const ClientUnknownHostFailure = Schema.Union([
+  LedgerError,
+  SettlementConflict,
+  UnknownResolutionConflict,
+  JoinedToHost,
+  DurableRuntimeFailpointError,
+  OperationDenied,
+  DurableAlarmError,
+  HostProtocolError,
 ]);
 
+export type ClientSubmitFailure = typeof ClientSubmitHostFailure.Type | ConversationClientError;
+export type ClientAwaitFailure = typeof ClientAwaitHostFailure.Type | ConversationClientError;
+export type ClientObserveFailure = typeof ClientObserveHostFailure.Type | ConversationClientError;
+export type ClientProgressFailure = ClientObserveFailure;
+export type ClientAbortFailure = typeof ClientAbortHostFailure.Type | ConversationClientError;
+export type ClientApprovalFailure = typeof ClientApprovalHostFailure.Type | ConversationClientError;
+export type ClientUnknownFailure = typeof ClientUnknownHostFailure.Type | ConversationClientError;
+
 const outOfContract = (
   conversationId: string,
   operation: string,
@@ -378,17 +318,6 @@ const outOfContract = (
     ),
   });
 
-/**
- * Narrow one decoded `HostFailed.failure` to the operation's declared failure family; an
- * out-of-contract tag folds into `ConversationClientError` instead of being erased or
- * re-thrown raw (the WP2 discipline). The predicate is the single documented narrowing over
- * the closed `HostFailure` union.
- */
-const narrowFailure =
-  <Failure extends HostFailure>(tags: ReadonlySet<string>) =>
-  (failure: HostFailure): failure is Failure =>
-    tags.has(failure._tag);
-
 /** Worker-side client over the Conversation Object namespace (DEPLOY-010). */
 export class CloudflareConversationClient extends Context.Service<
   CloudflareConversationClient,
@@ -453,32 +382,6 @@ export class CloudflareConversationClient extends Context.Service<
       const { namespace } = yield* ConversationObjectNamespace;
       const crypto = yield* Crypto.Crypto;
 
-      const platformSignals = (cause: unknown) => {
-        let retryable: boolean | undefined;
-        let overloaded: boolean | undefined;
-        if (typeof cause === "object" && cause !== null) {
-          if ("retryable" in cause && typeof cause.retryable === "boolean") {
-            retryable = cause.retryable;
-          }
-          if ("overloaded" in cause && typeof cause.overloaded === "boolean") {
-            overloaded = cause.overloaded;
-          }
-          // Miniflare's faithful `ctx.abort()` signal predates the public `retryable` field.
-          // Treat only its explicit reset marker as the same idempotent-retry classification.
-          if (
-            retryable === undefined &&
-            "durableObjectReset" in cause &&
-            cause.durableObjectReset === true
-          ) {
-            retryable = true;
-          }
-        }
-        return {
-          ...(retryable === undefined ? {} : { retryable }),
-          ...(overloaded === undefined ? {} : { overloaded }),
-        };
-      };
-
       const call = (
         conversationId: string,
         operation: string,
@@ -490,12 +393,13 @@ export class CloudflareConversationClient extends Context.Service<
             ConversationClientError.make({
               conversationId,
               message: boundHostDiagnostic(
-                `${operation} did not reach the Conversation Object: ${
-                  cause instanceof Error ? cause.message : String(cause)
-                }`,
+                `${operation} did not reach the Conversation Object: ${safeCauseMessage(
+                  cause,
+                  "the RPC failed without a diagnostic",
+                )}`,
               ),
               cause,
-              ...platformSignals(cause),
+              ...cloudflareFailureSignals(cause),
             }),
         }).pipe(
           Effect.flatMap((raw) =>
@@ -515,29 +419,27 @@ export class CloudflareConversationClient extends Context.Service<
           }),
         );
 
-      const expect = <
-        Result extends Exclude<HostResponse, HostFailed>,
-        Failure extends HostFailure,
-      >(
+      const expect = <ResultSchema extends Schema.Top, FailureSchema extends Schema.Top>(
         conversationId: string,
         operation: string,
-        resultTag: Result["_tag"],
-        tags: ReadonlySet<string>,
+        resultSchema: ResultSchema,
+        failureSchema: FailureSchema,
       ) => {
-        const isExpected = narrowFailure<Failure>(tags);
+        const isExpectedResult = Schema.is(resultSchema);
+        const isExpectedFailure = Schema.is(failureSchema);
         return (
           response: HostResponse,
-        ): Effect.Effect<Result, Failure | ConversationClientError> => {
+        ): Effect.Effect<ResultSchema["Type"], FailureSchema["Type"] | ConversationClientError> => {
           if (response._tag === "HostFailed") {
             const failure = response.failure;
-            return isExpected(failure)
+            return isExpectedFailure(failure)
               ? Effect.fail(failure)
               : Effect.fail(outOfContract(conversationId, operation, `failure ${failure._tag}`));
           }
-          if (response._tag !== resultTag) {
+          if (!isExpectedResult(response)) {
             return Effect.fail(outOfContract(conversationId, operation, `result ${response._tag}`));
           }
-          return Effect.succeed(response as Result);
+          return Effect.succeed(response);
         };
       };
 
@@ -565,11 +467,11 @@ export class CloudflareConversationClient extends Context.Service<
           const response = yield* call(conversationId, "observePage", (stub) =>
             stub.observePage(encoded),
           );
-          const page = yield* expect<ObservedPage, ClientObserveFailure & HostFailure>(
+          const page = yield* expect(
             conversationId,
             "observePage",
-            "ObservedPage",
-            OBSERVE_FAILURE_TAGS,
+            ObservedPage,
+            ClientObserveHostFailure,
           )(response);
           return page.records;
         });
@@ -627,11 +529,11 @@ export class CloudflareConversationClient extends Context.Service<
             const response = yield* call(options.conversationId, "submit", (stub) =>
               stub.submitEncoded(encoded),
             );
-            const succeeded = yield* expect<SubmitSucceeded, ClientSubmitFailure & HostFailure>(
+            const succeeded = yield* expect(
               options.conversationId,
               "submit",
-              "SubmitSucceeded",
-              SUBMIT_FAILURE_TAGS,
+              SubmitSucceeded,
+              ClientSubmitHostFailure,
             )(response);
             return succeeded.receipt;
           }),
@@ -648,11 +550,11 @@ export class CloudflareConversationClient extends Context.Service<
             const response = yield* call(receipt.conversationId, "awaitSettlement", (stub) =>
               stub.awaitSettlementEncoded(encoded),
             );
-            const settled = yield* expect<SettlementReached, ClientAwaitFailure & HostFailure>(
+            const settled = yield* expect(
               receipt.conversationId,
               "awaitSettlement",
-              "SettlementReached",
-              AWAIT_FAILURE_TAGS,
+              SettlementReached,
+              ClientAwaitHostFailure,
             )(response);
             return settled.settlement;
           }),
@@ -684,11 +586,11 @@ export class CloudflareConversationClient extends Context.Service<
                 stub.awaitProgressEncoded(encoded),
               ).pipe(
                 Effect.flatMap(
-                  expect<ProgressObserved, ClientProgressFailure & HostFailure>(
+                  expect(
                     conversationId,
                     "awaitProgress",
-                    "ProgressObserved",
-                    PROGRESS_FAILURE_TAGS,
+                    ProgressObserved,
+                    ClientObserveHostFailure,
                   ),
                 ),
                 Effect.asVoid,
@@ -733,11 +635,11 @@ export class CloudflareConversationClient extends Context.Service<
             const response = yield* call(conversationId, "abort", (stub) =>
               stub.abortEncoded(encoded),
             );
-            const recorded = yield* expect<AbortRecorded, ClientAbortFailure & HostFailure>(
+            const recorded = yield* expect(
               conversationId,
               "abort",
-              "AbortRecorded",
-              ABORT_FAILURE_TAGS,
+              AbortRecorded,
+              ClientAbortHostFailure,
             )(response);
             return recorded.intent;
           }),
@@ -754,11 +656,11 @@ export class CloudflareConversationClient extends Context.Service<
             const response = yield* call(conversationId, "resolveApproval", (stub) =>
               stub.resolveApprovalEncoded(encoded),
             );
-            const recorded = yield* expect<ApprovalRecorded, ClientApprovalFailure & HostFailure>(
+            const recorded = yield* expect(
               conversationId,
               "resolveApproval",
-              "ApprovalRecorded",
-              APPROVAL_FAILURE_TAGS,
+              ApprovalRecorded,
+              ClientApprovalHostFailure,
             )(response);
             return recorded.intent;
           }),
@@ -777,14 +679,11 @@ export class CloudflareConversationClient extends Context.Service<
             const response = yield* call(conversationId, "resolveUnknown", (stub) =>
               stub.resolveUnknownEncoded(encoded),
             );
-            const recorded = yield* expect<
-              UnknownResolutionRecorded,
-              ClientUnknownFailure & HostFailure
-            >(
+            const recorded = yield* expect(
               conversationId,
               "resolveUnknown",
-              "UnknownResolutionRecorded",
-              UNKNOWN_FAILURE_TAGS,
+              UnknownResolutionRecorded,
+              ClientUnknownHostFailure,
             )(response);
             return recorded.intent;
           }),