@opengeni/contracts 5.5.0 → 5.5.2-canary.40656248492001

package/src/secret-value.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+
+/**
+ * Schemas whose value is a secret: a password, key, token, or a bundle of
+ * credential headers or values. The action catalog generator reads this
+ * registry, so every action whose request or response carries such a field is
+ * marked as handling secrets wherever the schema is reused, whatever the
+ * field is called. Field names that already say "secret" ("apiKey",
+ * "clientSecret") are caught by name as well.
+ */
+export const secretValues = z.registry<{ secret: true }, z.ZodType>();
+
+/**
+ * Mark a schema as holding a secret value. Pass the schema built for this
+ * field ("z.record(...)"), never a shared one such as a primitive: the mark
+ * belongs to the schema instance, so marking a shared one would mark every
+ * field that uses it.
+ */
+export function secretValue<Schema extends z.ZodType>(schema: Schema): Schema {
+  secretValues.add(schema as z.ZodType, { secret: true });
+  return schema;
+}

package/src/session-goal-reports.ts

@@ -1,55 +1,61 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 
-export const SessionGoalReportRequirement = z
-  .object({
-    id: z
-      .string()
-      .max(64)
-      .describe(
-        "Stable report requirement identifier, at most 64 ASCII characters; not a title or status.",
-      )
-      .regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/),
-    title: z
-      .string()
-      .trim()
-      .min(1)
-      .max(512)
-      .describe(
-        "Short human-readable report title, at most 512 UTF-8 bytes. Keep normal spaces; do not put the report or a progress transcript here.",
-      )
-      .refine(
-        (value) => new TextEncoder().encode(value).byteLength <= 512,
-        "Report title exceeds 512 UTF-8 bytes",
-      ),
-  })
-  .strict();
+export const SessionGoalReportRequirement = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      id: z
+        .string()
+        .max(64)
+        .describe(
+          "Stable report requirement identifier, at most 64 ASCII characters; not a title or status.",
+        )
+        .regex(/^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/),
+      title: primitives.string
+        .trim()
+        .min(1)
+        .max(512)
+        .describe(
+          "Short human-readable report title, at most 512 UTF-8 bytes. Keep normal spaces; do not put the report or a progress transcript here.",
+        )
+        .refine(
+          (value) => new TextEncoder().encode(value).byteLength <= 512,
+          "Report title exceeds 512 UTF-8 bytes",
+        ),
+    })
+    .strict(),
+);
 export type SessionGoalReportRequirement = z.infer<typeof SessionGoalReportRequirement>;
 
-export const SessionGoalReportRequirements = z
-  .array(SessionGoalReportRequirement)
-  .max(16)
-  .superRefine((requirements, context) => {
-    if (new Set(requirements.map((item) => item.id)).size !== requirements.length) {
-      context.addIssue({ code: "custom", message: "Duplicate report requirement IDs" });
-    }
-  });
+export const SessionGoalReportRequirements = /* @__PURE__ */ defineSchema(() =>
+  z
+    .array(SessionGoalReportRequirement)
+    .max(16)
+    .superRefine((requirements, context) => {
+      if (new Set(requirements.map((item) => item.id)).size !== requirements.length) {
+        context.addIssue({ code: "custom", message: "Duplicate report requirement IDs" });
+      }
+    }),
+);
 
-export const SessionGoalReportDelivery = z
-  .object({
-    requirementId: SessionGoalReportRequirement.shape.id,
-    artifactId: z
-      .string()
-      .regex(/^[0-9a-f]{32}$/)
-      .refine((value) => !/^0+$/.test(value)),
-    inspectionReceiptId: z.string().uuid(),
-  })
-  .strict();
+export const SessionGoalReportDelivery = /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      requirementId: SessionGoalReportRequirement.shape.id,
+      artifactId: primitives.string.regex(/^[0-9a-f]{32}$/).refine((value) => !/^0+$/.test(value)),
+      inspectionReceiptId: primitives.uuid,
+    })
+    .strict(),
+);
 export type SessionGoalReportDelivery = z.infer<typeof SessionGoalReportDelivery>;
