@opengeni/contracts 2.9.2 → 2.13.0-canary.0

package/src/mcp-oauth.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+
+export const MCP_OAUTH_SCOPE = "mcp:access" as const;
+export const MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS = 15 * 60;
+export const MCP_OAUTH_REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
+export const MCP_OAUTH_AUTHORIZATION_CODE_TTL_SECONDS = 5 * 60;
+export const MCP_OAUTH_CONSENT_TTL_SECONDS = 10 * 60;
+
+const RedirectUri = z.string().url().max(2_048);
+
+export const McpOAuthClientRegistrationRequest = z
+  .object({
+    redirect_uris: z.array(RedirectUri).min(1).max(16),
+    client_name: z.string().trim().min(1).max(200).optional(),
+    application_type: z.enum(["native", "web"]).optional(),
+    token_endpoint_auth_method: z.literal("none").default("none"),
+    scope: z.literal(MCP_OAUTH_SCOPE).optional(),
+    grant_types: z
+      .array(z.enum(["authorization_code", "refresh_token"]))
+      .min(1)
+      .max(2)
+      .refine((grantTypes) => grantTypes.includes("authorization_code"), {
+        message: "authorization_code grant is required",
+      })
+      .default(["authorization_code", "refresh_token"]),
+    response_types: z.array(z.literal("code")).min(1).max(1).default(["code"]),
+  })
+  .strict();
+export type McpOAuthClientRegistrationRequest = z.infer<typeof McpOAuthClientRegistrationRequest>;
+
+export const McpOAuthClientRegistrationResponse = McpOAuthClientRegistrationRequest.extend({
+  client_id: z.string().min(1).max(256),
+  client_id_issued_at: z.number().int().nonnegative(),
+});
+export type McpOAuthClientRegistrationResponse = z.infer<typeof McpOAuthClientRegistrationResponse>;
+
+export const McpOAuthTokenResponse = z.object({
+  access_token: z.string().min(1),
+  token_type: z.literal("Bearer"),
+  expires_in: z.number().int().positive(),
+  refresh_token: z.string().min(1).optional(),
+  scope: z.literal(MCP_OAUTH_SCOPE),
+});
+export type McpOAuthTokenResponse = z.infer<typeof McpOAuthTokenResponse>;
+
+export const McpOAuthProtectedResourceMetadata = z.object({
+  resource: z.string().url(),
+  authorization_servers: z.array(z.string().url()).min(1).max(1),
+  scopes_supported: z.array(z.literal(MCP_OAUTH_SCOPE)).length(1),
+  bearer_methods_supported: z.array(z.literal("header")).length(1),
+});
+export type McpOAuthProtectedResourceMetadata = z.infer<typeof McpOAuthProtectedResourceMetadata>;
+
+export const McpOAuthAuthorizationServerMetadata = z.object({
+  issuer: z.string().url(),
+  authorization_endpoint: z.string().url(),
+  token_endpoint: z.string().url(),
+  registration_endpoint: z.string().url(),
+  response_types_supported: z.array(z.literal("code")).length(1),
+  grant_types_supported: z.array(z.enum(["authorization_code", "refresh_token"])).length(2),
+  code_challenge_methods_supported: z.array(z.literal("S256")).length(1),
+  token_endpoint_auth_methods_supported: z.array(z.literal("none")).length(1),
+  scopes_supported: z.array(z.literal(MCP_OAUTH_SCOPE)).length(1),
+  authorization_response_iss_parameter_supported: z.literal(true),
+});
+export type McpOAuthAuthorizationServerMetadata = z.infer<
+  typeof McpOAuthAuthorizationServerMetadata
+>;

