@sixb/core 0.1.11 → 0.1.13

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

package/src/sandboxes/configuration.ts

@@ -0,0 +1,268 @@
+import { isPlainRecord } from "../json"
+import type { OntologyRegistry } from "../ontology/registry"
+import { assertValidSchema } from "../ontology/validation/definition"
+import type { Sixb } from "../runtime/sixb"
+import type { InferParams, ParamsConfig } from "../shared/params/types"
+import { coerceParamsToTyped, normalizeParams } from "../shared/params/validation"
+import type { SandboxSourceAuth } from "./auth"
+import { SandboxError } from "./errors"
+import type { SandboxNetworkPolicy } from "./sandbox"
+
+/** Static recipes accept an empty parameter record, not arbitrary undeclared keys. */
+export type InferSandboxParams<TParams extends ParamsConfig> = keyof TParams extends never
+  ? Record<string, never>
+  : InferParams<TParams>
+
+/** Initial project contents, independent from the provider's runtime image or saved state. */
+export interface SandboxSource {
+  readonly type: "git"
+  readonly url: string
+  readonly revision?: string
+  readonly access?: "read" | "write"
+}
+
+/** Host-side recipe. Environment values are guest-readable, never a Git credential channel. */
+export interface SandboxEnvironment {
+  readonly source?: SandboxSource
+  readonly setup?: readonly string[]
+  readonly env?: Readonly<Record<string, string>>
+  readonly network?: SandboxNetworkPolicy
+}
+
+export interface SandboxResolveContext<TParams = Record<string, unknown>> {
+  readonly params: TParams
+  /** Bound to the current execution; a stored binding is not authorization. */
+  readonly sixb: Sixb
+}
+
+// The recipe both declares and consumes this schema: keep it invariant instead of asking
+// TypeScript to compare the recursive ontology inference through callback variance.
+// Provider option interfaces must preserve this annotation when extending the config.
+export interface SandboxConfig<in out TParams extends ParamsConfig = ParamsConfig>
+  extends SandboxEnvironment {
+  readonly auth?: SandboxSourceAuth
+  readonly params?: TParams
+  readonly resolve?: (
+    context: SandboxResolveContext<InferParams<NoInfer<TParams>>>
+  ) => SandboxEnvironment | Promise<SandboxEnvironment>
+}
+
+/** Registered project recipe; only thread params cross the durable boundary. */
+export interface SandboxDefinition {
+  readonly auth?: SandboxSourceAuth
+  readonly params: ParamsConfig
+  readonly resolve: (context: SandboxResolveContext) => Promise<SandboxEnvironment>
+}
+
+export function createSandboxDefinition<TParams extends ParamsConfig>(
+  config: SandboxConfig<TParams>,
+  ontology: OntologyRegistry
+): SandboxDefinition {
+  const raw: unknown = config
+  if (
+    !isPlainRecord(raw) ||
+    (config.params !== undefined && !isPlainRecord(raw.params)) ||
+    (config.resolve !== undefined && typeof config.resolve !== "function")
+  ) {
+    throw new SandboxError(
+      "[Sixb] Sandbox configuration requires a params object and a callable resolver when provided."
+    )
+  }
+  for (const key of Object.keys(config)) {
+    if (!["params", "resolve", "source", "setup", "env", "network", "auth"].includes(key)) {
+      throw new SandboxError("[Sixb] Unknown sandbox configuration field.")
+    }
+  }
+  if (config.auth !== undefined && typeof config.auth?.authorize !== "function") {
+    throw new SandboxError("[Sixb] sandboxes.auth requires an authorize function.")
+  }
+  if (config.params !== undefined && config.resolve === undefined) {
+    throw new SandboxError("[Sixb] Sandbox params require a resolve function.")
+  }
+  if (config.resolve !== undefined && (config.source !== undefined || config.setup !== undefined)) {
+    throw new SandboxError("[Sixb] Use either static source/setup or resolve, not both.")
+  }
+  const invalid = (path: string) =>
+    new SandboxError(`[Sixb] ${path} must be a valid parameter declaration; use param(schema).`)
+  for (const [id, value] of Object.entries(config.params ?? {})) {
+    const path = `sandboxes.params.${id}`
+    if (!id.trim() || !isPlainRecord(value)) throw invalid(path)
+    for (const key of Object.keys(value)) {
+      if (!["schema", "required", "nullable", "description", "semanticType"].includes(key)) {
+        throw invalid(path)
+      }
+    }
+    if (
+      (value.required !== undefined && typeof value.required !== "boolean") ||
+      (value.nullable !== undefined && typeof value.nullable !== "boolean") ||
+      (value.description !== undefined && typeof value.description !== "string") ||
+      (value.semanticType !== undefined && typeof value.semanticType !== "string")
+    )
+      throw invalid(path)
+    const schema: unknown = value.schema
+    if (isPlainRecord(schema) && schema.type === "objectRef") {
+      if (
+        typeof schema.objectTypeId !== "string" ||
+        !ontology.getObjectTypesById().has(schema.objectTypeId)
+      ) {
+        throw invalid(path)
+      }
+    } else {
+      assertValidSchema(schema, `${path}.schema`, invalid)
+    }
+  }
+  const params = structuredClone(config.params ?? {}) as ParamsConfig
+  const environment = captureEnvironment({
+    ...(config.source === undefined ? {} : { source: config.source }),
+    ...(config.setup === undefined ? {} : { setup: config.setup }),
+    ...(config.env === undefined ? {} : { env: config.env }),
+    ...(config.network === undefined ? {} : { network: config.network }),
+  })
+  // Capture the function too: later mutation of application config must not change this host.
+  // Erase inference only after capturing its schema; every invocation validates and coerces below.
+  const resolve = config.resolve as SandboxConfig["resolve"]
+  const authorize = config.auth?.authorize.bind(config.auth)
+  deepFreeze(params)
+  return Object.freeze({
+    params,
+    ...(authorize ? { auth: Object.freeze({ authorize }) } : {}),
+    resolve: async ({ params: input, sixb }: SandboxResolveContext) => {
+      const binding = normalizeParams(ontology.getValueTypesById(), params, input, {
+        kind: "sandbox",
+        id: "sandboxes",
+        path: "sandbox",
+      })
+      const typed = coerceParamsToTyped(params, binding, ontology.getValueTypesById())
+      if (!resolve) return structuredClone(environment)
+      const resolved = captureEnvironment(await resolve({ params: typed, sixb }))
+      return {
+        ...structuredClone(environment),
+        ...resolved,
+        env: { ...environment.env, ...resolved.env },
+      }
+    },
+  })
+}
+
+/** Capture declarative data only; never retain caller-owned objects or include values in errors. */
+export function captureEnvironment(value: unknown): SandboxEnvironment {
+  if (
+    !isPlainRecord(value) ||
+    Object.keys(value).some((key) => !["source", "setup", "env", "network"].includes(key))
+  ) {
+    return fail("environment")
+  }
+  if (value.source !== undefined) validateSource(value.source)
+  if (value.setup !== undefined) validateSetup(value.setup)
+  if (value.env !== undefined) validateEnv(value.env)
+  if (value.network !== undefined) validateNetwork(value.network)
+  // Every field and discriminant has been checked above; return only an isolated snapshot.
+  return structuredClone(value) as SandboxEnvironment
+}
+
+function fail(field: string): never {
+  throw new SandboxError(`[Sixb] Invalid sandbox ${field}.`)
+}
+
+function validateSource(source: unknown): void {
+  if (
+    !isPlainRecord(source) ||
+    source.type !== "git" ||
+    typeof source.url !== "string" ||
+    Object.keys(source).some((key) => !["type", "url", "revision", "access"].includes(key))
+  ) {
+    fail("source")
+  }
+  const url = parseUrl(source.url, "source URL")
+  if (url.protocol !== "https:" || url.username || url.password || url.search || url.hash) {
+    fail("source URL: expected credential-free HTTPS")
+  }
+  if (
+    source.revision !== undefined &&
+    (typeof source.revision !== "string" ||
+      !source.revision.trim() ||
+      source.revision.startsWith("-") ||
+      /[\x00-\x1f]/.test(source.revision))
+  ) {
+    fail("source revision")
+  }
+  if (source.access !== undefined && source.access !== "read" && source.access !== "write") {
+    fail("source access")
+  }
+}
+
+function validateSetup(setup: unknown): void {
+  if (
+    !Array.isArray(setup) ||
+    setup.some(
+      (command) => typeof command !== "string" || !command.trim() || command.includes("\0")
+    )
+  ) {
+    fail("setup")
+  }
+}
+
+function validateEnv(env: unknown): void {
+  if (
+    !isPlainRecord(env) ||
+    Object.entries(env).some(
+      ([key, entry]) =>
+        !key || /[=\0]/.test(key) || typeof entry !== "string" || entry.includes("\0")
+    )
+  ) {
+    fail("env")
+  }
+}
+
+function validateNetwork(network: unknown): void {
+  if (!isPlainRecord(network)) fail("network")
+  if (network.mode === "restricted") {
+    if (
+      Object.keys(network).some((key) => key !== "mode" && key !== "allow") ||
+      !Array.isArray(network.allow)
+    ) {
+      fail("network")
+    }
+    for (const target of network.allow) validateNetworkTarget(target)
+    return
+  }
+  if (
+    (network.mode !== "none" && network.mode !== "all") ||
+    Object.keys(network).some((key) => key !== "mode")
+  ) {
+    fail("network")
+  }
+}
+
+function validateNetworkTarget(target: unknown): void {
+  if (
+    !isPlainRecord(target) ||
+    typeof target.name !== "string" ||
+    !target.name.trim() ||
+    typeof target.origin !== "string" ||
+    Object.keys(target).some((key) => key !== "name" && key !== "origin")
+  ) {
+    fail("network target")
+  }
+  const url = parseUrl(target.origin, "network origin")
+  if (!["http:", "https:"].includes(url.protocol) || url.origin !== target.origin) {
+    fail("network origin")
+  }
+}
+
+function parseUrl(value: string, field: string): URL {
+  try {
+    return new URL(value)
+  } catch {
+    return fail(field)
+  }
+}
+
+function deepFreeze(value: object, seen = new Set<object>()): void {
+  if (seen.has(value)) return
+  seen.add(value)
+  for (const child of Object.values(value)) {
+    if (child !== null && typeof child === "object") deepFreeze(child, seen)
+  }
+  Object.freeze(value)
+}

