@opengeni/contracts 3.1.0-canary.1 → 3.1.2

package/src/prepared-mcp-setup.ts

@@ -0,0 +1,189 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+const fieldId = /* @__PURE__ */ defineSchema(() =>
+  z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,63}$/),
+);
+const headerName = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .min(1)
+    .max(256)
+    .regex(/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/),
+);
+const headerPart = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .max(16_384)
+    .regex(/^[^\r\n\0]*$/),
+);
+
+/** Configuration is safe to retain; secret values enter only the protected
+ * Connect credential request, never this model-visible setup description. */
+export const PreparedMcpSetup = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      name: z.string().trim().min(1).max(256),
+      endpointUrl: z
+        .string()
+        .url()
+        .max(2048)
+        .refine((value) => {
+          try {
+            const url = new URL(value);
+            return (
+              url.protocol === "https:" &&
+              !url.username &&
+              !url.password &&
+              !url.search &&
+              !url.hash
+            );
+          } catch {
+            return false;
+          }
+        }, "Use an HTTPS endpoint without credentials, query parameters, or a fragment"),
+      headers: z
+        .array(
+          z.union([
+            z.object({ name: headerName, value: headerPart.min(1) }).strict(),
+            z
+              .object({
+                name: headerName,
+                secret: fieldId,
+                prefix: headerPart.optional(),
+                suffix: headerPart.optional(),
+              })
+              .strict(),
+          ]),
+        )
+        .min(1)
+        .max(32),
+      secretFields: z
+        .array(z.object({ id: fieldId, label: z.string().trim().min(1).max(256) }).strict())
+        .max(32),
+    })
+    .strict()
+    .superRefine((value, context) => {
+      const names = value.headers.map((header) => header.name.toLowerCase());
+      const ids = value.secretFields.map((field) => field.id);
+      if (new Set(names).size !== names.length)
+        context.addIssue({
+          code: "custom",
+          path: ["headers"],
+          message: "Header names must be unique",
+        });
+      if (new Set(ids).size !== ids.length)
+        context.addIssue({
+          code: "custom",
+          path: ["secretFields"],
+          message: "Secret field IDs must be unique",
+        });
+      const used = new Set(
+        value.headers.flatMap((header) => ("secret" in header ? [header.secret] : [])),
+      );
+      if (used.size !== ids.length || ids.some((id) => !used.has(id)))
+        context.addIssue({
+          code: "custom",
+          path: ["secretFields"],
+          message: "Declare exactly the secret fields used by the headers",
+        });
+      for (const [index, header] of value.headers.entries()) {
+        if (
+          "value" in header &&
+          ["authorization", "proxy-authorization", "cookie", "x-api-key", "api-key"].includes(
+            header.name.toLowerCase(),
+          )
+        )
+          context.addIssue({
+            code: "custom",
+            path: ["headers", index],
+            message: "Credential headers must reference a protected secret field",
+          });
+      }
+    }),
+);
+export type PreparedMcpSetup = z.infer<typeof PreparedMcpSetup>;
+
+/** A missing-key proposal retains configuration only. Ownership is explicit
+ * and the displayed identity must equal the destination actually configured. */
+export const CustomMcpSetupRequest = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      kind: z.literal("mcp"),
+      name: z.string().trim().min(1).max(256),
+      endpointUrl: z
+        .string()
+        .url()
+        .max(2048)
+        .refine((value) => {
+          try {
+            const url = new URL(value);
+            return (
+              url.protocol === "https:" &&
+              !url.username &&
+              !url.password &&
+              !url.hash &&
+              !url.search
+            );
+          } catch {
+            return false;
+          }
+        }),
+      rationale: z.string().trim().min(1).max(2000),
+      ownership: z.enum(["personal", "workspace"]).optional(),
+      mcpSetup: PreparedMcpSetup.optional(),
+    })
+    .strict()
+    .superRefine((value, context) => {
+      if (Boolean(value.ownership) !== Boolean(value.mcpSetup))
+        context.addIssue({ code: "custom", message: "Prepared setup requires explicit ownership" });
+      if (
+        value.mcpSetup &&
+        (value.name !== value.mcpSetup.name || value.endpointUrl !== value.mcpSetup.endpointUrl)
+      )
+        context.addIssue({
+          code: "custom",
+          message: "Prepared setup must match the displayed server",
+        });
+    }),
+);
+export type CustomMcpSetupRequest = z.infer<typeof CustomMcpSetupRequest>;
+
+/** Values are intentionally accepted separately. Errors name neither supplied
+ * values nor undeclared input keys, which may themselves contain credentials. */
+export function preparedMcpHeaders(
+  configuration: PreparedMcpSetup,
+  values: Readonly<Record<string, string>>,
+): Record<string, string> {
+  const setup = PreparedMcpSetup.parse(configuration);
+  const supplied = Object.keys(values);
+  if (
+    supplied.length !== setup.secretFields.length ||
+    setup.secretFields.some((field) => !Object.hasOwn(values, field.id)) ||
+    supplied.some((key) => {
+      const value = values[key];
+      return (
+        typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > 16_384 ||
+        /[\r\n\0]/.test(value)
+      );
+    })
+  )
+    throw new Error("Supply exactly the requested secret fields");
+  const headers: Record<string, string> = {};
+  for (const header of setup.headers) {
+    const value =
+      "value" in header
+        ? header.value
+        : `${header.prefix ?? ""}${values[header.secret]}${header.suffix ?? ""}`;
+    if (value.length > 16_384) throw new Error("Prepared credential header is too long");
+    Object.defineProperty(headers, header.name, {
+      value,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    });
+  }
+  return headers;
+}

