@shipfox/api-workflows 4.0.0 → 6.0.0

package/src/core/checkout.ts

@@ -1,5 +1,5 @@
-import type {CheckoutSpec, IntegrationSourceControlService} from '@shipfox/api-integration-core';
-import {getProjectById} from '@shipfox/api-projects';
+import type {IntegrationsModuleClient} from '@shipfox/api-integration-core-dto';
+import type {ProjectsModuleClient} from '@shipfox/api-projects-dto';
 import {getJobById, getWorkflowRunByAttemptId} from '#db/workflow-runs.js';
 import {
   CheckoutIntentUnresolvedError,
@@ -20,15 +20,18 @@ export interface CheckoutIntent {
  * (`workflowRunId`/`workflowRunAttemptId`/`workspaceId` in the lease claim are informational).
  * Chain: job → attempt → run → project source metadata. Credential-free.
  */
-export async function resolveCheckoutIntent(jobId: string): Promise<CheckoutIntent> {
+export async function resolveCheckoutIntent(
+  jobId: string,
+  projects: ProjectsModuleClient,
+): Promise<CheckoutIntent> {
   const job = await getJobById(jobId);
   if (!job) throw new JobNotFoundError(jobId);
 
   const run = await getWorkflowRunByAttemptId(job.workflowRunAttemptId);
   if (!run) throw new WorkflowRunNotFoundError(job.workflowRunAttemptId);
 
-  const project = await getProjectById(run.projectId);
-  if (!project) throw new CheckoutIntentUnresolvedError(run.projectId);
+  const {project} = await projects.getProjectById({projectId: run.projectId});
+  if (project === null) throw new CheckoutIntentUnresolvedError(run.projectId);
 
   return {
     workspaceId: project.workspaceId,
@@ -41,23 +44,47 @@ export async function resolveCheckoutIntent(jobId: string): Promise<CheckoutInte
 
 /**
  * Resolves the job's checkout intent and exchanges it for a short-lived,
- * scoped checkout spec. `ref` is left undefined so the provider defaults to the
- * repository's default branch.
+ * scoped checkout spec. Omitting `ref` lets the provider use the repository's
+ * default branch while preserving the JSON-only inter-module boundary.
  */
 export async function createJobCheckoutSpec({
   jobId,
-  sourceControl,
+  integrations,
+  projects,
 }: {
   jobId: string;
-  sourceControl: IntegrationSourceControlService;
-}): Promise<{spec: CheckoutSpec; persistCredentials: boolean}> {
-  const intent = await resolveCheckoutIntent(jobId);
-  const spec = await sourceControl.createCheckoutSpec({
+  integrations: IntegrationsModuleClient;
+  projects: ProjectsModuleClient;
+}): Promise<{
+  spec: {
+    repositoryUrl: string;
+    ref: string;
+    credentials?: {username: string; token: string; expiresAt: Date};
+    gitAuthor?: {name: string; email: string};
+  };
+  persistCredentials: boolean;
+}> {
+  const intent = await resolveCheckoutIntent(jobId, projects);
+  const response = await integrations.createCheckoutSpec({
     workspaceId: intent.workspaceId,
     connectionId: intent.connectionId,
     externalRepositoryId: intent.externalRepositoryId,
-    ref: undefined,
     permissions: intent.permissions,
   });
-  return {spec, persistCredentials: intent.persistCredentials};
+  const {credentials, gitAuthor, ...checkout} = response;
+  return {
+    spec: {
+      ...checkout,
+      ...(credentials
+        ? {
+            credentials: {
+              ...credentials,
+              expiresAt: new Date(credentials.expiresAt),
+            },
+          }
+        : {}),
+      ...(gitAuthor ? {gitAuthor} : {}),
+    },
+    persistCredentials: intent.persistCredentials,
+  };
 }

package/src/core/entities/workflow-run-attempt.ts

@@ -1,4 +1,4 @@
-import type {WorkflowModel} from '@shipfox/api-definitions';
+import type {WorkflowModel} from '@shipfox/api-definitions-dto';
 import type {AgentToolMaterializationSnapshot} from '#core/agent-tools.js';
 import type {WorkflowRunStatus} from './workflow-run.js';
 

package/src/core/job-execution.ts

@@ -1,4 +1,4 @@
-import {catalogDefaultAgentResolver} from '@shipfox/api-agent/core/resolve-agent-config';
+import type {AgentInterModuleClient} from '@shipfox/api-agent-dto/inter-module';
 import type {LogOutcomeDto} from '@shipfox/api-workflows-dto';
 import {
   coerceStepOutputs,
@@ -26,6 +26,7 @@ import {
   recordWorkflowJobExecutionStepsSettled,
   recordWorkflowStepRestartEnqueued,
 } from '#metrics/instance.js';
+import {createAgentDefaultsResolver} from './agent-defaults.js';
 import {defaultStepConditionTrace, explicitConditionTrace} from './condition-trace.js';
 import type {JobExecution} from './entities/job-execution.js';
 import type {PersistedEvaluationTraceEntry, Step, StepStatusReason} from './entities/step.js';
@@ -83,6 +84,7 @@ interface PendingStepDispatchParams {
   readonly jobExecution: JobExecution;
   readonly context: WorkflowEvaluationContext;
   readonly tx: Tx;
+  readonly agent?: AgentInterModuleClient | undefined;
 }
 
 interface ResolvePendingStepParams {
@@ -92,6 +94,7 @@ interface ResolvePendingStepParams {
   readonly attempts: Awaited<ReturnType<typeof getStepAttemptsByJobExecutionId>>;
   readonly jobs: Awaited<ReturnType<typeof getDirectDependencyJobContexts>>;
   readonly tx: Tx;
+  readonly agent?: AgentInterModuleClient | undefined;
 }
 
 type StepConditionOutcome =
@@ -105,6 +108,7 @@ type StepConditionOutcome =
 async function nextStepForJobExecutionInTransaction(
   jobExecutionId: string,
   tx: Tx,
+  agent?: AgentInterModuleClient | undefined,
 ): Promise<NextStep> {
   const steps = await getStepsByJobExecutionIdForUpdate(jobExecutionId, tx);
   const hasNoSteps = steps.length === 0;
@@ -129,7 +133,7 @@ async function nextStepForJobExecutionInTransaction(
   const attempts = await getStepAttemptsByJobExecutionId(jobExecutionId, tx);
   const jobs = await getDirectDependencyJobContexts(jobExecution.jobId, tx);
 
-  return resolveNextPendingStep({jobExecutionId, steps, jobExecution, attempts, jobs, tx});
+  return resolveNextPendingStep({jobExecutionId, steps, jobExecution, attempts, jobs, tx, agent});
 }
 
 async function resolveNextPendingStep({
@@ -139,6 +143,7 @@ async function resolveNextPendingStep({
   attempts,
   jobs,
   tx,
+  agent,
 }: ResolvePendingStepParams): Promise<NextStep> {
   let skippedAny = false;
   let currentSteps = steps;
@@ -167,7 +172,7 @@ async function resolveNextPendingStep({
     });
     const condition = evaluateStepCondition({step: pending, context});
     if (condition.kind === 'run') {
-      return dispatchPendingStep({jobExecutionId, pending, jobExecution, context, tx});
+      return dispatchPendingStep({jobExecutionId, pending, jobExecution, context, tx, agent});
     }
 
     const skipped = await markStepSkipped(
@@ -208,12 +213,13 @@ async function dispatchPendingStepWithConfigPlan({
   jobExecution,
   context,
   tx,
+  agent,
 }: PendingStepDispatchParams): Promise<NextStep> {
   try {
-    const completed = completeStepDispatchConfig({
+    const completed = await completeStepDispatchConfig({
       step: pending,
       context,
-      resolveAgentDefaults: catalogDefaultAgentResolver,
+      resolveAgentDefaults: agent ? createAgentDefaultsResolver(agent, null) : undefined,
       definitionId: jobExecution.jobId,
     });
     const marked = await dispatchStepWithCompletedConfig(
@@ -258,7 +264,7 @@ async function dispatchPendingStepWithConfigPlan({
     });
     if (status) recordWorkflowJobExecutionStepsSettled(status);
     return status === null
-      ? nextStepForJobExecutionInTransaction(jobExecutionId, tx)
+      ? nextStepForJobExecutionInTransaction(jobExecutionId, tx, agent)
       : {kind: 'done', status};
   }
 }
@@ -333,6 +339,7 @@ export interface NextStepForLeasedJobExecutionParams {
   jobId: string;
   jobExecutionId: string;
   runnerSessionId: string;
+  agent?: AgentInterModuleClient | undefined;
 }
 
 export function nextStepForLeasedJobExecution(
@@ -342,16 +349,19 @@ export function nextStepForLeasedJobExecution(
     const leaseIsActive = await lockActiveJobExecutionLeaseForUpdate(params, tx);
     if (!leaseIsActive) throw new JobLeaseNotActiveError(params.jobExecutionId);
 
-    return nextStepForJobExecutionInTransaction(params.jobExecutionId, tx);
+    return nextStepForJobExecutionInTransaction(params.jobExecutionId, tx, params.agent);
   });
 }
 
-export function nextStepForJob(jobId: string): Promise<NextStep> {
+export function nextStepForJob(
+  jobId: string,
+  agent?: AgentInterModuleClient | undefined,
+): Promise<NextStep> {
   return withTransaction(async (tx) => {
     const jobExecution = await getLatestJobExecutionByJobId(jobId, tx);
     if (!jobExecution) throw new JobNotFoundError(jobId);
 
-    return nextStepForJobExecutionInTransaction(jobExecution.id, tx);
+    return nextStepForJobExecutionInTransaction(jobExecution.id, tx, agent);
   });
 }
 

package/src/core/job-transition/derive-job-execution-outputs.ts

@@ -1,4 +1,4 @@
-import type {WorkflowModel} from '@shipfox/api-definitions';
+import type {WorkflowModel} from '@shipfox/api-definitions-dto';
 import type {Job} from '../entities/job.js';
 import type {JobExecution} from '../entities/job-execution.js';
 import type {Step, StepAttempt} from '../entities/step.js';

package/src/core/job-transition/derive-job-success.ts

@@ -1,4 +1,4 @@
-import {DEFAULT_JOB_SUCCESS} from '@shipfox/api-definitions';
+import {DEFAULT_JOB_SUCCESS} from '@shipfox/api-definitions-dto';
 import {
   capTraceEntries,
   createWorkflowExpression,

package/src/core/listener-execution-materialization.test.ts

@@ -1,8 +1,9 @@
+import {resolveTestAgentDefaults} from '#test/fixtures/agent-inter-module.js';
 import {workflowModel} from '#test/index.js';
 import {materializeListenerExecution} from './listener-execution-materialization.js';
 
 describe('materializeListenerExecution', () => {
-  it('fails cleanly when agent integration materialization is unresolvable', () => {
+  it('fails cleanly when agent integration materialization is unresolvable', async () => {
     const model = workflowModel({
       jobs: {
         review: {
@@ -16,7 +17,7 @@ describe('materializeListenerExecution', () => {
       },
     });
 
-    const result = materializeListenerExecution({
+    const result = await materializeListenerExecution({
       model,
       run: {
         id: crypto.randomUUID(),
@@ -37,6 +38,7 @@ describe('materializeListenerExecution', () => {
       sequence: 1,
       triggerEvents: [],
       priorExecutions: [],
+      resolveAgentDefaults: resolveTestAgentDefaults,
     });
 
     expect(result).toMatchObject({

package/src/core/listener-execution-materialization.ts

@@ -1,8 +1,5 @@
-import {
-  type AgentDefaultsResolver,
-  catalogDefaultAgentResolver,
-} from '@shipfox/api-agent/core/resolve-agent-config';
-import type {WorkflowModel} from '@shipfox/api-definitions';
+import type {WorkflowModel} from '@shipfox/api-definitions-dto';
+import type {AgentDefaultsResolver} from './agent-defaults.js';
 import type {
   AgentToolMaterializationContext,
   AgentToolMaterializationSnapshot,
@@ -61,9 +58,9 @@ export interface MaterializedListenerExecution {
   readonly steps: readonly MaterializedWorkflowStep[];
 }
 
-export function materializeListenerExecution(
+export async function materializeListenerExecution(
   params: MaterializeListenerExecutionParams,
-): MaterializedListenerExecution {
+): Promise<MaterializedListenerExecution> {
   const fallbackName = `${params.job.key} #${params.sequence}`;
   let executionName = fallbackName;
   let evaluationTrace: readonly PersistedEvaluationTraceEntry[] = [];
@@ -95,11 +92,11 @@ export function materializeListenerExecution(
       context,
       definitionId: params.run.definitionId,
     });
-    steps = materializeJobExecutionSteps({
+    steps = await materializeJobExecutionSteps({
       model: params.model,
       job: modelJob,
       context,
-      resolveAgentDefaults: params.resolveAgentDefaults ?? catalogDefaultAgentResolver,
+      resolveAgentDefaults: params.resolveAgentDefaults,
       definitionId: params.run.definitionId,
       agentToolContext: params.agentToolContext,
       agentToolSnapshot: params.agentToolSnapshot,

package/src/core/run-workflow.test.ts

@@ -1,12 +1,14 @@
+import type {AgentInterModuleClient} from '@shipfox/api-agent-dto/inter-module';
 import type {WorkflowDefinition} from '@shipfox/api-definitions';
+import {createWorkflowModelSnapshot} from '@shipfox/api-definitions-dto';
+import type {DefinitionsInterModuleClient} from '@shipfox/api-definitions-dto/inter-module';
 import {workflowModel} from '#test/index.js';
 import type {TriggerPayload} from './entities/workflow-run.js';
 import {DefinitionNotFoundError, ProjectMismatchError} from './errors.js';
 import {runWorkflow} from './run-workflow.js';
 
-const mockCreateWorkspaceAgentDefaultsResolver = vi.hoisted(() => vi.fn());
-const mockWorkspaceAgentDefaultsResolver = vi.hoisted(() =>
-  vi.fn().mockReturnValue({
+const mockResolveAgentConfig = vi.hoisted(() =>
+  vi.fn().mockResolvedValue({
     harness: 'pi',
     provider: 'openai',
     model: 'gpt-5.5-pro',
@@ -22,26 +24,26 @@ vi.mock('@shipfox/api-definitions', () => ({
   getDefinitionById: vi.fn(),
 }));
 
-vi.mock('@shipfox/api-agent/core/resolve-agent-config', () => {
-  return {
-    catalogDefaultAgentResolver: vi.fn().mockReturnValue({
-      harness: 'pi',
-      provider: 'anthropic',
-      model: 'claude-opus-4-8',
-      thinking: 'xhigh',
-    }),
-  };
-});
-
-vi.mock('@shipfox/api-agent/core/workspace-agent-defaults-resolver', () => {
-  return {
-    createWorkspaceAgentDefaultsResolver: mockCreateWorkspaceAgentDefaultsResolver,
-  };
-});
-
 import {getDefinitionById} from '@shipfox/api-definitions';
 
 const mockGetDefinitionById = vi.mocked(getDefinitionById);
+const definitions: DefinitionsInterModuleClient = {
+  getDefinitionForWorkflowRun: async ({definitionId}) => {
+    const definition = await mockGetDefinitionById(definitionId);
+    return {
+      definition:
+        definition === undefined
+          ? null
+          : {
+              id: definition.id,
+              projectId: definition.projectId,
+              name: definition.name,
+              model: createWorkflowModelSnapshot(definition.model),
+              sourceSnapshot: definition.sourceSnapshot,
+            },
+    };
+  },
+};
 
 function buildDefinition(overrides?: Partial<WorkflowDefinition>): WorkflowDefinition {
   const model = workflowModel();
@@ -84,13 +86,15 @@ function manualPayload(): TriggerPayload {
 describe('runWorkflow', () => {
   let workspaceId: string;
   let projectId: string;
+  const agent: AgentInterModuleClient = {
+    resolveAgentConfig: mockResolveAgentConfig,
+    resolveRuntimeCredentials: vi.fn(),
+  };
 
   beforeEach(() => {
     workspaceId = crypto.randomUUID();
     projectId = crypto.randomUUID();
-    mockCreateWorkspaceAgentDefaultsResolver.mockClear();
-    mockCreateWorkspaceAgentDefaultsResolver.mockResolvedValue(mockWorkspaceAgentDefaultsResolver);
-    mockWorkspaceAgentDefaultsResolver.mockClear();
+    mockResolveAgentConfig.mockClear();
   });
 
   test('creates a run from a valid definition with the provided manual trigger payload', async () => {
@@ -98,11 +102,12 @@ describe('runWorkflow', () => {
     mockGetDefinitionById.mockResolvedValue(definition);
     const triggerPayload = manualPayload();
 
-    const run = await runWorkflow({
+    const run = await runWorkflow(definitions, {
       workspaceId,
       projectId,
       definitionId: definition.id,
       triggerPayload,
+      agent,
     });
 
     expect(run.id).toBeDefined();
@@ -114,7 +119,7 @@ describe('runWorkflow', () => {
     expect(run.triggerSource).toBe('manual');
     expect(run.triggerEvent).toBe('fire');
     expect(run.triggerPayload).toEqual(triggerPayload);
-    expect(mockCreateWorkspaceAgentDefaultsResolver).not.toHaveBeenCalled();
+    expect(mockResolveAgentConfig).not.toHaveBeenCalled();
   });
 
   test('builds the workspace agent resolver only when the definition has an agent step', async () => {
@@ -126,21 +131,16 @@ describe('runWorkflow', () => {
     const definition = buildDefinition({projectId, model});
     mockGetDefinitionById.mockResolvedValue(definition);
 
-    const run = await runWorkflow({
+    const run = await runWorkflow(definitions, {
       workspaceId,
       projectId,
       definitionId: definition.id,
       triggerPayload: manualPayload(),
+      agent,
     });
 
     expect(run.id).toBeDefined();
-    expect(mockCreateWorkspaceAgentDefaultsResolver).toHaveBeenCalledWith(workspaceId);
-    expect(mockWorkspaceAgentDefaultsResolver).toHaveBeenCalledWith({
-      harness: undefined,
-      provider: undefined,
-      model: undefined,
-      thinking: undefined,
-    });
+    expect(mockResolveAgentConfig).toHaveBeenCalledWith({workspaceId, config: {}});
   });
 
   test('persists an integration trigger payload intact', async () => {
@@ -154,11 +154,12 @@ describe('runWorkflow', () => {
       data: {ref: 'main', headCommitSha: 'abc', externalRepositoryId: 'github:1'},
     };
 
-    const run = await runWorkflow({
+    const run = await runWorkflow(definitions, {
       workspaceId,
       projectId,
       definitionId: definition.id,
       triggerPayload,
+      agent,
     });
 
     expect(run.triggerProvider).toBe('github');
@@ -172,11 +173,12 @@ describe('runWorkflow', () => {
     const definition = buildDefinition({projectId, sourceSnapshot});
     mockGetDefinitionById.mockResolvedValue(definition);
 
-    const run = await runWorkflow({
+    const run = await runWorkflow(definitions, {
       workspaceId,
       projectId,
       definitionId: definition.id,
       triggerPayload: manualPayload(),
+      agent,
     });
 
     expect(run.sourceSnapshot).toEqual(sourceSnapshot);
@@ -188,11 +190,12 @@ describe('runWorkflow', () => {
     const unknownId = crypto.randomUUID();
 
     await expect(
-      runWorkflow({
+      runWorkflow(definitions, {
         workspaceId,
         projectId,
         definitionId: unknownId,
         triggerPayload: manualPayload(),
+        agent,
       }),
     ).rejects.toThrow(DefinitionNotFoundError);
   });
@@ -203,11 +206,12 @@ describe('runWorkflow', () => {
     mockGetDefinitionById.mockResolvedValue(definition);
 
     await expect(
-      runWorkflow({
+      runWorkflow(definitions, {
         workspaceId,
         projectId,
         definitionId: definition.id,
         triggerPayload: manualPayload(),
+        agent,
       }),
     ).rejects.toThrow(ProjectMismatchError);
   });
@@ -216,11 +220,12 @@ describe('runWorkflow', () => {
     const definition = buildDefinition({projectId});
     mockGetDefinitionById.mockResolvedValue(definition);
 
-    const run = await runWorkflow({
+    const run = await runWorkflow(definitions, {
       workspaceId,
       projectId,
       definitionId: definition.id,
       triggerPayload: manualPayload(),
+      agent,
       inputs: {env: 'staging'},
     });
 

package/src/core/run-workflow.ts

@@ -1,7 +1,11 @@
-import {catalogDefaultAgentResolver} from '@shipfox/api-agent/core/resolve-agent-config';
-import {createWorkspaceAgentDefaultsResolver} from '@shipfox/api-agent/core/workspace-agent-defaults-resolver';
-import {getDefinitionById} from '@shipfox/api-definitions';
+import type {AgentInterModuleClient} from '@shipfox/api-agent-dto/inter-module';
+import {workflowModelFromSnapshot} from '@shipfox/api-definitions-dto';
+import type {DefinitionsInterModuleClient} from '@shipfox/api-definitions-dto/inter-module';
+import type {IntegrationsModuleClient} from '@shipfox/api-integration-core-dto';
+import type {ProjectsModuleClient} from '@shipfox/api-projects-dto';
+import type {SecretsInterModuleClient} from '@shipfox/api-secrets-dto/inter-module';
 import {createWorkflowRun} from '#db/workflow-runs.js';
+import {createAgentDefaultsResolver} from './agent-defaults.js';
 import type {TriggerPayload, WorkflowRun} from './entities/workflow-run.js';
 import {DefinitionNotFoundError, ProjectMismatchError} from './errors.js';
 import {modelHasAgentStep} from './step-config/materialize-workflow-model.js';
@@ -13,29 +17,42 @@ export interface RunWorkflowParams {
   triggerPayload: TriggerPayload;
   inputs?: Record<string, unknown> | undefined;
   triggerIdempotencyKey?: string | undefined;
+  integrations?: IntegrationsModuleClient | undefined;
+  projects?: ProjectsModuleClient | undefined;
 }
 
-export async function runWorkflow(params: RunWorkflowParams): Promise<WorkflowRun> {
-  const definition = await getDefinitionById(params.definitionId);
+export async function runWorkflow(
+  definitions: DefinitionsInterModuleClient,
+  params: RunWorkflowParams & {agent: AgentInterModuleClient},
+  options: {secrets?: Pick<SecretsInterModuleClient, 'getVariablesByNamespace'>} = {},
+): Promise<WorkflowRun> {
+  const {definition} = await definitions.getDefinitionForWorkflowRun({
+    definitionId: params.definitionId,
+  });
   if (!definition) throw new DefinitionNotFoundError(params.definitionId);
 
   if (definition.projectId !== params.projectId) {
     throw new ProjectMismatchError(definition.projectId, params.projectId);
   }
-  const resolveAgentDefaults = modelHasAgentStep(definition.model)
-    ? await createWorkspaceAgentDefaultsResolver(params.workspaceId)
-    : catalogDefaultAgentResolver;
+  const model = workflowModelFromSnapshot(definition.model);
+  const resolveAgentDefaults = createAgentDefaultsResolver(
+    params.agent,
+    modelHasAgentStep(model) ? params.workspaceId : null,
+  );
 
   return createWorkflowRun({
     workspaceId: params.workspaceId,
     projectId: params.projectId,
     definitionId: definition.id,
     name: definition.name,
-    model: definition.model,
+    model,
     triggerPayload: params.triggerPayload,
     inputs: params.inputs,
     sourceSnapshot: definition.sourceSnapshot,
     triggerIdempotencyKey: params.triggerIdempotencyKey,
     resolveAgentDefaults,
+    secrets: options.secrets,
+    integrations: params.integrations,
+    projects: params.projects,
   });
 }

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

@@ -1,10 +1,3 @@
-import {
-  InvalidAgentModelError,
-  UnsupportedHarnessProviderError,
-  UnsupportedHarnessThinkingError,
-  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,
@@ -14,8 +7,11 @@ import {
   type AgentThinking,
   type MaterializedAgentIntegrationConfigDto,
 } from '@shipfox/api-agent-dto';
-import type {WorkflowModel} from '@shipfox/api-definitions';
+import {agentInterModuleContract} from '@shipfox/api-agent-dto/inter-module';
+import type {WorkflowModel} from '@shipfox/api-definitions-dto';
 import type {ResolvedField, SiteResolvedField} from '@shipfox/expression';
+import {isInterModuleKnownError} from '@shipfox/inter-module';
+import type {AgentDefaultsResolver, ResolvedAgentDefaults} from '#core/agent-defaults.js';
 import {
   type AgentToolMaterializationContext,
   type AgentToolMaterializationSnapshot,
@@ -55,7 +51,7 @@ export interface ResolveAgentStepConfigParams {
   readonly context: WorkflowEvaluationContext;
   readonly mode: StepConfigMode;
   readonly definitionId: string;
-  readonly resolveAgentDefaults: AgentDefaultsResolver;
+  readonly resolveAgentDefaults?: AgentDefaultsResolver | undefined;
   readonly agentToolContext?: AgentToolMaterializationContext | undefined;
   readonly agentToolSnapshot?: AgentToolMaterializationSnapshot | null | undefined;
 }
@@ -68,7 +64,9 @@ export interface AgentStepConfig {
   readonly hasTemplates: boolean;
 }
 
-export function resolveAgentStepConfig(params: ResolveAgentStepConfigParams): AgentStepConfig {
+export async function resolveAgentStepConfig(
+  params: ResolveAgentStepConfigParams,
+): Promise<AgentStepConfig> {
   const fields = resolveAgentFields(params);
   const usesAuthoredMode = params.mode === 'authored';
 
@@ -78,17 +76,17 @@ export function resolveAgentStepConfig(params: ResolveAgentStepConfigParams): Ag
     fields.model?.kind === 'residual' || fields.provider?.kind === 'residual';
   if (hasDeferredModelOrProvider) return deferredAgentStepConfig(params, fields);
 
-  return agentStepConfigWithDefaults(params.step, params, fields);
+  return await agentStepConfigWithDefaults(params.step, params, fields);
 }
 
-export function completeAgentConfig(params: {
+export async function completeAgentConfig(params: {
   readonly config: Record<string, unknown>;
   readonly plan: StepConfigDispatchPlan;
   readonly context: WorkflowEvaluationContext;
-  readonly resolveAgentDefaults: AgentDefaultsResolver;
+  readonly resolveAgentDefaults?: AgentDefaultsResolver | undefined;
   readonly definitionId: string;
   readonly trace: PersistedEvaluationTraceEntry[];
-}): void {
+}): Promise<void> {
   const agent = params.plan.agent;
   if (agent === undefined) return;
 
@@ -117,7 +115,7 @@ export function completeAgentConfig(params: {
           params,
         });
 
-  const defaults = completeAgentDefaults({
+  const defaults = await completeAgentDefaults({
     harness: agent.harness ?? readConfigHarness(params.config),
     provider,
     model,
@@ -159,16 +157,18 @@ function completeAgentField(args: {
   return resolved.value;
 }
 
-export function completeAgentDefaults(params: {
+export async function completeAgentDefaults(params: {
   readonly harness: WorkflowModelAgentStep['harness'] | undefined;
   readonly provider: string | undefined;
   readonly model: string | undefined;
   readonly thinking: AgentThinking | undefined;
-  readonly resolveAgentDefaults: AgentDefaultsResolver;
+  readonly resolveAgentDefaults?: AgentDefaultsResolver | undefined;
   readonly definitionId: string;
-}): ReturnType<AgentDefaultsResolver> {
+}): Promise<ResolvedAgentDefaults> {
+  if (!params.resolveAgentDefaults) throw new Error('Agent defaults resolver is required');
+
   try {
-    return params.resolveAgentDefaults({
+    return await params.resolveAgentDefaults({
       harness: params.harness,
       provider: params.provider,
       model: params.model,
@@ -176,10 +176,8 @@ export function completeAgentDefaults(params: {
     });
   } catch (error) {
     if (
-      error instanceof UnsupportedModelProviderError ||
-      error instanceof UnsupportedHarnessProviderError ||
-      error instanceof UnsupportedHarnessThinkingError ||
-      error instanceof InvalidAgentModelError
+      isInterModuleKnownError(agentInterModuleContract.methods.resolveAgentConfig, error) &&
+      error.code === 'agent-config-invalid'
     ) {
       throw new AgentConfigUnresolvableError(params.definitionId, {cause: error});
     }
@@ -273,16 +271,16 @@ function deferredAgentStepConfig(
   };
 }
 
-function agentStepConfigWithDefaults(
+async function agentStepConfigWithDefaults(
   step: WorkflowModelAgentStep,
   params: ResolveAgentStepConfigParams,
   fields: AgentFieldResolutions,
-): AgentStepConfig {
+): Promise<AgentStepConfig> {
   const providerValue = frozenFieldValue(fields.provider);
   const modelValue = frozenFieldValue(fields.model);
   const promptIsDeferred = fields.prompt.kind === 'residual';
 
-  const resolved = completeAgentDefaults({
+  const resolved = await completeAgentDefaults({
     harness: step.harness,
     provider: providerValue,
     model: modelValue,