@sixb/core 0.1.21 → 0.1.22

package/src/testing/webhook-execution.ts

@@ -3,7 +3,7 @@ import type { StartWebhookRunInput, Storage, WebhookRunRecord } from "../storage
 import type { ExecutionStorage } from "../storage/executions"
 
 /** Create the durable execution required by a Webhook-run storage fixture. */
-export async function createTestWebhookExecution(
+async function createTestWebhookExecution(
   executions: ExecutionStorage,
   input: {
     readonly projectId: string

package/src/testing/webhook-run-storage-contract.ts

@@ -129,23 +129,20 @@ export function runWebhookRunStorageContractSuite<
         await expect(
           storage.webhookRuns.restart({ projectId, id: started.id })
         ).rejects.toMatchObject({ code: "invalid_transition" })
-      })
-    })
 
-    test("does not reopen a terminal client rejection", async () => {
-      await withStorage(async (storage) => {
-        const run = await startTestWebhookRun(storage, runInput("delivery-rejected"))
+        // A terminal client rejection is not reopened either.
+        const rejected = await startTestWebhookRun(storage, runInput("delivery-rejected"))
         await storage.webhookRuns.finish({
           projectId,
-          id: run.id,
+          id: rejected.id,
           status: "failed",
           finishedAt,
           responseStatus: 422,
           error: rejectedFailure,
         })
-        await expect(storage.webhookRuns.restart({ projectId, id: run.id })).rejects.toMatchObject({
-          code: "invalid_transition",
-        })
+        await expect(
+          storage.webhookRuns.restart({ projectId, id: rejected.id })
+        ).rejects.toMatchObject({ code: "invalid_transition" })
       })
     })
 

package/src/users/execution.ts

@@ -0,0 +1,131 @@
+import { assertAuthorized } from "../authorization"
+import { isUserRef, type UserRef } from "../ontology/user-ref"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type { UserRecord, UserStatus } from "../storage"
+
+const DEFAULT_LIMIT = 50
+const MAX_LIMIT = 200
+const MAX_SEARCH_LENGTH = 200
+
+/** A member as the directory shows them. Read from auth storage, never from what a writer stored. */
+export interface UserProfile {
+  readonly id: string
+  readonly email: string
+  readonly displayName?: string
+  readonly avatarUrl?: string
+  readonly status: UserStatus
+}
+
+export interface ListUsersInput {
+  /** Which members to list. Defaults to `"active"`. */
+  readonly status?: UserStatus | "all"
+  /**
+   * Keep members whose display name or email contains this text, ignoring case. At most 200
+   * characters.
+   */
+  readonly search?: string
+  /** From 1 to 200. Defaults to 50. */
+  readonly limit?: number
+  readonly offset?: number
+}
+
+/** One page of members, oldest first. */
+export interface UsersPage {
+  readonly users: readonly UserProfile[]
+  readonly hasMore: boolean
+  /** Every member matching the filters, across all pages. */
+  readonly total: number
+}
+
+/** The project's member directory. Reading it requires `can.view(project.users)`. */
+export interface UsersRuntime {
+  /** The member's profile, suspended or not, or `null` when no member has this id. */
+  get(user: UserRef): Promise<UserProfile | null>
+  list(input?: ListUsersInput): Promise<UsersPage>
+}
+
+export function createUsersRuntime(runtime: SixbRuntimeContext): UsersRuntime {
+  const assertReadable = () => assertAuthorized(runtime, { kind: "users.view" })
+
+  return {
+    get: async (user) => {
+      assertReadable()
+
+      if (!isUserRef(user)) {
+        throw new Error("[Sixb] users.get expects a user reference, such as userRef(id).")
+      }
+
+      const users = runtime.storage.auth?.users
+      if (!users) return null
+
+      const record = await users.getById({ projectId: runtime.projectId, id: user.id })
+      return record ? toUserProfile(record) : null
+    },
+
+    list: async (input = {}) => {
+      assertReadable()
+
+      const limit = listLimit(input.limit)
+      const offset = listOffset(input.offset)
+      const search = listSearch(input.search)
+
+      const users = runtime.storage.auth?.users
+      if (!users) return { users: [], hasMore: false, total: 0 }
+
+      const page = await users.list({
+        projectId: runtime.projectId,
+        ...statusFilter(input.status),
+        ...(search === undefined ? {} : { search }),
+        limit,
+        offset,
+        order: "asc",
+      })
+
+      return {
+        users: page.users.map(toUserProfile),
+        hasMore: page.hasMore,
+        total: page.total,
+      }
+    },
+  }
+}
+
+/** Only the fields the directory shows: no project id, no timestamps. */
+export function toUserProfile(record: UserRecord): UserProfile {
+  return {
+    id: record.id,
+    email: record.email,
+    ...(record.displayName === undefined ? {} : { displayName: record.displayName }),
+    ...(record.avatarUrl === undefined ? {} : { avatarUrl: record.avatarUrl }),
+    status: record.status,
+  }
+}
+
+function statusFilter(status: ListUsersInput["status"] = "active") {
+  if (status === "all") return {}
+  if (status === "active" || status === "suspended") return { statuses: [status] }
+
+  throw new Error(`[Sixb] users.list status must be "active", "suspended", or "all".`)
+}
+
+function listSearch(search: string | undefined): string | undefined {
+  const trimmed = search?.trim()
+  if (!trimmed) return undefined
+  if (trimmed.length <= MAX_SEARCH_LENGTH) return trimmed
+
+  throw new Error(`[Sixb] users.list search must be at most ${MAX_SEARCH_LENGTH} characters.`)
+}
+
+function listLimit(limit: number | undefined): number {
+  if (limit === undefined) return DEFAULT_LIMIT
+  if (Number.isInteger(limit) && limit >= 1 && limit <= MAX_LIMIT) return limit
+
+  throw new Error(`[Sixb] users.list limit must be an integer from 1 to ${MAX_LIMIT}.`)
+}
+
+function listOffset(offset: number | undefined): number {
+  if (offset === undefined) return 0
+  if (Number.isInteger(offset) && offset >= 0) return offset
+
+  throw new Error("[Sixb] users.list offset must be a non-negative integer.")
+}

