@shipfox/api-workflows 2.0.0

package/src/core/step-config/complete-step-dispatch-config.test.ts

@@ -0,0 +1,354 @@
+import {UnsupportedHarnessThinkingError} from '@shipfox/api-agent/core/errors';
+import type {AgentDefaultsResolver} from '@shipfox/api-agent/core/resolve-agent-config';
+import {
+  AGENT_INTEGRATION_MCP_AUTH,
+  AGENT_INTEGRATION_MCP_ENDPOINT,
+  AGENT_INTEGRATION_MCP_SERVER_NAME,
+  AGENT_INTEGRATION_MCP_TRANSPORT,
+  type AgentIntegrationMcpServerConfigDto,
+  type MaterializedAgentIntegrationConfigDto,
+} from '@shipfox/api-agent-dto';
+import {parseWorkflowTemplate, planInterpolationField} from '@shipfox/expression';
+import type {Step} from '#core/entities/step.js';
+import {AgentConfigUnresolvableError, InterpolationUnresolvableError} from '#core/errors.js';
+import {completeStepDispatchConfig} from './complete-step-dispatch-config.js';
+import type {WorkflowEvaluationContext} from './workflow-evaluation-context.js';
+
+function plannedField(source: string) {
+  const plan = planInterpolationField({
+    field: 'env.value',
+    segments: parseWorkflowTemplate(source),
+  });
+  if (!plan.ok) throw new Error('Expected field plan to be valid');
+  return plan.plan.field;
+}
+
+function template(source: string): string {
+  return '$'.concat('{{ ', source, ' }}');
+}
+
+function step(overrides: Partial<Step>): Step {
+  return {
+    id: 'step-1',
+    jobExecutionId: 'exec-1',
+    key: 'deploy',
+    name: 'Deploy',
+    sourceLocation: null,
+    status: 'pending',
+    statusReason: null,
+    evaluationTrace: null,
+    type: 'run',
+    config: {},
+    condition: null,
+    configPlan: null,
+    authoredConfig: null,
+    error: null,
+    position: 1,
+    version: 1,
+    currentAttempt: 1,
+    createdAt: new Date('2026-06-30T12:00:00.000Z'),
+    updatedAt: new Date('2026-06-30T12:00:00.000Z'),
+    ...overrides,
+  };
+}
+
+const context: WorkflowEvaluationContext = {
+  site: 'step-dispatch',
+  values: {
+    steps: {
+      build: {
+        outputs: {sha: 'abc123'},
+      },
+    },
+  },
+};
+
+const resolveAgentDefaults: AgentDefaultsResolver = (params) => ({
+  harness: params.harness ?? 'pi',
+  provider: params.provider ?? 'openai',
+  model: params.model ?? 'gpt-5.5',
+  thinking: params.thinking ?? 'off',
+});
+
+function materializedIntegration(): MaterializedAgentIntegrationConfigDto {
+  return {
+    connectionId: 'connection-1',
+    connectionSlug: 'github-main',
+    provider: 'github',
+    requiredScope: [{permission: 'issues', access: 'read'}],
+    tools: [
+      {
+        id: 'issue_read',
+        sensitivity: 'read',
+        sensitive: false,
+        requiredScope: [{permission: 'issues', access: 'read'}],
+        inputSchema: {type: 'object'},
+        methods: [
+          {
+            id: 'get',
+            token: 'issue_read.get',
+            sensitivity: 'read',
+            sensitive: false,
+            requiredScope: [{permission: 'issues', access: 'read'}],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function integrationMcpServers(
+  integrations: readonly MaterializedAgentIntegrationConfigDto[],
+): readonly AgentIntegrationMcpServerConfigDto[] {
+  return [
+    {
+      name: AGENT_INTEGRATION_MCP_SERVER_NAME,
+      transport: AGENT_INTEGRATION_MCP_TRANSPORT,
+      endpoint: AGENT_INTEGRATION_MCP_ENDPOINT,
+      auth: AGENT_INTEGRATION_MCP_AUTH,
+      integrations: [...integrations],
+    },
+  ];
+}
+
+describe('completeStepDispatchConfig', () => {
+  it('copies frozen agent integrations from the dispatch plan', () => {
+    const integrations = [materializedIntegration()];
+    const pending = step({
+      type: 'agent',
+      config: {
+        harness: 'pi',
+        provider: 'anthropic',
+        model: 'claude-opus-4-8',
+        thinking: 'high',
+      },
+      configPlan: {
+        agent: {
+          prompt: plannedField(template('steps.build.outputs.sha')),
+          integrations,
+        },
+      },
+    });
+
+    const result = completeStepDispatchConfig({
+      step: pending,
+      context,
+      resolveAgentDefaults,
+      definitionId: 'def-1',
+    });
+
+    expect(result.config.integrations).toEqual(integrations);
+    expect(result.config.mcpServers).toEqual(integrationMcpServers(integrations));
+  });
+
+  it('serializes residual secret env values as secret bindings without writing env values', () => {
+    const pending = step({
+      config: {},
+      configPlan: {
+        env: {
+          TOKEN: plannedField(`prefix-${template('secrets.local.TOKEN')}`),
+          SHORT: plannedField(template('secrets.API_KEY')),
+        },
+      },
+    });
+
+    const result = completeStepDispatchConfig({
+      step: pending,
+      context,
+      resolveAgentDefaults,
+      definitionId: 'def-1',
+    });
+
+    expect(result.config).toEqual({
+      secret_bindings: [
+        {
+          target: 'TOKEN',
+          segments: [
+            {kind: 'literal', value: 'prefix-'},
+            {kind: 'secret', store: 'local', key: 'TOKEN'},
+          ],
+        },
+        {
+          target: 'SHORT',
+          segments: [{kind: 'secret', store: 'local', key: 'API_KEY'}],
+        },
+      ],
+    });
+    expect(result.trace).toEqual([
+      {
+        expression: 'secrets.local.TOKEN',
+        roots: ['secrets'],
+        fillTarget: 'runner-fill',
+        evaluatedAt: 'step-dispatch',
+        reference: true,
+        field: 'env',
+        envKey: 'TOKEN',
+      },
+      {
+        expression: 'secrets.API_KEY',
+        roots: ['secrets'],
+        fillTarget: 'runner-fill',
+        evaluatedAt: 'step-dispatch',
+        reference: true,
+        field: 'env',
+        envKey: 'SHORT',
+      },
+    ]);
+  });
+
+  it('rejects secret env bindings with malformed target names', () => {
+    const pending = step({
+      config: {},
+      configPlan: {
+        env: {
+          'BAD-NAME': plannedField(template('secrets.API_KEY')),
+        },
+      },
+    });
+
+    const act = () =>
+      completeStepDispatchConfig({
+        step: pending,
+        context,
+        resolveAgentDefaults,
+        definitionId: 'def-1',
+      });
+
+    expect(act).toThrow();
+  });
+
+  it('keeps fully resolved step config byte-identical apart from resolved env additions', () => {
+    const pending = step({
+      config: {run: 'echo "$SHA"'},
+      configPlan: {
+        env: {
+          SHA: plannedField(template('steps.build.outputs.sha')),
+        },
+      },
+    });
+
+    const result = completeStepDispatchConfig({
+      step: pending,
+      context,
+      resolveAgentDefaults,
+      definitionId: 'def-1',
+    });
+
+    expect(result).toEqual({
+      config: {run: 'echo "$SHA"', env: {SHA: 'abc123'}},
+      trace: [
+        {
+          expression: 'steps.build.outputs.sha',
+          roots: ['steps'],
+          fillTarget: 'step-dispatch',
+          evaluatedAt: 'step-dispatch',
+          value: 'abc123',
+          field: 'env',
+          envKey: 'SHA',
+        },
+      ],
+    });
+  });
+
+  it('completes deferred agent config with the resolved harness', () => {
+    const integration = materializedIntegration();
+    const mcpServers = integrationMcpServers([integration]);
+    const pending = step({
+      type: 'agent',
+      config: {},
+      configPlan: {
+        agent: {
+          harness: 'claude',
+          tools: ['Read', 'WebSearch'],
+          integrations: [integration],
+          mcpServers,
+          prompt: plannedField(`Review ${template('steps.build.outputs.sha')}`),
+        },
+      },
+    });
+
+    const result = completeStepDispatchConfig({
+      step: pending,
+      context,
+      resolveAgentDefaults,
+      definitionId: 'def-1',
+    });
+
+    expect(result).toEqual({
+      config: {
+        harness: 'claude',
+        provider: 'openai',
+        model: 'gpt-5.5',
+        thinking: 'off',
+        tools: ['Read', 'WebSearch'],
+        integrations: [integration],
+        mcpServers,
+        prompt: 'Review abc123',
+      },
+      trace: [
+        {
+          expression: 'steps.build.outputs.sha',
+          roots: ['steps'],
+          fillTarget: 'step-dispatch',
+          evaluatedAt: 'step-dispatch',
+          value: 'abc123',
+          field: 'agent.prompt',
+        },
+      ],
+    });
+  });
+
+  it('wraps harness resolver errors as unresolvable agent config', () => {
+    const pending = step({
+      type: 'agent',
+      config: {},
+      configPlan: {
+        agent: {
+          harness: 'claude',
+          thinking: 'off',
+          prompt: plannedField(`Review ${template('steps.build.outputs.sha')}`),
+        },
+      },
+    });
+    const failingResolver: AgentDefaultsResolver = () => {
+      throw new UnsupportedHarnessThinkingError('claude', 'off', [
+        'low',
+        'medium',
+        'high',
+        'xhigh',
+        'max',
+      ]);
+    };
+
+    const act = () =>
+      completeStepDispatchConfig({
+        step: pending,
+        context,
+        resolveAgentDefaults: failingResolver,
+        definitionId: 'def-1',
+      });
+
+    expect(act).toThrow(AgentConfigUnresolvableError);
+  });
+
+  it('throws when a server-side segment still survives dispatch', () => {
+    const pending = step({
+      config: {},
+      configPlan: {
+        env: {
+          STATUS: plannedField(template('step.status')),
+        },
+      },
+    });
+
+    const act = () =>
+      completeStepDispatchConfig({
+        step: pending,
+        context,
+        resolveAgentDefaults,
+        definitionId: 'def-1',
+      });
+
+    expect(act).toThrow(InterpolationUnresolvableError);
+  });
+});

package/src/core/step-config/complete-step-dispatch-config.ts

@@ -0,0 +1,40 @@
+import type {AgentDefaultsResolver} from '@shipfox/api-agent/core/resolve-agent-config';
+import {capTraceEntries} from '@shipfox/expression';
+import type {PersistedEvaluationTraceEntry, Step} from '#core/entities/step.js';
+import {completeAgentConfig} from './agent.js';
+import {completeRunDispatchConfig} from './run.js';
+import type {WorkflowEvaluationContext} from './workflow-evaluation-context.js';
+
+export function completeStepDispatchConfig(params: {
+  readonly step: Step;
+  readonly context: WorkflowEvaluationContext;
+  readonly resolveAgentDefaults: AgentDefaultsResolver;
+  readonly definitionId: string;
+}): {
+  readonly config: Record<string, unknown>;
+  readonly trace: readonly PersistedEvaluationTraceEntry[];
+} {
+  const plan = params.step.configPlan;
+  if (plan === null) return {config: params.step.config, trace: []};
+
+  const config = {...params.step.config};
+  delete config.secret_bindings;
+  const trace: PersistedEvaluationTraceEntry[] = [...(plan.trace ?? [])];
+  completeRunDispatchConfig({
+    config,
+    plan,
+    context: params.context,
+    definitionId: params.definitionId,
+    trace,
+  });
+  completeAgentConfig({
+    config,
+    plan,
+    context: params.context,
+    resolveAgentDefaults: params.resolveAgentDefaults,
+    definitionId: params.definitionId,
+    trace,
+  });
+
+  return {config, trace: capTraceEntries(trace)};
+}

package/src/core/step-config/fields.ts

@@ -0,0 +1,111 @@
+import {
+  type EvaluationTraceEntry,
+  freezeResolvedFieldAtSite,
+  getWorkflowInterpolationFieldFailurePolicy,
+  type ResolvedField,
+  resolveFieldAtSite,
+  type SiteResolvedField,
+  type UnsafeRunInterpolationError,
+  type WorkflowInterpolationField,
+  type WorkflowTemplateDiagnostic,
+  WorkflowTemplateResolutionError,
+} from '@shipfox/expression';
+import {InterpolationUnresolvableError, type InterpolationUnresolvableField} from '#core/errors.js';
+import type {WorkflowEvaluationContext} from './workflow-evaluation-context.js';
+
+export type StepConfigField = InterpolationUnresolvableField;
+
+export interface WorkflowStepTemplateDiagnostic extends WorkflowTemplateDiagnostic {
+  readonly field: StepConfigField;
+  readonly envKey?: string;
+}
+
+export interface WorkflowStepEvaluationTraceEntry extends EvaluationTraceEntry {
+  readonly field: StepConfigField;
+  readonly envKey?: string;
+}
+
+export interface ResolveStepFieldParams {
+  readonly field: WorkflowInterpolationField;
+  readonly template: ResolvedField;
+  readonly context: WorkflowEvaluationContext;
+  readonly definitionId: string;
+  readonly errorField: InterpolationUnresolvableField;
+  readonly envKey?: string;
+}
+
+export function resolveStepField(params: ResolveStepFieldParams): SiteResolvedField {
+  try {
+    return resolveFieldAtSite({
+      field: params.template,
+      context: params.context.values,
+      site: params.context.site,
+      failurePolicy: getWorkflowInterpolationFieldFailurePolicy(params.field),
+    });
+  } catch (error) {
+    if (error instanceof WorkflowTemplateResolutionError) {
+      throw stepConfigInterpolationError(params, error);
+    }
+    throw error;
+  }
+}
+
+export function freezeStepField(params: ResolveStepFieldParams): {
+  readonly value: string;
+  readonly diagnostics: SiteResolvedField['diagnostics'];
+  readonly trace: SiteResolvedField['trace'];
+} {
+  try {
+    return freezeResolvedFieldAtSite({
+      field: params.template,
+      context: params.context.values,
+      site: params.context.site,
+      failurePolicy: getWorkflowInterpolationFieldFailurePolicy(params.field),
+    });
+  } catch (error) {
+    if (error instanceof WorkflowTemplateResolutionError) {
+      throw stepConfigInterpolationError(params, error);
+    }
+    throw error;
+  }
+}
+
+export function completeStepField(params: ResolveStepFieldParams): string {
+  return completeStepFieldWithTrace(params).value;
+}
+
+export function completeStepFieldWithTrace(params: ResolveStepFieldParams): {
+  readonly value: string;
+  readonly trace: SiteResolvedField['trace'];
+} {
+  const resolved = resolveStepField(params);
+  if (resolved.kind === 'frozen') return {value: resolved.value, trace: resolved.trace};
+
+  const source = resolved.field.segments.find((segment) => segment.kind === 'deferred')?.expression
+    .source;
+  throw new InterpolationUnresolvableError(params.definitionId, {
+    field: params.errorField,
+    source: source ?? params.field,
+    ...(params.envKey === undefined ? {} : {envKey: params.envKey}),
+  });
+}
+
+export function stepConfigInterpolationError(
+  params: {
+    readonly definitionId: string;
+    readonly errorField: InterpolationUnresolvableField;
+    readonly envKey?: string;
+  },
+  error: WorkflowTemplateResolutionError | UnsafeRunInterpolationError,
+): InterpolationUnresolvableError {
+  return new InterpolationUnresolvableError(params.definitionId, {
+    field: params.errorField,
+    source: error.source,
+    ...(params.envKey === undefined ? {} : {envKey: params.envKey}),
+    cause: error,
+  });
+}
+
+export function literalField(value: string): ResolvedField {
+  return {segments: [{kind: 'literal', value}]};
+}

package/src/core/step-config/index.ts

@@ -0,0 +1,41 @@
+export {
+  type AssembleExecutionCreationContextParams,
+  type AssembleJobActivationContextParams,
+  type AssembleWorkflowRunContextParams,
+  applyListenerFilterSnapshots,
+  assembleCreationContext,
+  assembleExecutionCreationContext,
+  assembleExecutionResolutionContext,
+  assembleExecutionsContext,
+  assembleGateContext,
+  assembleJobActivationContext,
+  assembleJobResolutionContext,
+  assembleListenerSnapshotContext,
+  assembleStepDispatchContext,
+  assembleWorkflowRunContext,
+  type JobContextInput,
+  type ListenerSnapshotPlan,
+  type ListenerTriggerWithSnapshot,
+  type MatcherSnapshotPlan,
+  planListenerFilterSnapshots,
+} from './assemble-run-context.js';
+export {completeStepDispatchConfig} from './complete-step-dispatch-config.js';
+export {
+  type MaterializedWorkflowStep,
+  type MaterializeJobExecutionStepsParams,
+  materializeJobExecutionSteps,
+} from './materialize-job-execution-steps.js';
+export {
+  type MaterializedWorkflowJob,
+  type MaterializeWorkflowModelParams,
+  materializeJobOutputs,
+  materializeJobRunner,
+  materializeWorkflowModel,
+  modelHasAgentStep,
+} from './materialize-workflow-model.js';
+export {
+  type ResolveJobExecutionNameParams,
+  resolveJobExecutionName,
+} from './resolve-job-execution-name.js';
+export type {WorkflowStepTemplateDiagnostic} from './resolve-step-config.js';
+export type {WorkflowEvaluationContext} from './workflow-evaluation-context.js';