-export const SessionGoalReportDeliveries = z
-  .array(SessionGoalReportDelivery)
-  .max(16)
-  .superRefine((deliveries, context) => {
-    if (new Set(deliveries.map((item) => item.requirementId)).size !== deliveries.length) {
-      context.addIssue({ code: "custom", message: "Duplicate report delivery requirement IDs" });
-    }
-  });
+export const SessionGoalReportDeliveries = /* @__PURE__ */ defineSchema(() =>
+  z
+    .array(SessionGoalReportDelivery)
+    .max(16)
+    .superRefine((deliveries, context) => {
+      if (new Set(deliveries.map((item) => item.requirementId)).size !== deliveries.length) {
+        context.addIssue({ code: "custom", message: "Duplicate report delivery requirement IDs" });
+      }
+    }),
+);

package/src/session-history-import.ts

@@ -1,3 +1,5 @@
+import * as primitives from "./primitives";
+import { defineSchema } from "./define-schema";
 import { z } from "zod";
 import { Session } from "./index";
 import type { SessionEventType } from "./index";
@@ -30,19 +32,23 @@ export const ARCHIVED_SESSION_IMPORT_EVENT_TYPES = [
   "goal.cleared",
 ] as const satisfies readonly SessionEventType[];
 
-export const SessionImportedArchive = /* @__PURE__ */ z
-  .object({
-    importId: z.string().min(1).max(200),
-    importedAt: z.iso.datetime({ offset: true }),
-    readOnly: z.literal(true),
-  })
-  .strict();
+export const SessionImportedArchive = /* @__PURE__ */ /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      importId: z.string().min(1).max(200),
+      importedAt: z.iso.datetime({ offset: true }),
+      readOnly: z.literal(true),
+    })
+    .strict(),
+);
 export type SessionImportedArchive = z.infer<typeof SessionImportedArchive>;
 
 /** JS/SQL session seams preserve millisecond precision; never silently truncate. */
-const sourceTimestamp = /* @__PURE__ */ z.iso
-  .datetime({ offset: true })
-  .refine((value) => !/\.\d{4}/u.test(value), "Source timestamp supports at most milliseconds");
+const sourceTimestamp = /* @__PURE__ */ /* @__PURE__ */ defineSchema(() =>
+  z.iso
+    .datetime({ offset: true })
+    .refine((value) => !/\.\d{4}/u.test(value), "Source timestamp supports at most milliseconds"),
+);
 
 /** Validate JSON without coercing dates, dropping undefined, or rewriting text. */
 function isImportJson(value: unknown): boolean {
@@ -86,74 +92,84 @@ function jsonBytes(value: unknown): number {
   }
 }
 
-export const ArchivedSessionImportEvent = /* @__PURE__ */ z
-  .object({
-    type: z.enum(ARCHIVED_SESSION_IMPORT_EVENT_TYPES),
-    createdAt: sourceTimestamp,
-    /** Source turn identity is presentation correlation; no execution row is created. */
-    turnId: z.string().uuid().nullable().optional(),
-    payload: z.record(z.string(), z.unknown()).refine(isImportJson, "Payload must be bounded JSON"),
-  })
-  .strict()
-  .refine(
-    (event) => isImportJson(event) && jsonBytes(event) <= SESSION_HISTORY_IMPORT_MAX_EVENT_BYTES,
-    "Imported event exceeds its JSON or byte limit",
-  );
+export const ArchivedSessionImportEvent = /* @__PURE__ */ /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      type: z.enum(ARCHIVED_SESSION_IMPORT_EVENT_TYPES),
+      createdAt: sourceTimestamp,
+      /** Source turn identity is presentation correlation; no execution row is created. */
+      turnId: z.string().uuid().nullable().optional(),
+      payload: z
+        .record(primitives.string, z.unknown())
+        .refine(isImportJson, "Payload must be bounded JSON"),
+    })
+    .strict()
+    .refine(
+      (event) => isImportJson(event) && jsonBytes(event) <= SESSION_HISTORY_IMPORT_MAX_EVENT_BYTES,
+      "Imported event exceeds its JSON or byte limit",
+    ),
+);
 export type ArchivedSessionImportEvent = z.infer<typeof ArchivedSessionImportEvent>;
 
-const importEvents = /* @__PURE__ */ z
-  .array(ArchivedSessionImportEvent)
-  .max(SESSION_HISTORY_IMPORT_MAX_EVENTS);
+const importEvents = /* @__PURE__ */ /* @__PURE__ */ defineSchema(() =>
+  z.array(ArchivedSessionImportEvent).max(SESSION_HISTORY_IMPORT_MAX_EVENTS),
+);
 
