@sixb/core 0.1.20 → 0.1.22

package/src/activity/timeline.ts

@@ -0,0 +1,385 @@
+import {
+  readableSubjects,
+  unreadableActionRunTypes,
+  viewableActionRuns,
+} from "../actions/run-authorization"
+import { canViewWorkflowRun, isRuntimeAllowed } from "../authorization"
+import { nearestOwner } from "../execution/lineage"
+import { addCostSummaries, resolveExecutionCosts } from "../runtime/ai-cost"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { ActionRunStatus } from "../storage/action-runs"
+import { ACTIVITY_MAX_VISIT_MS, ACTIVITY_MIN_IDLE_TIMEOUT_MS } from "../storage/activity/policy"
+import type { ActivityVisit, StoredActivityVisitPage } from "../storage/activity/types"
+import type { AgentRunStatus, ConversationAgentRunRecord } from "../storage/agents"
+import type { AiCostSummary } from "../storage/ai-cost"
+import type { ExecutionRecord } from "../storage/executions"
+import { objectBatchKey } from "../storage/objects/keys"
+import type { ShareGrantRecord } from "../storage/share-grants"
+import type { WorkflowRunStatus } from "../storage/workflow-runs"
+import { type ActivityConnection, readActivityConnection } from "./connection"
+import type { ActivityVisitView } from "./shares"
+
+/**
+ * At most this many page views and interactions together, and as many recorded executions, make a
+ * visit's timeline.
+ */
+export const ACTIVITY_TIMELINE_LIMIT = 200
+
+/**
+ * How far around its activity a visit claims its session's executions. A click right after a
+ * return reaches the server before the activity that opens the visit, and the last action before
+ * leaving may come after the last activity sent. Half the shortest idle timeout keeps the visits of
+ * one session from claiming the same execution.
+ */
+const SESSION_GRACE_MS = ACTIVITY_MIN_IDLE_TIMEOUT_MS / 2
+
+export interface ActivityPageEntry {
+  readonly kind: "page"
+  readonly at: Date
+  readonly sequence: number
+  readonly route: string
+}
+
+/** An interaction the app marked, on the page it happened on. */
+export interface ActivityInteractionEntry {
+  readonly kind: "interaction"
+  readonly at: Date
+  readonly sequence: number
+  readonly name: string
+  readonly route: string
+}
+
+export interface ActivityActionEntry {
+  readonly kind: "action"
+  readonly at: Date
+  readonly executionId: string
+  readonly actionId: string
+  readonly runId: string
+  /** `incomplete` when no outcome is recorded: the run is in flight, or was interrupted. */
+  readonly status: ActionRunStatus | "incomplete"
+  /** Whether the viewer may read the run itself, as Observability › Runs shows it. */
+  readonly runVisible: boolean
+  /** The object it applied to, only when the viewer can read that object. */
+  readonly object?: { readonly objectTypeId: string; readonly primaryId: string }
+}
+
+export interface ActivityWorkflowEntry {
+  readonly kind: "workflow"
+  readonly at: Date
+  readonly executionId: string
+  readonly workflowId: string
+  readonly runId: string
+  readonly status: WorkflowRunStatus | "incomplete"
+  /** Whether the viewer may read the run itself, as Observability › Runs shows it. */
+  readonly runVisible: boolean
+}
+
+/** A conversation's run: its metadata, and its thread's title only for those who read threads. */
+export interface ActivityAgentEntry {
+  readonly kind: "agent"
+  readonly at: Date
+  readonly executionId: string
+  readonly runId: string
+  readonly threadId: string
+  /**
+   * Present only when the viewer can read the conversation, with `can.observe(agent.threads)`.
+   * Activity alone never shows a title or a message.
+   */
+  readonly thread?: { readonly title?: string }
+  readonly status: AgentRunStatus
+  /** Messages in the thread now, every run's. */
+  readonly messages: number
+  /** The run's model calls with those of its subagents and tools; absent without any. */
+  readonly cost?: AiCostSummary
+}
+
+export type ActivityTimelineEntry =
+  | ActivityPageEntry
+  | ActivityInteractionEntry
+  | ActivityActionEntry
+  | ActivityWorkflowEntry
+  | ActivityAgentEntry
+
+export interface ActivityVisitTimeline {
+  readonly visit: ActivityVisitView
+  /** Absent once the session is gone, or without an auth or share store. */
+  readonly connection?: ActivityConnection
+  /**
+   * By time. Page views and interactions come in their sequence, and before executions at the same
+   * instant.
+   */
+  readonly entries: readonly ActivityTimelineEntry[]
+  /**
+   * More than {@link ACTIVITY_TIMELINE_LIMIT} page views and interactions, or recorded executions.
+   * The timeline then stops at the last page view or interaction, or the last root execution, it
+   * could keep.
+   */
+  readonly truncated: boolean
+}
+
+/**
+ * A visit's timeline: its page views and interactions, and what its session started while it
+ * lasted. One bounded read per source, each batched over the visit; see `README.md`.
+ */
+export async function composeActivityTimeline(
+  runtime: SixbRuntimeContext,
+  input: {
+    readonly page: StoredActivityVisitPage
+    /** The visit, named by its link's share. */
+    readonly visit: ActivityVisitView
+    /** That link's grant, read with the name. */
+    readonly grant?: ShareGrantRecord
+  },
+  now: Date
+): Promise<ActivityVisitTimeline> {
+  const { page, visit } = input
+  const { storage, projectId } = runtime
+
+  const [ledger, connection] = await Promise.all([
+    storage.executions.listBySession({
+      projectId,
+      session: { type: visit.actor.type, id: page.sessionId },
+      ...sessionWindow(visit),
+      limit: ACTIVITY_TIMELINE_LIMIT,
+    }),
+    readActivityConnection(runtime, page, input.grant, now),
+  ])
+  const executions = ledger.executions
+
+  const ofKind = (kind: "action" | "workflow") =>
+    executions.flatMap((execution) =>
+      execution.executor.type === "primitive" && execution.executor.kind === kind
+        ? [execution.id]
+        : []
+    )
+  const agentRunIds = executions.flatMap((execution) =>
+    execution.executor.type === "agent" ? [execution.executor.runId] : []
+  )
+
+  // Only what an Agent ran can count toward a conversation's cost.
+  const byId = new Map(executions.map((execution) => [execution.id, execution]))
+  const withAgent = executions.filter((execution) =>
+    lineage(execution, byId).some((ancestor) => ancestor.executor.type === "agent")
+  )
+
+  const [actionRuns, workflowRuns, agentRuns, costs] = await Promise.all([
+    storage.actionRuns?.getByExecutionIds({ projectId, executionIds: ofKind("action") }) ?? [],
+    storage.workflowRuns?.getByExecutionIds({ projectId, executionIds: ofKind("workflow") }) ?? [],
+    storage.agents?.runs.getByIds({ projectId, ids: agentRunIds }) ?? [],
+    resolveExecutionCosts({
+      storage: storage.aiCosts,
+      projectId,
+      executionIds: withAgent.map((execution) => execution.id),
+    }),
+  ])
+
+  // A subagent's cost goes to the conversation above it. A Workflow's Agent steps have none.
+  const conversations = new Map(
+    agentRuns.flatMap((run) =>
+      run.kind === "conversation" ? [[run.executionId, run] as const] : []
+    )
+  )
+  const subjects = actionRuns.flatMap((run) => (run.subject.kind === "object" ? [run.subject] : []))
+
+  const [threads, readable, unreadableRunTypes, viewableRuns] = await Promise.all([
+    storage.agents?.threads.getByIds({
+      projectId,
+      ids: [...conversations.values()].map((run) => run.threadId),
+    }) ?? [],
+    readableSubjects(runtime.objectReader, subjects),
+    subjects.length > 0 ? unreadableActionRunTypes(runtime.objectReader) : new Set<string>(),
+    viewableActionRuns(runtime.objectReader, runtime.authorization, actionRuns),
+  ])
+
+  const actionRunByExecution = new Map(actionRuns.map((run) => [run.executionId, run]))
+  const viewableRunIds = new Set(viewableRuns.map((run) => run.id))
+  const workflowRunByExecution = new Map(workflowRuns.map((run) => [run.executionId, run]))
+  const threadById = new Map(threads.map((thread) => [thread.id, thread]))
+  const observesThreads = isRuntimeAllowed(runtime, { kind: "agentThreads.observe" })
+  const costByAgent = rollUpCosts(byId, conversations, withAgent, costs)
+
+  const executionEntries = executions.flatMap((execution): ActivityTimelineEntry[] => {
+    const at = new Date(execution.createdAt)
+    const executor = execution.executor
+    const authority = execution.authorizationRef
+
+    if (executor.type === "primitive" && authority.type === "trustedPrimitive") {
+      if (executor.kind === "action") {
+        const run = actionRunByExecution.get(execution.id)
+        const subject = run?.subject.kind === "object" ? run.subject : undefined
+        const object =
+          subject && readable.has(objectBatchKey(subject.objectTypeId, subject.primaryId))
+            ? { objectTypeId: subject.objectTypeId, primaryId: subject.primaryId }
+            : undefined
+
+        // As the runs page decides: the action, its subject's type or, through a condition, the
+        // subject itself, and the type's markings.
+        const runVisible =
+          run !== undefined &&
+          viewableRunIds.has(run.id) &&
+          (subject === undefined || !unreadableRunTypes.has(subject.objectTypeId))
+
+        return [
+          {
+            kind: "action",
+            at,
+            executionId: execution.id,
+            actionId: authority.primitive.id,
+            runId: executor.runId,
+            status: run?.status ?? "incomplete",
+            runVisible,
+            ...(object === undefined ? {} : { object }),
+          },
+        ]
+      }
+
+      if (executor.kind === "workflow") {
+        const run = workflowRunByExecution.get(execution.id)
+        return [
+          {
+            kind: "workflow",
+            at,
+            executionId: execution.id,
+            workflowId: authority.primitive.id,
+            runId: executor.runId,
+            status: run?.status ?? "incomplete",
+            runVisible: run !== undefined && canViewWorkflowRun(runtime.authorization, run),
+          },
+        ]
+      }
+    }
+
+    const conversation = conversations.get(execution.id)
+    if (conversation) {
+      const cost = costByAgent.get(execution.id)
+      const thread = threadById.get(conversation.threadId)
+      const title = thread?.title
+
+      return [
+        {
+          kind: "agent",
+          at,
+          executionId: execution.id,
+          runId: conversation.id,
+          threadId: conversation.threadId,
+          ...(observesThreads && thread ? { thread: title === undefined ? {} : { title } } : {}),
+          status: conversation.status,
+          messages: thread?.messageCount ?? 0,
+          ...(cost === undefined ? {} : { cost }),
+        },
+      ]
+    }
+
+    return []
+  })
+
+  // Recorded entries come first at an equal instant, in their sequence: the sort is stable.
+  const recorded = [
+    ...page.pageViews.map(
+      (pageView): ActivityPageEntry => ({
+        kind: "page",
+        at: new Date(pageView.receivedAt),
+        sequence: pageView.sequence,
+        route: pageView.route,
+      })
+    ),
+    ...page.interactions.map(
+      (interaction): ActivityInteractionEntry => ({
+        kind: "interaction",
+        at: new Date(interaction.receivedAt),
+        sequence: interaction.sequence,
+        name: interaction.name,
+        route: interaction.route,
+      })
+    ),
+  ].sort((left, right) => left.sequence - right.sequence)
+
+  // Past the last page view, interaction or root kept, a source left rows out: the timeline stops
+  // there.
+  const cutoffs = [
+    page.hasMore ? recorded.at(-1)?.at : undefined,
+    ledger.truncated
+      ? executions.filter((execution) => execution.source.type !== "execution").at(-1)?.createdAt
+      : undefined,
+  ].flatMap((at) => (at === undefined ? [] : [at.getTime()]))
+  const cutoff = cutoffs.length > 0 ? Math.min(...cutoffs) : Number.POSITIVE_INFINITY
+
+  const entries = [...recorded, ...executionEntries]
+    .filter((entry) => entry.at.getTime() <= cutoff)
+    .sort((left, right) => left.at.getTime() - right.at.getTime())
+
+  return {
+    visit,
+    ...(connection === undefined ? {} : { connection }),
+    entries,
+    truncated: page.hasMore || ledger.truncated,
+  }
+}
+
+/**
+ * Roots created in `[start - grace, last activity + grace)`, cut where the session's next visit
+ * may start once this one is a day old.
+ */
+function sessionWindow(visit: ActivityVisit): { readonly from: Date; readonly to: Date } {
+  const startedAt = visit.startedAt.getTime()
+  return {
+    from: new Date(startedAt - SESSION_GRACE_MS),
+    to: new Date(
+      Math.min(
+        visit.lastSeenAt.getTime() + SESSION_GRACE_MS,
+        startedAt + ACTIVITY_MAX_VISIT_MS - SESSION_GRACE_MS
+      )
+    ),
+  }
+}
+
+/** An execution, then its parent and the parent's, as far as the visit's executions go. */
+function lineage(
+  execution: ExecutionRecord,
+  byId: ReadonlyMap<string, ExecutionRecord>
+): readonly ExecutionRecord[] {
+  const chain: ExecutionRecord[] = []
+  let current: ExecutionRecord | undefined = execution
+
+  while (current) {
+    chain.push(current)
+    current = current.source.type === "execution" ? byId.get(current.source.executionId) : undefined
+  }
+  return chain
+}
+
+/** Each conversation's cost: its own calls and those of everything below it, each counted once. */
+function rollUpCosts(
+  byId: ReadonlyMap<string, ExecutionRecord>,
+  conversations: ReadonlyMap<string, ConversationAgentRunRecord>,
+  withAgent: readonly ExecutionRecord[],
+  costs: readonly (AiCostSummary | undefined)[]
+): ReadonlyMap<string, AiCostSummary> {
+  const grouped = new Map<string, AiCostSummary[]>()
+
+  withAgent.forEach((execution, index) => {
+    const cost = costs[index]
+    const owner = nearestOwner(
+      execution.id,
+      (id) => {
+        const source = byId.get(id)?.source
+        return source?.type === "execution" ? source.executionId : undefined
+      },
+      (id) => conversations.has(id)
+    )
+    if (!cost || !owner) {
+      return
+    }
+
+    const summaries = grouped.get(owner) ?? []
+    summaries.push(cost)
+    grouped.set(owner, summaries)
+  })
+
+  return new Map(
+    [...grouped].flatMap(([owner, summaries]) => {
+      const total = addCostSummaries(summaries)
+      return total ? [[owner, total] as const] : []
+    })
+  )
+}

