@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/src/define-schema.ts

@@ -0,0 +1,10 @@
+/**
+ * Construct a schema eagerly, but give bundlers one removable boundary around
+ * the whole initializer (including nested schemas and chained builders).
+ * Annotate calls with @__PURE__ only when the factory has no effects beyond
+ * constructing its returned schema. This is not lazy validation: used schemas
+ * are created once, in the same module evaluation order as ordinary constants.
+ */
+export function defineSchema<Schema>(factory: () => Schema): Schema {
+  return factory();
+}

package/src/desktop-app.ts

@@ -0,0 +1,50 @@
+/**
+ * The web console running inside an Opengeni desktop app.
+ *
+ * A sign-in the console starts there finishes in the person's own browser
+ * (providers refuse embedded app windows). The console marks its API requests
+ * with this header so a flow that ends in that browser can hand the person
+ * back to the app instead of leaving them on a web page. It only changes where
+ * the person's own browser goes afterwards; it never grants or narrows access.
+ */
+export const OPENGENI_DESKTOP_APP_HEADER = "x-opengeni-desktop-app";
+
+/** The console page that hands a finished browser flow back to the desktop app. */
+export const DESKTOP_APP_RETURN_PATH = "/desktop-return";
+
+/**
+ * Where a flow started in the desktop app should send the browser when it
+ * finishes: the console's hand-back page carrying the original destination.
+ * Only a destination on the requesting console's own origin is wrapped;
+ * anything else (an embedding product's page, a malformed origin) is returned
+ * unchanged, as is a destination that is already the hand-back page.
+ */
+export function desktopAppReturnUrl(returnUrl: string, consoleOrigin: string | null): string {
+  if (!consoleOrigin) return returnUrl;
+  let target: URL;
+  let origin: string;
+  try {
+    target = new URL(returnUrl);
+    origin = new URL(consoleOrigin).origin;
+  } catch {
+    return returnUrl;
+  }
+  if (target.origin !== origin || target.pathname === DESKTOP_APP_RETURN_PATH) return returnUrl;
+  const handBack = new URL(DESKTOP_APP_RETURN_PATH, origin);
+  handBack.searchParams.set("url", returnUrl);
+  return handBack.toString();
+}
+
+/**
+ * The same hand-back for flows that name their destination as a console path
+ * (`/workspaces/…`) and add their outcome parameters to it when they finish;
+ * the hand-back page carries those parameters on to the destination. A path
+ * that is not console-relative, or is already the hand-back page, is returned
+ * unchanged.
+ */
+export function desktopAppReturnPath(returnPath: string): string {
+  if (!returnPath.startsWith("/") || returnPath.startsWith("//")) return returnPath;
+  const base = "https://console.invalid";
+  if (new URL(returnPath, base).pathname === DESKTOP_APP_RETURN_PATH) return returnPath;
+  return `${DESKTOP_APP_RETURN_PATH}?${new URLSearchParams({ url: returnPath }).toString()}`;
+}

package/src/direct-model-provider.ts

