@sixb/core 0.1.11 → 0.1.12

package/src/ontology/vector-profiles.ts

@@ -0,0 +1,35 @@
+import type { ObjectVectorSearchProfile } from "./types"
+
+/** Metadata-only copy. Executable provider objects and credentials never leave the host. */
+export function snapshotVectorProfiles(
+  profiles: Readonly<Record<string, ObjectVectorSearchProfile>>
+): Readonly<Record<string, ObjectVectorSearchProfile>> {
+  const snapshot: Record<string, ObjectVectorSearchProfile> = Object.create(null)
+  for (const [name, profileDefinition] of Object.entries(profiles)) {
+    const { providerId, modelId, definition } = profileDefinition.model
+    snapshot[name] = Object.freeze({
+      source: Object.freeze([...profileDefinition.source]),
+      model: Object.freeze({
+        providerId,
+        modelId,
+        definition: Object.freeze({
+          kind: "embedding" as const,
+          providerId,
+          modelId,
+          dimensions: definition.dimensions,
+          ...(definition.representation
+            ? {
+                representation: Object.freeze({
+                  name: definition.representation.name,
+                  ...(definition.representation.version === undefined
+                    ? {}
+                    : { version: definition.representation.version }),
+                }),
+              }
+            : {}),
+        }),
+      }),
+    })
+  }
+  return Object.freeze(snapshot)
+}

package/src/queues/in-memory.ts

@@ -20,6 +20,7 @@ import type {
   SubagentQueueJob,
   SyncQueueJobFailureCode,
   SyncRunRequestedQueueJob,
+  VectorIndexingQueueJob,
   WorkflowQueueJob,
   WorkflowQueueJobFailureCode,
 } from "./types"
