@bitkyc08/opencodex 2.55.0-preview.20260914 → 2.56.0

package/src/responses/continuation-ownership.ts

@@ -0,0 +1,29 @@
+import { effectiveAdapterContract, getAdapterDefinition, type AdapterWire } from "../adapters/registry";
+
+/**
+ * Wires whose upstream holds the conversation itself, so a turn may reference history this
+ * process no longer has.
+ *
+ * The set is empty, and that is the finding rather than an oversight. The three wires that look
+ * like they belong here do not:
+ *
+ * - devin sends `mapOcxMessagesToDevin(parsed)` — the whole conversation — on every turn
+ *   (`src/adapters/devin.ts`). Its session/thread id buys prompt caching, not remembered context.
+ * - cursor continues from `_providerContinuation.cursor.checkpointRef`, which is read out of the
+ *   very store that just expired; without it `resolveCursorCheckpoint` returns a reason and the
+ *   request falls back to `continuationMode: "full-replay"` over `parsed.context.messages`
+ *   (`src/adapters/cursor/request-builder.ts`).
+ * - kiro builds `conversationState.history` from the parsed turns it was given
+ *   (`src/adapters/kiro/payload.ts`); a conversation id alone reconstructs nothing.
+ *
+ * So for every translated wire a replay miss means the delta travels alone. Only the native
+ * Responses passthrough, which forwards `previous_response_id` untouched to a backend that stored
+ * the chain, can answer a turn whose history this process lost.
+ */
+export const PROVIDER_OWNED_CONTINUATION_WIRES: ReadonlySet<AdapterWire> = new Set<AdapterWire>();
+
+/** The wire an adapter id resolves to through contract inheritance, or undefined if unknown. */
+export function resolvedAdapterWire(adapterId: unknown): AdapterWire | undefined {
+  if (typeof adapterId !== "string" || !getAdapterDefinition(adapterId)) return undefined;
+  return effectiveAdapterContract(adapterId).wire;
+}

package/src/responses/state/replay-fingerprint.ts