package/src/product-analytics.ts

@@ -0,0 +1,261 @@
+import { defineSchema } from "./define-schema";
+import { z } from "zod";
+
+// Content-free product-analytics dimensions carried on durable facts and the
+// optional host export. Every value comes from a fixed list or from Opengeni's
+// own code-defined names. None of them is an authorization input, and none
+// may carry prompt text, tool arguments, customer names, tenant domains, or
+// operator-configured identifiers.
+
+/**
+ * The product surface through which a turn's request entered Opengeni.
+ *
+ * - `web`: the Opengeni web app (managed cookie or the local browser context).
+ * - `slack`: a Slack mention, command, DM, shortcut, thread reply, or reaction.
+ * - `api_key`: an API key or configured key, including the SDK and scripts.
+ * - `embedded`: a host that embeds Opengeni through signed delegation or an
+ *   organization key acting for an external user.
+ * - `scheduled`: a scheduled-task occurrence.
+ * - `agent`: another agent (a child session, an agent message, or Agent Steer).
+ * - `voice`: a realtime voice delegation or its end-of-call handoff.
+ * - `site`: a published workspace Site.
+ * - `automation`: an event-triggered automation run.
+ * - `mcp`: an external MCP client connected through workspace MCP OAuth.
+ * - `system`: Opengeni's own maintenance work with no human entry.
+ *
+ * Turns that no new request entered (goal continuations, child results,
+ * command results, wait timeouts, compaction) inherit the surface of the
+ * session's latest started turn. Null means no surface was captured: rows
+ * written before capture existed, or machine work in a session that has
+ * never started a turn with one.
+ */
+export const SESSION_TURN_SURFACES = [
+  "web",
+  "slack",
+  "api_key",
+  "embedded",
+  "scheduled",
+  "agent",
+  "voice",
+  "site",
+  "automation",
+  "mcp",
+  "system",
+] as const;
+export const SessionTurnSurface = /* @__PURE__ */ defineSchema(() => z.enum(SESSION_TURN_SURFACES));
+export type SessionTurnSurface = z.infer<typeof SessionTurnSurface>;
+
+/**
+ * Request header the first-party web console sends while its tab is visible
+ * and the person interacted with it in the last few minutes. The API records
+ * server-side presence (`opengeni_active_users`, `user.active`) only for
+ * canonical managed browser sessions carrying this exact value, so an idle open
+ * tab, background polling and stream re-authorization never count as activity.
+ * Analytics only: it never grants or narrows access.
+ */
+export const OPENGENI_USER_ACTIVITY_HEADER = "x-opengeni-user-activity";
+export const OPENGENI_USER_ACTIVITY_ACTIVE = "active";
+/** Interaction recency, in milliseconds, behind the activity header. */
+export const OPENGENI_USER_ACTIVITY_WINDOW_MS = 5 * 60_000;
+
+/** Parse a stored value; anything outside the fixed list is treated as absent. */
+export function sessionTurnSurfaceOrNull(value: unknown): SessionTurnSurface | null {
+  const parsed = SessionTurnSurface.safeParse(value);
+  return parsed.success ? parsed.data : null;
+}
+
+/**
+ * Model provider families exported for analytics. Reserved Opengeni provider
+ * ids pass through unchanged; every operator-configured registry provider is
+ * reported as `registry` so a deployment's own naming never leaves it.
+ * `opengeni_private.analytics_model_provider` (migration 0533) mirrors this.
+ */
+export const ANALYTICS_MODEL_PROVIDERS = [
+  "openai",
+  "azure",
+  "codex-subscription",
+  "supergrok-subscription",
+  "opengeni-gateway",
+  "workspace-gateway",
+  "organization-gateway",
+  "openrouter",
+  "workspace-openrouter",
+  "organization-openrouter",
+  "opper",
+  "workspace-opper",
+  "organization-opper",
+  "registry",
+] as const;
+export const AnalyticsModelProvider = /* @__PURE__ */ defineSchema(() =>
+  z.enum(ANALYTICS_MODEL_PROVIDERS),
+);
+export type AnalyticsModelProvider = z.infer<typeof AnalyticsModelProvider>;
+
+const RESERVED_ANALYTICS_MODEL_PROVIDERS: ReadonlySet<string> = new Set(
+  ANALYTICS_MODEL_PROVIDERS.filter((provider) => provider !== "registry"),
+);
+const REGISTRY_PROVIDER_ID = /^[A-Za-z0-9_-]{1,128}$/u;
+
+/** Map an accepted turn's execution-policy provider id to its analytics family. */
+export function analyticsModelProvider(
+  providerId: string | null | undefined,
+): AnalyticsModelProvider | null {
+  if (typeof providerId !== "string") return null;
+  if (RESERVED_ANALYTICS_MODEL_PROVIDERS.has(providerId)) {
+    return providerId as AnalyticsModelProvider;
+  }
+  return REGISTRY_PROVIDER_ID.test(providerId) ? "registry" : null;
+}
+
+/**
+ * Tool family on a tool-call fact: an Opengeni first-party tool name,
+ * `integration:<catalog domain>` for a reviewed catalog integration, or
+ * `custom` for any other MCP server (a workspace's own server, a self-hosted
+ * provider, or an unreviewed catalog entry). The domain part is limited to
+ * {@link TOOL_FAMILY_INTEGRATION_DOMAINS}, so a tenant's own host name is
+ * never exported.
+ */
+export const ToolFamily = /* @__PURE__ */ defineSchema(() =>
+  z
+    .string()
+    .max(160)
+    .regex(/^(?:custom|integration:[a-z0-9](?:[a-z0-9.-]{0,150}[a-z0-9])?|[a-z][a-z0-9_]{0,63})$/u),
+);
+export type ToolFamily = z.infer<typeof ToolFamily>;
+
+/**
+ * Reviewed integration domains that may appear as `integration:<domain>`:
+ * Opengeni's native provider domains plus the MCP host of every curated
+ * catalog entry (`data/catalog/curated.json`). A test keeps the curated part
+ * in sync. Any other domain is reported as `custom`.
+ */
+export const TOOL_FAMILY_INTEGRATION_DOMAINS = [
+  // Native provider domains.
+  "github.com",
+  "gitlab.com",
+  "dev.azure.com",
+  "slack.com",
+  "chatgpt.com",
+  "x.com",
+  "reddit.com",
+  "fiken.no",
+  "api.atlassian.com",
+  "googleapis.com",
+  // Curated catalog MCP hosts.
+  "gmailmcp.googleapis.com",
+  "mcp.slack.com",
+  "api.mobbin.com",
+  "mcp.linear.app",
+  "mcp.asana.com",
+  "mcp.stripe.com",
+  "mcp.figma.com",
+  "mcp.canva.com",
+  "mcp.sentry.dev",
+  "mcp.vercel.com",
+  "bindings.mcp.cloudflare.com",
+  "mcp.paypal.com",
+  "mcp.monday.com",
+  "mcp.airtable.com",
+  "mcp.zapier.com",
+  "mcp.webflow.com",
+  "mcp.supabase.com",
+  "mcp.clickup.com",
+  "mcp.calendly.com",
+  "mcp.box.com",
+  "mcp.dropbox.com",
+  "mcp.amplitude.com",
+  "mcp.posthog.com",
+  "mcp.pagerduty.com",
+  "mcp.apollo.io",
+  "api.ahrefs.com",
+  "mcp.semrush.com",
+  "mcp.frontapp.com",
+  "mcp.otter.ai",
+  "mcp.notion.com",
+  "mcp.hubspot.com",
+  "mcp.atlassian.com",
+  "mcp.intercom.com",
+] as const;
+
+const TOOL_FAMILY_INTEGRATION_DOMAIN_SET: ReadonlySet<string> = new Set(
+  TOOL_FAMILY_INTEGRATION_DOMAINS,
+);
+
+function normalizedDomain(value: string | null | undefined): string | null {
+  if (typeof value !== "string") return null;
+  const domain = value.trim().toLowerCase().replace(/\.$/u, "");
+  return domain.length > 0 ? domain : null;
+}
+
+/**
+ * Tool family for an MCP server that is not first-party. The first candidate
+ * domain on the reviewed list wins; otherwise the server is `custom`.
+ */
+export function integrationToolFamily(
+  candidateDomains: readonly (string | null | undefined)[],
+): ToolFamily {
+  for (const candidate of candidateDomains) {
+    const domain = normalizedDomain(candidate);
+    if (domain && TOOL_FAMILY_INTEGRATION_DOMAIN_SET.has(domain)) {
+      return `integration:${domain}`;
+    }
+  }
+  return "custom";
+}
+
+/**
+ * First-party tools the runtime exposes outside any MCP server: base sandbox
+ * and runtime tools, progressive-disclosure routers, media generation, and
+ * provider-hosted tool calls as the event stream names them.
+ */
+export const FIRST_PARTY_FUNCTION_TOOL_FAMILY_NAMES = [
+  "exec_command",
+  "write_stdin",
+  "view_image",
+  "apply_patch",
+  "skill_read",
+  "repository_skill_read",
+  "request_human_input",
+  "list_models",
+  "code_search",
+  "tool_search",
+  "tool_list",
+  "tool_invoke",
+  "generate_image",
+  "generate_video",
+  "get_video_generation_capabilities",
+  "computer_screenshot",
+  "web_search_call",
+  "image_generation_call",
+  "code_interpreter_call",
+  "file_search_call",
+  "computer_call",
+  "local_shell_call",
+  "shell_call",
+  "apply_patch_call",
+] as const;
+
+/**
+ * First-party tools served by in-process attempt definitions or the dedicated
+ * `files` server rather than the public `opengeni` MCP catalog.
+ */
+export const FIRST_PARTY_ATTEMPT_TOOL_FAMILY_NAMES = [
+  "skill_checkout",
+  "skill_publish",
+  "skill_install",
+  "skill_remove",
+  "skill_save",
+  "skill_search",
+  "operation_read",
+  "knowledge_source_fetch",
+  "knowledge_source_read",
+  "files_get_download_url",
+] as const;
+
+/**
+ * Opengeni's in-process integration tools that are not registry MCP servers,
+ * keyed by their catalog server id, with the provider domain they act on.
+ */
+export const IN_PROCESS_INTEGRATION_TOOL_FAMILY_DOMAINS: Readonly<Record<string, string>> = {
+  "google-drive-publishing": "googleapis.com",
+};

