@cursor/july 0.1.1 → 0.1.3

package/src/internal/terminal-style.ts

@@ -0,0 +1,74 @@
+/**
+ * Tiny ANSI helpers for CLI progress output. Respects `NO_COLOR` and
+ * only enables when the target stream is a TTY.
+ */
+
+import { clearScreenDown, cursorTo } from "node:readline";
+
+export interface TerminalPalette {
+  dim: (s: string) => string;
+  bold: (s: string) => string;
+  cyan: (s: string) => string;
+  green: (s: string) => string;
+  red: (s: string) => string;
+  magenta: (s: string) => string;
+  yellow: (s: string) => string;
+}
+
+const IDENTITY = (s: string): string => s;
+
+const PLAIN: TerminalPalette = {
+  dim: IDENTITY,
+  bold: IDENTITY,
+  cyan: IDENTITY,
+  green: IDENTITY,
+  red: IDENTITY,
+  magenta: IDENTITY,
+  yellow: IDENTITY,
+};
+
+export function colorEnabledFor(
+  stream: NodeJS.WriteStream = process.stdout
+): boolean {
+  return stream.isTTY === true && process.env.NO_COLOR === undefined;
+}
+
+export function makePalette(enabled: boolean): TerminalPalette {
+  if (!enabled) {
+    return PLAIN;
+  }
+  const wrap =
+    (code: string) =>
+    (s: string): string =>
+      `\u001b[${code}m${s}\u001b[0m`;
+  return {
+    dim: wrap("2"),
+    bold: wrap("1"),
+    cyan: wrap("36"),
+    green: wrap("32"),
+    red: wrap("31"),
+    magenta: wrap("35"),
+    yellow: wrap("33"),
+  };
+}
+
+/** Palette for human-facing stdout (init summaries, next steps). */
+export function stdoutPalette(): TerminalPalette {
+  return makePalette(colorEnabledFor(process.stdout));
+}
+
+/** Palette for human-facing stderr (login progress, warnings). */
+export function stderrPalette(): TerminalPalette {
+  return makePalette(colorEnabledFor(process.stderr));
+}
+
+/** Wipe the terminal before a `dev` Enter-to-restart cycle. */
+export function clearTerminal(
+  stream: NodeJS.WriteStream = process.stdout
+): void {
+  if (stream.isTTY !== true) {
+    return;
+  }
+  cursorTo(stream, 0, 0);
+  clearScreenDown(stream);
+}

package/src/internal/trajectory.ts

@@ -17,6 +17,16 @@ export interface TrajectoryToolCall {
   isError: boolean;
   /** Present when the tool required human approval before execute. */
   approvalDecision?: "approve" | "deny";
+  /** Parent task/subagent call id when this tool ran inside a subagent. */
+  parentCallId?: string;
+}
+
+export interface TrajectorySubagent {
+  callId: string;
+  name?: string;
+  description?: string;
+  /** Nested tool calls streamed while this subagent was running. */
+  toolCalls: TrajectoryToolCall[];
 }
 
 export interface TrajectoryTurn {
@@ -25,7 +35,7 @@ export interface TrajectoryTurn {
   assistantText: string;
   reasoningText?: string;
   toolCalls: TrajectoryToolCall[];
-  subagents: Array<{ callId: string; name?: string; description?: string }>;
+  subagents: TrajectorySubagent[];
   usage?: TurnUsage;
   result?: string;
   failed: boolean;
@@ -95,12 +105,20 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
         break;
       }
       case "message.completed": {
+        // Nested subagent text must not overwrite the parent turn reply.
+        if (event.data.parentCallId !== undefined) {
+          break;
+        }
         if (event.turnId !== undefined && event.data.text !== "") {
           ensureTurn(event.turnId).assistantText = event.data.text;
         }
         break;
       }
       case "reasoning.appended": {
+        // Nested subagent thinking stays off the parent turn transcript.
+        if (event.data.parentCallId !== undefined) {
+          break;
+        }
         if (event.turnId !== undefined) {
           ensureTurn(event.turnId).reasoningText = event.data.text;
         }
@@ -112,14 +130,28 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
         }
         const turn = ensureTurn(event.turnId);
         for (const call of event.data.calls) {
+          const parentCallId = call.parentCallId ?? event.data.parentCallId;
+          // Keep bare top-level `task` in toolCalls so evals like
+          // `calledTool("task")` / `notCalledTool("task")` keep working.
+          // Nested progress also appears under `subagents`.
           const entry: TrajectoryToolCall = {
             callId: call.callId,
             toolName: call.toolName,
             isError: false,
-            ...(call.args === undefined ? {} : { args: call.args }),
+            args: call.args,
+            parentCallId,
           };
           pendingCalls.set(call.callId, entry);
-          turn.toolCalls.push(entry);
+          if (parentCallId !== undefined) {
+            let sub = turn.subagents.find((s) => s.callId === parentCallId);
+            if (sub === undefined) {
+              sub = { callId: parentCallId, toolCalls: [] };
+              turn.subagents.push(sub);
+            }
+            sub.toolCalls.push(entry);
+          } else {
+            turn.toolCalls.push(entry);
+          }
         }
         break;
       }
