feat(workflow-executor): add HTTP server and WorkflowRunner scaffold by matthv · Pull Request #1500 · ForestAdmin/agent-nodejs

matthv · 2026-03-19T10:49:47Z

Summary

Adds ExecutorHttpServer (Koa) with two routes:
- GET /runs/:runId — reads records + steps from RunStoreFactory
- POST /runs/:runId/trigger — delegates to WorkflowRunner.triggerPoll()
Adds WorkflowRunner class (stub) as the main entry point, aligned with spec section 4.1. Starts HTTP server on start() if httpPort is configured
Adds RunStoreFactory interface to resolve runId → RunStore

Test plan

6 unit tests via supertest (GET 200/404, POST trigger, error propagation, start/stop)
Lint + build pass

fixes PRD-222

🤖 Generated with Claude Code

Note

Add Koa HTTP server and `WorkflowRunner` scaffold to workflow-executor

Adds ExecutorHttpServer, a Koa-based HTTP server with GET /runs/:runId (returns step executions or 404) and POST /runs/:runId/trigger (invokes WorkflowRunner.triggerPoll).
Adds WorkflowRunner, which manages the HTTP server lifecycle via start()/stop(); triggerPoll is currently a no-op stub.
Adds the RunStoreFactory interface for looking up a RunStore by run ID.
Exports all new types and classes from the package index.
Risk: handleTrigger does not catch errors from triggerPoll, so failures propagate as unhandled 500s via Koa's default error handler.

Changes since #1500 opened

Renamed RunStoreFactory.getRunStore method to buildRunStore and updated all call sites in ExecutorHttpServer.handleGetRun handler and test files to use the new method name [a78e559]
Renamed workflow-runner.ts to runner.ts and updated import paths from '../workflow-runner' and '../../src/workflow-runner' to '../runner' and '../../src/runner' respectively across ExecutorHttpServer, the package index exports, and test files [a78e559]
Modified ExecutorHttpServer.stop method to defer setting this.server to null until inside the HTTP server close callback, ensuring the server reference remains non-null during the asynchronous shutdown process [a78e559]
Renamed WorkflowRunner class to Runner and WorkflowRunnerConfig interface to RunnerConfig throughout the workflow-executor package [0d6abe8]
Updated documentation to reflect new scaffold architecture [0670c16]
Added error handling to ExecutorHttpServer.start method to reject the promise when the underlying HTTP server emits an error event during startup, and added guard logic to Runner.start method to prevent creating multiple ExecutorHttpServer instances when httpPort is configured [a7f17f2]
Added validation for missing runId parameter in HTTP handlers [0157cb1]
Removed nullability from RunStoreFactory.buildRunStore return type and corresponding null-check logic in ExecutorHttpServer.handleGetRun [afd0743]
Updated test suite to accommodate non-null RunStoreFactory contract [afd0743]
Relocated run-store-factory.ts module from src/http/ to src/ directory and updated all import paths [40d44d1]
Added test suite for Runner class HTTP server lifecycle management [42c459d]
Added test for Runner.triggerPoll method [42c459d]
Updated the import path for RunStore type in the run-store-factory module [d2d4ff5]
Added global error-handling middleware to ExecutorHttpServer and removed explicit parameter validation from route handlers [2ed53b6]
Modified Runner.start to support HTTP server initialization on port 0 and fixed ExecutorHttpServer.stop to preserve server instance on close failure [2ed53b6]
Made executionResult optional in ConditionStepExecutionData interface [2ed53b6]
Updated tests to validate structured error responses and constructor arguments [2ed53b6]
Made executionResult property required in ConditionStepExecutionData interface [fe50017]
Flattened RunnerConfig interface structure by replacing nested ports object with top-level agentPort and workflowPort properties [19926eb]
Changed RunStore interface methods to accept runId as a parameter [b6383ef]
Removed RunStoreFactory interface and its exports [b6383ef]
Updated ExecutorHttpServer to accept RunStore instead of RunStoreFactory [b6383ef]
Updated RunnerConfig to accept RunStore instead of RunStoreFactory [b6383ef]
Updated all step executor implementations to pass runId to RunStore methods [b6383ef]
Updated all test files to match new RunStore API signatures [b6383ef]

📊 Macroscope summarized 12bc2be. 5 files reviewed, 2 issues evaluated, 0 issues filtered, 1 comment posted

🗂️ Filtered Issues

linear · 2026-03-19T10:49:50Z

PRD-222 Implémenter le serveur HTTP de l'executor

Scra3 · 2026-03-19T14:55:50Z