package/src/sandboxes/environment.ts

@@ -0,0 +1,107 @@
+import { posix } from "node:path"
+import type { ParamsConfig } from "../shared/params/types"
+import type { SandboxConfig } from "./configuration"
+import { captureEnvironment, type SandboxEnvironment } from "./configuration"
+import { SandboxError } from "./errors"
+import type { CreateSandboxOptions, Sandbox } from "./sandbox"
+
+/** Select and validate before provisioning. Only the execution runtime may resolve a recipe. */
+export function sandboxCreationEnvironment<TParams extends ParamsConfig>(
+  configuration: SandboxConfig<TParams>,
+  options: CreateSandboxOptions
+): Pick<SandboxEnvironment, "source" | "setup"> {
+  if (options.environment === undefined && configuration.resolve !== undefined) {
+    throw new SandboxError(
+      "[Sixb] Dynamic sandbox configuration requires an execution-resolved environment."
+    )
+  }
+  const environment = captureEnvironment(
+    options.environment !== undefined
+      ? options.environment
+      : {
+          ...(configuration.source === undefined ? {} : { source: configuration.source }),
+          ...(configuration.setup === undefined ? {} : { setup: configuration.setup }),
+        }
+  )
+  if (environment.env !== undefined || environment.network !== undefined) {
+    throw new SandboxError(
+      "[Sixb] Pass env and network as sandbox session options, not environment."
+    )
+  }
+  if (environment.source) {
+    if (
+      (configuration.auth !== undefined || environment.source.access === "write") &&
+      !options.requestCredentials?.length
+    ) {
+      throw new SandboxError(
+        "[Sixb] Sandbox source authentication requires execution-prepared request credentials."
+      )
+    }
+    const network = options.network ?? configuration.network ?? { mode: "none" }
+    const origin = new URL(environment.source.url).origin
+    if (
+      network.mode === "none" ||
+      (network.mode === "restricted" && !network.allow.some((target) => target.origin === origin))
+    ) {
+      throw new SandboxError("[Sixb] Sandbox network policy denies the source origin.")
+    }
+  }
+  options.signal?.throwIfAborted()
+  return environment
+}
+
+/** Select the same project directory on creation and resume without touching saved files. */
+export function sandboxProjectDirectory(session: Sandbox, hasSource: boolean): Sandbox {
+  if (!hasSource) return session
+  const workingDirectory = posix.join(session.workingDirectory, "repository")
+  return {
+    id: session.id,
+    provider: session.provider,
+    get status() {
+      return session.status
+    },
+    workingDirectory,
+    ...(session.setRequestCredentials
+      ? { setRequestCredentials: session.setRequestCredentials.bind(session) }
+      : {}),
+    runCommand: (command, args, options) =>
+      session.runCommand(command, args, { ...options, cwd: options?.cwd ?? workingDirectory }),
+    writeFiles: (files) =>
+      session.writeFiles(
+        files.map((file) => ({
+          ...file,
+          path: posix.isAbsolute(file.path) ? file.path : posix.join(workingDirectory, file.path),
+        }))
+      ),
+    stop: () => session.stop(),
+    destroy: () => session.destroy(),
+  }
+}
+
+/** Provider-side initialization, after the session network/credentials have been applied.
+ * Call only on fresh creation. The caller owns cleanup if any command fails.
+ */
+export async function initializeSandboxEnvironment(
+  session: Sandbox,
+  environment: Pick<SandboxEnvironment, "source" | "setup">,
+  signal?: AbortSignal
+): Promise<Sandbox> {
+  environment = captureEnvironment(environment)
+  const run = async (sandbox: Sandbox, command: string, args: readonly string[]) => {
+    signal?.throwIfAborted()
+    const result = await sandbox.runCommand(command, args, { timeout: 120_000, signal })
+    if (result.exitCode !== 0 || result.timedOut) {
+      throw new SandboxError("[Sixb] Sandbox environment initialization failed.")
+    }
+  }
+  signal?.throwIfAborted()
+  const sandbox = sandboxProjectDirectory(session, environment.source !== undefined)
+  if (environment.source) {
+    await run(session, "git", ["clone", "--", environment.source.url, "repository"])
+    if (environment.source.revision) {
+      await run(sandbox, "git", ["checkout", environment.source.revision, "--"])
+    }
+  }
+  for (const command of environment.setup ?? []) await run(sandbox, "bash", ["-lc", command])
+  return sandbox
+}