@@ -141,24 +173,49 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
           pending.isError = event.data.isError;
           pending.toolName = event.data.toolName;
         } else if (event.turnId !== undefined) {
-          ensureTurn(event.turnId).toolCalls.push({
+          const turn = ensureTurn(event.turnId);
+          const entry: TrajectoryToolCall = {
             callId: event.data.callId,
             toolName: event.data.toolName,
             output: event.data.output,
             isError: event.data.isError,
-          });
+            parentCallId: event.data.parentCallId,
+          };
+          if (event.data.parentCallId !== undefined) {
+            let sub = turn.subagents.find(
+              (s) => s.callId === event.data.parentCallId
+            );
+            if (sub === undefined) {
+              sub = {
+                callId: event.data.parentCallId,
+                toolCalls: [],
+              };
+              turn.subagents.push(sub);
+            }
+            sub.toolCalls.push(entry);
+          } else {
+            turn.toolCalls.push(entry);
+          }
         }
         break;
       }
       case "subagent.called": {
         if (event.turnId !== undefined) {
-          ensureTurn(event.turnId).subagents.push({
-            callId: event.data.callId,
-            ...(event.data.name === undefined ? {} : { name: event.data.name }),
-            ...(event.data.description === undefined
-              ? {}
-              : { description: event.data.description }),
-          });
+          const turn = ensureTurn(event.turnId);
+          const existing = turn.subagents.find(
+            (s) => s.callId === event.data.callId
+          );
+          if (existing !== undefined) {
+            existing.name = event.data.name;
+            existing.description = event.data.description;
+          } else {
+            turn.subagents.push({
+              callId: event.data.callId,
+              name: event.data.name,
+              description: event.data.description,
+              toolCalls: [],
+            });
+          }
         }
         break;
       }