@@ -0,0 +1,112 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+export const DirectModelProvider = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["openai", "azure_openai"]),
+);
+export type DirectModelProvider = z.infer<typeof DirectModelProvider>;
+
+/** Pin customer credentials to official provider origins, never arbitrary URLs. */
+export const AzureOpenAIEndpoint = /* @__PURE__ */ defineSchema(() =>
+  primitives.string
+    .trim()
+    .url()
+    .superRefine((value, ctx) => {
+      let url: URL;
+      try {
+        url = new URL(value);
+      } catch {
+        // The preceding URL validator supplies the normal validation issue.
+        return;
+      }
+      if (
+        url.protocol !== "https:" ||
+        url.username ||
+        url.password ||
+        url.port ||
+        !/^[a-z0-9-]+\.openai\.azure\.com$/i.test(url.hostname) ||
+        !["", "/", "/openai/v1", "/openai/v1/"].includes(url.pathname) ||
+        url.search ||
+        url.hash
+      ) {
+        ctx.addIssue({
+          code: "custom",
+          message: "Enter your Azure OpenAI HTTPS resource endpoint",
+        });
+      }
+    })
+    .transform((value) => new URL(value).origin + "/openai/v1"),
+);
+
+/** An exact OpenAI model or Azure OpenAI deployment name. */
+export const DirectModelName = /* @__PURE__ */ defineSchema(() =>
+  primitives.string
+    .trim()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
+);
+
+export const DirectModelProviderMetadata = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      provider: DirectModelProvider,
+      model: DirectModelName,
+      endpoint: AzureOpenAIEndpoint.optional(),
+    })
+    .strict()
+    .superRefine((value, ctx) => {
+      if (value.provider === "azure_openai" && !value.endpoint) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["endpoint"],
+          message: "Azure OpenAI needs an endpoint",
+        });
+      }
+      if (value.provider === "openai" && value.endpoint) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["endpoint"],
+          message: "OpenAI uses its official API endpoint",
+        });
+      }
+    }),
+);
+export type DirectModelProviderMetadata = z.infer<typeof DirectModelProviderMetadata>;
+
+export function directModelConnectionSpec(connection: {
+  id: string;
+  version: number;
+  subjectId: string | null;
+  kind: string;
+  status: string;
+  providerDomain: string;
+  metadata: Record<string, unknown>;
+}) {
+  if (
+    connection.subjectId !== null ||
+    connection.kind !== "api_key" ||
+    connection.status !== "active"
+  )
+    return null;
+  const parsed = DirectModelProviderMetadata.safeParse(connection.metadata.directModelProvider);
+  if (!parsed.success || connection.metadata.credentialRole !== `direct_${parsed.data.provider}`)
+    return null;
+  const config = parsed.data;
+  const baseUrl = config.provider === "openai" ? "https://api.openai.com/v1" : config.endpoint!;
+  if (connection.providerDomain.toLowerCase() !== new URL(baseUrl).hostname) return null;
+  const providerId = `workspace-${config.provider === "openai" ? "openai" : "azure-openai"}-${connection.id}`;
+  return {
+    ...config,
+    baseUrl,
+    providerId,
+    modelId: `${providerId}/${connection.version}/${config.model}`,
+    connectionId: connection.id,
+    version: connection.version,
+  };
+}
+
+export function isDirectModelId(modelId: string): boolean {
+  return /^workspace-(?:openai|azure-openai)-[0-9a-f-]{36}\//.test(modelId);
+}

package/src/editable-artifact-binary.ts

@@ -1,7 +1,10 @@
 const TEXT_ENCODER = new TextEncoder();
 const TEXT_DECODER = new TextDecoder("utf-8", { fatal: true });
-const FNV_OFFSET = 0xcbf29ce484222325n;
-const FNV_PRIME = 0x100000001b3n;
+const FNV_OFFSET_LOW = 0x8422_2325;
+const FNV_OFFSET_HIGH = 0xcbf2_9ce4;
+// The 64-bit FNV prime is 2^40 + 0x1b3: multiply the low limb by 0x1b3 and
+// carry `low << 40` into the high limb as `low * 2^8`.
+const FNV_PRIME_LOW = 0x01b3;
 const SAFE_INTEGER = BigInt(Number.MAX_SAFE_INTEGER);
 const STABLE_ID = /^[0-9a-f]{32}$/u;
 
@@ -76,13 +79,31 @@ export function canonicalNumber(value: number, label: string): number {
   return value;
 }
 
