@opengeni/contracts 0.44.1 → 1.0.0

package/src/product-analytics.ts

@@ -0,0 +1,253 @@
+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 = 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",
+  "registry",
+] as const;
+export const AnalyticsModelProvider = 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 = 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,121 @@
+/**
+ * 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",
+  ],
+  /** 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);
+}

package/src/remember.ts

@@ -0,0 +1,243 @@
+import { z } from "zod";
+import {
+  AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
+  AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_TOO_LONG_MESSAGE,
+  AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS,
+  AGENT_AUTHORED_PREFERENCE_CONTENT_TOO_LONG_MESSAGE,
+} from "./agent-authored-durable-text";
+import {
+  CompanyBrainLearningDecisionSummary,
+  CompanyBrainLearningStepFailure,
+} from "./company-brain-governed-writes";
+import { GovernedLearningActivationDestination } from "./governed-learning-activation";
+import { HumanInputQuestion } from "./index";
+import {
+  PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS,
+  PREFERENCE_REGISTRY_TITLE_MAX_CHARS,
+  PreferenceRegistryStableKey,
+} from "./preference-registry";
+import { WorkspaceInstructionPolicyTarget } from "./workspace-instruction-policies";
+
+/**
+ * Explicit user-directed durable write ("remember X for this workspace").
+ *
+ * The lane is the Agent Knowledge area the content belongs to:
+ * - `preference`: a Ways-of-working preference (how agents should act);
+ * - `instruction_policy`: a mandatory workspace rule ("always"/"never");
+ * - `knowledge`: a company/product/people fact.
+ *
+ * v1 supports the workspace scope only. Personal and organization scopes are
+ * separate authorities that are not yet active for governed writes.
+ */
+export const RememberLane = z.enum(["preference", "instruction_policy", "knowledge"]);
+export type RememberLane = z.infer<typeof RememberLane>;
+
+export const RememberScope = z.enum(["workspace"]);
+export type RememberScope = z.infer<typeof RememberScope>;
+
+/**
+ * Ceiling for the Knowledge lane, which is retrieval evidence rather than
+ * always-composed prompt text. Other lanes have their own destination bounds:
+ * see `AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS` and
+ * `AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS`.
+ */
+export const REMEMBER_CONTENT_MAX_CHARS = 4_000;
+
+const rememberBase = {
+  operationId: z.string().uuid(),
+  scope: RememberScope.default("workspace"),
+  /** The exact user-directed content to remember, in the user's words. */
+  content: z.string().trim().min(1).max(REMEMBER_CONTENT_MAX_CHARS),
+  /** Why the agent believes the user asked for this to be remembered. */
+  reason: z.string().trim().min(1).max(4_096),
+};
+
+export const RememberRequest = z.discriminatedUnion("lane", [
+  z
+    .object({
+      ...rememberBase,
+      lane: z.literal("preference"),
+      // Only the short title/description descriptors are prompt-composed; the
+      // content is retrieved on demand, so this length is retrieval cost rather
+      // than standing prompt cost.
+      content: z
+        .string()
+        .trim()
+        .min(1)
+        .max(
+          AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS,
+          AGENT_AUTHORED_PREFERENCE_CONTENT_TOO_LONG_MESSAGE,
+        ),
+      stableKey: PreferenceRegistryStableKey,
+      title: z.string().trim().min(1).max(PREFERENCE_REGISTRY_TITLE_MAX_CHARS),
+      description: z
+        .string()
+        .trim()
+        .min(1)
+        .max(PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS),
+    })
+    .strict(),
+  z
+    .object({
+      ...rememberBase,
+      lane: z.literal("instruction_policy"),
+      // A mandatory rule is composed verbatim into the prompt of every session
+      // it applies to, for as long as it stays active. Its storage bound is
+      // shared with the human workspace-instruction editor.
+      content: z
+        .string()
+        .trim()
+        .min(1)
+        .max(
+          AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
+          AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_TOO_LONG_MESSAGE,
+        ),
+      target: WorkspaceInstructionPolicyTarget.default({
+        kind: "policy",
+        scope: "global",
+        roleKey: null,
+      }),
+    })
+    .strict(),
+  z
+    .object({
+      ...rememberBase,
+      lane: z.literal("knowledge"),
+      /** Short entity label the fact is about (company, product, person, team, ...). */
+      subject: z.string().trim().min(1).max(512),
+    })
+    .strict(),
+]);
+export type RememberRequest = z.infer<typeof RememberRequest>;
+
+/**
+ * Bound structured human-input question that authorizes a confirmed remember.
+ * The question id binds the exact confirmation target: the
+ * `knowledge_change_proposals` id for Ways-of-working lanes, or the
+ * `knowledge_claims` id for the Knowledge lane.
+ */
+export const REMEMBER_HUMAN_INPUT_SAVE_OPTION = "save" as const;
+export const REMEMBER_HUMAN_INPUT_SKIP_OPTION = "skip" as const;
+export function rememberHumanInputQuestionId(targetId: string): string {
+  return `remember:${targetId}`;
+}
+
+// z.lazy: this module is re-exported from ./index, so resolve the question
+// schema at parse time instead of at import time.
+export const RememberHumanInputPrompt = z.object({
+  questions: z.array(z.lazy(() => HumanInputQuestion)).length(1),
+  allowSkip: z.literal(false),
+});
+export type RememberHumanInputPrompt = z.infer<typeof RememberHumanInputPrompt>;
+
+export const RememberActivationSummary = z.discriminatedUnion("destination", [
+  z.object({
+    destination: GovernedLearningActivationDestination,
+    receiptId: z.string().uuid(),
+    destinationRevisionId: z.string().uuid().nullable(),
+    effectiveAt: z.string().datetime().nullable(),
+    authorityKind: z.enum(["automatic", "human_confirmed"]),
+    /** The `/learning` API/SDK history exposes exact undo for this receipt. */
+    undo: z.literal("learning_history"),
+  }),
+  z.object({
+    destination: z.literal("knowledge"),
+    receiptId: z.string().uuid(),
+    claimId: z.string().uuid(),
+    /** The retrievable Memory record materialized from the approved claim. */
+    memoryId: z.string().uuid(),
+    approvalReviewId: z.string().uuid(),
+    effectiveAt: z.string().datetime().nullable(),
+    authorityKind: z.literal("human_confirmed"),
+    /** Correct or archive the materialized record through the Memory lifecycle. */
+    undo: z.literal("memory_management"),
+  }),
+]);
+export type RememberActivationSummary = z.infer<typeof RememberActivationSummary>;
+
+export const RememberReceipt = z.discriminatedUnion("status", [
+  /** Learning policy is off for this source: nothing durable was written. */
+  z.object({
+    status: z.literal("blocked"),
+    operationId: z.string().uuid(),
+    lane: RememberLane,
+    scope: RememberScope,
+    reason: z.literal("learning_policy_off"),
+  }),
+  /** Kept for callers that still expect review-only Knowledge; not returned by `remember` today. */
+  z.object({
+    status: z.literal("proposed_for_review"),
+    operationId: z.string().uuid(),
+    lane: RememberLane,
+    scope: RememberScope,
+    noteId: z.string().uuid(),
+    claimId: z.string().uuid(),
+    evidenceId: z.string().uuid(),
+    reviewId: z.string().uuid().nullable(),
+  }),
+  /** Activated immediately (automatic policy) through the destination lifecycle. */
+  z.object({
+    status: z.literal("activated"),
+    operationId: z.string().uuid(),
+    lane: RememberLane,
+    scope: RememberScope,
+    noteId: z.string().uuid(),
+    proposalId: z.string().uuid(),
+    learning: CompanyBrainLearningDecisionSummary.nullable(),
+    activation: RememberActivationSummary,
+  }),
+  /**
+   * The proposal is durable but the workspace policy will not activate it on
+   * its own. The agent must ask the human exactly this question through the
+   * built-in `request_human_input` tool, then call `remember_confirm` with the
+   * returned request id.
+   */
+  z.object({
+    status: z.literal("confirmation_required"),
+    operationId: z.string().uuid(),
+    lane: RememberLane,
+    scope: RememberScope,
+    noteId: z.string().uuid(),
+    /** Ways-of-working lanes confirm a change proposal; Knowledge confirms the claim. */
+    proposalId: z.string().uuid().nullable(),
+    claimId: z.string().uuid(),
+    learning: CompanyBrainLearningDecisionSummary.nullable(),
+    learningFailure: CompanyBrainLearningStepFailure.nullable(),
+    humanInput: RememberHumanInputPrompt,
+    confirmWith: z.literal("remember_confirm"),
+  }),
+]);
+export type RememberReceipt = z.infer<typeof RememberReceipt>;
+
+export const RememberConfirmRequest = z.discriminatedUnion("target", [
+  z
+    .object({
+      target: z.literal("proposal"),
+      operationId: z.string().uuid(),
+      proposalId: z.string().uuid(),
+      /** `learning.receiptId` from the `confirmation_required` remember receipt. */
+      decisionReceiptId: z.string().uuid(),
+      /** The `requestId` returned by `request_human_input`. */
+      humanInputRequestId: z.string().uuid(),
+    })
+    .strict(),
+  z
+    .object({
+      target: z.literal("knowledge_claim"),
+      operationId: z.string().uuid(),
+      claimId: z.string().uuid(),
+      humanInputRequestId: z.string().uuid(),
+    })
+    .strict(),
+]);
+export type RememberConfirmRequest = z.infer<typeof RememberConfirmRequest>;
+
+export const RememberConfirmReceipt = z.object({
+  status: z.literal("activated"),
+  operationId: z.string().uuid(),
+  proposalId: z.string().uuid().nullable(),
+  claimId: z.string().uuid(),
+  decisionReceiptId: z.string().uuid().nullable(),
+  activation: RememberActivationSummary,
+});
+export type RememberConfirmReceipt = z.infer<typeof RememberConfirmReceipt>;

