@shpitdev/convex-cliproxy-observability 0.3.5 → 0.3.7

package/src/protocols/checkpoint.ts

@@ -1,3 +1,4 @@
+import { stockHookPieces } from "./body-parts.js";
 import {
   providerIdentity,
   TOKEN_FIELDS,
@@ -6,7 +7,7 @@ import {
   type PrivateContentReference,
 } from "../model-call/index.js";
 import type { CaptureObservationV1 } from "../capture/index.js";
-import { decodeBody } from "../capture/index.js";
+import { continuesBodyPart, decodeBody } from "../capture/index.js";
 import { assembleResponsesStream } from "./responses.js";
 import { SSEReader, type SSECheckpoint } from "./framing.js";
 import { count, list, nanoTime, object, parseObject } from "./values.js";
@@ -27,6 +28,10 @@ export type ProjectionCheckpoint = {
   streamed?: boolean;
   inputSeen?: boolean;
   chatFinished?: boolean;
+  /** First segment of an unfinished split body; projection reassembles from there. */
+  bodyPartSegment?: number;
+  /** Last part of an unfinished split body; the next observation must continue it. */
+  openBodyPart?: Pick<CaptureObservationV1, "kind" | "sequence" | "bodyPart">;
 };
 const usageFields = [
   "input_tokens",
@@ -185,19 +190,55 @@ function observeProtocol(
     }
   }
 }
