@opengeni/sdk 0.57.0 → 1.0.0

package/src/company-brain.ts

@@ -0,0 +1,59 @@
+import type {
+  CompanyBrainContextReceiptPage as ContractCompanyBrainContextReceiptPage,
+  CompanyBrainKnowledgeProposalPage as ContractCompanyBrainKnowledgeProposalPage,
+  CompanyBrainOkfPackage as ContractCompanyBrainOkfPackage,
+} from "@opengeni/contracts";
+
+export type CompanyBrainOkfPackage = ContractCompanyBrainOkfPackage;
+export type CompanyBrainContextReceiptPage = ContractCompanyBrainContextReceiptPage;
+export type CompanyBrainKnowledgeProposalPage = ContractCompanyBrainKnowledgeProposalPage;
+
+export type CompanyBrainContextReceiptListOptions = {
+  attemptId?: string;
+  cursor?: string;
+  limit?: number;
+};
+
+export type CompanyBrainKnowledgeProposalListOptions = {
+  limit?: number;
+};
+
+export type CompanyBrainInspectorTransport = {
+  requestJson<T>(method: string, path: string, body?: unknown): Promise<T>;
+};
+
+function inspectorPath(workspaceId: string, suffix: string): string {
+  return `/v1/workspaces/${workspaceId}/company-brain/${suffix}`;
+}
+
+export function listCompanyBrainContextReceipts(
+  client: CompanyBrainInspectorTransport,
+  workspaceId: string,
+  options: CompanyBrainContextReceiptListOptions = {},
+): Promise<CompanyBrainContextReceiptPage> {
+  const params = new URLSearchParams();
+  if (options.attemptId) params.set("attemptId", options.attemptId);
+  if (options.cursor) params.set("cursor", options.cursor);
+  if (options.limit !== undefined) params.set("limit", String(options.limit));
+  const query = params.toString();
+  return client.requestJson(
+    "GET",
+    `${inspectorPath(workspaceId, "context-receipts")}${query ? `?${query}` : ""}`,
+  );
+}
+
+export function listCompanyBrainKnowledgeProposals(
+  client: CompanyBrainInspectorTransport,
+  workspaceId: string,
+  options: CompanyBrainKnowledgeProposalListOptions = {},
+): Promise<CompanyBrainKnowledgeProposalPage> {
+  const query =
+    options.limit === undefined ? "" : `?limit=${encodeURIComponent(String(options.limit))}`;
+  return client.requestJson("GET", `${inspectorPath(workspaceId, "knowledge-proposals")}${query}`);
+}
+
+export type CompanyBrainOkfDownload = {
+  content: string;
+  contentType: string;
+  filename: string;
+};

package/src/company-profile.ts

