@sixb/core 0.1.17 → 0.1.18

package/src/agents/context/entries.ts

@@ -4,7 +4,15 @@ import type { ObjectRef } from "../../ontology/refs"
 import { AgentRequestError } from "../errors"
 
 export type AgentContextInput =
-  | { readonly kind: "object"; readonly ref: ObjectRef }
+  | {
+      readonly kind: "object"
+      readonly ref: ObjectRef
+      /**
+       * What the chat shows for this object instead of its title. Display only: it is not part of
+       * the context's identity and is never sent to the model.
+       */
+      readonly label?: string
+    }
   | {
       readonly kind: "app-state"
       readonly id: string
@@ -28,16 +36,25 @@ export interface AgentContextPart extends AgentContextEntryInput {
 export const MAX_AGENT_CONTEXT_ENTRIES = 12
 export const MAX_AGENT_APP_STATE_ENTRY_BYTES = 16 * 1024
 export const MAX_AGENT_APP_STATE_TOTAL_BYTES = 64 * 1024
+export const MAX_AGENT_CONTEXT_LABEL_LENGTH = 200
 
 /** Typed constructors for context values shared by custom apps and agent clients. */
 export const agentContext = {
   object<const TObjectTypeId extends string>(
     objectType: { readonly id: TObjectTypeId },
-    primaryId: string
+    primaryId: string,
+    options: { readonly label?: string } = {}
   ) {
+    const label =
+      options.label === undefined
+        ? undefined
+        : objectContextLabel(options.label, "agentContext.object() label", (message) => {
+            throw new TypeError(`[Sixb] ${message}.`)
+          })
     return {
       kind: "object" as const,
       ref: { objectTypeId: objectType.id, primaryId },
+      ...(label === undefined ? {} : { label }),
     }
   },
 
@@ -85,7 +102,13 @@ export function normalizeAgentContextEntries(
   for (const [index, rawEntry] of input.entries()) {
     const entry = normalizeEntry(rawEntry, index)
     const identity = agentContextIdentity(entry.context)
-    const serialized = stableJsonStringify(entry)
+    // A label is display only, so two entries that differ only by label are the same entry; the
+    // first one's label is kept.
+    const serialized = stableJsonStringify(
+      entry.context.kind === "object"
+        ? { ...entry, context: { kind: "object", ref: entry.context.ref } }
+        : entry
+    )
     const existing = byIdentity.get(identity)
 
     if (existing !== undefined) {
@@ -133,8 +156,16 @@ function normalizeEntry(rawEntry: unknown, index: number): AgentContextEntryInpu
       context.ref.primaryId,
       `context[${index}].context.ref.primaryId`
     )
+    const label =
+      context.label === undefined
+        ? undefined
+        : objectContextLabel(context.label, `context[${index}].context.label`, invalidContext)
     return {
-      context: { kind: "object", ref: { objectTypeId, primaryId } },
+      context: {
+        kind: "object",
+        ref: { objectTypeId, primaryId },
+        ...(label === undefined ? {} : { label }),
+      },
       origin: rawEntry.origin,
     }
   }
@@ -165,6 +196,19 @@ function normalizeEntry(rawEntry: unknown, index: number): AgentContextEntryInpu
   invalidContext(`context[${index}].context.kind must be 'object' or 'app-state'`)
 }
 
+function objectContextLabel(
+  value: unknown,
+  label: string,
+  fail: (message: string) => never
+): string {
+  const trimmed = typeof value === "string" ? value.trim() : ""
+  if (!trimmed) fail(`${label} must be a non-empty string`)
+  if (trimmed.length > MAX_AGENT_CONTEXT_LABEL_LENGTH) {
+    fail(`${label} must be at most ${MAX_AGENT_CONTEXT_LABEL_LENGTH} characters`)
+  }
+  return trimmed
+}
+
 function requireNonEmptyString(value: unknown, label: string): string {
   if (typeof value !== "string" || value.trim().length === 0) {
     invalidContext(`${label} must be a non-empty string`)

package/src/agents/context/index.ts

@@ -12,4 +12,5 @@ export {
   MAX_AGENT_APP_STATE_ENTRY_BYTES,
   MAX_AGENT_APP_STATE_TOTAL_BYTES,
   MAX_AGENT_CONTEXT_ENTRIES,
+  MAX_AGENT_CONTEXT_LABEL_LENGTH,
 } from "./entries"

package/src/agents/context-compaction.ts

@@ -1,5 +1,6 @@
 import { stableJsonStringify } from "../json"
 import type { AgentMessageRecord } from "../storage/agents/types"
+import { AGENT_CONTINUATION_INSTRUCTION } from "./adapters"
 import type { AgentMessage, AgentMessagePart } from "./message"
 
 export const AGENT_CONTEXT_ESTIMATOR_VERSION = 1 as const
@@ -144,6 +145,9 @@ function estimateMessageTokens(
       case "step-start":
         tokens += STEP_OVERHEAD_TOKENS
         break
+      case "continuation":
+        tokens += textTokens(AGENT_CONTINUATION_INSTRUCTION)
+        break
       case "context":
         tokens += textTokens(stableJsonStringify(part.context))
         break
@@ -199,6 +203,8 @@ function serializeSummaryPart(
     case "provider-state":
     case "step-start":
       return []
+    case "continuation":
+      return [`${indent}<continuation_request />`]
     case "context":
       return part.context.kind === "object"
         ? [

package/src/agents/errors.ts

@@ -33,12 +33,15 @@ export type AgentRequestErrorCode =
   | "agent_not_found"
   | "model_not_found"
   | "invalid_model_selection"
+  | "invalid_locale"
+  | "invalid_message"
   | "run_not_found"
   | "run_not_retryable"
   | "thread_not_found"
   | "active_run_exists"
   | "authority_not_inheritable"
   | "invalid_context"
+  | "invalid_attachment"
   | "storage_unavailable"
   | "sandbox_not_configured"
   | "invalid_sandbox_params"

package/src/agents/index.ts

@@ -1,3 +1,4 @@
+export type { PropertyClearance } from "../objects/property-clearance"
 export type {
   AgentFileDataProjection,
   AgentFileDataResolverInput,
@@ -18,6 +19,7 @@ export {
   agentServiceAccountId,
   ensureManagedAgentExecutionIdentity,
   resolveAgentExecutionAuthorization,
+  resolveAgentPropertyClearance,
   resolveInheritedAgentExecutionAuthorization,
 } from "./authority"
 export { defineAgentTool } from "./builders"
@@ -84,6 +86,7 @@ export {
 } from "./ids"
 export {
   AGENT_MESSAGE_CONTENT_VERSION,
+  type AgentContinuationPart,
   type AgentFilePart,
   type AgentMessage,
   type AgentMessagePart,
@@ -105,11 +108,19 @@ export type {
 export { runModelLoop } from "./model-loop"
 export { agent } from "./reference"
 export {
+  isRetryableAgentRun,
   type RequestAgentRunInput,
   type RequestAgentRunResult,
   requestAgentRun,
   retryAgentRun,
 } from "./request"
+export type {
+  AgentDefinitions,
+  AgentDefinitionsInput,
+  AgentProjectFile,
+  AgentSkillCatalog,
+  AgentSkillDefinition,
+} from "./skills"
 export type {
   AgentCompactionFailureCode,
   AgentRunControlStreamId,
@@ -144,11 +155,11 @@ export { isAgentToolResult } from "./tool-result"
 export type {
   AgentDescriptor,
   AgentReasoning,
-  AgentReasoningLevel,
   AgentReference,
   AgentToolArtifact,
   AgentToolArtifactPutInput,
   AgentToolArtifacts,
+  AgentToolAttachments,
   AgentToolContent,
   AgentToolDefinition,
   AgentToolDescriptionBuilder,
@@ -161,6 +172,7 @@ export type {
   AgentToolRunBuilder,
   AgentToolRunContext,
   AgentToolRunInfo,
+  AgentToolRuntimeFacade,
   AgentToolTextContent,
   AgentUsageReference,
   InferAgentToolInput,

package/src/agents/message.ts

@@ -60,6 +60,14 @@ interface AgentToolCallBase {
   readonly providerMetadata?: ProviderData
 }
 
+/**
+ * The user asked the Agent to continue an answer the turn limit cut short. Sixb writes the
+ * instruction the model reads; chats show no message for it.
+ */
+export interface AgentContinuationPart {
+  readonly type: "continuation"
+}
+
 /** Ordered, hidden provider state required to replay a model response losslessly. */
 export interface AgentProviderStatePart {
   readonly type: "provider-state"
@@ -84,6 +92,7 @@ export type AgentMessagePart =
   | AgentStepStartPart
   | AgentFilePart
   | AgentContextPart
+  | AgentContinuationPart
   | AgentToolCallPart
   | AgentProviderStatePart
 

package/src/agents/request.ts

@@ -3,6 +3,7 @@ import type { Principal } from "../auth"
 import { SYSTEM_PRINCIPAL } from "../auth"
 import { assertAuthorized } from "../authorization"
 import type { FileRef } from "../blob-storage"
+import { isValidFileRef } from "../blob-storage/validation"
 import {
   canInheritAgentRequestAuthorization,
   createInheritedAgentExecutionRecord,
@@ -10,8 +11,10 @@ import {
 import { resolveExecutionScopeAuthorization } from "../execution/authorization"
 import { ensureExecutionRecord, executionRecordInputFromRuntime } from "../execution/durable"
 import type { ExecutionContext } from "../execution/types"
-import type { LanguageModelCatalog, LanguageModelRef } from "../models"
-import { isModelReasoning } from "../models/language-model"
+import type { LanguageModelCatalog, LanguageModelEntry, LanguageModelRef } from "../models"
+import { isModelReasoning, modelReasoningSupportIssue } from "../models/language-model"
+import { resolveLanguageModel } from "../models/resolve"
+import { canonicalLocale, canonicalTimeZone } from "../runtime/locale"
 import type { SixbRuntimeContext } from "../runtime/types"
 import {
   type AgentStorage,
@@ -33,13 +36,19 @@ import { resolveAgentContextParts } from "./context-resolution"
 import { dispatchQueuedAgentRuns } from "./dispatch"
 import { AgentRequestError } from "./errors"
 import { createAgentMessageId, createAgentRunId, createAgentThreadId } from "./ids"
+import type { AgentMessagePart } from "./message"
 import { assertNoAgentSelector } from "./retired-config"
 import { publishAgentRunActivity } from "./streams/protocol"
-import { AGENT_REASONING_LEVELS, type AgentReasoningLevel } from "./types"
+import { AGENT_REASONING_LEVELS, type AgentReasoning } from "./types"
 
 export interface RequestAgentRunInput {
-  /** The user's message that triggers the turn. */
-  readonly text: string
+  /** The user's message that triggers the turn. Omitted only to {@link continue}. */
+  readonly text?: string
+  /**
+   * Continue an answer the turn limit cut short, in an existing thread. Sixb writes the
+   * instruction the model reads, so the request carries no text, attachments, or context.
+   */
+  readonly continue?: boolean
   /** Blob-backed files attached to the trigger message. */
   readonly attachments?: readonly FileRef[]
   /** Structured page/object context snapshotted onto the triggering user message. */
@@ -48,8 +57,15 @@ export interface RequestAgentRunInput {
   readonly threadId?: string
   /** Configured language model selected for this turn. Omitted uses the agent default. */
   readonly model?: LanguageModelRef
-  /** Provider-neutral reasoning effort selected for this turn. */
-  readonly reasoning?: AgentReasoningLevel
+  /** Reasoning effort or token budget for this turn. Omitted uses the model's default. */
+  readonly reasoning?: AgentReasoning
+  /**
+   * IANA time zone of the person asking, such as their browser's. The Agent presents dates and
+   * times in it. Omitted uses the project time zone.
+   */
+  readonly timeZone?: string
+  /** BCP 47 language of the person asking. Omitted uses the project locale. */
+  readonly locale?: string
   /** Title to stamp on the thread when one is created. */
   readonly title?: string
   /** Explicit id for the trigger (user) message. Defaults to a generated id. */
@@ -88,7 +104,17 @@ export async function requestAgentRun(
   assertNoAgentSelector(input)
   assertAuthorized(runtime, { kind: "agent.run" })
   assertRequestAuthorityCanRunAgent(runtime)
-  const spec = resolveConversationRunSpec({ models, input })
+  const trigger = triggerParts(input)
+  const continued = input.continue ? await continuedSelection(runtime, models, input) : {}
+  const spec = await resolveConversationRunSpec({
+    models,
+    input: {
+      ...input,
+      model: input.model ?? continued.model,
+      reasoning: input.reasoning ?? continued.reasoning,
+    },
+  })
+  assertAttachments(input.attachments)
 
   // Resolve context before creating a thread: invalid or inaccessible references must not leave an
   // empty conversation behind. The resulting parts are the exact snapshot persisted below.
@@ -142,7 +168,7 @@ export async function requestAgentRun(
         role: "user",
         parts: [
           ...contextParts,
-          { type: "text", text: input.text },
+          ...trigger,
           ...(input.attachments ?? []).map((fileRef) => ({ type: "file" as const, fileRef })),
         ],
         authorPrincipal: principal,
@@ -173,6 +199,15 @@ export async function requestAgentRun(
   }
 }
 
+/** A failed turn, or one its worker died during, can run again from the same trigger message. */
+export function isRetryableAgentRun(
+  run: Pick<ConversationAgentRunRecord, "status" | "finishReason">
+): boolean {
+  return (
+    run.status === "failed" || (run.status === "cancelled" && run.finishReason === "interrupted")
+  )
+}
+
 /** Retry a failed turn as a new child execution while reusing its immutable trigger message. */
 export async function retryAgentRun(
   runtime: SixbRuntimeContext,
@@ -186,10 +221,10 @@ export async function retryAgentRun(
   })
   assertAuthorized(runtime, { kind: "agent.run" })
   assertRequestAuthorityCanRunAgent(runtime)
-  if (failedRun.status !== "failed") {
+  if (!isRetryableAgentRun(failedRun)) {
     throw new AgentRequestError(
       "run_not_retryable",
-      `[Sixb] Only failed Agent runs can be retried.`
+      `[Sixb] Only failed or interrupted Agent runs can be retried.`
     )
   }
 
@@ -227,10 +262,10 @@ export async function retryAgentRun(
       triggerMessageId: failedRun.triggerMessageId,
       spec:
         failedRun.spec ??
-        resolveConversationRunSpec({
+        (await resolveConversationRunSpec({
           models,
           input: {},
-        }),
+        })),
     })
   })
   await publishRunActivity(runtime, run)
@@ -238,6 +273,70 @@ export async function retryAgentRun(
   return { run, ...(jobId ? { jobId } : {}), createdThread: false }
 }
 
+/**
+ * A continuation picks up where the cut-short turn stopped, with its model and reasoning unless the
+ * request chooses others. A model that has since left the catalog falls back to the defaults.
+ */
+async function continuedSelection(
+  runtime: SixbRuntimeContext,
+  models: LanguageModelCatalog | undefined,
+  input: RequestAgentRunInput
+): Promise<Pick<RequestAgentRunInput, "model" | "reasoning">> {
+  const agents = requireAgentStorage(runtime)
+  const threadId = input.threadId ?? ""
+  if (!(await agents.threads.getById({ projectId: runtime.projectId, id: threadId }))) {
+    throw new AgentRequestError(
+      "thread_not_found",
+      "[Sixb] An Agent continuation needs an existing thread."
+    )
+  }
+  if (input.model !== undefined || input.reasoning !== undefined) return {}
+  const { runs } = await agents.runs.list({
+    projectId: runtime.projectId,
+    threadId,
+    kinds: ["conversation"],
+    order: "desc",
+    limit: 1,
+  })
+  const spec = runs[0]?.kind === "conversation" ? runs[0].spec : undefined
+  if (!spec || !models?.getByRef(spec.model)) return {}
+  return {
+    model: spec.model,
+    ...(spec.reasoning === undefined ? {} : { reasoning: spec.reasoning }),
+  }
+}
+
+/** The words of the user, or the continuation Sixb words for them. */
+function triggerParts(input: RequestAgentRunInput): readonly AgentMessagePart[] {
+  if (input.continue === true) {
+    if (input.text !== undefined || input.attachments?.length || input.context?.length) {
+      throw new AgentRequestError(
+        "invalid_message",
+        "[Sixb] An Agent continuation carries no text, attachments, or context."
+      )
+    }
+    return [{ type: "continuation" }]
+  }
+  if (typeof input.text !== "string" || input.text.trim().length === 0) {
+    throw new AgentRequestError(
+      "invalid_message",
+      "[Sixb] An Agent message needs text, or `continue: true` to continue the previous answer."
+    )
+  }
+  return [{ type: "text", text: input.text }]
+}
+
+function assertAttachments(attachments: readonly FileRef[] | undefined): void {
+  for (const [index, attachment] of (attachments ?? []).entries()) {
+    if (!isValidFileRef(attachment)) {
+      throw new AgentRequestError(
+        "invalid_attachment",
+        `[Sixb] Attachment ${index} is not a valid file reference.`
+      )
+    }
+  }
+}
+
 function assertSandboxExecutionAvailable(thread: AgentThreadRecord): void {
   if (thread.sandboxState && !["new", "ready"].includes(thread.sandboxState.status)) {
     throw new AgentRequestError(
@@ -281,10 +380,14 @@ async function assertAiLimitPreflight(
   }
 }
 
-function resolveConversationRunSpec(input: {
+/**
+ * Freeze the model selection of a turn. The model's default reasoning is resolved here, not by the
+ * worker, so a retry runs with the reasoning the turn was admitted with.
+ */
+async function resolveConversationRunSpec(input: {
   readonly models?: LanguageModelCatalog
-  readonly input: Pick<RequestAgentRunInput, "model" | "reasoning">
-}): ConversationAgentRunSpec {
+  readonly input: Pick<RequestAgentRunInput, "model" | "reasoning" | "timeZone" | "locale">
+}): Promise<ConversationAgentRunSpec> {
   if (!input.models) {
     throw new AgentRequestError(
       "model_not_found",
@@ -300,20 +403,73 @@ function resolveConversationRunSpec(input: {
     )
   }
 
-  const reasoning = input.input.reasoning
-  if (reasoning !== undefined && !isModelReasoning(reasoning)) {
-    throw new AgentRequestError(
-      "invalid_model_selection",
-      `[Sixb] Agent reasoning must be one of: ${AGENT_REASONING_LEVELS.join(", ")}, or a nonnegative budgetTokens object.`
-    )
+  const explicitReasoning = input.input.reasoning
+  if (explicitReasoning !== undefined) {
+    await assertModelSupportsReasoning(model, explicitReasoning)
   }
+  const reasoning = explicitReasoning ?? model.model.defaultReasoning
+  const timeZone = requestedSetting(
+    "timeZone",
+    input.input.timeZone,
+    canonicalTimeZone,
+    "an IANA time zone"
+  )
+  const locale = requestedSetting(
+    "locale",
+    input.input.locale,
+    canonicalLocale,
+    "a BCP 47 language tag"
+  )
 
   return Object.freeze({
     model: Object.freeze({ provider: selected.provider, modelId: selected.modelId }),
     ...(reasoning === undefined ? {} : { reasoning }),
+    ...(timeZone === undefined ? {} : { timeZone }),
+    ...(locale === undefined ? {} : { locale }),
   })
 }
 
+function requestedSetting(
+  field: "timeZone" | "locale",
+  value: string | undefined,
+  canonical: (value: unknown) => string | undefined,
+  expected: string
+): string | undefined {
+  if (value === undefined) return undefined
+  const resolved = canonical(value)
+  if (resolved === undefined) {
+    throw new AgentRequestError(
+      "invalid_locale",
+      `[Sixb] Agent request '${field}' must be ${expected}; received ${JSON.stringify(value)}.`
+    )
+  }
+  return resolved
+}
+
+// Checked against the model's resolved capabilities, as `GET /api/models` reports them (its
+// configured ones when the provider catalog is unavailable). Undeclared capabilities accept any
+// level; the provider then falls back to its own default.
+async function assertModelSupportsReasoning(
+  entry: LanguageModelEntry,
+  reasoning: unknown
+): Promise<void> {
+  if (!isModelReasoning(reasoning)) {
+    throw new AgentRequestError(
+      "invalid_model_selection",
+      `[Sixb] Agent reasoning must be one of: ${AGENT_REASONING_LEVELS.join(", ")}, or a nonnegative budgetTokens object.`
+    )
+  }
+  if (reasoning === "provider-default") return
+  const model = await resolveLanguageModel(entry.model)
+  const issue = modelReasoningSupportIssue(model.definition.capabilities.reasoning, reasoning)
+  if (issue !== undefined) {
+    throw new AgentRequestError(
+      "invalid_model_selection",
+      `[Sixb] Language model '${entry.provider}/${entry.modelId}' cannot use this reasoning: ${issue}.`
+    )
+  }
+}
+
 async function prepareDurableAgentExecution(
   runtime: SixbRuntimeContext,
   execution: ExecutionContext,

package/src/agents/skills.ts

@@ -0,0 +1,63 @@
+import type { OntologyDocsCatalog, OntologyDocsInput } from "../ontology/docs"
+import { RuntimeError } from "../runtime/errors"
+
+/** A project file the Agent receives byte-for-byte in its sandbox. */
+export interface AgentProjectFile {
+  /** POSIX path, relative to the directory the file is installed in. */
+  readonly path: string
+  readonly contents: string | Uint8Array
+  /** Permission bits, kept only for executable files. */
+  readonly mode?: number
+}
+
+/** An Agent Skill read from `skills/<name>/SKILL.md` and the files next to it. */
+export interface AgentSkillDefinition {
+  readonly name: string
+  readonly description: string
+  /** Every file of the skill directory, `SKILL.md` included. */
+  readonly files: readonly AgentProjectFile[]
+}
+
+/** Immutable catalog of the Agent Skills registered with a Sixb host. */
+export interface AgentSkillCatalog {
+  list(): readonly AgentSkillDefinition[]
+  getByName(name: string): AgentSkillDefinition | null
+}
+
+/** The project files the Agent reads. createSixb() discovers them; tests may pass them directly. */
+export interface AgentDefinitionsInput {
+  /** Agent Skills, from `skills/`. */
+  readonly skills?: readonly AgentSkillDefinition[]
+  /** The conversational Agent's instructions, from `SIXB.md`. */
+  readonly instructions?: string
+  /** The modules, docs, and scripts of `ontology/`. */
+  readonly ontologyDocs?: OntologyDocsInput
+}
+
+/** The project files the Agent reads, validated with the other definitions. */
+export interface AgentDefinitions {
+  readonly skills: AgentSkillCatalog
+  /** Absent without `SIXB.md`. */
+  readonly instructions?: string
+  /** Where each object type's reference doc lives, with the docs and scripts of `ontology/`. */
+  readonly ontologyDocs: OntologyDocsCatalog
+}
+
+/** Index skills by name. Discovery validates each skill; names must also be unique. */
+export function createAgentSkillCatalog(
+  definitions: readonly AgentSkillDefinition[] | undefined
+): AgentSkillCatalog {
+  const skills = Object.freeze([...(definitions ?? [])])
+  const skillsByName = new Map<string, AgentSkillDefinition>()
+  for (const skill of skills) {
+    if (skillsByName.has(skill.name)) {
+      throw new RuntimeError(`[Sixb] Duplicate Agent Skill name: ${skill.name}`)
+    }
+    skillsByName.set(skill.name, skill)
+  }
+
+  return Object.freeze({
+    list: () => skills,
+    getByName: (name: string) => skillsByName.get(name) ?? null,
+  })
+}

package/src/agents/types.ts

@@ -1,10 +1,13 @@
-import type { BlobBody, FileRef } from "../blob-storage"
+import type { ActionsRuntime } from "../actions/execution"
+import type { BlobBody, FileRef, OpenedFileRef } from "../blob-storage"
 import type { ConnectorRuntime } from "../connectors"
 import type { JsonPrimitive, JsonValue, ReadonlyJsonValue } from "../json"
 import type { Logger } from "../logging"
 import { type LanguageModelRef, MODEL_REASONING_LEVELS, type ModelReasoning } from "../models"
+import type { ModelsRuntime } from "../models/generation-types"
 import type { InferSchema } from "../ontology/inference"
 import type { Schema } from "../ontology/types"
+import type { ObjectReader } from "../runtime/types"
 
 export type {
   AgentContextEntryInput,
@@ -32,9 +35,6 @@ export interface AgentDescriptor {
 
 export type AgentReasoning = ModelReasoning
 
-/** @deprecated Use {@link AgentReasoning}. */
-export type AgentReasoningLevel = AgentReasoning
-
 export const AGENT_REASONING_LEVELS = MODEL_REASONING_LEVELS
 
 type Simplify<T> = { [K in keyof T]: T[K] } & {}
@@ -98,6 +98,19 @@ export interface AgentToolArtifacts {
   put(input: AgentToolArtifactPutInput): Promise<AgentToolArtifact>
 }
 
+/**
+ * The files attached to the run that invoked a tool: the messages of a chat's thread, or the input
+ * files of a workflow AI task. A child Agent has none.
+ */
+export interface AgentToolAttachments {
+  /**
+   * Open an attachment by the `key` the Agent sees in `$SIXB_ATTACHMENTS`. Returns null when its
+   * stored file is gone, and throws an `AgentToolPublicError` for a key that is not one of this
+   * run's attachments.
+   */
+  open(key: string): Promise<OpenedFileRef | null>
+}
+
 export type AgentToolTextContent = {
   readonly type: "text"
   readonly text: string
@@ -120,6 +133,22 @@ export type AgentToolResult = {
   readonly content: readonly AgentToolContent[]
 }
 
+/**
+ * The run's domain SDK as an agent tool sees it. Unlike workflow steps and actions, it acts as the
+ * run's requester: the signed-in user in a chat, that same user in a child Agent, and the step's
+ * groups in a workflow AI task.
+ *
+ * A structural view of the public `Sixb` SDK, like `WorkflowRuntimeFacade`: the handler receives the
+ * run's bound SDK, and this type guides it to what a tool should do. It reads objects and changes
+ * them by requesting actions, which validate and record the change. Authority comes from the run,
+ * not from this view.
+ */
+export interface AgentToolRuntimeFacade extends ObjectReader {
+  readonly actions: ActionsRuntime
+  readonly models: ModelsRuntime
+  readonly connector: ConnectorRuntime
+}
+
 /** The narrow, run-scoped surface passed to an agent tool handler. */
 export interface AgentToolRunContext<
   TInput extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>,
@@ -128,9 +157,10 @@ export interface AgentToolRunContext<
   readonly toolCallId: string
   readonly signal: AbortSignal
   readonly run: AgentToolRunInfo
-  readonly connector: ConnectorRuntime
+  readonly sixb: AgentToolRuntimeFacade
   readonly logger: Logger
   readonly artifacts: AgentToolArtifacts
+  readonly attachments: AgentToolAttachments
 }
 
 /** Agent tool handlers may return only values safe to persist in agent messages. */