package/src/retained-output.ts

@@ -35,6 +35,7 @@ export const RetainedOutputKind = z.enum([
   "internal_update",
   "event_media",
   "computer_screenshot",
+  "browser_screenshot",
   "generated_image",
   "generated_video",
   "file",
@@ -124,6 +125,7 @@ export const RetainedArtifactReferenceSchema = z
 
     if (
       value.kind === "computer_screenshot" ||
+      value.kind === "browser_screenshot" ||
       value.kind === "generated_image" ||
       value.kind === "generated_video"
     ) {
@@ -187,12 +189,12 @@ export const RetainedArtifactReferenceSchema = z
       }
     }
 
-    if (value.kind === "computer_screenshot") {
+    if (value.kind === "computer_screenshot" || value.kind === "browser_screenshot") {
       if (value.retention.policy !== "session_screenshot" || !sessionMatch) {
         ctx.addIssue({
           code: "custom",
           path: ["retention"],
-          message: "computer screenshots require session-scoped expiring retrieval",
+          message: "session screenshots require session-scoped expiring retrieval",
         });
       }
     }
@@ -252,8 +254,23 @@ export type RetainedScreenshotArtifactInput = RetainedArtifactFileInput & {
   width: number;
   height: number;
   expiresAt: string;
+  kind?: "computer_screenshot" | "browser_screenshot";
 };
 
+export type RetainedSessionScreenshotKind = "computer_screenshot" | "browser_screenshot";
+
+/** The persisted, server-authored storage key distinguishes browser captures from legacy computer captures. */
+export function retainedSessionScreenshotKindFromObjectKey(
+  objectKey: string,
+): RetainedSessionScreenshotKind | null {
+  const match =
+    /^workspaces\/[0-9a-f-]+\/files\/[0-9a-f-]+\/retained\/(session-image|computer-screenshot|screenshot|browser-screenshot)\.(png|jpg|webp)$/.exec(
+      objectKey,
+    );
+  if (!match) return null;
+  return match[1] === "browser-screenshot" ? "browser_screenshot" : "computer_screenshot";
+}
+
 export type RetainedGeneratedImageArtifactInput = RetainedArtifactFileInput & {
   width: number;
   height: number;
@@ -305,7 +322,7 @@ export function retainedScreenshotReferenceFromFile(
   const value = {
     available: true as const,
     artifactId: file.id,
-    kind: "computer_screenshot" as const,
+    kind: file.kind ?? "computer_screenshot",
     contentType: canonicalRetainedContentType(file.contentType),
     originalBytes: file.sizeBytes,
     sha256: file.sha256,