@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/src/work-claims.ts

@@ -1,3 +1,5 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 import { normalizeAutomaticSessionTitle } from "./session-titles";
 
@@ -16,35 +18,32 @@ const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f]/u;
 const NAMESPACE_PATTERN = /^[a-z0-9](?:[a-z0-9._:-]{0,62}[a-z0-9])?$/u;
 
 function boundedCanonicalText(maxBytes: number, label: string) {
-  return z
-    .string()
-    .min(1)
-    .superRefine((value, context) => {
-      if (value !== value.trim()) {
-        context.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `${label} must not have leading or trailing whitespace`,
-        });
-      }
-      if (value !== value.normalize("NFKC")) {
-        context.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `${label} must use canonical Unicode normalization`,
-        });
-      }
-      if (CONTROL_CHARACTERS.test(value)) {
-        context.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `${label} must not contain control characters`,
-        });
-      }
-      if (utf8Bytes(value) > maxBytes) {
-        context.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `${label} must be at most ${maxBytes} UTF-8 bytes`,
-        });
-      }
-    });
+  return primitives.nonEmptyString.superRefine((value, context) => {
+    if (value !== value.trim()) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `${label} must not have leading or trailing whitespace`,
+      });
+    }
+    if (value !== value.normalize("NFKC")) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `${label} must use canonical Unicode normalization`,
+      });
+    }
+    if (CONTROL_CHARACTERS.test(value)) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `${label} must not contain control characters`,
+      });
+    }
+    if (utf8Bytes(value) > maxBytes) {
+      context.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `${label} must be at most ${maxBytes} UTF-8 bytes`,
+      });
+    }
+  });
 }
 
 export function normalizeWorkClaimNamespace(value: string): string {
@@ -61,26 +60,23 @@ export function normalizeWorkClaimDisplayLabel(value: string): string | null {
   return normalized;
 }
 
-export const WorkClaimNamespace = z
-  .string()
-  .min(1)
-  .max(WORK_CLAIM_NAMESPACE_MAX_BYTES)
-  .regex(NAMESPACE_PATTERN)
-  .refine((value) => value === normalizeWorkClaimNamespace(value), {
-    message: "work claim namespace must already be canonical lowercase text",
-  });
+export const WorkClaimNamespace = /* @__PURE__ */ defineSchema(() =>
+  primitives.nonEmptyString
+    .max(WORK_CLAIM_NAMESPACE_MAX_BYTES)
+    .regex(NAMESPACE_PATTERN)
+    .refine((value) => value === normalizeWorkClaimNamespace(value), {
+      message: "work claim namespace must already be canonical lowercase text",
+    }),
+);
 export type WorkClaimNamespace = z.infer<typeof WorkClaimNamespace>;
 
-export const WorkClaimCanonicalKey = boundedCanonicalText(
-  WORK_CLAIM_CANONICAL_KEY_MAX_BYTES,
-  "work claim canonical key",
+export const WorkClaimCanonicalKey = /* @__PURE__ */ defineSchema(() =>
+  boundedCanonicalText(WORK_CLAIM_CANONICAL_KEY_MAX_BYTES, "work claim canonical key"),
 );
 export type WorkClaimCanonicalKey = z.infer<typeof WorkClaimCanonicalKey>;
 
-export const WorkClaimDisplayLabel = z
-  .string()
-  .min(1)
-  .superRefine((value, context) => {
+export const WorkClaimDisplayLabel = /* @__PURE__ */ defineSchema(() =>
+  primitives.nonEmptyString.superRefine((value, context) => {
     if (utf8Bytes(value) > WORK_CLAIM_DISPLAY_LABEL_MAX_BYTES) {
       context.addIssue({
         code: z.ZodIssueCode.custom,
@@ -93,45 +89,56 @@ export const WorkClaimDisplayLabel = z
         message: "work claim display label must be a safe concise semantic label",
       });
     }
-  });
+  }),
+);
 export type WorkClaimDisplayLabel = z.infer<typeof WorkClaimDisplayLabel>;
 
-export const WorkClaimSubjectType = z.enum([
-  "repository",
-  "branch",
-  "pull_request",
-  "issue",
-  "artifact",
-  "release",
-  "ci_run",
-  "other",
-]);
+export const WorkClaimSubjectType = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "repository",
+    "branch",
+    "pull_request",
+    "issue",
+    "artifact",
+    "release",
+    "ci_run",
+    "other",
+  ]),
+);
 export type WorkClaimSubjectType = z.infer<typeof WorkClaimSubjectType>;
 
