@opengeni/sdk 3.3.2-canary.1 → 3.4.0

package/src/knowledge.ts

@@ -0,0 +1,72 @@
+export type {
+  AgentLearningMode,
+  AgentLearningCategory,
+  AgentLearningDefaults,
+  AgentLearningOverrides,
+  AgentLearningContext,
+  AgentLearningOverridePatch,
+  AgentLearningSettingsRecord,
+  AgentLearningOverrideRecord,
+  SaveAgentLearningSettingsRequest,
+  KnowledgeFilePreparationResult,
+  KnowledgeSavePreparationRequest,
+  KnowledgeSavePreparationResponse,
+  KnowledgeOriginalFileDownload,
+  KnowledgeEntryKind,
+  KnowledgeEntryScope,
+  KnowledgeIndexStatus,
+  KnowledgeEntryContent,
+  KnowledgeEntrySource,
+  KnowledgeEntryEvidence,
+  KnowledgeEntryRelationship,
+  KnowledgeEntryRecord,
+  KnowledgeEntrySummary,
+  KnowledgeEntrySaveRequest,
+  KnowledgeEntryReviewRequest,
+  KnowledgeEntryBatchReviewRequest,
+  KnowledgeEntryRestoreRequest,
+  KnowledgeEntryWriteReceipt,
+  KnowledgeEntryListRequest,
+  KnowledgeEntryListResponse,
+  KnowledgeReviewBatch,
+  KnowledgeReviewBatchListRequest,
+  KnowledgeReviewBatchListResponse,
+  AgentInstructionReviewRequest,
+  AgentInstructionReceipt,
+  AgentInstructionReviewItem,
+  AgentInstructionReviewListResponse,
+} from "@opengeni/contracts";
+
+import type { OpenGeniClient } from "./client";
+import type {
+  KnowledgeSavePreparationRequest,
+  KnowledgeSavePreparationResponse,
+  KnowledgeFilePreparationResult,
+} from "@opengeni/contracts";
+
+/** Agent-only source preparation is a focused transport surface, outside the browser client. */
+export async function prepareKnowledgeFile(
+  client: Pick<OpenGeniClient, "requestJson">,
+  workspaceId: string,
+  fileId: string,
+  purpose?: "evidence" | "reference",
+): Promise<KnowledgeFilePreparationResult> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/knowledge/files/${encodeURIComponent(fileId)}/prepare`,
+    purpose ? { purpose } : undefined,
+  );
+}
+
+/** Read-only collection/duplicate discovery for a live selected agent or human Knowledge reviewer. */
+export async function prepareKnowledgeSave(
+  client: Pick<OpenGeniClient, "requestJson">,
+  workspaceId: string,
+  request: KnowledgeSavePreparationRequest,
+): Promise<KnowledgeSavePreparationResponse> {
+  return client.requestJson(
+    "POST",
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/knowledge/entries/prepare-save`,
+    request,
+  );
+}

package/src/known-tools.ts

