@sixb/core 0.1.11 → 0.1.13

package/src/shared/params/types.ts

@@ -0,0 +1,85 @@
+import type {
+  DecimalValue,
+  InferSchemaOrRef,
+  ObjectRef,
+  ObjectRefSchema,
+  SchemaOrRef,
+  ValueType,
+} from "../../ontology"
+import type { RegisteredValueTypes } from "../../ontology/registered"
+import type { QuantitativeTypeId } from "../../ontology/units"
+
+type Simplify<T> = { [K in keyof T]: T[K] } & {}
+
+/** One declarative parameter accepted by a Sixb definition. */
+export interface ParamConfig {
+  readonly schema: SchemaOrRef
+  readonly required?: boolean
+  readonly nullable?: boolean
+  readonly description?: string
+  readonly semanticType?: QuantitativeTypeId
+}
+
+/** Parameter shape shared by definitions that accept validated invocation-time input. */
+export type ParamsConfig = Record<string, ParamConfig>
+
+type RequiredParamKeys<TParams extends ParamsConfig> = {
+  [K in keyof TParams]-?: TParams[K]["required"] extends true ? K : never
+}[keyof TParams]
+
+type OptionalParamKeys<TParams extends ParamsConfig> = Exclude<
+  keyof TParams,
+  RequiredParamKeys<TParams>
+>
+
+/**
+ * Validated params normalize `date` and `timestamp` values back to `Date` for typed runtime
+ * consumers. The wider ontology inference keeps storage-facing values permissive.
+ */
+export type ParamPrimitiveSchemaValues = {
+  string: string
+  uuid: string
+  boolean: boolean
+  integer: number
+  double: number
+  decimal: DecimalValue
+  date: Date
+  timestamp: Date
+}
+
+type InferStructuredParamValue<
+  TSchema extends SchemaOrRef,
+  TValueTypes extends readonly ValueType[],
+> = TSchema extends { type: "enum"; values: readonly (infer TValue)[] }
+  ? TValue
+  : TSchema extends ObjectRefSchema<infer TObjectTypeId>
+    ? ObjectRef<TObjectTypeId>
+    : InferSchemaOrRef<TSchema, TValueTypes>
+
+type InferParamSchemaValue<
+  TSchema extends SchemaOrRef,
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
+> = TSchema extends keyof ParamPrimitiveSchemaValues
+  ? ParamPrimitiveSchemaValues[TSchema]
+  : InferStructuredParamValue<TSchema, TValueTypes>
+
+type InferParamValue<
+  TParam extends ParamConfig,
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
+> = TParam["nullable"] extends true
+  ? InferParamSchemaValue<TParam["schema"], TValueTypes> | null
+  : InferParamSchemaValue<TParam["schema"], TValueTypes>
+
+/** Infer the validated runtime input represented by a parameter config. */
+export type InferParams<
+  TParams extends ParamsConfig,
+  TValueTypes extends readonly ValueType[] = RegisteredValueTypes,
+> = string extends keyof TParams
+  ? Record<string, unknown>
+  : Simplify<
+      {
+        [K in RequiredParamKeys<TParams>]: InferParamValue<TParams[K], TValueTypes>
+      } & {
+        [K in OptionalParamKeys<TParams>]?: InferParamValue<TParams[K], TValueTypes>
+      }
+    >

package/src/shared/params/user-refs.ts