+/**
+ * FNV-1a-64 over `bytes[0, end)` using 32-bit integer limbs, with the low
+ * limb's product split into 16-bit halves so every step stays in int32
+ * arithmetic. Bit-identical to the BigInt definition without allocating a
+ * BigInt per byte (which made checksumming stored history a dominant CPU cost).
+ */
+export function fnv1a64Limbs(
+  bytes: Uint8Array,
+  end: number = bytes.byteLength,
+): readonly [low: number, high: number] {
+  let low = FNV_OFFSET_LOW | 0;
+  let high = FNV_OFFSET_HIGH | 0;
+  for (let index = 0; index < end; index += 1) {
+    low ^= bytes[index]!;
+    const lowHalf = (low & 0xffff) * FNV_PRIME_LOW;
+    const highHalf = (low >>> 16) * FNV_PRIME_LOW + (lowHalf >>> 16);
+    high = (Math.imul(high, FNV_PRIME_LOW) + (highHalf >>> 16) + (low << 8)) | 0;
+    low = (highHalf << 16) | (lowHalf & 0xffff);
+  }
+  return [low >>> 0, high >>> 0];
+}
+
 export function fnv1a64(bytes: Uint8Array): bigint {
-  let hash = FNV_OFFSET;
-  for (const byte of bytes) {
-    hash ^= BigInt(byte);
-    hash = BigInt.asUintN(64, hash * FNV_PRIME);
-  }
-  return hash;
+  const [low, high] = fnv1a64Limbs(bytes);
+  return (BigInt(high) << 32n) | BigInt(low);
 }
 
 export function equalBytes(left: Uint8Array, right: Uint8Array): boolean {

package/src/editable-artifact-committed-transaction.ts

@@ -8,6 +8,12 @@
  */
 
 import { COMMITTED_TRANSACTION_PROTOCOL_VERSION } from "./editable-artifact-versions";
+import { fnv1a64Limbs } from "./editable-artifact-binary";
+import {
+  SPREADSHEET_DEFAULT_ROW_HEIGHT,
+  SPREADSHEET_DEFAULT_COLUMN_WIDTH,
+  SPREADSHEET_MAX_DIMENSION_PIXELS,
+} from "./spreadsheet-artifact-commands";
 
 export { COMMITTED_TRANSACTION_PROTOCOL_VERSION } from "./editable-artifact-versions";
 export const MAX_COMMITTED_TRANSACTION_BYTES = 8 * 1024 * 1024;
@@ -25,9 +31,6 @@ const MAX_SAFE_U64_HIGH = 0x1f_ffff;
 const U32_SIZE = 0x1_0000_0000;
 const U32_MAX = 0xffff_ffff;
 const MAX_DATE_MILLISECONDS = 8_640_000_000_000_000n;
-const FNV_OFFSET_LOW = 0x8422_2325;
-const FNV_OFFSET_HIGH = 0xcbf2_9ce4;
-const FNV_PRIME_LOW = 0x01b3;
 
 const HEX = Array.from({ length: 256 }, (_, value) => value.toString(16).padStart(2, "0"));
 
@@ -91,7 +94,7 @@ export function decodeCommittedTransactionSummary(bytes: Uint8Array): CommittedT
     );
   }
 