-export const WorkClaimRole = z.enum(["working", "reviewing", "monitoring", "delivering"]);
+export const WorkClaimRole = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["working", "reviewing", "monitoring", "delivering"]),
+);
 export type WorkClaimRole = z.infer<typeof WorkClaimRole>;
 
-export const WorkClaimState = z.enum(["active", "released", "superseded", "stale"]);
+export const WorkClaimState = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["active", "released", "superseded", "stale"]),
+);
 export type WorkClaimState = z.infer<typeof WorkClaimState>;
 
-export const WorkClaimProvenance = z.enum([
-  "explicit_agent",
-  "user_api",
-  "trusted_integration",
-  "session_resource",
-  "system_lifecycle",
-]);
+export const WorkClaimProvenance = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "explicit_agent",
+    "user_api",
+    "trusted_integration",
+    "session_resource",
+    "system_lifecycle",
+  ]),
+);
 export type WorkClaimProvenance = z.infer<typeof WorkClaimProvenance>;
 
-export const WorkClaimVersionKind = z.enum([
-  "git_commit",
-  "branch_head",
-  "pull_request_head",
-  "artifact_version",
-  "release_version",
-  "ci_run",
-  "other",
-]);
+export const WorkClaimVersionKind = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "git_commit",
+    "branch_head",
+    "pull_request_head",
+    "artifact_version",
+    "release_version",
+    "ci_run",
+    "other",
+  ]),
+);
 export type WorkClaimVersionKind = z.infer<typeof WorkClaimVersionKind>;
 
 export const WorkClaimVersionValue = boundedCanonicalText(
@@ -140,112 +147,120 @@ export const WorkClaimVersionValue = boundedCanonicalText(
 );
 export type WorkClaimVersionValue = z.infer<typeof WorkClaimVersionValue>;
 
-export const WorkClaimReleaseReason = z.enum([
-  "completed",
-  "cancelled",
-  "failed",
-  "superseded",
-  "no_longer_active",
-  "corrected",
-  "external_state_changed",
-  "other",
-]);
+export const WorkClaimReleaseReason = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "completed",
+    "cancelled",
+    "failed",
+    "superseded",
+    "no_longer_active",
+    "corrected",
+    "external_state_changed",
+    "other",
+  ]),
+);
 export type WorkClaimReleaseReason = z.infer<typeof WorkClaimReleaseReason>;
 
-export const WorkClaimMutationKind = z.enum([
-  "created",
-  "updated",
-  "released",
-  "superseded",
-  "stale",
-]);
+export const WorkClaimMutationKind = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["created", "updated", "released", "superseded", "stale"]),
+);
 export type WorkClaimMutationKind = z.infer<typeof WorkClaimMutationKind>;
 
