@sixb/core 0.1.20 → 0.1.22

package/src/agents/memory.ts

@@ -0,0 +1,178 @@
+/**
+ * Agent memory repos: a folder of linked Markdown files with `MEMORY.md` as the entry point, in the
+ * Agent Memory Repo format. These rules decide what a save may contain before it reaches storage.
+ */
+
+import type { Principal } from "../auth"
+import type { AgentMemoryChange, AgentMemoryFile } from "../storage/agents"
+import { AgentMemoryError } from "./errors"
+
+/** The two repos a conversation reaches: its user's own, and the one the project shares. */
+export type AgentMemoryRepoName = "user" | "project"
+
+export const AGENT_MEMORY_REPO_NAMES: readonly AgentMemoryRepoName[] = ["user", "project"]
+
+/** The file every repo starts from, and the one rendered into every conversation's prompt. */
+export const AGENT_MEMORY_ENTRY = "MEMORY.md"
+
+export const AGENT_MEMORY_LIMITS = {
+  /** `MEMORY.md` is part of every prompt. */
+  entryBytes: 16 * 1024,
+  fileBytes: 256 * 1024,
+  repoBytes: 4 * 1024 * 1024,
+  pathLength: 256,
+  messageLength: 500,
+} as const
+
+/** A link to a path that is not in the repo, found in one of its Markdown files. */
+export interface AgentMemoryLinkWarning {
+  /** The file the link is in. */
+  readonly path: string
+  readonly link: string
+}
+
+const encoder = new TextEncoder()
+
+/**
+ * The storage id of a repo: `user:<userId>` or `project`. A caller with no user of its own keeps
+ * its memory as `system:<id>`: a project without auth, or app code running as the system, which
+ * then reads a repo no signed-in user's conversation does.
+ */
+export function agentMemoryRepoId(repo: AgentMemoryRepoName, owner: Principal | null): string {
+  if (repo === "project") return "project"
+  if (!owner || owner.type === "serviceAccount") {
+    throw new AgentMemoryError(
+      "not_allowed",
+      "[Sixb] Agent memory of its own belongs to a signed-in user."
+    )
+  }
+  return `${owner.type}:${owner.id}`
+}
+
+export function parseAgentMemoryRepoName(value: string): AgentMemoryRepoName {
+  if (value === "user" || value === "project") return value
+  throw new AgentMemoryError(
+    "invalid_repo",
+    `[Sixb] Agent memory repo '${value}' does not exist. Use 'user' or 'project'.`
+  )
+}
+
+/** Why a path cannot hold a memory file, or `null` when it can. */
+export function agentMemoryPathProblem(path: string): string | null {
+  if (path.length === 0) return "is empty"
+  if (path.length > AGENT_MEMORY_LIMITS.pathLength) {
+    return `is longer than ${AGENT_MEMORY_LIMITS.pathLength} characters`
+  }
+  if (/[\u0000-\u001f\u007f\\]/.test(path)) return "contains a backslash or a control character"
+  if (path.startsWith("/")) return "is absolute; paths start at the repo root"
+  const segments = path.split("/")
+  if (segments.some((segment) => segment.length === 0)) return "has an empty segment"
+  if (segments.some((segment) => segment === "." || segment === "..")) {
+    return "has a '.' or '..' segment"
+  }
+  if (segments.some((segment) => segment.startsWith("."))) return "names a dotfile"
+  if (path.endsWith(".theirs")) return "is a conflict copy; merge it into its file and delete it"
+  return null
+}
+
+/**
+ * Apply `changes` to the repo's current files and check the result, so a save is rejected with
+ * an error the Agent can act on. Returns the repo as the save leaves it.
+ */
+export function applyAgentMemoryChanges(
+  current: readonly AgentMemoryFile[],
+  message: string,
+  changes: readonly AgentMemoryChange[]
+): AgentMemoryFile[] {
+  const fail = (detail: string): never => {
+    throw new AgentMemoryError("invalid_save", `[Sixb] Agent memory ${detail}`)
+  }
+
+  if (message.trim().length === 0) fail("save needs a message saying what was learned.")
+  if (message.length > AGENT_MEMORY_LIMITS.messageLength) {
+    fail(`save message is longer than ${AGENT_MEMORY_LIMITS.messageLength} characters.`)
+  }
+  if (changes.length === 0) fail("save changes no file.")
+
+  const files = new Map(current.map((file) => [file.path, file.contents]))
+  const seen = new Set<string>()
+  for (const change of changes) {
+    const problem = agentMemoryPathProblem(change.path)
+    if (problem) fail(`path '${change.path}' ${problem}.`)
+    if (seen.has(change.path)) fail(`save changes '${change.path}' more than once.`)
+    seen.add(change.path)
+
+    if (change.contents === null) {
+      files.delete(change.path)
+      continue
+    }
+    if (change.contents.includes("\u0000")) fail(`file '${change.path}' is not text.`)
+    const bytes = encoder.encode(change.contents).byteLength
+    if (change.path === AGENT_MEMORY_ENTRY && bytes > AGENT_MEMORY_LIMITS.entryBytes) {
+      fail(
+        `${AGENT_MEMORY_ENTRY} is over ${kilobytes(AGENT_MEMORY_LIMITS.entryBytes)}, and it is part of every prompt. Move entries into topic files and link them.`
+      )
+    }
+    if (bytes > AGENT_MEMORY_LIMITS.fileBytes) {
+      fail(`file '${change.path}' is over ${kilobytes(AGENT_MEMORY_LIMITS.fileBytes)}.`)
+    }
+    files.set(change.path, change.contents)
+  }
+
+  if (!files.has(AGENT_MEMORY_ENTRY)) {
+    fail(`repo must keep its ${AGENT_MEMORY_ENTRY}.`)
+  }
+  let total = 0
+  for (const contents of files.values()) total += encoder.encode(contents).byteLength
+  if (total > AGENT_MEMORY_LIMITS.repoBytes) {
+    fail(
+      `repo would be over ${kilobytes(AGENT_MEMORY_LIMITS.repoBytes)}. Remove entries that are cheap to look up again.`
+    )
+  }
+
+  return [...files].map(([path, contents]) => ({ path, contents }))
+}
+
+/**
+ * Links in the repo's Markdown files that point at no file. A `[[target]]` names a path from the
+ * repo root, with `.md` left out and any other extension kept.
+ */
+export function findBrokenAgentMemoryLinks(
+  files: readonly AgentMemoryFile[]
+): AgentMemoryLinkWarning[] {
+  const paths = new Set(files.map((file) => file.path))
+  const warnings: AgentMemoryLinkWarning[] = []
+  for (const file of files) {
+    if (!file.path.endsWith(".md")) continue
+    for (const link of agentMemoryLinks(file.contents)) {
+      if (!paths.has(agentMemoryLinkPath(link))) warnings.push({ path: file.path, link })
+    }
+  }
+  return warnings.sort((left, right) =>
+    left.path === right.path ? compare(left.link, right.link) : compare(left.path, right.path)
+  )
+}
+
+/** The distinct `[[link]]` targets in a Markdown file, in the order they first appear. */
+export function agentMemoryLinks(contents: string): string[] {
+  const links = new Set<string>()
+  for (const match of contents.matchAll(/\[\[([^[\]\n]+)\]\]/g)) {
+    const link = match[1]?.trim()
+    if (link) links.add(link)
+  }
+  return [...links]
+}
+
+/** The file a link names: `.md` is added unless its last segment already has an extension. */
+export function agentMemoryLinkPath(link: string): string {
+  const name = link.slice(link.lastIndexOf("/") + 1)
+  return name.includes(".") ? link : `${link}.md`
+}
+
+function kilobytes(bytes: number): string {
+  return bytes >= 1024 * 1024 ? `${bytes / (1024 * 1024)} MB` : `${bytes / 1024} KB`
+}
+
+function compare(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0
+}

