@opengeni/contracts 0.44.1 → 1.0.0

package/src/agent-instruction-changes.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS } from "./agent-authored-durable-text";
+import { KnowledgeEntryEvidence } from "./knowledge-entries";
+import { WorkspaceInstructionPolicyTarget } from "./workspace-instruction-policies";
+
+export const AgentInstructionEditMode = z.enum(["append", "edit"]);
+export type AgentInstructionEditMode = z.infer<typeof AgentInstructionEditMode>;
+
+export const AgentInstructionSaveRequest = z
+  .object({
+    operationId: z.uuid(),
+    target: WorkspaceInstructionPolicyTarget,
+    editMode: AgentInstructionEditMode,
+    content: z.string().max(AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS).optional(),
+    oldText: z.string().min(1).max(AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS).optional(),
+    newText: z.string().max(AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS).optional(),
+    expectedCurrentRevisionId: z.uuid().nullable(),
+    expectedActivationVersion: z.number().int().nonnegative(),
+    evidence: z.array(KnowledgeEntryEvidence).max(32).default([]),
+    reason: z.string().min(1).max(4096),
+  })
+  .superRefine((value, context) => {
+    if (value.editMode === "edit") {
+      if (value.oldText === undefined) {
+        context.addIssue({
+          code: "custom",
+          path: ["oldText"],
+          message: "An exact edit requires oldText",
+        });
+      }
+      if (value.newText === undefined) {
+        context.addIssue({
+          code: "custom",
+          path: ["newText"],
+          message: "An exact edit requires newText (use an empty string to remove the text)",
+        });
+      }
+      if (value.content !== undefined) {
+        context.addIssue({
+          code: "custom",
+          path: ["content"],
+          message: "An exact edit uses oldText and newText, not content",
+        });
+      }
+      return;
+    }
+    if (value.content === undefined || value.content.trim().length === 0) {
+      context.addIssue({
+        code: "custom",
+        path: ["content"],
+        message: "Append changes require non-empty content",
+      });
+    }
+    if (value.oldText !== undefined || value.newText !== undefined) {
+      context.addIssue({
+        code: "custom",
+        path: [value.oldText !== undefined ? "oldText" : "newText"],
+        message: "Append changes use content, not oldText or newText",
+      });
+    }
+  })
+  .strict();
+export type AgentInstructionSaveRequest = z.input<typeof AgentInstructionSaveRequest>;
+
+export const AgentInstructionReviewRequest = z
+  .object({
+    operationId: z.uuid(),
+    revisionId: z.uuid(),
+    decision: z.enum(["approve", "reject"]),
+    reason: z.string().min(1).max(4096),
+  })
+  .strict();
+export type AgentInstructionReviewRequest = z.infer<typeof AgentInstructionReviewRequest>;
+
+export const AgentInstructionReceipt = z.object({
+  operationId: z.uuid(),
+  revisionId: z.uuid(),
+  outcome: z.enum(["published", "pending", "rejected"]),
+  reviewBatchId: z.uuid().nullable(),
+  replayed: z.boolean(),
+});
+export type AgentInstructionReceipt = z.infer<typeof AgentInstructionReceipt>;
+
+export const AgentInstructionReviewItem = z.object({
+  revisionId: z.uuid(),
+  content: z.string(),
+  target: WorkspaceInstructionPolicyTarget,
+  reviewBatchId: z.uuid().nullable(),
+  sessionId: z.uuid().nullable(),
+  reason: z.string(),
+  createdAt: z.string(),
+});
+export type AgentInstructionReviewItem = z.infer<typeof AgentInstructionReviewItem>;
+export const AgentInstructionReviewListResponse = z.object({
+  entries: z.array(AgentInstructionReviewItem),
+  nextCursor: z.string().nullable(),
+});
+export type AgentInstructionReviewListResponse = z.infer<typeof AgentInstructionReviewListResponse>;

package/src/agent-learning.ts

