@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/src/agent-instruction-changes.ts

@@ -1,98 +1,118 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 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 const AgentInstructionEditMode = /* @__PURE__ */ defineSchema(() =>
+  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",
-        });
+export const AgentInstructionSaveRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      operationId: z.uuid(),
+      target: WorkspaceInstructionPolicyTarget,
+      editMode: AgentInstructionEditMode,
+      content: primitives.string
+        .max(AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS)
+        .optional(),
+      oldText: primitives.nonEmptyString
+        .max(AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS)
+        .optional(),
+      newText: primitives.string
+        .max(AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS)
+        .optional(),
+      expectedCurrentRevisionId: z.uuid().nullable(),
+      expectedActivationVersion: primitives.nonnegativeInteger,
+      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.newText === undefined) {
+      if (value.content === undefined || value.content.trim().length === 0) {
         context.addIssue({
           code: "custom",
-          path: ["newText"],
-          message: "An exact edit requires newText (use an empty string to remove the text)",
+          path: ["content"],
+          message: "Append changes require non-empty content",
         });
       }
-      if (value.content !== undefined) {
+      if (value.oldText !== undefined || value.newText !== undefined) {
         context.addIssue({
           code: "custom",
-          path: ["content"],
-          message: "An exact edit uses oldText and newText, not content",
+          path: [value.oldText !== undefined ? "oldText" : "newText"],
+          message: "Append changes use content, not oldText or newText",
         });
       }
-      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();
+    })
+    .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 const AgentInstructionReviewRequest = /* @__PURE__ */ defineSchema(() =>
+  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 const AgentInstructionReceipt = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    operationId: z.uuid(),
+    revisionId: z.uuid(),
+    outcome: z.enum(["published", "pending", "rejected"]),
+    reviewBatchId: z.uuid().nullable(),
+    replayed: primitives.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 const AgentInstructionReviewItem = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    revisionId: z.uuid(),
+    content: primitives.string,
+    target: WorkspaceInstructionPolicyTarget,
+    reviewBatchId: z.uuid().nullable(),
+    sessionId: z.uuid().nullable(),
+    reason: primitives.string,
+    createdAt: primitives.string,
+  }),
+);
 export type AgentInstructionReviewItem = z.infer<typeof AgentInstructionReviewItem>;
-export const AgentInstructionReviewListResponse = z.object({
-  entries: z.array(AgentInstructionReviewItem),
-  nextCursor: z.string().nullable(),
-});
+export const AgentInstructionReviewListResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    entries: z.array(AgentInstructionReviewItem),
+    nextCursor: primitives.nullableString,
+  }),
+);
 export type AgentInstructionReviewListResponse = z.infer<typeof AgentInstructionReviewListResponse>;

package/src/agent-learning.ts

@@ -1,19 +1,27 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 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 const AgentLearningMode = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["automatic", "review_first", "off"]),
+);
 export type AgentLearningMode = z.infer<typeof AgentLearningMode>;
 
