feat: connect orchestrator and frontend

[Scra3]

Definition of Done

General

• Write an explicit title for the Pull Request, following Conventional Commits specification
• Test manually the implemented changes
• Validate the code quality (indentation, syntax, style, simplicity, readability)

Security

• Consider the security impact of the changes made

Note

Connect workflow orchestrator to frontend via a new workflow-executor package and agent proxy routes

• Introduces the packages/workflow-executor package — a standalone Node.js service that polls the Forest server for pending workflow runs and executes each step via a set of typed step executors (Condition, ReadRecord, UpdateRecord, TriggerAction, LoadRelatedRecord, Mcp, Guidance).
• Each executor is backed by a common BaseStepExecutor providing idempotency checks, activity logging, timeout handling, and unified error-to-outcome mapping; a StepExecutorFactory selects the right implementation per step type.
• Adds an HTTP server (ExecutorHttpServer) with JWT auth, exposing GET /health, GET /runs/:runId, and POST /runs/:runId/trigger so the frontend can read step state and submit pending data.
• Adds WorkflowExecutorProxyRoute to the agent, exposing GET/_internal/workflow-executions/:runId and POST /_internal/workflow-executions/:runId/trigger that forward requests (including auth headers) to the executor URL configured via the new workflowExecutorUrl agent option.
• Persistence is handled by pluggable RunStore implementations: an InMemoryStore for development and a Sequelize-backed DatabaseStore (SQLite/Postgres) with Umzug migrations for production.
• Risk: enabling workflowExecutorUrl on the agent adds unauthenticated-to-executor proxy routes; the executor relies on JWT validation of the forwarded Authorization/Cookie headers for security.

^{Macroscope summarized d88b561.}

[macroscopeapp]

🟡 Medium src/cli-core.ts:17

Setting MAX_CHAIN_DEPTH=0 to disable chaining throws a ConfigurationError because parsePositiveIntEnv uses z.number().positive(), which rejects zero. The ExecutorOptions interface comment explicitly says "0 disables chaining", so users following the documentation cannot actually disable chaining. Consider changing the validator to allow zero.

-const POSITIVE_INT = z.coerce.number().int().positive();
+const NON_NEGATIVE_INT = z.coerce.number().int().nonnegative();

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file packages/workflow-executor/src/cli-core.ts around line 17:

Setting `MAX_CHAIN_DEPTH=0` to disable chaining throws a `ConfigurationError` because `parsePositiveIntEnv` uses `z.number().positive()`, which rejects zero. The `ExecutorOptions` interface comment explicitly says "0 disables chaining", so users following the documentation cannot actually disable chaining. Consider changing the validator to allow zero.

Evidence trail:
packages/workflow-executor/src/cli-core.ts line 17: `const POSITIVE_INT = z.coerce.number().int().positive();`
packages/workflow-executor/src/cli-core.ts line 153: `maxChainDepth: parsePositiveIntEnv('MAX_CHAIN_DEPTH', env.MAX_CHAIN_DEPTH),`
packages/workflow-executor/src/build-workflow-executor.ts line 43: `// Max auto-chained steps per entry (see RunnerConfig.maxChainDepth). 0 disables chaining.`
packages/workflow-executor/src/runner.ts line 55: `// next poll cycle (counted after the initial step). 0 disables chaining entirely. Default 50.`

[macroscopeapp]

🟢 Low workflow/workflow-executor-proxy.ts:24

When workflowExecutorUrl includes a path component (e.g., http://executor.com/api/v1), the path is silently discarded. At line 40, new URL(executorRelativeUrl, this.executorUrl) receives executorRelativeUrl starting with /runs/..., and the URL constructor treats absolute paths as relative to the origin, not the base path. So new URL('/runs/123', 'http://executor.com/api/v1') yields http://executor.com/runs/123, dropping /api/v1.

-    // Remove trailing slash for clean URL joining
-    this.executorUrl = new URL(options.workflowExecutorUrl.replace(/\/+$/, ''));
+    this.executorUrl = new URL(options.workflowExecutorUrl);

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file packages/agent/src/routes/workflow/workflow-executor-proxy.ts around line 24:

When `workflowExecutorUrl` includes a path component (e.g., `http://executor.com/api/v1`), the path is silently discarded. At line 40, `new URL(executorRelativeUrl, this.executorUrl)` receives `executorRelativeUrl` starting with `/runs/...`, and the URL constructor treats absolute paths as relative to the origin, not the base path. So `new URL('/runs/123', 'http://executor.com/api/v1')` yields `http://executor.com/runs/123`, dropping `/api/v1`.

Evidence trail:
packages/agent/src/routes/workflow/workflow-executor-proxy.ts lines 24 and 39-42 (REVIEWED_COMMIT): constructor strips trailing slashes from executorUrl, then `new URL(executorRelativeUrl, this.executorUrl)` is called with `executorRelativeUrl` starting with `/runs/...`. WHATWG URL spec: https://url.spec.whatwg.org/#dom-url-url — absolute-path references resolve against the origin, not the base path. packages/agent/src/types.ts:54 — `workflowExecutorUrl?: string | null` with no path restriction. packages/agent/test/routes/workflow/workflow-executor-proxy.test.ts — all tests use URLs without path components (e.g., `http://localhost:${executorPort}`).