@@ -0,0 +1,161 @@
+import { z } from "zod";
+
+/** Review controls publication. It never grants content or external-action authority. */
+export const AgentLearningMode = z.enum(["automatic", "review_first", "off"]);
+export type AgentLearningMode = z.infer<typeof AgentLearningMode>;
+
+export const AgentLearningCategory = z.enum(["knowledge", "instructions", "skills"]);
+export type AgentLearningCategory = z.infer<typeof AgentLearningCategory>;
+
+export const AgentLearningDefaults = z
+  .object({
+    knowledge: AgentLearningMode,
+    instructions: AgentLearningMode,
+    skills: AgentLearningMode,
+  })
+  .strict();
+export type AgentLearningDefaults = z.infer<typeof AgentLearningDefaults>;
+
+export const DEFAULT_AGENT_LEARNING: Readonly<AgentLearningDefaults> = Object.freeze({
+  knowledge: "automatic",
+  instructions: "automatic",
+  skills: "automatic",
+});
+
+/** An absent category inherits. `inherit` is a reset request, not persisted policy. */
+export const AgentLearningOverrides = AgentLearningDefaults.partial();
+export type AgentLearningOverrides = z.infer<typeof AgentLearningOverrides>;
+
+export const AgentLearningOverridePatch = z
+  .object({
+    knowledge: AgentLearningMode.or(z.literal("inherit")).optional(),
+    instructions: AgentLearningMode.or(z.literal("inherit")).optional(),
+    skills: AgentLearningMode.or(z.literal("inherit")).optional(),
+  })
+  .strict();
+export type AgentLearningOverridePatch = z.infer<typeof AgentLearningOverridePatch>;
+
+export const AgentLearningContext = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("chat"), id: z.uuid() }).strict(),
+  z.object({ kind: z.literal("scheduled_task"), id: z.uuid() }).strict(),
+]);
+export type AgentLearningContext = z.infer<typeof AgentLearningContext>;
+
+export const AgentLearningOwner = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("workspace"), workspaceId: z.uuid() }).strict(),
+  z.object({ kind: z.literal("personal"), subjectId: z.string().min(1).max(1024) }).strict(),
+]);
+export type AgentLearningOwner = z.infer<typeof AgentLearningOwner>;
+
+export const AgentLearningSettings = z
+  .object({
+    owner: AgentLearningOwner,
+    version: z.number().int().nonnegative(),
+    defaults: AgentLearningDefaults,
+  })
+  .strict();
+export type AgentLearningSettings = z.infer<typeof AgentLearningSettings>;
+
+export const AgentLearningContextSettings = z
+  .object({
+    context: AgentLearningContext,
+    version: z.number().int().nonnegative(),
+    overrides: AgentLearningOverrides,
+  })
+  .strict();
+export type AgentLearningContextSettings = z.infer<typeof AgentLearningContextSettings>;
+
+/** Versioned settings returned by both central and contextual editors. */
+export const AgentLearningSettingsRecord = z.object({
+  ownerKey: z.string(),
+  contextKey: z.string(),
+  version: z.number().int().nonnegative(),
+  settings: AgentLearningOverrides,
+});
+export type AgentLearningSettingsRecord = z.infer<typeof AgentLearningSettingsRecord>;
+export const AgentLearningOverrideRecord = z.object({
+  contextKey: z.string(),
+  version: z.number().int().positive(),
+  settings: AgentLearningOverrides,
+  updatedAt: z.string(),
+  label: z.string(),
+});
+export type AgentLearningOverrideRecord = z.infer<typeof AgentLearningOverrideRecord>;
+export type SaveAgentLearningSettingsRequest = {
+  scope: "workspace" | "personal";
+  source?: AgentLearningContext;
+  operationId: string;
+  expectedVersion: number;
+  settings: AgentLearningOverridePatch;
+};
+
+export const AgentLearningEffectiveCategory = z
+  .object({
+    mode: AgentLearningMode,
+    inherited: z.boolean(),
+  })
+  .strict();
+export const AgentLearningEffectivePolicy = z
+  .object({
+    knowledge: AgentLearningEffectiveCategory,
+    instructions: AgentLearningEffectiveCategory,
+    skills: AgentLearningEffectiveCategory,
+  })
+  .strict();
+export type AgentLearningEffectivePolicy = z.infer<typeof AgentLearningEffectivePolicy>;
+
+/** Apply only at an authorized settings boundary; this function confers no authority. */
+export function patchAgentLearningOverrides(
+  current: AgentLearningOverrides,
+  patch: AgentLearningOverridePatch,
+): AgentLearningOverrides {
+  const result = AgentLearningOverrides.parse(current);
+  const changes = AgentLearningOverridePatch.parse(patch);
+  for (const category of AgentLearningCategory.options) {
+    const value = changes[category];
+    if (value === "inherit") delete result[category];
+    else if (value !== undefined) result[category] = value;
+  }
+  return result;
+}
+
+/** Pure resolution over accepted settings. Runtime callers persist the resulting snapshot. */
+export function resolveAgentLearningPolicy(
+  defaults: AgentLearningDefaults,
+  overrides: AgentLearningOverrides,
+): AgentLearningEffectivePolicy {
+  const base = AgentLearningDefaults.parse(defaults);
+  const context = AgentLearningOverrides.parse(overrides);
+  return Object.fromEntries(
+    AgentLearningCategory.options.map((category) => [
+      category,
+      { mode: context[category] ?? base[category], inherited: context[category] === undefined },
+    ]),
+  ) as AgentLearningEffectivePolicy;
+}
+
+/** Migration adapter preserves explicit opt-outs and existing instruction/Skill choices. */
+export function agentLearningDefaultsFromLegacy(input: {
+  memoryEnabled?: boolean;
+  workspaceMode?: "off" | "suggest" | "automatic";
+}): AgentLearningDefaults {
+  const parsed = z
+    .object({
+      memoryEnabled: z.boolean().optional(),
+      workspaceMode: z.enum(["off", "suggest", "automatic"]).optional(),
+    })
+    .strict()
+    .parse(input);
+  const behavior = parsed.workspaceMode ?? "suggest";
+  return {
+    knowledge: parsed.memoryEnabled === false ? "off" : "automatic",
+    instructions: behavior === "suggest" ? "review_first" : behavior,
+    skills: behavior === "suggest" ? "review_first" : behavior,
+  };
+}
+
+/** Existing instruction and Skill lifecycles retain their native mode vocabulary. */
+export function agentLearningDestinationMode(mode: AgentLearningMode) {
+  const parsed = AgentLearningMode.parse(mode);
+  return parsed === "review_first" ? ("suggest" as const) : parsed;
+}