-export const ImportArchivedSessionRequest = /* @__PURE__ */ z
-  .object({
-    importId: z.string().min(1).max(200),
-    title: z.string().min(1).max(200),
-    createdAt: sourceTimestamp,
-    /** The authenticated asUser actor supplies creator/owner, never a display label. */
-    visibility: z.enum(["workspace_shared", "user_private"]).optional(),
-    events: importEvents.default([]),
-  })
-  .strict()
-  .refine(
-    (request) => jsonBytes(request) <= SESSION_HISTORY_IMPORT_MAX_BODY_BYTES,
-    "Import request exceeds its byte limit",
-  );
+export const ImportArchivedSessionRequest = /* @__PURE__ */ /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      importId: z.string().min(1).max(200),
+      title: z.string().min(1).max(200),
+      createdAt: sourceTimestamp,
+      /** The authenticated asUser actor supplies creator/owner, never a display label. */
+      visibility: z.enum(["workspace_shared", "user_private"]).optional(),
+      events: importEvents.default([]),
+    })
+    .strict()
+    .refine(
+      (request) => jsonBytes(request) <= SESSION_HISTORY_IMPORT_MAX_BODY_BYTES,
+      "Import request exceeds its byte limit",
+    ),
+);
 export type ImportArchivedSessionRequest = z.input<typeof ImportArchivedSessionRequest>;
 
-export const AppendArchivedSessionEventsRequest = /* @__PURE__ */ z
-  .object({
-    batchId: z.string().min(1).max(200),
-    offset: z
-      .number()
-      .int()
-      .nonnegative()
-      .max(Number.MAX_SAFE_INTEGER)
-      .refine((value) => !Object.is(value, -0)),
-    events: importEvents.min(1),
-  })
-  .strict()
-  .refine(
-    (request) => jsonBytes(request) <= SESSION_HISTORY_IMPORT_MAX_BODY_BYTES,
-    "Import batch exceeds its byte limit",
-  );
+export const AppendArchivedSessionEventsRequest = /* @__PURE__ */ /* @__PURE__ */ defineSchema(() =>
+  z
+    .object({
+      batchId: z.string().min(1).max(200),
+      offset: primitives.nonnegativeInteger
+        .max(Number.MAX_SAFE_INTEGER)
+        .refine((value) => !Object.is(value, -0)),
+      events: importEvents.min(1),
+    })
+    .strict()
+    .refine(
+      (request) => jsonBytes(request) <= SESSION_HISTORY_IMPORT_MAX_BODY_BYTES,
+      "Import batch exceeds its byte limit",
+    ),
+);
 export type AppendArchivedSessionEventsRequest = z.infer<typeof AppendArchivedSessionEventsRequest>;
 
 // Lazy to preserve the root contracts initialization order; SDK uses types only.
-export const ImportArchivedSessionResponse = /* @__PURE__ */ z.object({
-  session: /* @__PURE__ */ z.lazy(() => Session),
-  importId: z.string(),
-  created: z.boolean(),
-  nextOffset: z.number().int().nonnegative(),
-});
+export const ImportArchivedSessionResponse = /* @__PURE__ */ /* @__PURE__ */ defineSchema(() =>
+  z.object({
+    session: /* @__PURE__ */ z.lazy(() => Session),
+    importId: primitives.string,
+    created: primitives.boolean,
+    nextOffset: primitives.nonnegativeInteger,
+  }),
+);
 export type ImportArchivedSessionResponse = z.infer<typeof ImportArchivedSessionResponse>;
 
-export const AppendArchivedSessionEventsResponse = /* @__PURE__ */ z.object({
-  sessionId: z.string().uuid(),
-  importId: z.string(),
-  nextOffset: z.number().int().nonnegative(),
-  replayed: z.boolean(),
-});
+export const AppendArchivedSessionEventsResponse = /* @__PURE__ */ /* @__PURE__ */ defineSchema(
+  () =>
+    z.object({
+      sessionId: primitives.uuid,
+      importId: primitives.string,
+      nextOffset: primitives.nonnegativeInteger,
+      replayed: primitives.boolean,
+    }),
+);
 export type AppendArchivedSessionEventsResponse = z.infer<
   typeof AppendArchivedSessionEventsResponse
 >;

package/src/session-history.ts

