@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/src/subscription-plans.ts

@@ -0,0 +1,51 @@
+import * as primitives from "./primitives";
+import { z } from "zod";
+
+/** Operator-managed catalog; monetary amounts are USD micro-units. */
+export const SubscriptionPlan = z.strictObject({
+  key: primitives.string.regex(/^[a-z][a-z0-9_-]{0,39}$/),
+  label: primitives.string.trim().min(1).max(120),
+  stripePriceId: primitives.string.trim().min(1).max(200).nullable(),
+  /** Existing subscriptions only; checkout and plan changes use stripePriceId. */
+  legacyStripePriceIds: z.array(primitives.string.trim().min(1).max(200)).max(100).optional(),
+  monthlyPriceMicros: primitives.nonnegativeInteger.max(Number.MAX_SAFE_INTEGER).nullable(),
+  monthlyCreditMicros: primitives.nonnegativeInteger.max(Number.MAX_SAFE_INTEGER),
+  seatLimit: z.number().int().positive().max(1_000_000).nullable(),
+  freeCredit: primitives.boolean,
+});
+export type SubscriptionPlan = z.infer<typeof SubscriptionPlan>;
+
+export const SubscriptionPlanCatalog = z
+  .array(SubscriptionPlan)
+  .min(1)
+  .max(100)
+  .superRefine((plans, context) => {
+    if (new Set(plans.map((plan) => plan.key)).size !== plans.length) {
+      context.addIssue({ code: "custom", message: "Plan keys must be unique" });
+    }
+    const prices = plans.flatMap((plan) => [
+      ...(plan.stripePriceId ? [plan.stripePriceId] : []),
+      ...(plan.legacyStripePriceIds ?? []),
+    ]);
+    if (new Set(prices).size !== prices.length) {
+      context.addIssue({ code: "custom", message: "Stripe price IDs must be unique" });
+    }
+  });
+export type SubscriptionPlanCatalog = z.infer<typeof SubscriptionPlanCatalog>;
+
+export const BillingPlanBalance = z.object({
+  key: primitives.string,
+  label: primitives.string,
+  status: primitives.string,
+  creditGrantedMicros: primitives.nonnegativeInteger,
+  creditRemainingMicros: primitives.nonnegativeInteger,
+  /** Already unavailable, but not yet removed from the physical ledger. */
+  creditPendingExpiryMicros: z.number().int().nonnegative().optional(),
+  /** The granted period is model-scoped, rather than part of general credit. */
+  creditScoped: primitives.optionalBoolean,
+  periodResetAt: primitives.nullableString,
+  seatLimit: z.number().int().positive().nullable(),
+  seatsUsed: primitives.nonnegativeInteger,
+  cancelAtPeriodEnd: primitives.boolean,
+});
+export type BillingPlanBalance = z.infer<typeof BillingPlanBalance>;

package/src/subscription-usage-pool.ts

@@ -0,0 +1,44 @@
+import * as primitives from "./primitives";
+import { z } from "zod";
+import { defineSchema } from "./define-schema";
+
+/** Informational limits, never a routing/admission decision or a spending total. */
+export const SubscriptionUsagePool = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    provider: z.enum(["codex", "claude", "xai"]),
+    observedAt: z.string().datetime().nullable(),
+    windows: z.array(
+      z.object({
+        id: z.enum(["five_hour", "weekly"]),
+        remainingPercent: z.number().min(0).max(100).nullable(),
+        accounts: z.array(
+          z.object({
+            id: primitives.uuid,
+            label: primitives.string,
+            remainingPercent: z.number().min(0).max(100).nullable(),
+            resetsAt: z.string().datetime().nullable(),
+            weight: z.number().positive(),
+            weightBasis: z.enum(["observed", "plan_estimate"]),
+            observedAt: z.string().datetime().nullable(),
+          }),
+        ),
+        forecast: z.object({
+          kind: z.enum(["runs_out", "unused", "insufficient_history"]),
+          basis: primitives.string,
+          runsOutAt: z.string().datetime().nullable(),
+          nextResetAt: z.string().datetime().nullable(),
+          unusedPercent: z.number().min(0).max(100).nullable(),
+          utilizationPercent: z.number().min(0).max(100).nullable().optional(),
+          lowestPercent: z.number().min(0).max(100).nullable(),
+          historyDays: z.number().nonnegative(),
+        }),
+      }),
+    ),
+  }),
+);
+export type SubscriptionUsagePool = z.infer<typeof SubscriptionUsagePool>;
+
+export const SubscriptionUsagePoolsResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ pools: z.array(SubscriptionUsagePool), checkedAt: primitives.dateTime }),
+);
+export type SubscriptionUsagePoolsResponse = z.infer<typeof SubscriptionUsagePoolsResponse>;