package/src/agent-topology.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+
+import {
+  NestedAgentDepthValue,
+  SessionGoalStatus,
+  SessionStatus,
+} from "./session-topology-primitives";
+import { WorkDiscoveryProjection } from "./work-claims";
+
+/** Compact, bounded session projection for workspace agent-topology browsers. */
+export const AgentTopologySession = z.object({
+  id: z.string().uuid(),
+  title: z.string().nullable(),
+  titleTruncated: z.boolean(),
+  parentSessionId: z.string().uuid().nullable(),
+  rootSessionId: z.string().uuid(),
+  nestedAgentDepth: NestedAgentDepthValue,
+  ancestorPath: z.array(
+    z.object({
+      id: z.string().uuid(),
+      title: z.string().nullable(),
+      titleTruncated: z.boolean(),
+    }),
+  ),
+  status: SessionStatus,
+  goal: z
+    .object({
+      status: SessionGoalStatus,
+      summary: z.string(),
+      summaryTruncated: z.boolean(),
+    })
+    .nullable(),
+  pause: z.object({
+    state: z.enum(["active", "paused"]),
+    additionalBlockerCount: z.number().int().nonnegative(),
+    source: z
+      .object({
+        kind: z.enum(["session", "workspace"]),
+        sessionId: z.string().uuid().optional(),
+        displayName: z.string(),
+        displayNameTruncated: z.boolean(),
+      })
+      .nullable(),
+  }),
+  children: z.object({
+    directChildren: z.number().int().nonnegative(),
+    totalDescendants: z.number().int().nonnegative(),
+    runningDescendants: z.number().int().nonnegative(),
+    queuedDescendants: z.number().int().nonnegative(),
+    attentionDescendants: z.number().int().nonnegative(),
+    pausedDescendants: z.number().int().nonnegative(),
+    failedDescendants: z.number().int().nonnegative(),
+    truncated: z.boolean(),
+  }),
+  relatedWork: WorkDiscoveryProjection,
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type AgentTopologySession = z.infer<typeof AgentTopologySession>;
+
+export const AgentTopologyPageResponse = z.object({
+  sessions: z.array(AgentTopologySession),
+  total: z.number().int().nonnegative(),
+  hasMore: z.boolean(),
+  /** Operator rollout decision for human advisory presentation. */
+  humanAdvisoriesEnabled: z.boolean().optional(),
+  nextCursor: z.string().nullable(),
+});
+export type AgentTopologyPageResponse = z.infer<typeof AgentTopologyPageResponse>;

package/src/allowance-refusal.ts

@@ -0,0 +1,81 @@
+import type { AllowanceExhaustedRefusal } from "./usage-allowances";
+
+const MESSAGE_MAX_UTF8_BYTES = 1_024;
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+/** Mirror the canonical offset datetime's calendar/time bounds without loading
+ * the schema runtime into synchronous browser/React Native session projection.
+ * Contract-parity tests guard this deliberately small, bounded wire leaf.
+ */
+function resetTimestamp(value: unknown): value is string | null {
+  if (value === null) return true;
+  if (typeof value !== "string" || value.length > 64) return false;
+  const parts =
+    /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])T(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$/.exec(
+      value,
+    );
+  if (!parts || !Number.isFinite(Date.parse(value))) return false;
+  const year = Number(parts[1]);
+  const month = Number(parts[2]);
+  const day = Number(parts[3]);
+  const leapYear = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+  const days = [31, leapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return day <= days[month - 1]!;
+}
+
+/** Select only public refusal fields, including from an API error's details.
+ * LimitDecision's allowed:false and transport/SQL diagnostics never cross out.
+ */
+export function parseAllowanceExhaustedRefusal(value: unknown): AllowanceExhaustedRefusal | null {
+  const source = record(value);
+  if (source?.code !== "allowance_exhausted") return null;
+  const fields = record(source.details) ?? source;
+  const scope = fields.scope;
+  const subjectId = scope === "member" ? fields.subjectId : undefined;
+  if (
+    typeof source.message !== "string" ||
+    (scope !== "workspace" && scope !== "member") ||
+    !resetTimestamp(fields.resetsAt) ||
+    (subjectId !== undefined &&
+      (typeof subjectId !== "string" ||
+        subjectId.length === 0 ||
+        subjectId.length > 1_024 ||
+        subjectId.includes("\0")))
+  ) {
+    return null;
+  }
+  const normalized = source.message
+    .slice(0, MESSAGE_MAX_UTF8_BYTES * 2)
+    .replace(/[\u0000-\u001f\u007f]+/g, " ")
+    .trim();
+  const bytes = new TextEncoder().encode(normalized.slice(0, MESSAGE_MAX_UTF8_BYTES * 2));
+  let end = Math.min(bytes.length, MESSAGE_MAX_UTF8_BYTES);
+  while (end > 0 && end < bytes.length && (bytes[end]! & 0xc0) === 0x80) end -= 1;
+  return {
+    code: "allowance_exhausted",
+    scope,
+    resetsAt: fields.resetsAt,
+    ...(typeof subjectId === "string" ? { subjectId } : {}),
+    message: new TextDecoder().decode(bytes.slice(0, end)).trim(),
+  };
+}
+
+/** Bounded, fixed remedies: a ceiling is not an exhausted billing source.
+ * Never interpolate arbitrary exception prose or a member identifier.
+ */
+export function allowanceExhaustedMessage(refusal: AllowanceExhaustedRefusal): string {
+  const remedy =
+    refusal.scope === "workspace"
+      ? "The workspace usage allowance is exhausted. An organization administrator or a full-access organization API key can raise the workspace ceiling or add an allowance grant."
+      : "The member usage allowance is exhausted. A workspace administrator or a full-access organization API key can adjust the member ceiling.";
+  const reset =
+    refusal.resetsAt === null
+      ? "This allowance has no automatic reset."
+      : `It resets at ${new Date(refusal.resetsAt).toISOString().slice(0, 16).replace("T", " ")} UTC.`;
+  return `${remedy} ${reset}`;
+}

package/src/analytics-consent-report.ts

@@ -0,0 +1,20 @@
+/**
+ * Wire grammar of the content-free analytics consent beacon
+ * (`POST /v1/analytics-consent`).
+ *
+ * When a person answers the web console's optional-analytics banner, the
+ * browser reports only the closed decision so the API can count choices in
+ * `opengeni_analytics_consent_total{decision}`. The count shows how much of
+ * the audience the consent-gated analytics providers never see. A report
+ * carries no identifier, URL, cookie, or user content, and the web client and
+ * the API route both validate against these exact values.
+ */
+export const ANALYTICS_CONSENT_PATH = "/v1/analytics-consent";
+
+export const ANALYTICS_CONSENT_DECISIONS = ["granted", "denied"] as const;
+export type AnalyticsConsentDecision = (typeof ANALYTICS_CONSENT_DECISIONS)[number];
+
+/** Largest accepted report body. A valid report is under 32 bytes. */
+export const ANALYTICS_CONSENT_REPORT_MAX_BYTES = 128;
+
+export type AnalyticsConsentReport = { decision: AnalyticsConsentDecision };

package/src/api-key-presets.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import type { Permission } from "./permissions";
+
+/** Optional creation alias for the developer_setup organization access tier. */
+export const OrganizationApiKeyPreset = z.enum(["developer_setup"]);
+export type OrganizationApiKeyPreset = z.infer<typeof OrganizationApiKeyPreset>;
+
+/**
+ * The current setup-route floor: workspace provisioning, configuration/cleanup,
+ * and explicit literal budget authority. workspace:admin also covers discovery and session/tool/
+ * schedule guards. It is broad authority, not setup-only, and never confers
+ * literal secrets:read. No account:admin, billing, or redundant read scopes.
+ */
+export const DEVELOPER_SETUP_API_KEY_PRESET = {
+  id: "developer_setup",
+  label: "Developer setup",
+  description:
+    "Set up shared workspaces, tools and budgets. Includes broad workspace administration and expires after 24 hours. Can't manage API keys.",
+  permissions: [
+    "workspace:create",
+    "workspace:admin",
+    "usage_allowances:manage",
+  ] satisfies Permission[],
+  defaultExpiryHours: 24,
+} as const;

package/src/artifact-catalog.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { RetainedArtifactReferenceSchema } from "./retained-output";
+
+export const ArtifactCatalogKind = z.enum([
+  "site",
+  "document",
+  "spreadsheet",
+  "presentation",
+  "image",
+  "file",
+]);
+export type ArtifactCatalogKind = z.infer<typeof ArtifactCatalogKind>;
+
+/** Metadata only: native domain IDs, never content, storage keys or credentials. */
+export const ArtifactCatalogItem = z
+  .object({
+    id: z.string().min(1).max(128),
+    kind: ArtifactCatalogKind,
+    title: z.string().min(1).max(1024),
+    createdAt: z.string().datetime({ offset: true }),
+    updatedAt: z.string().datetime({ offset: true }),
+    status: z.enum(["active", "archived"]),
+    sourceSessionId: z.string().uuid().optional(),
+    versionId: z.string().min(1).max(128).optional(),
+    file: RetainedArtifactReferenceSchema.optional(),
+    filename: z.string().max(1024).optional(),
+    contentType: z.string().max(127).optional(),
+    sizeBytes: z.number().int().nonnegative().safe().optional(),
+  })
+  .strict();
+export type ArtifactCatalogItem = z.infer<typeof ArtifactCatalogItem>;
+
+export const ArtifactCatalogListQuery = z
+  .object({
+    sourceSessionId: z.string().uuid().optional(),
+    q: z
+      .string()
+      .trim()
+      .max(200)
+      .refine((value) => !value.includes("\0"))
+      .optional(),
+    kind: ArtifactCatalogKind.optional(),
+    sort: z.enum(["updated", "newest", "title"]).default("updated"),
+    status: z.enum(["active", "archived"]).default("active"),
+    limit: z.coerce.number().int().min(1).max(100).default(50),
+    cursor: z.string().min(1).max(8192).optional(),
+  })
+  .strict();
+export type ArtifactCatalogListQuery = z.infer<typeof ArtifactCatalogListQuery>;
+export type ArtifactCatalogListOptions = Omit<z.input<typeof ArtifactCatalogListQuery>, "limit"> & {
+  limit?: number;
+};
+
+export const ArtifactCatalogListResponse = z
+  .object({
+    items: z.array(ArtifactCatalogItem).max(100),
+    nextCursor: z.string().max(8192).nullable(),
+  })
+  .strict();
+export type ArtifactCatalogListResponse = z.infer<typeof ArtifactCatalogListResponse>;