@@ -0,0 +1,279 @@
+import { OpenGeniApiError } from "./errors";
+import { createSharedCatalogLoader, type SharedCatalogLoader } from "./shared-catalog-loader";
+import {
+  OpenGeniToolCallError,
+  OpenGeniToolReapprovalRequiredError,
+  type OpenGeniToolTransport,
+  type OpenGeniWorkspaceTools,
+  type OpenGeniToolCallOptions,
+} from "./tools";
+import type {
+  ToolGatewayTarget,
+  ToolGatewayResolvedTool,
+  ToolGatewayInvokeRequest,
+  ToolGatewayInvokeResponse,
+  ToolGatewayTargetApprovalResponse,
+  ToolGatewayManifestRequest,
+  ToolGatewayManifestResponse,
+  ToolGatewayIdentity,
+} from "./types";
+
+type Snapshot = ToolGatewayResolvedTool & { digest: string };
+const targetKey = (target: ToolGatewayTarget) =>
+  "identity" in target
+    ? JSON.stringify(["identity", target.identity.serverId, target.identity.toolName])
+    : JSON.stringify(["path", ...target.path]);
+export const isToolDefinitionStale = (error: unknown) => {
+  if (typeof error !== "object" || error === null) return false;
+  if (
+    ("outcomeUnknown" in error && error.outcomeUnknown === true) ||
+    ("retryable" in error && error.retryable === false)
+  )
+    return false;
+  return error instanceof OpenGeniApiError
+    ? error.status === 409 && error.details?.code === "tool_definition_stale"
+    : typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "tool_definition_stale";
+};
+
+/** Per-facade metadata only. Never coalesce invocations or retain credentials. */
+export function createKnownWorkspaceTools(
+  transport: OpenGeniToolTransport,
+  workspaceId: string,
+  createLegacy: () => OpenGeniWorkspaceTools,
+): OpenGeniWorkspaceTools {
+  const base = `/v1/workspaces/${encodeURIComponent(workspaceId)}/tools`;
+  let legacy: OpenGeniWorkspaceTools | undefined;
+  const old = () => (legacy ??= createLegacy());
+  const legacyTokens = new Set<string>();
+  const loaders = new Map<string, SharedCatalogLoader<Snapshot>>();
+  const snapshots = new Map<string, ToolGatewayResolvedTool>();
+  const revisions = new Map<string, number>();
+  let revisionSequence = 0;
+  const advance = (key: string) => {
+    if (!revisions.has(key) && revisions.size >= 256)
+      revisions.delete(revisions.keys().next().value!);
+    const revision = ++revisionSequence;
+    revisions.set(key, revision);
+    return revision;
+  };
+  const approvals = new Map<string, ToolGatewayTargetApprovalResponse>();
+  const loader = (target: ToolGatewayTarget) => {
+    const key = targetKey(target);
+    let value = loaders.get(key);
+    if (!value) {
+      value = createSharedCatalogLoader(async (_refresh, signal) => {
+        const result = await transport.requestJson<ToolGatewayResolvedTool>(
+          "POST",
+          `${base}/resolve`,
+          { target },
+          {},
+          { signal },
+        );
+        return { ...result, digest: result.definitionDigest };
+      });
+      if (loaders.size >= 256) loaders.delete(loaders.keys().next().value!);
+      loaders.set(key, value);
+    }
+    return value;
+  };
+  const remember = (target: ToolGatewayTarget, tool: ToolGatewayResolvedTool, revision: number) => {
+    const key = targetKey(target);
+    if (revisions.get(key) !== revision) return;
+    if (snapshots.size >= 256) snapshots.delete(snapshots.keys().next().value!);
+    snapshots.set(key, tool);
+  };
+  const resolve = async (
+    target: ToolGatewayTarget,
+    options: {
+      refresh?: boolean;
+      signal?: AbortSignal;
+      siteArtifactId?: string;
+      siteVersionId?: string;
+    } = {},
+  ) => {
+    if (options.siteArtifactId || options.siteVersionId)
+      return await transport.requestJson<ToolGatewayResolvedTool>(
+        "POST",
+        `${base}/resolve`,
+        { target, siteArtifactId: options.siteArtifactId, siteVersionId: options.siteVersionId },
+        {},
+        options.signal ? { signal: options.signal } : {},
+      );
+    const key = targetKey(target);
+    const revision = advance(key);
+    if (options.refresh) snapshots.delete(key);
+    const result = await loader(target).load(options);
+    remember(target, result, revision);
+    return result;
+  };
+  const invoke = (request: ToolGatewayInvokeRequest, options: { signal?: AbortSignal } = {}) =>
+    transport.requestJson<ToolGatewayInvokeResponse>(
+      "POST",
+      `${base}/invoke`,
+      request,
+      {},
+      options,
+    );
+  const call = async (
+    target: ToolGatewayTarget,
+    args: Record<string, unknown> = {},
+    options: OpenGeniToolCallOptions = {},
+  ) => {
+    if (
+      options.approvalToken &&
+      (options.approvalBinding === "catalog" || legacyTokens.has(options.approvalToken))
+    ) {
+      if ("identity" in target) return await old().$call(target.identity, args, options);
+      let node: unknown = old();
+      for (const part of target.path) node = (node as Record<string, unknown>)[part];
+      return await (
+        node as (
+          args: Record<string, unknown>,
+          options: OpenGeniToolCallOptions,
+        ) => Promise<unknown>
+      )(args, options);
+    }
+    if (options.approvalToken && !options.operationId)
+      throw new TypeError("operationId is required when using an approval token");
+    options.signal?.throwIfAborted();
+    const operationId = options.operationId ?? crypto.randomUUID();
+    const key = targetKey(target);
+    const revision = advance(key);
+    if (options.refreshCatalog) snapshots.delete(key);
+    let tool = options.refreshCatalog
+      ? await loader(target).load({
+          refresh: true,
+          ...(options.signal ? { signal: options.signal } : {}),
+        })
+      : snapshots.get(key);
+    const approved = options.approvalToken ? approvals.get(options.approvalToken) : undefined;
+    const expected =
+      options.expectedDefinitionDigest !== undefined
+        ? options.expectedDefinitionDigest
+        : options.approvalToken
+          ? undefined
+          : tool?.definitionDigest;
+    if (
+      approved &&
+      (approved.operationId !== operationId ||
+        ("identity" in target && targetKey({ identity: approved.tool.entry.identity }) !== key))
+    )
+      throw new OpenGeniToolReapprovalRequiredError(
+        operationId,
+        approved.tool.definitionDigest,
+        expected ?? "",
+        approved.tool.entry.identity,
+      );
+    const send = (digest: string | undefined) =>
+      invoke(
+        {
+          operationId,
+          target,
+          arguments: args,
+          ...(digest === undefined ? {} : { expectedDefinitionDigest: digest }),
+          ...(options.approvalToken ? { approvalToken: options.approvalToken } : {}),
+        },
+        options.signal ? { signal: options.signal } : {},
+      );
+    let response: ToolGatewayInvokeResponse;
+    try {
+      response = await send(expected);
+    } catch (error) {
+      if (!isToolDefinitionStale(error) || expected === undefined) throw error;
+      if (revisions.get(key) === revision) snapshots.delete(key);
+      if (options.expectedDefinitionDigest !== undefined && !options.approvalToken) throw error;
+      tool = await loader(target).reloadAfterStale(expected, options.signal);
+      remember(target, tool, revision);
+      if (options.approvalToken || options.expectedDefinitionDigest !== undefined)
+        throw new OpenGeniToolReapprovalRequiredError(
+          operationId,
+          expected,
+          tool.definitionDigest,
+          tool.entry.identity,
+        );
+      response = await send(tool.definitionDigest);
+    }
+    if (options.approvalToken) approvals.delete(options.approvalToken);
+    remember(target, response.tool, revision);
+    if (response.result.isError) throw new OpenGeniToolCallError(response.result);
+    return response.tool.entry.outputSchema && response.result.structuredContent !== undefined
+      ? response.result.structuredContent
+      : response.result;
+  };
+  const approveTarget = async (
+    identity: ToolGatewayIdentity,
+    args: Record<string, unknown> = {},
+    options: OpenGeniToolCallOptions = {},
+  ) => {
+    const tool = await resolve(
+      { identity },
+      { ...(options.signal ? { signal: options.signal } : {}) },
+    );
+    const response = await transport.requestJson<ToolGatewayTargetApprovalResponse>(
+      "POST",
+      `${base}/target-approvals`,
+      {
+        identity,
+        arguments: args,
+        operationId: options.operationId ?? crypto.randomUUID(),
+        expectedDefinitionDigest:
+          options.expectedDefinitionDigest === undefined
+            ? tool.definitionDigest
+            : options.expectedDefinitionDigest,
+      },
+      {},
+      options.signal ? { signal: options.signal } : {},
+    );
+    if (approvals.size >= 256) approvals.delete(approvals.keys().next().value!);
+    approvals.set(response.approvalToken, response);
+    return response;
+  };
+  const node = (path: string[]): unknown =>
+    new Proxy(
+      async (args: Record<string, unknown> = {}, options: OpenGeniToolCallOptions = {}) =>
+        call({ path }, args, options),
+      {
+        get: (_target, property) =>
+          property === "then" || typeof property !== "string"
+            ? undefined
+            : node([...path, property]),
+      },
+    );
+  return new Proxy(Object.create(null) as OpenGeniWorkspaceTools, {
+    get: (_target, property) => {
+      if (property === "then" || typeof property !== "string") return undefined;
+      if (property === "$targetProtocol") return 1;
+      if (property === "$resolve") return resolve;
+      if (property === "$invoke") return invoke;
+      if (property === "$manifest")
+        return (request: ToolGatewayManifestRequest, options: { signal?: AbortSignal } = {}) =>
+          transport.requestJson<ToolGatewayManifestResponse>(
+            "POST",
+            `${base}/manifest`,
+            request,
+            {},
+            options,
+          );
+      if (property === "$call")
+        return (
+          identity: ToolGatewayIdentity,
+          args?: Record<string, unknown>,
+          options?: OpenGeniToolCallOptions,
+        ) => call({ identity }, args, options);
+      if (property === "$approveTarget") return approveTarget;
+      if (property === "$approve")
+        return async (...args: Parameters<OpenGeniWorkspaceTools["$approve"]>) => {
+          const response = await old().$approve(...args);
+          if (legacyTokens.size >= 256) legacyTokens.delete(legacyTokens.values().next().value!);
+          legacyTokens.add(response.approvalToken);
+          return response;
+        };
+      if (property === "$catalog") return old().$catalog;
+      if (property === "$declarations") return old().$declarations;
+      return node([property]);
+    },
+  });
+}

