@shpitdev/convex-cliproxy-observability 0.1.0

package/src/model-call/index.ts

@@ -0,0 +1,224 @@
+/** Read contract only: storage and ingestion remain independently owned. */
+export type ModelCallSource = "cliproxy" | "openrouter" | "cliproxy_legacy";
+export type ModelCallState =
+  "in_progress" | "succeeded" | "failed" | "aborted" | "rejected" | "interrupted" | "unknown";
+export type EvidenceState = "complete" | "partial" | "unavailable" | "invalid" | "unsupported";
+export type ExactCorrelation = Partial<
+  Record<
+    | "requestId"
+    | "runId"
+    | "jobId"
+    | "traceId"
+    | "rootExecutionId"
+    | "opencodeSessionId"
+    | "operationId"
+    | "stepId"
+    | "partId"
+    | "attemptId",
+    string
+  >
+>;
+export type UsageMeasurement = {
+  value: number;
+  nativeField: string;
+  source: "client_protocol" | "openrouter_span";
+  scope: "call";
+  unit: "tokens";
+  finality: "final" | "partial" | "unknown";
+  semanticsVersion: string;
+};
+export type PrivateContentReference = {
+  key: string;
+  sha256: string;
+  byteLength: number;
+  contentType: string;
+};
+export type ModelCallV1 = {
+  schemaVersion: 1;
+  source: ModelCallSource;
+  callId: string;
+  sourceDocumentId: string;
+  gateway: "cliproxy" | "openrouter";
+  deploymentId?: string;
+  environment?: "dev" | "prod";
+  route?: string;
+  configRevision?: string;
+  authType: "unknown";
+  destinationId?: string;
+  instanceId?: string;
+  pluginBootId?: string;
+  executionId?: string;
+  sourceTraceId?: string;
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  requestModel?: string;
+  responseModel?: string;
+  providerName?: string;
+  streamed?: boolean;
+  operation: "generation" | "token_count" | "discovery" | "unknown";
+  tokenCount?: number;
+  clientProtocol?: "anthropic_messages" | "responses" | "chat_completions" | "unknown";
+  state: ModelCallState;
+  completionOutcome?: string;
+  executionStatusCode?: number;
+  protocolTerminal?: string;
+  finishReason?: string;
+  startTimeUnixNano?: string;
+  endTimeUnixNano?: string;
+  latencyMs?: number;
+  timeToFirstByteMs?: number;
+  timeToFirstContentMs?: number;
+  timingSource: "plugin_observed" | "openrouter_span" | "unavailable";
+  correlation: ExactCorrelation;
+  correlationConflicts: string[];
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  reasoningTokens?: number;
+  cachedInputTokens?: number;
+  usage: UsageMeasurement[];
+  cost:
+    | { kind: "unknown" }
+    | { kind: "provider_billed" | "proxy_reported"; currency: string; total: string };
+  attemptDetail: "unavailable";
+  capture: {
+    raw: EvidenceState;
+    projection: EvidenceState;
+    usage: EvidenceState;
+    preHook: "unavailable";
+    projectedThroughSequence: number;
+    persistedThroughSequence: number;
+    terminalSequence?: number;
+    gaps: string[];
+    parserVersion: string;
+    pluginVersion?: string;
+    redactionVersion?: string;
+    lastObservedAt?: string;
+  };
+  receivedAt: number;
+};
+export type ModelCallSummaryV1 = ModelCallV1;
+
+/** Structural input: there is no runtime dependency on the OpenRouter component. */
+export type OpenRouterSpanInput = {
+  _id: string;
+  receivedAt: number;
+  totalCost?: number;
+  openrouterUsageCost?: number;
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  requestModel?: string;
+  responseModel?: string;
+  providerName?: string;
+  streamed?: boolean;
+  startTimeUnixNano?: string;
+  endTimeUnixNano?: string;
+  finishReason?: string;
+  requestId?: string;
+  runId?: string;
+  jobId?: string;
+  rootExecutionId?: string;
+  opencodeSessionId?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  reasoningTokens?: number;
+  cachedInputTokens?: number;
+};
+export function fromOpenRouterSpan(span: OpenRouterSpanInput): ModelCallV1 {
+  const correlation: ExactCorrelation = {};
+  for (const field of [
+    "requestId",
+    "runId",
+    "jobId",
+    "rootExecutionId",
+    "opencodeSessionId",
+  ] as const) {
+    if (span[field] !== undefined) correlation[field] = span[field];
+  }
+  const usage: UsageMeasurement[] = [];
+  for (const field of [
+    "inputTokens",
+    "outputTokens",
+    "totalTokens",
+    "reasoningTokens",
+    "cachedInputTokens",
+  ] as const) {
+    const value = span[field];
+    if (value !== undefined && Number.isSafeInteger(value) && value >= 0)
+      usage.push({
+        value,
+        nativeField: field,
+        source: "openrouter_span",
+        scope: "call",
+        unit: "tokens",
+        finality: "unknown",
+        semanticsVersion: "stored_openrouter_span_v1",
+      });
+  }
+  return {
+    schemaVersion: 1,
+    source: "openrouter",
+    callId: `openrouter:${span._id}`,
+    sourceDocumentId: span._id,
+    gateway: "openrouter",
+    authType: "unknown",
+    traceId: span.traceId,
+    spanId: span.spanId,
+    parentSpanId: span.parentSpanId,
+    requestModel: span.requestModel,
+    responseModel: span.responseModel,
+    providerName: span.providerName,
+    streamed: span.streamed,
+    operation: "generation",
+    state: "unknown",
+    finishReason: span.finishReason,
+    startTimeUnixNano: span.startTimeUnixNano,
+    endTimeUnixNano: span.endTimeUnixNano,
+    timingSource: "openrouter_span",
+    correlation,
+    correlationConflicts: [],
+    inputTokens: span.inputTokens,
+    outputTokens: span.outputTokens,
+    totalTokens: span.totalTokens,
+    reasoningTokens: span.reasoningTokens,
+    cachedInputTokens: span.cachedInputTokens,
+    usage,
+    cost:
+      typeof (span.totalCost ?? span.openrouterUsageCost) === "number" &&
+      Number.isFinite(span.totalCost ?? span.openrouterUsageCost) &&
+      (span.totalCost ?? span.openrouterUsageCost)! >= 0
+        ? {
+            kind: "proxy_reported",
+            currency: "USD",
+            total: String(span.totalCost ?? span.openrouterUsageCost),
+          }
+        : { kind: "unknown" },
+    attemptDetail: "unavailable",
+    capture: {
+      raw: "unavailable",
+      projection: "partial",
+      usage: usage.length ? "partial" : "unavailable",
+      preHook: "unavailable",
+      projectedThroughSequence: 0,
+      persistedThroughSequence: 0,
+      gaps: ["stream_events_and_attempt_detail_unavailable"],
+      parserVersion: "openrouter-structural-v1",
+    },
+    receivedAt: span.receivedAt,
+  };
+}
+export function fromLegacyCliproxySpan(span: OpenRouterSpanInput): ModelCallV1 {
+  const call = fromOpenRouterSpan(span);
+  return {
+    ...call,
+    source: "cliproxy_legacy",
+    callId: `cliproxy_legacy:${span._id}`,
+    gateway: "cliproxy",
+    providerName: undefined,
+    timingSource: "unavailable",
+    cost: { kind: "unknown" },
+  };
+}