-export const WorkClaim = z.object({
-  id: z.string().uuid(),
-  sessionId: z.string().uuid(),
-  rootSessionId: z.string().uuid(),
-  subject: z.object({
-    namespace: WorkClaimNamespace,
-    type: WorkClaimSubjectType,
-    canonicalKey: WorkClaimCanonicalKey,
-    displayLabel: WorkClaimDisplayLabel.nullable(),
+export const WorkClaim = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    id: primitives.uuid,
+    sessionId: primitives.uuid,
+    rootSessionId: primitives.uuid,
+    subject: z.object({
+      namespace: WorkClaimNamespace,
+      type: WorkClaimSubjectType,
+      canonicalKey: WorkClaimCanonicalKey,
+      displayLabel: WorkClaimDisplayLabel.nullable(),
+    }),
+    role: WorkClaimRole,
+    state: WorkClaimState,
+    revision: primitives.positiveInteger,
+    provenance: WorkClaimProvenance,
+    version: z
+      .object({
+        kind: WorkClaimVersionKind,
+        value: WorkClaimVersionValue,
+      })
+      .nullable(),
+    observedAt: primitives.string.datetime({ offset: true }),
+    createdAt: primitives.string.datetime({ offset: true }),
+    updatedAt: primitives.string.datetime({ offset: true }),
+    settledAt: primitives.string.datetime({ offset: true }).nullable(),
   }),
-  role: WorkClaimRole,
-  state: WorkClaimState,
-  revision: z.number().int().positive(),
-  provenance: WorkClaimProvenance,
-  version: z
-    .object({
-      kind: WorkClaimVersionKind,
-      value: WorkClaimVersionValue,
-    })
-    .nullable(),
-  observedAt: z.string().datetime({ offset: true }),
-  createdAt: z.string().datetime({ offset: true }),
-  updatedAt: z.string().datetime({ offset: true }),
-  settledAt: z.string().datetime({ offset: true }).nullable(),
-});
+);
 export type WorkClaim = z.infer<typeof WorkClaim>;
 
-export const WorkClaimMutationResult = z.object({
-  claim: WorkClaim,
-  mutation: WorkClaimMutationKind,
-  replayed: z.boolean(),
-});
+export const WorkClaimMutationResult = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    claim: WorkClaim,
+    mutation: WorkClaimMutationKind,
+    replayed: primitives.boolean,
+  }),
+);
 export type WorkClaimMutationResult = z.infer<typeof WorkClaimMutationResult>;
 
-export const WorkClaimDiscoverySummary = WorkClaim.pick({
-  id: true,
-  sessionId: true,
-  subject: true,
-  role: true,
-  state: true,
-  revision: true,
-  provenance: true,
-  version: true,
-  observedAt: true,
-  updatedAt: true,
-  settledAt: true,
-});
+export const WorkClaimDiscoverySummary = /* @__PURE__ */ defineSchema(() =>
+  WorkClaim.pick({
+    id: true,
+    sessionId: true,
+    subject: true,
+    role: true,
+    state: true,
+    revision: true,
+    provenance: true,
+    version: true,
+    observedAt: true,
+    updatedAt: true,
+    settledAt: true,
+  }),
+);
 export type WorkClaimDiscoverySummary = z.infer<typeof WorkClaimDiscoverySummary>;
 
-export const WorkClaimSubjectFilter = z
-  .object({
-    namespace: WorkClaimNamespace,
-    type: WorkClaimSubjectType,
-    canonicalKey: WorkClaimCanonicalKey,
-  })
-  .strict();
+export const WorkClaimSubjectFilter = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      namespace: WorkClaimNamespace,
+      type: WorkClaimSubjectType,
+      canonicalKey: WorkClaimCanonicalKey,
+    })
+    .strict(),
+);
 export type WorkClaimSubjectFilter = z.infer<typeof WorkClaimSubjectFilter>;
 
-export const WorkDiscoveryMatchClass = z.enum(["exact_subject", "title", "goal", "fuzzy"]);
+export const WorkDiscoveryMatchClass = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["exact_subject", "title", "goal", "fuzzy"]),
+);
 export type WorkDiscoveryMatchClass = z.infer<typeof WorkDiscoveryMatchClass>;
 