package/src/message-links.ts

@@ -0,0 +1,178 @@
+/**
+ * Links an agent writes into chat Markdown that point at Opengeni-owned objects.
+ *
+ * Agents write these forms (tool receipts and bundled Skills teach them):
+ *
+ * - `artifact:<file uuid>` — a retained workspace file (exports, published files, images).
+ * - `sandbox:<path>[:<line>]` — a file in the session's sandbox or Connected Machine.
+ * - `/workspaces/<ws>/artifacts/editable/<32-hex id>` — a live editable document,
+ *   workbook, or presentation.
+ * - `/workspaces/<ws>/artifacts/<uuid>` — a saved Site / published HTML artifact.
+ * - `/workspaces/<ws>/artifacts/files/<uuid>` — a retained file (console path form).
+ *
+ * None of them is a URL a browser can navigate on its own: the `/workspaces/...`
+ * forms are Opengeni console routes, so inside another product they resolve
+ * against that product's origin and 404. Parse them with {@link parseOpenGeniLink}
+ * and route each target to the host's own UI (download, panel, page).
+ */
+export type OpenGeniLinkTarget =
+  | { kind: "file"; fileId: string; workspaceId: string | null; fromSession?: string }
+  | { kind: "editable-artifact"; artifactId: string; workspaceId: string; fromSession?: string }
+  | { kind: "site"; artifactId: string; workspaceId: string; fromSession?: string }
+  | { kind: "sandbox-file"; path: string; line: number | null };
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+const EDITABLE_ID = /^[0-9a-f]{32}$/iu;
+const WORKSPACE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u;
+const SANDBOX_SCHEME = "sandbox:";
+const LEGACY_WORKSPACE_PREFIX = "/workspace/";
+const TRAILING_LINE = /:([0-9]+)$/u;
+const TRAILING_INVALID_LINE = /:-(?:[0-9]+)$|:[0-9]+-[0-9]+$/u;
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f]/u;
+
+/** Application scheme names are case-insensitive, unlike their payloads. */
+export function openGeniLinkScheme(href: string | undefined): "artifact" | "sandbox" | null {
+  const scheme = /^([a-z]+):/iu.exec(href ?? "")?.[1]?.toLowerCase();
+  return scheme === "artifact" || scheme === "sandbox" ? scheme : null;
+}
+
+/** Reserved references must never fall back to navigation on a host origin. */
+export function isReservedOpenGeniLink(href: string | undefined): boolean {
+  if (!href) return false;
+  if (openGeniLinkScheme(href) || href.startsWith(LEGACY_WORKSPACE_PREFIX)) return true;
+  // Decoding is for reservation only: encoded variants are not valid targets.
+  try {
+    return /^\/workspaces\/[^/]+\/artifacts(?:\/|[?#]|$)/u.test(decodeURIComponent(href));
+  } catch {
+    return /^\/workspaces\/[^/]+\/artifacts/u.test(href);
+  }
+}
+
+/**
+ * Parse an Opengeni `sandbox:` href (plus the historical bare `/workspace/...`
+ * form). The decoded path is intentionally opaque: target selection, path
+ * policy, and filesystem authority belong to the session-aware host.
+ */
+export function parseSandboxLink(
+  href: string | undefined,
+): { path: string; line: number | null } | null {
+  if (!href) return null;
+  const encodedLocation =
+    openGeniLinkScheme(href) === "sandbox"
+      ? href.slice(SANDBOX_SCHEME.length)
+      : href.startsWith(LEGACY_WORKSPACE_PREFIX)
+        ? href
+        : null;
+  if (!encodedLocation || encodedLocation.includes("?") || encodedLocation.includes("#")) {
+    return null;
+  }
+  if (TRAILING_INVALID_LINE.test(encodedLocation)) return null;
+  const lineMatch = TRAILING_LINE.exec(encodedLocation);
+  const encodedPath = lineMatch ? encodedLocation.slice(0, -lineMatch[0].length) : encodedLocation;
+  const line = lineMatch?.[1] ? Number(lineMatch[1]) : null;
+  if (line !== null && (!Number.isSafeInteger(line) || line < 1)) return null;
+  if (!encodedPath) return null;
+  try {
+    const path = decodeURIComponent(encodedPath);
+    return path && !CONTROL_CHARACTER.test(path) ? { path, line } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Return the retained-file id of an exact `artifact:<uuid>` reference. */
+export function parseRetainedFileReference(href: string | undefined): string | null {
+  if (openGeniLinkScheme(href) !== "artifact") return null;
+  if (!href) return null;
+  const id = href.slice("artifact:".length);
+  return UUID.test(id) ? id.toLowerCase() : null;
+}
+
+/**
+ * Classify an agent-authored Markdown href. Returns `null` for ordinary links
+ * (`https://…`, `mailto:`, relative host links), which render as-is.
+ *
+ * Only root-relative console paths are recognized; an absolute URL is always an
+ * ordinary link, so a host's own `https://` routes are never reinterpreted.
+ * A validated `?fromSession=<uuid>` return hint is preserved.
+ */
+export function parseOpenGeniLink(href: string | undefined): OpenGeniLinkTarget | null {
+  if (!href) return null;
+  const fileId = parseRetainedFileReference(href);
+  if (fileId) return { kind: "file", fileId, workspaceId: null };
+  if (openGeniLinkScheme(href) === "sandbox" || href.startsWith(LEGACY_WORKSPACE_PREFIX)) {
+    const location = parseSandboxLink(href);
+    return location ? { kind: "sandbox-file", ...location } : null;
+  }
+  if (!href.startsWith("/workspaces/") || href.includes("#")) return null;
+  const separator = href.indexOf("?");
+  const pathname = separator < 0 ? href : href.slice(0, separator);
+  const search = separator < 0 ? undefined : href.slice(separator + 1);
+  let fromSession: string | undefined;
+  if (search !== undefined) {
+    const params = new URLSearchParams(search);
+    const keys = [...params.keys()];
+    if (keys.some((key) => key !== "fromSession") || keys.length > 1) return null;
+    if (!UUID.test(params.get("fromSession") ?? "")) return null;
+    fromSession = params.get("fromSession")!.toLowerCase();
+  }
+  const parts = pathname.split("/");
+  const workspaceId = parts[2] ?? "";
+  if (parts[1] !== "workspaces" || parts[3] !== "artifacts" || !WORKSPACE_SEGMENT.test(workspaceId))
+    return null;
+  if (parts.length === 6 && parts[4] === "editable" && EDITABLE_ID.test(parts[5] ?? "")) {
+    return {
+      kind: "editable-artifact",
+      artifactId: parts[5]!.toLowerCase(),
+      workspaceId,
+      ...(fromSession ? { fromSession } : {}),
+    };
+  }
+  if (parts.length === 6 && parts[4] === "files" && UUID.test(parts[5] ?? "")) {
+    return {
+      kind: "file",
+      fileId: parts[5]!.toLowerCase(),
+      workspaceId,
+      ...(fromSession ? { fromSession } : {}),
+    };
+  }
+  if (parts.length === 5 && UUID.test(parts[4] ?? "")) {
+    return {
+      kind: "site",
+      artifactId: parts[4]!.toLowerCase(),
+      workspaceId,
+      ...(fromSession ? { fromSession } : {}),
+    };
+  }
+  return null;
+}
+
+/** The Opengeni console route for a target (the form agents write). */
+export function openGeniConsolePath(
+  target: OpenGeniLinkTarget,
+  workspaceId: string,
+): string | null {
+  const workspace = encodeURIComponent(
+    target.kind === "sandbox-file" ? workspaceId : (target.workspaceId ?? workspaceId),
+  );
+  const search =
+    target.kind !== "sandbox-file" && target.fromSession && UUID.test(target.fromSession)
+      ? `?fromSession=${encodeURIComponent(target.fromSession)}`
+      : "";
+  switch (target.kind) {
+    case "file":
+      return `/workspaces/${workspace}/artifacts/files/${target.fileId}${search}`;
+    case "editable-artifact":
+      return `/workspaces/${workspace}/artifacts/editable/${target.artifactId}${search}`;
+    case "site":
+      return `/workspaces/${workspace}/artifacts/${target.artifactId}${search}`;
+    case "sandbox-file":
+      return null;
+  }
+}
+
+/**
+ * Request header naming the session an embedded artifact read belongs to.
+ * `createSessionProxyHandler` only serves artifacts Opengeni lists for it.
+ */
+export const SESSION_SCOPE_HEADER = "x-opengeni-session-id";

package/src/model-context.ts

@@ -0,0 +1,113 @@
+export type ModelContextInstructionLayerId =
+  | "operational_contract"
+  | "persona_and_core"
+  | "workspace_governance"
+  | "session_instructions"
+  | "workspace_memory"
+  | "skill_catalog"
+  | "codemode"
+  | "code_search"
+  | "git_bindings"
+  | "builtin_skills"
+  | "genesis_title"
+  | "sdk_capability_instructions"
+  | "sandbox_preamble"
+  | "sandbox_filesystem"
+  | "sent_system_instructions"
+  | "identity";
+
+/** Sections of a modular operational contract, in composition order. */
+export type AgentPromptModuleId =
+  | "base_behavior"
+  | "runtime_mechanics"
+  | "renderer_markdown"
+  | "sandbox"
+  | "connected_machine"
+  | "repositories"
+  | "workspace_environment"
+  | "rig"
+  | "artifacts"
+  | "media"
+  | "goals"
+  | "subagents"
+  | "knowledge"
+  | "skills"
+  | "secrets"
+  | "admin"
+  | "attachments";
+
+export type ModelContextInstructionModule = {
+  id: AgentPromptModuleId;
+  chars: number;
+};
+
+export type ModelContextInstructionLayer = {
+  id: ModelContextInstructionLayerId;
+  title: string;
+  content: string;
+  utf8Bytes: number;
+  estimatedTokens: number;
+  /** Present on the operational contract of sessions with an agent configuration. */
+  modules?: ModelContextInstructionModule[] | undefined;
+};
+
+export type ModelContextToolVisibility = "eager" | "searchable";
+
+export type ModelContextTool = {
+  name: string;
+  type: string;
+  visibility: ModelContextToolVisibility;
+  description?: string | undefined;
+  namespace?: string | undefined;
+  schema?: unknown | undefined;
+  utf8Bytes: number;
+  estimatedTokens: number;
+};
+
+export type ModelContextSkillKind = "preference_descriptor" | "runtime_skill" | "native_tool_skill";
+
+export type ModelContextSkill = {
+  kind: ModelContextSkillKind;
+  name: string;
+  description: string;
+  source?: string | undefined;
+  path?: string | undefined;
+};
+
+export type ModelContextTokenCounts = {
+  instructions: number;
+  tools: number;
+  prefix: number;
+};
+
+export type ModelContextSnapshot = {
+  providerRequest?:
+    | {
+        provider: string;
+        body: string | null;
+        unavailableReason?: string | undefined;
+        parts: {
+          key: string;
+          estimatedTokens: number | null;
+          utf8Bytes: number;
+          itemEstimatedTokens?: (number | null)[] | undefined;
+        }[];
+      }
+    | undefined;
+  version: 1;
+  capturedAt: string;
+  source: "model_request";
+  requestIndex: number;
+  instructions: string;
+  layers: ModelContextInstructionLayer[];
+  tools: ModelContextTool[];
+  skills: ModelContextSkill[];
+  tokens: ModelContextTokenCounts;
+};
+
+export type SessionModelContextResponse = {
+  sessionId: string;
+  attemptId: string | null;
+  turnId: string | null;
+  snapshot: ModelContextSnapshot | null;
+};

package/src/model-display.ts

@@ -0,0 +1,11 @@
+/** One clean model name and maker for every surface outside model settings. */
+export {
+  humanizeModelSlug,
+  isRawModelLabel,
+  modelDisplayName,
+  modelLogoUrl,
+  modelSlug,
+  modelVendor,
+  type ModelDisplayInput,
+  type ModelVendor,
+} from "@opengeni/contracts/model-display";