@shpitdev/convex-cliproxy-observability 0.1.0

package/dist/test.d.ts

@@ -0,0 +1,155 @@
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import type { TestConvex } from "convex-test";
+export declare function register(testConvex: TestConvex<SchemaDefinition<GenericSchema, boolean>>, name?: string): void;
+declare const _default: {
+    modules: Record<string, () => Promise<unknown>>;
+    register: typeof register;
+    schema: SchemaDefinition<{
+        calls: import("convex/server").TableDefinition<import("convex/values").VObject<{
+            terminalSequence?: number | undefined;
+            projectionFailure?: {
+                reason: string;
+                at: number;
+            } | undefined;
+            requestId?: string | undefined;
+            runId?: string | undefined;
+            jobId?: string | undefined;
+            rootExecutionId?: string | undefined;
+            opencodeSessionId?: string | undefined;
+            destinationId: string;
+            callId: string;
+            instanceId: string;
+            pluginBootId: string;
+            executionId: string;
+            receivedAt: number;
+            revision: number;
+            projectedThroughSequence: number;
+            persistedThroughSequence: number;
+            summaryJson: string;
+            checkpointJson: string;
+        }, {
+            destinationId: import("convex/values").VString<string, "required">;
+            callId: import("convex/values").VString<string, "required">;
+            instanceId: import("convex/values").VString<string, "required">;
+            pluginBootId: import("convex/values").VString<string, "required">;
+            executionId: import("convex/values").VString<string, "required">;
+            receivedAt: import("convex/values").VFloat64<number, "required">;
+            revision: import("convex/values").VFloat64<number, "required">;
+            projectedThroughSequence: import("convex/values").VFloat64<number, "required">;
+            persistedThroughSequence: import("convex/values").VFloat64<number, "required">;
+            terminalSequence: import("convex/values").VFloat64<number | undefined, "optional">;
+            summaryJson: import("convex/values").VString<string, "required">;
+            checkpointJson: import("convex/values").VString<string, "required">;
+            projectionFailure: import("convex/values").VObject<{
+                reason: string;
+                at: number;
+            } | undefined, {
+                reason: import("convex/values").VString<string, "required">;
+                at: import("convex/values").VFloat64<number, "required">;
+            }, "optional", "reason" | "at">;
+            requestId: import("convex/values").VString<string | undefined, "optional">;
+            runId: import("convex/values").VString<string | undefined, "optional">;
+            jobId: import("convex/values").VString<string | undefined, "optional">;
+            rootExecutionId: import("convex/values").VString<string | undefined, "optional">;
+            opencodeSessionId: import("convex/values").VString<string | undefined, "optional">;
+        }, "required", "destinationId" | "callId" | "instanceId" | "pluginBootId" | "executionId" | "receivedAt" | "revision" | "projectedThroughSequence" | "persistedThroughSequence" | "terminalSequence" | "summaryJson" | "checkpointJson" | "projectionFailure" | "requestId" | "runId" | "jobId" | "rootExecutionId" | "opencodeSessionId" | "projectionFailure.reason" | "projectionFailure.at">, {
+            by_call: ["destinationId", "callId", "_creationTime"];
+            by_received: ["destinationId", "receivedAt", "_creationTime"];
+            by_request: ["destinationId", "requestId", "receivedAt", "_creationTime"];
+            by_run: ["destinationId", "runId", "receivedAt", "_creationTime"];
+            by_job: ["destinationId", "jobId", "receivedAt", "_creationTime"];
+            by_root_execution: ["destinationId", "rootExecutionId", "receivedAt", "_creationTime"];
+            by_opencode_session: ["destinationId", "opencodeSessionId", "receivedAt", "_creationTime"];
+        }, {}, {}>;
+        segments: import("convex/server").TableDefinition<import("convex/values").VObject<{
+            destinationId: string;
+            callId: string;
+            receivedAt: number;
+            reference: {
+                key: string;
+                sha256: string;
+                byteLength: number;
+                contentType: string;
+            };
+            sequence: number;
+            throughSequence: number;
+            identity: string;
+            digest: string;
+        }, {
+            destinationId: import("convex/values").VString<string, "required">;
+            callId: import("convex/values").VString<string, "required">;
+            sequence: import("convex/values").VFloat64<number, "required">;
+            throughSequence: import("convex/values").VFloat64<number, "required">;
+            identity: import("convex/values").VString<string, "required">;
+            digest: import("convex/values").VString<string, "required">;
+            reference: import("convex/values").VObject<{
+                key: string;
+                sha256: string;
+                byteLength: number;
+                contentType: string;
+            }, {
+                key: import("convex/values").VString<string, "required">;
+                sha256: import("convex/values").VString<string, "required">;
+                byteLength: import("convex/values").VFloat64<number, "required">;
+                contentType: import("convex/values").VString<string, "required">;
+            }, "required", "key" | "sha256" | "byteLength" | "contentType">;
+            receivedAt: import("convex/values").VFloat64<number, "required">;
+        }, "required", "destinationId" | "callId" | "receivedAt" | "reference" | "sequence" | "throughSequence" | "identity" | "digest" | "reference.key" | "reference.sha256" | "reference.byteLength" | "reference.contentType">, {
+            by_identity: ["destinationId", "identity", "_creationTime"];
+            by_sequence: ["destinationId", "callId", "sequence", "_creationTime"];
+        }, {}, {}>;
+        receipts: import("convex/server").TableDefinition<import("convex/values").VObject<{
+            destinationId: string;
+            callId: string;
+            receivedAt: number;
+            sequence: number;
+            identity: string;
+            digest: string;
+        }, {
+            destinationId: import("convex/values").VString<string, "required">;
+            identity: import("convex/values").VString<string, "required">;
+            digest: import("convex/values").VString<string, "required">;
+            callId: import("convex/values").VString<string, "required">;
+            sequence: import("convex/values").VFloat64<number, "required">;
+            receivedAt: import("convex/values").VFloat64<number, "required">;
+        }, "required", "destinationId" | "callId" | "receivedAt" | "sequence" | "identity" | "digest">, {
+            by_identity: ["destinationId", "identity", "_creationTime"];
+        }, {}, {}>;
+        bootHealth: import("convex/server").TableDefinition<import("convex/values").VObject<{
+            destinationId: string;
+            instanceId: string;
+            pluginBootId: string;
+            observedAt: number;
+            healthJson: string;
+        }, {
+            destinationId: import("convex/values").VString<string, "required">;
+            instanceId: import("convex/values").VString<string, "required">;
+            pluginBootId: import("convex/values").VString<string, "required">;
+            observedAt: import("convex/values").VFloat64<number, "required">;
+            healthJson: import("convex/values").VString<string, "required">;
+        }, "required", "destinationId" | "instanceId" | "pluginBootId" | "observedAt" | "healthJson">, {
+            by_boot: ["destinationId", "instanceId", "pluginBootId", "_creationTime"];
+        }, {}, {}>;
+        sourceStatus: import("convex/server").TableDefinition<import("convex/values").VObject<{
+            healthJson?: string | undefined;
+            destinationId: string;
+            instanceId: string;
+            pluginBootId: string;
+            lastObservedAt: string;
+            lastReceivedAt: number;
+            coverage: string;
+        }, {
+            destinationId: import("convex/values").VString<string, "required">;
+            instanceId: import("convex/values").VString<string, "required">;
+            pluginBootId: import("convex/values").VString<string, "required">;
+            lastObservedAt: import("convex/values").VString<string, "required">;
+            lastReceivedAt: import("convex/values").VFloat64<number, "required">;
+            coverage: import("convex/values").VString<string, "required">;
+            healthJson: import("convex/values").VString<string | undefined, "optional">;
+        }, "required", "destinationId" | "instanceId" | "pluginBootId" | "healthJson" | "lastObservedAt" | "lastReceivedAt" | "coverage">, {
+            by_source: ["destinationId", "instanceId", "_creationTime"];
+        }, {}, {}>;
+    }, true>;
+};
+export default _default;
+//# sourceMappingURL=test.d.ts.map