package/src/users/index.ts

@@ -0,0 +1,2 @@
+export type { ListUsersInput, UserProfile, UsersPage, UsersRuntime } from "./execution"
+export { createUsersRuntime } from "./execution"

package/src/workers/queue-worker.ts

@@ -55,8 +55,6 @@ export abstract class QueueWorker<
   TFailureCodes extends QueueWorkerFailureCodes,
 > extends Worker {
   protected readonly config: Required<QueueWorkerConfig<TJob, TFailureCodes>>
-  /** Pause after a failed claim. Overridable so tests do not wait out real backoffs. */
-  protected readonly claimFailureDelayMs: number = CLAIM_FAILURE_DELAY_MS
   private consecutiveClaimFailures = 0
 
   constructor(config: QueueWorkerConfig<TJob, TFailureCodes>) {
@@ -168,7 +166,7 @@ export abstract class QueueWorker<
           { cause: error }
         )
       }
-      await sleep(this.claimFailureDelayMs, signal).catch(() => {})
+      await sleep(CLAIM_FAILURE_DELAY_MS, signal).catch(() => {})
       return []
     }
   }

package/src/workers/worker.ts

@@ -9,8 +9,6 @@ const STABLE_RUN_MS = 60_000
 
 /** Base worker lifecycle with bounded restart supervision. */
 export abstract class Worker {
-  /** Base restart backoff. Overridable so budget-exhaustion tests do not wait out real backoffs. */
-  protected readonly restartBackoffMs: number = RESTART_BACKOFF_MS
   private controller: AbortController | null = null
   private running: Promise<void> | null = null
 
@@ -66,7 +64,7 @@ export abstract class Worker {
         throw new WorkerUnhealthyError(this.constructor.name, restartCount, { cause: failure })
       }
 
-      const delayMs = Math.min(this.restartBackoffMs * 2 ** restartCount, MAX_RESTART_BACKOFF_MS)
+      const delayMs = Math.min(RESTART_BACKOFF_MS * 2 ** restartCount, MAX_RESTART_BACKOFF_MS)
       restartCount += 1
       await waitForAbort(delayMs, signal)
     }

package/src/workflows/builders.ts

@@ -1,6 +1,7 @@
 import type { ActionDefinition } from "../actions"
 import { isActionDefinition } from "../actions"
 import { AGENT_REASONING_LEVELS, isAgentToolDefinition } from "../agents"
+import { formatLanguageModelTiers, isLanguageModelTier } from "../models/catalog"
 import { isModelReasoning } from "../models/language-model"
 import type { SchemaOrRef } from "../ontology"
 import type { SandboxFactory } from "../sandboxes"