package/src/sandboxes/errors.ts

@@ -6,7 +6,7 @@ export class SandboxError extends Error {
   readonly name: string = "SandboxError"
 }
 
-/** The named sandbox or its saved filesystem no longer exists. Explicit recreation is required. */
+/** Confirmed missing/expired state. Never use for transport, authorization or session setup errors. */
 export class SandboxStateUnavailableError extends SandboxError {
   override readonly name = "SandboxStateUnavailableError"
 }

package/src/sandboxes/index.ts

@@ -1,3 +1,17 @@
+export type { InferParams, ParamsConfig } from "../shared/params/types"
+export type { SandboxSourceAuth, SandboxSourceCredentials } from "./auth"
+export { sandboxConfig } from "./config"
+export type {
+  SandboxConfig,
+  SandboxEnvironment,
+  SandboxResolveContext,
+  SandboxSource,
+} from "./configuration"
+export {
+  initializeSandboxEnvironment,
+  sandboxCreationEnvironment,
+  sandboxProjectDirectory,
+} from "./environment"
 export {
   SandboxError,
   SandboxIsolationUnavailableError,
@@ -17,6 +31,7 @@ export type {
   SandboxFileRecord,
   SandboxNetworkPolicy,
   SandboxNetworkTarget,
+  SandboxRequestCredential,
   SandboxSessionOptions,
   SandboxStatus,
 } from "./sandbox"

package/src/sandboxes/sandbox.ts

@@ -6,6 +6,9 @@
  * SandboxFactory.
  */
 
+import type { ParamsConfig } from "../shared/params/types"
+import type { SandboxConfig, SandboxEnvironment } from "./configuration"
+
 export type SandboxStatus = "running" | "stopped" | "failed"
 
 /**
@@ -13,7 +16,10 @@ export type SandboxStatus = "running" | "stopped" | "failed"
  * default set at factory.create(...).
  */
 export interface RunCommandOptions {
-  /** Overrides the sandbox-level workingDirectory for this call. */
+  /**
+   * Working directory for this call. Defaults to the sandbox's workingDirectory;
+   * relative paths resolve against it, while absolute paths override it.
+   */
   readonly cwd?: string
   /** Merged on top of sandbox-level env. Per-call wins on collision. */
   readonly env?: Readonly<Record<string, string>>
@@ -72,8 +78,20 @@ export interface SandboxNetworkTarget {
   readonly origin: string
 }
 
+/** Host-only credentials injected outside the guest into one exact HTTPS request target.
+ * This selects authenticated requests, not the sandbox's general egress allowlist.
+ */
+export interface SandboxRequestCredential {
+  readonly origin: string
+  readonly path: string
+  readonly method: "GET" | "POST"
+  readonly headers: { readonly Authorization: string }
+}
+
 /** Current execution defaults, supplied on both creation and resume, never recovered from files. */
 export interface SandboxSessionOptions {
+  /** Apply outside the guest before source/setup or resumed commands. Reject if unsupported. */
+  readonly requestCredentials?: readonly SandboxRequestCredential[]
   readonly workingDirectory?: string
   readonly env?: Readonly<Record<string, string>>
   readonly timeout?: number
@@ -82,6 +100,10 @@ export interface SandboxSessionOptions {
 
 /** Options accepted by every SandboxFactory.create. */
 export interface CreateSandboxOptions extends SandboxSessionOptions {
+  /** Cancel initialization; a provider request already in flight may still finish. */
+  readonly signal?: AbortSignal
+  /** Replaces static source/setup, including {} to skip both. Required for dynamic recipes. */
+  readonly environment?: Pick<SandboxEnvironment, "source" | "setup">
   /** Create new named state; reject an existing name or unsupported persistence before provisioning. */
   readonly persistence?: { readonly name: string }
 }
@@ -98,6 +120,14 @@ export interface Sandbox {
   readonly status: SandboxStatus
   readonly workingDirectory: string
 
+  /** Optional secure injection capability. Replaces all credentials on this session only.
+   * An empty list removes injection. Secrets must never enter guest files, env or snapshots.
+   * Must not resume a stopped session or change defaults inherited by future sessions.
+   */
+  readonly setRequestCredentials?: (
+    credentials: readonly SandboxRequestCredential[]
+  ) => Promise<void>
+
   runCommand(
     command: string,
     args?: readonly string[],
@@ -135,18 +165,26 @@ export interface Sandbox {
  * 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 {
+export interface SandboxFactory<in out TParams extends ParamsConfig = ParamsConfig> {
+  /** Supports initial and renewable host-only credentials on named persistent sessions. */
+  readonly supportsRequestCredentials?: boolean
+  /** Common host-side environment recipe. Never a discovered Agent definition. */
+  readonly configuration?: SandboxConfig<TParams>
   /** Create an ephemeral sandbox unless persistence is requested. Existing names must fail,
-   * never attach or overwrite. Unsupported providers must reject persistence before provisioning.
+   * never attach or overwrite. Apply the selected source/setup once, after session settings.
+   * Dynamic resolution and source authorization belong to the caller, never the provider.
+   * 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.
+   * it must never create an empty replacement. Transport/auth/setup errors must not be classified
+   * as missing state. 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.
+   * Never clone or replay setup on resume.
    */
   resume?(name: string, options?: ResumeSandboxOptions): Promise<Sandbox>
 }

package/src/shared/params/builders.ts

@@ -0,0 +1,50 @@
+import type { SchemaOrRef } from "../../ontology"
+import type { QuantitativeTypeId } from "../../ontology/units"
+import type { ParamConfig } from "./types"
+
+export interface ParamOptions {
+  readonly description?: string
+  readonly semanticType?: QuantitativeTypeId
+  readonly nullable?: boolean
+}
+
+type FieldFromOptions<TOptions, TKey extends string, TFallback> =
+  TOptions extends Record<TKey, infer TValue>
+    ? { [K in TKey]: TValue }
+    : { [K in TKey]?: TFallback }
+
+type ParamResult<
+  TSchema extends SchemaOrRef,
+  TRequired extends boolean,
+  TOptions extends ParamOptions | undefined,
+> = {
+  schema: TSchema
+  required: TRequired
+} & FieldFromOptions<TOptions, "description", string> &
+  FieldFromOptions<TOptions, "semanticType", QuantitativeTypeId> &
+  FieldFromOptions<TOptions, "nullable", boolean>
+
+/** Declare one required parameter. */
+export function param<
+  const TSchema extends SchemaOrRef,
+  const TOptions extends ParamOptions | undefined = undefined,
+>(schema: TSchema, options?: TOptions): ParamResult<TSchema, true, TOptions> {
+  const result: ParamConfig & { required: true } = {
+    schema,
+    required: true,
+    ...(options?.description !== undefined ? { description: options.description } : {}),
+    ...(options?.semanticType !== undefined ? { semanticType: options.semanticType } : {}),
+    ...(options?.nullable !== undefined ? { nullable: options.nullable } : {}),
+  }
+  return result as ParamResult<TSchema, true, TOptions>
+}
+
+/** Derive an optional parameter without changing its schema or metadata. */
+export function optional<const TParam extends ParamConfig>(
+  paramConfig: TParam
+): Omit<TParam, "required"> & { readonly required: false } {
+  return {
+    ...paramConfig,
+    required: false,
+  }
+}