@effect-agent/platform-cloudflare 0.1.0-beta.33 → 0.1.0-beta.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-agent/platform-cloudflare",
-  "version": "0.1.0-beta.33",
+  "version": "0.1.0-beta.34",
   "exports": {
     ".": {
       "types": "./dist/index.d.mts",
@@ -25,17 +25,17 @@
   },
   "dependencies": {
     "@cloudflare/puppeteer": "1.1.0",
-    "@effect-agent/core": "0.1.0-beta.33",
-    "@effect-agent/engine": "0.1.0-beta.33",
-    "@effect-agent/sandbox": "0.1.0-beta.33",
-    "@effect-agent/session": "0.1.0-beta.33",
-    "@effect-agent/storage-cloudflare": "0.1.0-beta.33",
-    "@effect/platform-browser": "4.0.0-rc.110",
-    "@effect/sql-sqlite-do": "4.0.0-rc.110",
-    "effect": "4.0.0-rc.110"
+    "@effect-agent/core": "0.1.0-beta.34",
+    "@effect-agent/engine": "0.1.0-beta.34",
+    "@effect-agent/sandbox": "0.1.0-beta.34",
+    "@effect-agent/session": "0.1.0-beta.34",
+    "@effect-agent/storage-cloudflare": "0.1.0-beta.34",
+    "@effect/platform-browser": "4.0.0-rc.111",
+    "@effect/sql-sqlite-do": "4.0.0-rc.111",
+    "effect": "4.0.0-rc.111"
   },
   "peerDependencies": {
-    "effect-cf": "^0.27.0"
+    "effect-cf": "^0.34.0"
   },
   "description": "Cloudflare Layer assembly for Effect Agent: Durable Objects and Browser Run adapters.",
   "license": "MIT",
@@ -54,16 +54,16 @@
   },
   "scripts": {
     "build": "vp pack",
-    "check": "tsc --noEmit -p tsconfig.json",
-    "test": "vitest run"
+    "check": "tsc --noEmit -p tsconfig.json"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "0.21.3",
-    "@cloudflare/workers-types": "5.20260813.1",
-    "@effect-agent/capabilities": "0.1.0-beta.30",
-    "@effect-agent/testing": "0.1.0-beta.30",
-    "@effect/vitest": "4.0.0-rc.110",
-    "effect-cf": "0.27.0",
+    "@cloudflare/workers-types": "5.20260825.1",
+    "@effect-agent/capabilities": "0.1.0-beta.33",
+    "@effect-agent/testing": "0.1.0-beta.33",
+    "@effect/sql-d1": "4.0.0-rc.111",
+    "@effect/vitest": "4.0.0-rc.111",
+    "effect-cf": "0.34.0",
     "esbuild": "0.28.1",
     "miniflare": "5.20260811.1-alpha",
     "typescript": "7.0.2",

package/src/bindings.ts

@@ -24,25 +24,27 @@ export class CloudflareBindingError extends Schema.TaggedError<CloudflareBinding
  * and the cross-Object transport call it through `DurableObjectNamespace` stubs. Every
  * `encoded` value is a Schema-encoded envelope (`client.ts` wire schemas for host entry
  * points, `@effect-agent/storage-cloudflare` port envelopes for `portCall`), so the RPC
- * boundary carries only structured-cloneable JSON.
+ * boundary carries only structured-cloneable JSON. The optional trailing trace context is
+ * transient native RPC metadata, stripped by an opted-in effect-cf receiver before decoding
+ * the host envelope. It never enters durable state.
  */
 export interface ConversationObjectRpc extends Rpc.DurableObjectBranded {
   /** Admission-limits gate + `DurableAgentRuntime.submit`; answers a `SubmitResponse`. */
-  submitEncoded(encoded: unknown): Promise<unknown>;
+  submitEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
   /** Wake-hinted, poll-guaranteed settlement wait; answers an `AwaitSettlementResponse`. */
-  awaitSettlementEncoded(encoded: unknown): Promise<unknown>;
+  awaitSettlementEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
   /** Event-driven durable progress wait; answers a `ProgressObserved` host response. */
-  awaitProgressEncoded(encoded: unknown): Promise<unknown>;
+  awaitProgressEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
   /** Best-effort cancellation for one in-flight progress wait. */
-  cancelProgressEncoded(encoded: unknown): Promise<unknown>;
+  cancelProgressEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
   /** One bounded page of canonical records; answers an `ObservePageResponse`. */
-  observePage(encoded: unknown): Promise<unknown>;
+  observePage(encoded: unknown, traceContext?: unknown): Promise<unknown>;
   /** Durable abort intent; answers an `AbortResponse`. */
-  abortEncoded(encoded: unknown): Promise<unknown>;
+  abortEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
   /** Durable approval decision (plan §2.6); answers a `ResolveApprovalResponse`. */
-  resolveApprovalEncoded(encoded: unknown): Promise<unknown>;
+  resolveApprovalEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
   /** Authorized DUR-017 Unknown-Outcome resolution; answers a `ResolveUnknownResponse`. */
-  resolveUnknownEncoded(encoded: unknown): Promise<unknown>;
+  resolveUnknownEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
   /** Owner-side cross-Object port endpoint (WP2 envelopes, executed on LOCAL facets). */
   portCall(encoded: unknown): Promise<unknown>;
   /** Droppable liveness hint from another Object: arms an immediate alarm. */
@@ -58,6 +60,8 @@ export class ConversationObjectNamespace extends Context.Service<
   ConversationObjectNamespace,
   {
     readonly namespace: DurableObjectNamespace<ConversationObjectRpc>;
+    /** Stable binding name for opted-in native RPC tracing; absent by default. */
+    readonly rpcTracing?: string;
   }
 >()("@effect-agent/platform-cloudflare/ConversationObjectNamespace") {
   static layer(
@@ -110,13 +114,20 @@ export const conversationNamespaceFromEnv = Effect.fn("conversationNamespaceFrom
   });
 });
 
-/** `ConversationObjectNamespace` built from the untyped Worker `env` (fails typed). */
+/**
+ * Build the namespace from Worker `env` (fails typed). Enable `rpcTracing` only when the
+ * receiver also opts into the effect-cf native RPC trace-context contract.
+ */
 export const conversationNamespaceLayer = (
   env: unknown,
   binding: string,
+  options: { readonly rpcTracing?: boolean } = {},
 ): Layer.Layer<ConversationObjectNamespace, CloudflareBindingError> =>
   Layer.effect(ConversationObjectNamespace)(
-    Effect.map(conversationNamespaceFromEnv(env, binding), (namespace) => ({ namespace })),
+    Effect.map(conversationNamespaceFromEnv(env, binding), (namespace) => ({
+      namespace,
+      ...(options.rpcTracing === true ? { rpcTracing: binding } : {}),
+    })),
   );
 
 /**

package/src/client.ts

@@ -31,6 +31,7 @@ import {
   type DurableSubmitOptions,
 } from "@effect-agent/session";
 import { Context, Crypto, Duration, Effect, Layer, Schema } from "effect";
+import { RpcTracing } from "effect-cf";
 
 import { DurableAlarmError } from "./alarm.ts";
 import { ConversationObjectNamespace, type ConversationObjectRpc } from "./bindings.ts";
@@ -318,6 +319,17 @@ const outOfContract = (
     ),
   });
 
+const hostRpcMethods = {
+  submit: "submitEncoded",
+  awaitSettlement: "awaitSettlementEncoded",
+  awaitProgress: "awaitProgressEncoded",
+  cancelProgress: "cancelProgressEncoded",
+  observePage: "observePage",
+  abort: "abortEncoded",
+  resolveApproval: "resolveApprovalEncoded",
+  resolveUnknown: "resolveUnknownEncoded",
+} as const satisfies Record<string, keyof ConversationObjectRpc>;
+
 /** Worker-side client over the Conversation Object namespace (DEPLOY-010). */
 export class CloudflareConversationClient extends Context.Service<
   CloudflareConversationClient,
@@ -379,45 +391,54 @@ export class CloudflareConversationClient extends Context.Service<
     ConversationObjectNamespace | Crypto.Crypto
   > = Layer.effect(CloudflareConversationClient)(
     Effect.gen(function* () {
-      const { namespace } = yield* ConversationObjectNamespace;
+      const { namespace, rpcTracing } = yield* ConversationObjectNamespace;
       const crypto = yield* Crypto.Crypto;
 
-      const call = (
-        conversationId: string,
-        operation: string,
-        invoke: (stub: DurableObjectStub<ConversationObjectRpc>) => Promise<unknown>,
-      ): Effect.Effect<HostResponse, ConversationClientError | HostProtocolError> =>
-        Effect.tryPromise({
-          try: () => invoke(namespace.get(namespace.idFromName(conversationId))),
-          catch: (cause) =>
-            ConversationClientError.make({
-              conversationId,
-              message: boundHostDiagnostic(
-                `${operation} did not reach the Conversation Object: ${safeCauseMessage(
-                  cause,
-                  "the RPC failed without a diagnostic",
-                )}`,
-              ),
-              cause,
-              ...cloudflareFailureSignals(cause),
-            }),
-        }).pipe(
-          Effect.flatMap((raw) =>
-            decodeHostResponse(raw).pipe(
-              Effect.mapError(
-                (error): HostProtocolError =>
-                  HostProtocolError.make({
-                    message: boundHostDiagnostic(
-                      `The ${operation} answer could not be decoded: ${error.message}`,
-                    ),
-                  }),
-              ),
+      const call = Effect.fn(
+        function* (
+          conversationId: string,
+          operation: keyof typeof hostRpcMethods,
+          encoded: unknown,
+        ): Effect.fn.Return<HostResponse, ConversationClientError | HostProtocolError> {
+          // Empty arguments preserve native arity. Passing `undefined` still adds an argument.
+          const traceArgs =
+            rpcTracing === undefined ? [] : yield* RpcTracing.withRpcTraceContext([]);
+          const raw = yield* Effect.tryPromise({
+            try: () => {
+              const stub = namespace.get(namespace.idFromName(conversationId));
+              return stub[hostRpcMethods[operation]](encoded, ...traceArgs);
+            },
+            catch: (cause) =>
+              ConversationClientError.make({
+                conversationId,
+                message: boundHostDiagnostic(
+                  `${operation} did not reach the Conversation Object: ${safeCauseMessage(
+                    cause,
+                    "the RPC failed without a diagnostic",
+                  )}`,
+                ),
+                cause,
+                ...cloudflareFailureSignals(cause),
+              }),
+          });
+          return yield* decodeHostResponse(raw).pipe(
+            Effect.mapError(
+              (error): HostProtocolError =>
+                HostProtocolError.make({
+                  message: boundHostDiagnostic(
+                    `The ${operation} answer could not be decoded: ${error.message}`,
+                  ),
+                }),
             ),
-          ),
-          Effect.withSpan("CloudflareConversationClient.call", {
-            attributes: { conversationId, operation },
-          }),
-        );
+          );
+        },
+        (effect, conversationId, operation) =>
+          rpcTracing === undefined
+            ? Effect.withSpan(effect, "CloudflareConversationClient.call", {
+                attributes: { conversationId, operation },
+              })
+            : RpcTracing.withRpcClientSpan(effect, rpcTracing, hostRpcMethods[operation]),
+      );
 
       const expect = <ResultSchema extends Schema.Top, FailureSchema extends Schema.Top>(
         conversationId: string,
@@ -464,9 +485,7 @@ export class CloudflareConversationClient extends Context.Service<
               }),
             ),
           );
-          const response = yield* call(conversationId, "observePage", (stub) =>
-            stub.observePage(encoded),
-          );
+          const response = yield* call(conversationId, "observePage", encoded);
           const page = yield* expect(
             conversationId,
             "observePage",
@@ -482,9 +501,7 @@ export class CloudflareConversationClient extends Context.Service<
       ): Effect.Effect<void> =>
         encodeCancelProgressRequest(CancelProgressRequest.make({ waiterId })).pipe(
           Effect.mapError(() => undefined),
-          Effect.flatMap((encoded) =>
-            call(conversationId, "cancelProgress", (stub) => stub.cancelProgressEncoded(encoded)),
-          ),
+          Effect.flatMap((encoded) => call(conversationId, "cancelProgress", encoded)),
           Effect.asVoid,
           Effect.ignore,
         );
@@ -526,9 +543,7 @@ export class CloudflareConversationClient extends Context.Service<
                 }),
               ),
             );