@@ -0,0 +1,48 @@
+import type { SchemaOrRef, ValueType } from "../../ontology"
+import { isObjectRefSchema } from "../../ontology/refs"
+import { collectUserRefIds, userReferenceProblem } from "../../ontology/user-ref"
+import type { AuthStorage } from "../../storage/auth/types"
+
+/**
+ * Reject params that reference a user who does not exist or is not active.
+ *
+ * Callers run it only when a new run is created: replaying an existing run keeps the params it was
+ * accepted with, even if a referenced user was suspended since.
+ */
+export async function assertParamUsersActive(input: {
+  readonly auth: AuthStorage | undefined
+  readonly projectId: string
+  readonly schemas: Readonly<Record<string, SchemaOrRef>>
+  readonly values: Readonly<Record<string, unknown>>
+  readonly valueTypesById: ReadonlyMap<string, ValueType>
+  /** Names one param in error messages, for example `Action param 'task.assign.assignee'`. */
+  readonly describe: (paramId: string) => string
+  readonly invalid: (message: string) => Error
+}): Promise<void> {
+  const references: { readonly paramId: string; readonly id: string }[] = []
+  for (const [paramId, schema] of Object.entries(input.schemas)) {
+    if (isObjectRefSchema(schema)) continue
+    const ids = collectUserRefIds(schema, input.values[paramId], input.valueTypesById, new Set())
+    for (const id of ids) references.push({ paramId, id })
+  }
+  if (references.length === 0) return
+
+  const users = input.auth?.users
+  const statuses = new Map(
+    await Promise.all(
+      [...new Set(references.map((reference) => reference.id))].map(
+        async (id) =>
+          [
+            id,
+            users
+              ? ((await users.getById({ projectId: input.projectId, id }))?.status ?? null)
+              : "unverifiable",
+          ] as const
+      )
+    )
+  )
+  for (const { paramId, id } of references) {
+    const problem = userReferenceProblem(input.describe(paramId), id, statuses.get(id) ?? null)
+    if (problem) throw input.invalid(problem)
+  }
+}

package/src/shared/params/validation.ts

@@ -0,0 +1,114 @@
+import { isPlainRecord, type JsonValue } from "../../json"
+import type { SchemaOrRef, ValueType } from "../../ontology"
+import { OntologyValidationError } from "../../ontology/errors"
+import { validateSchemaOrRefValue } from "../../ontology/refs"
+import type { Schema } from "../../ontology/types"
+import { coerceSchemaValueToTyped, normalizeSchemaValue } from "../../ontology/validation"
+import type { ParamsConfig } from "./types"
+
+export interface ParamsOwner {
+  /** Lowercase singular name used in validation errors, for example `action` or `agent`. */
+  readonly kind: string
+  readonly id: string
+  /** Stable value path passed to ontology validation. Defaults to `id`. */
+  readonly path?: string
+}
+
+/** Validate declarative params and normalize them to their durable JSON representation. */
+export function normalizeParams(
+  valueTypesById: ReadonlyMap<string, ValueType>,
+  paramsConfig: ParamsConfig,
+  params: Record<string, unknown>,
+  owner: ParamsOwner
+): Record<string, JsonValue> {
+  if (!isPlainRecord(params)) {
+    throw new OntologyValidationError(`[Sixb] ${capitalize(owner.kind)} params must be an object.`)
+  }
+  const knownParamIds = new Set(Object.keys(paramsConfig))
+  const normalized: [string, JsonValue][] = []
+
+  for (const paramId of Object.keys(params)) {
+    if (!knownParamIds.has(paramId)) {
+      throw new OntologyValidationError(
+        `Unknown param '${paramId}' for ${owner.kind} '${owner.id}'`
+      )
+    }
+  }
+
+  for (const [paramId, paramDef] of Object.entries(paramsConfig)) {
+    const value = Object.hasOwn(params, paramId) ? params[paramId] : undefined
+
+    if (value === undefined) {
+      if (paramDef.required) {
+        throw new OntologyValidationError(
+          `Missing required param '${paramId}' for ${owner.kind} '${owner.id}'`
+        )
+      }
+      continue
+    }
+
+    const path = `${owner.path ?? owner.id}.${paramId}`
+    if (value === null) {
+      if (!paramDef.nullable) {
+        throw new OntologyValidationError(
+          `[Sixb] ${capitalize(owner.kind)} param ${path} cannot be null`
+        )
+      }
+      normalized.push([paramId, null])
+      continue
+    }
+
+    validateSchemaOrRefValue(paramDef.schema, value, path, valueTypesById)
+    normalized.push([
+      paramId,
+      normalizeSchemaOrRefValue(paramDef.schema, value, path, valueTypesById),
+    ])
+  }
+
+  return Object.fromEntries(normalized)
+}
+
+/** Re-hydrate normalized storage values for typed runtime consumers. */
+export function coerceParamsToTyped(
+  paramsConfig: ParamsConfig,
+  params: Record<string, unknown>,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): Record<string, unknown> {
+  const coerced: Record<string, unknown> = { ...params }
+
+  for (const [paramId, paramDef] of Object.entries(paramsConfig)) {
+    if (!Object.hasOwn(params, paramId)) continue
+    const value = params[paramId]
+    if (value === undefined) continue
+
+    const schema = paramDef.schema
+    if (typeof schema === "object" && schema !== null && schema.type === "objectRef") {
+      continue
+    }
+
+    coerced[paramId] = coerceSchemaValueToTyped(schema as Schema, value, valueTypesById)
+  }
+
+  return coerced
+}
+
+function normalizeSchemaOrRefValue(
+  schema: SchemaOrRef,
+  value: unknown,
+  path: string,
+  valueTypesById: ReadonlyMap<string, ValueType>
+): JsonValue {
+  if (typeof schema === "object" && schema !== null && schema.type === "objectRef") {
+    const refValue = value as { objectTypeId: string; primaryId: string }
+    return {
+      objectTypeId: refValue.objectTypeId,
+      primaryId: refValue.primaryId,
+    }
+  }
+
+  return normalizeSchemaValue(schema as Schema, value, path, valueTypesById)
+}
+
+function capitalize(value: string): string {
+  return value.length === 0 ? value : `${value[0]?.toUpperCase()}${value.slice(1)}`
+}