@@ -0,0 +1,197 @@
+/**
+ * Conversation-first session history: which durable events are the steps of a
+ * turn, and which tool results stay visible without opening those steps.
+ * Dependency-free so browser packages can import it without the schema bundle.
+ */
+/**
+ * The bulk of a long agent turn: tool calls, their outputs and streamed
+ * reasoning or command output. A turn whose window skips any of these has
+ * steps a reader can open.
+ */
+export const SESSION_EVENT_CONTENT_STEP_TYPES = [
+  "agent.toolCall.created",
+  "agent.toolCall.output",
+  "agent.reasoning.delta",
+  "sandbox.command.output.delta",
+  "terminal.pty.output.delta",
+] as const;
+
+/**
+ * Turn bookkeeping that renders nothing in the conversation: a turn writes a
+ * few `agent.model.request` rows and an `agent.model.usage` row per model
+ * call. Only a turn's request rows up to its first model response draw
+ * anything (the "first model response" startup phase); a conversation-filter
+ * server keeps those, and every bookkeeping row of a turn without other
+ * steps, so it never looks like it has steps to open.
+ */
+export const SESSION_EVENT_BOOKKEEPING_STEP_TYPES = [
+  "agent.model.request",
+  "agent.model.usage",
+] as const;
+
+/**
+ * Everything conversation-first history reads exclude and load per turn, only
+ * when a reader asks for that turn's steps.
+ */
+export const SESSION_EVENT_STEP_TYPES = [
+  ...SESSION_EVENT_CONTENT_STEP_TYPES,
+  ...SESSION_EVENT_BOOKKEEPING_STEP_TYPES,
+] as const;
+
+/**
+ * The conversation-filter behavior a server applies to a read that sends
+ * `presentedToolCalls=include`, announced in the `X-OpenGeni-Conversation-Filter`
+ * response header. Version 2 keeps presented tool calls and the bookkeeping
+ * rows described by {@link SESSION_EVENT_BOOKKEEPING_STEP_TYPES}; excluded
+ * turnless output (PTY and command output) stays out, for the sandbox dock to
+ * read itself. A server without the header may ignore `presentedToolCalls`
+ * entirely.
+ */
+export const SESSION_EVENT_CONVERSATION_FILTER_VERSION = 2;
+export const SESSION_EVENT_CONVERSATION_FILTER_HEADER = "X-OpenGeni-Conversation-Filter";
+
+/**
+ * What a reader excludes from a conversation read when the server has not
+ * announced {@link SESSION_EVENT_CONVERSATION_FILTER_VERSION}: tool calls stay
+ * in (an older server would otherwise drop presented calls with them) and the
+ * reader drops the ones that are not presented.
+ */
+export const SESSION_EVENT_COMPAT_EXCLUDED_STEP_TYPES = [
+  "agent.toolCall.output",
+  "agent.reasoning.delta",
+  "sandbox.command.output.delta",
+  "terminal.pty.output.delta",
+] as const;
+
+/**
+ * Whether an `agent.model.request` phase is the model's first response. A
+ * turn's request rows after its first response no longer change what the
+ * conversation draws.
+ */
+export function isSessionModelResponsePhase(phase: unknown): boolean {
+  return phase === "first_byte" || phase === "first_event";
+}
+
+/**
+ * Tools whose result is primary output a reader sees without opening the
+ * turn's steps: presented images and published files, Skill changes that may
+ * need review, learning writes whose refusal is told outside the folded work
+ * row, and worker spawns or messages that a turn's wait counts. Matched on the
+ * tool name's leaf (`x__leaf` or `leaf`).
+ */
+export const SESSION_EVENT_PRESENTED_TOOL_LEAVES = [
+  "generate_image",
+  "image_generation_call",
+  "sandbox_file_publish",
+  "skill_save",
+  "skill_remove",
+  "skill_install",
+  "skill_publish",
+  "instruction_policy_save",
+  "knowledge_save",
+  "knowledge_retain_file",
+  "knowledge_retain_message",
+  "knowledge_archive",
+  "task_note_promote_knowledge",
+  "remember_confirm",
+  "session_create",
+  "session_send_message",
+] as const;
+
+/** Whether a tool name is one of {@link SESSION_EVENT_PRESENTED_TOOL_LEAVES}. */
+export function isPresentedSessionToolName(name: unknown): boolean {
+  if (typeof name !== "string" || name.length === 0) return false;
+  return SESSION_EVENT_PRESENTED_TOOL_LEAVES.some(
+    (leaf) => name === leaf || name.endsWith(`__${leaf}`),
+  );
+}
+
+/** The tool leaf a session runs the app's own actions through. */
+export const SESSION_EVENT_APP_ACTION_CALL_LEAF = "admin_action_call";
+
+/** The page an app action opens: buying credits, starting a subscription, or the billing portal. */
+export type PresentedAppActionPage = "credits" | "subscription" | "portal";
+
+/**
+ * App actions whose call is primary output too: each opens a payment page,
+ * and the chat shows it as a button that later confirms the payment, which a
+ * person returning to the chat (often in a reloaded tab) needs to see.
+ * Keyed by action id, with the "METHOD /path" a call may name it by instead
+ * (as `findAppAction` accepts) and the page it opens.
+ */
+export const SESSION_EVENT_PRESENTED_APP_ACTIONS = {
+  createBillingCheckout: { route: "POST /v1/billing/checkout", page: "credits" },
+  createSubscriptionCheckout: {
+    route: "POST /v1/billing/subscription/checkout",
+    page: "subscription",
+  },
+  createBillingPortalSession: { route: "POST /v1/billing/portal", page: "portal" },
+  createSubscriptionPortalSession: {
+    route: "POST /v1/billing/subscription/portal",
+    page: "portal",
+  },
+} as const satisfies Record<string, { route: string; page: PresentedAppActionPage }>;
+
+export type PresentedAppActionId = keyof typeof SESSION_EVENT_PRESENTED_APP_ACTIONS;
+
+/**
+ * The whitespace a call's action id is trimmed of before it's matched: exactly
+ * what `String.prototype.trim` removes, as the action runner trims the id
+ * (`findAppAction`), spelled out so the history query (Postgres `btrim`) and
+ * every client agree.
+ */
+export const SESSION_EVENT_APP_ACTION_ID_SPACE =
+  " \t\n\v\f\r\u00a0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff";
+
+/** Every name that calls one of {@link SESSION_EVENT_PRESENTED_APP_ACTIONS}: each id and its "METHOD /path". */
+export const SESSION_EVENT_PRESENTED_APP_ACTION_NAMES: readonly string[] = Object.entries(
+  SESSION_EVENT_PRESENTED_APP_ACTIONS,
+).flatMap(([id, { route }]) => [id, route]);
+
+const PRESENTED_APP_ACTION_BY_NAME: ReadonlyMap<string, PresentedAppActionId> = new Map(
+  Object.entries(SESSION_EVENT_PRESENTED_APP_ACTIONS).flatMap(([id, { route }]) => [
+    [id, id as PresentedAppActionId],
+    [route, id as PresentedAppActionId],
+  ]),
+);
+
+function trimActionId(value: string): string {
+  let start = 0;
+  let end = value.length;
+  while (start < end && SESSION_EVENT_APP_ACTION_ID_SPACE.includes(value[start]!)) start += 1;
+  while (end > start && SESSION_EVENT_APP_ACTION_ID_SPACE.includes(value[end - 1]!)) end -= 1;
+  return value.slice(start, end);
+}
+
+/**
+ * Which of {@link SESSION_EVENT_PRESENTED_APP_ACTIONS} an app action call's
+ * `id` names, by its id or its "METHOD /path"; undefined for anything else.
+ */
+export function presentedAppActionId(id: unknown): PresentedAppActionId | undefined {
+  return typeof id === "string" ? PRESENTED_APP_ACTION_BY_NAME.get(trimActionId(id)) : undefined;
+}
+
+/**
+ * Whether a tool call's result is primary output: a presented tool
+ * ({@link isPresentedSessionToolName}), or an app action call that runs one of
+ * {@link SESSION_EVENT_PRESENTED_APP_ACTIONS} (its arguments' top-level `id`,
+ * see {@link presentedAppActionId}). Takes the `agent.toolCall.created`
+ * payload (its `name` and `arguments`, an object or JSON text).
+ */
+export function isPresentedSessionToolCall(call: unknown): boolean {
+  if (!call || typeof call !== "object") return false;
+  const { name, arguments: args } = call as { name?: unknown; arguments?: unknown };
+  if (isPresentedSessionToolName(name)) return true;
+  const leaf = SESSION_EVENT_APP_ACTION_CALL_LEAF;
+  if (typeof name !== "string" || (name !== leaf && !name.endsWith(`__${leaf}`))) return false;
+  let parsed: unknown = args;
+  if (typeof args === "string") {
+    try {
+      parsed = JSON.parse(args);
+    } catch {
+      return false;
+    }
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return false;
+  return presentedAppActionId((parsed as { id?: unknown }).id) !== undefined;
+}

package/src/session-list-entries.ts

@@ -0,0 +1,106 @@
+import type { Session, SessionListEntry } from "./index";
+import {
+  deriveAutomaticSessionTitlePreview,
+  deriveSessionDisplayTitle,
+  sessionTitleIsPending,
+} from "./session-titles";
+
+/** Explicit list projection. Detail/configuration remains available from getSession. */
+export type SessionListEntryInput = Omit<
+  SessionListEntry,
+  | "displayTitle"
+  | "renameSeed"
+  | "scheduledTaskId"
+  | "siteOrigin"
+  | "pinned"
+  | "pinnedAt"
+  | "pinVersion"
+  | "unread"
+  | "activelyWorking"
+  | "attentionVersion"
+  | "archived"
+  | "archivedAt"
+  | "archiveVersion"
+  | "description"
+  | "avatar"
+> & {
+  /** Absent from older servers' rows and SDK-projected sessions. */
+  description?: string | null | undefined;
+  avatar?: Session["avatar"] | undefined;
+} & Partial<
+    Pick<
+      Session,
+      | "pinned"
+      | "pinnedAt"
+      | "pinVersion"
+      | "unread"
+      | "activelyWorking"
+      | "attentionVersion"
+      | "archived"
+      | "archivedAt"
+      | "archiveVersion"
+    >
+  > &
+  Pick<Session, "metadata" | "initialMessage">;
+
+export function sessionListEntry(session: SessionListEntryInput): SessionListEntry {
+  const origin = session.metadata._opengeniSiteOrigin as
+    | { siteId?: unknown; title?: unknown }
+    | undefined;
+  const siteOrigin =
+    origin &&
+    typeof origin.siteId === "string" &&
+    /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/i.test(origin.siteId) &&
+    typeof origin.title === "string"
+      ? { siteId: origin.siteId, title: origin.title }
+      : null;
+  const scheduledTaskId = session.metadata.scheduledTaskId;
+  return {
+    id: session.id,
+    workspaceId: session.workspaceId,
+    accountId: session.accountId,
+    status: session.status,
+    backgroundCommandActivity: session.backgroundCommandActivity,
+    hasSchedules: session.hasSchedules,
+    hasUpcomingSchedules: session.hasUpcomingSchedules,
+    waitingForEvents: session.waitingForEvents,
+    automationWait: session.automationWait,
+    title: session.title,
+    titleSource: session.titleSource,
+    description: session.description ?? null,
+    avatar: session.avatar ?? null,
+    displayTitle: deriveSessionDisplayTitle(session),
+    renameSeed: sessionTitleIsPending(session)
+      ? (deriveAutomaticSessionTitlePreview(session.initialMessage) ?? "")
+      : (session.title?.trim() ?? ""),
+    scheduledTaskId:
+      typeof scheduledTaskId === "string" && scheduledTaskId.length > 0 ? scheduledTaskId : null,
+    siteOrigin,
+    ...(session.model ? { model: session.model } : {}),
+    ...(session.reasoningEffort ? { reasoningEffort: session.reasoningEffort } : {}),
+    createdBy: session.createdBy,
+    channelId: session.channelId,
+    parentSessionId: session.parentSessionId,
+    rootSessionId: session.rootSessionId,
+    effectiveControl: session.effectiveControl,
+    inputWait: session.inputWait,
+    lastSequence: session.lastSequence,
+    pinned: session.pinned ?? false,
+    pinnedAt: session.pinnedAt ?? null,
+    pinVersion: session.pinVersion ?? 0,
+    unread: session.unread ?? false,
+    activelyWorking: session.activelyWorking ?? false,
+    attentionVersion: session.attentionVersion ?? 0,
+    archived: session.archived ?? false,
+    archivedAt: session.archivedAt ?? null,
+    importedArchive: session.importedArchive,
+    ...(session.retention ? { retention: session.retention } : {}),
+    archiveVersion: session.archiveVersion ?? 0,
+    treeStats: session.treeStats,
+    requiresActionSince: session.requiresActionSince,
+    // Lets lists tell a runtime-held session apart from one waiting on a person.
+    ...(session.admissionBlock !== undefined ? { admissionBlock: session.admissionBlock } : {}),
+    createdAt: session.createdAt,
+    updatedAt: session.updatedAt,
+  };
+}