@sixb/core 0.1.21 → 0.1.22

package/src/agents/request.ts

@@ -11,12 +11,19 @@ import {
 import { resolveExecutionScopeAuthorization } from "../execution/authorization"
 import { ensureExecutionRecord, executionRecordInputFromRuntime } from "../execution/durable"
 import type { ExecutionContext } from "../execution/types"
-import type { LanguageModelCatalog, LanguageModelEntry, LanguageModelRef } from "../models"
+import type {
+  LanguageModelCatalog,
+  LanguageModelEntry,
+  LanguageModelRef,
+  LanguageModelTierProbabilities,
+} from "../models"
 import { isModelReasoning, modelReasoningSupportIssue } from "../models/language-model"
 import { resolveLanguageModel } from "../models/resolve"
 import { canonicalLocale, canonicalTimeZone } from "../runtime/locale"
 import type { SixbRuntimeContext } from "../runtime/types"
 import {
+  type AgentApprovalMode,
+  type AgentApprovalRecord,
   type AgentStorage,
   AgentStorageError,
   type AgentThreadRecord,
@@ -31,14 +38,27 @@ import {
 } from "../storage/ai-limits/enforcement"
 import type { AiLimitPolicyStatus } from "../storage/ai-limits/types"
 import type { ExecutionRecord } from "../storage/executions"
+import {
+  type AgentTurnReadiness,
+  announceAgentApprovals,
+  assertAgentApprovalMode,
+  isAwaitingApprovalRun,
+  listTurnApprovals,
+  reportAgentApprovals,
+  reportSettledAgentApprovals,
+  resolveAgentApprovalMode,
+  turnResumeReadiness,
+} from "./approvals"
 import type { AgentContextEntryInput } from "./context/entries"
 import { resolveAgentContextParts } from "./context-resolution"
 import { dispatchQueuedAgentRuns } from "./dispatch"
 import { AgentRequestError } from "./errors"
 import { createAgentMessageId, createAgentRunId, createAgentThreadId } from "./ids"
 import type { AgentMessagePart } from "./message"
+import type { TurnModelRouter } from "./model-routing"
 import { assertNoAgentSelector } from "./retired-config"
 import { publishAgentRunActivity } from "./streams/protocol"
+import { assertConversationThread } from "./thread-access"
 import { AGENT_REASONING_LEVELS, type AgentReasoning } from "./types"
 
 export interface RequestAgentRunInput {
@@ -66,6 +86,11 @@ export interface RequestAgentRunInput {
   readonly timeZone?: string
   /** BCP 47 language of the person asking. Omitted uses the project locale. */
   readonly locale?: string
+  /**
+   * What the turn may change without asking whoever sent it. Omitted uses their choice in the
+   * thread, then their default, then `auto`.
+   */
+  readonly approvalMode?: AgentApprovalMode
   /** Title to stamp on the thread when one is created. */
   readonly title?: string
   /** Explicit id for the trigger (user) message. Defaults to a generated id. */
@@ -74,6 +99,13 @@ export interface RequestAgentRunInput {
   readonly principal?: Principal
 }
 
+/** What a turn's model is chosen from. */
+export interface AgentRequestModels {
+  readonly language?: LanguageModelCatalog
+  /** Picks the model of a turn that names none; absent without tiers and `models.decision`. */
+  readonly router?: TurnModelRouter
+}
+
 export interface RequestAgentRunResult {
   /** The durable queued run exactly as it was created (`status: "queued"`, attempt 0). */
   readonly run: ConversationAgentRunRecord
@@ -94,7 +126,7 @@ export interface RequestAgentRunResult {
 export async function requestAgentRun(
   runtime: SixbRuntimeContext,
   execution: ExecutionContext,
-  models: LanguageModelCatalog | undefined,
+  models: AgentRequestModels,
   input: RequestAgentRunInput
 ): Promise<RequestAgentRunResult> {
   const authority = resolveExecutionScopeAuthorization(runtime.projectId, {
@@ -105,15 +137,19 @@ export async function requestAgentRun(
   assertAuthorized(runtime, { kind: "agent.run" })
   assertRequestAuthorityCanRunAgent(runtime)
   const trigger = triggerParts(input)
-  const continued = input.continue ? await continuedSelection(runtime, models, input) : {}
-  const spec = await resolveConversationRunSpec({
-    models,
-    input: {
-      ...input,
-      model: input.model ?? continued.model,
-      reasoning: input.reasoning ?? continued.reasoning,
-    },
-  })
+  const continued = input.continue ? await continuedSelection(runtime, models.language, input) : {}
+  const selection = {
+    model: input.model ?? continued.model,
+    reasoning: input.reasoning ?? continued.reasoning,
+  }
+  const settings = requesterSettings(input)
+  if (input.approvalMode !== undefined) assertAgentApprovalMode(input.approvalMode)
+
+  // Any other turn's spec is checked now, before anything is written. A routed turn holds its
+  // router until its model is picked, last.
+  const routed = routedTurn(models.router, selection, input.text)
+  const requested =
+    routed ?? (await resolveConversationRunSpec({ models: models.language, selection, settings }))
   assertAttachments(input.attachments)
 
   // Resolve context before creating a thread: invalid or inaccessible references must not leave an
@@ -133,23 +169,44 @@ export async function requestAgentRun(
   const durableExecution = await prepareDurableAgentExecution(runtime, execution, runId)
   await assertAiLimitPreflight(runtime, durableExecution)
 
-  const { thread, createdThread } = await resolveThread(agents, {
-    projectId,
-    threadId: input.threadId,
-    title: input.title,
-    principal,
-  })
+  const existingThread = input.threadId
+    ? await agents.threads.getById({ projectId, id: input.threadId })
+    : null
+  if (existingThread) assertThreadAcceptsRun(existingThread)
+  // The message's mode, else the sender's in the thread.
+  const approvalMode =
+    input.approvalMode ??
+    (await resolveAgentApprovalMode(agents, { projectId, principal, threadId: existingThread?.id }))
+      .approvalMode
+
+  // Last before anything is written, so a message the checks above refuse never reaches the
+  // decision model. Concurrent messages to an idle thread can still each ask before one of them is
+  // refused with `active_run_exists` below.
+  const selected =
+    "router" in requested
+      ? await routedConversationRunSpec(agents, {
+          ...requested,
+          projectId,
+          threadId: existingThread?.id,
+          settings,
+          language: models.language,
+        })
+      : requested
+  const spec: ConversationAgentRunSpec = Object.freeze({ ...selected, approvalMode })
+
+  const createdThread = existingThread === null
+  const thread =
+    existingThread ??
+    (await createThread(agents, {
+      projectId,
+      threadId: input.threadId,
+      title: input.title,
+      principal,
+    }))
 
-  assertSandboxExecutionAvailable(thread)
-  // Fast single-flight check for a clear error. `runs.create` below is the atomic authority.
-  if (thread.activeRunId !== null) {
-    throw new AgentRequestError(
-      "active_run_exists",
-      `[Sixb] Agent thread '${thread.id}' already has an active run '${thread.activeRunId}'.`
-    )
-  }
   const triggerMessageId = input.messageId ?? createAgentMessageId()
   let run: ConversationAgentRunRecord
+  let superseded: readonly AgentApprovalRecord[] = []
   try {
     run = await runtime.storage.transaction(async (tx) => {
       const agents = tx.agents
@@ -160,6 +217,16 @@ export async function requestAgentRun(
         )
       }
       await tx.executions.create(durableExecution)
+      // The model learns, once, how the calls it made earlier ended: the ones still waiting are
+      // set aside by this message.
+      const reported = createdThread
+        ? { parts: [], superseded: [] }
+        : await reportAgentApprovals(agents, {
+            projectId,
+            threadId: thread.id,
+            messageId: triggerMessageId,
+          })
+      superseded = reported.superseded
       await agents.messages.append({
         id: triggerMessageId,
         projectId,
@@ -167,6 +234,7 @@ export async function requestAgentRun(
         runId: null,
         role: "user",
         parts: [
+          ...reported.parts,
           ...contextParts,
           ...trigger,
           ...(input.attachments ?? []).map((fileRef) => ({ type: "file" as const, fileRef })),
@@ -189,6 +257,7 @@ export async function requestAgentRun(
     throw error
   }
 
+  await announceAgentApprovals(runtime.broker, superseded)
   await publishRunActivity(runtime, run)
   const jobId = await dispatchAgentRun(runtime, agents, runId)
 
@@ -253,11 +322,14 @@ export async function retryAgentRun(
       threadId: failedRun.threadId,
       runId: failedRun.id,
     })
-    // What the failed turn published goes with what it said, so the retry starts clean.
-    await tx.artifacts?.deleteVersionsByOrigin({
-      projectId: runtime.projectId,
-      runId: failedRun.id,
-    })
+    // What the failed turn published goes with what it said, so the retry starts clean. Its
+    // children published into the thread too, each as its own run.
+    const artifacts = tx.artifacts
+    if (artifacts) {
+      for (const publishedBy of [failedRun.id, ...(await childRunIds(agents, failedRun))]) {
+        await artifacts.deleteVersionsByOrigin({ projectId: runtime.projectId, runId: publishedBy })
+      }
+    }
     await tx.executions.create(durableExecution)
     return agents.runs.create({
       id: runId,
@@ -267,10 +339,7 @@ export async function retryAgentRun(
       triggerMessageId: failedRun.triggerMessageId,
       spec:
         failedRun.spec ??
-        (await resolveConversationRunSpec({
-          models,
-          input: {},
-        })),
+        (await resolveConversationRunSpec({ models, selection: {}, settings: {} })),
     })
   })
   await publishRunActivity(runtime, run)
@@ -278,6 +347,197 @@ export async function retryAgentRun(
   return { run, ...(jobId ? { jobId } : {}), createdThread: false }
 }
 
+/** Where a resume left a paused turn. */
+export type AgentTurnResume =
+  | { readonly status: "resumed"; readonly run: ConversationAgentRunRecord }
+  | { readonly status: Exclude<AgentTurnReadiness, "ready"> }
+
+/**
+ * Resume a turn that paused on held calls, once its requester decided on all of them: a new turn
+ * with the paused one's spec and the given mode, whose trigger message carries how each call ended,
+ * and that the chat shows no text for. It checks what a retry checks, and throws what a retry
+ * throws; there are no words for Sixb to pick a model from.
+ *
+ * It writes nothing while a call still waits or an approved one has not run (`waiting`), and once
+ * the turn cannot resume (`closed`): a call was set aside, the turn was stopped or resumed already,
+ * or a message moved the thread on.
+ */
+export async function resumeAgentTurn(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  models: LanguageModelCatalog | undefined,
+  pausedRun: ConversationAgentRunRecord,
+  input: { readonly approvalMode: AgentApprovalMode; readonly principal?: Principal }
+): Promise<AgentTurnResume> {
+  const authority = resolveExecutionScopeAuthorization(runtime.projectId, {
+    execution,
+    authorization: runtime.runtimeAuthorization,
+  })
+  if (!isAwaitingApprovalRun(pausedRun)) return { status: "closed" }
+
+  const agents = requireAgentStorage(runtime)
+  const projectId = runtime.projectId
+  const scope = { projectId, runId: pausedRun.id }
+  // Read first, so a decision that leaves calls waiting never meets a check below.
+  const readiness = turnResumeReadiness(await listTurnApprovals(agents, scope))
+  if (readiness !== "ready") return { status: readiness }
+
+  assertAuthorized(runtime, { kind: "agent.run" })
+  assertRequestAuthorityCanRunAgent(runtime)
+  const thread = await agents.threads.getById({ projectId, id: pausedRun.threadId })
+  if (!thread) {
+    throw new AgentRequestError(
+      "thread_not_found",
+      `[Sixb] Agent thread '${pausedRun.threadId}' was not found.`
+    )
+  }
+  assertSandboxExecutionAvailable(thread)
+
+  const runId = createAgentRunId()
+  const durableExecution = await prepareResumedExecution(runtime, execution, runId)
+  await assertAiLimitPreflight(runtime, durableExecution)
+  const spec = await resumedConversationRunSpec(models, pausedRun.spec, input.approvalMode)
+  const principal =
+    authority.type === "principal"
+      ? authority.context.principal
+      : (input.principal ?? SYSTEM_PRINCIPAL)
+  const triggerMessageId = createAgentMessageId()
+
+  let run: ConversationAgentRunRecord
+  try {
+    run = await runtime.storage.transaction(async (tx) => {
+      const agents = tx.agents
+      if (!agents) {
+        throw new AgentRequestError(
+          "storage_unavailable",
+          "[Sixb] Agent storage is not configured."
+        )
+      }
+      // Checked again where it is written: a message sent meanwhile moved the thread on.
+      const latest = await latestConversationRun(agents, projectId, pausedRun.threadId)
+      if (latest?.id !== pausedRun.id) throw new TurnClosed()
+      const approvals = await listTurnApprovals(agents, scope)
+      if (turnResumeReadiness(approvals) !== "ready") throw new TurnClosed()
+
+      // The report's compare-and-swap lets one of two racing final decisions resume the turn, and
+      // a stop that lands first keeps it from resuming.
+      const parts = await reportSettledAgentApprovals(agents, {
+        projectId,
+        threadId: pausedRun.threadId,
+        messageId: triggerMessageId,
+        resuming: true,
+      })
+      const reported = new Set(parts.map((part) => part.approvalId))
+      const unreported = approvals.filter((approval) => approval.reportedInMessageId === undefined)
+      if (!unreported.every((approval) => reported.has(approval.id))) throw new TurnClosed()
+
+      await tx.executions.create(durableExecution)
+      await agents.messages.append({
+        id: triggerMessageId,
+        projectId,
+        threadId: pausedRun.threadId,
+        runId: null,
+        role: "user",
+        parts,
+        authorPrincipal: principal,
+      })
+      return agents.runs.create({
+        id: runId,
+        projectId,
+        executionId: durableExecution.id,
+        threadId: pausedRun.threadId,
+        triggerMessageId,
+        spec,
+      })
+    })
+  } catch (error) {
+    if (error instanceof TurnClosed) return { status: "closed" }
+    // Another turn took the thread first; its message reports what this one would have.
+    if (error instanceof AgentStorageError && error.code === "active_run_exists") {
+      return { status: "closed" }
+    }
+    throw error
+  }
+
+  await publishRunActivity(runtime, run)
+  await dispatchAgentRun(runtime, agents, runId)
+  return { status: "resumed", run }
+}
+
+/** Rolls the resume's transaction back: the turn cannot resume. */
+class TurnClosed extends Error {
+  constructor() {
+    super("[Sixb] The paused Agent turn can no longer resume.")
+  }
+}
+
+/**
+ * A resumed turn's execution. From a request, it is that request's child, like a retry. From the
+ * paused turn's own execution, as the worker resumes it, it is a sibling of the paused turn: a
+ * child of the request that started it, so that resumes never nest.
+ */
+async function prepareResumedExecution(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  runId: string
+): Promise<Omit<ExecutionRecord, "createdAt">> {
+  if (execution.executor.type !== "agent" || execution.source.type !== "execution") {
+    return prepareDurableAgentExecution(runtime, execution, runId)
+  }
+
+  const parent = await runtime.storage.executions.getById({
+    projectId: runtime.projectId,
+    id: execution.source.executionId,
+  })
+  if (!parent) {
+    throw new AgentRequestError(
+      "authority_not_inheritable",
+      `[Sixb] Agent execution '${execution.id}' has no parent to resume under.`
+    )
+  }
+  return createInheritedAgentExecutionRecord({ id: `exec_${randomUUID()}`, parent, runId })
+}
+
+/** The paused turn's spec, with defaults for a model that has since left the catalog. */
+async function resumedConversationRunSpec(
+  models: LanguageModelCatalog | undefined,
+  paused: ConversationAgentRunSpec | undefined,
+  approvalMode: AgentApprovalMode
+): Promise<ConversationAgentRunSpec> {
+  const kept =
+    paused && models?.getByRef(paused.model)
+      ? paused
+      : await resolveConversationRunSpec({
+          models,
+          selection: {},
+          settings: {
+            ...(paused?.timeZone === undefined ? {} : { timeZone: paused.timeZone }),
+            ...(paused?.locale === undefined ? {} : { locale: paused.locale }),
+          },
+        })
+  return Object.freeze({ ...kept, approvalMode })
+}
+
+/** Every child a turn spawned, whatever its status. */
+async function childRunIds(
+  agents: AgentStorage,
+  parent: ConversationAgentRunRecord
+): Promise<string[]> {
+  const ids: string[] = []
+  for (;;) {
+    const page = await agents.runs.list({
+      projectId: parent.projectId,
+      kinds: ["subagent"],
+      parentRunId: parent.id,
+      order: "asc",
+      limit: 100,
+      offset: ids.length,
+    })
+    ids.push(...page.runs.map((run) => run.id))
+    if (!page.hasMore || page.runs.length === 0) return ids
+  }
+}
+
 /**
  * A continuation picks up where the cut-short turn stopped, with its model and reasoning unless the
  * request chooses others. A model that has since left the catalog falls back to the defaults.
@@ -296,19 +556,71 @@ async function continuedSelection(
     )
   }
   if (input.model !== undefined || input.reasoning !== undefined) return {}
+  const spec = (await latestConversationRun(agents, runtime.projectId, threadId))?.spec
+  if (!spec || !models?.getByRef(spec.model)) return {}
+  return {
+    model: spec.model,
+    ...(spec.reasoning === undefined ? {} : { reasoning: spec.reasoning }),
+  }
+}
+
+/** A turn Sixb picks the model of, with the words it judges. */
+interface RoutedTurn {
+  readonly router: TurnModelRouter
+  readonly text: string
+}
+
+/**
+ * Naming a model or a reasoning opts a turn out of routing: it runs that model, or the default, as
+ * chosen. A continuation has no text to judge, and keeps the cut-short turn's model.
+ */
+function routedTurn(
+  router: TurnModelRouter | undefined,
+  selection: Pick<RequestAgentRunInput, "model" | "reasoning">,
+  text: string | undefined
+): RoutedTurn | undefined {
+  if (!router || text === undefined) return undefined
+  if (selection.model !== undefined || selection.reasoning !== undefined) return undefined
+
+  return { router, text }
+}
+
+/** The spec of a turn Sixb picks the model for, compared to the thread's previous turn. */
+async function routedConversationRunSpec(
+  agents: AgentStorage,
+  input: RoutedTurn & {
+    readonly projectId: string
+    readonly threadId: string | undefined
+    readonly settings: RequesterSettings
+    readonly language: LanguageModelCatalog | undefined
+  }
+): Promise<ConversationAgentRunSpec> {
+  const previous = input.threadId
+    ? await latestConversationRun(agents, input.projectId, input.threadId)
+    : undefined
+  const choice = await input.router.choose(input.text, previous)
+
+  return resolveConversationRunSpec({
+    models: input.language,
+    selection: { model: choice.model },
+    settings: input.settings,
+    tierProbabilities: choice.tierProbabilities,
+  })
+}
+
+async function latestConversationRun(
+  agents: AgentStorage,
+  projectId: string,
+  threadId: string
+): Promise<ConversationAgentRunRecord | undefined> {
   const { runs } = await agents.runs.list({
-    projectId: runtime.projectId,
+    projectId,
     threadId,
     kinds: ["conversation"],
     order: "desc",
     limit: 1,
   })
-  const spec = runs[0]?.kind === "conversation" ? runs[0].spec : undefined
-  if (!spec || !models?.getByRef(spec.model)) return {}
-  return {
-    model: spec.model,
-    ...(spec.reasoning === undefined ? {} : { reasoning: spec.reasoning }),
-  }
+  return runs[0]?.kind === "conversation" ? runs[0] : undefined
 }
 
 /** The words of the user, or the continuation Sixb words for them. */
@@ -342,6 +654,18 @@ function assertAttachments(attachments: readonly FileRef[] | undefined): void {
   }
 }
 
+function assertThreadAcceptsRun(thread: AgentThreadRecord): void {
+  assertConversationThread(thread)
+  assertSandboxExecutionAvailable(thread)
+  // Fast single-flight check for a clear error. `runs.create` is the atomic authority.
+  if (thread.activeRunId !== null) {
+    throw new AgentRequestError(
+      "active_run_exists",
+      `[Sixb] Agent thread '${thread.id}' already has an active run '${thread.activeRunId}'.`
+    )
+  }
+}
+
 function assertSandboxExecutionAvailable(thread: AgentThreadRecord): void {
   if (thread.sandboxState && !["new", "ready"].includes(thread.sandboxState.status)) {
     throw new AgentRequestError(
@@ -391,7 +715,10 @@ async function assertAiLimitPreflight(
  */
 async function resolveConversationRunSpec(input: {
   readonly models?: LanguageModelCatalog
-  readonly input: Pick<RequestAgentRunInput, "model" | "reasoning" | "timeZone" | "locale">
+  readonly selection: Pick<RequestAgentRunInput, "model" | "reasoning">
+  readonly settings: RequesterSettings
+  /** The decision model's answer, when Sixb picked the model. */
+  readonly tierProbabilities?: LanguageModelTierProbabilities
 }): Promise<ConversationAgentRunSpec> {
   if (!input.models) {
     throw new AgentRequestError(
@@ -399,7 +726,7 @@ async function resolveConversationRunSpec(input: {
       "[Sixb] Configure models.language before starting the Agent."
     )
   }
-  const selected = input.input.model ?? input.models.default
+  const selected = input.selection.model ?? input.models.default
   const model = input.models.getByRef(selected)
   if (model === null) {
     throw new AgentRequestError(
@@ -408,30 +735,43 @@ async function resolveConversationRunSpec(input: {
     )
   }
 
-  const explicitReasoning = input.input.reasoning
+  const explicitReasoning = input.selection.reasoning
   if (explicitReasoning !== undefined) {
     await assertModelSupportsReasoning(model, explicitReasoning)
   }
   const reasoning = explicitReasoning ?? model.model.defaultReasoning
+  const { timeZone, locale } = input.settings
+
+  return Object.freeze({
+    model: Object.freeze({ provider: selected.provider, modelId: selected.modelId }),
+    ...(model.tier === undefined ? {} : { tier: model.tier }),
+    ...(input.tierProbabilities === undefined
+      ? {}
+      : { tierProbabilities: Object.freeze({ ...input.tierProbabilities }) }),
+    ...(reasoning === undefined ? {} : { reasoning }),
+    ...(timeZone === undefined ? {} : { timeZone }),
+    ...(locale === undefined ? {} : { locale }),
+  })
+}
+
+/** Canonical settings of the person asking, as the run spec stores them. */
+type RequesterSettings = Pick<ConversationAgentRunSpec, "timeZone" | "locale">
+
+function requesterSettings(
+  input: Pick<RequestAgentRunInput, "timeZone" | "locale">
+): RequesterSettings {
   const timeZone = requestedSetting(
     "timeZone",
-    input.input.timeZone,
+    input.timeZone,
     canonicalTimeZone,
     "an IANA time zone"
   )
-  const locale = requestedSetting(
-    "locale",
-    input.input.locale,
-    canonicalLocale,
-    "a BCP 47 language tag"
-  )
+  const locale = requestedSetting("locale", input.locale, canonicalLocale, "a BCP 47 language tag")
 
-  return Object.freeze({
-    model: Object.freeze({ provider: selected.provider, modelId: selected.modelId }),
-    ...(reasoning === undefined ? {} : { reasoning }),
+  return {
     ...(timeZone === undefined ? {} : { timeZone }),
     ...(locale === undefined ? {} : { locale }),
-  })
+  }
 }
 
 function requestedSetting(
@@ -543,7 +883,7 @@ async function publishRunActivity(
   }
 }
 
-async function resolveThread(
+function createThread(
   agents: AgentStorage,
   params: {
     readonly projectId: string
@@ -551,24 +891,13 @@ async function resolveThread(
     readonly title?: string
     readonly principal: Principal
   }
-): Promise<{ thread: AgentThreadRecord; createdThread: boolean }> {
-  if (params.threadId) {
-    const existing = await agents.threads.getById({
-      projectId: params.projectId,
-      id: params.threadId,
-    })
-    if (existing) {
-      return { thread: existing, createdThread: false }
-    }
-  }
-
-  const thread = await agents.threads.create({
+): Promise<AgentThreadRecord> {
+  return agents.threads.create({
     id: params.threadId ?? createAgentThreadId(),
     projectId: params.projectId,
     ownerPrincipal: params.principal,
     ...(params.title === undefined ? {} : { title: params.title }),
   })
-  return { thread, createdThread: true }
 }
 
 function requireAgentStorage(runtime: SixbRuntimeContext): AgentStorage {