package/src/projection.ts

@@ -0,0 +1,99 @@
+import type { GenericActionCtx, GenericDataModel } from "convex/server";
+import type { CliproxyObservability } from "./client.js";
+import { resolveCallBlob, type PrivateCaptureStorage } from "./content/index.js";
+import { sha256, type CaptureObservationV1 } from "./capture/index.js";
+import { applyObservation, type ProjectionCheckpoint } from "./protocols/checkpoint.js";
+import type { ModelCallV1 } from "./model-call/index.js";
+/** Project at most two immutable segments. Host schedules the next page when `more` is true. */
+export async function projectPendingSegments(
+  ctx: Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "runMutation">,
+  options: {
+    client: CliproxyObservability;
+    storage: PrivateCaptureStorage;
+    destinationId: string;
+    callId: string;
+  },
+) {
+  const { client, destinationId, callId } = options;
+  const state = await ctx.runQuery(client.component.queries.getProcessingState, {
+    destinationId,
+    callId,
+  });
+  if (!state) return { progressed: false, more: false };
+  try {
+    const page = await ctx.runQuery(client.component.queries.pageEventSegments, {
+      destinationId,
+      callId,
+      afterSequence: state.projectedThroughSequence,
+      limit: 2,
+    });
+    const call = JSON.parse(state.summaryJson) as ModelCallV1;
+    call.capture.projectedThroughSequence = state.projectedThroughSequence;
+    const checkpoint = JSON.parse(state.checkpointJson) as ProjectionCheckpoint;
+    if (checkpoint.sseBlob) {
+      const stored = await resolveCallBlob(
+        options.storage,
+        [checkpoint.sseBlob],
+        checkpoint.sseBlob,
+      );
+      checkpoint.sse = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(stored));
+      delete checkpoint.sseBlob;
+    }
+    let through = state.projectedThroughSequence;
+    let waitingForGap = false;
+    for (const segment of page.segments) {
+      if (segment.sequence !== through + 1) {
+        waitingForGap = true;
+        break;
+      }
+      const content = await resolveCallBlob(
+        options.storage,
+        [segment.reference],
+        segment.reference,
+      );
+      for (const line of new TextDecoder("utf-8", { fatal: true })
+        .decode(content)
+        .split("\n")
+        .filter(Boolean))
+        applyObservation(call, checkpoint, JSON.parse(line) as CaptureObservationV1);
+      through = segment.throughSequence;
+    }
+    if (through === state.projectedThroughSequence)
+      return { progressed: false, more: false, waitingForGap };
+    // A frame can exceed Convex's checkpoint budget. Persist pending framing bytes
+    // privately; the bounded component checkpoint owns the exact reference.
+    if (checkpoint.sse && checkpoint.sse.pendingBase64.length > 16 * 1024) {
+      const bytes = new TextEncoder().encode(JSON.stringify(checkpoint.sse));
+      const digest = await sha256(bytes);
+      const ref = {
+        key: `observability/cliproxy/v2/${destinationId}/${state.instanceId}/${callId}/parser/${digest}.json`,
+        sha256: digest,
+        byteLength: bytes.length,
+        contentType: "application/json",
+      };
+      await options.storage.put(ref, bytes);
+      checkpoint.sseBlob = ref;
+      delete checkpoint.sse;
+    }
+    const committed = await ctx.runMutation(client.component.ingest.commitProjection, {
+      destinationId,
+      callId,
+      expectedRevision: state.revision,
+      throughSequence: through,
+      summaryJson: JSON.stringify(call),
+      checkpointJson: JSON.stringify(checkpoint),
+    });
+    return {
+      progressed: committed.committed,
+      more: !committed.committed || (!page.done && !waitingForGap),
+      waitingForGap,
+    };
+  } catch (error) {
+    await ctx.runMutation(client.component.ingest.recordProjectionFailure, {
+      destinationId,
+      callId,
+      expectedRevision: state.revision,
+    });
+    throw error;
+  }
+}

