@sixb/core 0.1.21 → 0.1.22

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"
+}

package/src/agents/participants.ts

@@ -0,0 +1,213 @@
+import { principalsEqual, type UserPrincipal } from "../auth"
+import { userReferenceProblem } from "../ontology/user-ref"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { SecurityDefinitionCatalog } from "../security"
+import {
+  type AgentStorage,
+  AgentStorageError,
+  type AgentThreadParticipantRecord,
+} from "../storage/agents"
+import { announceAgentApprovals } from "./approvals"
+import { userCanRunAgent } from "./authority"
+import { AgentRequestError } from "./errors"
+import {
+  type AgentThreadAccessRule,
+  type AgentThreadView,
+  assertConversationThread,
+} from "./thread-access"
+
+/** At most this many users take part in one conversation, besides its owner. */
+export const MAX_AGENT_THREAD_PARTICIPANTS = 50
+
+/** A user to add: by id, or by the email of their account. */
+export type AgentThreadParticipantInput = UserPrincipal | { readonly email: string }
+
+/** Add users to a conversation. Only its owner may, and only active users of the project. */
+export async function addAgentThreadParticipants(
+  runtime: SixbRuntimeContext,
+  rule: AgentThreadAccessRule,
+  security: SecurityDefinitionCatalog,
+  threadId: string,
+  users: readonly AgentThreadParticipantInput[]
+): Promise<AgentThreadView> {
+  const storage = requireStorage(runtime)
+  const readable = await rule.read(threadId)
+  if (!readable) throw threadNotFound(threadId)
+  // A sub-agent's thread is read by its conversation's participants.
+  assertConversationThread(readable.thread)
+
+  if (readable.access !== "owner") {
+    throw new AgentRequestError(
+      "not_thread_owner",
+      `[Sixb] Only the owner of Agent thread '${threadId}' can add participants to it.`
+    )
+  }
+
+  const principals = await activeUsers(runtime, security, users)
+  if (principals.some((user) => principalsEqual(user, readable.thread.ownerPrincipal))) {
+    throw invalidParticipant("The thread's owner already takes part in it; add other users.")
+  }
+
+  let participants: readonly AgentThreadParticipantRecord[]
+  try {
+    participants = await storage.threads.addParticipants({
+      projectId: runtime.projectId,
+      threadId,
+      principals,
+      addedBy: rule.caller,
+      maxParticipants: MAX_AGENT_THREAD_PARTICIPANTS,
+    })
+  } catch (error) {
+    if (error instanceof AgentStorageError && error.code === "participant_limit") {
+      throw invalidParticipant(
+        `An Agent thread can have at most ${MAX_AGENT_THREAD_PARTICIPANTS} participants.`
+      )
+    }
+    throw error
+  }
+
+  return {
+    ...readable.thread,
+    participants: participants.map(({ principal, addedAt, addedBy }) => ({
+      principal,
+      addedAt,
+      addedBy,
+    })),
+  }
+}
+
+/**
+ * Remove a user from a conversation. Its owner removes anyone; a participant removes only
+ * themself, which is how they leave. Removing someone who does not take part changes nothing.
+ */
+export async function removeAgentThreadParticipant(
+  runtime: SixbRuntimeContext,
+  rule: AgentThreadAccessRule,
+  threadId: string,
+  user: UserPrincipal
+): Promise<void> {
+  requireStorage(runtime)
+  const readable = await rule.read(threadId)
+  if (!readable) throw threadNotFound(threadId)
+  assertConversationThread(readable.thread)
+
+  const principal = userOf(user)
+
+  if (principalsEqual(principal, readable.thread.ownerPrincipal)) {
+    throw invalidParticipant("The thread's owner cannot be removed from it.")
+  }
+  if (readable.access !== "owner" && !principalsEqual(principal, rule.caller)) {
+    throw new AgentRequestError(
+      "not_thread_owner",
+      `[Sixb] Only the owner of Agent thread '${threadId}' can remove other participants.`
+    )
+  }
+
+  // Their turns never resume: the calls still waiting are cancelled, and the thread's next message
+  // reports what they decided.
+  const { cancelled } = await runtime.storage.transaction(async (tx) => {
+    const agents = tx.agents
+    if (!agents) {
+      throw new AgentRequestError("storage_unavailable", "[Sixb] Agent storage is not configured.")
+    }
+    await agents.threads.removeParticipant({ projectId: runtime.projectId, threadId, principal })
+    return agents.approvals.stop({ projectId: runtime.projectId, threadId, requestedBy: principal })
+  })
+  await announceAgentApprovals(runtime.broker, cancelled)
+}
+
+/**
+ * Each user once, by their account: an email resolves to its user. The only place that checks who
+ * may take part: storage receives distinct users and enforces only the limit. An unknown or
+ * suspended email is refused in the words an unknown or suspended id is, so it tells no more.
+ */
+async function activeUsers(
+  runtime: SixbRuntimeContext,
+  security: SecurityDefinitionCatalog,
+  users: readonly AgentThreadParticipantInput[]
+): Promise<UserPrincipal[]> {
+  if (!Array.isArray(users) || users.length === 0) {
+    throw invalidParticipant("Name at least one user.")
+  }
+  if (users.length > MAX_AGENT_THREAD_PARTICIPANTS) {
+    throw invalidParticipant(
+      `Add at most ${MAX_AGENT_THREAD_PARTICIPANTS} users to an Agent thread at once.`
+    )
+  }
+
+  const auth = runtime.storage.auth
+  const unique = new Map<string, UserPrincipal>()
+  for (const user of users) {
+    const email = emailOf(user)
+    const account =
+      auth &&
+      (email === undefined
+        ? await auth.users.getById({ projectId: runtime.projectId, id: userOf(user).id })
+        : await auth.users.getByEmail({ projectId: runtime.projectId, email }))
+
+    const named = email ?? userOf(user).id
+    const status = auth ? (account?.status ?? null) : "unverifiable"
+    const problem = userReferenceProblem("Agent thread participant", named, status)
+    if (problem || !account || !auth) {
+      throw new AgentRequestError(
+        "invalid_participant",
+        problem ?? `[Sixb] Unknown user '${named}'.`
+      )
+    }
+
+    // Someone who cannot use the Agent could never read the conversation they were added to.
+    const allowed = await userCanRunAgent({
+      auth,
+      projectId: runtime.projectId,
+      userId: account.id,
+      security,
+    })
+    if (!allowed) {
+      throw invalidParticipant(
+        `User '${named}' cannot use the Agent: a role granting can.run(agent) must reach them first.`
+      )
+    }
+
+    unique.set(account.id, { type: "user", id: account.id })
+  }
+  return [...unique.values()]
+}
+
+/** The trimmed email of an input naming a user by email; `undefined` for one naming an id. */
+function emailOf(user: AgentThreadParticipantInput): string | undefined {
+  if (!user || typeof user !== "object" || !("email" in user)) return undefined
+
+  const email = typeof user.email === "string" ? user.email.trim() : ""
+  if (!email) throw invalidParticipant("A user's email must not be empty.")
+  return email
+}
+
+/** A user named by id, with the id trimmed. */
+function userOf(user: AgentThreadParticipantInput): UserPrincipal {
+  const id =
+    user && "type" in user && user.type === "user" && typeof user.id === "string"
+      ? user.id.trim()
+      : ""
+  if (!id) {
+    throw invalidParticipant(
+      `Only users take part in an Agent thread: pass { type: "user", id } or { email }, not ${JSON.stringify(user)}.`
+    )
+  }
+  return { type: "user", id }
+}
+
+function requireStorage(runtime: SixbRuntimeContext): AgentStorage {
+  const storage = runtime.storage.agents
+  if (!storage) {
+    throw new AgentRequestError("storage_unavailable", "[Sixb] Agent storage is not configured.")
+  }
+  return storage
+}
+
+function threadNotFound(threadId: string): AgentRequestError {
+  return new AgentRequestError("thread_not_found", `[Sixb] Agent thread '${threadId}' not found.`)
+}
+
+function invalidParticipant(message: string): AgentRequestError {
+  return new AgentRequestError("invalid_participant", `[Sixb] ${message}`)
+}

package/src/agents/reference.ts

@@ -4,4 +4,6 @@ import type { AgentReference } from "./types"
 export const agent: AgentReference = Object.freeze({
   kind: "agent",
   usage: Object.freeze({ kind: "aiUsage" }),
+  threads: Object.freeze({ kind: "agentThreads" }),
+  memory: Object.freeze({ kind: "agentMemory" }),
 })