package/src/model-context-inspector.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+
+export const MODEL_CONTEXT_SNAPSHOT_VERSION = 1 as const;
+export const MODEL_CONTEXT_INSTRUCTIONS_MAX_UTF8_BYTES = 8 * 1024 * 1024;
+export const MODEL_CONTEXT_SNAPSHOT_MAX_UTF8_BYTES = 16 * 1024 * 1024;
+export const MODEL_CONTEXT_LAYER_MAX_COUNT = 16;
+export const MODEL_CONTEXT_TOOL_MAX_COUNT = 2_048;
+export const MODEL_CONTEXT_SKILL_MAX_COUNT = 1_024;
+
+export const ModelContextInstructionLayerId = z.enum([
+  "operational_contract",
+  "persona_and_core",
+  "workspace_governance",
+  "session_instructions",
+  "workspace_memory",
+  "codemode",
+  "git_bindings",
+  "genesis_title",
+  "sdk_capability_instructions",
+  "sandbox_preamble",
+  "sandbox_filesystem",
+  "sent_system_instructions",
+]);
+export type ModelContextInstructionLayerId = z.infer<typeof ModelContextInstructionLayerId>;
+
+export const ModelContextInstructionLayer = z
+  .object({
+    id: ModelContextInstructionLayerId,
+    title: z.string().min(1).max(120),
+    content: z.string(),
+    utf8Bytes: z.number().int().nonnegative(),
+    estimatedTokens: z.number().int().nonnegative(),
+  })
+  .strict();
+export type ModelContextInstructionLayer = z.infer<typeof ModelContextInstructionLayer>;
+
+export const ModelContextToolVisibility = z.enum(["eager", "searchable"]);
+export type ModelContextToolVisibility = z.infer<typeof ModelContextToolVisibility>;
+
+export const ModelContextTool = z
+  .object({
+    name: z.string().min(1).max(256),
+    type: z.string().min(1).max(64),
+    visibility: ModelContextToolVisibility,
+    description: z.string().max(16_384).optional(),
+    namespace: z.string().max(256).optional(),
+    schema: z.unknown().optional(),
+    utf8Bytes: z.number().int().nonnegative(),
+    estimatedTokens: z.number().int().nonnegative(),
+  })
+  .strict();
+export type ModelContextTool = z.infer<typeof ModelContextTool>;
+
+export const ModelContextSkillKind = z.enum([
+  "preference_descriptor",
+  "runtime_skill",
+  "native_tool_skill",
+]);
+export type ModelContextSkillKind = z.infer<typeof ModelContextSkillKind>;
+
+export const ModelContextSkill = z
+  .object({
+    kind: ModelContextSkillKind,
+    name: z.string().min(1).max(128),
+    description: z.string().max(8_192),
+    source: z.string().max(64).optional(),
+    path: z.string().max(1_024).optional(),
+  })
+  .strict();
+export type ModelContextSkill = z.infer<typeof ModelContextSkill>;
+
+export const ModelContextTokenCounts = z
+  .object({
+    instructions: z.number().int().nonnegative(),
+    tools: z.number().int().nonnegative(),
+    prefix: z.number().int().nonnegative(),
+  })
+  .strict();
+export type ModelContextTokenCounts = z.infer<typeof ModelContextTokenCounts>;
+
+export const ModelContextSnapshot = z
+  .object({
+    version: z.literal(MODEL_CONTEXT_SNAPSHOT_VERSION),
+    capturedAt: z.string().datetime(),
+    source: z.literal("model_request"),
+    requestIndex: z.number().int().nonnegative(),
+    instructions: z.string(),
+    layers: z.array(ModelContextInstructionLayer).max(MODEL_CONTEXT_LAYER_MAX_COUNT),
+    tools: z.array(ModelContextTool).max(MODEL_CONTEXT_TOOL_MAX_COUNT),
+    skills: z.array(ModelContextSkill).max(MODEL_CONTEXT_SKILL_MAX_COUNT),
+    tokens: ModelContextTokenCounts,
+  })
+  .strict();
+export type ModelContextSnapshot = z.infer<typeof ModelContextSnapshot>;
+
+export const SessionModelContextResponse = z
+  .object({
+    sessionId: z.string().uuid(),
+    attemptId: z.string().uuid().nullable(),
+    turnId: z.string().uuid().nullable(),
+    snapshot: ModelContextSnapshot.nullable(),
+  })
+  .strict();
+export type SessionModelContextResponse = z.infer<typeof SessionModelContextResponse>;