package/src/task-notes.ts

@@ -1,3 +1,5 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
 export const TASK_NOTE_TEXT_MAX_BYTES = 4_096;
@@ -11,23 +13,20 @@ export const TASK_NOTE_LIST_RESPONSE_MAX_BYTES = 96 * 1_024;
 const utf8Bytes = (value: string): number => new TextEncoder().encode(value).byteLength;
 
 export function boundedTaskNoteText(maxBytes: number, label: string) {
-  return z
-    .string()
-    .min(1)
-    .superRefine((value, ctx) => {
-      if (value !== value.trim()) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `${label} must not have leading or trailing whitespace`,
-        });
-      }
-      if (utf8Bytes(value) > maxBytes) {
-        ctx.addIssue({
-          code: z.ZodIssueCode.custom,
-          message: `${label} must be at most ${maxBytes} UTF-8 bytes`,
-        });
-      }
-    });
+  return primitives.nonEmptyString.superRefine((value, ctx) => {
+    if (value !== value.trim()) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `${label} must not have leading or trailing whitespace`,
+      });
+    }
+    if (utf8Bytes(value) > maxBytes) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `${label} must be at most ${maxBytes} UTF-8 bytes`,
+      });
+    }
+  });
 }
 
 export const TaskNoteText = boundedTaskNoteText(TASK_NOTE_TEXT_MAX_BYTES, "task note text");
@@ -36,70 +35,73 @@ export const TaskNoteReason = boundedTaskNoteText(
   "task note archive reason",
 );
 
-export const TaskNoteKind = z.enum([
-  "finding",
-  "decision",
-  "blocker",
-  "ownership",
-  "artifact",
-  "handoff",
-]);
+export const TaskNoteKind = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["finding", "decision", "blocker", "ownership", "artifact", "handoff"]),
+);
 export type TaskNoteKind = z.infer<typeof TaskNoteKind>;
 
-export const TaskNoteStatus = z.enum(["active", "archived"]);
+export const TaskNoteStatus = /* @__PURE__ */ defineSchema(() => z.enum(["active", "archived"]));
 export type TaskNoteStatus = z.infer<typeof TaskNoteStatus>;
 
-export const TaskNoteActorKind = z.enum(["human", "service"]);
+export const TaskNoteActorKind = /* @__PURE__ */ defineSchema(() => z.enum(["human", "service"]));
 export type TaskNoteActorKind = z.infer<typeof TaskNoteActorKind>;
 
-export const TaskNote = z.object({
-  id: z.string().uuid(),
-  rootSessionId: z.string().uuid(),
-  kind: TaskNoteKind,
-  text: TaskNoteText,
-  status: TaskNoteStatus,
-  version: z.number().int().positive(),
-  expiresAt: z.string().datetime({ offset: true }),
-  createdAt: z.string().datetime({ offset: true }),
-  updatedAt: z.string().datetime({ offset: true }),
-  archivedAt: z.string().datetime({ offset: true }).nullable(),
-  provenance: z.object({
-    actorKind: TaskNoteActorKind,
-    sourceSessionId: z.string().uuid(),
-    sourceTurnId: z.string().uuid(),
+export const TaskNote = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    id: primitives.uuid,
+    rootSessionId: primitives.uuid,
+    kind: TaskNoteKind,
+    text: TaskNoteText,
+    status: TaskNoteStatus,
+    version: primitives.positiveInteger,
+    expiresAt: primitives.string.datetime({ offset: true }),
+    createdAt: primitives.string.datetime({ offset: true }),
+    updatedAt: primitives.string.datetime({ offset: true }),
+    archivedAt: primitives.string.datetime({ offset: true }).nullable(),
+    provenance: z.object({
+      actorKind: TaskNoteActorKind,
+      sourceSessionId: primitives.uuid,
+      sourceTurnId: primitives.uuid,
+    }),
   }),
-});
+);
 export type TaskNote = z.infer<typeof TaskNote>;
 