package/src/protocols/anthropic-messages.ts

@@ -0,0 +1,115 @@
+import type { RecordValue } from "./types.js";
+import { append, count, list, object } from "./values.js";
+export function anthropicMessages(messages: unknown): RecordValue[] {
+  const result: RecordValue[] = [];
+  for (const value of list(messages)) {
+    const message = object(value);
+    if (!Array.isArray(message.content)) {
+      result.push(message);
+      continue;
+    }
+    let content: unknown[] = [];
+    let tools: unknown[] = [];
+    const flush = () => {
+      if (content.length || tools.length)
+        result.push({
+          role: message.role,
+          content,
+          ...(tools.length ? { tool_calls: tools } : {}),
+        });
+      content = [];
+      tools = [];
+    };
+    for (const raw of message.content) {
+      const block = object(raw);
+      if (block.type === "tool_use") {
+        tools.push({
+          id: block.id,
+          type: "function",
+          function: {
+            name: block.name,
+            arguments:
+              typeof block.partial_json === "string"
+                ? block.partial_json
+                : JSON.stringify(block.input),
+          },
+        });
+      } else if (block.type === "tool_result") {
+        flush();
+        result.push({
+          role: "tool",
+          tool_call_id: block.tool_use_id,
+          content: block.content,
+          is_error: block.is_error,
+        });
+      } else if (block.type === "text") content.push({ type: "text", text: block.text });
+      else content.push(block);
+    }
+    flush();
+  }
+  return result;
+}
+
+export function assembleAnthropicStream(events: RecordValue[]) {
+  let response: RecordValue = {};
+  let invalid = false,
+    recognized = false,
+    unsupported = false,
+    terminal = false,
+    terminalUsage = false;
+  const blocks = new Map<number, RecordValue>();
+  const argumentsByIndex = new Map<number, string>();
+  for (const event of events) {
+    const index = count(event.index);
+    if (event.type === "message_start") {
+      response = { ...object(event.message) };
+      recognized = true;
+      terminalUsage = false;
+    } else if (event.type === "content_block_start" && index !== undefined)
+      blocks.set(index, { ...object(event.content_block) });
+    else if (event.type === "content_block_delta" && index !== undefined) {
+      const block = blocks.get(index);
+      const delta = object(event.delta);
+      if (!block) {
+        invalid = true;
+        continue;
+      }
+      if (
+        !["text_delta", "thinking_delta", "signature_delta", "input_json_delta"].includes(
+          String(delta.type),
+        )
+      )
+        unsupported = true;
+      for (const key of ["text", "thinking", "signature"]) append(block, key, delta[key]);
+      if (typeof delta.partial_json === "string")
+        argumentsByIndex.set(index, (argumentsByIndex.get(index) ?? "") + delta.partial_json);
+    } else if (event.type === "message_delta") {
+      Object.assign(response, object(event.delta));
+      // Message start and final delta are snapshots of different fields, not increments.
+      response.usage = { ...object(response.usage), ...object(event.usage) };
+      terminalUsage =
+        typeof object(event.delta).stop_reason === "string" &&
+        count(object(event.usage).output_tokens) !== undefined;
+    } else if (event.type === "message_stop") terminal = true;
+    else if (event.type === "error") {
+      response.error = event.error;
+      recognized = true;
+      terminal = true;
+      terminalUsage = false;
+    }
+  }
+  for (const [index, argumentsText] of argumentsByIndex) {
+    const block = blocks.get(index);
+    if (block) {
+      try {
+        block.input = JSON.parse(argumentsText);
+      } catch {
+        block.partial_json = argumentsText;
+        invalid ||= terminal;
+      }
+    }
+  }
+  response.content = [...blocks.entries()].toSorted(([a], [b]) => a - b).map(([, value]) => value);
+
+  return { response, invalid, recognized, unsupported, terminal, terminalUsage };
+}