package/dist/test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.d.ts","sourceRoot":"","sources":["../src/test.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAK9C,wBAAgB,QAAQ,CACtB,UAAU,EAAE,UAAU,CAAC,gBAAgB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,EAChE,IAAI,SAA0B,QAG/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAED,wBAA6C"}

package/dist/test.js

@@ -0,0 +1,8 @@
+/// <reference types="vite/client" />
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+export function register(testConvex, name = "cliproxyObservability") {
+    testConvex.registerComponent(name, schema, modules);
+}
+export default { modules, register, schema };
+//# sourceMappingURL=test.js.map

package/dist/test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.js","sourceRoot":"","sources":["../src/test.ts"],"names":[],"mappings":"AAAA,qCAAqC;AAIrC,OAAO,MAAM,MAAM,uBAAuB,CAAC;AAE3C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;AAExD,MAAM,UAAU,QAAQ,CACtB,UAAgE,EAChE,IAAI,GAAG,uBAAuB;IAE9B,UAAU,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AACtD,CAAC;AAED,eAAe,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC"}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@shpitdev/convex-cliproxy-observability",
+  "description": "Private stock CLIProxy capture, protocol projections, and bounded model-call reads.",
+  "version": "0.1.0",
+  "author": "Anand Pant",
+  "license": "Apache-2.0",
+  "repository": "github:anandpant/convex-components",
+  "homepage": "https://github.com/anandpant/convex-components#readme",
+  "bugs": {
+    "url": "https://github.com/anandpant/convex-components/issues"
+  },
+  "keywords": [
+    "convex",
+    "component",
+    "cliproxy",
+    "observability"
+  ],
+  "type": "module",
+  "files": [
+    "CHANGELOG.md",
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./test": "./src/test.ts",
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./_generated/component": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./convex.config": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./model-call": {
+      "types": "./dist/model-call/index.d.ts",
+      "default": "./dist/model-call/index.js"
+    },
+    "./protocols": {
+      "types": "./dist/protocols/index.d.ts",
+      "default": "./dist/protocols/index.js"
+    },
+    "./capture": {
+      "types": "./dist/capture/index.d.ts",
+      "default": "./dist/capture/index.js"
+    }
+  },
+  "types": "./dist/client.d.ts",
+  "module": "./dist/client.js",
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc6 --project tsconfig.build.json",
+    "build:clean": "rm -rf dist *.tsbuildinfo && pnpm build",
+    "codegen": "convex codegen --component-dir ./src/component",
+    "pack:check": "pnpm build:clean && pnpm pack --pack-destination .pack && node scripts/check-pack.mjs",
+    "prepare": "pnpm build",
+    "test": "vitest run --typecheck",
+    "typecheck": "tsc6 --noEmit && tsc6 --noEmit --project tsconfig.test.json"
+  },
+  "peerDependencies": {
+    "convex": "^1.42.2"
+  },
+  "devDependencies": {
+    "@edge-runtime/vm": "^5.0.0",
+    "convex": "^1.45.0",
+    "convex-test": "^0.0.56",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  }
+}