-export const TaskNoteMutationResult = z.object({
-  note: TaskNote,
-  replayed: z.boolean(),
-});
+export const TaskNoteMutationResult = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    note: TaskNote,
+    replayed: primitives.boolean,
+  }),
+);
 export type TaskNoteMutationResult = z.infer<typeof TaskNoteMutationResult>;
 
 /** Atomic correction lineage: archive one exact v1 note and create one v1 replacement. */
-export const TaskNoteReplacementResult = z.object({
-  operationId: z.string().uuid(),
-  inputHash: z.string().regex(/^[0-9a-f]{64}$/),
-  replaces: z.object({
-    noteId: z.string().uuid(),
-    archivedVersion: z.literal(2),
+export const TaskNoteReplacementResult = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    operationId: primitives.uuid,
+    inputHash: primitives.string.regex(/^[0-9a-f]{64}$/),
+    replaces: z.object({
+      noteId: primitives.uuid,
+      archivedVersion: z.literal(2),
+    }),
+    replacement: TaskNote,
+    replayed: primitives.boolean,
   }),
-  replacement: TaskNote,
-  replayed: z.boolean(),
-});
+);
 export type TaskNoteReplacementResult = z.infer<typeof TaskNoteReplacementResult>;
 
-export const TaskNoteListResponse = z
-  .object({
-    notes: z.array(TaskNote).max(TASK_NOTE_LIST_MAX_LIMIT),
-  })
-  .superRefine((value, ctx) => {
-    if (utf8Bytes(JSON.stringify(value)) > TASK_NOTE_LIST_RESPONSE_MAX_BYTES) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: `task note list response must be at most ${TASK_NOTE_LIST_RESPONSE_MAX_BYTES} UTF-8 bytes`,
-      });
-    }
-  });
+export const TaskNoteListResponse = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      notes: z.array(TaskNote).max(TASK_NOTE_LIST_MAX_LIMIT),
+    })
+    .superRefine((value, ctx) => {
+      if (utf8Bytes(JSON.stringify(value)) > TASK_NOTE_LIST_RESPONSE_MAX_BYTES) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `task note list response must be at most ${TASK_NOTE_LIST_RESPONSE_MAX_BYTES} UTF-8 bytes`,
+        });
+      }
+    }),
+);
 export type TaskNoteListResponse = z.infer<typeof TaskNoteListResponse>;

package/src/tool-action-review.ts