package/src/agents/accounting.ts

@@ -0,0 +1,59 @@
+import { nearestOwner } from "../execution/lineage"
+import { addCostSummaries, resolveExecutionCosts } from "../runtime/ai-cost"
+import { addUsageSummaries, resolveExecutionUsage } from "../runtime/ai-usage"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { AiCostSummary } from "../storage/ai-cost"
+import type { AiModelCallUsage } from "../storage/ai-usage"
+
+/**
+ * Each turn's usage and cost: its own calls and those of everything below it, its children and
+ * what its tools ran, as Activity counts them. Each call counts once, toward the nearest turn above
+ * it. A child still at work adds what it has spent so far, and so does a workflow a tool started,
+ * also once the turn has ended: Activity counts it toward the conversation the same way. A child's
+ * execution counts the same way when it is the one asked about.
+ */
+export async function resolveTurnAccounting(
+  runtime: SixbRuntimeContext,
+  executionIds: readonly string[]
+): Promise<readonly { readonly usage?: AiModelCallUsage; readonly cost?: AiCostSummary }[]> {
+  if (executionIds.length === 0) return []
+  const { projectId, storage } = runtime
+
+  const below = await storage.executions.listDescendants({ projectId, executionIds })
+  const turns = new Set(executionIds)
+  const parentOf = new Map(below.map(({ id, parentId }) => [id, parentId]))
+  const turnOf = (executionId: string) =>
+    nearestOwner(
+      executionId,
+      (id) => parentOf.get(id),
+      (id) => turns.has(id)
+    )
+
+  const accounted = [...executionIds, ...below.map(({ id }) => id)]
+  const [usages, costs] = await Promise.all([
+    resolveExecutionUsage({ storage: storage.aiUsage, projectId, executionIds: accounted }),
+    resolveExecutionCosts({ storage: storage.aiCosts, projectId, executionIds: accounted }),
+  ])
+
+  const usagesByTurn = new Map<string, AiModelCallUsage[]>()
+  const costsByTurn = new Map<string, AiCostSummary[]>()
+  accounted.forEach((executionId, index) => {
+    const turn = turnOf(executionId)
+    const usage = usages[index]
+    const cost = costs[index]
+    // Never: every execution listed descends from a turn asked about.
+    if (turn === undefined) return
+
+    if (usage) usagesByTurn.set(turn, [...(usagesByTurn.get(turn) ?? []), usage])
+    if (cost) costsByTurn.set(turn, [...(costsByTurn.get(turn) ?? []), cost])
+  })
+
+  return executionIds.map((executionId) => {
+    const usage = addUsageSummaries(usagesByTurn.get(executionId) ?? [])
+    const cost = addCostSummaries(costsByTurn.get(executionId) ?? [])
+    return {
+      ...(usage === undefined ? {} : { usage }),
+      ...(cost === undefined ? {} : { cost }),
+    }
+  })
+}

