@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/src/bots.ts

@@ -0,0 +1,238 @@
+import { z } from "zod";
+import { defineSchema } from "./define-schema";
+
+/**
+ * Bots. A bot is an ordinary long-lived chat: its title is its name, and any
+ * chat may also carry a short description and an avatar. Both are display
+ * metadata for people; they never reach the model. People and the chat's own
+ * agent may change them at any time.
+ *
+ * A bot template is where a new bot starts: a name, description and avatar,
+ * plus setup instructions that become the new chat's first message. The
+ * agent then sets itself up with its ordinary tools (Skills, connections,
+ * schedules, machines) and the chat simply continues. A workspace keeps the
+ * templates its people and agents save.
+ *
+ * This module must not import `./index`.
+ */
+
+export const SESSION_DESCRIPTION_MAX_LENGTH = 280;
+
+/** Curated icon names (the web maps each to a Lucide glyph). */
+export const SESSION_AVATAR_ICONS = [
+  "bot",
+  "bug",
+  "mail",
+  "git-pull-request",
+  "telescope",
+  "chart-line",
+  "file-text",
+  "shield-check",
+  "wrench",
+  "search",
+  "calendar-clock",
+  "megaphone",
+  "receipt",
+  "rocket",
+  "database",
+  "code",
+  "briefcase",
+  "book-open",
+  "flask-conical",
+  "globe",
+  "headset",
+  "pen-tool",
+  "users",
+  "sparkles",
+] as const;
+export const SessionAvatarIcon = /* @__PURE__ */ defineSchema(() => z.enum(SESSION_AVATAR_ICONS));
+export type SessionAvatarIcon = z.infer<typeof SessionAvatarIcon>;
+
+const SESSION_AVATAR_EMOJI_PATTERN = /\p{Extended_Pictographic}|\p{Regional_Indicator}/u;
+
+/** True when `value` is exactly one user-perceived character that is an emoji. */
+export function isSingleSessionAvatarEmoji(value: string): boolean {
+  if (!SESSION_AVATAR_EMOJI_PATTERN.test(value)) return false;
+  const segmenter =
+    typeof Intl !== "undefined" && "Segmenter" in Intl
+      ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+      : null;
+  if (!segmenter) return [...value].length <= 8;
+  let count = 0;
+  for (const _segment of segmenter.segment(value)) {
+    count += 1;
+    if (count > 1) return false;
+  }
+  return count === 1;
+}
+
+/** Hue (0-359) of the avatar tile's background. */
+export const SessionAvatarHue = /* @__PURE__ */ defineSchema(() =>
+  z.number().int().min(0).max(359),
+);
+
+/**
+ * What a chat looks like in lists and its header. `image` names an image file
+ * in the workspace (for example one the agent generated); each viewer opens it
+ * with their own access, and anyone who cannot sees the chat's initials.
+ */
+export const SessionAvatar = /* @__PURE__ */ defineSchema(() =>
+  z.discriminatedUnion("kind", [
+    z
+      .object({
+        kind: z.literal("emoji"),
+        emoji: z.string().min(1).max(32).refine(isSingleSessionAvatarEmoji, {
+          message: "emoji must be a single emoji",
+        }),
+        hue: SessionAvatarHue,
+      })
+      .strict(),
+    z
+      .object({
+        kind: z.literal("icon"),
+        icon: SessionAvatarIcon,
+        hue: SessionAvatarHue,
+      })
+      .strict(),
+    z
+      .object({
+        kind: z.literal("letters"),
+        letters: z.string().regex(/^[\p{L}\p{N}]{1,2}$/u, {
+          message: "letters must be one or two letters or digits",
+        }),
+        hue: SessionAvatarHue,
+      })
+      .strict(),
+    z.object({ kind: z.literal("image"), artifactId: z.string().uuid() }).strict(),
+  ]),
+);
+export type SessionAvatar = z.infer<typeof SessionAvatar>;
+
+/** An avatar a file can carry to another workspace: anything but an image. */
+export const PortableSessionAvatar = /* @__PURE__ */ defineSchema(() =>
+  SessionAvatar.refine((avatar) => avatar.kind !== "image", {
+    message: "an image avatar stays in its workspace",
+  }),
+);
+
+/** Stored descriptions are trimmed; an empty one is no description. */
+export const SessionDescription = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .trim()
+    .max(SESSION_DESCRIPTION_MAX_LENGTH)
+    .transform((value) => (value.length > 0 ? value : null)),
+);
+
+// --- Bot templates --------------------------------------------------------
+
+export const BOT_TEMPLATE_NAME_MAX_LENGTH = 120;
+export const BOT_TEMPLATE_SETUP_INSTRUCTIONS_MAX_LENGTH = 20_000;
+/** Saved templates a workspace keeps; saving another past this is refused. */
+export const BOT_TEMPLATES_PER_WORKSPACE_MAX = 200;
+
+const Uuid = /* @__PURE__ */ defineSchema(() => z.string().uuid());
+const BotTemplateName = /* @__PURE__ */ defineSchema(() =>
+  z.string().trim().min(1).max(BOT_TEMPLATE_NAME_MAX_LENGTH),
+);
+const BotTemplateDescription = /* @__PURE__ */ defineSchema(() =>
+  z.string().trim().max(SESSION_DESCRIPTION_MAX_LENGTH),
+);
+/** The new chat's first message: what the agent does to set itself up. */
+const BotTemplateSetupInstructions = /* @__PURE__ */ defineSchema(() =>
+  z.string().trim().min(1).max(BOT_TEMPLATE_SETUP_INSTRUCTIONS_MAX_LENGTH),
+);
+
+/** A template saved in a workspace. */
+export const WorkspaceBotTemplate = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    id: Uuid,
+    workspaceId: Uuid,
+    name: z.string(),
+    description: z.string(),
+    avatar: SessionAvatar.nullable(),
+    setupInstructions: z.string(),
+    /** The chat it was saved from, when it was saved from one. */
+    sourceSessionId: Uuid.nullable(),
+    /** Who saved it; null when a workspace-level caller did. */
+    createdBySubjectId: z.string().nullable(),
+    /** `manage`: the reader may rename, change or delete it. */
+    viewerAccess: z.enum(["manage", "use"]),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+  }),
+);
+export type WorkspaceBotTemplate = z.output<typeof WorkspaceBotTemplate>;
+
+export const CreateBotTemplateRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      name: BotTemplateName,
+      description: BotTemplateDescription.default(""),
+      avatar: SessionAvatar.nullable().default(null),
+      setupInstructions: BotTemplateSetupInstructions,
+      sourceSessionId: Uuid.nullable().default(null),
+    })
+    .strict(),
+);
+export type CreateBotTemplateRequest = z.input<typeof CreateBotTemplateRequest>;
+export type ParsedCreateBotTemplateRequest = z.output<typeof CreateBotTemplateRequest>;
+
+/** Changes only what it names. */
+export const UpdateBotTemplateRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      name: BotTemplateName.optional(),
+      description: BotTemplateDescription.optional(),
+      avatar: SessionAvatar.nullable().optional(),
+      setupInstructions: BotTemplateSetupInstructions.optional(),
+    })
+    .strict(),
+);
+export type UpdateBotTemplateRequest = z.input<typeof UpdateBotTemplateRequest>;
+export type ParsedUpdateBotTemplateRequest = z.output<typeof UpdateBotTemplateRequest>;
+
+export const ListBotTemplatesResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ templates: z.array(WorkspaceBotTemplate) }),
+);
+export type ListBotTemplatesResponse = z.output<typeof ListBotTemplatesResponse>;
+
+export const BotTemplateResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({ template: WorkspaceBotTemplate }),
+);
+export type BotTemplateResponse = z.output<typeof BotTemplateResponse>;
+
+export const BOT_TEMPLATE_FILE_FORMAT = "opengeni.bot-template";
+
+/**
+ * A template as a file, to share outside its workspace. It carries no ids,
+ * owner or image: importing it saves a new template in the importer's
+ * workspace, and an image avatar becomes the name's initials.
+ */
+export const BotTemplateFile = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      format: z.literal(BOT_TEMPLATE_FILE_FORMAT),
+      version: z.literal(1),
+      name: BotTemplateName,
+      description: BotTemplateDescription.default(""),
+      avatar: PortableSessionAvatar.nullable().default(null),
+      setupInstructions: BotTemplateSetupInstructions,
+    })
+    .strict(),
+);
+export type BotTemplateFile = z.input<typeof BotTemplateFile>;
+
+/** The file for a template; an image avatar is dropped (see {@link BotTemplateFile}). */
+export function botTemplateFile(
+  template: Pick<WorkspaceBotTemplate, "name" | "description" | "avatar" | "setupInstructions">,
+): z.output<typeof BotTemplateFile> {
+  return {
+    format: BOT_TEMPLATE_FILE_FORMAT,
+    version: 1,
+    name: template.name,
+    description: template.description,
+    avatar: template.avatar && template.avatar.kind !== "image" ? template.avatar : null,
+    setupInstructions: template.setupInstructions,
+  };
+}

