@shipfox/api-workflows 16.0.0 → 17.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@shipfox/api-workflows",
   "license": "MIT",
-  "version": "16.0.0",
+  "version": "17.0.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -23,30 +23,30 @@
     "drizzle-orm": "^0.45.2",
     "js-yaml": "^4.1.0",
     "zod": "^4.4.3",
-    "@shipfox/api-auth-context": "15.0.0",
-    "@shipfox/api-auth-dto": "15.0.0",
-    "@shipfox/api-agent-dto": "16.0.0",
-    "@shipfox/annotations-dto": "12.3.0",
-    "@shipfox/api-definitions-dto": "16.0.0",
+    "@shipfox/api-auth-context": "17.0.0",
+    "@shipfox/api-auth-dto": "17.0.0",
+    "@shipfox/api-definitions-dto": "17.0.0",
     "@shipfox/api-projects-dto": "15.0.0",
     "@shipfox/api-integration-core-dto": "16.0.0",
+    "@shipfox/api-agent-dto": "17.0.0",
     "@shipfox/api-runners-dto": "16.0.0",
     "@shipfox/api-secrets-dto": "12.0.0",
-    "@shipfox/api-workflows-dto": "16.0.0",
+    "@shipfox/annotations-dto": "12.3.0",
+    "@shipfox/api-workflows-dto": "17.0.0",
     "@shipfox/api-workspaces-dto": "15.0.0",
     "@shipfox/config": "1.2.4",
     "@shipfox/inter-module": "0.2.3",
-    "@shipfox/expression": "2.4.0",
-    "@shipfox/node-drizzle": "0.3.5",
+    "@shipfox/expression": "2.4.1",
     "@shipfox/node-error-monitoring": "0.3.0",
     "@shipfox/node-fastify": "0.4.3",
     "@shipfox/node-module": "1.0.7",
     "@shipfox/node-opentelemetry": "0.6.5",
     "@shipfox/node-outbox": "0.2.6",
-    "@shipfox/node-postgres": "0.5.0",
+    "@shipfox/node-drizzle": "0.3.5",
+    "@shipfox/node-postgres": "0.5.1",
     "@shipfox/node-temporal": "0.4.6",
     "@shipfox/runner-labels": "0.2.0",
-    "@shipfox/workflow-document": "3.3.0"
+    "@shipfox/workflow-document": "3.3.1"
   },
   "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,