@effect-agent/platform-cloudflare 0.0.1-beta.5 → 0.0.1-beta.6

package/src/config.ts

@@ -103,6 +103,8 @@ export class CloudflareDurableRuntimeConfigValue extends Schema.Class<Cloudflare
   abortPollInterval: PositiveMillis,
   /** Canonical observation poll cadence of the Durable Object store. */
   observationPollInterval: NonNegativeMillis,
+  /** Cooperative background-export budget; native Object delivery never awaits the flush. */
+  telemetryFlushTimeout: PositiveMillis,
   /** Per-value byte bound; must stay under the platform's 2 MB SQLite value limit. */
   maxStoredValueBytes: Schema.Int.check(
     Schema.isGreaterThan(0),
@@ -129,6 +131,7 @@ export const CLOUDFLARE_RUNTIME_DEFAULTS = {
   leaseRenewalInterval: 10_000,
   abortPollInterval: 500,
   observationPollInterval: 25,
+  telemetryFlushTimeout: 2_000,
   maxStoredValueBytes: DEFAULT_MAX_STORED_VALUE_BYTES,
   verifyOnOpen: false,
   maxQueueDepthPerLane: 256,

package/src/conversation-object.ts

@@ -38,6 +38,7 @@ import {
   DurableObjectContext,
   conversationNamespaceLayer,
   type CloudflareBindingError,
+  type ConversationObjectNamespace,
 } from "./bindings.ts";
 import {
   AbortRecorded,
@@ -67,9 +68,18 @@ import {
   type CloudflareDurableRuntimeOptions,
   type CloudflareDurableRuntimeServices,
 } from "./layers.ts";
+import {
+  flushCloudflareRuntimeTelemetry,
+  logCloudflareWaitUntilRegistrationFailure,
+  makeCloudflareTelemetryFlushCoordinator,
+  registerCloudflareTelemetryAfterNativeSettlement,
+  withCloudflareNativeSpanFailure,
+  type CloudflareTelemetryFlushCoordinator,
+} from "./telemetry-internal.ts";
+import { CloudflareRuntimeTelemetry } from "./telemetry.ts";
 
 /**
- * `makeConversationObjectClass(options)` — the Conversation Durable Object (plan §1.4,
+ * `makeConversationObjectClass(options, telemetry?)` — the Conversation Durable Object (plan §1.4,
  * D-P6-1): a factory returning a class that applications export from their Worker entry.
  * One SQLite-backed Object per Conversation is the serialized owner (durability §6); the
  * Object never runs `runResolvedWorker`'s infinite loop — each ingress event or alarm runs
@@ -95,9 +105,15 @@ export interface ConversationObjectOptions extends CloudflareDurableRuntimeOptio
   readonly namespaceBinding: string;
 }
 
-type ConversationObjectError = CloudflareDurableRuntimeInitializationError | CloudflareBindingError;
+type ConversationObjectError<TelemetryError> =
+  | CloudflareDurableRuntimeInitializationError
+  | CloudflareBindingError
+  | TelemetryError;
 
-type EndpointServices = CloudflareDurableRuntimeServices | DurableObjectContext;
+type EndpointServices =
+  | CloudflareDurableRuntimeServices
+  | DurableObjectContext
+  | CloudflareRuntimeTelemetry;
 
 /** Port envelope tags whose owner-side execution durably mutates this Object's lane. */
 const MUTATING_PORT_TAGS: ReadonlySet<string> = new Set([
@@ -608,6 +624,54 @@ const gateEndpoint: Effect.Effect<void, unknown, EndpointServices> = Effect.gen(
   yield* maintenance.ensureAlarm;
 });
 
+const NATIVE_ENTRYPOINTS = [
+  "submit",
+  "await_settlement",
+  "observe",
+  "abort",
+  "resolve_approval",
+  "resolve_unknown",
+  "explain",
+  "verify",
+  "retry",
+  "obligations",
+  "port_call",
+  "wake",
+  "alarm",
+] as const;
+
+type NativeEntrypoint = (typeof NATIVE_ENTRYPOINTS)[number];
+
+/**
+ * Owner-side delivery measurement. The exact endpoint Cause is hidden behind a bounded typed
+ * marker while the span closes, then restored together with any newly composed real reasons.
+ */
+const observeNativeEntrypoint = <A, E>(
+  entrypoint: NativeEntrypoint,
+  effect: Effect.Effect<A, E, EndpointServices>,
+): Effect.Effect<A, E, EndpointServices> =>
+  Effect.gen(function* () {
+    const identity = yield* ConversationObjectIdentity;
+    const config = yield* CloudflareDurableRuntimeConfig;
+    return yield* withCloudflareNativeSpanFailure(effect, (masked) =>
+      masked.pipe(
+        Effect.withSpan(`effect_agent.cloudflare.conversation_object.${entrypoint}`, {
+          kind: "server",
+          attributes: {
+            "effect_agent.cloudflare.entrypoint": entrypoint,
+            "effect_agent.deployment.id": config.deploymentId,
+            conversationId: identity.conversationId,
+            producerId: identity.producerId,
+          },
+        }),
+      ),
+    );
+  });
+
+const flushNativeEntrypointTelemetry = Effect.flatMap(CloudflareDurableRuntimeConfig, (config) =>
+  flushCloudflareRuntimeTelemetry(config.telemetryFlushTimeout),
+);
+
 /** The public endpoint surface of one Conversation Object instance. */
 export interface ConversationObjectInstance extends DurableObject {
   submitEncoded(encoded: unknown): Promise<unknown>;
@@ -631,84 +695,151 @@ export interface ConversationObjectClass {
 }
 
 /**
- * Build the application's Conversation Object class (export it from the
- * Worker entry). The explicit return type is what makes declaration emit
- * possible: the class body carries a private runtime field, and TS4094
- * rejects inferring an exported anonymous class type around it.
+ * Build the application's Conversation Object class (export it from the Worker entry).
+ * `telemetry` is the host composition boundary: it may require the Object context/namespace and
+ * retain a typed acquisition error, while any additional output services remain available to the
+ * cached runtime. `TelemetryError` stays the first explicit generic for source compatibility;
+ * additional outputs infer from the Layer. Omitting it installs the content-free no-op service.
+ * The explicit return type is what makes declaration emit possible: the class body carries a
+ * private runtime field, and TS4094 rejects inferring an exported anonymous class type around it.
  */
-export const makeConversationObjectClass = (
+export const makeConversationObjectClass = <
+  TelemetryError = never,
+  AdditionalTelemetryOutputs = never,
+>(
   options: ConversationObjectOptions,
+  telemetry?: Layer.Layer<
+    CloudflareRuntimeTelemetry | AdditionalTelemetryOutputs,
+    TelemetryError,
+    DurableObjectContext | ConversationObjectNamespace
+  >,
 ): ConversationObjectClass => {
   class ConversationObject extends DurableObject {
-    readonly #runtime: ManagedRuntime.ManagedRuntime<EndpointServices, ConversationObjectError>;
+    readonly #runtime: ManagedRuntime.ManagedRuntime<
+      EndpointServices,
+      ConversationObjectError<TelemetryError>
+    >;
+    readonly #ctx: DurableObjectState;
+    readonly #telemetryFlush: CloudflareTelemetryFlushCoordinator;
 
     constructor(ctx: DurableObjectState, env: Cloudflare.Env) {
       super(ctx, env);
+      this.#ctx = ctx;
+      const platform = Layer.mergeAll(
+        DurableObjectContext.layer(ctx, env),
+        conversationNamespaceLayer(env, options.namespaceBinding),
+      );
+      // Host observability is composed at the Worker edge, not hidden in runtime options. Its
+      // typed acquisition failure remains in the ManagedRuntime error, while the Object context
+      // and namespace are available to Layers that derive exporter configuration from `env`.
+      const hostTelemetry = (telemetry ?? CloudflareRuntimeTelemetry.layerNoop).pipe(
+        Layer.provideMerge(platform),
+      );
       this.#runtime = ManagedRuntime.make(
         CloudflareDurableRuntime.layer(options).pipe(
-          Layer.provideMerge(
-            Layer.mergeAll(
-              DurableObjectContext.layer(ctx, env),
-              conversationNamespaceLayer(env, options.namespaceBinding),
-            ),
-          ),
+          // Supplying the host Layer outermost makes its Logger/Tracer/Metric runtime
+          // configuration observe application Layer acquisition and every native endpoint.
+          Layer.provideMerge(hostTelemetry),
         ),
       );
+      this.#telemetryFlush = makeCloudflareTelemetryFlushCoordinator(
+        () => this.#runtime.runPromise(flushNativeEntrypointTelemetry),
+        {
+          onReservationDropped: () => {
+            void this.#runtime.runSyncExit(
+              Effect.logWarning(
+                "Cloudflare telemetry delivery coalesced at the batch reservation limit",
+              ).pipe(
+                Effect.annotateLogs({
+                  "effect_agent.cloudflare.telemetry.failure_kind": "reservation_limit",
+                }),
+              ),
+            );
+          },
+        },
+      );
       // The constructor gate: local-only checks; never the recovery pass (deadlock argument,
       // plan §1.4). A failure here fails every delivery with the typed construction error.
       ctx.blockConcurrencyWhile(() => this.#runtime.runPromise(gateEndpoint));
     }
 
+    #runNative<A, E>(
+      entrypoint: NativeEntrypoint,
+      effect: Effect.Effect<A, E, EndpointServices>,
+    ): Promise<A> {
+      const delivery = this.#runtime.runPromise(observeNativeEntrypoint(entrypoint, effect));
+      // Reserve synchronously with the current native delivery, but do not await export from the
+      // RPC/alarm Promise. Each pending/trailing/queued batch waits for its assigned deliveries to
+      // settle and only its first owner registers the shared background Promise. Even an
+      // uninterruptible exporter therefore cannot delay a caller, suppress alarm retry, accumulate
+      // concurrent exporter work, an unbounded waitUntil registration queue, or unbounded retained
+      // delivery Promises. Excess arrivals are diagnosed and lossy-coalesced at the batch cap.
+      // Registration failure and every asynchronous flush failure remain isolated from delivery.
+      return registerCloudflareTelemetryAfterNativeSettlement(
+        (background) => this.#ctx.waitUntil(background),
+        delivery,
+        this.#telemetryFlush.reserve,
+        (cause) => {
+          // Native entrypoints run only after blockConcurrencyWhile has built the cached runtime.
+          // Effect Logger invocation is synchronous; runSyncExit captures a broken logger without
+          // starting an unscoped fiber or changing the delivery Promise. The exact platform value
+          // stays confined to this registration callback; the automatic Logger diagnostic is
+          // deliberately content-free.
+          void this.#runtime.runSyncExit(logCloudflareWaitUntilRegistrationFailure(cause));
+        },
+      );
+    }
+
     async submitEncoded(encoded: unknown): Promise<unknown> {
-      return this.#runtime.runPromise(submitEndpoint(encoded));
+      return this.#runNative("submit", submitEndpoint(encoded));
     }
 
     async awaitSettlementEncoded(encoded: unknown): Promise<unknown> {
-      return this.#runtime.runPromise(awaitSettlementEndpoint(encoded));
+      return this.#runNative("await_settlement", awaitSettlementEndpoint(encoded));
     }
 
     async observePage(encoded: unknown): Promise<unknown> {
-      return this.#runtime.runPromise(observePageEndpoint(encoded));
+      return this.#runNative("observe", observePageEndpoint(encoded));
     }
 
     async abortEncoded(encoded: unknown): Promise<unknown> {
-      return this.#runtime.runPromise(abortEndpoint(encoded));
+      return this.#runNative("abort", abortEndpoint(encoded));
     }
 
     async resolveApprovalEncoded(encoded: unknown): Promise<unknown> {
-      return this.#runtime.runPromise(resolveApprovalEndpoint(encoded));
+      return this.#runNative("resolve_approval", resolveApprovalEndpoint(encoded));
     }
 
     async resolveUnknownEncoded(encoded: unknown): Promise<unknown> {
-      return this.#runtime.runPromise(resolveUnknownEndpoint(encoded));
+      return this.#runNative("resolve_unknown", resolveUnknownEndpoint(encoded));
     }
 
     async explainEncoded(encoded: unknown): Promise<unknown> {
-      return this.#runtime.runPromise(explainEndpoint(encoded));
+      return this.#runNative("explain", explainEndpoint(encoded));
     }
 
     async verifyEncoded(encoded: unknown): Promise<unknown> {
-      return this.#runtime.runPromise(verifyEndpoint(encoded));
+      return this.#runNative("verify", verifyEndpoint(encoded));
     }
 
     async retryEncoded(encoded: unknown): Promise<unknown> {
-      return this.#runtime.runPromise(retryEndpoint(encoded));
+      return this.#runNative("retry", retryEndpoint(encoded));
     }
 
     async obligationsEncoded(encoded: unknown): Promise<unknown> {
-      return this.#runtime.runPromise(obligationsEndpoint(encoded));
+      return this.#runNative("obligations", obligationsEndpoint(encoded));
     }
 
     async portCall(encoded: unknown): Promise<unknown> {
-      return this.#runtime.runPromise(portCallEndpoint(encoded));
+      return this.#runNative("port_call", portCallEndpoint(encoded));
     }
 
     async wake(): Promise<void> {
-      await this.#runtime.runPromise(wakeEndpoint);
+      await this.#runNative("wake", wakeEndpoint);
     }
 
     override async alarm(): Promise<void> {
-      await this.#runtime.runPromise(alarmEndpoint);
+      await this.#runNative("alarm", alarmEndpoint);
     }
   }
 

package/src/index.ts

@@ -17,6 +17,8 @@ export * from "./config.ts";
 export * from "./alarm.ts";
 export * from "./wake-scheduler.ts";
 export * from "./transport.ts";
+export * from "./telemetry.ts";
 export * from "./layers.ts";
 export * from "./conversation-object.ts";
 export * from "./client.ts";
+export * from "./code-mode-executor.ts";

package/src/layers.ts

@@ -31,8 +31,8 @@ import { Context, Duration, Effect, Layer, Schema } from "effect";
 import { ConversationMaintenance, DurableAlarmService } from "./alarm.ts";
 import {
   ConversationObjectIdentity,
-  ConversationObjectNamespace,
   DurableObjectContext,
+  type ConversationObjectNamespace,
 } from "./bindings.ts";
 import {
   CLOUDFLARE_RUNTIME_DEFAULTS,
@@ -69,6 +69,11 @@ export interface CloudflareDurableRuntimeOptions {
   readonly abortPollInterval?: number | undefined;
   /** Milliseconds; default 25. */
   readonly observationPollInterval?: number | undefined;
+  /**
+   * Milliseconds; default 2000. Cooperative budget for the background exporter flush registered
+   * after each native RPC, wake, or alarm span. Delivery never awaits the flush.
+   */
+  readonly telemetryFlushTimeout?: number | undefined;
   /** Bytes; default just under the 2 MB platform value limit. */
   readonly maxStoredValueBytes?: number | undefined;
   /** Default false. */
@@ -180,6 +185,8 @@ const configFromOptions = (
     abortPollInterval: options.abortPollInterval ?? CLOUDFLARE_RUNTIME_DEFAULTS.abortPollInterval,
     observationPollInterval:
       options.observationPollInterval ?? CLOUDFLARE_RUNTIME_DEFAULTS.observationPollInterval,
+    telemetryFlushTimeout:
+      options.telemetryFlushTimeout ?? CLOUDFLARE_RUNTIME_DEFAULTS.telemetryFlushTimeout,
     maxStoredValueBytes:
       options.maxStoredValueBytes ?? CLOUDFLARE_RUNTIME_DEFAULTS.maxStoredValueBytes,
     verifyOnOpen: options.verifyOnOpen ?? CLOUDFLARE_RUNTIME_DEFAULTS.verifyOnOpen,
@@ -254,9 +261,9 @@ const resolveBindings = (
  * Storage compatibility is verified during construction: an incompatible database fails the
  * Layer typed (`DoStorageCompatibilityError`) before anything is mutated (DEPLOY-008).
  *
- * Requires only the two binding services (`DurableObjectContext`,
- * `ConversationObjectNamespace`) — platform values enter exclusively through Layers
- * (DEPLOY-010).
+ * Requires the two binding services (`DurableObjectContext`, `ConversationObjectNamespace`).
+ * Host observability belongs to the Worker composition edge because native entrypoint lifecycle
+ * instrumentation, rather than this durable runtime assembly, consumes it (DEPLOY-010).
  */
 export class CloudflareDurableRuntime {
   static layer(
@@ -365,11 +372,13 @@ export class CloudflareDurableRuntime {
           Layer.provideMerge(base),
         );
 
-        return Layer.mergeAll(
+        const application = Layer.mergeAll(
           runtimeStack,
           ConversationMaintenance.layer.pipe(Layer.provide(runtimeStack)),
           portsEndpointLayer,
         );
+
+        return application;
       }),
     );
   }