package/src/bundled-skills.ts

@@ -1,36 +1,93 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
-export const BundledSkillId = z.enum([
+/**
+ * Ids are permanent. The product-named ids on the left were renamed to
+ * neutral ones so embedding products never show another product's name to
+ * their agents. They stay accepted in requests and stored selections, and
+ * every selection resolves them to the current id.
+ */
+export const LEGACY_BUNDLED_SKILL_IDS = {
+  "builtin:opengeni-visualize": "builtin:visualize",
+  "builtin:opengeni-skills": "builtin:skill-management",
+  "builtin:opengeni-projects": "builtin:projects",
+  "builtin:opengeni-schedules": "builtin:schedules",
+  "builtin:opengeni-documents": "builtin:documents",
+  "builtin:opengeni-spreadsheets": "builtin:spreadsheets",
+  "builtin:opengeni-presentations": "builtin:presentations",
+  "builtin:opengeni-sites": "builtin:sites",
+  "builtin:opengeni-video-generation": "builtin:video-generation",
+  "builtin:opengeni-secrets": "builtin:secrets",
+} as const;
+const CURRENT_BUNDLED_SKILL_IDS = [
   "builtin:opengeni-help",
   "builtin:opengeni-client",
-  "builtin:opengeni-visualize",
+  "builtin:visualize",
   "builtin:document-parsing",
-  "builtin:opengeni-skills",
-  "builtin:opengeni-projects",
-  "builtin:opengeni-documents",
-  "builtin:opengeni-spreadsheets",
-  "builtin:opengeni-presentations",
-  "builtin:opengeni-sites",
-  "builtin:opengeni-video-generation",
-]);
+  "builtin:skill-management",
+  "builtin:projects",
+  "builtin:schedules",
+  "builtin:event-triggers",
+  "builtin:documents",
+  "builtin:spreadsheets",
+  "builtin:presentations",
+  "builtin:sites",
+  "builtin:video-generation",
+  "builtin:secrets",
+] as const;
+type LegacyBundledSkillId = keyof typeof LEGACY_BUNDLED_SKILL_IDS;
+
+/** Every accepted id: the current ids, then the legacy ids they replaced. */
+export const BundledSkillId = /* @__PURE__ */ defineSchema(() =>
+  z.enum([
+    ...CURRENT_BUNDLED_SKILL_IDS,
+    ...(Object.keys(LEGACY_BUNDLED_SKILL_IDS) as LegacyBundledSkillId[]),
+  ]),
+);
 export type BundledSkillId = z.infer<typeof BundledSkillId>;
