@shipfox/api-workflows 2.0.0

package/src/core/step-config/materialize-job-execution-steps.test.ts

@@ -0,0 +1,494 @@
+import {
+  InvalidAgentModelError,
+  UnsupportedModelProviderError,
+} 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,
+} from '@shipfox/api-agent-dto';
+import type {AgentToolCatalogEntry} from '@shipfox/api-integration-core';
+import type {AgentToolMaterializationContext} from '#core/agent-tools.js';
+import {AgentConfigUnresolvableError, InterpolationUnresolvableError} from '#core/errors.js';
+import {workflowModel} from '#test/index.js';
+import {materializeJobExecutionSteps} from './materialize-job-execution-steps.js';
+import type {WorkflowEvaluationContext} from './workflow-evaluation-context.js';
+
+function template(source: string): string {
+  return `\${{ ${source} }}`;
+}
+
+function shellRef(name: string): string {
+  return `\${${name}}`;
+}
+
+function jobExecutionContext(): WorkflowEvaluationContext {
+  return {
+    site: 'execution-creation',
+    values: {
+      run: {
+        id: 'run-1',
+        name: 'Reviews',
+        definition_id: 'def-1',
+        project_id: 'proj-1',
+        workspace_id: 'workspace-1',
+        created_at: new Date('2026-06-30T12:00:00.000Z'),
+      },
+      trigger: {source: 'manual', event: 'fire'},
+      event: null,
+      inputs: null,
+      execution: {
+        index: 1,
+        name: 'Review batch 2',
+        status: 'pending',
+        started_at: '2026-06-30T12:01:00.000Z',
+        finished_at: null,
+        events: [
+          {
+            source: 'github',
+            event: 'pull_request_review',
+            delivery_id: 'delivery-2',
+            received_at: '2026-06-30T12:01:00.000Z',
+            data: {body: 'LGTM'},
+          },
+        ],
+      },
+      executions: [
+        {
+          index: 0,
+          name: 'Review batch 1',
+          status: 'succeeded',
+          started_at: '2026-06-30T12:00:00.000Z',
+          finished_at: '2026-06-30T12:00:30.000Z',
+          events: [],
+        },
+      ],
+    },
+  };
+}
+
+function githubAgentToolContext(
+  catalog: readonly AgentToolCatalogEntry[] = githubAgentToolCatalog(),
+): AgentToolMaterializationContext {
+  return {
+    catalogs: new Map([['github', catalog]]),
+    workspaceConnectionSnapshot: new Map([
+      [
+        'github-main',
+        {
+          id: 'connection-1',
+          provider: 'github',
+          capabilities: ['agent_tools'],
+        },
+      ],
+    ]),
+    defaultConnection: {
+      id: 'connection-1',
+      slug: 'github-main',
+      provider: 'github',
+    },
+  };
+}
+
+function githubAgentToolCatalog(): readonly AgentToolCatalogEntry[] {
+  return [
+    {
+      id: 'issue_read',
+      description: 'Read issues.',
+      sensitivity: 'read',
+      sensitive: false,
+      requiredScope: [{permission: 'issues', access: 'read'}],
+      inputSchema: {type: 'object'},
+      methods: [
+        {
+          id: 'get',
+          description: 'Get issue.',
+          sensitivity: 'read',
+          sensitive: false,
+          requiredScope: [{permission: 'issues', access: 'read'}],
+        },
+        {
+          id: 'get_comments',
+          description: 'Get issue comments.',
+          sensitivity: 'read',
+          sensitive: false,
+          requiredScope: [{permission: 'issues', access: 'read'}],
+        },
+      ],
+    },
+    {
+      id: 'issue_write',
+      description: 'Write issues.',
+      sensitivity: 'write',
+      sensitive: false,
+      requiredScope: [{permission: 'issues', access: 'write'}],
+      inputSchema: {type: 'object'},
+      methods: [
+        {
+          id: 'create',
+          description: 'Create issue.',
+          sensitivity: 'write',
+          sensitive: false,
+          requiredScope: [{permission: 'issues', access: 'write'}],
+        },
+      ],
+    },
+    {
+      id: 'merge_pull_request',
+      description: 'Merge a pull request.',
+      sensitivity: 'write',
+      sensitive: true,
+      requiredScope: [
+        {permission: 'pull_requests', access: 'write'},
+        {permission: 'contents', access: 'write'},
+      ],
+      inputSchema: {type: 'object'},
+    },
+  ];
+}
+
+describe('materializeJobExecutionSteps', () => {
+  it('prepends setup and resolves job-execution context fields', () => {
+    const model = workflowModel({
+      jobs: {
+        review: {
+          steps: [
+            {
+              name: `Review ${template('execution.events[0].data.body')}`,
+              run: `echo "${template('executions[0].name')}"`,
+              env: {BODY: template('execution.events[0].data.body')},
+            },
+          ],
+        },
+      },
+    });
+    const job = model.jobs[0];
+    if (!job) throw new Error('Expected workflow job');
+
+    const steps = materializeJobExecutionSteps({model, job, context: jobExecutionContext()});
+
+    expect(steps).toEqual([
+      {
+        key: null,
+        name: 'Set up job',
+        sourceLocation: null,
+        status: 'pending',
+        type: 'setup',
+        config: {},
+        authoredConfig: null,
+        position: 0,
+      },
+      {
+        key: null,
+        name: 'Review LGTM',
+        sourceLocation: null,
+        status: 'pending',
+        type: 'run',
+        config: {
+          run: `echo "${shellRef('__sf_0')}"`,
+          env: {
+            BODY: 'LGTM',
+            __sf_0: 'Review batch 1',
+          },
+        },
+        authoredConfig: {
+          run: `echo "${template('executions[0].name')}"`,
+          env: {BODY: template('execution.events[0].data.body')},
+        },
+        configPlan: {
+          trace: [
+            {
+              expression: 'execution.events[0].data.body',
+              roots: ['execution'],
+              fillTarget: 'execution-creation',
+              evaluatedAt: 'execution-creation',
+              value: 'LGTM',
+              field: 'env',
+              envKey: 'BODY',
+            },
+            {
+              expression: 'executions[0].name',
+              roots: ['executions'],
+              fillTarget: 'execution-creation',
+              evaluatedAt: 'execution-creation',
+              value: 'Review batch 1',
+              field: 'run',
+            },
+            {
+              expression: 'execution.events[0].data.body',
+              roots: ['execution'],
+              fillTarget: 'execution-creation',
+              evaluatedAt: 'execution-creation',
+              value: 'LGTM',
+              field: 'step.name',
+            },
+          ],
+        },
+        position: 1,
+      },
+    ]);
+  });
+
+  it('freezes resolved agent integration tools with default connection, repo, and token scope', () => {
+    const model = workflowModel({
+      jobs: {
+        fix: {
+          steps: [
+            {
+              harness: 'pi',
+              provider: 'anthropic',
+              model: 'claude-opus-4-8',
+              thinking: 'high',
+              prompt: 'Fix it.',
+              integrations: [
+                {
+                  include: ['issue_read.get', 'issue_write.create', 'merge_pull_request'],
+                  allowWrite: true,
+                },
+              ],
+            },
+          ],
+        },
+      },
+    });
+    const job = model.jobs[0];
+    if (!job) throw new Error('Expected workflow job');
+
+    const steps = materializeJobExecutionSteps({
+      model,
+      job,
+      context: jobExecutionContext(),
+      agentToolContext: githubAgentToolContext(),
+    });
+    const integrations = steps[1]?.config.integrations;
+
+    expect(integrations).toEqual([
+      {
+        connectionId: 'connection-1',
+        connectionSlug: 'github-main',
+        provider: 'github',
+        requiredScope: [
+          {permission: 'issues', access: 'write'},
+          {permission: 'pull_requests', access: 'write'},
+          {permission: 'contents', access: 'write'},
+        ],
+        tools: [
+          {
+            id: 'issue_read',
+            sensitivity: 'read',
+            sensitive: false,
+            requiredScope: [{permission: 'issues', access: 'read'}],
+            inputSchema: {type: 'object'},
+            methods: [
+              {
+                id: 'get',
+                token: 'issue_read.get',
+                description: 'Get issue.',
+                sensitivity: 'read',
+                sensitive: false,
+                requiredScope: [{permission: 'issues', access: 'read'}],
+              },
+            ],
+          },
+          {
+            id: 'issue_write',
+            sensitivity: 'write',
+            sensitive: false,
+            requiredScope: [{permission: 'issues', access: 'write'}],
+            inputSchema: {type: 'object'},
+            methods: [
+              {
+                id: 'create',
+                token: 'issue_write.create',
+                description: 'Create issue.',
+                sensitivity: 'write',
+                sensitive: false,
+                requiredScope: [{permission: 'issues', access: 'write'}],
+              },
+            ],
+          },
+          {
+            id: 'merge_pull_request',
+            sensitivity: 'write',
+            sensitive: true,
+            requiredScope: [
+              {permission: 'pull_requests', access: 'write'},
+              {permission: 'contents', access: 'write'},
+            ],
+            inputSchema: {type: 'object'},
+          },
+        ],
+      },
+    ]);
+    expect(steps[1]?.config.mcpServers).toEqual([
+      {
+        name: AGENT_INTEGRATION_MCP_SERVER_NAME,
+        transport: AGENT_INTEGRATION_MCP_TRANSPORT,
+        endpoint: AGENT_INTEGRATION_MCP_ENDPOINT,
+        auth: AGENT_INTEGRATION_MCP_AUTH,
+        integrations,
+      },
+    ]);
+  });
+
+  it('carries frozen integrations through the agent dispatch plan when prompt is deferred', () => {
+    const model = workflowModel({
+      jobs: {
+        fix: {
+          steps: [
+            {
+              harness: 'pi',
+              provider: 'anthropic',
+              model: 'claude-opus-4-8',
+              thinking: 'high',
+              prompt: `Fix ${template('steps.build.outputs.summary')}`,
+              integrations: [
+                {
+                  connection: 'github-main',
+                  include: ['issue_read'],
+                  exclude: ['issue_read.get_comments'],
+                  allowWrite: false,
+                },
+              ],
+            },
+          ],
+        },
+      },
+    });
+    const job = model.jobs[0];
+    if (!job) throw new Error('Expected workflow job');
+
+    const steps = materializeJobExecutionSteps({
+      model,
+      job,
+      context: jobExecutionContext(),
+      agentToolContext: githubAgentToolContext(),
+    });
+
+    expect(steps[1]?.config).toEqual({
+      harness: 'pi',
+      provider: 'anthropic',
+      model: 'claude-opus-4-8',
+      thinking: 'high',
+    });
+    const integrations = steps[1]?.configPlan?.agent?.integrations;
+    expect(integrations).toEqual([
+      {
+        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',
+                description: 'Get issue.',
+                sensitivity: 'read',
+                sensitive: false,
+                requiredScope: [{permission: 'issues', access: 'read'}],
+              },
+            ],
+          },
+        ],
+      },
+    ]);
+    expect(steps[1]?.configPlan?.agent?.mcpServers).toEqual([
+      {
+        name: AGENT_INTEGRATION_MCP_SERVER_NAME,
+        transport: AGENT_INTEGRATION_MCP_TRANSPORT,
+        endpoint: AGENT_INTEGRATION_MCP_ENDPOINT,
+        auth: AGENT_INTEGRATION_MCP_AUTH,
+        integrations,
+      },
+    ]);
+  });
+
+  it('throws a permanent interpolation error for available missing value paths', () => {
+    const model = workflowModel({
+      jobs: {
+        review: {
+          steps: [{run: 'echo ok', env: {TICKET: template('inputs.ticket')}}],
+        },
+      },
+    });
+    const job = model.jobs[0];
+    if (!job) throw new Error('Expected workflow job');
+    const baseContext = jobExecutionContext();
+
+    let error: unknown;
+    try {
+      materializeJobExecutionSteps({
+        model,
+        job,
+        context: {...baseContext, values: {...baseContext.values, inputs: {}}},
+        definitionId: 'def-1',
+      });
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(InterpolationUnresolvableError);
+    expect(error).toMatchObject({
+      field: 'env',
+      source: 'inputs.ticket',
+      envKey: 'TICKET',
+    });
+  });
+
+  it.each([
+    new UnsupportedModelProviderError('unknown-provider'),
+    new InvalidAgentModelError('pi', 'anthropic', 'missing-model'),
+  ])('wraps known resolver errors as permanent agent config errors', (cause) => {
+    const model = workflowModel({
+      jobs: {
+        review: {steps: [{prompt: 'Summarize the review.'}]},
+      },
+    });
+    const job = model.jobs[0];
+    if (!job) throw new Error('Expected workflow job');
+    const resolveAgentDefaults = vi.fn<AgentDefaultsResolver>().mockImplementation(() => {
+      throw cause;
+    });
+
+    const materialize = () =>
+      materializeJobExecutionSteps({
+        model,
+        job,
+        context: jobExecutionContext(),
+        resolveAgentDefaults,
+        definitionId: 'def-1',
+      });
+
+    expect(materialize).toThrow(AgentConfigUnresolvableError);
+    expect(materialize).toThrow('Agent configuration cannot be resolved for definition def-1');
+  });
+
+  it('throws a permanent interpolation error for unsafe run interpolation', () => {
+    const model = workflowModel({
+      jobs: {
+        review: {steps: [{run: `echo \`${template('execution.index')}\``}]},
+      },
+    });
+    const job = model.jobs[0];
+    if (!job) throw new Error('Expected workflow job');
+
+    const materialize = () =>
+      materializeJobExecutionSteps({
+        model,
+        job,
+        context: jobExecutionContext(),
+        definitionId: 'def-1',
+      });
+
+    expect(materialize).toThrow(InterpolationUnresolvableError);
+  });
+});

