@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/dist/prepared-mcp-setup.d.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+/** Configuration is safe to retain; secret values enter only the protected
+ * Connect credential request, never this model-visible setup description. */
+export declare const PreparedMcpSetup: z.ZodObject<{
+    name: z.ZodString;
+    endpointUrl: z.ZodString;
+    headers: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        name: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        name: z.ZodString;
+        secret: z.ZodString;
+        prefix: z.ZodOptional<z.ZodString>;
+        suffix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>]>>;
+    secretFields: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+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 declare const CustomMcpSetupRequest: z.ZodObject<{
+    kind: z.ZodLiteral<"mcp">;
+    name: z.ZodString;
+    endpointUrl: z.ZodString;
+    rationale: z.ZodString;
+    ownership: z.ZodOptional<z.ZodEnum<{
+        personal: "personal";
+        workspace: "workspace";
+    }>>;
+    mcpSetup: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        endpointUrl: z.ZodString;
+        headers: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            name: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            name: z.ZodString;
+            secret: z.ZodString;
+            prefix: z.ZodOptional<z.ZodString>;
+            suffix: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>>;
+        secretFields: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+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 declare function preparedMcpHeaders(configuration: PreparedMcpSetup, values: Readonly<Record<string, string>>): Record<string, string>;

package/dist/prepared-mcp-setup.js

@@ -0,0 +1,13 @@
+import {
+  CustomMcpSetupRequest,
+  PreparedMcpSetup,
+  preparedMcpHeaders
+} from "./chunk-6LAT33BH.js";
+import "./chunk-AQYDZUJV.js";
+import "./chunk-56SNIMDO.js";
+export {
+  CustomMcpSetupRequest,
+  PreparedMcpSetup,
+  preparedMcpHeaders
+};
+//# sourceMappingURL=prepared-mcp-setup.js.map

package/dist/prepared-mcp-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/presentation-artifact-commands.js

@@ -29,8 +29,8 @@ import {
   encodePresentationArtifactCommandBatch,
   encodePresentationArtifactQuery,
   encodePresentationArtifactQueryResponse
-} from "./chunk-D2HKF2EF.js";
-import "./chunk-MYBZRDTY.js";
+} from "./chunk-XP5M3IKT.js";
+import "./chunk-WQI7VNN4.js";
 export {
   PRESENTATION_ARTIFACT_COMMAND_MAX_BYTES,
   PRESENTATION_ARTIFACT_COMMAND_MAX_COMMANDS,

package/dist/presentation-artifact-query.js

@@ -29,8 +29,8 @@ import {
   encodePresentationArtifactCommandBatch,
   encodePresentationArtifactQuery,
   encodePresentationArtifactQueryResponse
-} from "./chunk-D2HKF2EF.js";
-import "./chunk-MYBZRDTY.js";
+} from "./chunk-XP5M3IKT.js";
+import "./chunk-WQI7VNN4.js";
 export {
   PRESENTATION_ARTIFACT_COMMAND_MAX_BYTES,
   PRESENTATION_ARTIFACT_COMMAND_MAX_COMMANDS,

package/dist/primitives.d.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+/**
+ * Reuse common validators instead of retaining thousands of identical Zod
+ * instances. These are ordinary eager schemas, not a validation cache. Zod's
+ * builder methods return derived schemas; attach field-specific metadata to a
+ * derived schema rather than mutating a shared primitive's registry entry.
+ */
+export declare const string: z.ZodString;
+export declare const boolean: z.ZodBoolean;
+export declare const uuid: z.ZodString;
+export declare const nonnegativeInteger: z.ZodNumber;
+export declare const positiveInteger: z.ZodNumber;
+export declare const nullableString: z.ZodNullable<z.ZodString>;
+export declare const nonEmptyString: z.ZodString;
+export declare const nullableUuid: z.ZodNullable<z.ZodString>;
+export declare const optionalBoolean: z.ZodOptional<z.ZodBoolean>;
+export declare const optionalUuid: z.ZodOptional<z.ZodString>;
+export declare const dateTime: z.ZodString;

package/dist/product-analytics.d.ts

@@ -1,11 +1,11 @@
 import { z } from "zod";
 /**
- * The product surface through which a turn's request entered OpenGeni.
+ * The product surface through which a turn's request entered Opengeni.
  *
- * - `web`: the OpenGeni web app (managed cookie or the local browser context).
+ * - `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
+ * - `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).
@@ -13,7 +13,7 @@ import { z } from "zod";
  * - `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.
+ * - `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
@@ -36,33 +36,50 @@ export declare const SessionTurnSurface: z.ZodEnum<{
     web: "web";
 }>;
 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 declare const OPENGENI_USER_ACTIVITY_HEADER = "x-opengeni-user-activity";
+export declare const OPENGENI_USER_ACTIVITY_ACTIVE = "active";
+/** Interaction recency, in milliseconds, behind the activity header. */
+export declare const OPENGENI_USER_ACTIVITY_WINDOW_MS: number;
 /** Parse a stored value; anything outside the fixed list is treated as absent. */
 export declare function sessionTurnSurfaceOrNull(value: unknown): SessionTurnSurface | null;
 /**
- * Model provider families exported for analytics. Reserved OpenGeni provider
+ * 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 declare const ANALYTICS_MODEL_PROVIDERS: readonly ["openai", "azure", "codex-subscription", "supergrok-subscription", "opengeni-gateway", "workspace-gateway", "organization-gateway", "openrouter", "workspace-openrouter", "organization-openrouter", "registry"];
+export declare const ANALYTICS_MODEL_PROVIDERS: readonly ["openai", "azure", "codex-subscription", "supergrok-subscription", "opengeni-gateway", "workspace-gateway", "organization-gateway", "openrouter", "workspace-openrouter", "organization-openrouter", "opper", "workspace-opper", "organization-opper", "organization-openai", "organization-azure-openai", "registry"];
 export declare const AnalyticsModelProvider: z.ZodEnum<{
     azure: "azure";
     "codex-subscription": "codex-subscription";
     openai: "openai";
     "opengeni-gateway": "opengeni-gateway";
     openrouter: "openrouter";
+    opper: "opper";
+    "organization-azure-openai": "organization-azure-openai";
     "organization-gateway": "organization-gateway";
+    "organization-openai": "organization-openai";
     "organization-openrouter": "organization-openrouter";
+    "organization-opper": "organization-opper";
     registry: "registry";
     "supergrok-subscription": "supergrok-subscription";
     "workspace-gateway": "workspace-gateway";
     "workspace-openrouter": "workspace-openrouter";
+    "workspace-opper": "workspace-opper";
 }>;
 export type AnalyticsModelProvider = z.infer<typeof AnalyticsModelProvider>;
 /** Map an accepted turn's execution-policy provider id to its analytics family. */
 export declare function analyticsModelProvider(providerId: string | null | undefined): AnalyticsModelProvider | null;
 /**
- * Tool family on a tool-call fact: an OpenGeni first-party tool name,
+ * 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
@@ -73,11 +90,11 @@ export declare const ToolFamily: z.ZodString;
 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
+ * 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 declare const TOOL_FAMILY_INTEGRATION_DOMAINS: readonly ["github.com", "gitlab.com", "dev.azure.com", "slack.com", "chatgpt.com", "x.com", "reddit.com", "fiken.no", "api.atlassian.com", "googleapis.com", "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"];
+export declare const TOOL_FAMILY_INTEGRATION_DOMAINS: readonly ["github.com", "gitlab.com", "dev.azure.com", "slack.com", "chatgpt.com", "x.com", "reddit.com", "fiken.no", "api.atlassian.com", "googleapis.com", "gmailmcp.googleapis.com", "drivemcp.googleapis.com", "calendarmcp.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"];
 /**
  * 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`.
@@ -95,7 +112,7 @@ export declare const FIRST_PARTY_FUNCTION_TOOL_FAMILY_NAMES: readonly ["exec_com
  */
 export declare const FIRST_PARTY_ATTEMPT_TOOL_FAMILY_NAMES: readonly ["skill_checkout", "skill_publish", "skill_install", "skill_remove", "skill_save", "skill_search", "operation_read", "knowledge_source_fetch", "knowledge_source_read", "files_get_download_url"];
 /**
- * OpenGeni's in-process integration tools that are not registry MCP servers,
+ * 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 declare const IN_PROCESS_INTEGRATION_TOOL_FAMILY_DOMAINS: Readonly<Record<string, string>>;

package/dist/product-lifecycle-facts.d.ts

@@ -3,10 +3,21 @@
  *
  * 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. Every value is drawn from a fixed list; the
+ * 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 declare const CREDIT_GRANT_CLASSES: readonly ["signup_trial", "coupon", "manual", "other"];
+export type CreditGrantClass = (typeof CREDIT_GRANT_CLASSES)[number];
 /** Each fact type and the fixed values its `attribute` may carry. */
 export declare const PRODUCT_LIFECYCLE_FACT_ATTRIBUTES: {
     /** A managed account was created. Attribute: first sign-in method. */
@@ -21,20 +32,32 @@ export declare const PRODUCT_LIFECYCLE_FACT_ATTRIBUTES: {
     /** An organization was created by self-service setup or as an additional one. */
     readonly "organization.setup": readonly ["created", "additional"];
     /** A model subscription or organization model provider was connected. */
-    readonly "model.connected": readonly ["codex", "supergrok", "vercel_gateway", "openrouter", "anthropic", "claude_subscription"];
+    readonly "model.connected": readonly ["codex", "supergrok", "vercel_gateway", "openrouter", "anthropic", "claude_subscription", "opper", "elevenlabs", "openai", "azure_openai"];
     /** A credit top-up payment was granted. */
     readonly "credits.purchased": readonly [];
+    /** Credits were granted without a purchase. Attribute: grant class. */
+    readonly "credits.granted": readonly ["signup_trial", "coupon", "manual", "other"];
     /** An integration connection was created. Attribute: provider class. */
     readonly "connection.created": readonly ["slack", "github", "gitlab", "azure_devops", "bitbucket", "google", "microsoft", "linear", "atlassian", "notion", "supabase", "datadog", "posthog", "openai", "x", "other"];
+    /**
+     * An integration connection was revoked, or deleted while still live.
+     * Attribute: provider class, the same list as `connection.created`.
+     */
+    readonly "connection.revoked": readonly ["slack", "github", "gitlab", "azure_devops", "bitbucket", "google", "microsoft", "linear", "atlassian", "notion", "supabase", "datadog", "posthog", "openai", "x", "other"];
     readonly "scheduled_task.created": readonly [];
     /** A catalog Skill was installed into a workspace. */
     readonly "skill.installed": readonly [];
-    /** A Slack user was linked to an OpenGeni user. */
+    /** A Slack user was linked to an Opengeni user. */
     readonly "slack.user_linked": readonly [];
     /** A new Connected Machine was enrolled. */
     readonly "machine.enrolled": readonly [];
     /** A person became an active member of an organization that already had one. */
     readonly "member.joined": readonly [];
+    /**
+     * 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.
+     */
+    readonly "user.active": readonly [];
 };
 export type ProductLifecycleFactType = keyof typeof PRODUCT_LIFECYCLE_FACT_ATTRIBUTES;
 export declare const PRODUCT_LIFECYCLE_FACT_TYPES: ProductLifecycleFactType[];

package/dist/prompt-cache-diagnostics.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Per-call prompt-cache diagnostics.
+ *
+ * A provider reads its prompt cache only for the longest byte-identical
+ * request prefix it has seen recently. When a call reads much less than the
+ * previous call in the same session, these diagnostics say which part of the
+ * request changed (tools, system prompt or history), whether the provider
+ * dropped signed thinking blocks, or whether time or the serving account
+ * explain it. The worker records the observation; the usage fact stores it
+ * with the warm-miss classification so production can alert per class.
+ *
+ * Fingerprints are truncated SHA-256 digests of the wire request. They never
+ * contain request text.
+ */
+/** Hex digest prefix length kept for each fingerprint component. */
+export declare const PROMPT_CACHE_DIGEST_HEX_LENGTH = 16;
+/**
+ * Fingerprint of one provider request, as sent on the wire. `history` holds
+ * chained digests of the first `n` history items at n = 1, 2, 4, 8, ... and at
+ * the full item count, so two requests can be compared at every shared
+ * checkpoint without storing per-item digests.
+ */
+export type PromptCacheRequestFingerprint = {
+    v: 1;
+    /** Tool definitions, cache markers removed. */
+    tools: string;
+    /** System prompt, excluding per-request billing metadata and cache markers. */
+    system: string;
+    /** Number of history units: message content blocks, or Responses input items. */
+    items: number;
+    history: Array<[number, string]>;
+};
+/** What the worker observed about one model call. */
+export type PromptCacheObservation = {
+    /** Signed thinking blocks the provider dropped before inference, by reason. */
+    thinkingBlocksDropped?: Record<string, number>;
+    request?: PromptCacheRequestFingerprint;
+};
+export declare const PROMPT_CACHE_WARM_MISS_CLASSES: readonly [
+/** The history was replaced (compaction or truncation); a miss is expected. */
+"context_replaced", "tools_changed", "system_changed", 
+/** An item the previous request already sent changed. */
+"history_rewritten", 
+/** The prefix was identical but the provider dropped signed thinking. */
+"thinking_dropped", "account_changed", 
+/** Long enough since the previous call that the cache may have expired. */
+"idle_gap", 
+/** Nothing observed explains the miss (provider eviction or routing). */
+"unexplained"];
+export type PromptCacheWarmMissClass = (typeof PROMPT_CACHE_WARM_MISS_CLASSES)[number];
+export type PromptCacheWarmMiss = {
+    class: PromptCacheWarmMissClass;
+    /** Tokens a warm cache should have served: the shorter of the two prompts. */
+    expectedCachedTokens: number;
+    previousSourceKey: string;
+    gapMs: number;
+    /** For history_rewritten: the first checkpoint whose items differ. */
+    divergedWithinItems?: number;
+};
+export type PromptCacheDiagnostics = PromptCacheObservation & {
+    warmMiss?: PromptCacheWarmMiss;
+};
+/** One recorded call, as the classifier needs it. */
+export type PromptCacheCallSample = {
+    sourceKey: string;
+    /** Whole prompt including cached tokens. */
+    inputTokens: number | null;
+    cachedTokens: number | null;
+    connectionId: string | null;
+    occurredAt: Date;
+    observation: PromptCacheObservation | null;
+};
+/** Calls further apart than this may have lost the cache to its TTL. */
+export declare const PROMPT_CACHE_IDLE_GAP_MS: number;
+/** Validate an observation from an untrusted boundary; invalid parts are dropped. */
+export declare function parsePromptCacheObservation(value: unknown): PromptCacheObservation | null;
+/** Total signed thinking blocks the provider dropped for this call. */
+export declare function promptCacheThinkingBlocksDropped(observation: PromptCacheObservation | null): number;
+/**
+ * The first history checkpoint, up to the shorter request, whose digests
+ * differ; null when every shared checkpoint matches.
+ */
+export declare function firstDivergentHistoryCheckpoint(previous: PromptCacheRequestFingerprint, current: PromptCacheRequestFingerprint): number | null;
+/**
+ * Classify a call that read much less prompt cache than the previous call of
+ * the same model in the same session made warm. Returns null when there is no
+ * baseline or the call read what a warm cache should serve.
+ *
+ * Causes the request itself proves (tools, system, history) win over effects
+ * (dropped thinking) and circumstances (account, time).
+ */
+export declare function classifyPromptCacheWarmMiss(previous: PromptCacheCallSample | null, current: PromptCacheCallSample): PromptCacheWarmMiss | null;