@@ -0,0 +1,271 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+/** Gmail's batch modify limit: one review never selects more messages than this. */
+export const TOOL_REVIEW_SELECTION_LABELS_MAX = 1000;
+/** One selected item described by trusted provider metadata, never by agent arguments. */
+const ToolReviewSelectionLabel = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      id: z.string().max(256),
+      title: z.string().max(256),
+      subtitle: z.string().max(256).optional(),
+      provenance: z.literal("provider_metadata"),
+    })
+    .strict(),
+);
+
+/** Trusted adapter hints, never read from agent arguments or tool output. */
+export const ToolReviewContext = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      kind: z.enum(["generic", "gmail"]).default("generic"),
+      title: z.string().max(256).optional(),
+      accountLabel: z.string().max(256).optional(),
+      fieldLabels: z.record(primitives.string, z.string().max(256)).optional(),
+      protectedFields: z.array(primitives.string).optional(),
+      email: z
+        .object({
+          from: z.string().max(4096),
+          to: z.string().max(32768),
+          cc: z.string().max(32768),
+          bcc: z.string().max(32768),
+          subject: z.string().max(32768),
+          textBody: z.string().max(262144),
+          htmlBody: z.string().max(262144),
+          contentSha256: primitives.string.regex(/^[0-9a-f]{64}$/),
+          attachments: z
+            .array(
+              z
+                .object({
+                  name: z.string().max(1024),
+                  mediaType: z.string().max(256),
+                  bytes: primitives.nonnegativeInteger,
+                })
+                .strict(),
+            )
+            .max(100),
+        })
+        .strict()
+        .optional(),
+      samples: z.array(ToolReviewSelectionLabel).max(3).optional(),
+      /**
+       * Provider metadata for the whole selection, read when the review was
+       * prepared. Only the details page reads it; entries may be missing.
+       */
+      selectionLabels: z
+        .array(ToolReviewSelectionLabel)
+        .max(TOOL_REVIEW_SELECTION_LABELS_MAX)
+        .optional(),
+    })
+    .strict(),
+);
+export type ToolReviewContext = z.infer<typeof ToolReviewContext>;
+
+// Names are exact saved identities, never display labels. A name protected by
+// any reachable schema stays protected at every depth (conservative for sibling
+// properties with the same name). Never truncate this set and expose its tail.
+function schemaProtectedFields(root: Record<string, unknown>): string[] {
+  const protectedFields = new Set<string>();
+  const seen = new WeakMap<object, Set<string | undefined>>();
+  let visited = 0;
+  const object = (value: unknown): value is Record<string, unknown> =>
+    value !== null && typeof value === "object" && !Array.isArray(value);
+  const refuse = () => {
+    throw new Error("Tool review schema cannot be safely displayed");
+  };
+  const visit = (node: unknown, owner?: string, depth = 0): void => {
+    if (!object(node)) return;
+    const owners = seen.get(node) ?? new Set<string | undefined>();
+    if (owners.has(owner)) return;
+    owners.add(owner);
+    seen.set(node, owners);
+    if (++visited > 20000 || depth > 100) refuse();
+    if (node.$dynamicRef !== undefined || node.$recursiveRef !== undefined) refuse();
+    // A nested resource identifier changes the resolution base of local refs.
+    if (node !== root && node.$id !== undefined) refuse();
+    if (node.writeOnly === true) {
+      if (owner === undefined) refuse();
+      protectedFields.add(owner!);
+    }
+    if (node.contentSchema !== undefined) {
+      // Encoded content is one opaque argument value. Nested privacy annotations
+      // cannot be applied to its string without decoding and changing the bytes.
+      if (owner === undefined) refuse();
+      protectedFields.add(owner!);
+    }
+    if (typeof node.$ref === "string") {
+      if (node.$ref !== "#" && !node.$ref.startsWith("#/")) refuse();
+      let target: unknown = root;
+      if (node.$ref !== "#")
+        for (const part of node.$ref.slice(2).split("/")) {
+          const key = part.replaceAll("~1", "/").replaceAll("~0", "~");
+          if (!object(target) || !Object.hasOwn(target, key)) refuse();
+          target = (target as Record<string, unknown>)[key];
+        }
+      if (!object(target) && typeof target !== "boolean") refuse();
+      visit(target, owner, depth + 1);
+    }
+    if (object(node.properties))
+      for (const [key, schema] of Object.entries(node.properties)) visit(schema, key, depth + 1);
+    for (const key of [
+      "items",
+      "additionalItems",
+      "additionalProperties",
+      "unevaluatedItems",
+      "unevaluatedProperties",
+      "contains",
+      "if",
+      "then",
+      "else",
+      "not",
+    ]) {
+      const value = node[key];
+      if (Array.isArray(value)) for (const child of value) visit(child, owner, depth + 1);
+      else visit(value, owner, depth + 1);
+    }
+    for (const key of ["allOf", "anyOf", "oneOf", "prefixItems"]) {
+      if (Array.isArray(node[key])) for (const child of node[key]) visit(child, owner, depth + 1);
+    }
+    // A pattern cannot be represented by this exact-name privacy contract.
+    // Protect its containing object if any branch declares a private value.
+    for (const key of ["patternProperties", "dependentSchemas", "dependencies"]) {
+      if (object(node[key]))
+        for (const child of Object.values(node[key])) visit(child, owner, depth + 1);
+    }
+  };
+  try {
+    visit(root);
+    return [...protectedFields];
+  } catch {
+    // Review formatting must not change Allow/Block execution. Unsupported
+    // schema privacy is conservative: display no values, never guess a key.
+    return ["*"];
+  }
+}
+
+export function toolReviewContextFromSchema(
+  inputSchema: unknown,
+  hints: Omit<ToolReviewContext, "fieldLabels" | "protectedFields">,
+): ToolReviewContext {
+  const schema =
+    inputSchema && typeof inputSchema === "object" ? (inputSchema as Record<string, unknown>) : {};
+  const properties =
+    schema.properties && typeof schema.properties === "object"
+      ? Object.entries(schema.properties)
+      : [];
+  const clean = (text: string) =>
+    text
+      .replaceAll("\u0000", "")
+      .replace(/\p{Surrogate}/gu, "�")
+      .slice(0, 256);
+  return {
+    kind: hints.kind,
+    ...(hints.title ? { title: clean(hints.title) } : {}),
+    ...(hints.accountLabel ? { accountLabel: clean(hints.accountLabel) } : {}),
+    fieldLabels: Object.fromEntries(
+      properties
+        .slice(0, 128)
+        .flatMap(([key, value]) =>
+          value && typeof value === "object" && typeof value.title === "string"
+            ? [[key, clean(value.title)]]
+            : [],
+        ),
+    ),
+    protectedFields: schemaProtectedFields(schema),
+  };
+}
+
+export const ToolReviewStatus = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    "pending",
+    "approved",
+    "executing",
+    "completed",
+    "partial",
+    "unknown",
+    "rejected",
+    "cancelled",
+    "expired",
+    "revoked",
+    "blocked",
+    "stale",
+    "failed",
+    "unavailable",
+  ]),
+);
+export type ToolReviewStatus = z.infer<typeof ToolReviewStatus>;
+export const ToolReviewField = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      path: primitives.string,
+      label: primitives.string,
+      preview: primitives.string,
+      count: z.number().int().nonnegative().optional(),
+      truncated: primitives.boolean,
+      protected: primitives.optionalBoolean,
+    })
+    .strict(),
+);
+export const ToolActionReview = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      version: z.literal(1),
+      id: primitives.string,
+      actionDigest: primitives.string,
+      revision: primitives.string,
+      status: ToolReviewStatus,
+      title: primitives.string,
+      accountLabel: z.string().optional(),
+      consequence: z.string().optional(),
+      effects: z.array(primitives.string),
+      selectionCount: z.number().int().nonnegative().optional(),
+      selectionKind: z.enum(["messages", "threads"]).optional(),
+      samples: ToolReviewContext.shape.samples,
+      fields: z.array(ToolReviewField),
+      moreFields: primitives.nonnegativeInteger,
+      reason: primitives.string,
+      createdAt: primitives.string,
+      updatedAt: primitives.string,
+      approveLabel: primitives.string,
+      availableActions: z.array(z.enum(["approve", "reject"])),
+      detailsAvailable: primitives.boolean,
+    })
+    .strict(),
+);
+export type ToolActionReview = z.infer<typeof ToolActionReview>;
+export const ToolReviewDetailsPage = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      version: z.literal(1),
+      id: primitives.string,
+      actionDigest: primitives.string,
+      path: primitives.string,
+      items: z.array(
+        z
+          .object({
+            label: primitives.string,
+            value: primitives.string,
+            /** A secondary line, such as a selected message's sender and identifier. */
+            detail: z.string().optional(),
+            path: z.string().optional(),
+            truncated: primitives.optionalBoolean,
+          })
+          .strict(),
+      ),
+      total: primitives.nonnegativeInteger,
+      nextOffset: z.number().int().nonnegative().nullable(),
+    })
+    .strict(),
+);
+export type ToolReviewDetailsPage = z.infer<typeof ToolReviewDetailsPage>;
+
+export {
+  decodeReviewArguments,
+  safeReviewValue,
+  toolReviewAction,
+  toolReviewDetails,
+  toolReviewFieldLabel,
+  toolReviewFields,
+} from "./tool-review-presentation";