@yielded/agent-platform-cloudflare 0.1.0-beta.167 → 0.1.0-beta.168

package/src/CloudflareThreadClient.ts

@@ -1,4 +1,3 @@
-import { BrowserCrypto } from "@effect/platform-browser";
 import { AgentInputError } from "@yielded/agent/agent-error";
 import { DigestError } from "@yielded/agent/digest";
 import {
@@ -15,6 +14,7 @@ import {
   CanonicalSequence,
   DefinitionDigests,
   PersistedJson,
+  SubmissionSettledRecord,
   WorkerAdmission,
 } from "@yielded/agent/records";
 import {
@@ -30,6 +30,7 @@ import {
   IdempotencyKey,
   JoinedToHost,
   LedgerError,
+  OwnershipLost,
   Principal,
   Settlement,
   SettlementConflict,
@@ -42,10 +43,9 @@ import {
   AppendConflict,
   ThreadNotMaterialized,
   ThreadStoreError,
-  FenceRejected,
 } from "@yielded/agent/thread-store";
-import { Context, Crypto, Duration, Effect, Layer, Schema } from "effect";
-import { RpcTracing } from "effect-cf";
+import { Context, Crypto, Duration, Effect, Layer, Predicate, Schema, Stream } from "effect";
+import { RpcTargets, RpcTracing } from "effect-cf";
 
 import { DurableAlarmError } from "./Alarm.ts";
 import {
@@ -55,6 +55,16 @@ import {
 } from "./CloudflareBindings.ts";
 import { AdmissionLimitExceeded } from "./CloudflareConfig.ts";
 import { cloudflareFailureSignals, safeCauseMessage } from "./internal/boundary.ts";
+import { cloudflareCryptoLayer } from "./internal/crypto.ts";
+import {
+  Frame as LiveTextFrame,
+  isBoundedEvent,
+  MAX_DRAFT_PARTS,
+  MAX_FRAME_BYTES,
+  Request as WatchTextRequest,
+} from "./internal/live-text-protocol.ts";
+
+export { Frame as LiveTextFrame } from "./internal/live-text-protocol.ts";
 
 /**
  * The Worker↔Thread-Object host protocol (plan §1.4): Schema envelopes for the host
@@ -169,10 +179,10 @@ export const HostFailure = Schema.Union([
   UnknownResolutionConflict,
   JoinedToHost,
   LedgerError,
+  OwnershipLost,
   ThreadStoreError,
   ThreadNotMaterialized,
   AppendConflict,
-  FenceRejected,
   DurableRuntimeFailpointError,
   AdmissionLimitExceeded,
   DurableAlarmError,
@@ -198,6 +208,13 @@ export class SettlementReached extends Schema.TaggedClass<SettlementReached>(
   settlement: Settlement,
 }) {}
 
+/** The exact canonical record of an operationally finalized Submission. */
+export class SettlementRecordReached extends Schema.TaggedClass<SettlementRecordReached>(
+  "@effect-agent/platform-cloudflare/SettlementRecordReached",
+)("SettlementRecordReached", {
+  record: SubmissionSettledRecord,
+}) {}
+
 export class ObservedPage extends Schema.TaggedClass<ObservedPage>(
   "@effect-agent/platform-cloudflare/ObservedPage",
 )("ObservedPage", {
@@ -242,6 +259,7 @@ export class HostFailed extends Schema.TaggedClass<HostFailed>(
 export const HostResponse = Schema.Union([
   SubmitSucceeded,
   SettlementReached,
+  SettlementRecordReached,
   SubmissionStatusResponse,
   ObservedPage,
   ProgressObserved,
@@ -288,10 +306,10 @@ const ClientSubmitHostFailure = Schema.Union([
   AdmissionConflict,
   AdmissionPolicyError,
   LedgerError,
+  OwnershipLost,
   ThreadStoreError,
   ThreadNotMaterialized,
   AppendConflict,
-  FenceRejected,
   DurableRuntimeFailpointError,
   AdmissionLimitExceeded,
   DurableAlarmError,
@@ -300,6 +318,7 @@ const ClientSubmitHostFailure = Schema.Union([
 
 const ClientAwaitHostFailure = Schema.Union([
   LedgerError,
+  OwnershipLost,
   SettlementConflict,
   OperationDenied,
   HostProtocolError,
@@ -315,6 +334,7 @@ const ClientObserveHostFailure = Schema.Union([
 const ClientAbortHostFailure = Schema.Union([
   OperationDenied,
   LedgerError,
+  OwnershipLost,
   SettlementConflict,
   JoinedToHost,
   DurableRuntimeFailpointError,
@@ -324,6 +344,7 @@ const ClientAbortHostFailure = Schema.Union([
 
 const ClientApprovalHostFailure = Schema.Union([
   LedgerError,
+  OwnershipLost,
   SettlementConflict,
   ApprovalConflict,
   OperationDenied,
@@ -333,6 +354,7 @@ const ClientApprovalHostFailure = Schema.Union([
 
 const ClientUnknownHostFailure = Schema.Union([
   LedgerError,
+  OwnershipLost,
   SettlementConflict,
   UnknownResolutionConflict,
   JoinedToHost,
@@ -350,6 +372,127 @@ export type ClientAbortFailure = typeof ClientAbortHostFailure.Type | ThreadClie
 export type ClientApprovalFailure = typeof ClientApprovalHostFailure.Type | ThreadClientError;
 export type ClientUnknownFailure = typeof ClientUnknownHostFailure.Type | ThreadClientError;
 
+const liveTextProtocolFailure = () =>
+  HostProtocolError.make({
+    message: "Provisional text is incomplete or invalid; discard drafts and read canonical records",
+  });
+
+const decodeLiveText = (
+  threadId: ThreadId,
+  source: ReadableStream<unknown>,
+): Stream.Stream<LiveTextFrame, HostProtocolError | ThreadClientError> =>
+  Stream.suspend(() => {
+    const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false });
+    const decode = Schema.decodeUnknownSync(Schema.fromJsonString(LiveTextFrame));
+    let pending = "";
+    let pendingBytes = 0;
+    let expected = 0;
+    let streamId: string | undefined;
+    const models = new Map<string, { attemptId: string; parts: Set<string> }>();
+
+    const accept = (frame: LiveTextFrame): boolean => {
+      if (frame._tag === "Reset") {
+        if (frame.streamId === streamId || frame.threadId !== threadId)
+          throw liveTextProtocolFailure();
+        streamId = frame.streamId;
+        expected = 1;
+        models.clear();
+
+        return true;
+      }
+      if (
+        streamId === undefined ||
+        frame.streamId !== streamId ||
+        frame.sequence !== expected++ ||
+        frame.event.threadId !== threadId ||
+        !isBoundedEvent(frame.event)
+      )
+        throw liveTextProtocolFailure();
+      const event = frame.event;
+
+      if (event._tag === "AttemptEnded") {
+        for (const [key, model] of models)
+          if (model.attemptId === event.attemptId) models.delete(key);
+
+        return true;
+      }
+      const key = JSON.stringify([event.attemptId, event.runId, event.turnId, event.generation]);
+
+      if (event._tag === "Discard") {
+        models.delete(key);
+
+        return true;
+      }
+      let model = models.get(key);
+
+      if (event.part.type === "text-start") {
+        if (model?.parts.has(event.part.id)) throw liveTextProtocolFailure();
+        if (
+          [...models.values()].reduce((size, value) => size + value.parts.size, 0) >=
+          MAX_DRAFT_PARTS
+        )
+          throw liveTextProtocolFailure();
+        if (model === undefined) {
+          model = { attemptId: event.attemptId, parts: new Set() };
+          models.set(key, model);
+        }
+        model.parts.add(event.part.id);
+
+        return true;
+      }
+      if (!model?.parts.has(event.part.id)) throw liveTextProtocolFailure();
+      if (event.part.type === "text-end") {
+        model.parts.delete(event.part.id);
+        if (model.parts.size === 0) models.delete(key);
+      }
+
+      return true;
+    };
+
+    return Stream.fromReadableStream({
+      evaluate: () => source,
+      // The subscription Scope owns the single bounded cancellation after this reader unlocks.
+      releaseLockOnEnd: true,
+      onError: (cause) =>
+        ThreadClientError.make({
+          threadId,
+          message: "Provisional text disconnected; discard drafts and read canonical records",
+          cause,
+        }),
+    }).pipe(
+      Stream.mapEffect((chunk) =>
+        Effect.try({
+          try: () => {
+            if (!(chunk instanceof Uint8Array)) throw liveTextProtocolFailure();
+            const frames: LiveTextFrame[] = [];
+
+            for (let offset = 0; offset < chunk.byteLength;) {
+              const newline = chunk.indexOf(10, offset);
+              const end = newline < 0 ? chunk.byteLength : newline;
+
+              pendingBytes += end - offset;
+              if (pendingBytes > MAX_FRAME_BYTES) throw liveTextProtocolFailure();
+              pending += decoder.decode(chunk.subarray(offset, end), { stream: newline < 0 });
+              offset = end + 1;
+              if (newline < 0) break;
+              const frame = decode(pending);
+
+              pending = "";
+              pendingBytes = 0;
+              if (accept(frame)) frames.push(frame);
+            }
+
+            return frames;
+          },
+          catch: liveTextProtocolFailure,
+        }),
+      ),
+      Stream.flatMap(Stream.fromArray),
+      // This connection is open-ended. Clean EOF is also loss of provisional state.
+      Stream.concat(Stream.fail(liveTextProtocolFailure())),
+    );
+  });
+
 const outOfContract = (threadId: string, operation: string, observed: string): ThreadClientError =>
   ThreadClientError.make({
     threadId,
@@ -361,6 +504,7 @@ const outOfContract = (threadId: string, operation: string, observed: string): T
 const hostRpcMethods = {
   submit: "submitEncoded",
   awaitSettlement: "awaitSettlementEncoded",
+  awaitSettlementRecord: "awaitSettlementRecordEncoded",
   submissionStatus: "submissionStatusEncoded",
   awaitProgress: "awaitProgressEncoded",
   cancelProgress: "cancelProgressEncoded",
@@ -385,6 +529,14 @@ export class CloudflareThreadClient extends Context.Service<
       receipt: Receipt,
     ) => Effect.Effect<SubmissionStatus, ClientAwaitFailure>;
     readonly awaitSettlement: (receipt: Receipt) => Effect.Effect<Settlement, ClientAwaitFailure>;
+    /**
+     * Wait for finalization and return this Receipt's canonical terminal record in one RPC.
+     * Requires both settlement and observation authority. Decode an ordinary completed
+     * record's result through the Agent output Schema; joined completion may have no result.
+     */
+    readonly awaitSettlementRecord: (
+      receipt: Receipt,
+    ) => Effect.Effect<SubmissionSettledRecord, ClientAwaitFailure>;
     /**
      * Wait without polling until progress after `afterSequence` is already durable or hinted.
      * The result is deliberately void: canonical records remain authoritative and must be read.
@@ -394,6 +546,14 @@ export class CloudflareThreadClient extends Context.Service<
       threadId: ThreadId,
       afterSequence: CanonicalSequence,
     ) => Effect.Effect<void, ClientProgressFailure>;
+    /**
+     * Current provisional text followed by native deltas. Reset starts a replacement snapshot,
+     * including when a slow consumer exceeds the fixed backlog. Reconcile by
+     * Run/Turn identity to canonical records; discard drafts on Discard, AttemptEnded,
+     * Reset or stream failure. Snapshots exist only in the Object incarnation's memory.
+     * Scope the stream: interruption cancels its remote subscription.
+     */
+    readonly watchText: (threadId: ThreadId) => Stream.Stream<LiveTextFrame, ClientObserveFailure>;
     /** One bounded page of canonical records. */
     readonly readPage: (
       threadId: ThreadId,
@@ -439,7 +599,10 @@ export class CloudflareThreadClient extends Context.Service<
     readonly rpcTracing?: string;
   }): Layer.Layer<CloudflareThreadClient> {
     return CloudflareThreadClient.layer.pipe(
-      Layer.provide([ThreadObjectNamespace.layer(options.namespace, options), BrowserCrypto.layer]),
+      Layer.provide([
+        ThreadObjectNamespace.layer(options.namespace, options),
+        cloudflareCryptoLayer,
+      ]),
     );
   }
 
@@ -453,7 +616,7 @@ export class CloudflareThreadClient extends Context.Service<
       const { rpcTracing } = namespace;
       const crypto = yield* Crypto.Crypto;
 
-      const call = Effect.fn(
+      const call = Effect.fnUntraced(
         function* (
           threadId: ThreadId,
           operation: keyof typeof hostRpcMethods,
@@ -676,9 +839,31 @@ export class CloudflareThreadClient extends Context.Service<
             return settled.settlement;
           }),
 
+        awaitSettlementRecord: (receipt) =>
+          Effect.gen(function* () {
+            const encoded = yield* encodeReceipt(receipt).pipe(
+              Effect.mapError((error) =>
+                HostProtocolError.make({
+                  message: boundHostDiagnostic(`receipt encode failed: ${error.message}`),
+                }),
+              ),
+            );
+
+            const response = yield* call(receipt.threadId, "awaitSettlementRecord", encoded);
+
+            const settled = yield* expect(
+              receipt.threadId,
+              "awaitSettlementRecord",
+              SettlementRecordReached,
+              ClientAwaitHostFailure,
+            )(response);
+
+            return settled.record;
+          }),
+
         awaitProgress: (threadId, afterSequence) =>
           Effect.gen(function* () {
-            const waiterId = yield* crypto.randomUUIDv4.pipe(
+            const waiterId = yield* crypto.randomUUIDv4().pipe(
               Effect.mapError((error) =>
                 HostProtocolError.make({
                   message: boundHostDiagnostic(
@@ -718,6 +903,101 @@ export class CloudflareThreadClient extends Context.Service<
             yield* attempt(0).pipe(Effect.onInterrupt(() => cancelProgress(threadId, waiterId)));
           }),
 
+        watchText: (threadId) =>
+          Stream.unwrap(
+            Effect.gen(function* () {
+              const traceArgs =
+                rpcTracing === undefined ? [] : yield* RpcTracing.withRpcTraceContext([]);
+
+              const openingFailure = (cause: unknown) =>
+                ThreadClientError.make({
+                  threadId,
+                  message: "Provisional text observation could not reach the Thread Object",
+                  cause,
+                  ...cloudflareFailureSignals(cause),
+                });
+
+              // Retain the original RPC promise: resolving through callThreadObject would
+              // erase its optional native disposer before an interrupted opening can use it.
+              const target = yield* RpcTargets.get(namespace, threadId, () =>
+                namespace.get(threadId),
+              ).pipe(Effect.mapError(openingFailure));
+
+              let request: Promise<unknown> | undefined;
+              let received: unknown;
+              let closed = false;
+
+              const cancel = () => {
+                const value = received;
+
+                received = undefined;
+
+                return value instanceof ReadableStream && !value.locked
+                  ? value.cancel().catch(() => undefined)
+                  : Promise.resolve();
+              };
+
+              // Install ownership before invoking foreign code, not after its promise settles.
+              yield* Effect.addFinalizer(() =>
+                Effect.try({
+                  try: () => {
+                    closed = true;
+                    if (Predicate.hasProperty(request, Symbol.dispose)) {
+                      const dispose = request[Symbol.dispose];
+
+                      if (typeof dispose === "function") dispose.call(request);
+                    }
+                  },
+                  catch: () => undefined,
+                }).pipe(
+                  Effect.ignore,
+                  Effect.andThen(
+                    Effect.tryPromise({ try: cancel, catch: () => undefined }).pipe(
+                      Effect.interruptible,
+                      Effect.timeout(PROGRESS_CANCELLATION_TIMEOUT),
+                      Effect.ignore,
+                    ),
+                  ),
+                ),
+              );
+
+              const raw = yield* Effect.tryPromise({
+                try: () => {
+                  request = target.watchTextEncoded(
+                    Schema.encodeSync(WatchTextRequest)({ schemaVersion: 1 }),
+                    ...traceArgs,
+                  );
+
+                  return request.then((value) => {
+                    received = value;
+
+                    // A custom endpoint may return a plain, non-cancellable promise. Keep
+                    // late cleanup on that native promise chain; it starts no Effect fiber.
+                    return closed ? cancel().then(() => value) : value;
+                  });
+                },
+                catch: openingFailure,
+              }).pipe(
+                Effect.interruptible,
+                Effect.tapCause(() => RpcTargets.invalidate(target)),
+              );
+
+              if (raw instanceof ReadableStream) return decodeLiveText(threadId, raw);
+
+              const response = yield* decodeHostResponse(raw).pipe(
+                Effect.mapError(liveTextProtocolFailure),
+              );
+
+              if (
+                response._tag === "HostFailed" &&
+                Schema.is(ClientObserveHostFailure)(response.failure)
+              )
+                return yield* response.failure;
+
+              return yield* liveTextProtocolFailure();
+            }),
+          ),
+
         readPage,
 
         readAll: (threadId) =>