packages/workflow-executor/src/http/executor-http-server.ts

+
+  private async handleGetRun(ctx: Koa.Context): Promise<void> {
+    const { runId } = ctx.params;
+    const runStore = this.options.runStoreFactory.getRunStore(runId);


buildRunStore

packages/workflow-executor/src/runner.ts

Adds ExecutorHttpServer (Koa) with two routes: - GET /runs/:runId — reads records + steps from RunStore - POST /runs/:runId/trigger — delegates to WorkflowRunner.triggerPoll() WorkflowRunner is a concrete class (stub) aligned with spec section 4.1. Polling and execution dispatch will be implemented in a follow-up PR. fixes PRD-222 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Scra3 · 2026-03-19T15:04:06Z

packages/workflow-executor/src/http/run-store-factory.ts

+import type { RunStore } from '../ports/run-store';
+
+export interface RunStoreFactory {
+  getRunStore(runId: string): RunStore | null;


rename get by build

packages/workflow-executor/src/http/executor-http-server.ts

- Rename getRunStore → buildRunStore (Scra3) - Rename workflow-runner.ts → runner.ts (Scra3) - Fix stop() race condition: move this.server = null inside close callback (Macroscope) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

qltysh · 2026-03-19T15:09:55Z

Coverage Impact

Unable to calculate total coverage change because base branch coverage was not found.

Modified Files with Diff Coverage (6)

File	% Diff	Uncovered Line #s
packages/workflow-executor/src/runner.ts	100.0%
...s/workflow-executor/src/executors/read-record-step-executor.ts	100.0%
...ges/workflow-executor/src/executors/condition-step-executor.ts	100.0%
packages/workflow-executor/src/executors/base-step-executor.ts	100.0%
packages/workflow-executor/src/http/executor-http-server.ts	97.4%	60
packages/workflow-executor/src/index.ts	100.0%
Total	98.2%

🤖 Increase coverage with AI coding...

In the `feature/prd-222-implement-executor-http-server` branch, add test coverage for this new code:

- `packages/workflow-executor/src/http/executor-http-server.ts` -- Line 60

🚦 See full report on Qlty Cloud »

🛟 Help

Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.
Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.
File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)
- Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.

matthv · 2026-03-19T15:12:43Z

Addressed all review feedback:

getRunStore → buildRunStore ✅
workflow-runner.ts → runner.ts ✅
stop() race condition fixed — this.server = null moved inside close callback ✅

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Scra3 · 2026-03-19T15:19:14Z

packages/workflow-executor/src/http/run-store-factory.ts

+import type { RunStore } from '../ports/run-store';
+
+export interface RunStoreFactory {
+  buildRunStore(runId: string): RunStore | null;


👀 Can really return null?

packages/workflow-executor/src/runner.ts

packages/workflow-executor/src/http/executor-http-server.ts

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Guard against double start() in Runner (Macroscope) - Handle listen() error in start() via server.on('error', reject) (Macroscope) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Return 400 when runId is missing on both GET /runs/:runId and POST /runs/:runId/trigger. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Factory always builds a RunStore for the given runId. runId validation (400) is handled before calling buildRunStore. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

matthv · 2026-03-19T15:47:42Z

Final summary of all fixes applied:

Renames:

getRunStore → buildRunStore
workflow-runner.ts → runner.ts
WorkflowRunner → Runner, WorkflowRunnerConfig → RunnerConfig

Bug fixes:

stop() race condition — this.server = null moved inside close callback
start() hang on port conflict — added server.on('error', reject)
Double start() guard — if (httpPort && !this.httpServer)

Validation:

Both routes return 400 if runId is missing

Interface change:

buildRunStore no longer returns null — it always builds a RunStore for the given runId. Validation happens before the call.

Docs:

CLAUDE.md updated with new modules (runner, adapters, http)

RunStoreFactory is not HTTP-specific — it's also used by the Runner. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Tests start/stop lifecycle, HTTP server wiring, double-start guard, restart after stop, and triggerPoll stub. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

… types - Add Koa error middleware to ExecutorHttpServer (returns structured JSON on errors) - Use server.once('error') instead of .on() to avoid stale listener after start - Fix stop(): only null this.server on successful close, not on error - Fix Runner.start(): use !== undefined check for httpPort (avoids falsy 0 bug) - Fix Runner.start(): assign this.httpServer only after server.start() resolves - Make ConditionStepExecutionData.executionResult optional (matches runtime behavior) - Add GET /runs/:runId error path test (500 + structured body) - Assert buildRunStore called with correct runId in GET test - Assert response.body.error in trigger error test - Strengthen Runner constructor assertion to verify full config object - Remove module-level shared mock state in executor-http-server tests Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…onResult as required Out of scope for this PR — will be addressed separately. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…tly to RunStore methods RunStoreFactory was a superfluous abstraction (YAGNI) — its only role was to scope a RunStore to a runId, but all callers already know their runId. Adding runId directly to RunStore.getStepExecutions/saveStepExecution removes one level of indirection, one file, and simplifies RunnerConfig. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Scra3 reviewed Mar 19, 2026

View reviewed changes

packages/workflow-executor/src/runner.ts Show resolved Hide resolved

matthv force-pushed the feature/prd-222-implement-executor-http-server branch from 88ef7d5 to 12bc2be Compare March 19, 2026 15:03

Scra3 reviewed Mar 19, 2026

View reviewed changes

macroscopeapp bot reviewed Mar 19, 2026

View reviewed changes

packages/workflow-executor/src/http/executor-http-server.ts Outdated Show resolved Hide resolved

refactor(workflow-executor): rename WorkflowRunner to Runner

0d6abe8

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Scra3 reviewed Mar 19, 2026

View reviewed changes

macroscopeapp bot reviewed Mar 19, 2026

View reviewed changes

packages/workflow-executor/src/runner.ts Show resolved Hide resolved

packages/workflow-executor/src/http/executor-http-server.ts Show resolved Hide resolved

matthv and others added 4 commits March 19, 2026 16:23

docs(workflow-executor): update CLAUDE.md with new modules

0670c16

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix(workflow-executor): address second round of PR review

a7f17f2

- Guard against double start() in Runner (Macroscope) - Handle listen() error in start() via server.on('error', reject) (Macroscope) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix(workflow-executor): validate runId param on HTTP routes

0157cb1

Return 400 when runId is missing on both GET /runs/:runId and POST /runs/:runId/trigger. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix(workflow-executor): buildRunStore cannot return null

afd0743

Factory always builds a RunStore for the given runId. runId validation (400) is handled before calling buildRunStore. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

matthv and others added 7 commits March 19, 2026 16:55

refactor(workflow-executor): move RunStoreFactory to src root

40d44d1

RunStoreFactory is not HTTP-specific — it's also used by the Runner. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

test(workflow-executor): add Runner unit tests

42c459d

Tests start/stop lifecycle, HTTP server wiring, double-start guard, restart after stop, and triggerPoll stub. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix(workflow-executor): fix import path in run-store-factory after move

d2d4ff5

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

revert(workflow-executor): restore ConditionStepExecutionData.executi…

fe50017

…onResult as required Out of scope for this PR — will be addressed separately. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

refactor(workflow-executor): flatten RunnerConfig (remove ports nesting)

19926eb

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Scra3 approved these changes Mar 19, 2026

View reviewed changes

matthv merged commit 613ec1b into feat/prd-214-setup-workflow-executor-package Mar 20, 2026
30 checks passed

matthv deleted the feature/prd-222-implement-executor-http-server branch March 20, 2026 08:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(workflow-executor): add HTTP server and WorkflowRunner scaffold#1500

feat(workflow-executor): add HTTP server and WorkflowRunner scaffold#1500
matthv merged 14 commits intofeat/prd-214-setup-workflow-executor-packagefrom
feature/prd-222-implement-executor-http-server

matthv commented Mar 19, 2026 •

edited by macroscopeapp bot

Loading

Uh oh!

linear bot commented Mar 19, 2026

Uh oh!

Scra3 Mar 19, 2026

Uh oh!

Uh oh!

Scra3 Mar 19, 2026

Uh oh!

Uh oh!

qltysh bot commented Mar 19, 2026 •

edited

Loading

Uh oh!

matthv commented Mar 19, 2026

Uh oh!

Scra3 Mar 19, 2026

Uh oh!

Uh oh!

Uh oh!

matthv commented Mar 19, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

matthv commented Mar 19, 2026 • edited by macroscopeapp bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Add Koa HTTP server and WorkflowRunner scaffold to workflow-executor

Changes since #1500 opened

🗂️ Filtered Issues

Uh oh!

linear bot commented Mar 19, 2026

Uh oh!

Scra3 Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Scra3 Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

qltysh bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

matthv commented Mar 19, 2026

Uh oh!

Scra3 Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

matthv commented Mar 19, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

matthv commented Mar 19, 2026 •

edited by macroscopeapp bot

Loading

Add Koa HTTP server and `WorkflowRunner` scaffold to workflow-executor

qltysh bot commented Mar 19, 2026 •

edited

Loading