-export const WorkDiscoveryMatchedField = z.enum([
-  "subject",
-  "title",
-  "goal",
-  "claim_key",
-  "claim_label",
-]);
+export const WorkDiscoveryMatchedField = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["subject", "title", "goal", "claim_key", "claim_label"]),
+);
 export type WorkDiscoveryMatchedField = z.infer<typeof WorkDiscoveryMatchedField>;
 
 /**
  * Deliberately stable bands rather than a raw ranking score. Raw full-text or
  * trigram values are query-relative and become a misleading cross-query API.
  */
-export const WorkDiscoveryScoreBand = z.enum(["exact", "strong", "related"]);
+export const WorkDiscoveryScoreBand = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["exact", "strong", "related"]),
+);
 export type WorkDiscoveryScoreBand = z.infer<typeof WorkDiscoveryScoreBand>;
 
-export const WorkDiscoveryMatch = z
-  .object({
-    class: WorkDiscoveryMatchClass,
-    field: WorkDiscoveryMatchedField,
-    scoreBand: WorkDiscoveryScoreBand,
-    claimId: z.string().uuid().nullable(),
-  })
-  .strict();
+export const WorkDiscoveryMatch = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      class: WorkDiscoveryMatchClass,
+      field: WorkDiscoveryMatchedField,
+      scoreBand: WorkDiscoveryScoreBand,
+      claimId: primitives.nullableUuid,
+    })
+    .strict(),
+);
 export type WorkDiscoveryMatch = z.infer<typeof WorkDiscoveryMatch>;
 
 /**
@@ -253,14 +268,16 @@ export type WorkDiscoveryMatch = z.infer<typeof WorkDiscoveryMatch>;
  * the wire contract so a consumer cannot accidentally present a claim as a
  * lock, authorization grant, ownership transfer, or mandatory instruction.
  */
-export const WorkDiscoveryProjection = z
-  .object({
-    claims: z.array(WorkClaimDiscoverySummary).max(WORK_CLAIM_DISCOVERY_LIMIT),
-    claimsTruncated: z.boolean(),
-    match: WorkDiscoveryMatch.nullable(),
-    possibleOverlap: z.boolean(),
-    advisoryOnly: z.literal(true),
-    noAdditionalAccess: z.literal(true),
-  })
-  .strict();
+export const WorkDiscoveryProjection = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      claims: z.array(WorkClaimDiscoverySummary).max(WORK_CLAIM_DISCOVERY_LIMIT),
+      claimsTruncated: primitives.boolean,
+      match: WorkDiscoveryMatch.nullable(),
+      possibleOverlap: primitives.boolean,
+      advisoryOnly: z.literal(true),
+      noAdditionalAccess: z.literal(true),
+    })
+    .strict(),
+);
 export type WorkDiscoveryProjection = z.infer<typeof WorkDiscoveryProjection>;

package/src/workspace-control-event.ts