package/src/agents/adapters.ts

@@ -9,6 +9,8 @@ import type {
   ModelToolResultPart,
   ProviderData,
 } from "../models"
+import { agentMailInstruction } from "./agent-mail"
+import { approvalOutcomeInstruction } from "./approval-outcome"
 import { serializeAgentContextForModel } from "./context-model"
 import type {
   AgentFilePart,
@@ -135,6 +137,14 @@ function userModelMessage<TMessage extends AgentMessage>(
       content.push({ type: "text", text: AGENT_CONTINUATION_INSTRUCTION })
       return
     }
+    if (part.type === "approval-outcome") {
+      content.push({ type: "text", text: `${approvalOutcomeInstruction(part)}\n\n` })
+      return
+    }
+    if (part.type === "mail") {
+      content.push({ type: "text", text: agentMailInstruction(part) })
+      return
+    }
     if (part.type === "text") {
       content.push({
         type: "text",

package/src/agents/agent-mail.ts

@@ -0,0 +1,29 @@
+import type { AgentMailPart } from "./message"
+
+/** Read after a message that came as the reader answered: what it wrote is not delivered. */
+const AFTER_ANSWER =
+  "Your parent sent this after your answer above, which it has not received. Write your complete result again, accounting for this message: only what you write now reaches it."
+
+/**
+ * What the model reads for an {@link AgentMailPart}. The live delivery and a later run's replay of
+ * the child's thread both project it here, so a continuation's prefix keeps its bytes. The
+ * sender's text is escaped: it may quote what a tool read, and must not close the block or pass
+ * for one of Sixb's own.
+ */
+export function agentMailInstruction(part: AgentMailPart): string {
+  if (part.kind === "answer") {
+    const question =
+      part.inReplyTo === undefined ? "" : ` question="${escapeAttribute(part.inReplyTo)}"`
+    return `<sixb_parent_answer id="${escapeAttribute(part.id)}"${question}>${escapeText(part.text)}</sixb_parent_answer>`
+  }
+  const block = `<sixb_parent_message id="${escapeAttribute(part.id)}">${escapeText(part.text)}</sixb_parent_message>`
+  return part.afterAnswer ? `${block}\n\n${AFTER_ANSWER}` : block
+}
+
+function escapeText(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
+}
+
+function escapeAttribute(value: string): string {
+  return escapeText(value).replaceAll('"', "&quot;")
+}

package/src/agents/api-gateway.ts

@@ -1,5 +1,5 @@
 import { createHmac, timingSafeEqual } from "node:crypto"
-import { SIXB_API_ROUTES } from "../http/api-routes"
+import { type AgentApiEffect, SIXB_API_ROUTES } from "../http/api-routes"
 import { matchesPathPattern, normalizeRoutePath } from "../http/route-pattern"
 
 export const AGENT_API_GATEWAY_PREFIX = "/__sixb/agent-api"
@@ -15,6 +15,8 @@ export interface AgentApiGatewayCapabilityInput {
 export interface AgentApiRoute {
   readonly method: string
   readonly path: string
+  /** What a call changes; a GET reads. */
+  readonly effect: AgentApiEffect
 }
 
 /**
@@ -23,7 +25,11 @@ export interface AgentApiRoute {
  */
 export const AGENT_API_ROUTES: readonly AgentApiRoute[] = SIXB_API_ROUTES.filter(
   (route) => route.agentApi
-).map((route) => ({ method: route.method, path: route.path }))
+).map((route) => ({
+  method: route.method,
+  path: route.path,
+  effect: route.agentEffect ?? "read",
+}))
 
 export function createAgentApiGatewayCapability(input: AgentApiGatewayCapabilityInput): string {
   return `${AGENT_API_GATEWAY_CAPABILITY_PREFIX}${capabilityDigest(input)}`
@@ -43,9 +49,14 @@ export function isValidAgentApiGatewayCapability(
 }
 
 export function isAllowedAgentApiRequest(method: string, pathname: string): boolean {
+  return findAgentApiRoute(method, pathname) !== undefined
+}
+
+/** The gateway route a request matches, with what it changes. */
+export function findAgentApiRoute(method: string, pathname: string): AgentApiRoute | undefined {
   const normalizedMethod = method.toUpperCase()
   const normalizedPath = normalizeRoutePath(pathname)
-  return AGENT_API_ROUTES.some(
+  return AGENT_API_ROUTES.find(
     (route) => route.method === normalizedMethod && matchesPathPattern(normalizedPath, route.path)
   )
 }

package/src/agents/approval-continuation.ts

@@ -0,0 +1,48 @@
+import type { Sixb } from "../runtime/sixb"
+import type { AgentTurnResume } from "./request"
+
+/** Where a resume left the paused turn, as whoever asked it learns. */
+export type AgentApprovalResume =
+  | AgentTurnResume
+  /**
+   * The turn could not resume as its requester: an AI limit, a lost grant or a thread they left.
+   * `retrying`: Sixb tries again; otherwise the thread's next message reports the calls.
+   */
+  | {
+      readonly status: "refused"
+      readonly code: string
+      readonly message: string
+      readonly retrying: boolean
+    }
+
+const resumeKey = Symbol("sixb.agentTurnResume")
+
+interface ResumeOwner {
+  readonly [resumeKey]?: (runId: string) => Promise<AgentApprovalResume>
+}
+
+/**
+ * Let code without a request resume a paused turn with a bound SDK's authority: the worker, after a
+ * turn paused on calls already decided, and its repair pass. The call side of a decision is the
+ * host's approval executor.
+ */
+export function registerAgentTurnResume(
+  agent: object,
+  resume: (runId: string) => Promise<AgentApprovalResume>
+): void {
+  Object.defineProperty(agent, resumeKey, {
+    configurable: false,
+    enumerable: false,
+    value: resume,
+    writable: false,
+  })
+}
+
+/** Resume a paused turn as the bound SDK's principal, its requester. */
+export function resumeDecidedAgentTurn(sixb: Sixb, runId: string): Promise<AgentApprovalResume> {
+  const resume = (sixb.agent as ResumeOwner)[resumeKey]
+  if (!resume) {
+    throw new Error("[Sixb] Agent turns cannot resume from this SDK: it was not bound by Sixb.")
+  }
+  return resume(runId)
+}