@@ -0,0 +1,80 @@
+/** Hard cap for canonicalizing ANY item. Past it, the item is not comparable. */
+const REPLAY_FINGERPRINT_MAX_BYTES = 8 * 1024;
+/** Depth ceiling so a pathologically nested item cannot blow the canonicalizer. */
+const REPLAY_FINGERPRINT_MAX_DEPTH = 64;
+
+/**
+ * Canonical, order-stable fingerprint for one input item, or null when the item cannot be
+ * compared safely.
+ *
+ * Byte-counted DURING the walk rather than serialize-then-measure: a tool result can be
+ * megabytes and this runs on the request path, so the point of the cap is to stop early,
+ * not to discover afterwards that we should have. Object keys are sorted so two
+ * semantically identical items cannot differ by key order alone.
+ *
+ * The cap applies to EVERY item. An `id`/`call_id` is additional occurrence evidence, never
+ * a substitute for content equality, so an over-cap identified tool item is non-comparable
+ * exactly like an over-cap message.
+ */
+function replayItemFingerprint(item: unknown): string | null {
+  const out: string[] = [];
+  let bytes = 0;
+  const push = (text: string): boolean => {
+    bytes += Buffer.byteLength(text, "utf8");
+    if (bytes > REPLAY_FINGERPRINT_MAX_BYTES) return false;
+    out.push(text);
+    return true;
+  };
+  const walk = (value: unknown, depth: number): boolean => {
+    if (depth > REPLAY_FINGERPRINT_MAX_DEPTH) return false;
+    if (value === null || typeof value !== "object") return push(JSON.stringify(value) ?? "null");
+    if (Array.isArray(value)) {
+      if (!push("[")) return false;
+      for (const element of value) {
+        if (!walk(element, depth + 1)) return false;
+        if (!push(",")) return false;
+      }
+      return push("]");
+    }
+    if (!push("{")) return false;
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      if (!push(JSON.stringify(key))) return false;
+      if (!walk((value as Record<string, unknown>)[key], depth + 1)) return false;
+      if (!push(",")) return false;
+    }
+    return push("}");
+  };
+  return walk(item, 0) ? out.join("") : null;
+}
+
+/** Non-empty provider-issued `id`/`call_id` on an item, else null. */
+export function providerIssuedIdentity(item: unknown): string | null {
+  if (!item || typeof item !== "object" || Array.isArray(item)) return null;
+  const record = item as { id?: unknown; call_id?: unknown };
+  for (const candidate of [record.id, record.call_id]) {
+    if (typeof candidate === "string" && candidate.trim().length > 0) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Number of leading stored items the client already carries verbatim, or 0.
+ *
+ * Requires an exact ordered run: every stored item must match the client input item at the
+ * same index. Any not-comparable item aborts to 0 — skipping just that item could align two
+ * different occurrences and manufacture a false positive, and a false positive here deletes
+ * real conversation history.
+ *
+ * Known gap (FU-2): stored input can contain proxy-injected guidance the client never saw,
+ * and ids repaired after recording. Those sessions do not match here and expand as before.
+ */
+export function clientCarriedPrefixLength(stored: readonly unknown[], clientInput: readonly unknown[]): number {
+  if (stored.length === 0 || clientInput.length < stored.length) return 0;
+  for (let index = 0; index < stored.length; index += 1) {
+    const storedPrint = replayItemFingerprint(stored[index]);
+    if (storedPrint === null) return 0;
+    const clientPrint = replayItemFingerprint(clientInput[index]);
+    if (clientPrint === null || storedPrint !== clientPrint) return 0;
+  }
+  return stored.length;
+}

package/src/responses/state/snapshot-codec.ts

@@ -0,0 +1,104 @@
+import type {
+  ResidentInput,
+  ResidentResponseState,
+  SpillFailedResponseState,
+  SpilledResponseState,
+  StoredResponseState,
+} from "../state";
+import type { ResponseSpillRef } from "../spill-store";
+import type { OcxProviderContinuationState } from "../../types";
+
+export interface SnapshotLoadStore {
+  replaceMapEntry(id: string, next: StoredResponseState, expected?: StoredResponseState): boolean;
+  stubSize(id: string, entry: Omit<SpilledResponseState, "sizeBytes">): number;
+  tombstone(id: string, createdAt: number): SpillFailedResponseState;
+  measureResidentEntry(id: string, entry: ResidentInput): ResidentResponseState | null;
+  admitOversizedCandidate(id: string, candidate: ResidentResponseState, expected?: StoredResponseState): void;
+  byteCap(): number;
+}
+
+interface LegacySnapshotState {
+  createdAt?: unknown;
+  clientThreadId?: unknown;
+  items?: unknown;
+  providers?: OcxProviderContinuationState;
+  conversationId?: unknown;
+  cursorCheckpointUsable?: unknown;
+}
+
+function isSpillRef(value: unknown): value is ResponseSpillRef {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const ref = value as ResponseSpillRef;
+  return ref.version === 1
+    && typeof ref.fileName === "string"
+    && /^[0-9a-f]{64}$/.test(ref.digest)
+    && Number.isSafeInteger(ref.payloadBytes)
+    && ref.payloadBytes >= 0;
+}
+
+export function loadSnapshotEntry(id: string, value: unknown, store: SnapshotLoadStore): void {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return;
+  const rec = value as LegacySnapshotState & { kind?: unknown; spill?: unknown };
+  if (typeof rec.createdAt !== "number" || !Number.isFinite(rec.createdAt)) return;
+  const clientThreadId = typeof rec.clientThreadId === "string" && rec.clientThreadId.trim().length > 0
+    ? rec.clientThreadId.trim()
+    : undefined;
+  // A malformed boundary degrades to "never skip" rather than to a bad index: an untrusted
+  // snapshot must not be able to authorize dropping conversation history.
+  const anchorFor = (itemCount: number): number | undefined => {
+    const raw = (rec as { providerOutputStart?: unknown }).providerOutputStart;
+    return Number.isSafeInteger(raw) && (raw as number) >= 0 && (raw as number) <= itemCount
+      ? raw as number
+      : undefined;
+  };
+  if (rec.kind === "spill") {
+    if (!isSpillRef(rec.spill)) return;
+    const base: Omit<SpilledResponseState, "sizeBytes"> = {
+      kind: "spill",
+      createdAt: rec.createdAt,
+      ...(clientThreadId ? { clientThreadId } : {}),
+      // Item count is unknown until materialization, so accept any non-negative integer
+      // here; the spill payload validator re-checks it against the real array.
+      ...(anchorFor(Number.MAX_SAFE_INTEGER) !== undefined ? { providerOutputStart: anchorFor(Number.MAX_SAFE_INTEGER) } : {}),
+      ...(rec.providers ? { providers: rec.providers } : {}),
+      spill: rec.spill,
+    };
+    store.replaceMapEntry(id, { ...base, sizeBytes: store.stubSize(id, base) });
+    return;
+  }
+  if (rec.kind === "spill-failed") {
+    store.replaceMapEntry(id, store.tombstone(id, rec.createdAt));
+    return;
+  }
+  if (rec.kind !== undefined && rec.kind !== "resident") return;
+  if (!Array.isArray(rec.items)) return;
+  const providers = rec.providers ?? (typeof rec.conversationId === "string"
+    ? {
+        cursor: {
+          conversationId: rec.conversationId,
+          ...(typeof rec.cursorCheckpointUsable === "boolean"
+            ? { checkpointUsable: rec.cursorCheckpointUsable }
+            : {}),
+        },
+      }
+    : undefined);
+  const resident = store.measureResidentEntry(id, {
+    createdAt: rec.createdAt,
+    ...(clientThreadId ? { clientThreadId } : {}),
+    items: rec.items,
+    ...(anchorFor(rec.items.length) !== undefined ? { providerOutputStart: anchorFor(rec.items.length) } : {}),
+    ...(providers ? { providers } : {}),
+  });
+  if (!resident) {
+    store.replaceMapEntry(id, store.tombstone(id, rec.createdAt));
+    return;
+  }
+  // Same admission boundary as live writes: an oversized snapshot row goes
+  // straight to spill (or tombstone above the payload ceiling) instead of
+  // entering the resident map and demoting unrelated rows on the first prune.
+  if (resident.sizeBytes > store.byteCap()) {
+    store.admitOversizedCandidate(id, resident, undefined);
+    return;
+  }
+  store.replaceMapEntry(id, resident);
+}

package/src/responses/state/spill-failure.ts

@@ -0,0 +1,118 @@
+export const spillCounters = {
+  writes: 0, writeFailures: 0, readFailures: 0,
+  aclRetryReturnedTimeouts: 0, aclTimeoutMemoRefusals: 0,
+};
+
+export type ResponseSpillWriteFailureCode =
+  | "EACLRETRYEXHAUSTED"
+  | "ETIMEDOUT"
+  | "EACCES"
+  | "ENOSPC"
+  | "EFBIG"
+  | "EIO"
+  | "ECAPACITY"
+  | "ELOOP"
+  | "EUNKNOWN";
+
+export type ResponseSpillWriteStatus = "initial" | "healthy" | "degraded";
+
+export type ResponseSpillWriteFailureOrigin =
+  | "retry_returned_timeout"
+  | "timeout_memo_refusal";
+
+interface ResponseSpillWriteHealth {
+  consecutiveFailures: number;
+  lastFailureCode: ResponseSpillWriteFailureCode | null;
+  lastFailureOrigin: ResponseSpillWriteFailureOrigin | null;
+  lastFailureAt: number | null;
+  lastSuccessAt: number | null;
+}
+
+export const spillWriteHealth: ResponseSpillWriteHealth = {
+  consecutiveFailures: 0,
+  lastFailureCode: null,
+  lastFailureOrigin: null,
+  lastFailureAt: null,
+  lastSuccessAt: null,
+};
+
+/**
+ * Collapse filesystem/runtime errors into a fixed privacy-safe diagnostic union.
+ * Messages and paths are deliberately ignored: this projection is returned by the
+ * authenticated memory endpoint, and a nested `cause` can contain a username or
+ * workspace path even when the public wrapper does not.
+ */
+function classifySpillWriteFailure(error: unknown): ResponseSpillWriteFailureCode {
+  let cursor = error;
+  for (let depth = 0; depth < 4 && cursor && typeof cursor === "object"; depth += 1) {
+    const record = cursor as { code?: unknown; cause?: unknown };
+    const code = typeof record.code === "string" ? record.code.toUpperCase() : "";
+    switch (code) {
+      case "EACLRETRYEXHAUSTED": return "EACLRETRYEXHAUSTED";
+      case "ETIMEDOUT": return "ETIMEDOUT";
+      case "EACCES":
+      case "EPERM": return "EACCES";
+      case "ENOSPC":
+      case "EDQUOT": return "ENOSPC";
+      case "EFBIG": return "EFBIG";
+      case "EIO": return "EIO";
+      case "ECAPACITY": return "ECAPACITY";
+      case "ELOOP": return "ELOOP";
+    }
+    cursor = record.cause;
+  }
+  return "EUNKNOWN";
+}
+
+/** The spill writer preserves ACL errors in cause; only a fixed memo marker is diagnostic. */
+export function spillAclMemoRefusalOrigin(error: unknown): "timeout_memo_refusal" | null {
+  let cursor = error;
+  for (let depth = 0; depth < 4 && cursor && typeof cursor === "object"; depth += 1) {
+    const record = cursor as { code?: unknown; aclFailureOrigin?: unknown; cause?: unknown };
+    if ((record.code === "ETIMEDOUT" || record.code === "EACLRETRYEXHAUSTED")
+      && record.aclFailureOrigin === "timeout_memo_refusal") {
+      return "timeout_memo_refusal";
+    }
+    cursor = record.cause;
+  }
+  return null;
+}
+
+export function noteSpillWriteSuccess(): void {
+  spillCounters.writes += 1;
+  spillWriteHealth.consecutiveFailures = 0;
+  spillWriteHealth.lastSuccessAt = Date.now();
+}
+
+export function noteSpillWriteFailure(
+  error: unknown,
+  override?: ResponseSpillWriteFailureCode,
+  retryOrigin: ResponseSpillWriteFailureOrigin | null = null,
+): void {
+  const code = override ?? classifySpillWriteFailure(error);
+  const origin = code === "ETIMEDOUT" || code === "EACLRETRYEXHAUSTED"
+    ? spillAclMemoRefusalOrigin(error) ?? retryOrigin
+    : null;
+  spillCounters.writeFailures += 1;
+  spillWriteHealth.consecutiveFailures += 1;
+  spillWriteHealth.lastFailureCode = code;
+  spillWriteHealth.lastFailureOrigin = origin;
+  spillWriteHealth.lastFailureAt = Date.now();
+  // Count terminal publications, not ACL calls or a transient first attempt.
+  if (origin === "retry_returned_timeout") spillCounters.aclRetryReturnedTimeouts += 1;
+  else if (origin === "timeout_memo_refusal") spillCounters.aclTimeoutMemoRefusals += 1;
+}
+/**
+ * Admission-boundary observability (test-visible). directSpills: oversized
+ * candidates routed straight to durable spill without a resident stay or
+ * unrelated demotion. oversizedDrops: candidates above the single-spill
+ * payload ceiling, tombstoned instead of retained. snapshotOversizedRefusals:
+ * snapshot files refused before parse.
+ */
+export const admissionCounters = { directSpills: 0, oversizedDrops: 0, snapshotOversizedRefusals: 0 };
+
+
+/** Test-only: admission-boundary counters (proves the new paths fire). */
+export function responseAdmissionCountersForTests(): Readonly<typeof admissionCounters> {
+  return admissionCounters;
+}