-export const AgentLearningCategory = z.enum(["knowledge", "instructions", "skills"]);
+export const AgentLearningCategory = /* @__PURE__ */ defineSchema(() =>
+  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 const AgentLearningDefaults = /* @__PURE__ */ defineSchema(() =>
+  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({
@@ -23,63 +31,79 @@ export const DEFAULT_AGENT_LEARNING: Readonly<AgentLearningDefaults> = Object.fr
 });
 
 /** An absent category inherits. `inherit` is a reset request, not persisted policy. */
-export const AgentLearningOverrides = AgentLearningDefaults.partial();
+export const AgentLearningOverrides = /* @__PURE__ */ defineSchema(() =>
+  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 const AgentLearningOverridePatch = /* @__PURE__ */ defineSchema(() =>
+  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 const AgentLearningContext = /* @__PURE__ */ defineSchema(() =>
+  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 const AgentLearningOwner = /* @__PURE__ */ defineSchema(() =>
+  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 const AgentLearningSettings = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      owner: AgentLearningOwner,
+      version: primitives.nonnegativeInteger,
+      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 const AgentLearningContextSettings = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      context: AgentLearningContext,
+      version: primitives.nonnegativeInteger,
+      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 const AgentLearningSettingsRecord = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    ownerKey: primitives.string,
+    contextKey: primitives.string,
+    version: primitives.nonnegativeInteger,
+    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 const AgentLearningOverrideRecord = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    contextKey: primitives.string,
+    version: primitives.positiveInteger,
+    settings: AgentLearningOverrides,
+    updatedAt: primitives.string,
+    label: primitives.string,
+  }),
+);
 export type AgentLearningOverrideRecord = z.infer<typeof AgentLearningOverrideRecord>;
 export type SaveAgentLearningSettingsRequest = {
   scope: "workspace" | "personal";
@@ -89,19 +113,23 @@ export type SaveAgentLearningSettingsRequest = {
   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 const AgentLearningEffectiveCategory = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      mode: AgentLearningMode,
+      inherited: primitives.boolean,
+    })
+    .strict(),
+);
+export const AgentLearningEffectivePolicy = /* @__PURE__ */ defineSchema(() =>
+  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. */
@@ -141,7 +169,7 @@ export function agentLearningDefaultsFromLegacy(input: {
 }): AgentLearningDefaults {
   const parsed = z
     .object({
-      memoryEnabled: z.boolean().optional(),
+      memoryEnabled: primitives.optionalBoolean,
       workspaceMode: z.enum(["off", "suggest", "automatic"]).optional(),
     })
     .strict()

package/src/agent-topology.ts

@@ -1,3 +1,5 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
 import {
@@ -8,62 +10,66 @@ import {
 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
+export const AgentTopologySession = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    id: primitives.uuid,
+    title: primitives.nullableString,
+    titleTruncated: primitives.boolean,
+    parentSessionId: primitives.nullableUuid,
+    rootSessionId: primitives.uuid,
+    nestedAgentDepth: NestedAgentDepthValue,
+    ancestorPath: z.array(
+      z.object({
+        id: primitives.uuid,
+        title: primitives.nullableString,
+        titleTruncated: primitives.boolean,
+      }),
+    ),
+    status: SessionStatus,
+    goal: z
       .object({
-        kind: z.enum(["session", "workspace"]),
-        sessionId: z.string().uuid().optional(),
-        displayName: z.string(),
-        displayNameTruncated: z.boolean(),
+        status: SessionGoalStatus,
+        summary: primitives.string,
+        summaryTruncated: primitives.boolean,
       })
       .nullable(),
+    pause: z.object({
+      state: z.enum(["active", "paused"]),
+      additionalBlockerCount: primitives.nonnegativeInteger,
+      source: z
+        .object({
+          kind: z.enum(["session", "workspace"]),
+          sessionId: primitives.optionalUuid,
+          displayName: primitives.string,
+          displayNameTruncated: primitives.boolean,
+        })
+        .nullable(),
+    }),
+    children: z.object({
+      directChildren: primitives.nonnegativeInteger,
+      totalDescendants: primitives.nonnegativeInteger,
+      runningDescendants: primitives.nonnegativeInteger,
+      queuedDescendants: primitives.nonnegativeInteger,
+      attentionDescendants: primitives.nonnegativeInteger,
+      pausedDescendants: primitives.nonnegativeInteger,
+      failedDescendants: primitives.nonnegativeInteger,
+      truncated: primitives.boolean,
+    }),
+    relatedWork: WorkDiscoveryProjection,
+    createdAt: primitives.string,
+    updatedAt: primitives.string,
   }),
-  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 const AgentTopologyPageResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    sessions: z.array(AgentTopologySession),
+    total: primitives.nonnegativeInteger,
+    hasMore: primitives.boolean,
+    /** Operator rollout decision for human advisory presentation. */
+    humanAdvisoriesEnabled: primitives.optionalBoolean,
+    nextCursor: primitives.nullableString,
+  }),
+);
 export type AgentTopologyPageResponse = z.infer<typeof AgentTopologyPageResponse>;

package/src/api-key-presets.ts

@@ -0,0 +1,28 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+import type { Permission } from "./permissions";
+
+/** Optional creation alias for the developer_setup organization access tier. */
+export const OrganizationApiKeyPreset = /* @__PURE__ */ defineSchema(() =>
+  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/app-action-catalog-types.ts

@@ -0,0 +1,32 @@
+export type ActionCatalogEntry = {
+  /** Stable name an agent calls: the SDK method ("listSessions"), else "METHOD /path". */
+  id: string;
+  method: string;
+  path: string;
+  /** Contract schema names for the JSON body and response, when known. */
+  request: string[];
+  /**
+   * Query parameter names the route reads, from its handler. Set only when it
+   * reads any; describe lists them so a caller can filter and page.
+   */
+  query?: string[];
+  response: string[];
+  /**
+   * Why no MCP caller can complete this action: it needs the person's own
+   * Opengeni browser session. Set only on such actions; the server hides them.
+   */
+  browserOnly?: string;
+  /**
+   * Where the action carries a key, password, token or other secret: field
+   * paths ("request.apiKey", "response.token") or a route reason, derived by
+   * the catalog generator. Without full access a chat leaves it to the app.
+   */
+  secretFields?: string[];
+  /**
+   * The workspace permission the route checks before anything else, from its
+   * handler's first access check. Set only when the handler shows one; the
+   * route's own checks still decide. Lets a caller leave out actions a person
+   * can never run.
+   */
+  permission?: string;
+};