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

package/src/config.ts

@@ -12,7 +12,7 @@ const PositiveMillis = Schema.Int.check(Schema.isGreaterThan(0));
 const NonNegativeMillis = Schema.Int.check(Schema.isGreaterThanOrEqualTo(0));
 
 /** The supplied Cloudflare durable runtime configuration failed validation (DEPLOY-003). */
-export class CloudflarePlatformConfigError extends Schema.TaggedErrorClass<CloudflarePlatformConfigError>()(
+export class CloudflarePlatformConfigError extends Schema.TaggedError<CloudflarePlatformConfigError>()(
   "CloudflarePlatformConfigError",
   {
     message: Schema.String,
@@ -28,7 +28,7 @@ export class CloudflarePlatformConfigError extends Schema.TaggedErrorClass<Cloud
  * Conversation Object's submit entry point before `DurableAgentRuntime.submit` runs, and
  * nothing was admitted or written.
  */
-export class AdmissionLimitExceeded extends Schema.TaggedErrorClass<AdmissionLimitExceeded>()(
+export class AdmissionLimitExceeded extends Schema.TaggedError<AdmissionLimitExceeded>()(
   "AdmissionLimitExceeded",
   {
     limit: Schema.Literals(["queue-depth", "input-bytes", "database-bytes"]),
@@ -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. */
@@ -97,16 +102,35 @@ export interface CloudflareDurableRuntimeOptions {
   readonly toolReconciler?: Layer.Layer<ToolReconciler> | undefined;
   /**
    * Registered worker Bindings resolved at durable claim time (S2, spec/subagents.md §11):
-   * build each with `DurableWorkerBinding.make(binding, digests)`. An Effect form is accepted
-   * because the capture is effectful; it runs once per incarnation during Layer construction.
-   * Defaults to the empty registration (every resolved claim fails closed).
+   * build each with `DurableWorkerBinding.make(binding, digests)`. An Effect or callback form is
+   * accepted because capture can be effectful. The callback receives the live Object context and
+   * derived identities and is evaluated once per incarnation during Layer construction. Defaults
+   * to the empty registration (every resolved claim fails closed).
    */
-  readonly bindings?:
-    | ReadonlyArray<ResolvedBinding>
-    | Effect.Effect<ReadonlyArray<ResolvedBinding>>
-    | undefined;
+  readonly bindings?: CloudflareBindingSource | undefined;
+}
+
+/** Per-incarnation host values available while registered worker Bindings are captured. */
+export interface CloudflareBindingSourceContext {
+  readonly ctx: DurableObjectState;
+  readonly env: unknown;
+  readonly conversationId: ConversationId;
+  readonly producerId: ProducerId;
 }
 
+/**
+ * Registered worker Bindings, or a closed Effect/callback that captures them once for each
+ * Durable Object incarnation. Callback Effects cannot require services or fail typed.
+ */
+export type CloudflareBindingSource =
+  | ReadonlyArray<ResolvedBinding>
+  | Effect.Effect<ReadonlyArray<ResolvedBinding>, never, never>
+  | ((
+      context: CloudflareBindingSourceContext,
+    ) =>
+      | ReadonlyArray<ResolvedBinding>
+      | Effect.Effect<ReadonlyArray<ResolvedBinding>, never, never>);
+
 /** Every construction failure of the assembled Cloudflare durable runtime stack. */
 export type CloudflareDurableRuntimeInitializationError =
   | CloudflarePlatformConfigError
@@ -161,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,
@@ -208,13 +234,19 @@ const conversationIdFromState = (
       );
 
 const resolveBindings = (
-  bindings: CloudflareDurableRuntimeOptions["bindings"],
+  source: CloudflareDurableRuntimeOptions["bindings"],
+  context: CloudflareBindingSourceContext,
 ): Effect.Effect<ReadonlyArray<ResolvedBinding>> =>
-  bindings === undefined
+  source === undefined
     ? Effect.succeed([])
-    : Effect.isEffect(bindings)
-      ? bindings
-      : Effect.succeed(bindings);
+    : Effect.isEffect(source)
+      ? source
+      : typeof source === "function"
+        ? Effect.suspend(() => {
+            const bindings = source(context);
+            return Effect.isEffect(bindings) ? bindings : Effect.succeed(bindings);
+          })
+        : Effect.succeed(source);
 
 /**
  * The DC Layer assembly (deployment §12: a Layer-assembly library, not an app entrypoint;
@@ -229,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(
@@ -243,7 +275,7 @@ export class CloudflareDurableRuntime {
   > {
     return Layer.unwrap(
       Effect.gen(function* () {
-        const { ctx } = yield* DurableObjectContext;
+        const { ctx, env } = yield* DurableObjectContext;
         const config = yield* configFromOptions(options);
         const conversationId = yield* conversationIdFromState(ctx);
         const producerId = yield* decodeProducerId(
@@ -317,7 +349,10 @@ export class CloudflareDurableRuntime {
             : Layer.succeed(DurableRuntimeFailpoint)({ hit: options.runtimeFailpoint(ctx) });
         const reconcilerLayer = options.toolReconciler ?? ToolReconciler.uncertain;
         const bindingResolverLayer = Layer.effect(AgentBindingResolver)(
-          Effect.map(resolveBindings(options.bindings), AgentBindingResolver.fromBindings),
+          Effect.map(
+            resolveBindings(options.bindings, { ctx, env, conversationId, producerId }),
+            (bindings) => AgentBindingResolver.fromBindings(bindings),
+          ),
         );
 
         const base = Layer.mergeAll(
@@ -337,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;
       }),
     );
   }