package/src/core/step-config/materialize-job-execution-steps.ts

@@ -0,0 +1,136 @@
+import {
+  type AgentDefaultsResolver,
+  catalogDefaultAgentResolver,
+} from '@shipfox/api-agent/core/resolve-agent-config';
+import type {WorkflowModel} from '@shipfox/api-definitions';
+import type {WorkflowExpression} from '@shipfox/expression';
+import type {
+  AgentToolMaterializationContext,
+  AgentToolMaterializationSnapshot,
+} from '#core/agent-tools.js';
+import type {StepConfigDispatchPlan} from '#core/entities/step.js';
+import {resolveStepConfig, type WorkflowStepTemplateDiagnostic} from './resolve-step-config.js';
+import type {WorkflowEvaluationContext} from './workflow-evaluation-context.js';
+
+type WorkflowModelJob = WorkflowModel['jobs'][number];
+type WorkflowModelStep = WorkflowModelJob['steps'][number];
+type WorkflowSourceLocation = NonNullable<WorkflowModelStep['sourceLocation']>;
+
+const FIRST_LINE_PATTERN = /\r?\n/;
+
+export interface MaterializedWorkflowStep {
+  readonly key: string | null;
+  readonly name: string;
+  readonly sourceLocation: WorkflowSourceLocation | null;
+  readonly status: 'pending';
+  readonly type: WorkflowModelStep['kind'] | 'setup';
+  readonly config: Readonly<Record<string, unknown>>;
+  readonly condition?: WorkflowExpression;
+  readonly configPlan?: StepConfigDispatchPlan;
+  readonly authoredConfig: Readonly<Record<string, unknown>> | null;
+  readonly diagnostics?: readonly WorkflowStepTemplateDiagnostic[];
+  readonly position: number;
+}
+
+export interface MaterializeJobExecutionStepsParams {
+  readonly model: WorkflowModel;
+  readonly job: WorkflowModelJob;
+  readonly context: WorkflowEvaluationContext;
+  readonly resolveAgentDefaults?: AgentDefaultsResolver | undefined;
+  readonly definitionId?: string | undefined;
+  readonly agentToolContext?: AgentToolMaterializationContext | undefined;
+  readonly agentToolSnapshot?: AgentToolMaterializationSnapshot | null | undefined;
+}
+
+// Synthetic "Set up job" step prepended when a job execution's steps are materialized.
+// The runner prepares the workspace here; failures report through the normal step
+// protocol instead of hanging the job until the lease/timeout fires. Its config is
+// credential-free.
+const SETUP_STEP: MaterializedWorkflowStep = {
+  key: null,
+  name: 'Set up job',
+  sourceLocation: null,
+  status: 'pending',
+  type: 'setup',
+  config: {},
+  authoredConfig: null,
+  position: 0,
+};
+
+export function materializeJobExecutionSteps(
+  params: MaterializeJobExecutionStepsParams,
+): readonly MaterializedWorkflowStep[] {
+  const {
+    model,
+    job,
+    context,
+    resolveAgentDefaults = catalogDefaultAgentResolver,
+    definitionId = model.name,
+    agentToolContext,
+    agentToolSnapshot,
+  } = params;
+
+  return [
+    SETUP_STEP,
+    ...job.steps.map((step, stepPosition) => {
+      // The trusted context exposes the stable job key; the authored display field remains `job.name`.
+      const stepContext = {...context.values, job: {key: job.key}};
+      const resolved = resolveStepConfig({
+        jobKey: job.key,
+        step,
+        workflowEnv: model.env,
+        workflowEnvTemplates: model.templates?.env,
+        jobEnv: job.env,
+        jobEnvTemplates: job.templates?.env,
+        context: stepContext,
+        site: context.site,
+        resolveAgentDefaults,
+        definitionId,
+        agentToolContext,
+        agentToolSnapshot,
+      });
+      return {
+        key: step.key ?? null,
+        name: resolved.name ?? stepDisplayName(step),
+        sourceLocation: step.sourceLocation ?? null,
+        status: 'pending' as const,
+        type: step.kind,
+        config: resolved.config,
+        ...(step.if === undefined ? {} : {condition: step.if}),
+        authoredConfig: resolved.authoredConfig,
+        ...materializedConfigPlan(resolved.configPlan, resolved.trace),
+        ...(resolved.diagnostics.length === 0 ? {} : {diagnostics: resolved.diagnostics}),
+        position: stepPosition + 1,
+      };
+    }),
+  ];
+}
+
+function materializedConfigPlan(
+  configPlan: StepConfigDispatchPlan | null,
+  trace: NonNullable<StepConfigDispatchPlan['trace']>,
+): {readonly configPlan?: StepConfigDispatchPlan} {
+  if (configPlan === null && trace.length === 0) return {};
+  return {configPlan: {...(configPlan ?? {}), ...(trace.length === 0 ? {} : {trace})}};
+}
+
+function stepDisplayName(step: WorkflowModelStep): string {
+  switch (step.kind) {
+    case 'run':
+      return firstLine(step.command.value);
+    case 'agent':
+      return step.model === undefined
+        ? firstLine(step.prompt)
+        : `${step.model} · ${firstLine(step.prompt)}`;
+    default:
+      return assertNever(step);
+  }
+}
+
+function firstLine(value: string): string {
+  return value.split(FIRST_LINE_PATTERN, 1)[0]?.trim() || value.trim();
+}
+
+function assertNever(value: never): never {
+  throw new Error(`Unhandled workflow step kind: ${JSON.stringify(value)}`);
+}