-            const response = yield* call(options.conversationId, "submit", (stub) =>
-              stub.submitEncoded(encoded),
-            );
+            const response = yield* call(options.conversationId, "submit", encoded);
             const succeeded = yield* expect(
               options.conversationId,
               "submit",
@@ -547,9 +562,7 @@ export class CloudflareConversationClient extends Context.Service<
                 }),
               ),
             );
-            const response = yield* call(receipt.conversationId, "awaitSettlement", (stub) =>
-              stub.awaitSettlementEncoded(encoded),
-            );
+            const response = yield* call(receipt.conversationId, "awaitSettlement", encoded);
             const settled = yield* expect(
               receipt.conversationId,
               "awaitSettlement",
@@ -582,9 +595,7 @@ export class CloudflareConversationClient extends Context.Service<
             );
 
             const attempt = (retry: number): Effect.Effect<void, ClientProgressFailure> =>
-              call(conversationId, "awaitProgress", (stub) =>
-                stub.awaitProgressEncoded(encoded),
-              ).pipe(
+              call(conversationId, "awaitProgress", encoded).pipe(
                 Effect.flatMap(
                   expect(
                     conversationId,
@@ -632,9 +643,7 @@ export class CloudflareConversationClient extends Context.Service<
                 }),
               ),
             );