package/src/agents/message.ts

@@ -1,6 +1,11 @@
 import type { FileRef } from "../blob-storage"
 import type { JsonValue } from "../json"
 import type { ProviderData } from "../models"
+import type {
+  AgentApprovalCall,
+  AgentApprovalOutcome,
+  AgentApprovalStatus,
+} from "../storage/agents/types"
 import type { AgentContextPart } from "./context/entries"
 
 /**
@@ -68,6 +73,56 @@ export interface AgentContinuationPart {
   readonly type: "continuation"
 }
 
+/**
+ * How a call the Agent made in an earlier turn ended, once its requester decided on it or it was
+ * set aside. Sixb writes it at the start of the next user message; chats show no text for it.
+ */
+export interface AgentApprovalOutcomePart {
+  readonly type: "approval-outcome"
+  readonly approvalId: string
+  readonly status: Exclude<AgentApprovalStatus, "pending">
+  readonly call: AgentApprovalCallSummary
+  /** What the approved call gave, when it ran. */
+  readonly outcome?: AgentApprovalOutcome
+  /** The turn's sub-agent that made the call, when the turn did not make it itself. */
+  readonly caller?: AgentApprovalCaller
+}
+
+/** A turn's sub-agent that made a call: its run, and the key it was spawned with. */
+export interface AgentApprovalCaller {
+  readonly runId: string
+  readonly key: string
+  /** The message resumes the turn and the sub-agent paused on its calls: it goes on. */
+  readonly continues?: true
+}
+
+/** The call an approval held, as the model asked for it, without its params. */
+export type AgentApprovalCallSummary =
+  | Pick<Extract<AgentApprovalCall, { readonly kind: "action" }>, "kind" | "actionId" | "subject">
+  | Pick<Extract<AgentApprovalCall, { readonly kind: "workflow" }>, "kind" | "workflowId">
+
+/**
+ * A message a sub-agent read before its next step: today, its parent steering it, or answering the
+ * question it paused on. Sixb writes it in the sub-agent's thread, where the child read it; the
+ * model reads it as data from the sender, never from the user.
+ */
+export interface AgentMailPart {
+  readonly type: "mail"
+  /** The mail's id, the same in the sender's and the reader's records. */
+  readonly id: string
+  readonly from: "parent"
+  /** `answer`: the reply to the question it asked, `inReplyTo`. */
+  readonly kind: "message" | "answer"
+  /** The question an answer replies to. */
+  readonly inReplyTo?: string
+  readonly text: string
+  /**
+   * It came as the reader answered: the sender has not received that answer, so the reader writes
+   * its whole result again.
+   */
+  readonly afterAnswer?: true
+}
+
 /** Ordered, hidden provider state required to replay a model response losslessly. */
 export interface AgentProviderStatePart {
   readonly type: "provider-state"
@@ -93,6 +148,8 @@ export type AgentMessagePart =
   | AgentFilePart
   | AgentContextPart
   | AgentContinuationPart
+  | AgentApprovalOutcomePart
+  | AgentMailPart
   | AgentToolCallPart
   | AgentProviderStatePart
 

package/src/agents/model-loop.ts

@@ -59,6 +59,20 @@ interface ModelLoopOptions {
   readonly onEvent?: (event: ModelUiChunk) => void | Promise<void>
   readonly onModelCallEnd?: (event: ModelCallEndEvent) => void | Promise<void>
   readonly onStepEnd?: (step: ModelStep) => void | Promise<void>
+  /**
+   * Asked after each step that ran local tools, once `onStepEnd` settled: `true` ends the loop
+   * there, before the next provider call. Its tool results are the last thing the loop produced.
+   */
+  readonly pauseAfterStep?: (step: ModelStep) => boolean | Promise<boolean>
+  /**
+   * Asked when the model answers without local tools and a step is left, once `onStepEnd` settled,
+   * with that step's index. Messages it returns follow that answer in one more step, instead of the
+   * loop ending on it.
+   */
+  readonly beforeComplete?: (
+    step: ModelStep,
+    stepIndex: number
+  ) => readonly ModelMessage[] | undefined | Promise<readonly ModelMessage[] | undefined>
   readonly generateCallId?: () => string
 }
 
@@ -94,6 +108,15 @@ export type ModelLoopResult<TOutput = string> =
       readonly partialContent: readonly ModelAssistantPart[]
     }
 