package/src/protocols/chat-completions.ts

@@ -0,0 +1,94 @@
+import type { RecordValue } from "./types.js";
+import { append, count, list, object } from "./values.js";
+export function assembleChatStream(events: RecordValue[], done: boolean, stockCompleted = false) {
+  const response: RecordValue = {};
+  let invalid = false,
+    recognized = false,
+    unsupported = false,
+    terminal = false,
+    terminalUsage = false;
+  const choices = new Map<number, RecordValue>();
+  const tools = new Map<number, Map<number, RecordValue>>();
+  for (const event of events) {
+    if (Array.isArray(event.choices) || event.error) recognized = true;
+    for (const key of ["id", "model", "object"])
+      if (event[key] !== undefined) response[key] = event[key];
+    if (event.usage !== undefined && event.usage !== null) response.usage = event.usage;
+    // Final usage is emitted on an empty choices chunk or with finished choices.
+    // A later [DONE] marker cannot turn an earlier running count into final usage.
+    if (Array.isArray(event.choices))
+      terminalUsage =
+        event.usage !== undefined &&
+        event.usage !== null &&
+        event.choices.every((choice) => typeof object(choice).finish_reason === "string");
+    if (event.error) {
+      response.error = event.error;
+      terminalUsage = false;
+    }
+    for (const raw of list(event.choices)) {
+      const choice = object(raw);
+      const index = count(choice.index);
+      if (index === undefined) {
+        invalid = true;
+        continue;
+      }
+      const saved = choices.get(index) ?? { index, message: { role: "assistant" } };
+      const message = object(saved.message);
+      const delta = object(choice.delta);
+      if (
+        Object.keys(delta).some(
+          (key) =>
+            ![
+              "role",
+              "content",
+              "reasoning_content",
+              "reasoning",
+              "refusal",
+              "tool_calls",
+              "reasoning_details",
+            ].includes(key),
+        )
+      )
+        unsupported = true;
+      for (const key of ["content", "reasoning_content", "reasoning", "refusal"])
+        append(message, key, delta[key]);
+      if (delta.reasoning_details !== undefined)
+        message.reasoning_details = [
+          ...list(message.reasoning_details),
+          ...list(delta.reasoning_details),
+        ];
+      const byIndex = tools.get(index) ?? new Map<number, RecordValue>();
+      for (const rawTool of list(delta.tool_calls)) {
+        const tool = object(rawTool);
+        const toolIndex = count(tool.index);
+        if (toolIndex === undefined) {
+          invalid = true;
+          continue;
+        }
+        const savedTool = byIndex.get(toolIndex) ?? { type: "function", function: {} };
+        if (tool.id !== undefined) savedTool.id = tool.id;
+        if (tool.type !== undefined) savedTool.type = tool.type;
+        for (const key of ["name", "arguments"])
+          append(object(savedTool.function), key, object(tool.function)[key]);
+        byIndex.set(toolIndex, savedTool);
+      }
+      tools.set(index, byIndex);
+      if (byIndex.size)
+        message.tool_calls = [...byIndex.entries()]
+          .toSorted(([a], [b]) => a - b)
+          .map(([, value]) => value);
+      if (choice.finish_reason !== undefined && choice.finish_reason !== null)
+        saved.finish_reason = choice.finish_reason;
+      choices.set(index, saved);
+    }
+  }
+  response.choices = [...choices.entries()].toSorted(([a], [b]) => a - b).map(([, value]) => value);
+  terminal =
+    done ||
+    response.error !== undefined ||
+    (stockCompleted &&
+      choices.size > 0 &&
+      [...choices.values()].every((choice) => typeof choice.finish_reason === "string"));
+
+  return { response, invalid, recognized, unsupported, terminal, terminalUsage };
+}