@@ -402,6 +403,10 @@ export class InMemoryQueues implements Queues {
   readonly scope = "process" as const
   private readonly store = new InMemoryQueueStore()
 
+  readonly vectorIndexing = new InMemoryQueue<
+    VectorIndexingQueueJob,
+    "internal.unexpected" | "runtime.cancelled"
+  >(this.store, "vector.indexing")
   readonly syncRuns = new InMemoryQueue<SyncRunRequestedQueueJob, SyncQueueJobFailureCode>(
     this.store,
     "sync.runs"

package/src/queues/index.ts

@@ -37,6 +37,7 @@ export type {
   SubagentRunRequestedQueueJob,
   SyncQueueJobFailureCode,
   SyncRunRequestedQueueJob,
+  VectorIndexingQueueJob,
   WorkflowQueueJob,
   WorkflowQueueJobFailureCode,
   WorkflowRunRequestedQueueJob,

package/src/queues/types.ts

@@ -226,7 +226,17 @@ export type AgentQueueJob =
   | AgentWorkflowNodeRequestedQueueJob
   | AgentAiUsageRecordRequestedQueueJob
 
+/** Internal lane hosted by ProjectionWorker. */
+export type VectorIndexingQueueJob = QueueJob<
+  "vector.index.requested",
+  { readonly indexingId: string }
+>
+
 export interface Queues {
+  readonly vectorIndexing: Queue<
+    VectorIndexingQueueJob,
+    "internal.unexpected" | "runtime.cancelled"
+  >
   readonly syncRuns: Queue<SyncRunRequestedQueueJob, SyncQueueJobFailureCode>
   readonly pipelines: Queue<PipelineRunRequestedQueueJob, PipelineQueueJobFailureCode>
   readonly projections: Queue<ProjectionRunRequestedQueueJob, ProjectionQueueJobFailureCode>

package/src/runtime/create.ts

@@ -21,6 +21,7 @@ import type { RuleDefinition } from "../rules"
 import type { SandboxFactory } from "../sandboxes"
 import type { ScheduleDefinition } from "../schedules"
 import type { GroupDefinition, MembershipPolicyDefinition, RoleDefinition } from "../security"
+import type { ParamsConfig } from "../shared/params/types"
 import type { ShareDefinition } from "../shares"
 import type { Storage } from "../storage"
 import type { SyncDefinition } from "../syncs"
@@ -29,14 +30,14 @@ import { RuntimeError } from "./errors"
 import { SixbHost } from "./host"
 import type { OntologySource } from "./types"
 
-export interface CreateSixbOptions {
+export interface CreateSixbOptions<in out TParams extends ParamsConfig = ParamsConfig> {
   id?: string
   broker: Broker
   storage: Storage
   lakeStorage: LakeStorage
   blobStorage: BlobStorage
   queues: Queues
-  sandboxes?: SandboxFactory
+  sandboxes?: SandboxFactory<TParams>
   /** Optional process-level output provider. Omit for broker-only logging. */
   logger?: LoggerProvider
   /** Broker capture controls, independent from the output provider. */
@@ -79,9 +80,9 @@ export interface CreateSixbOptions {
  * `rules/`, `workflows/`, `shares/`, and `security/{groups,roles,policies}/`
  * relative to `projectRoot`.
  */
-export async function createSixb(
-  options: CreateSixbOptions
-): Promise<SixbHost<readonly OntologySource[]>> {
+export async function createSixb<const TParams extends ParamsConfig = ParamsConfig>(
+  options: CreateSixbOptions<TParams>
+): Promise<SixbHost<readonly OntologySource[], TParams>> {
   assertNoAgentDefinitions(options)
   const projectRoot = resolve(options.projectRoot ?? process.cwd())
 
@@ -99,7 +100,7 @@ export async function createSixb(
   // Explicit definitions come first so local setup can override ordering while duplicate ids are
   // still rejected by the SixbHost constructor. Every family merges — `actions` and `projections`
   // used to *replace* discovery instead, silently and undocumented.
-  return new SixbHost<readonly OntologySource[]>({
+  return new SixbHost<readonly OntologySource[], TParams>({
     id: options.id,
     ontology: allSources,
     broker: options.broker,

package/src/runtime/host.ts

@@ -53,12 +53,21 @@ import {
 } from "../maintenance"
 import { createOntologyMaterializer, type OntologyMaterializerContract } from "../materializer"
 import type { ModelCatalogInput } from "../models"
+import { bindEmbeddingModels } from "../models/execution/embedding"
+import { ModelExecutionSession } from "../models/execution/session"
+import { createVectorIndexingRuntime } from "../objects/vectors/indexing"
+import { registerVectorIndexingRuntime } from "../objects/vectors/indexing-runtime"
 import type { PipelineDefinition } from "../pipelines/types"
 import { registerProjectionRegistry } from "../projections/internal"
 import type { ProjectionDefinition } from "../projections/types"
 import type { Queues } from "../queues"
 import type { RuleDefinition } from "../rules"
 import type { SandboxFactory } from "../sandboxes"
+import {
+  createSandboxDefinition,
+  type InferSandboxParams,
+  type SandboxDefinition,
+} from "../sandboxes/configuration"
 import { type SchedulerController, SchedulerRuntime } from "../scheduler"
 import type { ScheduleDefinition } from "../schedules"
 import type {
@@ -67,6 +76,7 @@ import type {
   RoleDefinition,
   SecurityDefinitionCatalog,
 } from "../security"
+import type { ParamsConfig } from "../shared/params/types"
 import type { ShareDefinition } from "../shares"
 import type { Storage } from "../storage"
 import type { SyncDefinition } from "../syncs"
@@ -83,7 +93,10 @@ import { createBoundSixb, type Sixb, type SixbDependencies } from "./sixb"
 import { StorageReadiness } from "./storage-readiness"
 import type { OntologySource, SixbHostContext, SixbRuntimeContext } from "./types"
 
-export interface SixbHostOptions<TOntologySources extends readonly OntologySource[]> {
+export interface SixbHostOptions<
+  TOntologySources extends readonly OntologySource[],
+  in out TParams extends ParamsConfig = ParamsConfig,
+> {
   id?: string
   ontology: TOntologySources
   broker: Broker
@@ -91,7 +104,7 @@ export interface SixbHostOptions<TOntologySources extends readonly OntologySourc
   lakeStorage: LakeStorage
   blobStorage: BlobStorage
   queues: Queues
-  sandboxes?: SandboxFactory
+  sandboxes?: SandboxFactory<TParams>
   /** Optional process-level output provider. Omit for broker-only logging. */
   logger?: LoggerProvider
   /** Broker capture controls, independent from the output provider. */
@@ -125,6 +138,7 @@ export interface SixbHostOptions<TOntologySources extends readonly OntologySourc
 
 export class SixbHost<
   TOntologySources extends readonly OntologySource[] = readonly OntologySource[],
+  TParams extends ParamsConfig = ParamsConfig,
 > {
   readonly projectId: string
   private readonly webhookRegistry: WebhookRegistry
@@ -135,6 +149,7 @@ export class SixbHost<
   private readonly storageReadiness: StorageReadiness
   private readonly connectorService: ConnectorService
   private readonly materializer: OntologyMaterializerContract
+  readonly sandboxDefinition?: SandboxDefinition
   readonly definitions: SixbDefinitions
   readonly broker: Broker
   readonly events: DomainEventLog
@@ -143,12 +158,12 @@ export class SixbHost<
   readonly lakeStorage: LakeStorage
   readonly blobStorage: BlobStorage
   readonly queues: Queues
-  readonly sandboxes?: SandboxFactory
+  readonly sandboxes?: Pick<SandboxFactory, "create" | "resume">
   readonly projectRoot: string
   readonly scheduler: SchedulerController
   readonly auth: AuthRuntime
 
-  constructor(options: SixbHostOptions<TOntologySources>) {
+  constructor(options: SixbHostOptions<TOntologySources, TParams>) {
     const errorReporter = attachSixbErrorReporter(this, options.onError)
     this.projectId = options.id ?? "default"
     this.broker = options.broker
@@ -174,6 +189,10 @@ export class SixbHost<
 
     const definitions = resolveDefinitions(options)
     this.definitions = definitions
+    this.sandboxDefinition =
+      options.sandboxes?.configuration === undefined
+        ? undefined
+        : createSandboxDefinition(options.sandboxes.configuration, definitions.ontology)
     registerProjectionRegistry(this, definitions.projections)
 
     this.auth = new AuthRuntime({
@@ -226,6 +245,7 @@ export class SixbHost<
     })
 
     this.hostContext = {
+      embeddingModels: definitions.models?.embedding,
       projectId: this.projectId,
       broker: this.broker,
       ontology: definitions.ontology,
@@ -236,6 +256,10 @@ export class SixbHost<
     }
     registerProjectionRegistry(this.hostContext, definitions.projections)
     shareSixbErrorReporter(this, this.hostContext)
+    registerVectorIndexingRuntime(
+      this,
+      createVectorIndexingRuntime(this.hostContext, this.materializer)
+    )
     this.scheduler = new SchedulerRuntime({
       schedules: definitions.schedules.list(),
       events: this.eventService,
@@ -243,21 +267,29 @@ export class SixbHost<
   }
 
   /** Bind an existing opaque scope. This method never creates or escalates authority. */
-  withScope(scope: ExecutionScope): Sixb<TOntologySources> {
+  withScope(scope: ExecutionScope): Sixb<TOntologySources, InferSandboxParams<TParams>> {
     const capturedScope = captureExecutionScope(scope)
     const authorization = resolveExecutionScopeAuthorization(this.projectId, capturedScope)
     if (authorization.type === "unrestricted" && authorization.ref.type === "kernel") {
       throw new Error("[Sixb] Kernel authority cannot be bound to the domain SDK.")
     }
 
+    const modelExecution = new ModelExecutionSession(
+      { ...this.hostContext, runtimeAuthorization: capturedScope.authorization },
+      capturedScope.execution
+    )
+    const embeddingModels = bindEmbeddingModels(this.hostContext.embeddingModels, modelExecution)
     const objectReader = createAuthorizedObjectReader({
       scope: capturedScope,
       ontology: this.hostContext.ontology,
       objectStorage: this.storage.objects,
+      embeddingModels,
     })
 
     const runtime: SixbRuntimeContext = {
       ...this.hostContext,
+      embeddingModels,
+      modelExecution,
       runtimeAuthorization: capturedScope.authorization,
       objectReader,
       ...(authorization.type === "principal" ? { authorization: authorization.context } : {}),
@@ -269,7 +301,7 @@ export class SixbHost<
         notifyCommittedFacts: () => this.committedFacts.notify(),
       })
     )
-    return createBoundSixb<TOntologySources>(
+    return createBoundSixb<TOntologySources, InferSandboxParams<TParams>>(
       runtime,
       this.sixbDependencies(),
       capturedScope.execution
@@ -329,6 +361,10 @@ export class SixbHost<
   private sixbDependencies(): SixbDependencies {
     return {
       definitions: this.definitions,
+      sandbox: this.sandboxDefinition && {
+        definition: this.sandboxDefinition,
+        supportsPersistence: typeof this.sandboxes?.resume === "function",
+      },
       logging: this.logging,
       connectorService: this.connectorService,
       ...(this.connectorService.connectionProcess === undefined

package/src/runtime/internal.ts

@@ -10,6 +10,9 @@ export type {
 } from "../connectors/connections/contracts"
 export type { ConnectorConnectionsRuntime } from "../connectors/connections/execution"
 export type { AuthorizedObjectReader } from "../execution/authorized-object-reader"
+export { VectorIndexingDeferred } from "../objects/vectors/indexing"
+export type { VectorIndexingRuntime } from "../objects/vectors/indexing-runtime"
+export { getVectorIndexingRuntime } from "../objects/vectors/indexing-runtime"
 export type { OntologyMutationRuntime } from "./ontology-mutations"
 export {
   createOntologyMutationRuntime,

package/src/runtime/resolve-definitions.ts

@@ -7,6 +7,7 @@ import type { ConnectorDefinition } from "../connectors"
 import type { DatasetDefinition } from "../datasets/types"
 import { assertDatasetDefinition } from "../datasets/validation"
 import { createModelCatalog, type ModelCatalogInput } from "../models"
+import { sameEmbeddingModel } from "../models/embedding-model"
 import { OntologyRegistry } from "../ontology"
 import type { PipelineDefinition } from "../pipelines/types"
 import { ProjectionRegistry } from "../projections"
@@ -70,6 +71,23 @@ export function resolveDefinitions(options: DefinitionOptions): ResolvedDefiniti
   })
 
   const models = options.models === undefined ? undefined : createModelCatalog(options.models)
+  for (const type of ontology.listObjectTypes()) {
+    for (const [name, profile] of Object.entries(type.search?.vectors ?? {})) {
+      const registered = models?.embedding.getByRef({
+        provider: profile.model.providerId,
+        modelId: profile.model.modelId,
+      })
+      if (!registered || !sameEmbeddingModel(registered.model, profile.model)) {
+        throw new Error(
+          "[Sixb] Vector profile " +
+            type.id +
+            "." +
+            name +
+            " requires its model in models.embedding with matching identity and dimensions."
+        )
+      }
+    }
+  }
   const tools = createAgentToolCatalog(options.tools)
   const connectorsById = indexUniqueDefinitions("connector", options.connectors ?? [])
 
@@ -147,7 +165,7 @@ export function resolveDefinitions(options: DefinitionOptions): ResolvedDefiniti
     workflowIds: new Set(workflowsById.keys()),
     syncIds: new Set(syncsById.keys()),
     pipelineIds: new Set(pipelinesById.keys()),
-    agentAvailable: models !== undefined,
+    agentAvailable: models?.language !== undefined,
     connectorIds: new Set(connectorsById.keys()),
     shareIds: new Set(sharesById.keys()),
     getSubTypes: (objectTypeId) => ontology.listSubTypes(objectTypeId),

package/src/runtime/sixb.ts

@@ -22,6 +22,7 @@ import { createObjectsRuntime, type ObjectsRuntime } from "../objects/execution"
 import { createPipelinesRuntime, type PipelinesRuntime } from "../pipelines/execution"
 import { createProjectionsRuntime, type ProjectionsRuntime } from "../projections/execution"
 import { createRulesRuntime, type RulesRuntime } from "../rules/execution"
+import type { SandboxDefinition } from "../sandboxes/configuration"
 import { createSchedulesRuntime, type SchedulesRuntime } from "../schedules/execution"
 import { createSharesRuntime, type SharesRuntime } from "../shares/execution"
 import { createSyncsRuntime, type SyncsRuntime } from "../syncs/execution"
@@ -33,6 +34,7 @@ import type { OntologySource, SixbRuntimeContext } from "./types"
 /** Domain SDK bound to one immutable execution and one registered runtime authority. */
 export interface Sixb<
   TOntologySources extends readonly OntologySource[] = readonly OntologySource[],
+  TParams extends Record<string, unknown> = Record<string, unknown>,
 > {
   readonly execution: ExecutionContext
   readonly objects: ObjectsRuntime<TOntologySources>
@@ -43,7 +45,7 @@ export interface Sixb<
   readonly pipelines: PipelinesRuntime
   readonly projections: ProjectionsRuntime
   readonly rules: RulesRuntime
-  readonly agent: AgentRuntime
+  readonly agent: AgentRuntime<TParams>
   readonly models: ModelsRuntime
   readonly aiUsage: AiUsageRuntime
   readonly events: EventsRuntime
@@ -57,6 +59,10 @@ export interface Sixb<
 const boundSixbInstances = new WeakSet<object>()
 
 export interface SixbDependencies {
+  readonly sandbox?: {
+    readonly definition: SandboxDefinition
+    readonly supportsPersistence: boolean
+  }
   readonly definitions: SixbDefinitions
   readonly logging: LoggingService
   readonly connectorService: ConnectorService
@@ -65,11 +71,14 @@ export interface SixbDependencies {
   readonly lakeStorage: LakeStorage
 }
 
-export function createBoundSixb<TOntologySources extends readonly OntologySource[]>(
+export function createBoundSixb<
+  TOntologySources extends readonly OntologySource[],
+  TParams extends Record<string, unknown> = Record<string, unknown>,
+>(
   runtime: SixbRuntimeContext,
   dependencies: SixbDependencies,
   execution: ExecutionContext
-): Sixb<TOntologySources> {
+): Sixb<TOntologySources, TParams> {
   resolveExecutionScopeAuthorization(runtime.projectId, {
     execution,
     authorization: runtime.runtimeAuthorization,
@@ -78,9 +87,9 @@ export function createBoundSixb<TOntologySources extends readonly OntologySource
     reader: runtime.objectReader,
     scope: { execution, authorization: runtime.runtimeAuthorization },
   })
-  const sixb: Sixb<TOntologySources> = {
+  const sixb: Sixb<TOntologySources, TParams> = {
     execution,
-    ...createExecutionFacades<TOntologySources>(runtime, execution, dependencies),
+    ...createExecutionFacades<TOntologySources, TParams>(runtime, execution, dependencies),
   }
   shareOntologyMutationRuntime(runtime, sixb)
   if (dependencies.connectorConnections) {
@@ -96,15 +105,19 @@ export function createBoundSixb<TOntologySources extends readonly OntologySource
 /** Internal nominal guard for execution boundaries that accept a narrow structural host. */
 export function isBoundSixb<
   TOntologySources extends readonly OntologySource[] = readonly OntologySource[],
->(value: unknown): value is Sixb<TOntologySources> {
+  TParams extends Record<string, unknown> = Record<string, unknown>,
+>(value: unknown): value is Sixb<TOntologySources, TParams> {
   return typeof value === "object" && value !== null && boundSixbInstances.has(value)
 }
 
-function createExecutionFacades<TOntologySources extends readonly OntologySource[]>(
+function createExecutionFacades<
+  TOntologySources extends readonly OntologySource[],
+  TParams extends Record<string, unknown>,
+>(
   runtime: SixbRuntimeContext,
   execution: ExecutionContext,
   dependencies: SixbDependencies
-): Omit<Sixb<TOntologySources>, "execution"> {
+): Omit<Sixb<TOntologySources, TParams>, "execution"> {
   return {
     objects: createObjectsRuntime<TOntologySources>(runtime, execution),
     actions: createActionsRuntime(runtime, execution),
@@ -120,7 +133,12 @@ function createExecutionFacades<TOntologySources extends readonly OntologySource
     pipelines: createPipelinesRuntime(runtime, execution, dependencies.definitions.pipelines),
     projections: createProjectionsRuntime(runtime, dependencies.definitions.projections),
     rules: createRulesRuntime(runtime, dependencies.definitions.rules),
-    agent: createAgentRuntime(runtime, execution, dependencies.definitions.models),
+    agent: createAgentRuntime<TParams>(
+      runtime,
+      execution,
+      dependencies.definitions.models,
+      dependencies.sandbox
+    ),
     models: createModelsRuntime(runtime, execution, dependencies.definitions.models),
     aiUsage: createAiUsageRuntime(runtime, dependencies.definitions.security),
     events: createEventsRuntime(runtime),

package/src/runtime/types.ts

@@ -16,6 +16,8 @@ import type { Broker } from "../broker"
 import type { DomainEventLog } from "../events"
 import type { RuntimeAuthorization } from "../execution"
 import type { AuthorizedObjectReader } from "../execution/authorized-object-reader"
+import type { EmbeddingModelCatalog } from "../models"
+import type { ModelExecutionSession } from "../models/execution/session"
 import type {
   ObjectQuery,
   ObjectQueryExplanation,
@@ -28,6 +30,7 @@ import type {
   ObjectQuerySortDirection,
   ValidatedObjectQuery,
 } from "../objects/query"
+import type { ObjectVectorHandle, VectorProfileName } from "../objects/vectors/types"
 import type { ObjectLinkTargetType, ObjectRef, ObjectType, Property, ValueType } from "../ontology"
 import type {
   InferObjectProperties,
@@ -49,6 +52,7 @@ import type { ActionRunRecord, ObjectLinkRow, Storage } from "../storage"
  * registered runtime authority.
  */
 export interface SixbHostContext {
+  readonly embeddingModels?: EmbeddingModelCatalog
   readonly projectId: string
   readonly broker: Broker
   readonly ontology: OntologyRegistry
@@ -60,6 +64,8 @@ export interface SixbHostContext {
 
 /** Host dependencies paired with the process-local authority of one bound execution. */
 export interface SixbRuntimeContext extends SixbHostContext {
+  /** Internal model-call session shared by object operations and model generation. */
+  readonly modelExecution?: ModelExecutionSession
   readonly runtimeAuthorization: RuntimeAuthorization
   /** Core-owned read boundary carrying this exact execution authority. */
   readonly objectReader: AuthorizedObjectReader
@@ -429,6 +435,7 @@ export type ListResultWithoutTotal<T> = {
 }
 
 export type ObjectQueryListOptions = {
+  signal?: AbortSignal
   includeTotal?: boolean
 }
 
@@ -716,7 +723,9 @@ export type ObjectQueryRow<
   TValueTypes extends readonly ValueType[],
   TLinks,
 > = TObjectType extends ObjectTypeWithPropertyTokens
-  ? ExpandedRowForSource<TObjectType, TValueTypes, ExpansionLinksForSource<TLinks, TObjectType>>
+  ? ExpandedRowForSource<TObjectType, TValueTypes, ExpansionLinksForSource<TLinks, TObjectType>> & {
+      score?: number
+    }
   : never
 
 /**
@@ -844,10 +853,10 @@ export interface ObjectQueryBuilder<
     options?: { fields?: readonly ObjectSetQueryPropertyToken<TObjectType>[] }
   ): ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes, TLinks>
 
-  /** Search a vector property at the current object type. */
+  /** Search a profile; text is embedded server-side with its configured model. */
   vector(
-    property: ObjectSetQueryPropertyToken<TObjectType>,
-    vector: readonly number[],
+    profile: VectorProfileName<TObjectType>,
+    vector: string,
     options: { k: number }
   ): ObjectQueryBuilder<TObjectType, TRegisteredObjectTypes, TValueTypes, TLinks>
 
@@ -941,9 +950,11 @@ export interface ObjectQueryBuilder<
   list(): Promise<ListResult<ObjectQueryRow<TObjectType, TValueTypes, TLinks>>>
   list(options: {
     includeTotal: false
+    signal?: AbortSignal
   }): Promise<ListResultWithoutTotal<ObjectQueryRow<TObjectType, TValueTypes, TLinks>>>
   list(options: {
     includeTotal?: true
+    signal?: AbortSignal
   }): Promise<ListResult<ObjectQueryRow<TObjectType, TValueTypes, TLinks>>>
   list(
     options?: ObjectQueryListOptions
@@ -969,6 +980,7 @@ export interface ObjectByIdHandle<
   TObjectType extends ObjectTypeWithPropertyTokens,
   TValueTypes extends readonly ValueType[],
 > {
+  vector(profile: VectorProfileName<TObjectType>): ObjectVectorHandle
   /** Get the object at this id, or null if it doesn't exist. */
   get(): Promise<TwinObject<TObjectType, TValueTypes> | null>
 

package/src/sandboxes/README.md

@@ -0,0 +1,41 @@
+# Sandboxes
+
+Factories define environments; threads retain immutable parameters; runs provide current authority.
+
+- `create()` applies static source/setup. An explicit `environment` replaces both, including `{}`.
+  Dynamic recipes require an execution-resolved environment; providers never invoke resolvers.
+- Selection and validation happen before provisioning. Initial source access must be allowed by
+  the session network policy. Creation runs setup once; resume never replays it.
+- Runs without a thread binding explicitly select `{}`; shared env/network defaults remain session
+  settings, not an implicit project binding. Unsupported provider capabilities fail explicitly.
+
+- [Configuration](./configuration.ts) validates and snapshots recipes, sharing Action parameter
+  schemas. Resolvers receive the execution-scoped SDK. Only parameters are stored in `sandbox_params`.
+- [Initialization](./environment.ts) runs once, after session settings are applied. Git uses
+  `repository/`; source-free environments use the provider root. Vercel skips native cloning on this
+  path to avoid preparing the source twice. Confirmed loss uses a fresh name and replays setup.
+- Threads expose immutable `sandboxParams` and worker-owned `sandboxState`; its `name` is the
+  provider's exact persistent name, also checked during transitions and explicit recreation.
+- The conversation environment owns acquisition and preservation, including preparation failures.
+  It resolves access before compaction, drains operations, cleans transient files and confirms
+  preservation before the worker finalizes. Source identity/revision cannot change on resume.
+- Git checkouts exclude `.sixb/agent/` locally before run files are written. Tracked runtime files,
+  redirected metadata and repository rules overriding this exclusion block acquisition or saving.
+  This prevents accidental staging, not deliberate publication with `git add -f`.
+- Confirmed missing/expired state allows one replacement attempt under the current execution fence.
+  A durable reset timestamp informs subsequent model calls; conversation history is preserved.
+- Omitted network policy permits API/source access. Explicit policies are never widened; incompatible
+  policies fail before provisioning. Guest-readable `env` is not a Git credential channel.
+
+## V1 limits
+
+Vercel requests can outlive their worker: storage fencing cannot cancel provider-side work.
+Uncertain sandboxes stay blocked; explicit recreation uses a new name without deleting old state.
+Saved files remain subject to provider retention.
+
+Source `auth` stays host-side. Named providers advertising `supportsRequestCredentials` must apply
+execution-prepared credentials; direct create/resume never invoke `auth` implicitly. They apply
+initial credentials before setup and expose session-scoped renewal. Unsupported providers reject
+credentials before provisioning. During initial provisioning/setup, the worker aborts before token
+expiry if no session handle is available yet; renewal begins after acquisition. Normal teardown
+removes injection and revokes grants. A crash cannot guarantee immediate revocation.

package/src/sandboxes/auth.ts

@@ -0,0 +1,17 @@
+import type { SandboxSource } from "./configuration"
+import type { SandboxRequestCredential } from "./sandbox"
+
+/** Per-run source access. Never persist these grants or expose them to the guest. */
+export interface SandboxSourceCredentials {
+  readonly requests: readonly SandboxRequestCredential[]
+  readonly expiresAt: Date
+  revoke(): Promise<void>
+}
+
+/** Integration-owned authentication; grant source.access (read by default), or reject. */
+export interface SandboxSourceAuth {
+  authorize(input: {
+    readonly source: SandboxSource
+    readonly signal: AbortSignal
+  }): Promise<SandboxSourceCredentials>
+}

package/src/sandboxes/config.ts

@@ -0,0 +1,37 @@
+import type { ParamsConfig } from "../shared/params/types"
+import { captureEnvironment, type SandboxConfig } from "./configuration"
+import { SandboxError } from "./errors"
+
+/** Extract only the common recipe; provider credentials and infrastructure stay on the factory. */
+export function sandboxConfig<TParams extends ParamsConfig>(
+  options: SandboxConfig<TParams>
+): SandboxConfig<TParams> {
+  if (options.auth !== undefined && typeof options.auth?.authorize !== "function") {
+    throw new SandboxError("[Sixb] sandboxes.auth requires an authorize function.")
+  }
+  const authorize = options.auth?.authorize.bind(options.auth)
+  if (options.params !== undefined && options.resolve === undefined) {
+    throw new SandboxError("[Sixb] Sandbox params require a resolve function.")
+  }
+  if (options.resolve !== undefined && typeof options.resolve !== "function") {
+    throw new SandboxError("[Sixb] Sandbox resolve must be a function.")
+  }
+  if (
+    options.resolve !== undefined &&
+    (options.source !== undefined || options.setup !== undefined)
+  ) {
+    throw new SandboxError("[Sixb] Use either static source/setup or resolve, not both.")
+  }
+  const environment = captureEnvironment({
+    ...(options.source === undefined ? {} : { source: options.source }),
+    ...(options.setup === undefined ? {} : { setup: options.setup }),
+    ...(options.env === undefined ? {} : { env: options.env }),
+    ...(options.network === undefined ? {} : { network: options.network }),
+  })
+  return Object.freeze({
+    ...(authorize ? { auth: Object.freeze({ authorize }) } : {}),
+    ...environment,
+    ...(options.params === undefined ? {} : { params: structuredClone(options.params) }),
+    ...(options.resolve === undefined ? {} : { resolve: options.resolve }),
+  })
+}