package/src/model-picker-order.ts

@@ -0,0 +1,87 @@
+export type ModelPickerBillingClass =
+  | "opengeni_credits"
+  | "external"
+  | "codex_subscription"
+  | "supergrok_subscription"
+  | "byok"
+  | "organization_byok";
+
+// Every closed billing class has a unique first character. Keeping the order
+// as initials avoids duplicating the full public labels in browser bundles.
+const MODEL_PICKER_BILLING_CLASS_ORDER: readonly ModelPickerBillingClass[] = [
+  "opengeni_credits",
+  "external",
+  "codex_subscription",
+  "supergrok_subscription",
+  "byok",
+  "organization_byok",
+];
+
+export type ModelPickerBillingCandidate = {
+  source?: string | undefined;
+  cost?: "free" | "credits" | "subscription" | "workspace" | "organization" | undefined;
+  billing?:
+    | {
+        upstreamPayer?: string | undefined;
+        metering?: string | undefined;
+      }
+    | undefined;
+  credentialSource?:
+    | {
+        kind?: string | undefined;
+        provider?: string | undefined;
+      }
+    | undefined;
+};
+
+export function modelPickerBillingClassFor(
+  model: ModelPickerBillingCandidate,
+): ModelPickerBillingClass {
+  if (model.cost === "credits") return "opengeni_credits";
+  if (model.cost === "workspace") return "byok";
+  if (model.cost === "organization") return "organization_byok";
+  const source = model.source;
+  const credential = model.credentialSource;
+  const payer = model.billing?.upstreamPayer;
+  if (model.billing?.metering === "external" && payer === "deployment") {
+    return "external";
+  }
+  if (
+    source === "supergrok" ||
+    (credential?.kind === "connected_subscription" && credential.provider === "xai")
+  ) {
+    return "supergrok_subscription";
+  }
+  if (
+    source === "codex" ||
+    credential?.kind === "connected_subscription" ||
+    payer === "connected_subscription"
+  ) {
+    return "codex_subscription";
+  }
+  if (
+    source === "workspace_gateway" ||
+    credential?.kind === "workspace_connection" ||
+    payer === "workspace"
+  ) {
+    return "byok";
+  }
+  if (credential?.kind === "organization_connection" || payer === "organization") {
+    return "organization_byok";
+  }
+  return "opengeni_credits";
+}
+
+export function compareModelPickerOrder(
+  left: { billingClass: ModelPickerBillingClass; selectable: boolean; label: string },
+  right: { billingClass: ModelPickerBillingClass; selectable: boolean; label: string },
+): number {
+  const classDelta =
+    MODEL_PICKER_BILLING_CLASS_ORDER.indexOf(left.billingClass) -
+    MODEL_PICKER_BILLING_CLASS_ORDER.indexOf(right.billingClass);
+  return (
+    classDelta ||
+    +right.selectable - +left.selectable ||
+    (left.label < right.label ? -1 : left.label > right.label ? 1 : 0)
+  );
+}

package/src/organization-membership-lifecycle.ts

@@ -239,6 +239,26 @@ export const CreateOrganizationResponse = z.object({
 });
 export type CreateOrganizationResponse = z.infer<typeof CreateOrganizationResponse>;
 
