@sixb/core 0.1.20 → 0.1.22

package/src/agents/run-scope.ts

@@ -0,0 +1,134 @@
+import { assertAgentExecutionRecord } from "../execution/agent"
+import type { SecurityDefinitionCatalog } from "../security"
+import type { AuthStorage } from "../storage/auth"
+import type { ExecutionRecord, ExecutionStorage } from "../storage/executions"
+import {
+  type AgentExecutionAuthorization,
+  resolveAgentExecutionAuthorization,
+  resolveInheritedAgentExecutionAuthorization,
+} from "./authority"
+
+export interface AgentRunScopeHost {
+  readonly id: string
+  readonly storage: { readonly executions: ExecutionStorage; readonly auth?: AuthStorage }
+  readonly definitions: { readonly security: SecurityDefinitionCatalog }
+}
+
+/** A conversation turn or a child inherits its requester's authority; a workflow node is managed. */
+export type AgentRunScopeAuthority =
+  | { readonly type: "inherited" }
+  | { readonly type: "managed"; readonly actorId: string }
+
+/** What an Agent run's work is bound to: its own execution, with its current grants. */
+export interface AgentRunExecutionScope {
+  readonly execution: ExecutionRecord
+  readonly actorId?: string
+  readonly runId: string
+  readonly authorization: AgentExecutionAuthorization
+}
+
+export type AgentRunScopeErrorCode =
+  /** The run's execution record is missing. */
+  | "execution_unavailable"
+  /** The record names a principal, and the runtime has no auth storage to resolve it. */
+  | "auth_unavailable"
+  /** The record's authority no longer resolves, or does not belong to the run. */
+  | "authority_invalid"
+
+export class AgentRunScopeError extends Error {
+  readonly name = "AgentRunScopeError"
+
+  constructor(
+    readonly code: AgentRunScopeErrorCode,
+    message: string
+  ) {
+    super(message)
+  }
+}
+
+/**
+ * Restore an Agent run's execution from server-side records only: the run's execution record, then
+ * the grants its authority has now. The agent API gateway binds every request to it, and a decided
+ * approval runs its call under it.
+ */
+export async function resolveAgentRunExecutionScope(
+  host: AgentRunScopeHost,
+  run: {
+    readonly runId: string
+    readonly executionId: string
+    readonly authority: AgentRunScopeAuthority
+  }
+): Promise<AgentRunExecutionScope> {
+  const execution = await host.storage.executions.getById({
+    projectId: host.id,
+    id: run.executionId,
+  })
+  if (!execution) {
+    throw new AgentRunScopeError(
+      "execution_unavailable",
+      `[Sixb] Agent run '${run.runId}' execution is not available.`
+    )
+  }
+
+  // Authority comes from the record whether auth is enabled or not: an auth-disabled record is
+  // unrestricted, and a workflow AI task has its groups, as for its in-process tools. Only a record
+  // naming a principal needs auth storage.
+  const auth = host.storage.auth
+  if (!auth && execution.authorizationRef.type !== "disabled") {
+    throw new AgentRunScopeError(
+      "auth_unavailable",
+      `[Sixb] Agent run '${run.runId}' needs auth storage to resolve its authority.`
+    )
+  }
+
+  try {
+    const authorization = await resolveAuthorization(host, auth, run, execution)
+    return {
+      execution,
+      ...(run.authority.type === "managed" ? { actorId: run.authority.actorId } : {}),
+      runId: run.runId,
+      authorization,
+    }
+  } catch (error) {
+    throw new AgentRunScopeError(
+      "authority_invalid",
+      `[Sixb] Agent run '${run.runId}' execution authority is not valid: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    )
+  }
+}
+
+async function resolveAuthorization(
+  host: AgentRunScopeHost,
+  auth: AuthStorage | undefined,
+  run: { readonly runId: string; readonly authority: AgentRunScopeAuthority },
+  execution: ExecutionRecord
+): Promise<AgentExecutionAuthorization> {
+  if (run.authority.type === "inherited") {
+    const authorization = await resolveInheritedAgentExecutionAuthorization({
+      auth,
+      projectId: host.id,
+      authorizationRef: execution.authorizationRef,
+      security: host.definitions.security,
+    })
+    assertAgentExecutionRecord({ execution, runId: run.runId, authorization })
+    return authorization
+  }
+
+  const resolved = await resolveAgentExecutionAuthorization({
+    auth,
+    projectId: host.id,
+    actorId: run.authority.actorId,
+    authorizationRef: execution.authorizationRef,
+    security: host.definitions.security,
+  })
+  const authorization = { type: "principal", context: resolved.context } as const
+  assertAgentExecutionRecord({
+    execution,
+    actorId: run.authority.actorId,
+    runId: run.runId,
+    authorization,
+  })
+  return authorization
+}

package/src/agents/skills.ts

@@ -50,6 +50,12 @@ export function createAgentSkillCatalog(
   const skills = Object.freeze([...(definitions ?? [])])
   const skillsByName = new Map<string, AgentSkillDefinition>()
   for (const skill of skills) {
+    // As discovery refuses them: the worker adds its built-in skills under this prefix.
+    if (skill.name.startsWith("sixb-")) {
+      throw new RuntimeError(
+        `[Sixb] Agent Skill name '${skill.name}' uses the reserved 'sixb-' prefix.`
+      )
+    }
     if (skillsByName.has(skill.name)) {
       throw new RuntimeError(`[Sixb] Duplicate Agent Skill name: ${skill.name}`)
     }

package/src/agents/streams/index.ts

@@ -1,5 +1,8 @@
 /** Browser-safe agent stream reader contract. Producers belong to internal/agents/streams. */
+export type { ModelUiChunk } from "../../models/events"
 export type {
+  AgentActivityEvent,
+  AgentApprovalActivityEvent,
   AgentCompactionFailureCode,
   AgentRunActivityEvent,
   AgentRunControlStreamId,
@@ -13,6 +16,8 @@ export {
   AGENT_ACTIVITY_STREAM_SCHEMA_VERSION,
   AGENT_COMPACTION_FAILURE_CODES,
   AGENT_RUN_STREAM_SCHEMA_VERSION,
+  isAgentActivityEvent,
+  isAgentApprovalActivityEvent,
   isAgentRunActivityEvent,
   isAgentRunStreamEvent,
 } from "./protocol"

package/src/agents/streams/internal.ts

@@ -12,6 +12,7 @@ export {
   agentRunStreamIdempotencyKey,
   DEFAULT_AGENT_ACTIVITY_STREAM_RETENTION,
   DEFAULT_AGENT_RUN_STREAM_RETENTION,
+  publishAgentChildFinished,
   publishAgentRunActivity,
   publishAgentRunCancel,
   publishAgentRunFinished,

package/src/agents/streams/protocol.ts

@@ -1,13 +1,18 @@
 import type { Broker, BrokerStreamDefinition } from "../../broker"
 import { parseSixbFailure } from "../../errors/internal"
 import type { SixbFailure } from "../../errors/types"
-import { isJsonValue, isPlainRecord, type JsonValue } from "../../json"
+import { isPlainRecord, type JsonValue } from "../../json"
+import { isModelUiChunk, type ModelUiChunk } from "../../models/events"
 import {
+  AGENT_APPROVAL_STATUSES,
   AGENT_RUN_FAILURE_CODES,
+  type AgentApprovalRecord,
+  type AgentApprovalStatus,
   type AgentContextCheckpointReason,
   type AgentRunFailureCode,
   type AgentRunRecord,
   type ConversationAgentRunRecord,
+  type SubagentRunRecord,
 } from "../../storage/agents/types"
 
 export const AGENT_RUN_STREAM_SCHEMA_VERSION = 1 as const
@@ -72,6 +77,91 @@ export function isAgentRunActivityEvent(value: unknown): value is AgentRunActivi
   )
 }
 
+/**
+ * A held call of a thread's turn changed: it was held, decided, ran, or was set aside. Clients read
+ * the thread's approvals again.
+ */
+export interface AgentApprovalActivityEvent {
+  readonly schemaVersion: typeof AGENT_ACTIVITY_STREAM_SCHEMA_VERSION
+  readonly type: "agent.approval.activity"
+  readonly projectId: string
+  readonly approvalId: string
+  readonly threadId: string
+  /** The conversation turn the call belongs to. */
+  readonly runId: string
+  readonly status: AgentApprovalStatus
+  /** Whether the approved call ran and has its outcome. */
+  readonly hasOutcome: boolean
+  readonly occurredAt: string
+}
+
+/** Everything the project's activity feed carries. */
+export type AgentActivityEvent = AgentRunActivityEvent | AgentApprovalActivityEvent
+
+export function agentApprovalActivityEvent(
+  approval: AgentApprovalRecord,
+  occurredAt: Date = new Date()
+): AgentApprovalActivityEvent {
+  return {
+    schemaVersion: AGENT_ACTIVITY_STREAM_SCHEMA_VERSION,
+    type: "agent.approval.activity",
+    projectId: approval.projectId,
+    approvalId: approval.id,
+    threadId: approval.threadId,
+    runId: approval.runId,
+    status: approval.status,
+    hasOutcome: approval.outcome !== undefined,
+    occurredAt: occurredAt.toISOString(),
+  }
+}
+
+export function isAgentApprovalActivityEvent(value: unknown): value is AgentApprovalActivityEvent {
+  return (
+    isPlainRecord(value) &&
+    value.schemaVersion === AGENT_ACTIVITY_STREAM_SCHEMA_VERSION &&
+    value.type === "agent.approval.activity" &&
+    typeof value.projectId === "string" &&
+    typeof value.approvalId === "string" &&
+    typeof value.threadId === "string" &&
+    typeof value.runId === "string" &&
+    (AGENT_APPROVAL_STATUSES as readonly unknown[]).includes(value.status) &&
+    typeof value.hasOutcome === "boolean" &&
+    typeof value.occurredAt === "string"
+  )
+}
+
+export function isAgentActivityEvent(value: unknown): value is AgentActivityEvent {
+  return isAgentRunActivityEvent(value) || isAgentApprovalActivityEvent(value)
+}
+
+/** Announce held calls that changed, in one append. Each change is announced once. */
+export async function publishAgentApprovalActivity(
+  broker: Broker,
+  approvals: readonly AgentApprovalRecord[]
+): Promise<void> {
+  const first = approvals[0]
+  if (!first) return
+
+  await broker.ensureStream({
+    projectId: first.projectId,
+    stream: agentActivityStreamDefinition(),
+  })
+  await broker.append({
+    projectId: first.projectId,
+    streamId: AGENT_ACTIVITY_STREAM_ID,
+    records: approvals.map((approval) => {
+      const event = agentApprovalActivityEvent(approval)
+      return {
+        name: event.type,
+        key: event.threadId,
+        // The event is composed only of validated JSON primitives.
+        payload: event as unknown as JsonValue,
+        idempotencyKey: `${event.approvalId}:${event.status}${event.hasOutcome ? ":outcome" : ""}`,
+      }
+    }),
+  })
+}
+
 export async function publishAgentRunActivity(
   broker: Broker,
   run: ConversationAgentRunRecord
@@ -200,6 +290,296 @@ export async function subscribeAgentRunCancel(
   )
 }
 
+// ── Inbox streams (mail between a turn and its sub-agents) ──────────────────────────────────────
+//
+// A sub-agent's thread has an inbox its runs read at each step boundary: its parent steering it,
+// and the parent's reply to its question. Every run of the child reads the same one. A turn has
+// one too, where its children ask it. Its durable record is the sender's tool call and the
+// reader's thread, which keeps each `mail` part where it was read, or the tool result. An answer
+// the parent could only give in a later turn starts the run that continues the child, never through
+// these streams. A thread's inbox outlives the turn only so that a child paused on a held call,
+// which a later turn continues once the user decides, can still be given what it did not read: it
+// keeps mail as long as an approval waits, and a day more.
+//
+// A turn's inbox also hears when each of its children finishes, so one subscription per turn wakes
+// its waits for questions and for children alike.
+
+export type AgentThreadInboxStreamId = `agents.threads.${string}.inbox`
+export type AgentRunInboxStreamId = `agents.runs.${string}.inbox`
+
+export function agentThreadInboxStreamId(threadId: string): AgentThreadInboxStreamId {
+  return `agents.threads.${threadId}.inbox`
+}
+
+export function agentRunInboxStreamId(runId: string): AgentRunInboxStreamId {
+  return `agents.runs.${runId}.inbox`
+}
+
+const AGENT_MAIL_RECORD = "agent.mail"
+
+const AGENT_INBOX_RETENTION = {
+  // An approval waits at most 7 days (`AGENT_APPROVAL_TTL_MS`).
+  maxAgeMs: 8 * 24 * 60 * 60 * 1000,
+  maxRecords: 1_000,
+} as const
+
+/** Whose inbox: a sub-agent's thread, or a turn its children ask. */
+export type AgentInbox = { readonly threadId: string } | { readonly runId: string }
+
+function inboxStreamDefinition(inbox: AgentInbox): BrokerStreamDefinition {
+  return { id: inboxStreamId(inbox), retention: AGENT_INBOX_RETENTION }
+}
+
+function inboxStreamId(inbox: AgentInbox): AgentThreadInboxStreamId | AgentRunInboxStreamId {
+  return "threadId" in inbox
+    ? agentThreadInboxStreamId(inbox.threadId)
+    : agentRunInboxStreamId(inbox.runId)
+}
+
+/**
+ * The kinds of mail this version writes and understands:
+ *
+ * - `message`: the parent steers its child;
+ * - `question`: the child asks its parent, and waits;
+ * - `answer`: the parent's reply to a question, `inReplyTo`;
+ * - `deferred`: the parent's turn ended without one, so the child pauses on its question.
+ */
+export const AGENT_MAIL_KINDS = ["message", "question", "answer", "deferred"] as const
+export type AgentMailKind = (typeof AGENT_MAIL_KINDS)[number]
+
+/**
+ * One message between a turn and its sub-agent: to the child's thread, or, a question, from the
+ * child's thread to the turn.
+ */
+export type AgentMail = {
+  /** Unique per message: a sender writing it again, or the broker redelivering it, is the same. */
+  readonly id: string
+  readonly fromRunId: string
+  readonly kind: AgentMailKind
+  /** The question an `answer` or `deferred` replies to. */
+  readonly inReplyTo?: string
+  /** What the reader's model reads, whatever the kind: a reader that does not know it reads this. */
+  readonly text: string
+  readonly sentAt: string
+} & (
+  | { readonly toThreadId: string }
+  | {
+      readonly toRunId: string
+      /** The sub-agent's thread that asks. */
+      readonly fromThreadId: string
+    }
+)
+
+/**
+ * Mail as a reader finds it. Its kind may be one a newer sender writes: the reader delivers its
+ * text as a message rather than skipping it, so no reader's cursor passes mail it never delivered.
+ */
+export type ReceivedAgentMail = Omit<AgentMail, "kind"> & { readonly kind: string }
+
+export function isKnownAgentMailKind(kind: string): kind is AgentMailKind {
+  return (AGENT_MAIL_KINDS as readonly string[]).includes(kind)
+}
+
+function isReceivedAgentMail(value: unknown): value is ReceivedAgentMail {
+  return (
+    isPlainRecord(value) &&
+    typeof value.id === "string" &&
+    typeof value.fromRunId === "string" &&
+    (typeof value.toThreadId === "string" ||
+      (typeof value.toRunId === "string" && typeof value.fromThreadId === "string")) &&
+    typeof value.kind === "string" &&
+    value.kind.length > 0 &&
+    (value.inReplyTo === undefined || typeof value.inReplyTo === "string") &&
+    typeof value.text === "string" &&
+    typeof value.sentAt === "string"
+  )
+}
+
+/** Whether mail is addressed to this inbox. */
+function isFor(mail: ReceivedAgentMail, inbox: AgentInbox): boolean {
+  return "threadId" in inbox
+    ? "toThreadId" in mail && mail.toThreadId === inbox.threadId
+    : "toRunId" in mail && mail.toRunId === inbox.runId
+}
+
+function recipientOf(mail: AgentMail): AgentInbox {
+  return "toThreadId" in mail ? { threadId: mail.toThreadId } : { runId: mail.toRunId }
+}
+
+/** Write a message to its recipient's inbox. Idempotent by its id where the broker dedupes. */
+export async function publishAgentMail(
+  broker: Broker,
+  params: { readonly projectId: string; readonly mail: AgentMail }
+): Promise<void> {
+  const { projectId, mail } = params
+  const inbox = recipientOf(mail)
+  await broker.ensureStream({ projectId, stream: inboxStreamDefinition(inbox) })
+  await broker.append({
+    projectId,
+    streamId: inboxStreamId(inbox),
+    records: [
+      {
+        name: AGENT_MAIL_RECORD,
+        key: "threadId" in inbox ? inbox.threadId : inbox.runId,
+        // The mail is composed only of validated JSON primitives.
+        payload: mail as unknown as JsonValue,
+        idempotencyKey: mail.id,
+      },
+    ],
+  })
+}
+
+/**
+ * Call `onMail` with each page of mail to an inbox as it arrives, from its start. It is a wake: a
+ * broker may deliver a record again, so the reader keeps each mail once by its id. Returns the
+ * unsubscribe handle.
+ */
+export function subscribeAgentMail(
+  broker: Broker,
+  params: { readonly projectId: string; readonly inbox: AgentInbox },
+  onMail: (mail: readonly ReceivedAgentMail[]) => void
+): Promise<() => void> {
+  return subscribeAgentInbox(broker, params, { mail: onMail })
+}
+
+/**
+ * Hear an inbox from its start: its mail, and, for a turn's with `childFinished`, the ids of its
+ * children as each finishes. Both are wakes: a broker may deliver a record again, and a finish says
+ * only that the child's run is worth reading. Returns the unsubscribe handle.
+ */
+export async function subscribeAgentInbox(
+  broker: Broker,
+  params: { readonly projectId: string; readonly inbox: AgentInbox },
+  on: {
+    readonly mail: (mail: readonly ReceivedAgentMail[]) => void
+    readonly childFinished?: (runIds: readonly string[]) => void
+  }
+): Promise<() => void> {
+  const { inbox } = params
+  await broker.ensureStream({
+    projectId: params.projectId,
+    stream: inboxStreamDefinition(inbox),
+  })
+  return broker.subscribe(
+    {
+      projectId: params.projectId,
+      streamId: inboxStreamId(inbox),
+      from: "earliest",
+      names: on.childFinished
+        ? [AGENT_MAIL_RECORD, AGENT_CHILD_FINISHED_RECORD]
+        : [AGENT_MAIL_RECORD],
+    },
+    (records) => {
+      const mail: ReceivedAgentMail[] = []
+      const finished: string[] = []
+      for (const { name, payload } of records) {
+        if (name === AGENT_MAIL_RECORD) {
+          if (isReceivedAgentMail(payload) && isFor(payload, inbox)) mail.push(payload)
+        } else if (
+          "runId" in inbox &&
+          isAgentChildFinished(payload) &&
+          payload.parentRunId === inbox.runId
+        ) {
+          finished.push(payload.runId)
+        }
+      }
+
+      if (mail.length > 0) on.mail(mail)
+      if (finished.length > 0) on.childFinished?.(finished)
+    }
+  )
+}
+
+const AGENT_CHILD_FINISHED_RECORD = "agent.child.finished"
+
+/** A child stopped being at work: it ended, or paused on a held call or on its question. */
+interface AgentChildFinished {
+  readonly runId: string
+  readonly parentRunId: string
+  readonly status: "succeeded" | "failed" | "cancelled"
+}
+
+function isAgentChildFinished(value: unknown): value is AgentChildFinished {
+  return (
+    isPlainRecord(value) &&
+    typeof value.runId === "string" &&
+    typeof value.parentRunId === "string" &&
+    isTerminalAgentRunStatus(value.status)
+  )
+}
+
+/**
+ * Tell the turn a child works under, on the turn's inbox, that the child finished. Its run stream
+ * says so too, but that stream belongs to the transcript sink, which a worker may replace, and
+ * hearing it would take one subscription per child, each carrying every chunk the child streams.
+ * This record is the platform's, and one subscription per turn hears every child.
+ */
+export async function publishAgentChildFinished(
+  broker: Broker,
+  run: SubagentRunRecord
+): Promise<void> {
+  if (run.status === "queued" || run.status === "running") return
+
+  const finished: AgentChildFinished = {
+    runId: run.id,
+    parentRunId: run.parentRunId,
+    status: run.status,
+  }
+  const inbox = { runId: run.parentRunId }
+  await broker.ensureStream({ projectId: run.projectId, stream: inboxStreamDefinition(inbox) })
+  await broker.append({
+    projectId: run.projectId,
+    streamId: inboxStreamId(inbox),
+    records: [
+      {
+        name: AGENT_CHILD_FINISHED_RECORD,
+        key: run.parentRunId,
+        // The record is composed only of validated JSON primitives.
+        payload: finished as unknown as JsonValue,
+        idempotencyKey: `${run.id}:${run.attempt}:finished:${run.status}`,
+      },
+    ],
+  })
+}
+
+/**
+ * Read an inbox's mail after `afterCursor`, or from the start, every page of it. Carry the returned
+ * cursor to the next read. A record that is not mail at all (no envelope, no text) cannot be
+ * delivered: it is reported and passed, never silently.
+ */
+export async function readAgentMail(
+  broker: Broker,
+  params: { readonly projectId: string; readonly inbox: AgentInbox; readonly afterCursor?: string }
+): Promise<{ readonly mail: readonly ReceivedAgentMail[]; readonly cursor?: string }> {
+  const mail: ReceivedAgentMail[] = []
+  const streamId = inboxStreamId(params.inbox)
+  let cursor = params.afterCursor
+
+  for (;;) {
+    const page = await broker.read({
+      projectId: params.projectId,
+      streamId,
+      names: [AGENT_MAIL_RECORD],
+      ...(cursor === undefined ? {} : { afterCursor: cursor }),
+    })
+    for (const record of page.records) {
+      if (!isReceivedAgentMail(record.payload)) {
+        console.error(
+          `[Sixb] Agent inbox '${streamId}' record '${record.cursor}' is not mail; it is skipped.`
+        )
+        continue
+      }
+      if (isFor(record.payload, params.inbox)) mail.push(record.payload)
+    }
+
+    const previous = cursor
+    cursor = page.cursor ?? cursor
+    if (!page.hasMore || cursor === previous) break
+  }
+
+  return { mail, ...(cursor === undefined ? {} : { cursor }) }
+}
+
 /** Exact portable failure exposed by a terminal Agent run stream event. */
 export type AgentRunFailure = SixbFailure<AgentRunFailureCode>
 
@@ -235,7 +615,7 @@ export type AgentRunStreamEvent =
   | (AgentRunStreamEventBase & {
       readonly type: "agent.ui.chunk"
       readonly chunkIndex: number
-      readonly chunk: JsonValue
+      readonly chunk: ModelUiChunk
     })
   | (AgentRunStreamEventBase & {
       readonly type: "agent.message.finalized"
@@ -332,11 +712,8 @@ export function isAgentRunStreamEvent(value: unknown): value is AgentRunStreamEv
         AGENT_COMPACTION_FAILURE_CODES.includes(value.errorCode as AgentCompactionFailureCode)
       )
     case "agent.ui.chunk":
-      return (
-        Number.isInteger(value.chunkIndex) &&
-        Object.hasOwn(value, "chunk") &&
-        isJsonValue(value.chunk)
-      )
+      // A chunk type this reader does not know fails here, so a newer producer's chunk is skipped.
+      return Number.isInteger(value.chunkIndex) && isModelUiChunk(value.chunk)
     case "agent.message.finalized":
       return typeof value.messageId === "string"
     case "agent.run.finished":
@@ -420,4 +797,5 @@ export async function publishAgentRunFinished(broker: Broker, run: AgentRunRecor
     ],
   })
   if (run.kind === "conversation") await publishAgentRunActivity(broker, run)
+  else await publishAgentChildFinished(broker, run)
 }

package/src/agents/subagent-runs.ts

@@ -0,0 +1,41 @@
+import type { AgentStorage, SubagentRunRecord } from "../storage/agents"
+
+const PAGE = 100
+
+/**
+ * A sub-agent's thread's runs, in the order they ran: by creation, then, for runs created in the
+ * same instant, by where their trigger is in the thread. Runs are single-flight in a thread, so each
+ * trigger follows the work of the runs before it. A run whose messages left the thread, an attempt
+ * a retry removed, comes first among those created with it.
+ */
+export async function listSubagentThreadRuns(
+  agents: AgentStorage,
+  input: { readonly projectId: string; readonly threadId: string }
+): Promise<readonly SubagentRunRecord[]> {
+  const runs: SubagentRunRecord[] = []
+  for (;;) {
+    const page = await agents.runs.list({
+      projectId: input.projectId,
+      threadId: input.threadId,
+      kinds: ["subagent"],
+      order: "asc",
+      limit: PAGE,
+      offset: runs.length,
+    })
+    runs.push(...page.runs.filter((run) => run.kind === "subagent"))
+    if (!page.hasMore || page.runs.length === 0) break
+  }
+
+  const triggers = await Promise.all(
+    runs.map((run) =>
+      agents.messages.getById({ projectId: input.projectId, id: run.triggerMessageId })
+    )
+  )
+  const seqOf = new Map(runs.map((run, index) => [run.id, triggers[index]?.seq ?? -1]))
+  return runs.sort(
+    (a, b) =>
+      a.createdAt.getTime() - b.createdAt.getTime() ||
+      (seqOf.get(a.id) ?? -1) - (seqOf.get(b.id) ?? -1) ||
+      a.id.localeCompare(b.id)
+  )
+}