package/src/shares/compiler.ts

@@ -1,7 +1,8 @@
 import type { ActionDefinitionCatalog } from "../actions"
 import type { LinkPathSelection, LinkPathSelectionMode, ObjectRef } from "../ontology"
+import { isPrimitiveSchema, primitiveTraits } from "../ontology/primitives"
 import type { OntologyDefinitionCatalog } from "../ontology/registry"
-import type { ObjectLink, ObjectType } from "../ontology/types"
+import type { ObjectLink, ObjectType, PrimitiveSchema } from "../ontology/types"
 import type {
   ObjectReadLinkDefinitionSelection,
   ObjectReadLinkSelection,
@@ -88,17 +89,6 @@ export function compileShareAccessPlan(input: CompileShareAccessPlanInput): Shar
   return snapshotShareAccessPlan({ grants })
 }
 
-const SHAREABLE_PRIMITIVE_SCHEMAS = new Set([
-  "string",
-  "integer",
-  "double",
-  "decimal",
-  "boolean",
-  "date",
-  "timestamp",
-  "uuid",
-])
-
 /**
  * V1 deliberately excludes references from shared Action params. A delegated caller cannot yet be
  * authorized to resolve arbitrary object or blob references supplied at invocation time.
@@ -112,9 +102,9 @@ function assertShareableActionParams(input: {
   const seenSchemas = new WeakSet<object>()
   const resolvingValueTypes = new Set<string>()
 
-  const reject = (path: string, kind: "objectRef" | "fileRef"): never => {
+  const reject = (path: string, kind: "objectRef" | PrimitiveSchema): never => {
     throw invalid(
-      `Share '${input.shareId}' Action '${input.actionId}' parameter '${path}' uses ${kind}. Shared Action parameters cannot contain objectRef or fileRef in V1.`
+      `Share '${input.shareId}' Action '${input.actionId}' parameter '${path}' uses ${kind}. Shared Action parameters cannot contain objectRef, fileRef, or userRef in V1.`
     )
   }
 
@@ -126,8 +116,8 @@ function assertShareableActionParams(input: {
 
   const walk = (schema: unknown, path: string): void => {
     if (typeof schema === "string") {
-      if (schema === "fileRef") reject(path, "fileRef")
-      if (!SHAREABLE_PRIMITIVE_SCHEMAS.has(schema)) malformed(path)
+      if (!isPrimitiveSchema(schema)) malformed(path)
+      else if (primitiveTraits(schema)?.shareableParam !== true) reject(path, schema)
       return
     }
     if (!isRecord(schema)) throw malformed(path)

package/src/storage/action-runs/types.ts

@@ -27,6 +27,7 @@ export const ACTION_RUN_FAILURE_CODES = [
   "runtime.cancelled",
   "queue.enqueue_failed",
   "action.phase_failed",
+  "action.read_conflict",
 ] as const satisfies readonly [SixbErrorCode, ...SixbErrorCode[]]
 
 export type ActionRunFailureCode = (typeof ACTION_RUN_FAILURE_CODES)[number]

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

@@ -14,7 +14,9 @@ import {
   assertCreateAgentContextCheckpointInput,
   assertCreateSubagentRunInput,
   assertSubagentRunResult,
+  snapshotAgentThreadSandboxParams,
   subagentRunMatchesCreateInput,
+  transitionAgentThreadSandbox,
 } from "./provider"
 import type {
   AgentContextCheckpointRecord,
@@ -26,6 +28,7 @@ import type {
   AgentRunStore,
   AgentStorage,
   AgentThreadRecord,
+  AgentThreadSandboxState,
   AgentThreadStore,
   AppendAgentMessageInput,
   ConfirmAgentRunExecutionOwnershipInput,
@@ -46,6 +49,7 @@ import type {
   ReclaimAgentRunInput,
   StartAgentRunInput,
   SubagentRunRecord,
+  TransitionAgentThreadSandboxInput,
 } from "./types"
 import { AGENT_RUN_FAILURE_CODES } from "./types"
 
@@ -56,7 +60,7 @@ function normalizeFailure(
 }
 
 function key(projectId: string, id: string): string {
-  return `${projectId}:${id}`
+  return JSON.stringify([projectId, id])
 }
 
 function clone<T>(value: T): T {
@@ -118,7 +122,26 @@ export interface InMemoryAgentStorageSnapshot {
 class InMemoryAgentThreadStore implements AgentThreadStore {
   constructor(private readonly state: AgentStoreState) {}
 
+  async transitionSandbox(
+    input: TransitionAgentThreadSandboxInput
+  ): Promise<AgentThreadSandboxState> {
+    const threadKey = key(input.projectId, input.id)
+    const thread = this.state.threads.get(threadKey) ?? null
+    const run =
+      input.action === "recreate"
+        ? null
+        : (this.state.runs.get(key(input.projectId, input.runId)) ?? null)
+    const sandboxState = transitionAgentThreadSandbox(thread, run, input)
+    if (!thread) throw new AgentStorageError("thread_not_found", "[Sixb] Thread not found.")
+    this.state.threads.set(threadKey, { ...thread, sandboxState: clone(sandboxState) })
+    return clone(sandboxState)
+  }
+
   async create(input: CreateAgentThreadInput): Promise<AgentThreadRecord> {
+    const sandboxParams =
+      input.sandboxParams === undefined
+        ? undefined
+        : snapshotAgentThreadSandboxParams(input.sandboxParams)
     const threadKey = key(input.projectId, input.id)
     if (this.state.threads.has(threadKey)) {
       throw new AgentStorageError(
@@ -132,6 +155,7 @@ class InMemoryAgentThreadStore implements AgentThreadStore {
       id: input.id,
       projectId: input.projectId,
       ownerPrincipal: clone(input.ownerPrincipal),
+      ...(sandboxParams === undefined ? {} : { sandboxParams }),
       ...(input.title === undefined ? {} : { title: input.title }),
       status: input.status ?? "active",
       activeRunId: null,

package/src/storage/agents/index.ts

@@ -22,6 +22,8 @@ export type {
   AgentRunStore,
   AgentStorage,
   AgentThreadRecord,
+  AgentThreadSandboxParams,
+  AgentThreadSandboxState,
   AgentThreadStatus,
   AgentThreadStore,
   AppendAgentMessageInput,
@@ -46,6 +48,7 @@ export type {
   SubagentRunRecord,
   SubagentRunResult,
   SubagentRunSpec,
+  TransitionAgentThreadSandboxInput,
 } from "./types"
 export {
   AGENT_RUN_DIAGNOSTIC_CODES,

package/src/storage/agents/provider.ts

@@ -1,6 +1,7 @@
 import { isDeepStrictEqual } from "node:util"
 import { AGENT_REASONING_LEVELS } from "../../agents/types"
 import { isFileRef } from "../../blob-storage"
+import { isJsonObject, isPlainRecord } from "../../json"
 import { isModelReasoning } from "../../models/language-model"
 import type { ExecutionRecord, ExecutionStorage } from "../executions"
 import { findAgentRunExecution } from "../executions/run-link"
@@ -10,13 +11,117 @@ import type {
   AgentMessageRecord,
   AgentRunRecord,
   AgentThreadRecord,
+  AgentThreadSandboxParams,
+  AgentThreadSandboxState,
   ConversationAgentRunSpec,
   CreateAgentContextCheckpointInput,
   CreateSubagentRunInput,
   SubagentRunRecord,
   SubagentRunResult,
+  TransitionAgentThreadSandboxInput,
 } from "./types"
 
+/** Shared state machine. Providers must lock the run, then thread, around this decision/write. */
+export function transitionAgentThreadSandbox(
+  thread: AgentThreadRecord | null,
+  run: AgentRunRecord | null,
+  input: TransitionAgentThreadSandboxInput
+): AgentThreadSandboxState {
+  const fail = (message: string): never => {
+    throw new AgentStorageError("invalid_state", `[Sixb] Sandbox ${message}`)
+  }
+  if (!thread?.sandboxParams) return fail("is not configured on this thread.")
+  if (!/^[a-zA-Z0-9-]{1,80}$/.test(input.name)) return fail("name is invalid.")
+  const state = thread.sandboxState
+  if (input.action === "recreate") {
+    if (thread.activeRunId !== null) return fail("cannot be recreated during an active run.")
+    if (!state || state.name !== input.expectedSandboxName || input.name === state.name)
+      return fail("changed; reload before recreating.")
+    if (!["busy", "blocked", "unavailable"].includes(state.status)) {
+      return fail("does not require recovery.")
+    }
+    return {
+      name: input.name,
+      status: "new",
+      initialized: false,
+      resetAt: new Date().toISOString(),
+    }
+  }
+  if (
+    run?.kind !== "conversation" ||
+    run.threadId !== thread.id ||
+    run.status !== "running" ||
+    thread.activeRunId !== run.id ||
+    run.id !== input.runId ||
+    run.execution?.token !== input.executionToken ||
+    run.execution.queueLeaseExpiresAt.getTime() <= Date.now()
+  ) {
+    throw new AgentStorageError("execution_lost", "[Sixb] Sandbox execution ownership was lost.")
+  }
+  if (input.action === "acquire") {
+    if (state && state.status !== "new" && state.status !== "ready") {
+      return fail("requires recovery; previous operations may still be in flight.")
+    }
+    if (state && state.name !== input.name) return fail("name changed.")
+    if (!/^[a-f0-9]{64}$/.test(input.sourceFingerprint))
+      return fail("source fingerprint is invalid.")
+    if (state?.sourceFingerprint && state.sourceFingerprint !== input.sourceFingerprint) {
+      return fail("source identity changed; the existing checkout was not opened.")
+    }
+    return {
+      name: input.name,
+      status: "busy",
+      initialized: state?.initialized ?? false,
+      ...(state?.resetAt ? { resetAt: state.resetAt } : {}),
+      sourceFingerprint: input.sourceFingerprint,
+      owner: { runId: input.runId, executionToken: input.executionToken },
+    }
+  }
+  if (
+    state?.status !== "busy" ||
+    state.name !== input.name ||
+    state.owner?.runId !== input.runId ||
+    state.owner.executionToken !== input.executionToken
+  ) {
+    return fail("is not owned by this execution.")
+  }
+  if (input.action === "replace") {
+    if (
+      !state.initialized ||
+      input.nextName === state.name ||
+      !/^[a-zA-Z0-9-]{1,80}$/.test(input.nextName)
+    ) {
+      return fail("replacement requires initialized state and a fresh valid name.")
+    }
+    // Only the owning worker may report confirmed loss; retain its fence across replacement.
+    return {
+      ...state,
+      name: input.nextName,
+      initialized: false,
+      resetAt: new Date().toISOString(),
+    }
+  }
+  if (input.status === "ready" && !input.initialized) return fail("initialization is incomplete.")
+  return {
+    name: state.name,
+    status: input.status,
+    initialized: input.initialized,
+    sourceFingerprint: state.sourceFingerprint,
+    ...(state.resetAt ? { resetAt: state.resetAt } : {}),
+  }
+}
+
+/** Snapshot application parameters independently of worker-owned sandbox state. */
+export function snapshotAgentThreadSandboxParams(value: unknown): AgentThreadSandboxParams {
+  if (!isPlainRecord(value) || !isJsonObject(value)) {
+    throw new AgentStorageError(
+      "invalid_input",
+      "[Sixb] Thread sandbox must contain only JSON params."
+    )
+  }
+  return structuredClone(value)
+}
+
 /** Validate the provider-neutral model selection captured for a conversational turn. */
 export function assertConversationAgentRunSpec(
   spec: ConversationAgentRunSpec,

package/src/storage/agents/types.ts

@@ -10,12 +10,63 @@ import type { LanguageModelRef } from "../../models"
 
 export type AgentThreadStatus = "active" | "archived"
 
+/** Immutable, non-secret application input. Never store resolved env or credentials here. */
+export type AgentThreadSandboxParams = Readonly<Record<string, JsonValue>>
+
+/** Worker-owned state, independent from the immutable application binding. */
+export interface AgentThreadSandboxState {
+  /** Exact name passed to the provider. Replacements always receive a fresh name. */
+  readonly name: string
+  readonly status: "new" | "busy" | "ready" | "blocked" | "unavailable"
+  readonly sourceFingerprint?: string
+  readonly initialized: boolean
+  /** Durable context boundary: local files from before this reset are no longer available. */
+  readonly resetAt?: string
+  /** Never expires automatically: a delayed provider operation must not reach a successor. */
+  readonly owner?: { readonly runId: string; readonly executionToken: string }
+}
+
+export type TransitionAgentThreadSandboxInput = {
+  readonly projectId: string
+  readonly id: string
+} & (
+  | {
+      readonly action: "acquire"
+      readonly runId: string
+      readonly executionToken: string
+      readonly name: string
+      readonly sourceFingerprint: string
+    }
+  | {
+      readonly action: "replace"
+      readonly runId: string
+      readonly executionToken: string
+      readonly name: string
+      readonly nextName: string
+    }
+  | {
+      readonly action: "settle"
+      readonly runId: string
+      readonly executionToken: string
+      readonly name: string
+      readonly status: "ready" | "blocked" | "unavailable"
+      readonly initialized: boolean
+    }
+  | {
+      readonly action: "recreate"
+      readonly expectedSandboxName: string
+      readonly name: string
+    }
+)
+
 export interface AgentThreadRecord {
   readonly id: string
   readonly projectId: string
   /** Who owns/opened the thread. Reuses the canonical auth principal (gains `agent` later for free). */
   readonly ownerPrincipal: Principal
   readonly title?: string
+  readonly sandboxParams?: AgentThreadSandboxParams
+  readonly sandboxState?: AgentThreadSandboxState
   readonly status: AgentThreadStatus
   /** Single-flight anchor: the id of the one run currently allowed to write, or `null` when idle. */
   readonly activeRunId: string | null
@@ -30,6 +81,7 @@ export interface CreateAgentThreadInput {
   readonly projectId: string
   readonly ownerPrincipal: Principal
   readonly title?: string
+  readonly sandboxParams?: AgentThreadSandboxParams
   readonly status?: AgentThreadStatus
   readonly createdAt?: Date
   readonly updatedAt?: Date
@@ -416,6 +468,8 @@ export interface CreateAgentContextCheckpointInput {
 // ── Store ───────────────────────────────────────────────────────────────────────────────────────
 
 export interface AgentThreadStore {
+  /** Atomic run-fenced transition, or explicit idle-thread recreation. */
+  transitionSandbox(input: TransitionAgentThreadSandboxInput): Promise<AgentThreadSandboxState>
   create(input: CreateAgentThreadInput): Promise<AgentThreadRecord>
   getById(params: { projectId: string; id: string }): Promise<AgentThreadRecord | null>
   list(input: ListAgentThreadsInput): Promise<ListAgentThreadsResult>