-export const BundledSkillSelection = z
-  .array(BundledSkillId)
-  .max(BundledSkillId.options.length)
-  .refine((ids) => new Set(ids).size === ids.length, "bundled Skill ids must be unique")
-  .transform((ids) => [...ids].sort());
+
+/** The current id for a bundled Skill id; a legacy id maps to its rename. */
+export function canonicalBundledSkillId<T extends string>(id: T): T | BundledSkillId {
+  return (LEGACY_BUNDLED_SKILL_IDS as Record<string, BundledSkillId>)[id] ?? id;
+}
+
+export const BundledSkillSelection = /* @__PURE__ */ defineSchema(() =>
+  z
+    .array(BundledSkillId)
+    .max(BundledSkillId.options.length)
+    .transform((ids) => ids.map((id) => canonicalBundledSkillId(id)))
+    .refine((ids) => new Set(ids).size === ids.length, "bundled Skill ids must be unique")
+    .transform((ids) => [...ids].sort()),
+);
 
 /** Undefined is defaults/inheritance; an explicit empty list disables bundles. */
 export function resolveBundledSkillSelection(
   requested: readonly BundledSkillId[] | undefined,
   parent: readonly BundledSkillId[] | undefined,
 ): BundledSkillId[] | undefined {
-  const selected = requested === undefined ? parent : requested;
-  if (parent !== undefined && selected?.some((id) => !parent.includes(id)))
+  const selected = (requested === undefined ? parent : requested)?.map((id) =>
+    canonicalBundledSkillId(id),
+  );
+  const allowed = parent?.map((id) => canonicalBundledSkillId(id));
+  if (allowed !== undefined && selected?.some((id) => !allowed.includes(id)))
     throw new Error("A child cannot widen its parent's bundled Skill selection");
   return selected === undefined ? undefined : BundledSkillSelection.parse(selected);
 }
 