+/**
+ * Split bodies up to this size are reassembled for scalar projection. Larger ones
+ * stay complete in raw segments; projection does not allocate them in a 64 MiB
+ * Convex action.
+ */
+export const MAX_PROJECTED_SPLIT_BYTES = 8 * 1024 * 1024;
+/**
+ * Earlier parts of a split body only advance the sequence. The final part needs
+ * the exact reassembled body (`BodyPartAssembler`) as `assembled`, or `null` when
+ * the body exceeds `MAX_PROJECTED_SPLIT_BYTES` and its semantics are not projected.
+ */
 export function applyObservation(
   call: ModelCallV1,
   state: ProjectionCheckpoint,
   o: CaptureObservationV1,
+  assembled?: Uint8Array | null,
 ): void {
   if (o.sequence !== call.capture.projectedThroughSequence + 1)
     throw new Error("projection sequence gap");
+  if (o.captureIncomplete) call.capture.incomplete = true;
+  if (o.lostContentBytes !== undefined)
+    call.capture.lostContentBytes = Math.max(
+      call.capture.lostContentBytes ?? 0,
+      o.lostContentBytes,
+    );
   if (o.gap) {
     state.rawGap = true;
     if (!call.capture.gaps.includes(o.gap) && call.capture.gaps.length < 8)
       call.capture.gaps.push(o.gap.slice(0, 128));
   }
-  const body = decodeBody(o);
+  const part = o.bodyPart;
+  // Segments validate only their own neighbors; continuity across them is checked here.
+  if (
+    (state.openBodyPart || (part && part.index > 0)) &&
+    !(state.openBodyPart && continuesBodyPart(state.openBodyPart, o))
+  )
+    throw new Error("body part interrupted");
+  const deferred = part !== undefined && part.index < part.count - 1;
+  state.openBodyPart = deferred
+    ? { kind: o.kind, sequence: o.sequence, bodyPart: part }
+    : undefined;
+  if (part && !deferred && assembled === undefined)
+    throw new Error("split body requires reassembly");
+  const unprojected = part !== undefined && !deferred && assembled === null;
+  if (unprojected && part.totalBytes <= MAX_PROJECTED_SPLIT_BYTES)
+    throw new Error("split body within projection bound");
+  // Like an over-limit SSE frame: content is retained, its semantics are not decoded.
+  if (unprojected && o.kind !== "request") state.invalid = state.frameLimit = true;
+  const body = deferred || unprojected ? new Uint8Array() : (assembled ?? decodeBody(o));
   const decoder = new TextDecoder("utf-8", { fatal: true });
   // A new after-auth event replaces the selection, including unknown fields.
   // Stream initialization may omit auth; an explicit selection replaces the pair.
@@ -220,14 +261,21 @@ export function applyObservation(
     call.correlationConflicts = o.correlationConflicts ?? [];
     call.traceId = o.correlation?.traceId;
     call.sourceTraceId = o.sourceTraceId;
-    try {
-      const input = parseObject(decoder.decode(body));
-      state.streamed = input.stream === true;
-      call.streamed = state.streamed;
-    } catch {
-      state.invalid = true;
+    if (!deferred && !unprojected) {
+      try {
+        const input = parseObject(decoder.decode(body));
+        state.streamed = input.stream === true;
+        call.streamed = state.streamed;
+      } catch {
+        state.invalid = true;
+      }
     }
   }
+  // An unparsed request (e.g. a split body over the projection bound) takes
+  // streaming from the protocol evidence that follows it.
+  if (call.streamed === undefined && (o.kind === "stream_init" || o.kind === "stream_chunk"))
+    call.streamed = true;
+  else if (call.streamed === undefined && o.kind === "response") call.streamed = false;
   // Derived read fields: reads fill them only for summaries projected before 0.3.0.
   Object.assign(call, providerIdentity(call), { costProvenance: call.cost.kind });
   if (o.kind === "response" || o.kind === "stream_chunk" || o.kind === "completion") {
@@ -244,9 +292,13 @@ export function applyObservation(
       }
       if ((o.kind === "stream_chunk" || o.kind === "completion") && body.length) {
         const reader = new SSEReader(state.sse);
-        for (const frame of o.bodyFraming === "stock_hook_chunk"
-          ? reader.feedStock(body, call.clientProtocol, o.observedAt)
-          : reader.feed(body, o.observedAt)) {
+        const pieces = o.bodyFraming === "stock_hook_block" ? stockHookPieces(o, body) : [body];
+        const frames = pieces.flatMap((piece) =>
+          o.bodyFraming === "stock_hook_chunk" || o.bodyFraming === "stock_hook_block"
+            ? reader.feedStock(piece, call.clientProtocol, o.observedAt)
+            : reader.feed(piece, o.observedAt),
+        );
+        for (const frame of frames) {
           if (frame.data === "[DONE]") {
             if (call.clientProtocol === "chat_completions" && state.chatFinished)
               state.terminal = "completed";
@@ -287,17 +339,19 @@ export function applyObservation(
       call.latencyMs = Number(BigInt(call.endTimeUnixNano) - BigInt(start)) / 1e6;
     call.capture.terminalSequence = o.sequence;
     call.state =
-      o.completionOutcome === "canceled"
-        ? "aborted"
-        : o.completionOutcome === "failed"
-          ? "failed"
-          : o.completionOutcome === "rejected"
-            ? "rejected"
-            : state.terminal === "completed"
-              ? "succeeded"
-              : state.terminal === "failed" || state.terminal === "incomplete"
-                ? "failed"
-                : "unknown";
+      o.completionOutcome === undefined && o.captureIncomplete
+        ? "unknown"
+        : o.completionOutcome === "canceled"
+          ? "aborted"
+          : o.completionOutcome === "failed"
+            ? "failed"
+            : o.completionOutcome === "rejected"
+              ? "rejected"
+              : state.terminal === "completed"
+                ? "succeeded"
+                : state.terminal === "failed" || state.terminal === "incomplete"
+                  ? "failed"
+                  : "unknown";
   }
   call.protocolTerminal = state.terminal;
   const final =

package/src/protocols/index.ts

@@ -25,7 +25,7 @@ export function projectCapturedPayloads(args: {
   response?: Uint8Array;
   chunks?: readonly Uint8Array[];
   complete?: boolean;
-  /** Set only for capturePolicy hook-body-v1, never historical canonical SSE. */
+  /** Set only for expanded raw stock hooks, never historical canonical SSE. */
   stockHookChunks?: boolean;
 }): CliproxyProjection {
   const projection: CliproxyProjection = {
@@ -142,3 +142,6 @@ export function projectCapturedPayloads(args: {
   }
   return projection;
 }
+
+export { expandStockHookBlock } from "./stock-block.js";
+export { BodyPartAssembler, stockHookPieces } from "./body-parts.js";

package/src/protocols/stock-block.ts

@@ -0,0 +1,18 @@
+/** Recover stock parser boundaries without altering the captured bytes. */
+export function expandStockHookBlock(
+  body: Uint8Array,
+  lengths: readonly number[],
+): readonly Uint8Array[] {
+  if (!Array.isArray(lengths) || lengths.length === 0 || lengths.length > 1024)
+    throw new Error("invalid stock hook block lengths");
+  const pieces: Uint8Array[] = [];
+  let offset = 0;
+  for (const length of lengths) {
+    if (!Number.isSafeInteger(length) || length < 0 || length > body.byteLength - offset)
+      throw new Error("invalid stock hook block length");
+    pieces.push(body.subarray(offset, offset + length));
+    offset += length;
+  }
+  if (offset !== body.byteLength) throw new Error("stock hook block byte mismatch");
+  return pieces;
+}