@sixb/core 0.1.8 → 0.1.10

package/src/queues/in-memory.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto"
 import type { SixbErrorCode } from "../errors/types"
 import { QueueError } from "./errors"
+import { IndexedHeap } from "./indexed-heap"
 import type {
   ActionQueueJobFailureCode,
   ActionRunRequestedQueueJob,
@@ -29,6 +30,9 @@ interface QueueRecord<TQueueJob extends QueueJob = QueueJob> {
   readonly sequence: number
   readonly queueId: string
   job: TQueueJob
+  availableAtMs: number
+  readonly createdAtMs: number
+  leaseExpiryMs: number | null
   // A leased job stays "queued" until a worker completes or fails it.
   state: QueueRecordState
   failure: QueueJobFailure | null
@@ -63,25 +67,15 @@ function clearLease(record: QueueRecord): void {
   record.leaseId = null
   record.claimedAt = null
   record.leaseExpiresAt = null
+  record.leaseExpiryMs = null
 }
 
 // Best-effort ordering is part of the contract; this keeps the in-memory provider deterministic.
 function compareQueueRecords(left: QueueRecord, right: QueueRecord): number {
-  const availableDifference =
-    parseTimestamp(left.job.availableAt, "job.availableAt") -
-    parseTimestamp(right.job.availableAt, "job.availableAt")
-
-  if (availableDifference !== 0) {
-    return availableDifference
-  }
-
-  const createdDifference =
-    parseTimestamp(left.job.createdAt, "job.createdAt") -
-    parseTimestamp(right.job.createdAt, "job.createdAt")
-
-  if (createdDifference !== 0) {
-    return createdDifference
-  }
+  const availableDifference = left.availableAtMs - right.availableAtMs
+  if (availableDifference !== 0) return availableDifference
+  const createdDifference = left.createdAtMs - right.createdAtMs
+  if (createdDifference !== 0) return createdDifference
 
   return left.sequence - right.sequence
 }
@@ -107,11 +101,18 @@ function createQueueJob<TQueueJob extends QueueJob>(
 }
 
 function leaseExpiresAtMs(record: QueueRecord): number | null {
-  if (!record.leaseId || !record.leaseExpiresAt) {
-    return null
-  }
+  return record.leaseExpiryMs
+}
 
-  return parseTimestamp(record.leaseExpiresAt, "leaseExpiresAt")
+function eligibleAt(record: QueueRecord): number {
+  return Math.max(record.availableAtMs, record.leaseExpiryMs ?? -Infinity)
+}
+
+interface QueueLane {
+  // Terminal records remain here for caller-id deduplication, never in the delivery indexes.
+  readonly records: Map<string, QueueRecord>
+  readonly ready: IndexedHeap<QueueRecord>
+  readonly waiting: IndexedHeap<QueueRecord>
 }
 
 function toClaimedQueueJob<TQueueJob extends QueueJob>(
@@ -130,27 +131,26 @@ function toClaimedQueueJob<TQueueJob extends QueueJob>(
 }
 
 class InMemoryQueueStore {
-  private readonly recordsByProject = new Map<string, QueueRecord[]>()
+  private readonly projects = new Map<string, Map<string, QueueLane>>()
   private nextSequence = 1
 
   add<TQueueJob extends QueueJob>(projectId: string, queueId: string, job: TQueueJob): void {
-    const records = this.getOrCreateRecords(projectId)
-    records.push({
-      sequence: this.nextSequence,
+    const lane = this.lane(projectId, queueId)
+    const record: QueueRecord = {
+      sequence: this.nextSequence++,
       queueId,
       job,
+      availableAtMs: parseTimestamp(job.availableAt, "job.availableAt"),
+      createdAtMs: parseTimestamp(job.createdAt, "job.createdAt"),
+      leaseExpiryMs: null,
       state: "queued",
       failure: null,
       leaseId: null,
       claimedAt: null,
       leaseExpiresAt: null,
-    })
-    this.nextSequence += 1
-  }
-
-  list<TQueueJob extends QueueJob>(projectId: string, queueId: string): QueueRecord<TQueueJob>[] {
-    const records = this.recordsByProject.get(projectId) ?? []
-    return records.filter((record) => record.queueId === queueId) as QueueRecord<TQueueJob>[]
+    }
+    lane.records.set(job.id, record)
+    this.schedule(projectId, record, Date.now())
   }
 
   find<TQueueJob extends QueueJob>(
@@ -158,20 +158,67 @@ class InMemoryQueueStore {
     queueId: string,
     jobId: string
   ): QueueRecord<TQueueJob> | null {
-    return (
-      this.list<TQueueJob>(projectId, queueId).find((record) => record.job.id === jobId) ?? null
-    )
+    return (this.projects.get(projectId)?.get(queueId)?.records.get(jobId) ??
+      null) as QueueRecord<TQueueJob> | null
   }
 
-  private getOrCreateRecords(projectId: string): QueueRecord[] {
-    const existing = this.recordsByProject.get(projectId)
-    if (existing) {
-      return existing
+  schedule(projectId: string, record: QueueRecord, now: number): void {
+    const lane = this.lane(projectId, record.queueId)
+    if (record.state !== "queued") {
+      lane.ready.delete(record)
+      lane.waiting.delete(record)
+    } else if (eligibleAt(record) <= now) {
+      lane.waiting.delete(record)
+      lane.ready.set(record)
+    } else {
+      lane.ready.delete(record)
+      lane.waiting.set(record)
+    }
+  }
+
+  takeReady<TQueueJob extends QueueJob>(
+    projectId: string,
+    queueId: string,
+    now: number,
+    limit: number
+  ): QueueRecord<TQueueJob>[] {
+    const lane = this.projects.get(projectId)?.get(queueId)
+    if (!lane) return []
+    // Wake delayed jobs and expired leases, then order all ready jobs by the original contract.
+    // A lease expiry controls eligibility, not the priority of a redelivered job.
+    while (lane.waiting.peek() && eligibleAt(lane.waiting.peek()!) <= now) {
+      lane.ready.set(lane.waiting.pop()!)
     }
+    const selected: QueueRecord[] = []
+    while (selected.length < limit) {
+      const record = lane.ready.peek()
+      if (!record || record.availableAtMs > now) break
+      lane.ready.pop()
+      // A backwards wall-clock adjustment can make a previously expired lease live again.
+      if (eligibleAt(record) > now) lane.waiting.set(record)
+      else selected.push(record)
+    }
+    return selected as QueueRecord<TQueueJob>[]
+  }
 
-    const records: QueueRecord[] = []
-    this.recordsByProject.set(projectId, records)
-    return records
+  private lane(projectId: string, queueId: string): QueueLane {
+    let queues = this.projects.get(projectId)
+    if (!queues) {
+      queues = new Map()
+      this.projects.set(projectId, queues)
+    }
+    let lane = queues.get(queueId)
+    if (!lane) {
+      lane = {
+        records: new Map(),
+        ready: new IndexedHeap(compareQueueRecords),
+        waiting: new IndexedHeap(
+          (left, right) => eligibleAt(left) - eligibleAt(right) || left.sequence - right.sequence
+        ),
+      }
+      queues.set(queueId, lane)
+    }
+    return lane
   }
 }
 
@@ -219,8 +266,8 @@ class InMemoryQueue<TQueueJob extends QueueJob, TFailureCode extends SixbErrorCo
     assertNonEmpty(params.projectId, "projectId")
     assertNonEmpty(params.workerId, "workerId")
 
-    const limit = params.limit ?? 1
-    if (limit <= 0) {
+    const limit = Math.trunc(params.limit ?? 1)
+    if (!(limit > 0)) {
       return []
     }
 
@@ -228,24 +275,11 @@ class InMemoryQueue<TQueueJob extends QueueJob, TFailureCode extends SixbErrorCo
     assertPositiveNumber(leaseMs, "leaseMs")
 
     const now = Date.now()
-    const claimable = this.store
-      .list<TQueueJob>(params.projectId, this.queueId)
-      .filter((record) => {
-        if (record.state !== "queued") {
-          return false
-        }
-
-        if (parseTimestamp(record.job.availableAt, "job.availableAt") > now) {
-          return false
-        }
-
-        const expiresAt = leaseExpiresAtMs(record)
-        return expiresAt === null || expiresAt <= now
-      })
-      .sort(compareQueueRecords)
-      .slice(0, limit)
-
     const claimedAt = new Date(now).toISOString()
+    // Validate before removing candidates, and cache the same millisecond precision we return.
+    const leaseExpiry = new Date(now + leaseMs)
+    const leaseExpiresAt = leaseExpiry.toISOString()
+    const claimable = this.store.takeReady<TQueueJob>(params.projectId, this.queueId, now, limit)
 
     return claimable.map((record) => {
       // Attempts count claims so redelivery after lease expiry or retry is visible to workers.
@@ -255,7 +289,9 @@ class InMemoryQueue<TQueueJob extends QueueJob, TFailureCode extends SixbErrorCo
       }
       record.leaseId = randomUUID()
       record.claimedAt = claimedAt
-      record.leaseExpiresAt = new Date(now + leaseMs).toISOString()
+      record.leaseExpiresAt = leaseExpiresAt
+      record.leaseExpiryMs = leaseExpiry.getTime()
+      this.store.schedule(params.projectId, record, now)
 
       return toClaimedQueueJob(record)
     })
@@ -265,6 +301,7 @@ class InMemoryQueue<TQueueJob extends QueueJob, TFailureCode extends SixbErrorCo
     const record = this.requireActiveLease(params)
     record.state = "completed"
     clearLease(record)
+    this.store.schedule(params.projectId, record, Date.now())
   }
 
   async retry(params: {
@@ -275,13 +312,15 @@ class InMemoryQueue<TQueueJob extends QueueJob, TFailureCode extends SixbErrorCo
   }): Promise<void> {
     const record = this.requireActiveLease(params)
     const availableAt = params.availableAt ?? new Date().toISOString()
-    parseTimestamp(availableAt, "availableAt")
+    const availableAtMs = parseTimestamp(availableAt, "availableAt")
 
+    record.availableAtMs = availableAtMs
     record.job = {
       ...record.job,
       availableAt,
     }
     clearLease(record)
+    this.store.schedule(params.projectId, record, Date.now())
   }
 
   async fail(params: {
@@ -294,6 +333,7 @@ class InMemoryQueue<TQueueJob extends QueueJob, TFailureCode extends SixbErrorCo
     record.state = "failed"
     record.failure = structuredClone(params.failure)
     clearLease(record)
+    this.store.schedule(params.projectId, record, Date.now())
   }
 
   async renewLease(params: {
@@ -319,7 +359,10 @@ class InMemoryQueue<TQueueJob extends QueueJob, TFailureCode extends SixbErrorCo
       return null
     }
 
-    record.leaseExpiresAt = new Date(now + params.leaseMs).toISOString()
+    const leaseExpiry = new Date(now + params.leaseMs)
+    record.leaseExpiresAt = leaseExpiry.toISOString()
+    record.leaseExpiryMs = leaseExpiry.getTime()
+    this.store.schedule(params.projectId, record, now)
     return toClaimedQueueJob(record)
   }
 

package/src/queues/index.ts

@@ -7,14 +7,16 @@ export type {
   ModelRoute,
 } from "../models"
 export type { ModelProviderIds } from "../models/events"
+export type {
+  AiModelCallAccountingPayload,
+  AiModelCallRecordPayload,
+} from "../models/execution/types"
 export type { ProviderScope } from "../provider-scope"
 export { QueueError } from "./errors"
 export { InMemoryQueues } from "./in-memory"
 export type {
   ActionQueueJobFailureCode,
   ActionRunRequestedQueueJob,
-  AgentAiUsageAccountingPayload,
-  AgentAiUsageRecordPayload,
   AgentAiUsageRecordRequestedQueueJob,
   AgentQueueJob,
   AgentQueueJobFailureCode,

package/src/queues/indexed-heap.ts

@@ -0,0 +1,74 @@
+/** Internal mutable priority index. Updating or removing an entry never leaves stale copies. */
+export class IndexedHeap<T> {
+  private readonly items: T[] = []
+  private readonly positions = new Map<T, number>()
+
+  constructor(private readonly compare: (left: T, right: T) => number) {}
+
+  peek(): T | undefined {
+    return this.items[0]
+  }
+
+  pop(): T | undefined {
+    const first = this.peek()
+    if (first !== undefined) this.delete(first)
+    return first
+  }
+
+  set(item: T): void {
+    const index = this.positions.get(item)
+    if (index === undefined) {
+      this.positions.set(item, this.items.length)
+      this.items.push(item)
+      this.up(this.items.length - 1)
+    } else {
+      this.down(this.up(index))
+    }
+  }
+
+  delete(item: T): void {
+    const index = this.positions.get(item)
+    if (index === undefined) return
+    const last = this.items.pop()!
+    this.positions.delete(item)
+    if (index === this.items.length) return
+    this.items[index] = last
+    this.positions.set(last, index)
+    this.down(this.up(index))
+  }
+
+  private up(start: number): number {
+    let index = start
+    while (index > 0) {
+      const parent = Math.floor((index - 1) / 2)
+      if (this.compare(this.items[parent]!, this.items[index]!) <= 0) break
+      this.swap(parent, index)
+      index = parent
+    }
+    return index
+  }
+
+  private down(start: number): void {
+    let index = start
+    while (index * 2 + 1 < this.items.length) {
+      const left = index * 2 + 1
+      const right = left + 1
+      const child =
+        right < this.items.length && this.compare(this.items[right]!, this.items[left]!) < 0
+          ? right
+          : left
+      if (this.compare(this.items[index]!, this.items[child]!) <= 0) break
+      this.swap(index, child)
+      index = child
+    }
+  }
+
+  private swap(left: number, right: number): void {
+    const a = this.items[left]!
+    const b = this.items[right]!
+    this.items[left] = b
+    this.items[right] = a
+    this.positions.set(a, right)
+    this.positions.set(b, left)
+  }
+}

package/src/queues/types.ts

@@ -1,11 +1,13 @@
 import type { SixbErrorCode, SixbFailure } from "../errors/types"
 import type { JsonValue } from "../json"
-import type { ModelCallCost, ModelCostEstimate, ModelRoute } from "../models"
+import type {
+  AiModelCallAccountingPayload,
+  AiModelCallRecordPayload,
+} from "../models/execution/types"
 import type { ProjectionRunFailureCode } from "../projections/types"
 import type { ProviderScope } from "../provider-scope"
 import type { ActionRunFailureCode } from "../storage/action-runs/types"
 import type { AgentRunFailureCode } from "../storage/agents/types"
-import type { RecordAiModelCallInput } from "../storage/ai-usage"
 import type { PipelineRunFailureCode } from "../storage/pipeline-runs/types"
 import type { SyncRunFailureCode } from "../storage/sync-runs/types"
 import type { WorkflowRunFailureCode } from "../storage/workflow-runs/types"
@@ -210,33 +212,12 @@ export interface AgentWorkflowNodeRequestedQueueJob
     }
   > {}
 
-/** JSON-safe representation of one model-call ledger append awaiting durable recovery. */
-export type AgentAiUsageRecordPayload = Omit<
-  RecordAiModelCallInput,
-  "projectId" | "usage" | "occurredAt" | "recordedAt"
-> & {
-  readonly usage: {
-    readonly [Field in keyof RecordAiModelCallInput["usage"]]: RecordAiModelCallInput["usage"][Field]
-  }
-  readonly occurredAt: string
-}
-
-export interface AgentAiUsageAccountingPayload {
-  readonly estimate?: ModelCostEstimate
-  readonly cost: ModelCallCost
-  readonly route?: ModelRoute
-  readonly ratedAt: string
-  /** Absent on pre-limit jobs; those model calls did not create a reservation. */
-  readonly reconcileLimitReservation?: boolean
-}
-
 export interface AgentAiUsageRecordRequestedQueueJob
   extends QueueJob<
     "agent.ai-usage.record.requested",
     {
-      readonly record: AgentAiUsageRecordPayload
-      /** Absent only on legacy jobs that predate atomic valuation recovery. */
-      readonly accounting?: AgentAiUsageAccountingPayload
+      readonly record: AiModelCallRecordPayload
+      readonly accounting: AiModelCallAccountingPayload
     }
   > {}
 

package/src/runtime/create.ts

@@ -10,7 +10,8 @@ import type { ConnectorConnectionOptions, ConnectorDefinition } from "../connect
 import type { DatasetDefinition } from "../datasets"
 import type { SixbErrorHandler } from "../error-reporting/types"
 import type { LakeStorage } from "../lake-storage"
-import type { LoggerProvider, ObservabilityOptions } from "../logging"
+import type { LoggerProvider } from "../logging"
+import type { ObservabilityOptions } from "../logging/service"
 import type { OntologyMaintenanceOptions } from "../maintenance"
 import type { ModelCatalogInput } from "../models"
 import type { PipelineDefinition } from "../pipelines/types"

package/src/runtime/host.ts

@@ -19,7 +19,6 @@ import type { BlobStorage } from "../blob-storage"
 import type { Broker } from "../broker"
 import { registerConnectorConnectionCallbackProcess } from "../connectors/connections/capability"
 import { createConnectorCredentialProtectorFromKey } from "../connectors/credentials"
-import { createConnectorCodedError } from "../connectors/errors"
 import { ConnectorService } from "../connectors/service"
 import {
   type ConnectorConnectionOptions,
@@ -43,7 +42,8 @@ import {
 import { createAuthorizedObjectReader } from "../execution/authorized-object-reader"
 import type { ExecutionScope } from "../execution/types"
 import type { LakeStorage } from "../lake-storage"
-import { type LoggerProvider, LoggingService, type ObservabilityOptions } from "../logging"
+import type { LoggerProvider } from "../logging"
+import { LoggingService, type ObservabilityOptions } from "../logging/service"
 import {
   OntologyMaintenance,
   type OntologyMaintenanceHandle,
@@ -184,7 +184,6 @@ export class SixbHost<
     })
     validateAuthStrategySecurityReferences(this.auth.getStrategy(), definitions.security)
     const connectors = definitions.connectors.list()
-    assertConnectorConnectionSurfaces(connectors)
     const hasOAuthConnectors = connectors.some(isOAuthConnectorDefinition)
     const credentialProtector =
       hasOAuthConnectors && options.connectorConnections?.encryptionKey !== undefined
@@ -385,15 +384,3 @@ function assertWebhookRunStorage(
     }
   }
 }
-
-function assertConnectorConnectionSurfaces(connectors: readonly ConnectorDefinition[]): void {
-  for (const connector of connectors) {
-    if (!isOAuthConnectorDefinition(connector)) continue
-    if (connector.adapter.webhooks !== undefined) {
-      throw createConnectorCodedError(
-        "connector.configuration_invalid",
-        `OAuth connector '${connector.id}' cannot register webhooks until connection routing is defined.`
-      )
-    }
-  }
-}

package/src/runtime/ontology-mutations.ts

@@ -3,13 +3,16 @@ import type {
   OntologyEditCommit,
   ProjectionCommitResult,
   ProjectionRunFinishInput,
+  ProjectionSourceRef,
   ProjectionSourceReplacement,
   TelemetryAppend,
   TelemetryCommitResult,
 } from "../materialization/model"
 import type { BoundOntologyMaterializer } from "../materializer"
+import type { OntologySourceRecord } from "../storage/ontology"
 
 export interface OntologyMutationRuntime {
+  getProjectionSource?(source: ProjectionSourceRef): Promise<OntologySourceRecord | null>
   commitEdits(input: OntologyEditCommit): Promise<EditCommitResult>
   replaceProjection(input: ProjectionSourceReplacement): Promise<ProjectionCommitResult>
   finishProjection(input: ProjectionRunFinishInput): Promise<void>
@@ -55,6 +58,7 @@ export function createOntologyMutationRuntime(input: {
   readonly notifyCommittedFacts: () => void
 }): OntologyMutationRuntime {
   const runtime: OntologyMutationRuntime = {
+    getProjectionSource: (source) => input.materializer.projections.getActive(source),
     commitEdits: (command) =>
       commitAndNotify(() => input.materializer.edits.commit(command), input.notifyCommittedFacts),
     replaceProjection: (command) =>

package/src/runtime/sixb.ts

@@ -16,6 +16,8 @@ import { assertAuthorizedObjectReaderBinding } from "../execution/authorized-obj
 import type { LakeStorage } from "../lake-storage/types"
 import { createLogsRuntime, type LogsRuntime } from "../logging/execution"
 import type { LoggingService } from "../logging/service"
+import { createModelsRuntime } from "../models/execution"
+import type { ModelsRuntime } from "../models/generation-types"
 import { createObjectsRuntime, type ObjectsRuntime } from "../objects/execution"
 import { createPipelinesRuntime, type PipelinesRuntime } from "../pipelines/execution"
 import { createProjectionsRuntime, type ProjectionsRuntime } from "../projections/execution"
@@ -42,6 +44,7 @@ export interface Sixb<
   readonly projections: ProjectionsRuntime
   readonly rules: RulesRuntime
   readonly agent: AgentRuntime
+  readonly models: ModelsRuntime
   readonly aiUsage: AiUsageRuntime
   readonly events: EventsRuntime
   readonly logs: LogsRuntime
@@ -118,6 +121,7 @@ function createExecutionFacades<TOntologySources extends readonly OntologySource
     projections: createProjectionsRuntime(runtime, dependencies.definitions.projections),
     rules: createRulesRuntime(runtime, dependencies.definitions.rules),
     agent: createAgentRuntime(runtime, execution, dependencies.definitions.models),
+    models: createModelsRuntime(runtime, execution, dependencies.definitions.models),
     aiUsage: createAiUsageRuntime(runtime, dependencies.definitions.security),
     events: createEventsRuntime(runtime),
     logs: createLogsRuntime(runtime, dependencies.logging),

package/src/sandboxes/errors.ts

@@ -6,6 +6,11 @@ export class SandboxError extends Error {
   readonly name: string = "SandboxError"
 }
 
+/** The named sandbox or its saved filesystem no longer exists. Explicit recreation is required. */
+export class SandboxStateUnavailableError extends SandboxError {
+  override readonly name = "SandboxStateUnavailableError"
+}
+
 /** runCommand / stop / destroy called after the sandbox is stopped or destroyed. */
 export class SandboxNotRunningError extends SandboxError {
   override readonly name = "SandboxNotRunningError"

package/src/sandboxes/index.ts

@@ -2,6 +2,7 @@ export {
   SandboxError,
   SandboxIsolationUnavailableError,
   SandboxNotRunningError,
+  SandboxStateUnavailableError,
   SandboxTimeoutError,
 } from "./errors"
 export type { ExecOptions } from "./exec"
@@ -9,11 +10,13 @@ export { exec } from "./exec"
 export type {
   CommandResult,
   CreateSandboxOptions,
+  ResumeSandboxOptions,
   RunCommandOptions,
   Sandbox,
   SandboxFactory,
   SandboxFileRecord,
   SandboxNetworkPolicy,
   SandboxNetworkTarget,
+  SandboxSessionOptions,
   SandboxStatus,
 } from "./sandbox"

package/src/sandboxes/sandbox.ts

@@ -72,17 +72,25 @@ export interface SandboxNetworkTarget {
   readonly origin: string
 }
 
-/**
- * Options accepted by every SandboxFactory.create. Provider-specific factories
- * may extend this type with their own options.
- */
-export interface CreateSandboxOptions {
+/** Current execution defaults, supplied on both creation and resume, never recovered from files. */
+export interface SandboxSessionOptions {
   readonly workingDirectory?: string
   readonly env?: Readonly<Record<string, string>>
   readonly timeout?: number
   readonly network?: SandboxNetworkPolicy
 }
 
+/** Options accepted by every SandboxFactory.create. */
+export interface CreateSandboxOptions extends SandboxSessionOptions {
+  /** Create new named state; reject an existing name or unsupported persistence before provisioning. */
+  readonly persistence?: { readonly name: string }
+}
+
+/** Resume changes execution defaults, not the identity or creation configuration of saved state. */
+export interface ResumeSandboxOptions extends SandboxSessionOptions {
+  readonly persistence?: never
+}
+
 export interface Sandbox {
   readonly id: string
   /** Provider id matching the package suffix, for example "local". */
@@ -109,16 +117,36 @@ export interface Sandbox {
    */
   writeFiles(files: readonly SandboxFileRecord[]): Promise<void>
 
-  /** Mark the sandbox stopped; subsequent runCommand calls reject. Idempotent. */
+  /** Stop this session; subsequent operations reject. Idempotent.
+   * Persistent handles confirm preservation and share the outcome, including failure,
+   * across repeated/concurrent calls.
+   */
   stop(): Promise<void>
-  /** Stop and reclaim any provider-side resources. Idempotent. */
+  /** Stop and reclaim resources, permanently deleting named state when persistent. Idempotent.
+   * Requires exclusive lifecycle ownership, including after stop(); never routine persistent teardown.
+   */
   destroy(): Promise<void>
 }
 
 /**
  * What createSixb({ sandboxes }) accepts. Provider-specific factories hold
  * their defaults set once and expose create(options) for each run.
+ * Persistent files are retention-bound, not a durable file store or a distributed lock.
+ * Callers own namespacing and must serialize the entire create/resume/use/stop/destroy lifecycle.
+ * Credentials and current authority must be supplied again, never inferred from saved files.
  */
 export interface SandboxFactory {
+  /** Create an ephemeral sandbox unless persistence is requested. Existing names must fail,
+   * never attach or overwrite. Unsupported providers must reject persistence before provisioning.
+   * A persistent handle targets one session; operations must not automatically resume another VM.
+   */
   create(options?: CreateSandboxOptions): Promise<Sandbox>
+  /**
+   * Present only when named persistent creation and resume are supported.
+   * Resume an existing, stopped sandbox. Missing/expired state throws SandboxStateUnavailableError;
+   * it must never create an empty replacement. An already running sandbox must be rejected.
+   * Returns a handle bound to the resumed session, with no automatic resume on use.
+   * Runtime options must be provided again; no creation settings or persistence option are accepted.
+   */
+  resume?(name: string, options?: ResumeSandboxOptions): Promise<Sandbox>
 }

package/src/storage/agents/in-memory.ts

@@ -1,6 +1,5 @@
 import { AGENT_MESSAGE_CONTENT_VERSION } from "../../agents/message"
 import { principalsEqual } from "../../auth"
-import { normalizeRequesterGroupIds } from "../../auth/attribution"
 import { parseSixbFailure } from "../../errors/internal"
 import type { SixbFailure } from "../../errors/types"
 import type { ExecutionStorage } from "../executions"
@@ -234,7 +233,6 @@ class InMemoryAgentRunStore implements AgentRunStore {
       threadId: input.threadId,
       triggerMessageId: input.triggerMessageId,
       spec: clone(input.spec),
-      requesterGroupIds: normalizeRequesterGroupIds(input.requesterGroupIds),
       status: "queued",
       attempt: 0,
       createdAt,
@@ -330,7 +328,6 @@ class InMemoryAgentRunStore implements AgentRunStore {
       parentRunId: input.parentRunId,
       spawnKey: input.spawnKey,
       spec: clone(input.spec),
-      requesterGroupIds: clone(parent.requesterGroupIds),
       status: "queued",
       attempt: 0,
       createdAt: new Date(input.createdAt ?? new Date()),

package/src/storage/agents/types.ts

@@ -148,8 +148,6 @@ interface AgentRunRecordBase {
   readonly id: string
   readonly projectId: string
   readonly executionId: string
-  /** Durable group memberships snapshotted when the run was admitted. */
-  readonly requesterGroupIds: readonly string[]
   readonly status: AgentRunStatus
   readonly modelId?: string
   /** Why the run ended (our own SDK-independent enum). */
@@ -215,7 +213,6 @@ export interface CreateAgentRunInput {
   readonly threadId: string
   readonly triggerMessageId: string
   readonly spec: ConversationAgentRunSpec
-  readonly requesterGroupIds: readonly string[]
   readonly createdAt?: Date
 }