+/**
+ * Freeze the defaults a session's agent configuration implies. An agent that
+ * starts from `capabilities: "none"` carries no bundled Opengeni guides unless
+ * the request lists them; an explicit list (including `[]`) is kept exactly,
+ * and `"all"` or legacy (null) configurations keep the bundled defaults.
+ */
+export function bundledSkillSelectionForAgentConfig(
+  selection: BundledSkillId[] | undefined,
+  agentConfig: { from: "all" | "none" } | null | undefined,
+): BundledSkillId[] | undefined {
+  return selection === undefined && agentConfig?.from === "none" ? [] : selection;
+}
+
 // Immutable session configuration, following the existing create-identity
 // metadata convention. Callers cannot set this through arbitrary metadata.
 const BUNDLED_SKILL_SELECTION_KEY = "_opengeni_bundled_skill_ids_v1";
@@ -50,8 +107,8 @@ export function withBundledSkillSelectionMetadata(
  * stored selection and never turns it back into defaults. Input stays strict,
  * and a value that is not a list of id strings still fails.
  */
-const StoredBundledSkillSelection = z.array(z.string());
-const knownBundledSkillIds: ReadonlySet<string> = new Set(BundledSkillId.options);
+const StoredBundledSkillSelection = /* @__PURE__ */ defineSchema(() => z.array(primitives.string));
+const knownBundledSkillIds: ReadonlySet<string> = new Set(CURRENT_BUNDLED_SKILL_IDS);
 /**
  * Exact stored selection for keyed create replay identity. Unlike the
  * tolerant read, it keeps ids this build does not know: a retry must match
@@ -65,8 +122,8 @@ export function bundledSkillSelectionFromMetadata(
 ): BundledSkillId[] | undefined {
   const value = metadata[BUNDLED_SKILL_SELECTION_KEY];
   if (value === undefined) return undefined;
-  const known = StoredBundledSkillSelection.parse(value).filter((id): id is BundledSkillId =>
-    knownBundledSkillIds.has(id),
-  );
+  const known = StoredBundledSkillSelection.parse(value)
+    .map((id) => canonicalBundledSkillId(id))
+    .filter((id): id is BundledSkillId => knownBundledSkillIds.has(id));
   return [...new Set(known)].sort();
 }

package/src/canonical-human-identities.ts

@@ -1,93 +1,96 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
-export const CanonicalHumanIdentityStatus = z.enum([
-  "active",
-  "recovery_required",
-  "disputed",
-  "disabled",
-]);
+export const CanonicalHumanIdentityStatus = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["active", "recovery_required", "disputed", "disabled"]),
+);
 export type CanonicalHumanIdentityStatus = z.infer<typeof CanonicalHumanIdentityStatus>;
 
-export const CanonicalHumanLoginBindingStatus = z.enum([
-  "active",
-  "recovery_pending",
-  "stale",
-  "disputed",
-  "revoked",
-]);
+export const CanonicalHumanLoginBindingStatus = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["active", "recovery_pending", "stale", "disputed", "revoked"]),
+);
 export type CanonicalHumanLoginBindingStatus = z.infer<typeof CanonicalHumanLoginBindingStatus>;
 
-export const CanonicalHumanRecoveryState = z.enum([
-  "ready",
-  "recovery_required",
-  "lost_factor",
-  "disputed",
-  "disabled",
-]);
+export const CanonicalHumanRecoveryState = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["ready", "recovery_required", "lost_factor", "disputed", "disabled"]),
+);
 export type CanonicalHumanRecoveryState = z.infer<typeof CanonicalHumanRecoveryState>;
 
-export const CanonicalHumanLoginBinding = z.object({
-  id: z.string().uuid(),
-  providerId: z.string().min(1).max(128),
-  providerAccountId: z.string().min(1).max(1024),
-  status: CanonicalHumanLoginBindingStatus,
-  revision: z.number().int().positive(),
-  verifiedAt: z.string().datetime(),
-  lastVerifiedAt: z.string().datetime(),
-  revokedAt: z.string().datetime().nullable(),
-  createdAt: z.string().datetime(),
-  updatedAt: z.string().datetime(),
-});
+export const CanonicalHumanLoginBinding = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    id: primitives.uuid,
+    providerId: z.string().min(1).max(128),
+    providerAccountId: z.string().min(1).max(1024),
+    status: CanonicalHumanLoginBindingStatus,
+    revision: primitives.positiveInteger,
+    verifiedAt: primitives.dateTime,
+    lastVerifiedAt: primitives.dateTime,
+    revokedAt: z.string().datetime().nullable(),
+    createdAt: primitives.dateTime,
+    updatedAt: primitives.dateTime,
+  }),
+);
 export type CanonicalHumanLoginBinding = z.infer<typeof CanonicalHumanLoginBinding>;
 
-export const CanonicalHumanIdentityProjection = z.object({
-  activeIdentity: z.object({
-    id: z.string().uuid(),
-    displayName: z.string().min(1).max(256),
-    status: CanonicalHumanIdentityStatus,
-    identityRevision: z.number().int().positive(),
-    authRevision: z.number().int().positive(),
-    activeLoginBindingId: z.string().uuid().nullable(),
-    recoveryState: CanonicalHumanRecoveryState,
-    createdAt: z.string().datetime(),
-    updatedAt: z.string().datetime(),
+export const CanonicalHumanIdentityProjection = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    activeIdentity: z.object({
+      id: primitives.uuid,
+      displayName: z.string().min(1).max(256),
+      status: CanonicalHumanIdentityStatus,
+      identityRevision: primitives.positiveInteger,
+      authRevision: primitives.positiveInteger,
+      activeLoginBindingId: primitives.nullableUuid,
+      recoveryState: CanonicalHumanRecoveryState,
+      createdAt: primitives.dateTime,
+      updatedAt: primitives.dateTime,
+    }),
+    loginBindings: z.array(CanonicalHumanLoginBinding).max(64),
   }),
-  loginBindings: z.array(CanonicalHumanLoginBinding).max(64),
-});
+);
 export type CanonicalHumanIdentityProjection = z.infer<typeof CanonicalHumanIdentityProjection>;
 
 const OperationFields = {
-  operationId: z.string().uuid().optional(),
-  expectedIdentityRevision: z.number().int().positive(),
-  reason: z.string().trim().min(1).max(512),
+  operationId: primitives.optionalUuid,
+  expectedIdentityRevision: primitives.positiveInteger,
+  reason: primitives.string.trim().min(1).max(512),
 } as const;
 
-export const LinkCanonicalHumanLoginBindingRequest = z.object({
-  ...OperationFields,
-  providerId: z.string().trim().min(1).max(128),
-  providerAccountId: z.string().trim().min(1).max(1024),
-});
+export const LinkCanonicalHumanLoginBindingRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    ...OperationFields,
+    providerId: primitives.string.trim().min(1).max(128),
+    providerAccountId: primitives.string.trim().min(1).max(1024),
+  }),
+);
 export type LinkCanonicalHumanLoginBindingRequest = z.infer<
   typeof LinkCanonicalHumanLoginBindingRequest
 >;
 
-export const CanonicalHumanBindingOperationRequest = z.object({
-  ...OperationFields,
-});
+export const CanonicalHumanBindingOperationRequest = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    ...OperationFields,
+  }),
+);
 export type CanonicalHumanBindingOperationRequest = z.infer<
   typeof CanonicalHumanBindingOperationRequest
 >;
 
-export const CanonicalHumanIdentityMutationOutcome = z.enum(["applied", "lost_factor", "disputed"]);
+export const CanonicalHumanIdentityMutationOutcome = /* @__PURE__ */ defineSchema(() =>
+  z.enum(["applied", "lost_factor", "disputed"]),
+);
 export type CanonicalHumanIdentityMutationOutcome = z.infer<
   typeof CanonicalHumanIdentityMutationOutcome
 >;
 
-export const CanonicalHumanIdentityMutationResponse = z.object({
-  outcome: CanonicalHumanIdentityMutationOutcome,
-  operationId: z.string().uuid(),
-  identity: CanonicalHumanIdentityProjection,
-});
+export const CanonicalHumanIdentityMutationResponse = /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    outcome: CanonicalHumanIdentityMutationOutcome,
+    operationId: primitives.uuid,
+    identity: CanonicalHumanIdentityProjection,
+  }),
+);
 export type CanonicalHumanIdentityMutationResponse = z.infer<
   typeof CanonicalHumanIdentityMutationResponse
 >;