@shipfox/api-workflows 15.0.0 → 16.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows",
   "license": "MIT",
-  "version": "15.0.0",
+  "version": "16.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -25,18 +25,18 @@
     "zod": "^4.4.3",
     "@shipfox/api-auth-context": "15.0.0",
     "@shipfox/api-auth-dto": "15.0.0",
-    "@shipfox/api-agent-dto": "15.0.0",
+    "@shipfox/api-agent-dto": "16.1.0",
     "@shipfox/annotations-dto": "12.3.0",
-    "@shipfox/api-definitions-dto": "15.0.0",
+    "@shipfox/api-definitions-dto": "16.1.0",
     "@shipfox/api-projects-dto": "15.0.0",
-    "@shipfox/api-integration-core-dto": "15.0.0",
-    "@shipfox/api-runners-dto": "14.0.0",
+    "@shipfox/api-integration-core-dto": "16.0.0",
+    "@shipfox/api-runners-dto": "16.0.0",
     "@shipfox/api-secrets-dto": "12.0.0",
-    "@shipfox/api-workflows-dto": "15.0.0",
+    "@shipfox/api-workflows-dto": "16.1.0",
     "@shipfox/api-workspaces-dto": "15.0.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",
-    "@shipfox/expression": "2.3.0",
+    "@shipfox/expression": "2.4.0",
     "@shipfox/node-drizzle": "0.3.5",
     "@shipfox/node-error-monitoring": "0.3.0",
     "@shipfox/node-fastify": "0.4.3",
@@ -46,7 +46,7 @@
     "@shipfox/node-postgres": "0.5.0",
     "@shipfox/node-temporal": "0.4.6",
     "@shipfox/runner-labels": "0.2.0",
-    "@shipfox/workflow-document": "3.2.0"
+    "@shipfox/workflow-document": "3.3.0"
   },
   "imports": {
     "#*": "./dist/*"

package/src/core/agent-tools.test.ts

@@ -0,0 +1,85 @@
+import {workflowModel} from '#test/index.js';
+import {loadAgentToolMaterializationContext} from './agent-tools.js';
+import {AgentIntegrationMaterializationError} from './errors.js';
+
+describe('loadAgentToolMaterializationContext', () => {
+  const workspaceId = crypto.randomUUID();
+  const projectId = crypto.randomUUID();
+
+  test('returns undefined for a model with only run steps', async () => {
+    const model = workflowModel({
+      name: 'Plain',
+      runner: 'ubuntu-latest',
+    });
+
+    await expect(
+      loadAgentToolMaterializationContext({model, workspaceId, projectId}),
+    ).resolves.toBeUndefined();
+  });
+
+  test('returns undefined for a model with only checkout steps', async () => {
+    const model = workflowModel({
+      name: 'Checkout',
+      runner: 'ubuntu-latest',
+      jobs: {
+        build: {
+          steps: [
+            {
+              checkout: {
+                repository: 'acme/platform',
+                fetchDepth: 1,
+                permissions: {contents: 'read'},
+                persistCredentials: true,
+              },
+            },
+          ],
+        },
+      },
+    });
+
+    await expect(
+      loadAgentToolMaterializationContext({model, workspaceId, projectId}),
+    ).resolves.toBeUndefined();
+  });
+
+  test('returns undefined for agent steps without integrations', async () => {
+    const model = workflowModel({
+      name: 'Agent',
+      runner: 'ubuntu-latest',
+      jobs: {
+        build: {
+          steps: [{prompt: 'Do the thing'}],
+        },
+      },
+    });
+
+    await expect(
+      loadAgentToolMaterializationContext({model, workspaceId, projectId}),
+    ).resolves.toBeUndefined();
+  });
+
+  test('does not short-circuit for a tool-step-only model', async () => {
+    const model = workflowModel({
+      name: 'Tools',
+      runner: 'ubuntu-latest',
+      jobs: {
+        build: {
+          steps: [
+            {
+              tool: 'get_issue',
+              connection: 'linear-main',
+              with: {id: 'ENG-1'},
+            },
+          ],
+        },
+      },
+    });
+
+    // A tool step is an integration tool reference, so the loader must not
+    // return early: with project access missing it reports the materialization
+    // setup failure instead of silently skipping tool-step runs.
+    await expect(
+      loadAgentToolMaterializationContext({model, workspaceId, projectId}),
+    ).rejects.toThrow(AgentIntegrationMaterializationError);
+  });
+});

package/src/core/agent-tools.ts

@@ -61,7 +61,7 @@ export async function loadAgentToolMaterializationContext(params: {
   readonly projects?: ProjectsModuleClient | undefined;
   readonly jobs?: readonly WorkflowModelJob[] | undefined;
 }): Promise<AgentToolMaterializationContext | undefined> {
-  if (!modelHasAgentStepIntegrations(params.model, params.jobs)) return undefined;
+  if (!hasIntegrationToolReferences(params.model, params.jobs)) return undefined;
 
   if (params.projects === undefined) {
     throw new AgentIntegrationMaterializationError('Project access is not configured');
@@ -410,12 +410,20 @@ function isPermissionScope(
   );
 }
 
-function modelHasAgentStepIntegrations(
+/**
+ * Model-level twin of `hasIntegrationToolReferences` in
+ * `libs/api/definitions/src/core/has-integration-tool-references.ts`, which
+ * runs the same criterion over the authored `WorkflowDocument` at sync time.
+ * Keep both in sync.
+ */
+function hasIntegrationToolReferences(
   model: WorkflowModel | null,
   jobs: readonly WorkflowModelJob[] | undefined,
 ): boolean {
   if (model === null) return false;
   return (jobs ?? model.jobs).some((job) =>
-    job.steps.some((step) => step.kind === 'agent' && step.integrations !== undefined),
+    job.steps.some(
+      (step) => step.kind === 'tool' || (step.kind === 'agent' && step.integrations !== undefined),
+    ),
   );
 }

package/src/core/entities/step.ts

@@ -13,7 +13,7 @@ import type {InterpolationUnresolvableField} from '../errors.js';
 
 export type StepStatus = 'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'skipped';
 
-export const STEP_TYPES = ['setup', 'run', 'agent', 'checkout'] as const;
+export const STEP_TYPES = ['setup', 'run', 'agent', 'checkout', 'tool'] as const;
 
 export type StepType = (typeof STEP_TYPES)[number];
 

package/src/core/errors.ts

@@ -84,6 +84,8 @@ export type InterpolationUnresolvableField =
   | 'step.name'
   | 'step.working_directory'
   | 'step.feedback'
+  | 'tool.with'
+  | 'tool.outputs'
   | 'checkout.project'
   | 'checkout.connection'
   | 'checkout.repository'

package/src/core/job-execution.test.ts

@@ -1195,6 +1195,7 @@ describe('step attempts', () => {
         attempt: 1,
         status: 'failed',
         logOutcome: 'abandoned',
+        stepAttemptId: expect.any(String),
       },
     ]);
   });

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