@@ -0,0 +1,134 @@
+import type { WorkspaceControlEvent, WorkspaceControlEventTruncation } from "./index";
+import { sessionEventJsonBytes } from "./event-preview";
+export const WORKSPACE_CONTROL_REASON_MAX_BYTES = 8 * 1024;
+
+export const WORKSPACE_CONTROL_ACTOR_MAX_BYTES = 1024;
+
+export const WORKSPACE_CONTROL_EVENT_MAX_BYTES = 16 * 1024;
+
+export type WorkspaceControlBoundarySurface = WorkspaceControlEventTruncation["surface"];
+
+export type BoundWorkspaceControlEventOptions = {
+  surface?: WorkspaceControlBoundarySurface;
+  reasonOriginalBytes?: number | null;
+  actorOriginalBytes?: number | null;
+};
+
+/** UTF-8 byte count used by workspace-control storage and transport guards. */
+export function workspaceControlUtf8Bytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+/**
+ * Canonical bounded invalidation event. The event is not a full evidence store:
+ * when a producer or legacy row exceeds a field cap, the retained head carries
+ * a visible marker and structured exact byte-loss facts.
+ */
+export function boundWorkspaceControlEvent(
+  event: WorkspaceControlEvent,
+  options: BoundWorkspaceControlEventOptions = {},
+): WorkspaceControlEvent {
+  const existingFields = new Map(
+    (event.truncation?.fields ?? []).map((field) => [field.field, field] as const),
+  );
+  const reason =
+    event.reason === null
+      ? null
+      : boundWorkspaceControlText(event.reason, WORKSPACE_CONTROL_REASON_MAX_BYTES);
+  const actor = boundWorkspaceControlText(event.actor, WORKSPACE_CONTROL_ACTOR_MAX_BYTES);
+  const reasonBytes = reason === null ? 0 : workspaceControlUtf8Bytes(reason);
+  const actorBytes = workspaceControlUtf8Bytes(actor);
+  const reasonOriginalBytes =
+    event.reason === null
+      ? null
+      : Math.max(
+          workspaceControlUtf8Bytes(event.reason),
+          normalizedWorkspaceControlOriginalBytes(options.reasonOriginalBytes),
+          existingFields.get("reason")?.originalBytes ?? 0,
+        );
+  const actorOriginalBytes = Math.max(
+    workspaceControlUtf8Bytes(event.actor),
+    normalizedWorkspaceControlOriginalBytes(options.actorOriginalBytes),
+    existingFields.get("actor")?.originalBytes ?? 0,
+  );
+  const fields: WorkspaceControlEventTruncation["fields"] = [];
+  if (reasonOriginalBytes !== null && reasonOriginalBytes > reasonBytes) {
+    fields.push({
+      field: "reason",
+      originalBytes: reasonOriginalBytes,
+      deliveredBytes: reasonBytes,
+      omittedBytes: reasonOriginalBytes - reasonBytes,
+    });
+  }
+  if (actorOriginalBytes > actorBytes) {
+    fields.push({
+      field: "actor",
+      originalBytes: actorOriginalBytes,
+      deliveredBytes: actorBytes,
+      omittedBytes: actorOriginalBytes - actorBytes,
+    });
+  }
+  if (fields.length === 0 && event.truncation == null) {
+    if (sessionEventJsonBytes(event) > WORKSPACE_CONTROL_EVENT_MAX_BYTES) {
+      throw new RangeError("Workspace control event exceeds its bounded envelope");
+    }
+    return event;
+  }
+
+  const truncation: WorkspaceControlEventTruncation = {
+    truncated: true,
+    surface: event.truncation?.surface ?? options.surface ?? "durable_control",
+    deliveredBytes: 0,
+    fields,
+    fullEvidence: { available: false, reason: "not_retained" },
+  };
+  const bounded: WorkspaceControlEvent = {
+    ...event,
+    reason,
+    actor,
+    truncation,
+  };
+  settleWorkspaceControlDeliveredBytes(bounded, truncation);
+  const deliveredBytes = sessionEventJsonBytes(bounded);
+  if (deliveredBytes > WORKSPACE_CONTROL_EVENT_MAX_BYTES) {
+    throw new RangeError(
+      `Bounded workspace control event exceeds its final envelope (${deliveredBytes} > ${WORKSPACE_CONTROL_EVENT_MAX_BYTES} bytes)`,
+    );
+  }
+  return bounded;
+}
+
+function boundWorkspaceControlText(value: string, maxBytes: number): string {
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  const bytes = encoder.encode(value);
+  if (bytes.byteLength <= maxBytes) return value;
+  const marker = "…[truncated]";
+  const prefixBudget = Math.max(0, maxBytes - encoder.encode(marker).byteLength);
+  let prefixEnd = Math.min(prefixBudget, bytes.byteLength);
+  while (prefixEnd > 0 && prefixEnd < bytes.byteLength && (bytes[prefixEnd]! & 0xc0) === 0x80) {
+    prefixEnd -= 1;
+  }
+  return `${decoder.decode(bytes.subarray(0, prefixEnd))}${marker}`;
+}
+
+function normalizedWorkspaceControlOriginalBytes(value: number | null | undefined): number {
+  return value === null || value === undefined || !Number.isFinite(value)
+    ? 0
+    : Math.max(0, Math.floor(value));
+}
+
+function settleWorkspaceControlDeliveredBytes(
+  event: WorkspaceControlEvent,
+  truncation: WorkspaceControlEventTruncation,
+): void {
+  for (let attempt = 0; attempt < 16; attempt += 1) {
+    const deliveredBytes = sessionEventJsonBytes(event);
+    if (truncation.deliveredBytes === deliveredBytes) return;
+    truncation.deliveredBytes = deliveredBytes;
+  }
+  const deliveredBytes = sessionEventJsonBytes(event);
+  if (truncation.deliveredBytes !== deliveredBytes) {
+    throw new RangeError("Workspace control event byte accounting did not converge");
+  }
+}