-  const [checksumLow, checksumHigh] = fnv1a64(bytes, payloadEnd);
+  const [checksumLow, checksumHigh] = fnv1a64Limbs(bytes, payloadEnd);
   if (
     view.getUint32(payloadEnd, true) !== checksumLow ||
     view.getUint32(payloadEnd + 4, true) !== checksumHigh
@@ -281,6 +284,18 @@ class Reader {
       case 5:
         this.stableId("selective undo target");
         return totalCells;
+      case 6:
+      case 7: {
+        this.skipGeneration("dimension sheet generation");
+        this.u32("dimension index");
+        const pixels = this.u32("dimension pixels");
+        const defaultPixels =
+          tag === 6 ? SPREADSHEET_DEFAULT_ROW_HEIGHT : SPREADSHEET_DEFAULT_COLUMN_WIDTH;
+        if (pixels > SPREADSHEET_MAX_DIMENSION_PIXELS || pixels === defaultPixels) {
+          throw new TypeError("OGACO002 dimension pixels are noncanonical or outside bounds");
+        }
+        return totalCells;
+      }
       default:
         throw new TypeError(`invalid OGACO002 collaboration command tag: ${tag}`);
     }
@@ -475,17 +490,3 @@ function hexBytes(bytes: Uint8Array): string {
   for (const byte of bytes) result += HEX[byte];
   return result;
 }
-
-/** FNV-1a-64 using exact 32-bit limbs; avoids a BigInt allocation per byte. */
-function fnv1a64(bytes: Uint8Array, end: number): readonly [low: number, high: number] {
-  let low = FNV_OFFSET_LOW;
-  let high = FNV_OFFSET_HIGH;
-  for (let index = 0; index < end; index += 1) {
-    low = (low ^ bytes[index]!) >>> 0;
-    const lowProduct = low * FNV_PRIME_LOW;
-    const carry = Math.floor(lowProduct / U32_SIZE);
-    high = (high * FNV_PRIME_LOW + carry + low * 0x100) >>> 0;
-    low = lowProduct >>> 0;
-  }
-  return [low, high];
-}

package/src/editable-artifact-serialized-commit.ts

@@ -94,7 +94,11 @@ export type EditableArtifactSerializedCommitSummary = Readonly<{
 export function encodeEditableArtifactSerializedCommit(
   input: EditableArtifactSerializedCommitInput,
 ): Uint8Array {
-  const normalized = normalizeSerializedCommit(input);
+  return encodeNormalizedSerializedCommit(normalizeSerializedCommit(input));
+}
+
+/** Encodes a commit whose fields `normalizeSerializedCommit` already validated. */
+function encodeNormalizedSerializedCommit(normalized: NormalizedSerializedCommit): Uint8Array {
   const payload = new ArtifactBinaryWriter(
     EDITABLE_ARTIFACT_SERIALIZED_COMMIT_MAX_BYTES -
       EDITABLE_ARTIFACT_BINARY_HEADER_BYTES -
@@ -206,7 +210,9 @@ export function decodeEditableArtifactSerializedCommit(
     intentBytes,
     nativeReceiptBytes,
   });
-  const canonical = encodeEditableArtifactSerializedCommit(normalized);
+  // The fields were just normalized; re-encoding them proves canonical bytes
+  // without decoding and validating the nested intent and receipt twice.
+  const canonical = encodeNormalizedSerializedCommit(normalized);
   if (!equalBytes(bytes, canonical)) {
     throw new TypeError("serialized commit is not canonically encoded");
   }

package/src/editable-artifact-versions.ts

@@ -1,4 +1,10 @@
-/** Modality-specific durable semantic/schema versions. */
+/**
+ * Modality-specific durable semantic/schema versions.
+ * Spreadsheet dimensions are an additive current-schema extension: existing
+ * command/operation tags and dimension-free snapshot bytes stay unchanged.
+ * Direct snapshots and private projections advertise their explicit extension
+ * flags; old executables reject new tags/flags, never silently discard them.
+ */
 export const SPREADSHEET_ARTIFACT_MODEL_SCHEMA_VERSION = 2 as const;
 export const DOCUMENT_ARTIFACT_MODEL_SCHEMA_VERSION = 1 as const;
 export const PRESENTATION_ARTIFACT_MODEL_SCHEMA_VERSION = 1 as const;

package/src/event-preview.ts

@@ -15,6 +15,18 @@ import {
 
 export const SESSION_EVENT_PAYLOAD_MAX_BYTES = 64 * 1024;
 
+/**
+ * Durable ceiling for one `agent.toolCall.output` event. The event is the
+ * human/audit record of a tool result; model history keeps its own truncated
+ * copy separately. A tool can return far more than anyone ever sees (a shell
+ * command printing a 45 MB line, for example), and storing that inline made
+ * every later history read load it whole. The budget comfortably exceeds the
+ * model-facing tool-output truncation, so the timeline never shows less than
+ * the model saw.
+ */
+export const TOOL_CALL_OUTPUT_EVENT_MAX_BYTES = 256 * 1024;
+const TOOL_CALL_OUTPUT_EVENT_STRING_BYTES = 64 * 1024;
+
 const TARGET_PAYLOAD_BYTES = 60 * 1024;
 const DEFAULT_STRING_BYTES = 8 * 1024;
 const RETRY_STRING_BYTES = 1024;
@@ -90,6 +102,11 @@ export type SessionEventPayloadTruncation = {
 export type BoundSessionEventPayloadOptions = {
   surface?: SessionEventBoundarySurface;
   maxBytes?: number;
+  /**
+   * Per-string head+tail budget once the payload must be bounded. Defaults to
+   * the compact preview budget; larger budgets keep the byte target at maxBytes.
+   */
+  stringBytes?: number;
   /**
    * Separately trusted durable receipt. Producer payload fields never populate
    * this slot; invalid values fail closed to not_retained.
@@ -195,12 +212,23 @@ export function boundSessionEventPayload<T>(
 ): T {
   const maxBytes = Math.max(1024, Math.floor(options.maxBytes ?? SESSION_EVENT_PAYLOAD_MAX_BYTES));
   const surface = options.surface ?? "durable_audit";
+  const customStringBytes =
+    options.stringBytes === undefined
+      ? null
+      : Math.max(RETRY_STRING_BYTES, Math.floor(options.stringBytes));
+  const stringBytes = customStringBytes ?? DEFAULT_STRING_BYTES;
+  const retryStringBytes =
+    customStringBytes === null
+      ? RETRY_STRING_BYTES
+      : Math.max(RETRY_STRING_BYTES, Math.floor(customStringBytes / 8));
+  const targetBytes =
+    customStringBytes === null ? Math.min(maxBytes, TARGET_PAYLOAD_BYTES) : maxBytes;
   const fullEvidence =
     validateRetainedOutputEvidence(options.fullEvidence) ?? retainedOutputUnavailable();
   const originalMeasurement = measureJsonBytes(payload);
   const originalBytes = originalMeasurement.bytes;
 
-  let state = previewState(DEFAULT_STRING_BYTES, DEFAULT_ARRAY_ENTRIES, DEFAULT_OBJECT_FIELDS);
+  let state = previewState(stringBytes, DEFAULT_ARRAY_ENTRIES, DEFAULT_OBJECT_FIELDS);
   let preview = previewValue(payload, state, "$", 0);
   if (!state.changed && originalBytes !== null && originalBytes <= maxBytes) {
     return payload;
@@ -212,8 +240,8 @@ export function boundSessionEventPayload<T>(
     boundaryMetadata(surface, reason, originalBytes, state, fullEvidence),
   );
 
-  if (sessionEventJsonBytes(bounded) > Math.min(maxBytes, TARGET_PAYLOAD_BYTES)) {
-    state = previewState(RETRY_STRING_BYTES, RETRY_ARRAY_ENTRIES, RETRY_OBJECT_FIELDS);
+  if (sessionEventJsonBytes(bounded) > targetBytes) {
+    state = previewState(retryStringBytes, RETRY_ARRAY_ENTRIES, RETRY_OBJECT_FIELDS);
     preview = previewValue(payload, state, "$", 0);
     reason = payloadTruncationReason(originalMeasurement, state);
     bounded = attachTruncation(
@@ -243,6 +271,28 @@ export function boundSessionEventPayload<T>(
   return bounded as T;
 }
 
+/**
+ * Write-time bound for durable session events. Only tool-call output has an
+ * unbounded producer; it is kept intact up to TOOL_CALL_OUTPUT_EVENT_MAX_BYTES
+ * and otherwise stored as an explicit head+tail preview whose `truncation`
+ * records the original size. Every other event type is returned unchanged.
+ */
+export function boundSessionEventPayloadForWrite<T>(type: string, payload: T): T {
+  if (type !== "agent.toolCall.output") return payload;
+  let bytes: number | null;
+  try {
+    bytes = sessionEventJsonBytes(payload);
+  } catch {
+    bytes = null;
+  }
+  if (bytes !== null && bytes <= TOOL_CALL_OUTPUT_EVENT_MAX_BYTES) return payload;
+  return boundSessionEventPayload(payload, {
+    surface: "durable_audit",
+    maxBytes: TOOL_CALL_OUTPUT_EVENT_MAX_BYTES,
+    stringBytes: TOOL_CALL_OUTPUT_EVENT_STRING_BYTES,
+  });
+}
+
 function previewState(
   stringBytes: number,
   arrayEntries: number,