@@ -62,6 +62,8 @@ describe('runWorkflow', () => {
     getValidationCatalog: vi.fn().mockResolvedValue(agentValidationCatalog),
     resolveAgentConfig: mockResolveAgentConfig,
     resolveRuntimeCredentials: vi.fn(),
+    claimSession: vi.fn(),
+    carryOverSessions: vi.fn(),
   };
 
   beforeEach(() => {
@@ -256,6 +258,8 @@ describe('runDevWorkflow', () => {
     getValidationCatalog: vi.fn().mockResolvedValue(agentValidationCatalog),
     resolveAgentConfig: mockResolveAgentConfig,
     resolveRuntimeCredentials: vi.fn(),
+    claimSession: vi.fn(),
+    carryOverSessions: vi.fn(),
   };
 
   beforeEach(() => {

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

@@ -168,6 +168,8 @@ function stepDisplayName(step: WorkflowModelStep): string {
         : `${step.model} · ${firstLine(step.prompt)}`;
     case 'checkout':
       return 'Checkout';
+    case 'tool':
+      return step.tool.method === undefined ? step.tool.id : `${step.tool.id}.${step.tool.method}`;
     default:
       return assertNever(step);
   }

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

@@ -154,7 +154,10 @@ function resolveWorkingDirectoryConfig(
   params: Omit<BuildStepConfigParams, 'context'> & {readonly context: WorkflowEvaluationContext},
 ): WorkingDirectoryConfig {
   const value = params.step.workingDirectory;
-  const template = params.step.templates?.workingDirectory;
+  // Tool steps have no working tree, so they never carry a working-directory
+  // template; the union narrows the remaining kinds to those that can.
+  const template =
+    params.step.kind === 'tool' ? undefined : params.step.templates?.workingDirectory;
   if (value === undefined) {
     return {
       config: {},

package/src/db/index.ts

@@ -82,6 +82,7 @@ export {
   getWorkflowRunById,
   getWorkflowRunDetail,
   listRunAttempts,
+  listStepAttemptIdsByJobId,
   listWorkflowRunJobSummaries,
   listWorkflowRuns,
   listWorkflowRunsByProject,

package/src/db/workflow-runs/outbox.ts

@@ -99,6 +99,7 @@ export async function writeJobStepsSettledOutbox(
 export async function writeStepAttemptTerminatedOutbox(
   tx: Tx,
   params: {
+    stepAttemptId: string;
     stepId: string;
     attempt: number;
     status: 'succeeded' | 'failed' | 'cancelled';
@@ -119,6 +120,7 @@ export async function writeStepAttemptTerminatedOutbox(
       attempt: params.attempt,
       status: params.status,
       logOutcome: params.logOutcome,
+      stepAttemptId: params.stepAttemptId,
     },
   });
 }

package/src/db/workflow-runs/run-create.test.ts

@@ -1191,6 +1191,47 @@ describe('workflow run queries', () => {
           }),
         expected: {field: 'step.working_directory', source: 'vars.REQUIRED'},
       },
+      {
+        field: 'tool.with',
+        model: () =>
+          workflowModel({
+            name: 'Missing tool with var',
+            runner: 'ubuntu-latest',
+            jobs: {
+              build: {
+                steps: [
+                  {
+                    tool: 'get_issue',
+                    connection: 'linear-main',
+                    with: {id: template('vars.REQUIRED')},
+                  },
+                ],
+              },
+            },
+          }),
+        expected: {field: 'tool.with', source: 'vars.REQUIRED'},
+      },
+      {
+        field: 'tool.outputs',
+        model: () =>
+          workflowModel({
+            name: 'Missing tool output var',
+            runner: 'ubuntu-latest',
+            jobs: {
+              build: {
+                steps: [
+                  {
+                    tool: 'get_issue',
+                    connection: 'linear-main',
+                    with: {id: 'ENG-1'},
+                    outputs: {sev: template('vars.REQUIRED')},
+                  },
+                ],
+              },
+            },
+          }),
+        expected: {field: 'tool.outputs', envKey: 'sev', source: 'vars.REQUIRED'},
+      },
       {
         field: 'checkout.repository',
         model: () =>

package/src/db/workflow-runs/run-create.ts

@@ -1,6 +1,7 @@
 import {
   createWorkflowModelSnapshot,
   WORKFLOW_MODEL_CHECKOUT_TARGET_FIELDS,
+  type WorkflowJsonTemplateTree,
   type WorkflowModel,
 } from '@shipfox/api-definitions-dto';
 import type {IntegrationsModuleClient} from '@shipfox/api-integration-core-dto/inter-module';
@@ -455,9 +456,13 @@ function referencedVariables(
 
     for (const step of job.steps) {
       collectFieldVariableReferences(step.templates?.name, references, {field: 'step.name'});
-      collectFieldVariableReferences(step.templates?.workingDirectory, references, {
-        field: 'step.working_directory',
-      });
+      collectFieldVariableReferences(
+        step.kind === 'tool' ? undefined : step.templates?.workingDirectory,
+        references,
+        {
+          field: 'step.working_directory',
+        },
+      );
       if (step.kind === 'run') {
         collectFieldVariableReferences(step.templates?.command, references, {field: 'run'});
         collectTemplateVariableReferences(step.templates?.env, references);
@@ -467,6 +472,16 @@ function referencedVariables(
         collectFieldVariableReferences(step.templates?.provider, references, {
           field: 'agent.provider',
         });
+      } else if (step.kind === 'tool') {
+        collectTemplateTreeVariableReferences(step.templates?.with, references, {
+          field: 'tool.with',
+        });
+        for (const [key, expression] of Object.entries(step.outputMappings ?? {})) {
+          collectExpressionVariableReferences(expression, references, {
+            field: 'tool.outputs',
+            envKey: key,
+          });
+        }
       } else if (step.kind === 'checkout') {
         for (const [key, field] of WORKFLOW_MODEL_CHECKOUT_TARGET_FIELDS) {
           collectFieldVariableReferences(step.checkout.templates?.[key], references, {field});
@@ -534,6 +549,69 @@ function collectFieldVariableReferences(
   }
 }
 
+/**
+ * Collect `vars.*` references from a tool step's `with` template tree: a
+ * `WorkflowJsonTemplateTree` mirrors the authored `with` payload with every
+ * interpolated string leaf replaced by its parsed template, so walk it like
+ * the authored structure and collect from each leaf template.
+ */
+function collectTemplateTreeVariableReferences(
+  tree: WorkflowJsonTemplateTree | undefined,
+  references: ReferencedVariable[],
+  source: {
+    readonly field: InterpolationUnresolvableError['field'];
+    readonly envKey?: string | undefined;
+  },
+): void {
+  if (tree === undefined) return;
+
+  if (Array.isArray(tree)) {
+    // A field template is itself an array of segments; a `with` list is an
+    // array of child trees. Segments carry a `kind`, so distinguish the two.
+    if (tree.every((element) => isFieldTemplateSegment(element))) {
+      collectFieldVariableReferences(tree, references, source);
+      return;
+    }
+    for (const child of tree) collectTemplateTreeVariableReferences(child, references, source);
+    return;
+  }
+
+  if (typeof tree === 'object') {
+    for (const child of Object.values(tree)) {
+      collectTemplateTreeVariableReferences(child, references, source);
+    }
+  }
+}
+
+function isFieldTemplateSegment(value: unknown): value is ResolvedFieldSegment {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    ((value as {kind?: unknown}).kind === 'literal' ||
+      (value as {kind?: unknown}).kind === 'deferred')
+  );
+}
+
+function collectExpressionVariableReferences(
+  expression: WorkflowExpression,
+  references: ReferencedVariable[],
+  source: {
+    readonly field: InterpolationUnresolvableError['field'];
+    readonly envKey?: string | undefined;
+  },
+): void {
+  const keyAccess = analyzeContextKeyAccess(expression);
+  for (const reference of keyAccess.references) {
+    if (reference.root !== 'vars') continue;
+    references.push({
+      key: reference.key,
+      field: source.field,
+      source: expression.source,
+      envKey: source.envKey,
+    });
+  }
+}
+
 function logTemplateDiagnostics(params: {
   readonly workflowRunId: string;
   readonly diagnostics: readonly (WorkflowStepTemplateDiagnostic & {

package/src/db/workflow-runs/steps.ts

@@ -197,6 +197,7 @@ export async function bulkUpdateStepStatuses(
       ),
     )
     .returning({
+      id: stepAttempts.id,
       stepId: stepAttempts.stepId,
       attempt: stepAttempts.attempt,
       logOutcome: stepAttempts.logOutcome,
@@ -205,6 +206,7 @@ export async function bulkUpdateStepStatuses(
   if (finalizedAttempts.length > 0) {
     for (const attempt of finalizedAttempts) {
       await writeStepAttemptTerminatedOutbox(tx, {
+        stepAttemptId: attempt.id,
         stepId: attempt.stepId,
         attempt: attempt.attempt,
         status: params.status,
@@ -459,6 +461,7 @@ export async function finishStepAttempt(params: FinishStepAttemptParams, tx: Tx)
       ),
     )
     .returning({
+      id: stepAttempts.id,
       stepId: stepAttempts.stepId,
       attempt: stepAttempts.attempt,
       logOutcome: stepAttempts.logOutcome,
@@ -468,6 +471,7 @@ export async function finishStepAttempt(params: FinishStepAttemptParams, tx: Tx)
   if (!row) return;
 
   await writeStepAttemptTerminatedOutbox(tx, {
+    stepAttemptId: row.id,
     stepId: row.stepId,
     attempt: row.attempt,
     status: params.status,
@@ -531,6 +535,21 @@ export async function getStepAttempts(jobId: string): Promise<StepAttempt[]> {
   return rows.map((row) => toStepAttempt(row.stepAttempt));
 }
 
+/**
+ * Lists only the step attempt ids of a job, without materializing the full
+ * attempt entities. The session release sweep only needs the ids to release
+ * claims, so this keeps the per-job-terminated query off a full-row projection.
+ */
+export async function listStepAttemptIdsByJobId(jobId: string): Promise<string[]> {
+  const rows = await db()
+    .select({id: stepAttempts.id})
+    .from(stepAttempts)
+    .innerJoin(steps, eq(stepAttempts.stepId, steps.id))
+    .innerJoin(jobExecutions, eq(steps.jobExecutionId, jobExecutions.id))
+    .where(eq(jobExecutions.jobId, jobId));
+  return rows.map((row) => row.id);
+}
+
 export async function getStepAttemptsByJobIds(jobIds: string[]): Promise<StepAttempt[]> {
   if (jobIds.length === 0) return [];
   const rows = await db()

package/src/db/workflow-runs.ts

@@ -117,6 +117,7 @@ export {
   getStepsByJobExecutionIdForUpdate,
   getStepsByJobId,
   insertRunningStepAttempt,
+  listStepAttemptIdsByJobId,
   markStepRunning,
   markStepSkipped,
   rewindStepsToPending,

package/src/presentation/inter-module.test.ts

@@ -23,6 +23,7 @@ const mocks = vi.hoisted(() => ({
   getJobScope: vi.fn(),
   getStepById: vi.fn(),
   getStepByIdForJobExecution: vi.fn(),
+  listStepAttemptIdsByJobId: vi.fn(),
 }));
 
 vi.mock('#db/index.js', () => mocks);
@@ -47,12 +48,37 @@ const input = {
 describe('Workflows inter-module presentation', () => {
   beforeEach(() => {
     mocks.getJobScope.mockReset();
+    mocks.listStepAttemptIdsByJobId.mockReset();
     mocks.getStepById.mockReset();
     mocks.getStepByIdForJobExecution.mockReset();
     mocks.deliverEventToListener.mockReset();
     mocks.deliverEventToListener.mockResolvedValue({buffered: true, skipped: false});
   });
 
+  it('returns the step attempt ids of a job for the session release sweep', async () => {
+    const stepAttemptId = '00000000-0000-4000-8000-000000000010';
+    mocks.listStepAttemptIdsByJobId.mockResolvedValue([stepAttemptId]);
+    const presentation = createWorkflowsInterModulePresentation({
+      agent: {} as never,
+      definitions: {} as never,
+      integrations: {} as never,
+      projects: {} as never,
+      runners: {} as never,
+      secrets: {} as never,
+      workspaces: {getWorkspaceOperatingState: vi.fn()} as never,
+    });
+
+    const result = await presentation.handlers.listJobStepAttempts(
+      {jobId: '00000000-0000-4000-8000-000000000006'},
+      {signal: new AbortController().signal},
+    );
+
+    expect(mocks.listStepAttemptIdsByJobId).toHaveBeenCalledWith(
+      '00000000-0000-4000-8000-000000000006',
+    );
+    expect(result).toEqual({stepAttemptIds: [stepAttemptId]});
+  });
+
   it('returns only the resolved harness for Logs', async () => {
     mocks.getStepById.mockResolvedValue({config: {harness: 'claude'}});
     const presentation = createWorkflowsInterModulePresentation({

package/src/presentation/inter-module.ts

@@ -32,7 +32,12 @@ import {
 } from '#core/index.js';
 import {resolveWorkflowRunTriggerReference} from '#core/resolve-trigger-reference.js';
 import {assertWorkspaceAdmitsNewJobs} from '#core/workspace-admission.js';
-import {getJobScope, getStepById, getStepByIdForJobExecution} from '#db/index.js';
+import {
+  getJobScope,
+  getStepById,
+  getStepByIdForJobExecution,
+  listStepAttemptIdsByJobId,
+} from '#db/index.js';
 import {deliverEventToListener} from '#db/job-listener-events.js';
 
 type WorkspaceAdmissionKnownError = InterModuleKnownErrorFor<
@@ -151,6 +156,9 @@ export function createWorkflowsInterModulePresentation(params: {
       const parsed = harnessSchema.safeParse(step?.config.harness);
       return {harness: parsed.success ? parsed.data : DEFAULT_HARNESS};
     },
+    listJobStepAttempts: async ({jobId}) => {
+      return {stepAttemptIds: await listStepAttemptIdsByJobId(jobId)};
+    },
     getLeasedAgentToolContext: async (input) => {
       const method = workflowsInterModuleContract.methods.getLeasedAgentToolContext;
       const {active: leaseIsActive} = await params.runners.getLeaseState({

package/src/presentation/routes/agent-runtime-config.test.ts

@@ -54,6 +54,8 @@ const agentTestClient: AgentInterModuleClient = {
   getValidationCatalog: vi.fn(),
   resolveAgentConfig: vi.fn(),
   resolveRuntimeCredentials,
+  claimSession: vi.fn(),
+  carryOverSessions: vi.fn(),
 };
 
 describe('GET /runs/jobs/current/agent-runtime-config', () => {

package/test/factories/workflow-model.ts

@@ -1,4 +1,9 @@
-import {DEFAULT_JOB_CHECKOUT, type WorkflowModel} from '@shipfox/api-definitions-dto';
+import {
+  DEFAULT_JOB_CHECKOUT,
+  type WorkflowJsonTemplateTree,
+  type WorkflowJsonValue,
+  type WorkflowModel,
+} from '@shipfox/api-definitions-dto';
 import {
   createWorkflowExpression,
   parseWorkflowTemplate,
@@ -41,7 +46,14 @@ interface TestCheckoutStep extends TestWorkflowStepBase {
   readonly checkout: Checkout;
 }
 
-type TestWorkflowStep = TestRunStep | TestAgentStep | TestCheckoutStep;
+interface TestToolStep extends TestWorkflowStepBase {
+  readonly tool: string;
+  readonly connection?: string | undefined;
+  readonly with?: WorkflowJsonValue | undefined;
+  readonly outputs?: Readonly<Record<string, string>> | undefined;
+}
+
+type TestWorkflowStep = TestRunStep | TestAgentStep | TestCheckoutStep | TestToolStep;
 
 const DEFAULT_RUNNER_LABELS = ['ubuntu-latest'] as const;
 
@@ -171,6 +183,18 @@ function normalizeStep(step: TestWorkflowStep, jobId: string, stepIndex: number)
     };
   }
 
+  if ('tool' in step) {
+    return {
+      ...base,
+      kind: 'tool',
+      tool: splitToolId(step.tool),
+      ...(step.connection === undefined ? {} : {connection: step.connection}),
+      ...(step.with === undefined ? {} : {with: step.with}),
+      ...(step.outputs === undefined ? {} : {outputMappings: outputMappings(step.outputs)}),
+      ...optionalToolTemplates(step),
+    };
+  }
+
   return {
     ...base,
     kind: 'checkout',
@@ -274,6 +298,54 @@ function optionalAgentTemplates(step: TestAgentStep) {
   };
 }
 
+function optionalToolTemplates(step: TestToolStep) {
+  const withTree = step.with === undefined ? undefined : withTemplateTree(step.with);
+  const name = step.name === undefined ? undefined : fieldTemplate('step.name', step.name);
+  if (withTree === undefined && name === undefined) return {};
+  return {
+    templates: {
+      ...(withTree === undefined ? {} : {with: withTree}),
+      ...(name === undefined ? {} : {name}),
+    },
+  };
+}
+
+function withTemplateTree(value: WorkflowJsonValue): WorkflowJsonTemplateTree | undefined {
+  if (Array.isArray(value)) {
+    const trees = value.map((child) => withTemplateTree(child));
+    return trees.every((tree) => tree === undefined) ? undefined : trees;
+  }
+  if (typeof value === 'object' && value !== null) {
+    const entries = Object.entries(value).flatMap(([key, child]) => {
+      const tree = withTemplateTree(child);
+      return tree === undefined ? [] : [[key, tree] as const];
+    });
+    return entries.length === 0 ? undefined : Object.fromEntries(entries);
+  }
+  if (typeof value !== 'string') return undefined;
+  return fieldTemplate('tool.with', value);
+}
+
+function outputMappings(outputs: Readonly<Record<string, string>>) {
+  return Object.fromEntries(
+    Object.entries(outputs).map(([key, source]) => {
+      const template = fieldTemplate('tool.outputs', source);
+      if (template === undefined || template.length !== 1 || template[0]?.kind !== 'deferred') {
+        throw new Error(
+          `Expected test tool output mapping to be exactly one expression for ${key}: ${source}`,
+        );
+      }
+      return [key, template[0].expression];
+    }),
+  );
+}
+
+function splitToolId(source: string): {readonly id: string; readonly method?: string} {
+  const dotIndex = source.indexOf('.');
+  if (dotIndex < 1 || dotIndex === source.length - 1) return {id: source};
+  return {id: source.slice(0, dotIndex), method: source.slice(dotIndex + 1)};
+}
+
 function envTemplates(env: WorkflowModel['env'] | undefined): WorkflowEnvTemplates | undefined {
   if (env === undefined) return undefined;
 

package/test/fixtures/agent-inter-module.ts

@@ -46,6 +46,8 @@ export const agentTestClient: AgentInterModuleClient = {
       credentials: {api_key: 'test-agent-credential'},
     });
   },
+  claimSession: vi.fn(),
+  carryOverSessions: vi.fn(),
 };
 
 export const resolveTestAgentDefaults: AgentDefaultsResolver = (config) => {