@sixb/core 0.1.6 → 0.1.7

package/src/workflows/builders.ts

@@ -1,14 +1,16 @@
 import type { ActionDefinition } from "../actions"
 import { isActionDefinition } from "../actions"
-import type { AgentDefinition } from "../agents"
-import { isAgentDefinition } from "../agents"
+import { AGENT_REASONING_LEVELS, isAgentToolDefinition } from "../agents"
+import { isModelReasoning } from "../models/language-model"
 import type { SchemaOrRef } from "../ontology"
 import type { ScheduleDefinition, ScheduleDefinitionForEvent } from "../schedules"
 import { isScheduleDefinition } from "../schedules"
+import { isGroupDefinition } from "../security"
 import { WorkflowDefinitionError } from "./errors"
 import type {
   AgentStepBuilder,
   AgentStepDefinition,
+  DefineAgentStepConfig,
   InterventionBuilder,
   InterventionDefaultsRuntimeHandler,
   InterventionDefinition,
@@ -115,14 +117,25 @@ export function defineWorkflowStep<const TId extends string>(id: TId): StepBuild
   } as unknown as StepBuilder<TId>
 }
 
-export function defineAgentStep<const TId extends string, const TAgent extends AgentDefinition>(
+export function defineAgentStep<const TId extends string>(
   id: TId,
-  agent: TAgent
-): AgentStepBuilder<TId, TAgent> {
+  config: DefineAgentStepConfig
+): AgentStepBuilder<TId> {
   assertNonEmpty(id, "Agent step", "id")
-  if (!isAgentDefinition(agent)) {
-    throw new WorkflowDefinitionError(`Agent step "${id}" references an invalid agent.`)
+  if (!isRecord(config)) {
+    throw new WorkflowDefinitionError(`Agent step "${id}" config must be an object.`)
   }
+  if (typeof config.instructions !== "string" || !config.instructions.trim()) {
+    throw new WorkflowDefinitionError(`Agent step "${id}" instructions must not be empty.`)
+  }
+  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.`
+    )
+  }
+  const { model, reasoning, instructions } = config
+  const groupIds = groupIdsFromAgentStepConfig(id, config)
+  const toolNames = toolNamesFromAgentStepConfig(id, config)
 
   return {
     input(input: RuntimeWorkflowInput): unknown {
@@ -133,13 +146,82 @@ export function defineAgentStep<const TId extends string, const TAgent extends A
               if (typeof prompt !== "function") {
                 throw new WorkflowDefinitionError(`Agent step "${id}" prompt must be a function.`)
               }
-              return { kind: "agentStep", id, agent, input, output, prompt }
+              return {
+                kind: "agentStep",
+                id,
+                ...(model === undefined ? {} : { model }),
+                ...(reasoning === undefined ? {} : { reasoning }),
+                instructions,
+                groupIds,
+                toolNames,
+                input,
+                output,
+                prompt,
+              }
             },
           }
         },
       }
     },
-  } as unknown as AgentStepBuilder<TId, TAgent>
+  } as unknown as AgentStepBuilder<TId>
+}
+
+function groupIdsFromAgentStepConfig(
+  stepId: string,
+  config: DefineAgentStepConfig
+): readonly string[] {
+  if (config.groups !== undefined && !Array.isArray(config.groups)) {
+    throw new WorkflowDefinitionError(
+      `Agent step "${stepId}" groups must be an array of group definitions.`
+    )
+  }
+  const groupIds = Array.from(config.groups ?? [], (group) => {
+    if (!isGroupDefinition(group)) {
+      throw new WorkflowDefinitionError(
+        `Agent step "${stepId}" groups must contain only group definitions.`
+      )
+    }
+    return group.id
+  })
+  assertUniqueAgentStepValues(stepId, "group", groupIds)
+  return Object.freeze(groupIds)
+}
+
+function toolNamesFromAgentStepConfig(
+  stepId: string,
+  config: DefineAgentStepConfig
+): readonly string[] {
+  if (config.tools !== undefined && !Array.isArray(config.tools)) {
+    throw new WorkflowDefinitionError(
+      `Agent step "${stepId}" tools must be an array of agent tool definitions.`
+    )
+  }
+  const toolNames = Array.from(config.tools ?? [], (tool) => {
+    if (!isAgentToolDefinition(tool)) {
+      throw new WorkflowDefinitionError(
+        `Agent step "${stepId}" tools must contain only agent tool definitions.`
+      )
+    }
+    return tool.name
+  })
+  assertUniqueAgentStepValues(stepId, "tool", toolNames)
+  return Object.freeze(toolNames)
+}
+
+function assertUniqueAgentStepValues(
+  stepId: string,
+  kind: "group" | "tool",
+  values: readonly string[]
+): void {
+  const seen = new Set<string>()
+  for (const value of values) {
+    if (seen.has(value)) {
+      throw new WorkflowDefinitionError(
+        `Agent step "${stepId}" ${kind}s contains duplicate ${kind} '${value}'.`
+      )
+    }
+    seen.add(value)
+  }
 }
 
 export function defineIntervention<const TId extends string>(
@@ -469,3 +551,7 @@ function isRuntimeWorkflowMapper(value: unknown): value is RuntimeWorkflowMapper
 function isRuntimeWorkflowScheduleMapper(value: unknown): value is RuntimeWorkflowScheduleMapper {
   return typeof value === "function"
 }
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}

package/src/workflows/execution.ts

@@ -61,7 +61,8 @@ export type ListWorkflowRunNodesInput = Omit<
 >
 
 /** Execution-facing Agent node view derived from its run row and model-call ledger. */
-export interface WorkflowAgentNodeRunView extends Omit<WorkflowAgentNodeRunRecord, "execution"> {
+export interface WorkflowAgentNodeRunView
+  extends Omit<WorkflowAgentNodeRunRecord, "execution" | "actorId"> {
   readonly usage?: AiModelCallUsage
   /** Preferred valuation; omitted when there are no calls or cost storage is unavailable. */
   readonly cost?: AiCostSummary
@@ -274,7 +275,6 @@ function toWorkflowAgentNodeRunView(
     projectId: execution.projectId,
     nodeRunId: execution.nodeRunId,
     executionId: execution.executionId,
-    agentId: execution.agentId,
     status: execution.status,
     prompt: execution.prompt,
     modelId: execution.modelId,

package/src/workflows/failure.ts

@@ -15,7 +15,7 @@ export interface WorkflowNodeFailureIdentity extends WorkflowNodeFailureIdentity
         readonly actionId: string
         readonly actionRunId?: string
       }
-    | { readonly type: "agent"; readonly agentId: string }
+    | { readonly type: "agent"; readonly agentStepId: string }
     | { readonly type: "intervention"; readonly interventionId: string }
 }
 
@@ -56,7 +56,7 @@ function workflowNodeFailureDetails(identity: WorkflowNodeFailureIdentity) {
         ...(identity.child.actionRunId ? { actionRunId: identity.child.actionRunId } : {}),
       }
     case "agent":
-      return { ...base, agentId: identity.child.agentId }
+      return { ...base, agentStepId: identity.child.agentStepId }
     case "intervention":
       return { ...base, interventionId: identity.child.interventionId }
   }

package/src/workflows/index.ts

@@ -1,3 +1,4 @@
+export { workflowAgentStepActorId } from "./agent-step-identity"
 export {
   defineAgentStep,
   defineIntervention,
@@ -39,6 +40,7 @@ export type {
   AgentStepPrompt,
   AgentStepPromptBuilder,
   AgentStepPromptContext,
+  DefineAgentStepConfig,
   DerivedWorkflowNodeKey,
   InferAgentStepInput,
   InferAgentStepOutput,
@@ -90,6 +92,7 @@ export {
   isInterventionDefinition,
   isStepDefinition,
   isWorkflowDefinition,
+  validateWorkflowAgentStepGroupReferences,
   validateWorkflowAgentStepInput,
   validateWorkflowAgentStepOutput,
   validateWorkflowDefinition,

package/src/workflows/types.ts

@@ -5,8 +5,8 @@ import type {
   ObjectActionDefinition,
 } from "../actions"
 import type { ActionsRuntime } from "../actions/execution"
-import type { AgentsRuntime } from "../agents/execution"
-import type { AgentDefinition } from "../agents/types"
+import type { AgentRuntime } from "../agents/execution"
+import type { AgentReasoningLevel, AgentToolDefinition } from "../agents/types"
 import type { Principal } from "../auth"
 import type { BlobsRuntime } from "../blob-storage/execution"
 import type { ConnectorRuntime } from "../connectors/execution"
@@ -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 { LanguageModel } from "../models/language-model"
 import type { ObjectsRuntime } from "../objects/execution"
 import type { InferSchemaOrRef, ObjectRef, OntologySource, SchemaOrRef } from "../ontology"
 import type { PipelinesRuntime } from "../pipelines/execution"
@@ -22,6 +23,7 @@ import type { ProjectionsRuntime } from "../projections/execution"
 import type { RulesRuntime } from "../rules/execution"
 import type { ScheduleDefinition, ScheduleDefinitionForEvent } from "../schedules"
 import type { SchedulesRuntime } from "../schedules/execution"
+import type { GroupDefinition } from "../security"
 import type { SyncsRuntime } from "../syncs/execution"
 import type { WorkflowsRuntime } from "./execution"
 
@@ -60,7 +62,7 @@ export interface StepRunContext<TInput extends Record<string, unknown>> {
 export interface WorkflowRuntimeFacade {
   readonly objects: ObjectsRuntime<readonly OntologySource[]>
   readonly actions: ActionsRuntime
-  readonly agents: AgentsRuntime
+  readonly agent: AgentRuntime
   readonly datasets: DatasetsRuntime
   readonly workflows: WorkflowsRuntime
   readonly syncs: SyncsRuntime
@@ -133,9 +135,18 @@ export type AgentStepPrompt<TInput extends Record<string, unknown>> = (
   ctx: AgentStepPromptContext<TInput>
 ) => string | Promise<string>
 
+/** Runtime configuration owned directly by a workflow Agent step. */
+export interface DefineAgentStepConfig {
+  readonly model?: LanguageModel
+  readonly reasoning?: AgentReasoningLevel
+  readonly instructions: string
+  readonly groups?: readonly GroupDefinition[]
+  /** Project tools this workflow task may call. Defaults to none. */
+  readonly tools?: readonly AgentToolDefinition[]
+}
+
 export interface AgentStepDefinition<
   TId extends string = string,
-  TAgent extends AgentDefinition = AgentDefinition,
   TInput extends Record<string, unknown> = Record<string, unknown>,
   TOutput extends Record<string, unknown> = Record<string, unknown>,
   TInputValue extends Record<string, unknown> = Record<string, unknown>,
@@ -143,7 +154,11 @@ export interface AgentStepDefinition<
 > {
   readonly kind: "agentStep"
   readonly id: TId
-  readonly agent: TAgent
+  readonly model?: LanguageModel
+  readonly reasoning?: AgentReasoningLevel
+  readonly instructions: string
+  readonly groupIds: readonly string[]
+  readonly toolNames: readonly string[]
   readonly input: TInput
   readonly output: TOutput
   readonly prompt: AgentStepPrompt<Record<string, unknown>>
@@ -153,7 +168,6 @@ export interface AgentStepDefinition<
 
 export interface AgentStepPromptBuilder<
   TId extends string,
-  TAgent extends AgentDefinition,
   TInput extends Record<string, unknown>,
   TOutput extends Record<string, unknown>,
 > {
@@ -161,7 +175,6 @@ export interface AgentStepPromptBuilder<
     prompt: AgentStepPrompt<InferSchemaOrRefRecord<TInput>>
   ): AgentStepDefinition<
     TId,
-    TAgent,
     TInput,
     TOutput,
     InferSchemaOrRefRecord<TInput>,
@@ -171,18 +184,17 @@ export interface AgentStepPromptBuilder<
 
 export interface AgentStepOutputBuilder<
   TId extends string,
-  TAgent extends AgentDefinition,
   TInput extends Record<string, unknown>,
 > {
   output<const TOutput extends Record<string, unknown>>(
     output: TOutput & SchemaOrRefInput<TOutput>
-  ): AgentStepPromptBuilder<TId, TAgent, TInput, TOutput>
+  ): AgentStepPromptBuilder<TId, TInput, TOutput>
 }
 
-export interface AgentStepBuilder<TId extends string, TAgent extends AgentDefinition> {
+export interface AgentStepBuilder<TId extends string> {
   input<const TInput extends Record<string, unknown>>(
     input: TInput & SchemaOrRefInput<TInput>
-  ): AgentStepOutputBuilder<TId, TAgent, TInput>
+  ): AgentStepOutputBuilder<TId, TInput>
 }
 
 export type InferAgentStepInput<TStep extends AgentStepDefinition> = TStep extends {

package/src/workflows/validation.ts

@@ -1,8 +1,11 @@
 import { isActionDefinition } from "../actions"
-import { isAgentDefinition } from "../agents"
+import type { AgentToolCatalog } from "../agents"
+import type { ModelCatalog } from "../models"
+import { isModelReasoning } from "../models/language-model"
 import type { SchemaOrRef, ValueType } from "../ontology"
 import { validateSchemaOrRefValue } from "../ontology"
 import type { ScheduleDefinition } from "../schedules"
+import type { SecurityDefinitionCatalog } from "../security"
 import { WorkflowDefinitionError, WorkflowValidationError } from "./errors"
 import type {
   AgentStepDefinition,
@@ -45,7 +48,11 @@ export function isAgentStepDefinition(value: unknown): value is AgentStepDefinit
     isRecord(value) &&
     value.kind === "agentStep" &&
     typeof value.id === "string" &&
-    isAgentDefinition(value.agent) &&
+    (value.model === undefined || isLanguageModel(value.model)) &&
+    (value.reasoning === undefined || isModelReasoning(value.reasoning)) &&
+    typeof value.instructions === "string" &&
+    isStringArray(value.groupIds) &&
+    isStringArray(value.toolNames) &&
     isRecord(value.input) &&
     isRecord(value.output) &&
     typeof value.prompt === "function"
@@ -111,7 +118,8 @@ export function validateWorkflowsAtStartup(options: {
   workflows: readonly WorkflowDefinition[]
   registeredSchedules: ReadonlyMap<string, ScheduleDefinition>
   registeredActionIds: ReadonlySet<string>
-  registeredAgentIds: ReadonlySet<string>
+  models?: ModelCatalog
+  tools: AgentToolCatalog
 }): readonly WorkflowDefinition[] {
   for (const workflow of options.workflows) {
     validateWorkflowDefinition(workflow)
@@ -131,10 +139,8 @@ export function validateWorkflowsAtStartup(options: {
           `Workflow "${workflow.id}" references unknown action "${node.action.id}". Add it to 'actions' in createSixb() or export it from 'actions/'.`
         )
       }
-      if (node.type === "agent" && !options.registeredAgentIds.has(node.agentStep.agent.id)) {
-        throw new WorkflowDefinitionError(
-          `Workflow "${workflow.id}" references unknown agent "${node.agentStep.agent.id}". Add it to 'agents' in createSixb() or export it from 'agents/'.`
-        )
+      if (node.type === "agent") {
+        validateWorkflowAgentStepRuntimeReferences(workflow.id, node.agentStep, options)
       }
     }
   }
@@ -142,6 +148,52 @@ export function validateWorkflowsAtStartup(options: {
   return options.workflows
 }
 
+/** Validate workflow task memberships once the security catalog has been composed. */
+export function validateWorkflowAgentStepGroupReferences(
+  workflows: readonly WorkflowDefinition[],
+  security: SecurityDefinitionCatalog
+): void {
+  for (const workflow of workflows) {
+    for (const node of workflow.nodes) {
+      if (node.type !== "agent") continue
+      for (const groupId of node.agentStep.groupIds) {
+        if (!security.getGroupById(groupId)) {
+          throw new WorkflowDefinitionError(
+            `Workflow "${workflow.id}" agent step "${node.id}" references unknown group "${groupId}". Add it to 'security/groups/' or pass it to createSixb({ groups }).`
+          )
+        }
+      }
+    }
+  }
+}
+
+function validateWorkflowAgentStepRuntimeReferences(
+  workflowId: string,
+  step: AgentStepDefinition,
+  options: { readonly models?: ModelCatalog; readonly tools: AgentToolCatalog }
+): void {
+  if (step.model === undefined && options.models === undefined) {
+    throw new WorkflowDefinitionError(
+      `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().`
+      )
+    }
+  }
+  for (const toolName of step.toolNames) {
+    if (options.tools.getByName(toolName) === null) {
+      throw new WorkflowDefinitionError(
+        `Workflow "${workflowId}" agent step "${step.id}" uses unknown project tool "${toolName}". Add it to 'tools' in createSixb().`
+      )
+    }
+  }
+}
+
 export function validateWorkflowInput(params: {
   readonly workflow: WorkflowDefinition
   readonly value: unknown
@@ -326,6 +378,13 @@ function validateAgentNodeDefinition(workflowId: string, node: WorkflowAgentNode
       `Workflow "${workflowId}" agent node id "${node.id}" does not match agent step definition id "${node.agentStep.id}".`
     )
   }
+  if (!node.agentStep.instructions.trim()) {
+    throw new WorkflowDefinitionError(
+      `Workflow "${workflowId}" agent step "${node.id}" instructions must not be empty.`
+    )
+  }
+  assertUniqueNonEmptyAgentStepValues(workflowId, node.id, "group", node.agentStep.groupIds)
+  assertUniqueNonEmptyAgentStepValues(workflowId, node.id, "tool", node.agentStep.toolNames)
   if (node.mapper !== undefined && typeof node.mapper !== "function") {
     throw new WorkflowDefinitionError(
       `Workflow "${workflowId}" agent node "${node.id}" mapper must be a function.`
@@ -333,6 +392,40 @@ function validateAgentNodeDefinition(workflowId: string, node: WorkflowAgentNode
   }
 }
 
+function assertUniqueNonEmptyAgentStepValues(
+  workflowId: string,
+  stepId: string,
+  kind: "group" | "tool",
+  values: readonly string[]
+): void {
+  const seen = new Set<string>()
+  for (const value of values) {
+    if (!value.trim()) {
+      throw new WorkflowDefinitionError(
+        `Workflow "${workflowId}" agent step "${stepId}" has an empty ${kind} id.`
+      )
+    }
+    if (seen.has(value)) {
+      throw new WorkflowDefinitionError(
+        `Workflow "${workflowId}" agent step "${stepId}" has duplicate ${kind} '${value}'.`
+      )
+    }
+    seen.add(value)
+  }
+}
+
+function isLanguageModel(value: unknown): boolean {
+  return (typeof value === "object" || typeof value === "function") && value !== null
+}
+
+function isStringArray(value: unknown): value is readonly string[] {
+  if (!Array.isArray(value)) return false
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.hasOwn(value, index) || typeof value[index] !== "string") return false
+  }
+  return true
+}
+
 export function validateWorkflowAgentStepInput(params: {
   readonly workflowId: string
   readonly agentStep: AgentStepDefinition