@@ -21,7 +21,10 @@ export type CompanyProfileRevision = CompanyProfileRevisionIdentity & {
   accountId: string;
   intent: "active" | "proposal";
   profile: CompanyProfileContent;
-  provenance: { source: "human" | "durable_learning" | "migration"; sourceId: string | null };
+  provenance: {
+    source: "human" | "agent_admin" | "durable_learning" | "migration";
+    sourceId: string | null;
+  };
   supersedesRevisionId: string | null;
   createdBySubjectId: string;
   createdAt: string;
@@ -79,6 +82,19 @@ export type CompanyProfileMutationResponse = {
   head: CompanyProfileHead | null;
   event: CompanyProfileActivationEvent | null;
 };
+export type CompanyProfileAgentPolicyMode = "off" | "suggest" | "automatic";
+export type CompanyProfileAgentPolicy = {
+  organizationId: string;
+  mode: CompanyProfileAgentPolicyMode;
+  version: number;
+  updatedAt: string;
+  changed?: boolean;
+};
+export type UpdateCompanyProfileAgentPolicyRequest = {
+  mode: CompanyProfileAgentPolicyMode;
+  expectedVersion: number;
+  operationId: string;
+};
 export type CompanyProfileDiffRequest = { fromRevisionId: string; toRevisionId: string };
 export type CompanyProfileDiffResponse = {
   from: CompanyProfileRevision;

package/src/core.ts

@@ -1,6 +1,22 @@
-export { OpenGeniClient as OpenGeniCoreClient } from "./client";
+/** Backward-compatible non-artifact client surface. */
+export { OpenGeniDocumentAuthorityClient as OpenGeniCoreClient } from "./document-authority-client";
+export {
+  OpenGeniToolCallError,
+  OpenGeniToolReapprovalRequiredError,
+  OpenGeniToolsClient,
+} from "./tools";
+export type {
+  OpenGeniGeneratedTools,
+  OpenGeniDynamicToolNode,
+  OpenGeniToolCallOptions,
+  OpenGeniToolFunction,
+  OpenGeniToolsFacade,
+  OpenGeniWorkspaceTools,
+} from "./tools";
 export type {
   FetchLike,
+  FetchResponse,
+  GetSessionOptions,
   OpenGeniClientOptions,
   OpenGeniRequestOptions,
   SendMessageInput,
@@ -11,9 +27,15 @@ export type {
 export {
   OpenGeniApiContractMismatchError,
   OpenGeniApiError,
+  OpenGeniSetupError,
+  OpenGeniSecureContextRequiredError,
   OpenGeniSessionListCursorError,
   OpenGeniStreamError,
+  formatErrorMessage,
   isRetryableStreamError,
 } from "./errors";
+export type { OpenGeniSecureContextRequiredReason } from "./errors";
+export { parseDeprecationNotice } from "./deprecation";
+export type { OpenGeniDeprecationHandler, OpenGeniDeprecationNotice } from "./deprecation";
 export { resolveWorkspaceVoiceInputEnabled } from "./transcription";
 export { OPENGENI_API_CONTRACT_HEADER, OPENGENI_API_CONTRACT_REVISION } from "./types";

package/src/deprecation.ts

@@ -0,0 +1,149 @@
+/**
+ * Deprecation notices advertised by the OpenGeni API.
+ *
+ * Per the public API compatibility policy, a route whose behaviour is scheduled
+ * for removal answers with the standard `Deprecation` (RFC 9745) and `Sunset`
+ * (RFC 8594) headers plus `Link: <notes>; rel="deprecation"`. The client
+ * surfaces them through `OpenGeniClientOptions.onDeprecation`, or by default
+ * as a one-time `console.warn` per route, so an integrator pinned to an older
+ * SDK learns about a removal well before it happens.
+ */
+
+export type OpenGeniDeprecationNotice = {
+  /** Request method, upper case. */
+  method: string;
+  /** Request path with ids collapsed (`/v1/workspaces/:id/...`), stable per route. */
+  route: string;
+  /** Exact request path. */
+  path: string;
+  /** When the deprecation was announced, if the header carried a date. */
+  deprecatedAt: Date | null;
+  /** Earliest removal on the server, if advertised. */
+  sunset: Date | null;
+  /** Migration notes (`rel="deprecation"`), if advertised. */
+  link: string | null;
+  /** Replacement (`rel="successor-version"`), if advertised. */
+  successor: string | null;
+};
+
+/** `false` silences notices; a function receives each route's notice once per client. */
+export type OpenGeniDeprecationHandler = (notice: OpenGeniDeprecationNotice) => void;
+
+type HeaderBag = { get(name: string): string | null };
+
+const ID_SEGMENT =
+  /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|\d+|[A-Za-z0-9_-]{20,})$/i;
+
+function routeKey(path: string): string {
+  return path
+    .split("/")
+    .map((segment) => (ID_SEGMENT.test(segment) ? ":id" : segment))
+    .join("/");
+}
+
+function parseDeprecationDate(value: string): Date | null {
+  const trimmed = value.trim();
+  // RFC 9745 structured date `@<unix seconds>`; older drafts used `true` or an HTTP-date.
+  const structured = /^@(-?\d+)$/.exec(trimmed);
+  if (structured) return new Date(Number(structured[1]) * 1000);
+  const parsed = Date.parse(trimmed);
+  return Number.isNaN(parsed) ? null : new Date(parsed);
+}
+
+function parseLinks(value: string | null): Map<string, string> {
+  const links = new Map<string, string>();
+  if (!value) return links;
+  for (const match of value.matchAll(/<([^>]*)>\s*((?:;\s*[^;,]+)*)/g)) {
+    const rel = /;\s*rel="?([^";,]+)"?/i.exec(match[2] ?? "")?.[1];
+    if (!rel) continue;
+    for (const name of rel.toLowerCase().split(/\s+/)) {
+      if (!links.has(name)) links.set(name, match[1]!);
+    }
+  }
+  return links;
+}
+
+/** Read a deprecation notice from response headers; `null` when none is advertised. */
+export function parseDeprecationNotice(
+  method: string,
+  url: string,
+  headers: HeaderBag,
+): OpenGeniDeprecationNotice | null {
+  const deprecation = headers.get("deprecation");
+  const sunsetHeader = headers.get("sunset");
+  if (!deprecation && !sunsetHeader) return null;
+  let path = url;
+  try {
+    path = new URL(url, "http://opengeni.invalid").pathname;
+  } catch {
+    // Keep the raw value; the notice is advisory.
+  }
+  const sunset = sunsetHeader ? Date.parse(sunsetHeader) : Number.NaN;
+  const links = parseLinks(headers.get("link"));
+  return {
+    method: method.toUpperCase(),
+    route: routeKey(path),
+    path,
+    deprecatedAt: deprecation ? parseDeprecationDate(deprecation) : null,
+    sunset: Number.isNaN(sunset) ? null : new Date(sunset),
+    link: links.get("deprecation") ?? links.get("sunset") ?? null,
+    successor: links.get("successor-version") ?? null,
+  };
+}
+
+const warnedRoutes = new Set<string>();
+
+/** The default handler: one `console.warn` per route per process. */
+export function warnDeprecationOnce(notice: OpenGeniDeprecationNotice): void {
+  const key = `${notice.method} ${notice.route}`;
+  if (warnedRoutes.has(key)) return;
+  warnedRoutes.add(key);
+  const sunset = notice.sunset ? ` and will be removed after ${notice.sunset.toISOString()}` : "";
+  const notes = notice.link ? ` Migration notes: ${notice.link}.` : "";
+  console.warn(
+    `[@opengeni/sdk] ${key} is deprecated${sunset}.${notes} Upgrade @opengeni/sdk, or pass onDeprecation to handle this notice.`,
+  );
+}
+
+type FetchFunction<R extends { headers: HeaderBag }> = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<R>;
+
+/**
+ * Wrap a fetch implementation so every response is inspected for a deprecation
+ * notice. The handler runs at most once per route for this wrapper and never
+ * affects the request: a throwing handler is swallowed.
+ */
+export function withDeprecationNotices<R extends { headers: HeaderBag }>(
+  fetchImpl: FetchFunction<R>,
+  handler: OpenGeniDeprecationHandler | false | undefined,
+): FetchFunction<R> {
+  if (handler === false) return fetchImpl;
+  const notify = handler ?? warnDeprecationOnce;
+  const seen = new Set<string>();
+  return async (input, init) => {
+    const response = await fetchImpl(input, init);
+    try {
+      const headers = response.headers;
+      if (headers && (headers.get("deprecation") || headers.get("sunset"))) {
+        const method =
+          init?.method ??
+          (typeof Request !== "undefined" && input instanceof Request ? input.method : "GET");
+        const url =
+          typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        const notice = parseDeprecationNotice(method, url, headers);
+        if (notice) {
+          const key = `${notice.method} ${notice.route}`;
+          if (!seen.has(key)) {
+            seen.add(key);
+            notify(notice);
+          }
+        }
+      }
+    } catch {
+      // Deprecation notices are advisory and must never fail a request.
+    }
+    return response;
+  };
+}

package/src/document-authority-client.ts

@@ -0,0 +1,219 @@
+import type { CompanyBrainOkfDownload, CompanyBrainOkfPackage } from "./company-brain";
+import { OpenGeniClient as OpenGeniCoreClient } from "./client";
+import type {
+  ApiKey,
+  UpdateOrganizationApiKeyRequest,
+  Document,
+  IssueUserResourceGrantRequest,
+  UserResourceGrantMutationResponse,
+  DocumentBase,
+  FileDownloadUrlResponse,
+  DocumentAuthorityReclassification,
+  DocumentDefaultCollectionBackfill,
+  DocumentDefaultCollectionBackfillAudit,
+  GetDocumentDefaultCollectionBackfillAuditOptions,
+  ListDocumentAuthorityReclassificationsOptions,
+  ListDocumentAuthorityReclassificationsResponse,
+  ListDocumentDefaultCollectionBackfillRunsResponse,
+  ListOrganizationDocumentAuthorityReclassificationsResponse,
+  ReclassifyDocumentAuthorityRequest,
+  RunDocumentDefaultCollectionBackfillRequest,
+} from "./types";
+
+/**
+ * Operator-only authority administration and Document tenancy-backfill surface.
+ *
+ * The public root and legacy `core` clients extend this class for compatibility.
+ * Browser consoles that import `@opengeni/sdk/browser` do not retain these
+ * methods or their routes.
+ */
+export class OpenGeniDocumentAuthorityClient extends OpenGeniCoreClient {
+  /** Read organization-key metadata and policy; never returns the secret token. */
+  async getOrganizationApiKey(organizationId: string, apiKeyId: string): Promise<ApiKey> {
+    return await this.requestJson<ApiKey>(
+      "GET",
+      `/v1/organizations/${organizationId}/api-keys/${apiKeyId}`,
+    );
+  }
+
+  /** Update metadata or replace the policy. Policy narrowing applies on the next request. */
+  async updateOrganizationApiKey(
+    organizationId: string,
+    apiKeyId: string,
+    request: UpdateOrganizationApiKeyRequest,
+  ): Promise<ApiKey> {
+    return await this.requestJson<ApiKey>(
+      "PATCH",
+      `/v1/organizations/${organizationId}/api-keys/${apiKeyId}`,
+      request,
+    );
+  }
+
+  /** Issue an exact-session or standing personal-resource grant. */
+  async issueUserResourceGrant(
+    workspaceId: string,
+    authorityId: string,
+    request: IssueUserResourceGrantRequest,
+  ): Promise<UserResourceGrantMutationResponse> {
+    return await this.requestJson<UserResourceGrantMutationResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/user-resource-authorities/${authorityId}/grants`,
+      request,
+    );
+  }
+
+  async listDocumentBases(workspaceId: string): Promise<DocumentBase[]> {
+    return await this.requestJson<DocumentBase[]>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/document-bases`,
+    );
+  }
+
+  /**
+   * List every Document the current human can manage from this workspace,
+   * including portable personal and organization-scoped Documents whose
+   * immutable ingestion workspace is different.
+   */
+  async listAccessibleDocuments(workspaceId: string): Promise<Document[]> {
+    return await this.requestJson<Document[]>("GET", `/v1/workspaces/${workspaceId}/documents`);
+  }
+
+  /** Mint a source-file URL through the Document's effective authority. */
+  async createDocumentOriginalFileDownloadUrl(
+    workspaceId: string,
+    documentId: string,
+  ): Promise<FileDownloadUrlResponse> {
+    return await this.requestJson<FileDownloadUrlResponse>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/documents/${documentId}/original-file/download-url`,
+    );
+  }
+
+  /** Retry indexing for a failed document. */
+  async reindexDocument(
+    workspaceId: string,
+    baseId: string,
+    documentId: string,
+  ): Promise<Document> {
+    return await this.requestJson<Document>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/document-bases/${baseId}/documents/${documentId}/reindex`,
+    );
+  }
+
+  /** Permission-filtered Company Brain package with authorized guidance bodies. */
+  getCompanyBrain(workspaceId: string): Promise<CompanyBrainOkfPackage> {
+    return this.requestJson<CompanyBrainOkfPackage>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/company-brain`,
+    );
+  }
+
+  /** Download the deterministic Markdown/YAML Company Brain package. */
+  async exportCompanyBrainOkf(workspaceId: string): Promise<CompanyBrainOkfDownload> {
+    const response = await this.requestResponse(
+      "GET",
+      `/v1/workspaces/${workspaceId}/company-brain/export`,
+    );
+    const headers = response.headers;
+    return {
+      content: await response.text(),
+      contentType: headers.get("content-type") ?? "text/markdown",
+      filename: headers.get("content-disposition")?.split('"')[1] ?? "company-brain.okf.md",
+    };
+  }
+
+  /**
+   * Atomically reclassify a Document's authority and every indexed chunk.
+   * The operation is replay-safe and rejects a stale expected authority tuple.
+   */
+  async reclassifyDocumentAuthority(
+    workspaceId: string,
+    documentId: string,
+    request: ReclassifyDocumentAuthorityRequest,
+  ): Promise<DocumentAuthorityReclassification> {
+    return await this.requestJson<DocumentAuthorityReclassification>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/documents/${documentId}/authority-reclassifications`,
+      request,
+    );
+  }
+
+  /** List the current actor's durable authority-reclassification receipts. */
+  async listDocumentAuthorityReclassifications(
+    workspaceId: string,
+    documentId: string,
+    options: ListDocumentAuthorityReclassificationsOptions = {},
+  ): Promise<ListDocumentAuthorityReclassificationsResponse> {
+    const params = new URLSearchParams();
+    if (options.limit !== undefined) params.set("limit", String(options.limit));
+    if (options.cursor) params.set("cursor", options.cursor);
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    return await this.requestJson<ListDocumentAuthorityReclassificationsResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/documents/${documentId}/authority-reclassifications${query}`,
+    );
+  }
+
+  /**
+   * Advance one resumable, organization-scoped Default collection backfill.
+   * Reusing an operation ID is idempotent; keep the run ID across batches.
+   */
+  async runDocumentDefaultCollectionBackfill(
+    workspaceId: string,
+    request: RunDocumentDefaultCollectionBackfillRequest,
+  ): Promise<DocumentDefaultCollectionBackfill> {
+    return await this.requestJson<DocumentDefaultCollectionBackfill>(
+      "POST",
+      `/v1/workspaces/${workspaceId}/document-default-collection-backfills`,
+      request,
+    );
+  }
+
+  /** List organization-scoped Default collection backfill runs (organization admin only). */
+  async listDocumentDefaultCollectionBackfillRuns(
+    workspaceId: string,
+    options: ListDocumentAuthorityReclassificationsOptions = {},
+  ): Promise<ListDocumentDefaultCollectionBackfillRunsResponse> {
+    const params = new URLSearchParams();
+    if (options.limit !== undefined) params.set("limit", String(options.limit));
+    if (options.cursor) params.set("cursor", options.cursor);
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    return await this.requestJson<ListDocumentDefaultCollectionBackfillRunsResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/document-default-collection-backfills${query}`,
+    );
+  }
+
+  /** Read bounded operation and workspace receipts for one Default-collection backfill run. */
+  async getDocumentDefaultCollectionBackfillAudit(
+    workspaceId: string,
+    runId: string,
+    options: GetDocumentDefaultCollectionBackfillAuditOptions = {},
+  ): Promise<DocumentDefaultCollectionBackfillAudit> {
+    const params = new URLSearchParams();
+    if (options.limit !== undefined) params.set("limit", String(options.limit));
+    if (options.operationCursor) params.set("operationCursor", options.operationCursor);
+    if (options.receiptCursor) params.set("receiptCursor", options.receiptCursor);
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    return await this.requestJson<DocumentDefaultCollectionBackfillAudit>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/document-default-collection-backfills/${runId}${query}`,
+    );
+  }
+
+  /** List organization-wide Document authority changes (organization admin only). */
+  async listOrganizationDocumentAuthorityReclassifications(
+    workspaceId: string,
+    options: ListDocumentAuthorityReclassificationsOptions = {},
+  ): Promise<ListOrganizationDocumentAuthorityReclassificationsResponse> {
+    const params = new URLSearchParams();
+    if (options.limit !== undefined) params.set("limit", String(options.limit));
+    if (options.cursor) params.set("cursor", options.cursor);
+    const query = params.size > 0 ? `?${params.toString()}` : "";
+    return await this.requestJson<ListOrganizationDocumentAuthorityReclassificationsResponse>(
+      "GET",
+      `/v1/workspaces/${workspaceId}/document-authority-reclassifications${query}`,
+    );
+  }
+}

package/src/document-authority.ts

@@ -0,0 +1,17 @@
+export { OpenGeniDocumentAuthorityClient } from "./document-authority-client";
+export type {
+  DocumentAuthorityReclassification,
+  DocumentDefaultCollectionBackfill,
+  DocumentDefaultCollectionBackfillAudit,
+  DocumentDefaultCollectionBackfillOperationAudit,
+  DocumentDefaultCollectionBackfillReceiptAudit,
+  DocumentDefaultCollectionBackfillRunAudit,
+  GetDocumentDefaultCollectionBackfillAuditOptions,
+  ListDocumentAuthorityReclassificationsOptions,
+  ListDocumentAuthorityReclassificationsResponse,
+  ListDocumentDefaultCollectionBackfillRunsResponse,
+  ListOrganizationDocumentAuthorityReclassificationsResponse,
+  OrganizationDocumentAuthorityReclassification,
+  ReclassifyDocumentAuthorityRequest,
+  RunDocumentDefaultCollectionBackfillRequest,
+} from "./types";

package/src/editable-artifacts/browser-session.ts

@@ -1,6 +1,8 @@
-import { DOCUMENT_ARTIFACT_COMMAND_VERSION } from "@opengeni/contracts/document-artifact-commands";
-import { PRESENTATION_ARTIFACT_COMMAND_VERSION } from "@opengeni/contracts/presentation-artifact-commands";
-import { SPREADSHEET_ARTIFACT_COMMAND_VERSION } from "@opengeni/contracts/spreadsheet-artifact-commands";
+import { EDITABLE_ARTIFACT_LIVE_WIRE_VERSION } from "@opengeni/contracts/editable-artifact-live";
+import {
+  EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION,
+  currentEditableArtifactCompatibility,
+} from "@opengeni/contracts/editable-artifacts";
 
 import type { EditableArtifactCacheAuthority } from "./controller";
 import {
@@ -10,6 +12,7 @@ import {
 import { createEditableArtifactSession, type EditableArtifactSession } from "./session";
 import type { EditableArtifactStoragePort } from "./storage";
 import type { EditableArtifactModality } from "./types";
+import type { EditableArtifactOpenFailureReporter } from "./open-failure";
 import {
   createBrowserEditableArtifactWorkerKernel,
   type CreateBrowserEditableArtifactWorkerKernelOptions,
@@ -20,10 +23,11 @@ export type EditableArtifactBrowserRuntime = Omit<
   "modality" | "kernelVersion" | "protocolVersion" | "modelSchemaVersion" | "commandVersion"
 > &
   Readonly<{
-    /** Exact native/WASM build identity admitted by the API. */
+    /** Exact package/executable build identity; the API records but does not compatibility-gate it. */
     kernelVersion: string;
     modelSchemaVersion: number;
-    protocolVersion?: number;
+    /** Exact OGATX001 intent protocol version. */
+    protocolVersion: number;
     commandVersion: number;
   }>;
 
@@ -36,11 +40,21 @@ export type CreateBrowserEditableArtifactSessionOptions = Readonly<{
   runtime: EditableArtifactBrowserRuntime;
   transport?: Omit<
     CreateEditableArtifactHttpLiveTransportOptions,
-    "baseUrl" | "workspaceId" | "protocolVersion" | "kernelVersion" | "modelSchemaVersion"
+    | "baseUrl"
+    | "workspaceId"
+    | "modality"
+    | "liveProtocolVersion"
+    | "kernelVersion"
+    | "modelSchemaVersion"
+    | "snapshotVersion"
+    | "commandProtocolVersion"
+    | "committedTransactionProtocolVersion"
   >;
   storage?: EditableArtifactStoragePort;
   /** Reuse the replica used to create the artifact when opening it immediately. */
   replicaId?: string;
+  /** Receives bounded categories/codes only; never workbook or formula content. */
+  onOpenFailure?: EditableArtifactOpenFailureReporter;
 }>;
 
 /**
@@ -53,17 +67,23 @@ export function createBrowserEditableArtifactSession(
   const baseUrl = canonicalBaseUrl(options.baseUrl);
   const workspaceId = boundedIdentity(options.workspaceId, "workspaceId");
   assertCacheAuthority(options.storageAuthority, baseUrl, workspaceId);
-  const protocolVersion = positiveVersion(options.runtime.protocolVersion ?? 1, "protocolVersion");
+  const protocolVersion = positiveVersion(options.runtime.protocolVersion, "protocolVersion");
+  if (protocolVersion !== EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION) {
+    throw new TypeError("protocolVersion is incompatible with the current intent protocol");
+  }
   const modelSchemaVersion = positiveVersion(
     options.runtime.modelSchemaVersion,
     "modelSchemaVersion",
   );
   const kernelVersion = boundedIdentity(options.runtime.kernelVersion, "kernelVersion", 512);
   const commandVersion = positiveVersion(options.runtime.commandVersion, "commandVersion");
-  const expectedCommandVersion = commandVersionFor(options.artifact.modality);
-  if (commandVersion !== expectedCommandVersion) {
+  const current = currentEditableArtifactCompatibility(options.artifact.modality);
+  if (
+    modelSchemaVersion !== current.modelSchemaVersion ||
+    commandVersion !== current.commandProtocolVersion
+  ) {
     throw new TypeError(
-      `commandVersion ${commandVersion} is incompatible with ${options.artifact.modality} ${expectedCommandVersion}`,
+      `runtime versions are incompatible with current ${options.artifact.modality} compatibility`,
     );
   }
   const {
@@ -87,9 +107,13 @@ export function createBrowserEditableArtifactSession(
       ...options.transport,
       baseUrl,
       workspaceId,
-      protocolVersion,
+      modality: options.artifact.modality,
+      liveProtocolVersion: EDITABLE_ARTIFACT_LIVE_WIRE_VERSION,
       kernelVersion,
       modelSchemaVersion,
+      snapshotVersion: current.snapshotVersion,
+      commandProtocolVersion: current.commandProtocolVersion,
+      committedTransactionProtocolVersion: current.committedTransactionProtocolVersion,
     });
     return createEditableArtifactSession({
       artifactId: options.artifact.id,
@@ -102,6 +126,7 @@ export function createBrowserEditableArtifactSession(
       modelSchemaVersion,
       commandVersion,
       protocolVersion,
+      ...(options.onOpenFailure ? { onOpenFailure: options.onOpenFailure } : {}),
       ...(replicaId ? { writerReplicaIdFactory: () => replicaId } : {}),
       ownsWorker: true,
     });
@@ -121,17 +146,6 @@ export function createEditableArtifactReplicaId(): string {
   }
 }
 
-function commandVersionFor(modality: EditableArtifactModality): number {
-  switch (modality) {
-    case "spreadsheet":
-      return SPREADSHEET_ARTIFACT_COMMAND_VERSION;
-    case "document":
-      return DOCUMENT_ARTIFACT_COMMAND_VERSION;
-    case "presentation":
-      return PRESENTATION_ARTIFACT_COMMAND_VERSION;
-  }
-}
-
 function canonicalBaseUrl(value: string | URL): URL {
   const url = new URL(value);
   if (url.username || url.password || url.search || url.hash) {