package/src/workspace-governance-context.ts

@@ -0,0 +1,63 @@
+/**
+ * Durable, model-visible workspace governance context.
+ *
+ * Governance (instruction policies, learning settings, organization profile)
+ * can change between turns and differs by who starts a turn. In the system
+ * prompt, every such change rewrote text that earlier requests had already sent
+ * and invalidated the whole cached history. It is therefore delivered as a
+ * history item inserted before the turn that first sees a new value; earlier
+ * items stay byte-identical, and the newest item replaces older ones.
+ */
+export const WORKSPACE_GOVERNANCE_CONTEXT_PREFIX = "<opengeni_workspace_governance>\n";
+export const WORKSPACE_GOVERNANCE_CONTEXT_SUFFIX = "\n</opengeni_workspace_governance>";
+const GUIDANCE =
+  "This is the current workspace governance and replaces earlier workspace governance blocks.\n\n";
+/** Recorded when governance that applied earlier no longer does. */
+export const WORKSPACE_GOVERNANCE_NONE = "No workspace governance is active.";
+
+export function workspaceGovernanceContextItem(governance: string): Record<string, unknown> {
+  return {
+    type: "message",
+    role: "developer",
+    content:
+      WORKSPACE_GOVERNANCE_CONTEXT_PREFIX +
+      GUIDANCE +
+      governance +
+      WORKSPACE_GOVERNANCE_CONTEXT_SUFFIX,
+  };
+}
+
+/** Accept the Chat Completions projection and SDK text-part normalization too. */
+export function readWorkspaceGovernanceContext(item: Record<string, unknown>): string | null {
+  if (item.type === "unknown" && item.providerData && typeof item.providerData === "object") {
+    const data = item.providerData as Record<string, unknown>;
+    if (data.type === "message") return readWorkspaceGovernanceContext(data);
+  }
+  if (item.type !== "message" || (item.role !== "developer" && item.role !== "system")) return null;
+  const content =
+    typeof item.content === "string"
+      ? item.content
+      : Array.isArray(item.content) &&
+          item.content.every(
+            (part) =>
+              part &&
+              (part.type === "input_text" || part.type === "output_text" || part.type === "text") &&
+              typeof part.text === "string",
+          )
+        ? item.content.map((part) => part.text).join("")
+        : null;
+  const prefix = WORKSPACE_GOVERNANCE_CONTEXT_PREFIX + GUIDANCE;
+  return content?.startsWith(prefix) && content.endsWith(WORKSPACE_GOVERNANCE_CONTEXT_SUFFIX)
+    ? content.slice(prefix.length, -WORKSPACE_GOVERNANCE_CONTEXT_SUFFIX.length)
+    : null;
+}
+
+export function latestWorkspaceGovernanceContext(
+  items: readonly Record<string, unknown>[],
+): Record<string, unknown> | undefined {
+  for (let index = items.length - 1; index >= 0; index--) {
+    const governance = readWorkspaceGovernanceContext(items[index]!);
+    if (governance !== null) return workspaceGovernanceContextItem(governance);
+  }
+  return undefined;
+}