feat: connect orchestrator and frontend

[Scra3]

MAIN BRANCH TO INTRODUCE WORKFLOW EXECUTOR.

Note

Add @forestadmin/workflow-executor package and connect it to the agent frontend

• Introduces a new @forestadmin/workflow-executor package: a long-lived polling service that fetches available workflow runs from the Forest server, executes AI-driven steps (read, update, trigger-action, load-related-record, MCP, condition, guidance), and persists results via in-memory or database-backed stores.
• Adds concrete step executors for each step type with idempotency guards, AI tool selection, activity log integration, and optional user-confirmation flows (awaiting-input).
• Adds adapters for agent client, Forest server workflow port, AI model (via AiClientAdapter or ServerAiAdapter), activity log port with retry and draining, and structured loggers.
• Exposes an authenticated Koa HTTP server (ExecutorHttpServer) with /health, GET /runs/:runId, and POST /runs/:runId/trigger endpoints protected by JWT.
• Adds WorkflowExecutorProxyRoute to the agent, proxying /_internal/workflow-executions/:runId requests to the configured executor URL when workflowExecutorUrl is set in AgentOptions.
• Extends @forestadmin/ai-proxy with AiClient, createBaseChatModel, getAiConfiguration, validateAiConfigurations, and mcpServerId propagation through MCP and integration tool factories.
• Risk: the new executor process requires FOREST_ENV_SECRET, FOREST_AUTH_SECRET, and AGENT_URL at startup; missing or malformed values cause an immediate ConfigurationError.

^{Macroscope summarized 0cac172.}

[macroscopeapp]

🟡 Medium adapters/forest-server-workflow-port.ts:134

In toMalformedInfo, accessing run.workflowHistory.at(-1) throws TypeError: Cannot read properties of undefined (reading 'at') when workflowHistory is null or undefined. Since this method is only called from error handlers during malformed run recovery, a missing workflowHistory causes the error handling itself to crash. Consider guarding the access with optional chaining: run.workflowHistory?.at(-1).

Suggested change

	const pending = run.workflowHistory.at(-1) ?? null;
	const pending = run.workflowHistory?.at(-1) ?? null;

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

In file packages/workflow-executor/src/adapters/forest-server-workflow-port.ts around line 134:

In `toMalformedInfo`, accessing `run.workflowHistory.at(-1)` throws `TypeError: Cannot read properties of undefined (reading 'at')` when `workflowHistory` is `null` or `undefined`. Since this method is only called from error handlers during malformed run recovery, a missing `workflowHistory` causes the error handling itself to crash. Consider guarding the access with optional chaining: `run.workflowHistory?.at(-1)`.

Evidence trail:
packages/workflow-executor/src/adapters/forest-server-workflow-port.ts line 134: `run.workflowHistory.at(-1)` without optional chaining
packages/workflow-executor/src/adapters/server-types.ts line 120: `workflowHistory: ServerStepHistory[]` (non-nullable type, but data from network)
packages/workflow-executor/src/adapters/forest-server-workflow-port.ts lines 63-76: catch block calling `toMalformedInfo` at line 69 when error is `WorkflowExecutorError`
packages/workflow-executor/src/adapters/forest-server-workflow-port.ts lines 107-128: `toDispatch` throws `InvalidStepDefinitionError` at lines 109 and 118 BEFORE `workflowHistory` is accessed
packages/workflow-executor/src/adapters/forest-server-workflow-port.ts lines 55-57: data comes from server HTTP response with no runtime type validation

[macroscopeapp]

🟡 Medium executors/base-step-executor.ts:209

The non-null assertion patchBodySchemas[execution.type]! at line 210 crashes when execution.type is 'read-record' or 'record' — these types have no schema in patchBodySchemas, so schema.safeParse throws TypeError: Cannot read properties of undefined. Consider adding schemas for these types or throwing a descriptive StepStateError when no schema exists.

      const schema = patchBodySchemas[execution.type];
-
-      if (!parsed.success) {
+      if (!schema) {
+        throw new StepStateError(`No pending data validator for step type "${execution.type}"`);
+      }
+
+      const parsed = schema.safeParse(pendingData);
+
+      if (!parsed.success) {

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

In file packages/workflow-executor/src/executors/base-step-executor.ts around lines 209-217:

The non-null assertion `patchBodySchemas[execution.type]!` at line 210 crashes when `execution.type` is `'read-record'` or `'record'` — these types have no schema in `patchBodySchemas`, so `schema.safeParse` throws `TypeError: Cannot read properties of undefined`. Consider adding schemas for these types or throwing a descriptive `StepStateError` when no schema exists.