feat(agent): proxify ws executor call

[arnaud-moncel]

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

Add proxy routes for workflow executor under /_internal/workflow-executions/*

• Adds a new WorkflowExecutorProxyRoute that registers three private routes (GET, POST, PATCH) under /_internal/workflow-executions/:runId and proxies them to the workflow executor's /runs/* endpoints.
• A new workflowExecutorUrl option on AgentOptions controls whether the proxy is active; when null or unset, no routes are registered.
• Request bodies are forwarded as JSON for non-GET methods; responses are parsed as JSON when possible, otherwise returned as raw text.
• Also adds mock mode infrastructure (MockWorkflowPort, MockAgentPort, MockAiModelPort) and an expanded README to the workflow-executor example package.

^{Macroscope summarized ba56cb7.}

[macroscopeapp]

🟡 Medium workflow/workflow-executor-proxy.ts:36

handleProxy uses context.path to construct the target URL, but path contains only the pathname without the query string. Requests with query parameters (e.g., ?foo=bar) lose those parameters when forwarded to the executor. Consider using context.url instead, which includes both the pathname and query string.

-    const executorPath = context.path.replace(
+    const executorPath = context.url.replace(
       WorkflowExecutorProxyRoute.AGENT_PREFIX,
       WorkflowExecutorProxyRoute.EXECUTOR_PREFIX,
     );

🚀 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 lines 36-39:

`handleProxy` uses `context.path` to construct the target URL, but `path` contains only the pathname without the query string. Requests with query parameters (e.g., `?foo=bar`) lose those parameters when forwarded to the executor. Consider using `context.url` instead, which includes both the pathname and query string.

Evidence trail:
1. packages/agent/src/routes/workflow/workflow-executor-proxy.ts lines 36-40 (REVIEWED_COMMIT): Code uses `context.path.replace()` to construct `executorPath`, then `new URL(executorPath, this.executorUrl)` to create the target URL.
2. Koa documentation at https://koajs.com confirms: `request.path` - "Get request pathname" and `request.querystring` - "Get raw query string void of ?" - these are separate properties, confirming `path` does not include query parameters.

[qltysh]

1 new issue

Tool	Category	Rule	Count
qlty	Structure	Function with many returns (count = 4): createMockModel	1

[macroscopeapp]

🟢 Low src/main.ts:40

Number(process.env.EXECUTOR_HTTP_PORT) and Number(process.env.EXECUTOR_POLLING_INTERVAL_MS) return NaN for invalid numeric strings (e.g., abc), silently propagating NaN to downstream code that expects a valid number. Unlike required env vars which throw on missing values, these misconfigurations fail silently and cause confusing downstream failures. Consider validating and throwing a clear error when the environment variable is set but not parsable as a number.

-  const httpPort = Number(process.env.EXECUTOR_HTTP_PORT ?? '4001');
-  const pollingIntervalMs = Number(process.env.EXECUTOR_POLLING_INTERVAL_MS ?? '5000');
+  const httpPort = parseIntEnv('EXECUTOR_HTTP_PORT', 4001);
+  const pollingIntervalMs = parseIntEnv('EXECUTOR_POLLING_INTERVAL_MS', 5000);

Also found in 1 other location(s)

packages/agent/src/routes/workflow/workflow-executor-proxy.ts:19

Calling .replace() on options.workflowExecutorUrl at line 19 will throw a TypeError if the value is null. The type AgentOptions.workflowExecutorUrl is string | null, and the test factory in code object 1 defaults it to null. If WorkflowExecutorProxyRoute is instantiated when workflowExecutorUrl is null, the constructor crashes with "Cannot read properties of null (reading 'replace')".

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

In file packages/workflow-executor/src/main.ts around lines 40-41:

`Number(process.env.EXECUTOR_HTTP_PORT)` and `Number(process.env.EXECUTOR_POLLING_INTERVAL_MS)` return `NaN` for invalid numeric strings (e.g., `abc`), silently propagating `NaN` to downstream code that expects a valid number. Unlike required env vars which throw on missing values, these misconfigurations fail silently and cause confusing downstream failures. Consider validating and throwing a clear error when the environment variable is set but not parsable as a number.

Evidence trail:
packages/workflow-executor/src/main.ts:40 - `const httpPort = Number(process.env.EXECUTOR_HTTP_PORT ?? '4001')` shows Number() parsing without validation
packages/workflow-executor/src/main.ts:41 - `const pollingIntervalMs = Number(process.env.EXECUTOR_POLLING_INTERVAL_MS ?? '5000')` same pattern
packages/workflow-executor/src/main.ts:70 - httpPort passed to Runner constructor
packages/workflow-executor/src/http/executor-http-server.ts:93 - `this.server.listen(this.options.port, resolve)` uses port directly
packages/workflow-executor/src/runner.ts:198 - `setTimeout(() => this.runPollCycle(), this.config.pollingIntervalMs)` uses interval directly
packages/workflow-executor/src/main.ts:24-30 - requireEnv() validates required vars but no equivalent for numeric validation

Also found in 1 other location(s):
- packages/agent/src/routes/workflow/workflow-executor-proxy.ts:19 -- Calling `.replace()` on `options.workflowExecutorUrl` at line 19 will throw a `TypeError` if the value is `null`. The type `AgentOptions.workflowExecutorUrl` is `string | null`, and the test factory in code object 1 defaults it to `null`. If `WorkflowExecutorProxyRoute` is instantiated when `workflowExecutorUrl` is `null`, the constructor crashes with "Cannot read properties of null (reading 'replace')".

[qltysh]

Coverage Impact

⬇️ Merging this pull request will decrease total coverage on feat/prd-214-setup-workflow-executor-package by 0.01%.

Modified Files with Diff Coverage (3)

Rating	File	% Diff	Uncovered Line #s
	packages/agent/src/utils/options-validator.ts	100.0%
	packages/agent/src/routes/index.ts	66.7%	179
	packages/agent/src/routes/workflow/workflow-executor-proxy.ts	97.1%	69
	Total	94.7%

🤖 Increase coverage with AI coding...

In the `feat/wf-executor-proxy` branch, add test coverage for this new code:

- `packages/agent/src/routes/index.ts` -- Line 179
- `packages/agent/src/routes/workflow/workflow-executor-proxy.ts` -- Line 69

🚦 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.