-            const response = yield* call(conversationId, "abort", (stub) =>
-              stub.abortEncoded(encoded),
-            );
+            const response = yield* call(conversationId, "abort", encoded);
             const recorded = yield* expect(
               conversationId,
               "abort",
@@ -653,9 +662,7 @@ export class CloudflareConversationClient extends Context.Service<
                 }),
               ),
             );
-            const response = yield* call(conversationId, "resolveApproval", (stub) =>
-              stub.resolveApprovalEncoded(encoded),
-            );
+            const response = yield* call(conversationId, "resolveApproval", encoded);
             const recorded = yield* expect(
               conversationId,
               "resolveApproval",
@@ -676,9 +683,7 @@ export class CloudflareConversationClient extends Context.Service<
                 }),
               ),
             );
-            const response = yield* call(conversationId, "resolveUnknown", (stub) =>
-              stub.resolveUnknownEncoded(encoded),
-            );
+            const response = yield* call(conversationId, "resolveUnknown", encoded);
             const recorded = yield* expect(
               conversationId,
               "resolveUnknown",

package/src/conversation-object.ts

@@ -35,7 +35,6 @@ import {
   encodePortResponse,
   type PortRequest,
 } from "@effect-agent/storage-cloudflare";
-import type { DurableObject as CloudflareDurableObject } from "cloudflare:workers";
 import { Effect, Layer, Option, Schema, Stream } from "effect";
 import {
   DurableObject as EffectCfDurableObject,
@@ -110,6 +109,8 @@ import { ProgressWaitRegistry } from "./progress-wait.ts";
 
 /** Construction options for one deployed Conversation Object class. */
 export interface ConversationObjectOptions extends CloudflareDurableRuntimeOptions {
+  /** Accept transient native RPC tracing through effect-cf; disabled by default. */
+  readonly rpcTracing?: boolean;
   /**
    * Name of the Worker `env` binding carrying THIS class's `DurableObjectNamespace` — the
    * Object's route back to sibling Conversation Objects for the WP2 cross-Object port calls
@@ -676,6 +677,7 @@ const gateEndpoint: Effect.Effect<void, MaintenancePassFailure, EndpointServices
  */
 const effectCfPlatformLayer = (
   namespaceBinding: string,
+  rpcTracing = false,
 ): Layer.Layer<
   DurableObjectContext | ConversationObjectNamespace,
   CloudflareBindingError,
@@ -692,22 +694,27 @@ const effectCfPlatformLayer = (
     Effect.gen(function* () {
       const env = yield* WorkerEnvironment;
       const binding = yield* conversationNamespaceFromEnv(env, namespaceBinding);
-      return ConversationObjectNamespace.of({ namespace: binding });
+      return ConversationObjectNamespace.of({
+        namespace: binding,
+        ...(rpcTracing === true ? { rpcTracing: namespaceBinding } : {}),
+      });
     }),
   );
   return Layer.merge(context, namespace);
 };
 
-/** The public endpoint surface of one Conversation Object instance. */
-export interface ConversationObjectInstance extends CloudflareDurableObject {
-  submitEncoded(encoded: unknown): Promise<unknown>;
-  awaitSettlementEncoded(encoded: unknown): Promise<unknown>;
-  awaitProgressEncoded(encoded: unknown): Promise<unknown>;
-  cancelProgressEncoded(encoded: unknown): Promise<unknown>;
-  observePage(encoded: unknown): Promise<unknown>;
-  abortEncoded(encoded: unknown): Promise<unknown>;
-  resolveApprovalEncoded(encoded: unknown): Promise<unknown>;
-  resolveUnknownEncoded(encoded: unknown): Promise<unknown>;
+/** The public endpoints and effect-cf invocation hook of one Conversation Object instance. */
+export interface ConversationObjectInstance<EventServices = never> extends InstanceType<
+  EffectCfDurableObject.DurableObjectClass<Record<never, never>, RuntimeServices | EventServices>
+> {
+  submitEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  awaitSettlementEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  awaitProgressEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  cancelProgressEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  observePage(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  abortEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  resolveApprovalEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
+  resolveUnknownEncoded(encoded: unknown, traceContext?: unknown): Promise<unknown>;
   explainEncoded(encoded: unknown): Promise<unknown>;
   verifyEncoded(encoded: unknown): Promise<unknown>;
   retryEncoded(encoded: unknown): Promise<unknown>;
@@ -718,8 +725,8 @@ export interface ConversationObjectInstance extends CloudflareDurableObject {
 }
 
 /** The constructor shape workerd instantiates for each Conversation Object. */
-export interface ConversationObjectClass {
-  new (ctx: DurableObjectState, env: Cloudflare.Env): ConversationObjectInstance;
+export interface ConversationObjectClass<EventServices = never> {
+  new (ctx: DurableObjectState, env: Cloudflare.Env): ConversationObjectInstance<EventServices>;
 }
 
 /**
@@ -739,13 +746,13 @@ export const makeConversationObjectClass = <EventLayerError = never, EventServic
     | EffectCfDurableObjectState.DurableObjectState
     | WorkerEnvironment
   >,
-): ConversationObjectClass => {
+): ConversationObjectClass<EventServices> => {
   const application: Layer.Layer<
     RuntimeServices,
     CloudflareDurableRuntimeInitializationError | CloudflareBindingError,
     EffectCfDurableObjectState.DurableObjectState | WorkerEnvironment
   > = CloudflareDurableRuntime.layer(options).pipe(
-    Layer.provideMerge(effectCfPlatformLayer(options.namespaceBinding)),
+    Layer.provideMerge(effectCfPlatformLayer(options.namespaceBinding, options.rpcTracing)),
   );
 
   // The storage/config Layer must acquire inside Cloudflare's constructor gate. effect-cf owns
@@ -793,6 +800,7 @@ export const makeConversationObjectClass = <EventLayerError = never, EventServic
     EventLayerError,
     typeof rpc
   >(runtime, {
+    ...(options.rpcTracing === true ? { rpcTracing: { service: options.namespaceBinding } } : {}),
     ...(observability === undefined ? {} : { eventLayer: observability }),
     // Force the gated runtime Layer when Cloudflare loads this Object incarnation. Recovery stays
     // in each bounded pass so cross-Object initialization cannot deadlock.

package/src/layers.ts

@@ -1,6 +1,14 @@
 import { ConversationId } from "@effect-agent/core";
-import type { RunContextPreparation, RunCostEstimator } from "@effect-agent/engine";
-import { RunContextPreparationPassthrough } from "@effect-agent/engine";
+import type {
+  RunContextPreparation,
+  RunCostEstimator,
+  RunToolFailureObserver,
+} from "@effect-agent/engine";
+import {
+  CurrentToolFailureObserver,
+  RunContextPreparationPassthrough,
+  toolFailureObserverLayer,
+} from "@effect-agent/engine";
 import {
   AgentBindingResolver,
   DurableAgentRuntime,
@@ -82,6 +90,8 @@ export interface CloudflareDurableRuntimeOptions {
   readonly abortPollInterval?: number | undefined;
   /** Deployment-owned pricing authority used by durable cost budgets and settlements. */
   readonly estimateCostMicrousd?: RunCostEstimator | undefined;
+  /** Closed trusted Tool failure reporting. Omission masks ambient observers at construction. */
+  readonly toolFailureObserver?: RunToolFailureObserver | undefined;
   /** Milliseconds; default 25. */
   readonly observationPollInterval?: number | undefined;
   /** Bytes; default just under the 2 MB platform value limit. */
@@ -382,6 +392,10 @@ export class CloudflareDurableRuntime {
           options.operationAuthorizer === undefined
             ? Layer.empty
             : operationAuthorizerLayer(options.operationAuthorizer);
+        const observerLayer =
+          options.toolFailureObserver === undefined
+            ? Layer.succeed(CurrentToolFailureObserver)(undefined)
+            : toolFailureObserverLayer(options.toolFailureObserver);
         const bindingResolverLayer = Layer.effect(AgentBindingResolver)(
           Effect.map(
             resolveBindings(options.bindings, { ctx, env, conversationId, producerId }),
@@ -413,6 +427,7 @@ export class CloudflareDurableRuntime {
               runtimeFailpointLayer,
               reconcilerLayer,
               authorizerLayer,
+              observerLayer,
               runContextLayer,
               BrowserCrypto.layer,
             ),