@@ -202,7 +259,13 @@ export function buildTrajectory(events: SessionEvent[]): Trajectory {
 
   const turns = turnOrder.map((id) => turnsById.get(id)!);
   const turnsFailed = turns.filter((t) => t.failed).length;
-  const toolCallCount = turns.reduce((n, t) => n + t.toolCalls.length, 0);
+  const toolCallCount = turns.reduce(
+    (n, t) =>
+      n +
+      t.toolCalls.length +
+      t.subagents.reduce((m, s) => m + s.toolCalls.length, 0),
+    0
+  );
   const lastGood = [...turns].reverse().find((t) => t.assistantText !== "");
   return {
     sessionId,
@@ -270,6 +333,21 @@ export function formatTrajectoryText(trajectory: Trajectory): string {
         lines.push(`    ${truncate(stringify(call.output), 160)}`);
       }
     }
+    for (const sub of turn.subagents) {
+      const label = sub.name ?? "subagent";
+      const detail =
+        sub.description !== undefined
+          ? ` — ${truncate(sub.description, 80)}`
+          : "";
+      lines.push(`  task ${label}${detail}`);
+      for (const call of sub.toolCalls) {
+        const mark = call.isError ? "✗" : "→";
+        lines.push(`    ${mark} ${call.toolName}${formatArgs(call.args)}`);
+        if (call.output !== undefined) {
+          lines.push(`      ${truncate(stringify(call.output), 160)}`);
+        }
+      }
+    }
     if (turn.assistantText.length > 0) {
       lines.push(`  agent: ${truncate(turn.assistantText, 400)}`);
     }

package/src/internal/workspace.ts

@@ -15,6 +15,7 @@ import type {
   ResolvedAgent,
 } from "../types.js";
 import { parseFrontmatter, serializeFrontmatter } from "./frontmatter.js";
+import { buildIdentitySection } from "./prompt-context.js";
 
 export interface MaterializeWorkspaceOptions {
   agent: ResolvedAgent;
@@ -31,6 +32,41 @@ export function agentToolScriptPath(toolName: string): string {
   return `.agent-serve/tools/${toolName}.sh`;
 }
 
+/**
+ * Always-on identity line prepended when composing instructions. Sourced from
+ * {@link ResolvedAgent.name} (`defineAgent({ name })`, else package/dir name)
+ * so agents know who they are without restating it in authored prose.
+ */
+export function buildIdentityPreamble(name: string): string {
+  const trimmed = name.trim();
+  if (trimmed === "") {
+    return "";
+  }
+  return `You are ${trimmed}. That is your name; use it when people ask who you are.`;
+}
+
+/**
+ * Prepend {@link buildIdentityPreamble} to authored instructions. Used when
+ * loading `instructions.md` / `.ts` / dir into {@link ResolvedAgent.instructions}.
+ */
+export function withIdentityPreamble(
+  name: string,
+  instructions: string | undefined
+): string | undefined {
+  const preamble = buildIdentityPreamble(name);
+  const body = instructions?.trim() ?? "";
+  if (preamble === "" && body === "") {
+    return undefined;
+  }
+  if (preamble === "") {
+    return body === "" ? undefined : body;
+  }
+  if (body === "") {
+    return preamble;
+  }
+  return `${preamble}\n\n${body}`;
+}
+
 /**
  * Markdown catalog of agent-side tools for AGENTS.md / cloud first prompt.
  *
@@ -96,12 +132,14 @@ export async function materializeWorkspace(
   const agentToolsSection = buildAgentToolsCatalog(agent.tools, {
     includeScripts: false,
   });
-  const agentsMd = [agent.instructions?.trim() ?? "", agentToolsSection]
+  const agentsMd = [
+    agent.instructions?.trim() ?? "",
+    buildIdentitySection(agent),
+    agentToolsSection,
+  ]
     .filter((part) => part !== "")
     .join("\n\n");
-  if (agentsMd !== "") {
-    await writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
-  }
+  await writeFile(join(workspaceDir, "AGENTS.md"), agentsMd, "utf8");
 
   for (const tool of agent.tools) {
     if (tool.execution !== "agent" || tool.script === undefined) {

package/src/storage.ts

@@ -0,0 +1,325 @@
+/**
+ * Durable storage plug-in for agent-serve.
+ *
+ * Author `agent/storage.ts` with {@link defineStorage} to mirror the
+ * framework's durable state into storage you own (a database, S3, a data
+ * pipeline, …). Without it, state lives under `--state-root` on local disk
+ * only (and eval/A/B history follows the narrower `persistRuns` /
+ * `persistSamples` / `persistSnapshots` hooks).
+ *
+ * The sink is a plain key-value store — four functions, no schema:
+ *
+ * ```ts
+ * import { defineStorage } from "@anysphere/agent-serve/storage";
+ *
+ * export default defineStorage({
+ *   put: (key, value) => db.upsert(key, value),
+ *   get: (key) => db.get(key),
+ *   delete: (key) => db.delete(key),
+ *   list: (prefix) => db.listByPrefix(prefix), // [{ key, value }] in key order
+ * });
+ * ```
+ *
+ * The **framework mints every key** from a stable, versioned scheme (see
+ * {@link storageKeys}) and decides **when** to call the sink: session
+ * records and event chunks flush when a turn's handlers have settled,
+ * reads happen at serve start (bulk restore), on continuation-token misses
+ * (lazy restore), and at playground hydration. Authors do not schedule
+ * reads or writes — the only timing knobs are {@link StoragePolicy}'s
+ * `debounceMs` (event write batching) and `restore` (startup hydration).
+ *
+ * Because keys are opaque strings to the sink, new kinds of durable state
+ * (channel cursors, thread affinity, …) are new key prefixes — existing
+ * sinks store them with no code changes.
+ *
+ * Delivery semantics: writes are **serialized** (one sink call in flight
+ * per agent, in order), **bounded** (a sink that falls behind sheds writes
+ * rather than growing memory), and **at-most-once** — a throwing `put` is
+ * logged and dropped, never retried, and never fails a turn. The local
+ * event log under `--state-root` remains the live source of truth; this
+ * interface is the durable mirror.
+ */
+
+import { createHash } from "node:crypto";
+import { brandDefinition } from "./internal/brand.js";
+import type { JsonValue } from "./types.js";
+
+// ============================================================================
+// Sink interface
+// ============================================================================
+
+/** One `{ key, value }` pair returned by {@link StorageConfig.list}. */
+export interface StorageEntry {
+  key: string;
+  value: JsonValue;
+}
+
+/** Context passed to every sink call. */
+export interface StorageContext {
+  /** Agent name (also baked into every key; see {@link storageKeys}). */
+  agentName: string;
+  /** Absolute agent project root (directory that contains `agent/`). */
+  projectRoot: string;
+  /**
+   * Why the framework is calling:
+   * - `"policy"` — a flush trigger fired (turn end, debounce, change)
+   * - `"shutdown"` — the serve process is draining; last chance to write
+   * - `"restore"` — serve start or a lazy restore; reads rebuilding state
+   */
+  reason: "policy" | "shutdown" | "restore";
+}
+
+export interface StoragePolicy {
+  /**
+   * Batch event-chunk writes on a quiet-period timer instead of flushing
+   * once per turn. The debounce **spans turn boundaries** — a rapid
+   * multi-turn exchange becomes one write when the session goes quiet —
+   * so it is the right choice for chatty sessions where per-turn writes
+   * are too many. Unset (default): one event chunk per turn.
+   */
+  debounceMs?: number;
+  /**
+   * Guardrails for the **startup bulk restore**. Whatever `list` returns
+   * is filtered to these caps before anything is written to local disk, so
+   * a large store cannot blow up `--state-root` or stall serve start.
+   * Newest sessions (by `updatedAt`) win within each cap.
+   *
+   * `"off"` disables the startup restore entirely — sessions then restore
+   * one at a time as follow-ups actually arrive (lazy-only; recommended
+   * for high-traffic deployments).
+   */
+  restore?: StorageRestorePolicy | "off";
+}
+
+/** Caps applied to the startup bulk restore. See {@link StoragePolicy.restore}. */
+export interface StorageRestorePolicy {
+  /** Max sessions materialized (default {@link STORAGE_DEFAULT_RESTORE_MAX_SESSIONS}). */
+  maxSessions?: number;
+  /**
+   * Skip sessions whose `updatedAt` is older than this (default
+   * {@link STORAGE_DEFAULT_RESTORE_MAX_AGE_MS}). Older sessions remain
+   * reachable lazily on their next follow-up.
+   */
+  maxAgeMs?: number;
+  /**
+   * Stop restoring once this many bytes of records + events have been
+   * written (default {@link STORAGE_DEFAULT_RESTORE_MAX_TOTAL_BYTES}).
+   * Checked before each session is written, so one oversized stream
+   * cannot blow past the budget.
+   */
+  maxTotalBytes?: number;
+}
+
+export interface StorageConfig {
+  /** Optional label surfaced on `GET /v1/info` diagnostics. */
+  name?: string;
+  /** Timing knobs; see {@link StoragePolicy}. */
+  policy?: StoragePolicy;
+  /**
+   * Store one value under a key (upsert, last-write-wins). Called on the
+   * framework's schedule — never concurrently, always in order. Keep it
+   * fast or buffer internally: the delivery queue is bounded, so a sink
+   * that falls behind sustained traffic sheds writes (logged) instead of
+   * growing memory; it never stalls the agent loop.
+   */
+  put(key: string, value: JsonValue, ctx: StorageContext): void | Promise<void>;
+  /** Remove a key. Optional — without it, deletions are skipped. */
+  delete?(key: string, ctx: StorageContext): void | Promise<void>;
+  /**
+   * Point lookup. Optional — required for **lazy restore** (resolving a
+   * continuation token on a replacement host) and the A/B backfill.
+   * Return `undefined`/`null` only for a **definitive** miss: on the lazy
+   * restore path a throw propagates and fails the follow-up (retryable) —
+   * a store outage must not read as "unknown token", which would fork the
+   * conversation onto a new session.
+   */
+  get?(
+    key: string,
+    ctx: StorageContext
+  ): JsonValue | undefined | null | Promise<JsonValue | undefined | null>;
+  /**
+   * All entries under a key prefix, in ascending key order. Optional —
+   * required for the **startup bulk restore** (sessions + event streams)
+   * and playground eval history.
+   */
+  list?(
+    prefix: string,
+    ctx: StorageContext
+  ): StorageEntry[] | Promise<StorageEntry[]>;
+}
+
+export type StorageDefinition = StorageConfig & {
+  readonly __agentServe: "storage";
+};
+
+/**
+ * Author the project storage sink (`agent/storage.ts`, default
+ * export). See the module doc for semantics and an example.
+ */
+export function defineStorage(config: StorageConfig): StorageDefinition {
+  if (typeof config.put !== "function") {
+    throw new Error("defineStorage: config.put must be a function");
+  }
+  for (const hook of ["get", "list", "delete"] as const) {
+    const value = config[hook];
+    if (value !== undefined && typeof value !== "function") {
+      throw new Error(
+        `defineStorage: config.${hook} must be a function when set`
+      );
+    }
+  }
+  // Validate eagerly so a bad policy fails at discovery, not first flush.
+  resolveStoragePolicy(config.policy);
+  return brandDefinition("storage", config);
+}
+
+// ============================================================================
+// Key scheme
+// ============================================================================
+
+/**
+ * Framework-owned key root. All {@link storageKeys} values live under this
+ * prefix so a shared store can route or namespace agentkit data.
+ */
+export const STORAGE_KEY_ROOT = "agentkit/v1" as const;
+
+/**
+ * The framework-owned key scheme. Keys are a **stable, versioned contract**
+ * under {@link STORAGE_KEY_ROOT}: sinks may treat them as opaque strings, or
+ * route on prefixes (e.g. event chunks to object storage, everything else
+ * to a database). Channel ids and continuation tokens are the only segments
+ * that may contain caller-controlled characters; they are URI-encoded, and
+ * a segment whose encoding exceeds {@link MAX_KEY_SEGMENT_BYTES} is replaced
+ * by a `sha256:…` digest — so every minted key has a bounded length that any
+ * backend (VARCHAR columns, btree index tuples, S3 key limits) can store,
+ * no matter what a caller stuffs into a token. The substitution is
+ * deterministic: writes and continuation lookups build the same key.
+ *
+ * | Key | Value |
+ * | --- | --- |
+ * | `agentkit/v1/{agent}/session/{sessionId}` | `SessionRecord` |
+ * | `agentkit/v1/{agent}/session-events/{sessionId}/{index}` | `SessionEvent[]` chunk (index = first event's index, zero-padded) |
+ * | `agentkit/v1/{agent}/continuation/{channelId}/{token}` | `{ sessionId }` |
+ * | `agentkit/v1/{agent}/reminder/{reminderId}` | `ReminderRecord` |
+ * | `agentkit/v1/{agent}/eval-run/{runId}` | `EvalRunSnapshot` |
+ * | `agentkit/v1/{agent}/ab-sample/{sessionId}/{at}` | `ABMetricSample` |
+ * | `agentkit/v1/{agent}/ab-snapshot` | latest aggregate `ABSnapshot` |
+ */
+export const storageKeys = {
+  session: (agent: string, sessionId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/session/${sessionId}`,
+  sessionPrefix: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/session/`,
+  sessionEvents: (
+    agent: string,
+    sessionId: string,
+    firstIndex: number
+  ): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/${String(firstIndex).padStart(8, "0")}`,
+  sessionEventsPrefix: (agent: string, sessionId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/session-events/${sessionId}/`,
+  continuation: (
+    agent: string,
+    channelId: string,
+    continuationKey: string
+  ): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/continuation/${keySegment(channelId)}/${keySegment(continuationKey)}`,
+  reminder: (agent: string, reminderId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/reminder/${reminderId}`,
+  reminderPrefix: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/reminder/`,
+  evalRun: (agent: string, runId: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/eval-run/${runId}`,
+  evalRunPrefix: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/eval-run/`,
+  abSample: (agent: string, sessionId: string, at: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/ab-sample/${sessionId}/${at}`,
+  abSnapshot: (agent: string): string =>
+    `${STORAGE_KEY_ROOT}/${agent}/ab-snapshot`,
+} as const;
+
+/**
+ * Max bytes a caller-controlled key segment may occupy after URI-encoding.
+ * Chosen so full keys stay well under common backend limits (Postgres btree
+ * index tuples cap at ~2704 bytes; S3 keys at 1024). Longer segments are
+ * replaced by their SHA-256 digest, keeping every minted key bounded.
+ */
+export const MAX_KEY_SEGMENT_BYTES = 256;
+
+/**
+ * URI-encode one caller-controlled key segment, substituting a `sha256:…`
+ * digest of the raw value when the encoding exceeds
+ * {@link MAX_KEY_SEGMENT_BYTES}. Deterministic, so key construction on the
+ * write path and the continuation-lookup path always agree.
+ */
+function keySegment(raw: string): string {
+  const encoded = encodeURIComponent(raw);
+  if (Buffer.byteLength(encoded, "utf8") <= MAX_KEY_SEGMENT_BYTES) {
+    return encoded;
+  }
+  return `sha256:${createHash("sha256").update(raw, "utf8").digest("hex")}`;
+}
+
+// ============================================================================
+// Policy resolution
+// ============================================================================
+
+export const STORAGE_DEFAULT_RESTORE_MAX_SESSIONS = 1_000;
+export const STORAGE_DEFAULT_RESTORE_MAX_AGE_MS: number = 30 * 24 * 60 * 60_000;
+export const STORAGE_DEFAULT_RESTORE_MAX_TOTAL_BYTES = 1_073_741_824; // 1 GiB
+
+/** {@link StoragePolicy} with defaults applied. */
+export interface ResolvedStoragePolicy {
+  /** Event-chunk flush trigger: per turn, or debounced across turns. */
+  events: "turnEnd" | { debounceMs: number };
+  restore:
+    | "off"
+    | { maxSessions: number; maxAgeMs: number; maxTotalBytes: number };
+}
+
+/** Apply {@link StoragePolicy} defaults (exposed for tooling/tests). */
+export function resolveStoragePolicy(
+  policy: StoragePolicy | undefined
+): ResolvedStoragePolicy {
+  return {
+    events:
+      policy?.debounceMs === undefined
+        ? "turnEnd"
+        : { debounceMs: clampInt(policy.debounceMs, 2_000, 0, 60_000) },
+    restore:
+      policy?.restore === "off"
+        ? "off"
+        : {
+            maxSessions: clampInt(
+              policy?.restore?.maxSessions,
+              STORAGE_DEFAULT_RESTORE_MAX_SESSIONS,
+              0,
+              1_000_000
+            ),
+            maxAgeMs: clampInt(
+              policy?.restore?.maxAgeMs,
+              STORAGE_DEFAULT_RESTORE_MAX_AGE_MS,
+              0,
+              10 * 365 * 24 * 60 * 60_000
+            ),
+            maxTotalBytes: clampInt(
+              policy?.restore?.maxTotalBytes,
+              STORAGE_DEFAULT_RESTORE_MAX_TOTAL_BYTES,
+              0,
+              1_099_511_627_776 // 1 TiB
+            ),
+          },
+  };
+}
+
+function clampInt(
+  value: number | undefined,
+  fallback: number,
+  min: number,
+  max: number
+): number {
+  if (value === undefined || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.min(max, Math.max(min, Math.floor(value)));
+}