@sixb/core 0.1.20 → 0.1.21

package/src/testing/execution-storage-contract.ts

@@ -1,7 +1,8 @@
-import { describe, expect, test } from "bun:test"
+import { describe, expect, setSystemTime, test } from "bun:test"
 import type { AuthStorage } from "../storage/auth"
 import type {
   CreateExecutionInput,
+  ExecutionRecord,
   ExecutionStorage,
   TrustedPrimitiveKind,
 } from "../storage/executions"
@@ -338,6 +339,126 @@ export function runExecutionStorageContractSuite<TStorage extends ExecutionStora
       })
     })
 
+    test("lists a session's roots in a window and everything they caused", async () => {
+      // Removal proof: drop `parent_execution_id IS NULL` from a provider's root read; the Agent
+      // execution, which copies the session, is listed twice.
+      await withStorage(async (storage) => {
+        await seedAuth(storage.auth)
+        await seedSharedSession(storage)
+
+        const userRequest = (id: string) =>
+          principalRequest({ id, credential: { type: "session", id: "session-user" } })
+
+        await createAt(storage, -60_000, userRequest("before"))
+        const root = await createAt(storage, 0, userRequest("root"))
+        await createAt(storage, 1_000, childOf(root, trustedPrimitive("root-action")))
+        await createAt(
+          storage,
+          2_000,
+          principalRequest({
+            id: "other-user",
+            principal: { type: "user", id: "user-other" },
+            credential: { type: "session", id: "session-other" },
+          })
+        )
+        await createAt(storage, 3_000, delegatedRequest("shared"))
+        await createAt(storage, 4_000, {
+          ...childOf(root, agentExecution("root-agent")),
+          authorizationRef: root.authorizationRef,
+        })
+        await createAt(storage, 10 * 60_000, userRequest("after"))
+        // A descendant counts whenever it was created, after the window too.
+        await createAt(
+          storage,
+          11 * 60_000,
+          childOf(
+            { id: "root-action", correlationId: root.correlationId },
+            trustedPrimitive("late-workflow", {}, "workflow")
+          )
+        )
+
+        const window = {
+          projectId,
+          from: new Date(createdAt.getTime() - 1_000),
+          to: new Date(createdAt.getTime() + 5 * 60_000),
+          limit: 10,
+        }
+
+        const user = await storage.executions.listBySession({
+          ...window,
+          session: { type: "user", id: "session-user" },
+        })
+        expect(user.truncated).toBe(false)
+        expect(user.executions.map((execution) => execution.id)).toEqual([
+          "root",
+          "root-action",
+          "root-agent",
+          "late-workflow",
+        ])
+        expect(user.executions[0]).toEqual(root)
+
+        const shared = await storage.executions.listBySession({
+          ...window,
+          session: { type: "share", id: "share-session-one" },
+        })
+        expect(shared.executions.map((execution) => execution.id)).toEqual(["shared"])
+
+        // The session id is not a credential of any other kind.
+        await expect(
+          storage.executions.listBySession({
+            ...window,
+            session: { type: "share", id: "session-user" },
+          })
+        ).resolves.toEqual({ executions: [], truncated: false })
+      })
+    })
+
+    test("bounds a session's executions, keeping roots and the earliest first", async () => {
+      await withStorage(async (storage) => {
+        await seedAuth(storage.auth)
+
+        for (const [index, id] of ["first", "second", "third"].entries()) {
+          const root = await createAt(
+            storage,
+            index * 1_000,
+            principalRequest({ id, credential: { type: "session", id: "session-user" } })
+          )
+          await createAt(storage, index * 1_000 + 500, childOf(root, trustedPrimitive(`${id}-run`)))
+        }
+
+        const list = (limit: number) =>
+          storage.executions.listBySession({
+            projectId,
+            session: { type: "user", id: "session-user" },
+            from: createdAt,
+            to: new Date(createdAt.getTime() + 60_000),
+            limit,
+          })
+
+        const roots = await list(2)
+        expect(roots.truncated).toBe(true)
+        expect(roots.executions.map((execution) => execution.id)).toEqual(["first", "second"])
+
+        const partial = await list(4)
+        expect(partial.truncated).toBe(true)
+        expect(partial.executions).toHaveLength(4)
+        expect(partial.executions.map((execution) => execution.id)).toEqual(
+          expect.arrayContaining(["first", "second", "third"])
+        )
+
+        const all = await list(6)
+        expect(all.truncated).toBe(false)
+        expect(all.executions.map((execution) => execution.id)).toEqual([
+          "first",
+          "first-run",
+          "second",
+          "second-run",
+          "third",
+          "third-run",
+        ])
+      })
+    })
+
     test("participates in storage transactions and rollback", async () => {
       await withStorage(async (storage) => {
         await expect(
@@ -355,6 +476,31 @@ export function runExecutionStorageContractSuite<TStorage extends ExecutionStora
   })
 }
 
+/** Creates an execution at `offsetMs` after the fixtures' creation time: storage stamps it. */
+async function createAt(
+  storage: ExecutionStorageContractStorage,
+  offsetMs: number,
+  input: CreateExecutionInput
+): Promise<ExecutionRecord> {
+  setSystemTime(new Date(createdAt.getTime() + offsetMs))
+  try {
+    return await storage.executions.create(input)
+  } finally {
+    setSystemTime()
+  }
+}
+
+function childOf(
+  parent: Pick<ExecutionRecord, "id" | "correlationId">,
+  input: CreateExecutionInput
+): CreateExecutionInput {
+  return {
+    ...input,
+    source: { type: "execution", executionId: parent.id },
+    correlationId: parent.correlationId,
+  }
+}
+
 async function seedAuth(auth: AuthStorage): Promise<void> {
   await auth.users.create({
     id: "user-one",

package/src/testing/index.ts

@@ -9,6 +9,10 @@ export {
   type ActionRunStorageContractSuiteOptions,
   runActionRunStorageContractSuite,
 } from "./action-run-storage-contract"
+export {
+  type ActivityStorageContractSuiteOptions,
+  runActivityStorageContractSuite,
+} from "./activity-storage-contract"
 export { createTestAgentExecution } from "./agent-execution"
 export {
   type AgentStorageContractSuiteOptions,
@@ -34,6 +38,11 @@ export {
   runAiUsageStorageContractSuite,
   seedAiUsageStorageContractExecutions,
 } from "./ai-usage-storage-contract"
+export {
+  type ArtifactStorageContractStorage,
+  type ArtifactStorageContractSuiteOptions,
+  runArtifactStorageContractSuite,
+} from "./artifact-storage-contract"
 export {
   type AuthStorageContractSuiteOptions,
   runAuthStorageContractSuite,

package/src/testing/lake-merge-storage-contract.ts

@@ -285,6 +285,44 @@ export function runLakeMergeStorageContractSuite<TStorage extends LakeStorage>(
         expect(await storage.listVersions(invoices.id)).toHaveLength(1)
       })
     })
+
+    test("a merge keeps its parent's lineage", async () => {
+      await withStorage(async (storage) => {
+        await storage.createDataset(invoices)
+
+        const source = (column: string) => ({ datasetId: "contract.source", column })
+        const lineage = {
+          rows: [source("tenant")],
+          columns: { id: [source("id")], note: [source("amount")], status: [source("state")] },
+        }
+
+        const pipeline = { kind: "pipeline", id: "contract-pipeline" } as const
+        const seed = await storage.beginWrite({ dataset: invoices, producer: pipeline, lineage })
+        await seed.writeRows([{ id: "inv_1", status: "open", note: "120.00" }])
+        await seed.commit()
+
+        const sync = { kind: "sync", id: "sync-invoices" } as const
+        const merge = await storage.beginMerge({ dataset: invoices, producer: sync })
+        await merge.writeChanges([change.upsert({ id: "inv_2", status: "paid", note: null })])
+        const merged = expectCreated(await merge.commit())
+
+        // Its own rows depend on its own columns only; the rows it keeps, on what they did.
+        expect(merged.lineage).toEqual(lineage)
+        expect((await storage.getVersion(invoices.id, merged.versionId))?.lineage).toEqual(lineage)
+
+        // A parent that records no lineage could hold anything, and so could the merge.
+        const unanalyzed = await storage.beginWrite({ dataset: invoices, producer: pipeline })
+        await unanalyzed.writeRows([{ id: "inv_1", status: "open", note: "120.00" }])
+        const legacy = await unanalyzed.commit()
+
+        const next = await storage.beginMerge({ dataset: invoices, producer: sync })
+        await next.writeChanges([change.upsert({ id: "inv_3", status: "open", note: null })])
+
+        expect(expectCreated(await next.commit()).lineage).toEqual({
+          unknown: `version '${legacy.versionId}' of '${invoices.id}' recorded no column lineage`,
+        })
+      })
+    })
   })
 }
 

package/src/testing/lake-storage-contract.ts

@@ -2,7 +2,14 @@ import { describe, expect, test } from "bun:test"
 import type { FileRef } from "../blob-storage"
 import { col, type DatasetDefinition, defineDataset } from "../datasets"
 import { LakeStorageError } from "../lake-storage/errors"
-import type { DatasetRow, LakeStorage } from "../lake-storage/types"
+import type {
+  BeginDatasetWriteInput,
+  DatasetColumnRef,
+  DatasetProducer,
+  DatasetRow,
+  DatasetWriteCommitResult,
+  LakeStorage,
+} from "../lake-storage/types"
 
 export type LakeStorageSchemaEvolutionCapability = "strict" | "addNullableColumns"
 
@@ -16,6 +23,8 @@ export interface LakeStorageContractSuiteOptions<TStorage extends LakeStorage =
    * `strict`, which allows metadata-only merges but rejects schema evolution.
    */
   readonly schemaEvolution?: LakeStorageSchemaEvolutionCapability
+  /** Open the same lake again, to check what a provider persists. */
+  readonly reopen?: (storage: TStorage) => TStorage | Promise<TStorage>
   /**
    * Version id that is syntactically valid for the provider but should not
    * exist. Defaults to a generic id accepted by providers without format
@@ -65,6 +74,30 @@ const invoiceRef: FileRef = {
   logicalPath: "invoices/invoice.txt",
 }
 
+const pipeline: DatasetProducer = { kind: "pipeline", id: "contract-pipeline", stepId: "copy" }
+const source = (column: string): DatasetColumnRef => ({ datasetId: "contract.source", column })
+
+/** A step that copies `contract.source` columns, as resolved lineage. */
+const copied = {
+  rows: [],
+  columns: { customerName: [source("name")], orderId: [source("id")] },
+}
+/** The same step, before a fix: it wrote amounts into `customerName`. */
+const fromAmount = {
+  rows: [],
+  columns: { customerName: [source("amount")], orderId: [source("id")] },
+}
+
+async function write(
+  storage: LakeStorage,
+  input: Pick<BeginDatasetWriteInput, "producer" | "lineage" | "mode">,
+  rows: readonly DatasetRow[]
+): Promise<DatasetWriteCommitResult> {
+  const session = await storage.beginWrite({ dataset: writeDataset, ...input })
+  await session.writeRows(rows)
+  return session.commit()
+}
+
 /**
  * Runs the shared `LakeStorage` contract against any provider.
  *
@@ -612,7 +645,7 @@ export function runLakeStorageContractSuite<TStorage extends LakeStorage>(
 
       test("versions changed input lineage even when output rows are identical", () =>
         withStorage(async (storage) => {
-          // Regression proof: omit hasDatasetInputChanges in the provider's no-op branch.
+          // Regression proof: omit hasDatasetProvenanceChanges in the provider's no-op branch.
           // The updated input reference is lost and the stale writer is no longer fenced.
           await storage.createDataset(writeDataset)
           await storage.createDataset(definitionDataset)
@@ -644,6 +677,68 @@ export function runLakeStorageContractSuite<TStorage extends LakeStorage>(
           expect(await collectRows(storage.readRows({ datasetId: writeDataset.id }))).toEqual(rows)
         }))
 
+      test("versions changed column lineage even when output rows are identical", () =>
+        withStorage(async (storage) => {
+          // Regression proof: compare only inputs in the provider's no-op branch. The rerun
+          // reuses the version without lineage, and its rows stay classified with every marking.
+          await storage.createDataset(writeDataset)
+          const rows = [{ orderId: "ord_1", customerName: "Ada" }]
+          const commit = async (
+            write: Pick<BeginDatasetWriteInput, "producer" | "lineage" | "mode">,
+            expectedLatestVersionId: string | null,
+            written: readonly DatasetRow[] = rows
+          ) => {
+            const session = await storage.beginWrite({ dataset: writeDataset, ...write })
+            await session.writeRows(written)
+            return session.commit({ expectedLatestVersionId })
+          }
+
+          const initial = await commit({ producer: pipeline }, null)
+          expect(initial.lineage).toBeUndefined()
+
+          const analyzed = await commit({ producer: pipeline, lineage: copied }, initial.versionId)
+          expect(analyzed).toMatchObject({ outcome: "created", lineage: copied })
+
+          // Order and repetition do not change a lineage.
+          const reordered = {
+            rows: [],
+            columns: {
+              orderId: [...copied.columns.orderId, ...copied.columns.orderId],
+              customerName: copied.columns.customerName,
+            },
+          }
+          expect(
+            await commit({ producer: pipeline, lineage: reordered }, analyzed.versionId)
+          ).toMatchObject({ outcome: "unchanged", versionId: analyzed.versionId })
+
+          // A run that recorded no lineage is a change too: reusing the analyzed version would
+          // classify its rows by a lineage the run did not record.
+          const unanalyzed = await commit({ producer: pipeline }, analyzed.versionId)
+          expect(unanalyzed).toMatchObject({ outcome: "created" })
+          expect(
+            (await storage.getVersion(writeDataset.id, unanalyzed.versionId))?.lineage
+          ).toBeUndefined()
+
+          // An empty append compares what it would store, after merging its parent's lineage.
+          const analyzedAgain = await commit(
+            { producer: pipeline, lineage: copied },
+            unanalyzed.versionId
+          )
+
+          const append = { producer: pipeline, mode: "append" } as const
+          const narrower = { rows: [], columns: { ...copied.columns, customerName: [] } }
+          expect(
+            await commit({ ...append, lineage: narrower }, analyzedAgain.versionId, [])
+          ).toMatchObject({ outcome: "unchanged", versionId: analyzedAgain.versionId })
+
+          const wider = { rows: [source("tenant")], columns: copied.columns }
+          const widened = await commit({ ...append, lineage: wider }, analyzedAgain.versionId, [])
+          expect(widened).toMatchObject({
+            outcome: "created",
+            lineage: { rows: [source("tenant")], columns: copied.columns },
+          })
+        }))
+
       test("creates an initial empty append version", async () => {
         await withStorage(async (storage) => {
           await storage.createDataset(writeDataset)
@@ -939,6 +1034,156 @@ export function runLakeStorageContractSuite<TStorage extends LakeStorage>(
         })
       })
     })
+
+    describe("resolved column lineage", () => {
+      test("stores the lineage of every version, in a canonical form, across reopening", async () => {
+        let storage = await options.createStorage()
+        try {
+          // A provider that stores lineage says so: Sixb then reads a version without lineage as
+          // one committed before the provider recorded it, not as one whose lineage was dropped.
+          expect(storage.recordsLineage).toBe(true)
+
+          await storage.createDataset(writeDataset)
+          const synced = await write(storage, { producer: { kind: "sync", id: "contract-sync" } }, [
+            { orderId: "ord_1", customerName: "Ada" },
+          ])
+
+          // Outside pipelines, a version depends on its own columns only.
+          expect(synced.lineage).toEqual({ rows: [], columns: { customerName: [], orderId: [] } })
+
+          const repeated = {
+            rows: [source("tenant"), source("tenant")],
+            columns: {
+              orderId: [source("id")],
+              customerName: [source("name"), source("amount"), source("name")],
+              dropped: [source("id")],
+            },
+          }
+          const computed = await write(storage, { producer: pipeline, lineage: repeated }, [
+            { orderId: "ord_1", customerName: "Ada" },
+          ])
+
+          const canonical = {
+            rows: [source("tenant")],
+            columns: {
+              customerName: [source("amount"), source("name")],
+              orderId: [source("id")],
+            },
+          }
+          expect(computed.lineage).toEqual(canonical)
+
+          if (options.reopen) storage = await options.reopen(storage)
+
+          expect((await storage.getVersion(writeDataset.id, computed.versionId))?.lineage).toEqual(
+            canonical
+          )
+          expect((await storage.getLatestVersion(writeDataset.id))?.lineage).toEqual(canonical)
+
+          const listed = await storage.listVersions(writeDataset.id)
+          expect(Object.fromEntries(listed.map((v) => [v.versionId, v.lineage]))).toEqual({
+            [computed.versionId]: canonical,
+            [synced.versionId]: synced.lineage,
+          })
+        } finally {
+          await options.teardown?.(storage)
+        }
+      })
+
+      test("an append keeps its parent's lineage and a snapshot replaces it", () =>
+        withStorage(async (storage) => {
+          await storage.createDataset(writeDataset)
+          await write(storage, { producer: pipeline, lineage: fromAmount }, [
+            { orderId: "ord_1", customerName: "120.00" },
+          ])
+
+          const appended = await write(
+            storage,
+            { producer: pipeline, lineage: copied, mode: "append" },
+            [{ orderId: "ord_2", customerName: "Grace" }]
+          )
+
+          expect(appended.lineage).toEqual({
+            rows: [],
+            columns: {
+              customerName: [source("amount"), source("name")],
+              orderId: [source("id")],
+            },
+          })
+
+          const replaced = await write(storage, { producer: pipeline, lineage: copied }, [
+            { orderId: "ord_2", customerName: "Grace" },
+          ])
+          expect(replaced.lineage).toEqual(copied)
+        }))
+
+      test("a version that keeps rows of an unknown history records it as unknown", () =>
+        withStorage(async (storage) => {
+          await storage.createDataset(writeDataset)
+          const unanalyzed = await write(storage, { producer: pipeline }, [
+            { orderId: "ord_1", customerName: "Ada" },
+          ])
+          expect(unanalyzed.lineage).toBeUndefined()
+
+          const unknown = {
+            unknown: `version '${unanalyzed.versionId}' of '${writeDataset.id}' recorded no column lineage`,
+          }
+
+          const synced = await write(
+            storage,
+            { producer: { kind: "sync", id: "contract-sync" }, mode: "append" },
+            [{ orderId: "ord_2", customerName: "Grace" }]
+          )
+          expect(synced.lineage).toEqual(unknown)
+
+          // The reason keeps naming where the lineage was lost.
+          const computed = await write(
+            storage,
+            { producer: pipeline, lineage: copied, mode: "append" },
+            [{ orderId: "ord_3", customerName: "Katherine" }]
+          )
+
+          expect(computed.lineage).toEqual(unknown)
+          expect((await storage.getVersion(writeDataset.id, computed.versionId))?.lineage).toEqual(
+            unknown
+          )
+
+          const replaced = await write(storage, { producer: pipeline, lineage: copied }, [
+            { orderId: "ord_3", customerName: "Katherine" },
+          ])
+          expect(replaced.lineage).toEqual(copied)
+        }))
+
+      test("a schema change keeps its parent's lineage", () =>
+        withStorage(async (storage) => {
+          if (schemaEvolution === "strict") return
+
+          const initial = defineDataset("contract.lineage.schema_evolution", {
+            schema: [col("invoiceId", "string")],
+          })
+          const widened = defineDataset("contract.lineage.schema_evolution", {
+            schema: [col("invoiceId", "string"), col("currency", "string", { nullable: true })],
+          })
+
+          await storage.createDataset(initial)
+          const session = await storage.beginWrite({
+            dataset: initial,
+            producer: pipeline,
+            lineage: { rows: [source("tenant")], columns: { invoiceId: [source("id")] } },
+          })
+          await session.writeRows([{ invoiceId: "inv_1" }])
+          await session.commit()
+
+          await storage.createDataset(widened)
+          const [schemaVersion] = await storage.listVersions(initial.id, 1)
+          expect(schemaVersion?.mode).toBe("schema")
+
+          // Its rows hold no currency yet.
+          expect(schemaVersion?.lineage).toEqual({
+            rows: [source("tenant")],
+            columns: { currency: [], invoiceId: [source("id")] },
+          })
+        }))
+    })
   })
 }
 

package/src/testing/materializer-storage-contract.ts

@@ -2128,6 +2128,7 @@ function observeActionRunRecords(storage: ContractStorage) {
             },
             recordEffects: (input) => actionRuns.recordEffects(input),
             getById: (input) => actionRuns.getById(input),
+            getByExecutionIds: (input) => actionRuns.getByExecutionIds(input),
             list: (input) => actionRuns.list(input),
           }
           return run(

package/src/testing/ontology-storage-contract.ts

@@ -721,6 +721,60 @@ export function runOntologyStorageContractSuite<TStorage extends OntologyStorage
       })
     })
 
+    test("lists the dataset version each active source applied, in one read", async () => {
+      await withStorage(async (storage) => {
+        expect(
+          await storage.ontology.sources.listActive({ projectId: "contract-project" })
+        ).toEqual([])
+
+        const devices = await createReadyEmptyCandidate(storage, "run-a", "candidate-a", "01")
+        await activateEmptyCandidate(storage, devices, null, "commit-a", "2026-01-03T00:00:00.000Z")
+
+        const others = await createReadyEmptyCandidate(
+          storage,
+          "run-b",
+          "candidate-b",
+          "02",
+          "contract.others"
+        )
+        await activateEmptyCandidate(storage, others, null, "commit-b", "2026-01-04T00:00:00.000Z")
+
+        // A newer version supersedes the first one; a ready candidate is not active yet.
+        const newer = await createReadyEmptyCandidate(storage, "run-c", "candidate-c", "05")
+        const activeDevices = await storage.ontology.sources.getActive({
+          projectId: "contract-project",
+          source: devices.source,
+        })
+        await activateEmptyCandidate(
+          storage,
+          newer,
+          activeDevices,
+          "commit-c",
+          "2026-01-06T00:00:00.000Z"
+        )
+        await createReadyEmptyCandidate(storage, "run-d", "candidate-d", "07", "contract.pending")
+
+        const active = await storage.ontology.sources.listActive({ projectId: "contract-project" })
+        expect(
+          [...active].sort((a, b) => a.source.projectionId.localeCompare(b.source.projectionId))
+        ).toEqual([
+          {
+            source: { projectionId: "contract.devices" },
+            datasetVersion: newer.identity.datasetVersion,
+            projectionRevision: "projection-contract-revision",
+          },
+          {
+            source: { projectionId: "contract.others" },
+            datasetVersion: others.identity.datasetVersion,
+            projectionRevision: "projection-contract-revision",
+          },
+        ])
+        expect(await storage.ontology.sources.listActive({ projectId: "other-project" })).toEqual(
+          []
+        )
+      })
+    })
+
     test("rolls back exact rows, commits, and outbox writes through one transaction facade", async () => {
       await withStorage(async (storage) => {
         await expect(
@@ -1025,9 +1079,10 @@ async function createReadyEmptyCandidate(
   storage: OntologyStorageContractStorage,
   runId: string,
   materializationId: string,
-  versionId: string
+  versionId: string,
+  projectionId?: string
 ): Promise<ReadyCandidate> {
-  const identity = replacementIdentity(versionId)
+  const identity = replacementIdentity(versionId, projectionId)
   const run = await startTestProjectionRun(storage, {
     id: runId,
     projectId: "contract-project",

package/src/testing/share-grant-storage-contract.ts

@@ -80,6 +80,21 @@ export function runShareGrantStorageContractSuite<TStorage extends ShareGrantSto
       })
     })
 
+    test("reads several grants at once, in the order asked", async () => {
+      await withStorage(async (storage) => {
+        const first = await storage.create(grantInput())
+        const second = await storage.create(
+          grantInput({ id: "shr_2", tokenHash: "b".repeat(64), definitionId: "invoice" })
+        )
+        await storage.create(grantInput({ id: "shr_3", projectId: "other-project" }))
+
+        await expect(
+          storage.getByIds({ projectId, ids: ["shr_2", "missing", "shr_1", "shr_2", "shr_3"] })
+        ).resolves.toEqual([second, first])
+        await expect(storage.getByIds({ projectId, ids: [] })).resolves.toEqual([])
+      })
+    })
+
     test("lists a bounded deterministic page with total and hasMore", async () => {
       await withStorage(async (storage) => {
         await storage.create(grantInput({ id: "shr_a", tokenHash: "b".repeat(64) }))

package/src/workflows/builders.ts

@@ -3,6 +3,7 @@ import { isActionDefinition } from "../actions"
 import { AGENT_REASONING_LEVELS, isAgentToolDefinition } from "../agents"
 import { isModelReasoning } from "../models/language-model"
 import type { SchemaOrRef } from "../ontology"
+import type { SandboxFactory } from "../sandboxes"
 import type { ScheduleDefinition, ScheduleDefinitionForEvent } from "../schedules"
 import { isScheduleDefinition } from "../schedules"
 import { isGroupDefinition } from "../security"
@@ -25,6 +26,7 @@ import type {
   WorkflowTriggerDefinition,
 } from "./types"
 import {
+  assertAgentStepSandbox,
   assertNonEmpty,
   isAgentStepDefinition,
   isInterventionDefinition,
@@ -137,6 +139,7 @@ export function defineAgentStep<const TId extends string>(
   const groupIds = groupIdsFromAgentStepConfig(id, config)
   const toolNames = toolNamesFromAgentStepConfig(id, config)
   const skillNames = skillNamesFromAgentStepConfig(id, config)
+  const sandbox = sandboxFromAgentStepConfig(id, config)
 
   return {
     input(input: RuntimeWorkflowInput): unknown {
@@ -156,6 +159,7 @@ export function defineAgentStep<const TId extends string>(
                 groupIds,
                 toolNames,
                 skillNames,
+                ...(sandbox === undefined ? {} : { sandbox }),
                 input,
                 output,
                 prompt,
@@ -231,6 +235,16 @@ function skillNamesFromAgentStepConfig(
   return Object.freeze(skillNames)
 }
 
+function sandboxFromAgentStepConfig(
+  stepId: string,
+  config: DefineAgentStepConfig
+): SandboxFactory | undefined {
+  if (config.sandbox === undefined) return undefined
+
+  assertAgentStepSandbox(config.sandbox, `Agent step "${stepId}"`)
+  return config.sandbox
+}
+
 function assertUniqueAgentStepValues(
   stepId: string,
   kind: "group" | "tool" | "skill",