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

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/interactive-browser.ts

@@ -22,10 +22,13 @@ import {
   InteractiveBrowserPolicy,
   InteractiveBrowserPolicyDeniedError,
   InteractiveBrowserProtocolError,
+  InteractiveBrowserTargetUrl,
+  InteractiveBrowserUnsupportedError,
   PageScreenshotResult,
   SandboxImplementation,
   type BrowserHandle,
   type InteractiveBrowserError,
+  type InteractiveBrowserNetworkPolicy,
 } from "@effect-agent/sandbox";
 import {
   Context,
@@ -170,7 +173,7 @@ type BrowserFailure = typeof InteractiveBrowserError.Type;
 type BrowserOperation = InteractiveBrowserActionError["operation"];
 
 interface InteractiveBrowserPolicySnapshot {
-  readonly allowedHosts: ReadonlyArray<string>;
+  readonly network: Exclude<InteractiveBrowserNetworkPolicy, { readonly _tag: "PublicWeb" }>;
   readonly maxActions: number;
   readonly maxElapsedMillis: number;
   readonly maxReturnedBytes: number;
@@ -443,29 +446,46 @@ const isRemoteClosure = (cause: unknown): boolean =>
     causeText(cause),
   );
 
-const snapshotPolicy = (
+const snapshotPolicy = Effect.fn("BrowserRunInteractive.snapshotPolicy")(function* (
   input: InteractiveBrowserPolicy,
-): Effect.Effect<InteractiveBrowserPolicySnapshot, InteractiveBrowserPolicyDeniedError> =>
-  Schema.decodeUnknownEffect(InteractiveBrowserPolicy)(input).pipe(
+): Effect.fn.Return<
+  InteractiveBrowserPolicySnapshot,
+  InteractiveBrowserPolicyDeniedError | InteractiveBrowserUnsupportedError
+> {
+  const decoded = yield* Schema.decodeUnknownEffect(InteractiveBrowserPolicy)(input).pipe(
     Effect.mapError(() => policyError("The interactive browser policy is malformed")),
-    Effect.map((decoded) =>
-      Object.freeze({
-        allowedHosts: Object.freeze([...decoded.allowedHosts]),
-        maxActions: decoded.maxActions,
-        maxElapsedMillis: decoded.maxElapsedMillis,
-        maxReturnedBytes: decoded.maxReturnedBytes,
-      }),
-    ),
   );
+  if (decoded.network._tag === "PublicWeb") {
+    return yield* InteractiveBrowserUnsupportedError.make({
+      implementation: browserRunInteractiveImplementation,
+      feature: "policy",
+      message:
+        "Cloudflare Browser Run cannot enforce the PublicWeb network policy for all session traffic",
+    });
+  }
+  return Object.freeze({
+    network:
+      decoded.network._tag === "ExactHosts"
+        ? Object.freeze({
+            _tag: decoded.network._tag,
+            allowedHosts: Object.freeze([...decoded.network.allowedHosts]),
+          })
+        : Object.freeze({ _tag: decoded.network._tag }),
+    maxActions: decoded.maxActions,
+    maxElapsedMillis: decoded.maxElapsedMillis,
+    maxReturnedBytes: decoded.maxReturnedBytes,
+  });
+});
 
 const hostAllowed = (policy: InteractiveBrowserPolicySnapshot, value: string): boolean => {
+  if (policy.network._tag === "Unrestricted") return true;
   try {
     const url = new URL(value);
     return (
       url.protocol === "https:" &&
       url.username === "" &&
       url.password === "" &&
-      policy.allowedHosts.some((host) => host === url.host)
+      policy.network.allowedHosts.some((host) => host === url.host)
     );
   } catch {
     return false;
@@ -756,7 +776,7 @@ const makeHandle = Effect.fn("BrowserRunInteractive.makeHandle")(function* (
           return yield* decodeNavigationResult(page, policy);
         }),
         Effect.suspend(() =>
-          hostAllowed(policy, request.url)
+          Schema.is(InteractiveBrowserTargetUrl)(request.url) && hostAllowed(policy, request.url)
             ? Effect.void
             : Effect.fail(policyError("The navigation URL is outside the browser policy")),
         ),

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,
             ),