@@ -130,6 +131,11 @@ export function defineAgentStep<const TId extends string>(
   if (typeof config.instructions !== "string" || !config.instructions.trim()) {
     throw new WorkflowDefinitionError(`Agent step "${id}" instructions must not be empty.`)
   }
+  if (typeof config.model === "string" && !isLanguageModelTier(config.model)) {
+    throw new WorkflowDefinitionError(
+      `Agent step "${id}" has unknown model tier "${config.model}". Use ${formatLanguageModelTiers()}, or pass a model.`
+    )
+  }
   if (config.reasoning !== undefined && !isModelReasoning(config.reasoning)) {
     throw new WorkflowDefinitionError(
       `Agent step "${id}" reasoning must be one of: ${AGENT_REASONING_LEVELS.join(", ")}, or a nonnegative budgetTokens object.`

package/src/workflows/request.ts

@@ -9,7 +9,8 @@ import type { ExecutionContext } from "../execution/types"
 import { assertValidFileRefs } from "../ontology/validation"
 import type { SixbRuntimeContext } from "../runtime/types"
 import { dispatchWorkflowRun } from "./run-dispatch"
-import type { WorkflowDefinition, WorkflowRunSource } from "./types"
+import { snapshotWorkflowInput } from "./snapshot"
+import type { WorkflowDefinition, WorkflowIOSnapshot, WorkflowRunSource } from "./types"
 
 export interface WorkflowRunRequestOptions {
   readonly input?: Readonly<Record<string, unknown>>
@@ -45,13 +46,7 @@ export async function requestWorkflowRun(
   workflow: WorkflowDefinition,
   options: WorkflowRunRequestOptions = {}
 ): Promise<WorkflowRunRequestResult> {
-  resolveExecutionScopeAuthorization(runtime.projectId, {
-    execution,
-    authorization: runtime.runtimeAuthorization,
-  })
-  assertAuthorized(runtime, { kind: "workflow.run", workflowId: workflow.id })
-  // Only caller input: automatic runs carry stored data, which may predate the rule.
-  assertValidFileRefs(options.input, `Workflow "${workflow.id}" input`)
+  admitWorkflowRequest(runtime, execution, workflow, options.input)
   return dispatchWorkflowRun({
     errorReporterHost: runtime,
     projectId: runtime.projectId,
@@ -79,3 +74,46 @@ export async function requestWorkflowRun(
     },
   })
 }
+
+/** A workflow start as it would run: authorized, with its input as the run would snapshot it. */
+export interface PreparedWorkflowRequest {
+  readonly workflowId: string
+  readonly input: WorkflowIOSnapshot
+}
+
+/**
+ * Admit a workflow start without starting it: the checks `requestWorkflowRun` applies, and the
+ * input snapshot the run would store. The agent API gateway prepares the starts it holds for
+ * approval.
+ */
+export function prepareWorkflowRequest(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  workflow: WorkflowDefinition,
+  input: Readonly<Record<string, unknown>> = {}
+): PreparedWorkflowRequest {
+  admitWorkflowRequest(runtime, execution, workflow, input)
+  return {
+    workflowId: workflow.id,
+    input: snapshotWorkflowInput({
+      workflow,
+      value: input,
+      valueTypesById: runtime.ontology.getValueTypesById(),
+    }),
+  }
+}
+
+function admitWorkflowRequest(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  workflow: WorkflowDefinition,
+  input: Readonly<Record<string, unknown>> | undefined
+): void {
+  resolveExecutionScopeAuthorization(runtime.projectId, {
+    execution,
+    authorization: runtime.runtimeAuthorization,
+  })
+  assertAuthorized(runtime, { kind: "workflow.run", workflowId: workflow.id })
+  // Only caller input: automatic runs carry stored data, which may predate the rule.
+  assertValidFileRefs(input, `Workflow "${workflow.id}" input`)
+}

package/src/workflows/types.ts

@@ -15,6 +15,7 @@ import type { EventsRuntime } from "../events/execution"
 import type { JsonValue } from "../json"
 import type { Logger } from "../logging"
 import type { LogsRuntime } from "../logging/execution"
+import type { LanguageModelTier } from "../models/catalog"
 import type { ModelsRuntime } from "../models/generation-types"
 import type { LanguageModel } from "../models/language-model"
 import type { ObjectsRuntime } from "../objects/execution"
@@ -27,6 +28,7 @@ import type { ScheduleDefinition, ScheduleDefinitionForEvent } from "../schedule
 import type { SchedulesRuntime } from "../schedules/execution"
 import type { GroupDefinition } from "../security"
 import type { SyncsRuntime } from "../syncs/execution"
+import type { UsersRuntime } from "../users"
 import type { WorkflowsRuntime } from "./execution"
 
 type Simplify<T> = { [K in keyof T]: T[K] } & {}
@@ -75,6 +77,7 @@ export interface WorkflowRuntimeFacade {
   readonly events: EventsRuntime
   readonly logs: LogsRuntime
   readonly schedules: SchedulesRuntime
+  readonly users: UsersRuntime
   readonly connector: ConnectorRuntime
   readonly blobs: BlobsRuntime
 }
@@ -140,7 +143,8 @@ export type AgentStepPrompt<TInput extends Record<string, unknown>> = (
 
 /** Runtime configuration owned directly by a workflow Agent step. */
 export interface DefineAgentStepConfig {
-  readonly model?: LanguageModel
+  /** A model runs as given; a tier runs that tier's model from `models.language`. */
+  readonly model?: LanguageModel | LanguageModelTier
   readonly reasoning?: AgentReasoning
   readonly instructions: string
   readonly groups?: readonly GroupDefinition[]
@@ -166,7 +170,7 @@ export interface AgentStepDefinition<
 > {
   readonly kind: "agentStep"
   readonly id: TId
-  readonly model?: LanguageModel
+  readonly model?: LanguageModel | LanguageModelTier
   readonly reasoning?: AgentReasoning
   readonly instructions: string
   readonly groupIds: readonly string[]

package/src/workflows/validation.ts

@@ -1,6 +1,11 @@
 import { isActionDefinition } from "../actions"
 import type { AgentSkillCatalog, AgentToolCatalog } from "../agents"
 import type { ModelCatalog } from "../models"
+import {
+  assertValidLanguageModel,
+  isLanguageModelTier,
+  selectLanguageModel,
+} from "../models/catalog"
 import { isModelReasoning, modelReasoningSupportIssue } from "../models/language-model"
 import type { SchemaOrRef, ValueType } from "../ontology"
 import { validateSchemaOrRefValue } from "../ontology/refs"
@@ -55,7 +60,9 @@ export function isAgentStepDefinition(value: unknown): value is AgentStepDefinit
     isRecord(value) &&
     value.kind === "agentStep" &&
     typeof value.id === "string" &&
-    (value.model === undefined || isLanguageModel(value.model)) &&
+    (value.model === undefined ||
+      isLanguageModelTier(value.model) ||
+      isLanguageModel(value.model)) &&
     (value.reasoning === undefined || isModelReasoning(value.reasoning)) &&
     typeof value.instructions === "string" &&
     isStringArray(value.groupIds) &&
@@ -190,17 +197,24 @@ function validateWorkflowAgentStepRuntimeReferences(
       `Workflow "${workflowId}" agent step "${step.id}" needs a model. Configure 'models.language' or pass 'model' to defineAgentStep().`
     )
   }
-  if (step.model !== undefined && options.models !== undefined) {
-    const ref = { provider: step.model.providerId, modelId: step.model.modelId }
-    if (options.models.language?.getByRef(ref) == null) {
-      throw new WorkflowDefinitionError(
-        `Workflow "${workflowId}" agent step "${step.id}" uses unknown language model "${ref.provider}/${ref.modelId}". Add it to 'models.language' in createSixb().`
-      )
-    }
+  if (typeof step.model === "string" && options.models?.language === undefined) {
+    throw new WorkflowDefinitionError(
+      `Workflow "${workflowId}" agent step "${step.id}" needs a model for tier "${step.model}". Configure 'models.language' or pass a model to defineAgentStep().`
+    )
+  }
+  // The step's own model runs as given, so it passes the checks a catalog model passes.
+  if (step.model !== undefined && typeof step.model !== "string") {
+    assertValidLanguageModel(
+      step.model,
+      (detail) =>
+        new WorkflowDefinitionError(
+          `Workflow "${workflowId}" agent step "${step.id}" has an invalid language model: ${detail}.`
+        )
+    )
   }
   // Same rule as a catalog default: checked against the capabilities the model declares, so an
   // effort or token budget outside them fails at startup rather than on the step's first run.
-  const model = step.model ?? options.models?.language?.default?.model
+  const model = selectLanguageModel(options.models?.language, step.model)
   if (step.reasoning !== undefined && model !== undefined) {
     const issue = modelReasoningSupportIssue(
       model.definition.capabilities.reasoning,