+/** What a loop given `pauseAfterStep` returns: it may also stop after a step that ran tools. */
+export type PausableModelLoopResult<TOutput = string> =
+  | ModelLoopResult<TOutput>
+  /** `pauseAfterStep` stopped the loop after the last of these steps. */
+  | {
+      readonly status: "paused"
+      readonly steps: readonly ModelStep[]
+    }
+
 interface CompletedResponse {
   readonly providerIds?: import("../models/events").ModelProviderIds
   readonly content: readonly ModelAssistantPart[]
@@ -121,12 +144,15 @@ interface ParsedToolCall {
  * Completed steps and partial content contain validated JSON payloads and normalized provider
  * metadata. Trace adapters may project these results directly; storage owns write validation.
  */
+export function runModelLoop<TOutput = string>(
+  input: RunModelLoopInput<TOutput> & Required<Pick<ModelLoopOptions, "pauseAfterStep">>
+): Promise<PausableModelLoopResult<TOutput>>
 export function runModelLoop<TOutput = string>(
   input: RunModelLoopInput<TOutput>
 ): Promise<ModelLoopResult<TOutput>>
 export async function runModelLoop(
   input: RunModelLoopInput<unknown>
-): Promise<ModelLoopResult<unknown>> {
+): Promise<PausableModelLoopResult<unknown>> {
   assertLoopInput(input)
   const tools = indexTools(input.tools ?? [])
   const toolSpecifications = [...tools.values()].map<ModelToolSpecification>((tool) => ({
@@ -229,6 +255,7 @@ export async function runModelLoop(
           : estimate
         await input.onModelCallEnd?.({
           callId,
+          modelKind: "language",
           providerId: input.model.providerId,
           modelId: input.model.modelId,
           responseId: facts.responseId ?? `${callId}:response`,
@@ -246,17 +273,21 @@ export async function runModelLoop(
     if (input.signal.aborted && !accumulator.isFinished()) {
       return { status: "aborted", steps, partialContent: accumulator.partialContent() }
     }
-    const response = accumulator.complete()
-    const responseId = response.responseId ?? `${callId}:response`
+    const completed = accumulator.complete()
+    const responseId = completed.responseId ?? `${callId}:response`
     if (terminalStreamError) throw terminalStreamError.error
-    if (response.projectionError) throw response.projectionError
+    if (completed.projectionError) throw completed.projectionError
     if (input.signal.aborted) {
-      return { status: "aborted", steps, partialContent: response.content }
+      return { status: "aborted", steps, partialContent: completed.content }
     }
 
-    const localCalls = response.toolCalls.filter((call) => call.part.providerExecuted !== true)
     // Closed tool arguments are not proof of a successful response. In particular,
     // providers can close valid JSON before reporting truncation or content filtering.
+    // A response cut short by the output limit still ends the loop with what it produced:
+    // its local tool calls are dropped, never executed. Other unsuccessful finishes fail.
+    const response =
+      completed.finishReason === "length" ? withoutLocalToolCalls(completed) : completed
+    const localCalls = response.toolCalls.filter((call) => call.part.providerExecuted !== true)
     if (localCalls.length > 0 && !["stop", "tool-calls", "pause"].includes(response.finishReason)) {
       throw new ModelStreamError(
         `[SixbModels] Cannot execute local tools after '${response.finishReason}'.`
@@ -284,6 +315,25 @@ export async function runModelLoop(
       const step = modelStep(response, responseId, response.content, cost)
       steps.push(step)
       await input.onStepEnd?.(step)
+
+      // An answer cut short by the output limit ends the loop as it is.
+      const canContinue = response.finishReason !== "length" && stepIndex + 1 < input.maxSteps
+      let followUp: readonly ModelMessage[] | undefined
+      try {
+        followUp = canContinue ? await input.beforeComplete?.(step, stepIndex) : undefined
+      } catch (error) {
+        if (!input.signal.aborted && !isAbortError(error)) throw error
+        return { status: "aborted", steps, partialContent: [] }
+      }
+      if (followUp?.length) {
+        messages = [
+          ...requestMessages,
+          { role: "assistant", content: response.content },
+          ...followUp,
+        ]
+        continue
+      }
+
       if (input.output) {
         const text = responseText(response)
         if (response.finishReason !== "stop") {
@@ -333,6 +383,9 @@ export async function runModelLoop(
         partialContent: [],
       }
     }
+    if (await input.pauseAfterStep?.(step)) {
+      return { status: "paused", steps }
+    }
 
     const assistantContent = response.content.filter(
       (part) => part.type !== "tool-result" || part.providerExecuted === true
@@ -400,6 +453,22 @@ function indexTools(tools: readonly ModelTool[]): ReadonlyMap<string, ModelTool>
   return result
 }
 
+function withoutLocalToolCalls(response: CompletedResponse): CompletedResponse {
+  const dropped = new Set(
+    response.toolCalls
+      .filter((call) => call.part.providerExecuted !== true)
+      .map((call) => call.part.toolCallId)
+  )
+  if (dropped.size === 0) return response
+  return {
+    ...response,
+    content: response.content.filter(
+      (part) => part.type !== "tool-call" || !dropped.has(part.toolCallId)
+    ),
+    toolCalls: response.toolCalls.filter((call) => !dropped.has(call.part.toolCallId)),
+  }
+}
+
 function responseText(response: CompletedResponse): string {
   return response.content
     .filter((part): part is ModelTextPart => part.type === "text")
@@ -715,6 +784,7 @@ class StreamAccumulator {
     if (!this.finished || !this.finishReason) {
       throw new ModelStreamError("[SixbModels] Stream ended without a finish event.")
     }
+    if (this.finishReason === "length") this.settleTruncatedParts()
     for (const part of this.parts) {
       if ("complete" in part && !part.complete) {
         throw new ModelStreamError(
@@ -744,6 +814,23 @@ class StreamAccumulator {
     }
   }
 
+  /**
+   * The output limit explains spans a provider left open: streamed text and reasoning are kept as
+   * written, and an unfinished tool call is dropped, never executed.
+   */
+  private settleTruncatedParts(): void {
+    for (let index = this.parts.length - 1; index >= 0; index -= 1) {
+      const part = this.parts[index]
+      if (part === undefined || !("complete" in part) || part.complete) continue
+      if (part.type === "tool-call") {
+        this.parts.splice(index, 1)
+        this.toolCalls.delete(part.toolCallId)
+      } else {
+        part.complete = true
+      }
+    }
+  }
+
   partialContent(): readonly ModelAssistantPart[] {
     return this.parseParts(true).content
   }

package/src/agents/model-routing.ts

@@ -0,0 +1,193 @@
+import type {
+  DecisionModelsRuntime,
+  LanguageModelCatalog,
+  LanguageModelEntry,
+  LanguageModelTier,
+  LanguageModelTierProbabilities,
+  ModelCatalog,
+} from "../models"
+import { LANGUAGE_MODEL_TIERS } from "../models/catalog"
+import { question } from "../models/decision/questions"
+import { supportsQuestion } from "../models/decision/validation"
+import { RuntimeError } from "../runtime/errors"
+import type { ConversationAgentRunRecord } from "../storage/agents"
+
+/** Moving up needs no confidence: a turn goes to `heavy` from this probability. */
+const HEAVY_FROM = 0.4
+
+/** Moving down does: a turn goes to `light` only from this probability. */
+const LIGHT_FROM = 0.8
+
+/**
+ * How long a turn waits for its tier before it aims for `standard`. Jev answers in about 150 ms;
+ * the margin covers a gateway's slow start, and every millisecond delays the answer's first token.
+ */
+const DECISION_TIMEOUT_MS = 2_000
+
+/** How long a provider keeps a thread's prompt cache after the last call that read it. */
+const PROMPT_CACHE_TTL_MS = 5 * 60_000
+
+const TIER_QUESTIONS = {
+  tier: question.choice({
+    instructions:
+      "A user sent this message to a data agent. The agent answers from the project's data with " +
+      "tools: it searches and reads objects, queries and aggregates datasets, follows links, runs " +
+      "actions and writes reports. Pick the model tier the answer needs. Judge the work the " +
+      "answer takes, not the length or tone of the message.",
+    options: {
+      light:
+        "A lookup, a count, a filter or a list: one or two queries with an obvious answer. " +
+        "Greetings, thanks and short follow-ups.",
+      standard:
+        "Usual analysis: several queries, comparisons, trends or aggregations, a short summary, " +
+        "or a simple action, with a clear path to the answer.",
+      heavy:
+        "Open-ended work: a multi-step investigation, explaining why something happened, " +
+        "weighing trade-offs, building a plan, or writing a long report.",
+    },
+  }),
+}
+
+export interface TurnModelChoice {
+  readonly model: LanguageModelEntry
+  /** The decision model's answer; absent when it failed and the turn aimed for `standard`. */
+  readonly tierProbabilities?: LanguageModelTierProbabilities
+}
+
+export interface TurnModelRouter {
+  /** The model of a turn that names none, given the thread's previous turn. */
+  choose(text: string, previous: ConversationAgentRunRecord | undefined): Promise<TurnModelChoice>
+}
+
+/**
+ * With tiers, the default decision model picks the tier of each turn, so it must take the question.
+ * Checked at startup: a model that cannot would leave every turn on `standard`, warning each time.
+ */
+export function assertTurnModelRouting(models: ModelCatalog | undefined): void {
+  const tiers = models?.language?.tiers ?? []
+  const decision = models?.decision?.default
+  if (tiers.length === 0 || !decision) return
+  if (supportsQuestion(decision.model.definition.capabilities, TIER_QUESTIONS.tier)) return
+
+  throw new RuntimeError(
+    `[Sixb] The default decision model '${decision.provider}/${decision.modelId}' cannot pick the tier of an Agent turn: it needs 'choice' questions with ${LANGUAGE_MODEL_TIERS.length} options. Put a decision model that supports them first in 'models.decision', or configure 'models.language' as a list.`
+  )
+}
+
+/** Sixb picks the model of each turn when the project configures tiers and a decision model. */
+export function createTurnModelRouter(
+  models: ModelCatalog | undefined,
+  decision: DecisionModelsRuntime
+): TurnModelRouter | undefined {
+  const language = models?.language
+  if (!language || language.tiers.length === 0 || !models?.decision) return undefined
+
+  return {
+    async choose(text, previous) {
+      const tierProbabilities = await askTier(decision, text)
+      const tier = tierProbabilities ? tierFor(tierProbabilities) : "standard"
+
+      return {
+        model: turnModel(language, tier, previous),
+        ...(tierProbabilities ? { tierProbabilities } : {}),
+      }
+    },
+  }
+}
+
+/** The decision model's answer, or nothing when it fails or is too slow. */
+async function askTier(
+  decision: DecisionModelsRuntime,
+  text: string
+): Promise<LanguageModelTierProbabilities | undefined> {
+  const timeout = new AbortController()
+  const timer = setTimeout(() => {
+    timeout.abort(
+      new DOMException("[Sixb] The decision model did not answer in time.", "TimeoutError")
+    )
+  }, DECISION_TIMEOUT_MS)
+
+  try {
+    // The race holds the turn to its timeout even when a provider ignores the signal.
+    const { output } = await Promise.race([
+      decision.evaluate({ input: text, questions: TIER_QUESTIONS, signal: timeout.signal }),
+      rejectOnAbort(timeout.signal),
+    ])
+    const { light, standard, heavy } = output.tier.probabilities
+    return { light, standard, heavy }
+  } catch (error) {
+    // The request's own cancellation still cancels the message.
+    if (!timeout.signal.aborted && isAbortError(error)) throw error
+
+    console.warn(
+      "[Sixb] Could not pick the tier of an Agent turn; it aims for standard, and the cache rule still applies.",
+      error
+    )
+    return undefined
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/** Moving down needs confidence; moving up doesn't. */
+function tierFor(probabilities: LanguageModelTierProbabilities): LanguageModelTier {
+  if (probabilities.heavy >= HEAVY_FROM) return "heavy"
+  if (probabilities.light >= LIGHT_FROM) return "light"
+  return "standard"
+}
+
+/**
+ * Switching models drops the prompt cache, so the thread stays on its model unless the switch is
+ * free: a harder turn always moves up, an easier one moves down only once the cache is cold.
+ */
+function turnModel(
+  language: LanguageModelCatalog,
+  tier: LanguageModelTier,
+  previous: ConversationAgentRunRecord | undefined
+): LanguageModelEntry {
+  const target = language.getByTier(tier)
+  const last = previous && previousTurn(language, previous)
+  if (!last) return target
+
+  const change = tierRank(target.tier ?? tier) - tierRank(last.tier)
+  if (change > 0 || last.model === null) return target
+  if (change === 0 || last.cacheWarm) return last.model
+  return target
+}
+
+interface PreviousTurn {
+  /** Null once the model has left the catalog. */
+  readonly model: LanguageModelEntry | null
+  readonly tier: LanguageModelTier
+  readonly cacheWarm: boolean
+}
+
+/** An older run without a tier takes its model's; one without either counts as no turn at all. */
+function previousTurn(
+  language: LanguageModelCatalog,
+  run: ConversationAgentRunRecord
+): PreviousTurn | undefined {
+  if (!run.spec) return undefined
+
+  const model = language.getByRef(run.spec.model)
+  const tier = run.spec.tier ?? model?.tier
+  if (tier === undefined) return undefined
+
+  // A run that never recorded its end counts from its start, or from its admission.
+  const lastCallAt = run.completedAt ?? run.startedAt ?? run.createdAt
+  return { model, tier, cacheWarm: Date.now() - lastCallAt.getTime() < PROMPT_CACHE_TTL_MS }
+}
+
+function tierRank(tier: LanguageModelTier): number {
+  return LANGUAGE_MODEL_TIERS.indexOf(tier)
+}
+
+function rejectOnAbort(signal: AbortSignal): Promise<never> {
+  return new Promise((_, reject) => {
+    signal.addEventListener("abort", () => reject(signal.reason), { once: true })
+  })
+}
+
+function isAbortError(error: unknown): boolean {
+  return (error instanceof DOMException || error instanceof Error) && error.name === "AbortError"
+}