@sixb/core 0.1.21 → 0.1.22

package/src/actions/run/types.ts

@@ -1,11 +1,13 @@
 import type { BlobsRuntime } from "../../blob-storage/execution"
 import type { ConnectorRuntime } from "../../connectors/execution"
+import type { AuthorizablePrincipal } from "../../execution/types"
 import type { LoggingService } from "../../logging/service"
 import type { ModelsRuntime } from "../../models/generation-types"
 import type { ObjectsRuntime } from "../../objects/execution"
 import type { SixbDefinitions } from "../../runtime/definitions"
 import type { OntologyMutationRuntime } from "../../runtime/ontology-mutations"
-import type { ActionRunRecord, ActionRunStorage, Storage } from "../../storage"
+import type { ActionRunRecord, ActionRunStorage, ObjectRow, Storage } from "../../storage"
+import type { UsersRuntime } from "../../users"
 import type { ActionsRuntime } from "../execution"
 import type { ActionRunSignals } from "./signals"
 
@@ -16,6 +18,7 @@ export interface ActionExecutionFacade {
   readonly actions: ActionsRuntime
   readonly connector: ConnectorRuntime
   readonly blobs: BlobsRuntime
+  readonly users: UsersRuntime
 }
 
 export interface ActionRunContext {
@@ -27,8 +30,21 @@ export interface ActionRunContext {
   readonly ontologyMutations: OntologyMutationRuntime
   readonly sixb: ActionExecutionFacade
   readonly actions: Pick<SixbDefinitions["actions"], "getById">
+  /** Who started the chain of executions the run belongs to, when a principal did. */
+  readonly requestedBy: AuthorizablePrincipal | undefined
+  /** Reads the subject as its requester sees it: see {@link ReadSubjectAsRequester}. */
+  readonly readSubjectAsRequester?: ReadSubjectAsRequester
 }
 
+/**
+ * Reads the run's subject through its requester's reader. Present when the requester views the
+ * subject's type only through a condition: the run then acts only on a state its requester sees.
+ */
+export type ReadSubjectAsRequester = (subject: {
+  readonly objectTypeId: string
+  readonly primaryId: string
+}) => Promise<ObjectRow | null>
+
 /**
  * A requested run that has not ended: the request it executes, under the durable execution created
  * for it. Nothing else about it is stored until its terminal record is written.

package/src/actions/run-authorization.ts

@@ -1,8 +1,80 @@
+import { type AuthorizationContext, canViewActionRun, isAllowed } from "../authorization"
+import { AuthorizationError } from "../authorization/errors"
 import type { ResolvedRuntimeAuthorization } from "../execution/authorization"
 import { type AuthorizedObjectReader, readerClearance } from "../execution/authorized-object-reader"
 import type { Storage } from "../storage"
 import type { ActionRunRecord } from "../storage/action-runs"
 import { findPrimitiveParentRequestExecution } from "../storage/executions/run-link"
+import { objectBatchKey } from "../storage/objects/keys"
+import type { ActionObjectSubject } from "./types"
+
+/**
+ * The runs among these a principal may view. `canViewActionRun` decides on the subject's type,
+ * which a type the principal views through a condition fails: a run on one is viewable while the
+ * condition shows its subject now. A deleted subject shows nothing, so its runs stay hidden.
+ */
+export async function viewableActionRuns<
+  TRun extends Pick<ActionRunRecord, "actionId" | "subject">,
+>(
+  objectReader: AuthorizedObjectReader,
+  authorization: AuthorizationContext | null | undefined,
+  runs: readonly TRun[]
+): Promise<readonly TRun[]> {
+  if (!authorization) return runs
+
+  const subjectThroughCondition = (run: TRun): ActionObjectSubject | undefined =>
+    run.subject.kind === "object" &&
+    authorization.viewConditions?.has(run.subject.objectTypeId) === true &&
+    isAllowed(authorization, { kind: "action.apply", actionId: run.actionId })
+      ? run.subject
+      : undefined
+
+  const subjects = runs.flatMap((run) => subjectThroughCondition(run) ?? [])
+  const shown = subjects.length === 0 ? new Set() : await readableSubjects(objectReader, subjects)
+
+  return runs.filter((run) => {
+    if (canViewActionRun(authorization, run)) return true
+
+    const subject = subjectThroughCondition(run)
+    return (
+      subject !== undefined && shown.has(objectBatchKey(subject.objectTypeId, subject.primaryId))
+    )
+  })
+}
+
+/**
+ * The action subjects the reader reads now, by `objectBatchKey`: object type grants, conditions,
+ * markings and existence alike. One batch per object type, as a type the reader cannot see fails
+ * its whole batch.
+ */
+export async function readableSubjects(
+  objectReader: AuthorizedObjectReader,
+  subjects: readonly ActionObjectSubject[]
+): Promise<ReadonlySet<string>> {
+  const byType = new Map<string, Map<string, ActionObjectSubject>>()
+  for (const subject of subjects) {
+    const items = byType.get(subject.objectTypeId) ?? new Map()
+    items.set(subject.primaryId, subject)
+    byType.set(subject.objectTypeId, items)
+  }
+
+  const readable = new Set<string>()
+  await Promise.all(
+    [...byType.values()].map(async (items) => {
+      try {
+        const rows = await objectReader.getByPrimaryIdBatch({ items: [...items.values()] })
+        for (const key of rows.keys()) {
+          readable.add(key)
+        }
+      } catch (error) {
+        if (!(error instanceof AuthorizationError)) {
+          throw error
+        }
+      }
+    })
+  )
+  return readable
+}
 
 /**
  * Whether the reader can read the object type of a run's subject under the markings of the

package/src/actions/types/context.ts

@@ -1,6 +1,7 @@
 import type { BlobsRuntime } from "../../blob-storage/execution"
 import type { ConnectorRuntime } from "../../connectors"
 import type { RecordEditsContext } from "../../edits"
+import type { AuthorizablePrincipal } from "../../execution/types"
 import type { Logger } from "../../logging"
 import type {
   EffectiveLinkChange,
@@ -11,7 +12,9 @@ import type { ModelsRuntime } from "../../models/generation-types"
 import type { ObjectType, Property } from "../../ontology"
 import type { InferPropertyUnit, InferPropertyValue } from "../../ontology/inference"
 import type { ObjectTypeWithPropertyTokens, PropertyToken } from "../../ontology/tokens"
+import type { UserRef } from "../../ontology/user-ref"
 import type { ObjectReader } from "../../runtime/types"
+import type { UsersRuntime } from "../../users"
 import type { ActionPrimitiveSchemaValues } from "./params"
 
 export type ActionTargetObject<TObjectType extends ObjectType = ObjectType> = {
@@ -42,9 +45,13 @@ type InferActionSnapshotPropertyValue<TPropertyToken> = TPropertyToken extends {
 
 type InferActionSnapshotSchemaValue<TSchema> = TSchema extends keyof ActionPrimitiveSchemaValues
   ? ActionPrimitiveSchemaValues[TSchema]
-  : TSchema extends { readonly type: "enum"; readonly values: readonly (infer TValue)[] }
-    ? TValue
-    : unknown
+  : TSchema extends "userRef"
+    ? UserRef
+    : TSchema extends { readonly type: "array"; readonly items: "userRef" }
+      ? readonly UserRef[]
+      : TSchema extends { readonly type: "enum"; readonly values: readonly (infer TValue)[] }
+        ? TValue
+        : unknown
 
 export type ActionSubject = { readonly kind: "none" } | ActionObjectSubject
 
@@ -158,6 +165,7 @@ export interface ActionRuntimeFacade {
   readonly blobs: ActionBlobContext
   readonly models: ModelsRuntime
   readonly connector: ConnectorRuntime
+  readonly users: UsersRuntime
   objects<const TObjectType extends ObjectTypeWithPropertyTokens>(
     objectType: TObjectType
   ): ActionTelemetryObjectSet<TObjectType>
@@ -184,6 +192,15 @@ export interface BaseActionPhaseContext<TParams extends Record<string, unknown>>
   readonly run: ActionRunPhaseInfo
   readonly params: TParams
   readonly subject: ActionSubject
+  /**
+   * On whose behalf the run happens: the user or service account that started the chain of
+   * executions it belongs to, meaning the caller, or whoever started the workflow or agent run that
+   * requested it. It does not mean they approved this exact request: an agent's request carries it
+   * too. `undefined` when no principal did, as for a schedule, an event or a shared link. Once
+   * narrowed with `requestedBy?.type === "user"`, it is a `ref.user()` value you can compare or
+   * store.
+   */
+  readonly requestedBy: AuthorizablePrincipal | undefined
   /**
    * Aborts when the caller cancels the run or it runs out of time: a run has 30 seconds until its
    * writeback succeeds or its edits commit, and its effects have 30 more after the commit. Forward

package/src/actions/validators.ts

@@ -1,3 +1,4 @@
+import { withFailureMessage } from "../errors/failure-message"
 import { ActionValidationError } from "../objects/action/errors"
 import type { ActionDefinition, ActionSubject, ActionTargetObject } from "./types"
 import { isObjectActionDefinition } from "./validation"
@@ -19,10 +20,7 @@ export async function runActionValidators<TBaseContext extends object>(input: {
     for (const validator of validators) {
       const result = await validator(input.baseContext)
       if (isValidatorErrorResult(result)) {
-        throw new ActionValidationError(result.error, {
-          actionId: input.action.id,
-          subject: input.subject,
-        })
+        throw validatorRejection(input, result.error)
       }
     }
     return
@@ -38,14 +36,27 @@ export async function runActionValidators<TBaseContext extends object>(input: {
       target: input.target,
     })
     if (isValidatorErrorResult(result)) {
-      throw new ActionValidationError(result.error, {
-        actionId: input.action.id,
-        subject: input.subject,
-      })
+      throw validatorRejection(input, result.error)
     }
   }
 }
 
+/**
+ * The run fails with `action.rejected` and this message, which the author wrote for the caller. A
+ * thrown error's message stays private: it can come from anything the handler called.
+ */
+function validatorRejection(
+  input: { readonly action: ActionDefinition; readonly subject: ActionSubject },
+  message: string
+): ActionValidationError {
+  const rejection = new ActionValidationError(message, {
+    actionId: input.action.id,
+    subject: input.subject,
+  })
+
+  return withFailureMessage(rejection, message)
+}
+
 function isValidatorErrorResult(value: unknown): value is { readonly error: string } {
   return (
     typeof value === "object" &&

package/src/activity/README.md

@@ -136,10 +136,13 @@ time range, so the same user's other browser, active at the same time, stays out
   Page views and interactions are at their server receipt, executions at their creation: the
   app's steps credit an execution to the last page view before it, so one started as the page
   changed can land in the neighboring step.
-- **Content:** a run shows its thread's message count, never its title or messages. An action
+- **Content:** a run shows its thread's message count, never its messages. Its title, under
+  `thread`, only for a viewer who also holds `can.observe(agent.threads)`, the grant that opens
+  the conversation itself (`sixb.agent.observed`); `thread` is also what tells the app it may link
+  there. Activity alone never reveals a conversation. An action
   names its object only when the viewer's own object reader returns it, so object type grants,
   markings and deletion all hide it. `runVisible` says whether the viewer may read the run
-  itself, decided as the runs reads decide it (`canViewActionRun` and the subject type's
+  itself, decided as the runs reads decide it (`viewableActionRuns` and the subject type's
   markings, `canViewWorkflowRun`); the app links a run only then.
 - **Bounds:** 200 page views and interactions together, and 200 recorded executions, roots first
   and the earliest first. Past either limit `truncated` is set and the timeline stops at the last

package/src/activity/timeline.ts

@@ -1,7 +1,11 @@
-import type { ActionObjectSubject } from "../actions"
-import { unreadableActionRunTypes } from "../actions/run-authorization"
-import { AuthorizationError, canViewActionRun, canViewWorkflowRun } from "../authorization"
-import { resolveExecutionCosts } from "../runtime/ai-cost"
+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"
@@ -70,13 +74,18 @@ export interface ActivityWorkflowEntry {
   readonly runVisible: boolean
 }
 
-/** A conversation's run: its metadata only, never its title or messages. */
+/** 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
@@ -172,18 +181,21 @@ export async function composeActivityTimeline(
   )
   const subjects = actionRuns.flatMap((run) => (run.subject.kind === "object" ? [run.subject] : []))
 
-  const [threads, readable, unreadableRunTypes] = await Promise.all([
+  const [threads, readable, unreadableRunTypes, viewableRuns] = await Promise.all([
     storage.agents?.threads.getByIds({
       projectId,
       ids: [...conversations.values()].map((run) => run.threadId),
     }) ?? [],
-    readableObjects(runtime, subjects),
+    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 messagesByThread = new Map(threads.map((thread) => [thread.id, thread.messageCount]))
+  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[] => {
@@ -200,10 +212,11 @@ export async function composeActivityTimeline(
             ? { objectTypeId: subject.objectTypeId, primaryId: subject.primaryId }
             : undefined
 
-        // As the runs page decides: the action and its subject's type, and the type's markings.
+        // 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 &&
-          canViewActionRun(runtime.authorization, run) &&
+          viewableRunIds.has(run.id) &&
           (subject === undefined || !unreadableRunTypes.has(subject.objectTypeId))
 
         return [
@@ -239,6 +252,9 @@ export async function composeActivityTimeline(
     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",
@@ -246,8 +262,9 @@ export async function composeActivityTimeline(
           executionId: execution.id,
           runId: conversation.id,
           threadId: conversation.threadId,
+          ...(observesThreads && thread ? { thread: title === undefined ? {} : { title } } : {}),
           status: conversation.status,
-          messages: messagesByThread.get(conversation.threadId) ?? 0,
+          messages: thread?.messageCount ?? 0,
           ...(cost === undefined ? {} : { cost }),
         },
       ]
@@ -342,83 +359,27 @@ function rollUpCosts(
 
   withAgent.forEach((execution, index) => {
     const cost = costs[index]
-    const owner = lineage(execution, byId).find((ancestor) => conversations.has(ancestor.id))
+    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.id) ?? []
+    const summaries = grouped.get(owner) ?? []
     summaries.push(cost)
-    grouped.set(owner.id, summaries)
+    grouped.set(owner, summaries)
   })
 
   return new Map(
     [...grouped].flatMap(([owner, summaries]) => {
-      const total = addCosts(summaries)
+      const total = addCostSummaries(summaries)
       return total ? [[owner, total] as const] : []
     })
   )
 }
-
-function addCosts(summaries: readonly AiCostSummary[]): AiCostSummary | undefined {
-  const amounts = new Map<string, bigint>()
-  let ratedCallCount = 0
-  let unpriceableCallCount = 0
-  let unvaluedCallCount = 0
-
-  for (const summary of summaries) {
-    for (const money of summary.amounts) {
-      amounts.set(money.currency, (amounts.get(money.currency) ?? 0n) + BigInt(money.amountNanos))
-    }
-    ratedCallCount += summary.ratedCallCount
-    unpriceableCallCount += summary.unpriceableCallCount
-    unvaluedCallCount += summary.unvaluedCallCount
-  }
-
-  if (ratedCallCount + unpriceableCallCount + unvaluedCallCount === 0) {
-    return undefined
-  }
-
-  return {
-    amounts: [...amounts]
-      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
-      .map(([currency, amount]) => ({ currency, amountNanos: amount.toString() })),
-    ratedCallCount,
-    unpriceableCallCount,
-    unvaluedCallCount,
-  }
-}
-
-/**
- * The action subjects the viewer can read, through its own object reader: object type grants,
- * markings and existence alike. One batch per object type, as a type the viewer cannot see fails
- * its whole batch.
- */
-async function readableObjects(
-  runtime: SixbRuntimeContext,
-  subjects: readonly ActionObjectSubject[]
-): Promise<ReadonlySet<string>> {
-  const byType = new Map<string, Map<string, ActionObjectSubject>>()
-  for (const subject of subjects) {
-    const items = byType.get(subject.objectTypeId) ?? new Map()
-    items.set(subject.primaryId, subject)
-    byType.set(subject.objectTypeId, items)
-  }
-
-  const readable = new Set<string>()
-  await Promise.all(
-    [...byType.values()].map(async (items) => {
-      try {
-        const rows = await runtime.objectReader.getByPrimaryIdBatch({ items: [...items.values()] })
-        for (const key of rows.keys()) {
-          readable.add(key)
-        }
-      } catch (error) {
-        if (!(error instanceof AuthorizationError)) {
-          throw error
-        }
-      }
-    })
-  )
-  return readable
-}

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