+export const CreateAdditionalOrganizationRequest = z
+  .object({
+    name: z.string().trim().min(1).max(120),
+    workspaceName: z.string().trim().min(1).max(120),
+    operationId: z.string().uuid(),
+  })
+  .strict();
+export type CreateAdditionalOrganizationRequest = z.infer<
+  typeof CreateAdditionalOrganizationRequest
+>;
+
+export const CreateAdditionalOrganizationResponse = z.object({
+  organization: OrganizationSummary,
+  workspaceId: z.string().uuid(),
+  personalWorkspaceId: z.string().uuid(),
+});
+export type CreateAdditionalOrganizationResponse = z.infer<
+  typeof CreateAdditionalOrganizationResponse
+>;
+
 export const UpdateOrganizationNameRequest = z.object({
   name: z.string().trim().min(1).max(120),
   expectedUpdatedAt: z.string().datetime({ offset: true }),

package/src/session-mcp-projections.ts

@@ -0,0 +1,268 @@
+import type { SessionGoalStatus, SessionStatus } from "./session-topology-primitives";
+import type { WorkDiscoveryProjection } from "./work-claims";
+import type { Session, SessionQueueSnapshot } from "./index";
+
+/** MCP-only presentation choice. REST/SDK session shapes keep their own defaults. */
+export type SessionMcpDetail = "compact" | "full";
+
+/** Search evidence is inseparable from matching; presentation opts never weaken search. */
+export function sessionMcpIncludesRelatedWork(options: {
+  detail?: SessionMcpDetail | undefined;
+  includeRelatedWork?: boolean | undefined;
+  query?: string | undefined;
+  subject?: unknown;
+}): boolean {
+  return (
+    Boolean(options.query?.trim() || options.subject) ||
+    (options.includeRelatedWork ?? options.detail === "full")
+  );
+}
+
+/** A database prefix plus its exact Unicode code-point count, not a JS UTF-16 count. */
+export function boundSessionMcpText(
+  value: string | null,
+  maxChars = 600,
+  originalChars?: number | null,
+) {
+  if (value === null) return { text: null, truncated: false };
+  const chars = Array.from(value);
+  const sourceChars = Math.max(chars.length, originalChars ?? chars.length);
+  if (sourceChars <= maxChars) return { text: value, truncated: false };
+  let bodyChars = maxChars;
+  let marker = "";
+  for (let attempt = 0; attempt < 4; attempt += 1) {
+    marker = `…[${Math.max(0, sourceChars - bodyChars)} chars truncated]…`;
+    const next = Math.max(0, maxChars - Array.from(marker).length);
+    if (next === bodyChars) break;
+    bodyChars = next;
+  }
+  return { text: `${chars.slice(0, bodyChars).join("")}${marker}`, truncated: true };
+}
+
+export type SessionMcpControlSource = {
+  state: string;
+  primaryBlocker: {
+    kind: "session" | "workspace";
+    sessionId?: string | undefined;
+    displayName: string;
+    displayNameOriginalChars?: number;
+    reason?: string | null;
+  } | null;
+  additionalBlockerCount: number;
+};
+
+/** Call only after related-access projection: this helper never grants ancestor access. */
+export function compactSessionMcpPause(control: SessionMcpControlSource) {
+  const blocker = control.primaryBlocker;
+  if (control.state === "active" && !blocker && !control.additionalBlockerCount) return undefined;
+  const name = blocker
+    ? boundSessionMcpText(blocker.displayName, 200, blocker.displayNameOriginalChars)
+    : null;
+  const reason = blocker?.reason ? boundSessionMcpText(blocker.reason) : null;
+  return {
+    state: control.state,
+    ...(blocker
+      ? {
+          source: {
+            kind: blocker.kind,
+            ...(blocker.sessionId ? { sessionId: blocker.sessionId } : {}),
+            displayName: name!.text,
+            ...(name!.truncated ? { displayNameTruncated: true } : {}),
+            ...(reason
+              ? { reason: reason.text, ...(reason.truncated ? { reasonTruncated: true } : {}) }
+              : {}),
+          },
+        }
+      : {}),
+    ...(control.additionalBlockerCount > 0
+      ? { additionalBlockerCount: control.additionalBlockerCount }
+      : {}),
+  };
+}
+
+export type SessionMcpListSource = {
+  id: string;
+  title: string | null;
+  titleOriginalChars?: number | null;
+  status: SessionStatus;
+  parentSessionId: string | null;
+  effectiveControl: SessionMcpControlSource;
+  goal: { status: SessionGoalStatus; text: string; textOriginalChars?: number } | null;
+  updatedAt: string;
+  workDiscovery?: WorkDiscoveryProjection;
+  treeStats?: {
+    attentionDescendants: number;
+    pausedDescendants: number;
+    failedDescendants: number;
+    truncated: boolean;
+  };
+};
+
+/** Closed allowlist, shared by MCP adapters. Never spread a database/session object. */
+export function compactSessionMcpListRow(
+  session: SessionMcpListSource,
+  includeRelatedWork = false,
+) {
+  const title = boundSessionMcpText(session.title, 200, session.titleOriginalChars);
+  const goal = session.goal
+    ? boundSessionMcpText(session.goal.text, 600, session.goal.textOriginalChars)
+    : null;
+  const pause = compactSessionMcpPause(session.effectiveControl);
+  const tree = session.treeStats;
+  const attention =
+    tree &&
+    (tree.attentionDescendants > 0 ||
+      tree.pausedDescendants > 0 ||
+      tree.failedDescendants > 0 ||
+      tree.truncated)
+      ? {
+          ...(tree.attentionDescendants > 0
+            ? { requiresActionDescendants: tree.attentionDescendants }
+            : {}),
+          ...(tree.pausedDescendants > 0 ? { pausedDescendants: tree.pausedDescendants } : {}),
+          ...(tree.failedDescendants > 0 ? { failedDescendants: tree.failedDescendants } : {}),
+          ...(tree.truncated ? { truncated: true } : {}),
+        }
+      : undefined;
+  return {
+    id: session.id,
+    title: title.text,
+    status: session.status,
+    ...(title.truncated ? { titleTruncated: true } : {}),
+    ...(session.parentSessionId ? { parentSessionId: session.parentSessionId } : {}),
+    ...(goal
+      ? {
+          goal: {
+            status: session.goal!.status,
+            summary: goal.text,
+            ...(goal.truncated ? { summaryTruncated: true } : {}),
+          },
+        }
+      : {}),
+    ...(pause ? { pause } : {}),
+    ...(attention ? { attention } : {}),
+    ...(includeRelatedWork && session.workDiscovery ? { relatedWork: session.workDiscovery } : {}),
+    updatedAt: session.updatedAt,
+  };
+}
+
+export type SessionMcpMonitoringSource = {
+  goal: {
+    status: SessionGoalStatus;
+    text: string;
+    textOriginalChars: number;
+    evidence: string | null;
+    evidenceOriginalChars: number | null;
+    rationale: string | null;
+    rationaleOriginalChars: number | null;
+    pausedReason: string | null;
+    pausedReasonOriginalChars: number | null;
+  } | null;
+  progress: {
+    sequence: number;
+    text: string | null;
+    originalChars: number | null;
+    occurredAt: string;
+  } | null;
+  wait: { reason: string; until: string } | null;
+};
+
+/** Closed management projection shared by adapters; never includes session configuration.
+ * Apply target/ancestor authorization projection to session before calling. */
+export function compactSessionMcpDetail(
+  session: Session,
+  monitoring: SessionMcpMonitoringSource,
+  queue: SessionQueueSnapshot | null,
+) {
+  const title = boundSessionMcpText(session.title, 200);
+  const pause = compactSessionMcpPause(session.effectiveControl);
+  const goal = monitoring.goal;
+  const goalText = goal ? boundSessionMcpText(goal.text, 600, goal.textOriginalChars) : null;
+  const optionalText = <Name extends string>(
+    name: Name,
+    text: string | null,
+    originalChars: number | null,
+    limit = 600,
+  ): Partial<Record<Name, string | null> & Record<`${Name}Truncated`, true>> => {
+    if (text === null) return {};
+    const bounded = boundSessionMcpText(text, limit, originalChars);
+    return {
+      [name]: bounded.text,
+      ...(bounded.truncated ? { [`${name}Truncated`]: true } : {}),
+    } as Partial<Record<Name, string | null> & Record<`${Name}Truncated`, true>>;
+  };
+  const progress = monitoring.progress;
+  const progressText = progress
+    ? boundSessionMcpText(progress.text, 600, progress.originalChars)
+    : null;
+  const waitReason = monitoring.wait ? boundSessionMcpText(monitoring.wait.reason) : null;
+  return {
+    id: session.id,
+    title: title.text,
+    status: session.status,
+    ...(title.truncated ? { titleTruncated: true } : {}),
+    ...(session.parentSessionId ? { parentSessionId: session.parentSessionId } : {}),
+    ...(session.activeTurnId ? { activeTurnId: session.activeTurnId } : {}),
+    lastSequence: session.lastSequence,
+    ...(goal
+      ? {
+          goal: {
+            status: goal.status,
+            summary: goalText!.text,
+            ...(goalText!.truncated ? { summaryTruncated: true } : {}),
+            ...optionalText("evidence", goal.evidence, goal.evidenceOriginalChars, 2000),
+            ...optionalText("rationale", goal.rationale, goal.rationaleOriginalChars),
+            ...optionalText("pausedReason", goal.pausedReason, goal.pausedReasonOriginalChars),
+          },
+        }
+      : {}),
+    ...(progress
+      ? {
+          progress: {
+            sequence: progress.sequence,
+            text: progressText!.text,
+            occurredAt: progress.occurredAt,
+            ...(progressText!.truncated ? { textTruncated: true } : {}),
+          },
+        }
+      : {}),
+    ...(pause ? { pause } : {}),
+    ...(monitoring.wait
+      ? {
+          wait: {
+            reason: waitReason!.text,
+            until: monitoring.wait.until,
+            ...(waitReason!.truncated ? { reasonTruncated: true } : {}),
+          },
+        }
+      : {}),
+    ...(queue
+      ? {
+          queue: {
+            queuedTurns: queue.items.length,
+            pendingInputs: queue.pendingInputs.length,
+            ...(queue.stoppingPreviousAttempt ? { stoppingPreviousAttempt: true } : {}),
+          },
+        }
+      : {}),
+    ...(session.effectiveControl.settlement || session.effectiveControl.backgroundCommandSettlement
+      ? {
+          stopping: {
+            ...(session.effectiveControl.settlement
+              ? { attempts: session.effectiveControl.settlement.attemptCount }
+              : {}),
+            ...(session.effectiveControl.backgroundCommandSettlement
+              ? {
+                  backgroundCommands:
+                    session.effectiveControl.backgroundCommandSettlement.commandCount,
+                }
+              : {}),
+          },
+        }
+      : {}),
+    updatedAt: session.updatedAt,
+  };
+}
+
+export type SessionMcpCompactListRow = ReturnType<typeof compactSessionMcpListRow>;
+export type SessionMcpCompactDetail = ReturnType<typeof compactSessionMcpDetail>;

package/src/session-titles.ts

@@ -15,6 +15,14 @@ export const AUTOMATIC_SESSION_TITLE_MAX_GRAPHEMES = 80;
  */
 export const AUTOMATIC_SESSION_TITLE_FALLBACK = "New conversation";
 
+// Session creation accepts a body far larger than a navigation label. Bound
+// the source before any replace/split/normalization so a persisted large prompt
+// cannot amplify memory or CPU on every client render.
+const PROMPT_PREVIEW_SCAN_MAX_CODE_UNITS = 4_096;
+
+const SESSION_ID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu;
+
 let titleSegmenter: Intl.Segmenter | null | undefined;
 
 const KNOWN_SENSITIVE_VALUE_PATTERNS = [
@@ -329,3 +337,95 @@ export function normalizeAutomaticSessionTitle(value: string): string | null {
   if (!title || !hasVisibleAutomaticTitleContent(title)) return null;
   return title;
 }
+
+export type SessionDisplayTitleInput = {
+  id?: string | null | undefined;
+  title?: string | null | undefined;
+  titleSource?: "user" | "agent" | null | undefined;
+  initialMessage?: string | null | undefined;
+  metadata?: Readonly<Record<string, unknown>> | undefined;
+};
+
+export type SessionDisplayTitleOptions = {
+  /** Optional metadata fields to try before the opening-prompt preview. */
+  metadataKeys?: readonly string[] | undefined;
+};
+
+/**
+ * Derive a bounded, sensitive-safe preview from the opening prompt.
+ *
+ * Unsafe leading lines are skipped instead of forcing the whole session back
+ * to a generic label. This covers prompts that begin with a pasted URL or
+ * identifier followed by an ordinary natural-language request on the next
+ * line, without putting the rejected value into navigation surfaces.
+ */
+export function deriveAutomaticSessionTitlePreview(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+
+  const lines = value
+    .slice(0, PROMPT_PREVIEW_SCAN_MAX_CODE_UNITS)
+    .replace(/[\u0000-\u001f\u007f-\u009f]+/gu, "\n")
+    .split(/\n+/u);
+
+  for (const candidate of lines) {
+    const line = candidate.trim();
+    if (!line || containsSensitiveAutomaticSessionTitleValue(line)) continue;
+
+    const preview = boundAutomaticSessionTitle(line.replace(/\s+/gu, " "))
+      .replace(/[\s.!?,;:\-–—]+$/u, "")
+      .trim();
+    if (preview) return preview;
+  }
+
+  return null;
+}
+
+function automaticSessionReferenceTitle(id: unknown): string {
+  const sessionId = typeof id === "string" ? id.trim() : "";
+  return SESSION_ID_PATTERN.test(sessionId)
+    ? `Conversation ${sessionId.slice(0, 13)}`
+    : AUTOMATIC_SESSION_TITLE_FALLBACK;
+}
+
+/**
+ * Whether the durable title still represents the automatic-title pending state.
+ * A user-authored title always wins, even when its literal value is the marker.
+ */
+export function sessionTitleIsPending(input: SessionDisplayTitleInput): boolean {
+  const title = input.title?.trim() ?? "";
+  return input.titleSource !== "user" && (!title || title === AUTOMATIC_SESSION_TITLE_FALLBACK);
+}
+
+/**
+ * Derive the title a human-facing client should display for a session.
+ *
+ * A semantic agent title or human rename wins. While automatic naming is still
+ * pending, clients show a short, sensitive-safe preview of the opening prompt.
+ * If no safe prompt text exists, a UUID-derived reference keeps real sessions
+ * distinguishable without exposing prompt bytes. The durable pending marker is
+ * therefore an internal lifecycle value rather than the ordinary visible name.
+ */
+export function deriveSessionDisplayTitle(
+  input: SessionDisplayTitleInput,
+  options: SessionDisplayTitleOptions = {},
+): string {
+  const title = input.title?.trim() ?? "";
+  if (input.titleSource === "user") {
+    return title || automaticSessionReferenceTitle(input.id);
+  }
+  if (title && !sessionTitleIsPending(input)) {
+    return title;
+  }
+
+  for (const key of options.metadataKeys ?? []) {
+    const value = input.metadata?.[key];
+    if (typeof value === "string" && value.trim().length > 0) {
+      return value.trim();
+    }
+  }
+
+  return (
+    deriveAutomaticSessionTitlePreview(input.initialMessage) ??
+    automaticSessionReferenceTitle(input.id)
+  );
+}