package/src/capture/index.ts

@@ -0,0 +1,277 @@
+import type { ExactCorrelation } from "../model-call/index.js";
+export const MAX_ENVELOPE_BYTES = 2 * 1024 * 1024;
+export const MAX_CONTENT_BYTES = 1024 * 1024;
+const id = /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,199}$/;
+const routes = new Set([
+  "GET /v1/models",
+  "POST /v1/messages",
+  "POST /v1/messages/count_tokens",
+  "POST /v1/responses",
+  "POST /v1/chat/completions",
+]);
+export type CaptureObservationV1 = {
+  schemaVersion: 1;
+  pluginVersion: string;
+  redactionVersion: string;
+  destinationId: string;
+  instanceId: string;
+  pluginBootId: string;
+  requestId: string;
+  sequence: number;
+  kind: "request" | "response" | "stream_init" | "stream_chunk" | "completion" | "capture_health";
+  observedAt: string;
+  offsetNs: number;
+  route: string;
+  configRevision: string;
+  sourceFormat?: string;
+  requestedModel?: string;
+  sourceTraceId?: string;
+  correlation?: ExactCorrelation;
+  correlationConflicts?: string[];
+  stockChunkIndex?: number;
+  body?: string;
+  observedBodyBytes?: number;
+  bodyFraming?: "stock_json_chunk" | "stock_sse_candidate";
+  contentSha256: string;
+  contentBytes: number;
+  completionOutcome?: string;
+  executionStatusCode?: number;
+  executionStartedAt?: string;
+  executionCompletedAt?: string;
+  error?: string;
+  gap?: string;
+  bodyFromSequence?: number;
+  droppedObservationsTotal?: number;
+  scopeConflictsTotal?: number;
+};
+export async function sha256(bytes: Uint8Array): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", Uint8Array.from(bytes));
+  return Array.from(new Uint8Array(digest), (v) => v.toString(16).padStart(2, "0")).join("");
+}
+export async function observationIdentity(o: CaptureObservationV1) {
+  return sha256(
+    new TextEncoder().encode(
+      JSON.stringify([
+        o.destinationId,
+        o.instanceId,
+        o.pluginBootId,
+        o.requestId,
+        o.sequence,
+        o.kind,
+      ]),
+    ),
+  );
+}
+export async function callIdentity(
+  o: Pick<CaptureObservationV1, "destinationId" | "instanceId" | "pluginBootId" | "requestId">,
+) {
+  return sha256(
+    new TextEncoder().encode(
+      JSON.stringify([o.destinationId, o.instanceId, o.pluginBootId, o.requestId]),
+    ),
+  );
+}
+export function decodeBody(o: CaptureObservationV1): Uint8Array {
+  const raw = o.body ?? "";
+  if (
+    raw.length > Math.ceil(MAX_CONTENT_BYTES / 3) * 4 ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(raw)
+  )
+    throw new Error("invalid body encoding");
+  const decoded = atob(raw);
+  if (decoded.length > MAX_CONTENT_BYTES || decoded.length !== o.contentBytes)
+    throw new Error("body size mismatch");
+  return Uint8Array.from(decoded, (c) => c.charCodeAt(0));
+}
+export async function validateObservation(
+  raw: Uint8Array,
+  expected: { destinationId: string; instanceIds: readonly string[] },
+) {
+  if (raw.byteLength > MAX_ENVELOPE_BYTES) throw new Error("envelope limit");
+  const value: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(raw));
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("observation required");
+  const o = value as CaptureObservationV1;
+  if (
+    o.schemaVersion !== 1 ||
+    o.destinationId !== expected.destinationId ||
+    !expected.instanceIds.includes(o.instanceId)
+  )
+    throw new Error("scope mismatch");
+  for (const field of [
+    "destinationId",
+    "instanceId",
+    "pluginBootId",
+    "requestId",
+    "configRevision",
+  ] as const) {
+    if (typeof o[field] !== "string" || !id.test(o[field])) throw new Error("invalid identity");
+  }
+  if (
+    !Number.isSafeInteger(o.sequence) ||
+    o.sequence < 1 ||
+    !Number.isSafeInteger(o.offsetNs) ||
+    o.offsetNs < 0 ||
+    !Number.isSafeInteger(o.contentBytes) ||
+    o.contentBytes < 0 ||
+    !routes.has(o.route) ||
+    !Number.isFinite(Date.parse(o.observedAt))
+  )
+    throw new Error("invalid observation metadata");
+  if (
+    !["request", "response", "stream_init", "stream_chunk", "completion"].includes(o.kind) ||
+    !/^[a-f0-9]{64}$/.test(o.contentSha256)
+  )
+    throw new Error("unsupported observation");
+  for (const [key, val] of Object.entries(o.correlation ?? {})) {
+    if (
+      ![
+        "requestId",
+        "runId",
+        "jobId",
+        "traceId",
+        "rootExecutionId",
+        "opencodeSessionId",
+        "operationId",
+        "stepId",
+        "partId",
+        "attemptId",
+      ].includes(key) ||
+      typeof val !== "string" ||
+      val.length > 256
+    )
+      throw new Error("invalid correlation");
+  }
+  if (
+    o.correlationConflicts &&
+    (!Array.isArray(o.correlationConflicts) ||
+      o.correlationConflicts.length > 10 ||
+      o.correlationConflicts.some((x) => typeof x !== "string" || x.length > 64))
+  )
+    throw new Error("invalid correlation conflicts");
+  for (const field of [
+    "pluginVersion",
+    "redactionVersion",
+    "sourceFormat",
+    "requestedModel",
+    "sourceTraceId",
+    "gap",
+    "completionOutcome",
+  ] as const) {
+    if (o[field] !== undefined && (typeof o[field] !== "string" || o[field]!.length > 256))
+      throw new Error("invalid optional metadata");
+  }
+  if (!o.pluginVersion || !o.redactionVersion) throw new Error("capture versions required");
+  if (
+    o.kind === "completion" &&
+    !["succeeded", "failed", "canceled", "rejected"].includes(o.completionOutcome ?? "")
+  )
+    throw new Error("invalid completion outcome");
+  if (
+    o.bodyFraming !== undefined &&
+    !["stock_json_chunk", "stock_sse_candidate"].includes(o.bodyFraming)
+  )
+    throw new Error("invalid body framing");
+  if (
+    o.observedBodyBytes !== undefined &&
+    (!Number.isSafeInteger(o.observedBodyBytes) ||
+      o.observedBodyBytes < 0 ||
+      o.observedBodyBytes > MAX_ENVELOPE_BYTES)
+  )
+    throw new Error("invalid observed byte count");
+  const body = decodeBody(o);
+  if ((await sha256(body)) !== o.contentSha256) throw new Error("content digest mismatch");
+  return {
+    observation: o,
+    body,
+    identity: await observationIdentity(o),
+    callId: await callIdentity(o),
+    digest: await sha256(raw),
+  };
+}
+
+/** One immutable NDJSON segment batches observations: no per-token Convex writes. */
+export type CaptureSegmentV1 = {
+  schemaVersion: 1;
+  operation: "segment";
+  destinationId: string;
+  instanceId: string;
+  pluginBootId: string;
+  requestId: string;
+  firstSequence: number;
+  throughSequence: number;
+  contentSha256: string;
+  contentBytes: number;
+  contentBase64: string;
+};
+export const MAX_SEGMENT_BYTES = 1408 * 1024;
+export async function validateSegment(
+  raw: Uint8Array,
+  expected: { destinationId: string; instanceIds: readonly string[] },
+) {
+  if (raw.length > MAX_ENVELOPE_BYTES) throw new Error("envelope limit");
+  const envelope = JSON.parse(
+    new TextDecoder("utf-8", { fatal: true }).decode(raw),
+  ) as CaptureSegmentV1;
+  if (
+    envelope.schemaVersion !== 1 ||
+    envelope.operation !== "segment" ||
+    envelope.destinationId !== expected.destinationId ||
+    !expected.instanceIds.includes(envelope.instanceId) ||
+    !Number.isSafeInteger(envelope.firstSequence) ||
+    !Number.isSafeInteger(envelope.throughSequence) ||
+    envelope.firstSequence < 1 ||
+    envelope.throughSequence < envelope.firstSequence ||
+    envelope.throughSequence - envelope.firstSequence >= 256 ||
+    typeof envelope.contentBase64 !== "string" ||
+    envelope.contentBase64.length > Math.ceil(MAX_SEGMENT_BYTES / 3) * 4
+  )
+    throw new Error("invalid segment");
+  const content = Uint8Array.from(atob(envelope.contentBase64), (c) => c.charCodeAt(0));
+  if (
+    content.byteLength !== envelope.contentBytes ||
+    content.byteLength > MAX_SEGMENT_BYTES ||
+    (await sha256(content)) !== envelope.contentSha256
+  )
+    throw new Error("segment integrity failure");
+  const lines = new TextDecoder("utf-8", { fatal: true }).decode(content).split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  if (lines.length !== envelope.throughSequence - envelope.firstSequence + 1)
+    throw new Error("segment sequence count mismatch");
+  const observations: CaptureObservationV1[] = [];
+  for (const [index, line] of lines.entries()) {
+    const { observation } = await validateObservation(new TextEncoder().encode(line), expected);
+    if (
+      observation.instanceId !== envelope.instanceId ||
+      observation.pluginBootId !== envelope.pluginBootId ||
+      observation.requestId !== envelope.requestId ||
+      observation.sequence !== envelope.firstSequence + index
+    )
+      throw new Error("segment identity mismatch");
+    observations.push(observation);
+  }
+  const first = observations[0]!;
+  if (
+    observations.some(
+      (o, index) =>
+        o.route !== first.route ||
+        o.configRevision !== first.configRevision ||
+        (o.kind === "completion" && index !== observations.length - 1),
+    )
+  )
+    throw new Error("inconsistent segment lifecycle");
+  const callId = await callIdentity(first);
+  const identity = await sha256(
+    new TextEncoder().encode(
+      JSON.stringify([
+        envelope.destinationId,
+        envelope.instanceId,
+        envelope.pluginBootId,
+        envelope.requestId,
+        envelope.firstSequence,
+        envelope.throughSequence,
+      ]),
+    ),
+  );
+  return { envelope, observations, content, callId, identity, digest: envelope.contentSha256 };
+}