package/src/product-lifecycle-facts.ts

@@ -0,0 +1,122 @@
+/**
+ * Content-free per-person product lifecycle facts.
+ *
+ * Migration `0532_product_lifecycle_fact_export.sql` captures one fact per
+ * product change with row triggers and writes it to the durable host export as
+ * the `lifecycle_fact` kind; `0565_usage_analytics_presence_and_facts.sql` adds
+ * `user.active`, `credits.granted` and `connection.revoked`. Every value is drawn from a fixed list; the
+ * database function `opengeni_private.product_lifecycle_fact_valid` enforces
+ * the same lists and a test keeps the two copies identical.
+ */
+
+/**
+ * Closed class of a positive credit grant (`grant` or `manual_credit_grant`
+ * ledger row). `opengeni_private.credit_grant_class` mirrors this mapping:
+ * - `signup_trial`: the one-time verified-signup trial (source `verified_signup_trial`).
+ * - `coupon`: a fully discounted Stripe checkout (source `stripe_checkout_coupon`).
+ * - `manual`: an operator grant (`manual_credit_grant` or source `operator_adjustment`).
+ * - `other`: any other grant source.
+ */
+export const CREDIT_GRANT_CLASSES = ["signup_trial", "coupon", "manual", "other"] as const;
+export type CreditGrantClass = (typeof CREDIT_GRANT_CLASSES)[number];
+
+const CONNECTION_PROVIDER_CLASSES = [
+  "slack",
+  "github",
+  "gitlab",
+  "azure_devops",
+  "bitbucket",
+  "google",
+  "microsoft",
+  "linear",
+  "atlassian",
+  "notion",
+  "supabase",
+  "datadog",
+  "posthog",
+  "openai",
+  "x",
+  "other",
+] as const;
+
+/** Each fact type and the fixed values its `attribute` may carry. */
+export const PRODUCT_LIFECYCLE_FACT_ATTRIBUTES = {
+  /** A managed account was created. Attribute: first sign-in method. */
+  "auth.sign_up": ["email", "google", "github", "other"],
+  /**
+   * The account email became verified: by the verification link, or at
+   * creation when a social provider already verified it.
+   */
+  "auth.email_verified": [],
+  /** A live sign-in session was created. Attribute: method of that session. */
+  "auth.sign_in": ["email", "google", "github", "other"],
+  /** An organization was created by self-service setup or as an additional one. */
+  "organization.setup": ["created", "additional"],
+  /** A model subscription or organization model provider was connected. */
+  "model.connected": [
+    "codex",
+    "supergrok",
+    "vercel_gateway",
+    "openrouter",
+    "anthropic",
+    "claude_subscription",
+    "opper",
+  ],
+  /** A credit top-up payment was granted. */
+  "credits.purchased": [],
+  /** Credits were granted without a purchase. Attribute: grant class. */
+  "credits.granted": CREDIT_GRANT_CLASSES,
+  /** An integration connection was created. Attribute: provider class. */
+  "connection.created": CONNECTION_PROVIDER_CLASSES,
+  /**
+   * An integration connection was revoked, or deleted while still live.
+   * Attribute: provider class, the same list as `connection.created`.
+   */
+  "connection.revoked": CONNECTION_PROVIDER_CLASSES,
+  "scheduled_task.created": [],
+  /** A catalog Skill was installed into a workspace. */
+  "skill.installed": [],
+  /** A Slack user was linked to an Opengeni user. */
+  "slack.user_linked": [],
+  /** A new Connected Machine was enrolled. */
+  "machine.enrolled": [],
+  /** A person became an active member of an organization that already had one. */
+  "member.joined": [],
+  /**
+   * A managed person was active in an authenticated browser session on a new
+   * UTC day: at most one fact per person per UTC day, with no organization.
+   */
+  "user.active": [],
+} as const satisfies Record<string, readonly string[]>;
+
+export type ProductLifecycleFactType = keyof typeof PRODUCT_LIFECYCLE_FACT_ATTRIBUTES;
+
+export const PRODUCT_LIFECYCLE_FACT_TYPES = Object.keys(
+  PRODUCT_LIFECYCLE_FACT_ATTRIBUTES,
+) as ProductLifecycleFactType[];
+
+/**
+ * What kind of subject caused the fact. Only `user` and `api_key` facts carry
+ * their opaque subject id; every other subject string is reduced to its kind
+ * because embedded hosts may put their own identifiers in it.
+ */
+export const PRODUCT_LIFECYCLE_SUBJECT_KINDS = [
+  "user",
+  "api_key",
+  "service",
+  "other",
+  "none",
+] as const;
+export type ProductLifecycleSubjectKind = (typeof PRODUCT_LIFECYCLE_SUBJECT_KINDS)[number];
+
+/** Pseudonymous subject ids that may leave the database. */
+export const PRODUCT_LIFECYCLE_SUBJECT_ID_PATTERN = /^(user|api_key):[A-Za-z0-9_-]{8,128}$/;
+
+export function isProductLifecycleFact(type: string, attribute: string | null): boolean {
+  if (!Object.hasOwn(PRODUCT_LIFECYCLE_FACT_ATTRIBUTES, type)) return false;
+  const allowed: readonly string[] =
+    PRODUCT_LIFECYCLE_FACT_ATTRIBUTES[type as ProductLifecycleFactType];
+  return allowed.length === 0
+    ? attribute === null
+    : attribute !== null && allowed.includes(attribute);
+}