@xdelivered/emberflow 0.2.0

package/dist/src/nodes/requireAuth.d.ts

@@ -0,0 +1,20 @@
+import type { NodeRegistry } from '../engine/index.js';
+/**
+ * Explicit in-flow auth check. Config carries the AuthPolicy fields (scheme,
+ * secretRef, verify?, header?). Reads the request off ctx.input (the
+ * operation's incoming { headers, ... }) and the secret off ctx.secrets,
+ * then reuses the same enforceAuth() the HTTP handler runs before the
+ * operation body (server/httpOperations.ts via server/auth/enforce.ts) so
+ * there is a single verify code path.
+ *
+ * Browser-safe: uses only src/engine (no server/ import), since src/nodes is
+ * bundled into the studio browser build (src/store/builderStore.ts). Custom
+ * verifiers registered server-side via project.registerVerifiers are a
+ * server-enforcement concern; this node only has the default bearer/apiKey
+ * verifiers (unless policy.verify happens to name one of those).
+ *
+ * Pure-read: throws HttpError(401/500) on failure, otherwise returns
+ * { user } for downstream nodes to see. No side effects, so no
+ * `effects: 'mutation'`.
+ */
+export declare function registerRequireAuthNode(registry: NodeRegistry): void;

package/dist/src/nodes/requireAuth.js

@@ -0,0 +1,48 @@
+import { createDefaultVerifierRegistry, enforceAuth } from '../engine/index.js';
+/**
+ * Explicit in-flow auth check. Config carries the AuthPolicy fields (scheme,
+ * secretRef, verify?, header?). Reads the request off ctx.input (the
+ * operation's incoming { headers, ... }) and the secret off ctx.secrets,
+ * then reuses the same enforceAuth() the HTTP handler runs before the
+ * operation body (server/httpOperations.ts via server/auth/enforce.ts) so
+ * there is a single verify code path.
+ *
+ * Browser-safe: uses only src/engine (no server/ import), since src/nodes is
+ * bundled into the studio browser build (src/store/builderStore.ts). Custom
+ * verifiers registered server-side via project.registerVerifiers are a
+ * server-enforcement concern; this node only has the default bearer/apiKey
+ * verifiers (unless policy.verify happens to name one of those).
+ *
+ * Pure-read: throws HttpError(401/500) on failure, otherwise returns
+ * { user } for downstream nodes to see. No side effects, so no
+ * `effects: 'mutation'`.
+ */
+export function registerRequireAuthNode(registry) {
+    registry.register({
+        type: 'requireAuth',
+        label: 'Require Auth',
+        description: 'Verifies the incoming request against an auth policy (bearer/apiKey shared-secret, or a named custom verifier) and attaches { user } for downstream nodes. Throws HttpError(401) on failure, HttpError(500) if misconfigured.',
+        simpleDescription: 'Checks the request is authorized before continuing',
+        category: 'http',
+        traceKind: 'compute',
+        tags: ['http', 'auth'],
+        configSchema: {
+            fields: [
+                { name: 'scheme', type: 'string' },
+                { name: 'secretRef', type: 'string' },
+                { name: 'verify', type: 'string' },
+                { name: 'header', type: 'string' },
+            ],
+        },
+        outputSchema: {
+            fields: [{ name: 'user', type: 'object' }],
+        },
+    }, async (ctx) => {
+        const policy = ctx.config;
+        const input = (ctx.input ?? {});
+        const request = { headers: input.headers ?? {} };
+        const verifiers = createDefaultVerifierRegistry();
+        const { user } = enforceAuth({ policy, request, secrets: ctx.secrets, verifiers });
+        return { user };
+    });
+}

package/dist/src/nodes/response.d.ts

@@ -0,0 +1,8 @@
+import type { NodeRegistry } from '../engine/index.js';
+/**
+ * Terminal node for an HTTP operation: its input `{ status, body }` becomes
+ * the HTTP response `extractResponse` (server/operationResult.ts) maps onto
+ * the wire. `status` defaults to 200 when the input omits it. Pure — no
+ * side effects, so no `effects: 'mutation'` declaration.
+ */
+export declare function registerResponseNodes(registry: NodeRegistry): void;

package/dist/src/nodes/response.js

@@ -0,0 +1,33 @@
+/**
+ * Terminal node for an HTTP operation: its input `{ status, body }` becomes
+ * the HTTP response `extractResponse` (server/operationResult.ts) maps onto
+ * the wire. `status` defaults to 200 when the input omits it. Pure — no
+ * side effects, so no `effects: 'mutation'` declaration.
+ */
+export function registerResponseNodes(registry) {
+    registry.register({
+        type: 'Response',
+        label: 'Response',
+        description: 'Terminal node for an HTTP operation: its input { status, body } becomes the HTTP response. Omit status to default to 200.',
+        simpleDescription: 'Shapes the HTTP response for this operation',
+        category: 'http',
+        traceKind: 'compute',
+        tags: ['http'],
+        inputSchema: {
+            fields: [
+                { name: 'status', type: 'number' },
+                { name: 'body', type: 'object' },
+            ],
+        },
+        outputSchema: {
+            fields: [
+                { name: 'status', type: 'number' },
+                { name: 'body', type: 'object' },
+            ],
+        },
+    }, async (ctx) => {
+        const input = (ctx.input ?? {});
+        const status = typeof input.status === 'number' ? input.status : 200;
+        return { status, body: input.body };
+    });
+}

package/dist/src/nodes/weather.d.ts

@@ -0,0 +1,33 @@
+import type { NodeRegistry } from '../engine/index.js';
+export declare function describeWeatherCode(code: number): string;
+export interface AdvisoryInput {
+    place: string;
+    temperatureC: number;
+    windKmh: number;
+    weatherCode: number;
+    maxC: number;
+    minC: number;
+    rainChancePct: number;
+}
+export declare function buildAdvisory(input: AdvisoryInput): {
+    place: string;
+    temperatureC: number;
+    condition: string;
+    headline: string;
+    range: string;
+    advice: string;
+};
+export type WeatherSeverity = 'severe' | 'mild';
+/**
+ * Pure severity rule: severe when wind is at gale strength (≥ 40 km/h) or rain
+ * is likely (≥ 70% chance), otherwise mild.
+ */
+export declare function classifyWeather(windKmh: number, rainChancePct: number): {
+    severity: WeatherSeverity;
+    reason: string;
+};
+/**
+ * Real-infrastructure nodes backed by the Open-Meteo public APIs
+ * (keyless, CORS-enabled): geocoding + weather forecast.
+ */
+export declare function registerWeatherNodes(registry: NodeRegistry): void;

package/dist/src/nodes/weather.js

@@ -0,0 +1,260 @@
+const WEATHER_CODES = {
+    0: 'clear sky',
+    1: 'mainly clear',
+    2: 'partly cloudy',
+    3: 'overcast',
+    45: 'fog',
+    48: 'rime fog',
+    51: 'light drizzle',
+    53: 'drizzle',
+    55: 'dense drizzle',
+    61: 'light rain',
+    63: 'rain',
+    65: 'heavy rain',
+    71: 'light snow',
+    73: 'snow',
+    75: 'heavy snow',
+    80: 'rain showers',
+    81: 'rain showers',
+    82: 'violent rain showers',
+    95: 'thunderstorm',
+    96: 'thunderstorm with hail',
+    99: 'thunderstorm with heavy hail',
+};
+export function describeWeatherCode(code) {
+    return WEATHER_CODES[code] ?? `unknown conditions (code ${code})`;
+}
+export function buildAdvisory(input) {
+    const condition = describeWeatherCode(input.weatherCode);
+    const advice = [];
+    if (input.rainChancePct >= 50)
+        advice.push('take an umbrella');
+    if (input.windKmh >= 30)
+        advice.push('expect strong wind');
+    if (input.temperatureC <= 5)
+        advice.push('dress warm');
+    if (input.temperatureC >= 28)
+        advice.push('stay hydrated');
+    if (advice.length === 0)
+        advice.push('no precautions needed');
+    return {
+        place: input.place,
+        temperatureC: input.temperatureC,
+        condition,
+        headline: `${input.place}: ${Math.round(input.temperatureC)}°C, ${condition}`,
+        range: `${Math.round(input.minC)}–${Math.round(input.maxC)}°C today, ${Math.round(input.rainChancePct)}% rain chance`,
+        advice: advice.join('; '),
+    };
+}
+/**
+ * Pure severity rule: severe when wind is at gale strength (≥ 40 km/h) or rain
+ * is likely (≥ 70% chance), otherwise mild.
+ */
+export function classifyWeather(windKmh, rainChancePct) {
+    if (windKmh >= 40) {
+        return { severity: 'severe', reason: `high winds at ${Math.round(windKmh)} km/h` };
+    }
+    if (rainChancePct >= 70) {
+        return { severity: 'severe', reason: `${Math.round(rainChancePct)}% chance of rain` };
+    }
+    return {
+        severity: 'mild',
+        reason: `winds ${Math.round(windKmh)} km/h, ${Math.round(rainChancePct)}% rain chance`,
+    };
+}
+/**
+ * Real-infrastructure nodes backed by the Open-Meteo public APIs
+ * (keyless, CORS-enabled): geocoding + weather forecast.
+ */
+export function registerWeatherNodes(registry) {
+    registry.register({
+        type: 'GeocodeCity',
+        label: 'Geocode City',
+        description: 'Resolves a city name to coordinates via the Open-Meteo geocoding API.',
+        category: 'http',
+        traceKind: 'http',
+        traceDetail: 'GET https://geocoding-api.open-meteo.com/v1/search?name={city}&count=1',
+        // city is input-drivable (e.g. from an Input node); config is the fallback.
+        inputSchema: {
+            fields: [{ name: 'city', type: 'string' }],
+        },
+        configSchema: {
+            fields: [{ name: 'city', type: 'string', required: true }],
+        },
+        outputSchema: {
+            fields: [
+                { name: 'place', type: 'string' },
+                { name: 'country', type: 'string' },
+                { name: 'latitude', type: 'number' },
+                { name: 'longitude', type: 'number' },
+            ],
+        },
+    }, async (ctx) => {
+        const city = String(ctx.input.city ?? '');
+        if (!city)
+            throw new Error('No city configured');
+        const url = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(city)}&count=1`;
+        ctx.log('info', `GET ${url}`);
+        const response = await fetch(url);
+        if (!response.ok)
+            throw new Error(`Geocoding failed: HTTP ${response.status}`);
+        const data = (await response.json());
+        const hit = data.results?.[0];
+        if (!hit)
+            throw new Error(`No location found for "${city}"`);
+        ctx.log('info', `Resolved ${hit.name}, ${hit.country} → ${hit.latitude}, ${hit.longitude}`);
+        return {
+            place: hit.name,
+            country: hit.country,
+            latitude: hit.latitude,
+            longitude: hit.longitude,
+        };
+    });
+    registry.register({
+        type: 'FetchForecast',
+        label: 'Fetch Forecast',
+        description: 'Fetches live current conditions and today’s outlook from the Open-Meteo forecast API.',
+        category: 'http',
+        traceKind: 'http',
+        traceDetail: 'GET https://api.open-meteo.com/v1/forecast?latitude&longitude&current=temperature_2m,wind_speed_10m,weather_code&daily=…&forecast_days=1',
+        inputSchema: {
+            fields: [
+                { name: 'latitude', type: 'number', required: true },
+                { name: 'longitude', type: 'number', required: true },
+            ],
+        },
+        outputSchema: {
+            fields: [
+                { name: 'temperatureC', type: 'number' },
+                { name: 'windKmh', type: 'number' },
+                { name: 'weatherCode', type: 'number' },
+                { name: 'maxC', type: 'number' },
+                { name: 'minC', type: 'number' },
+                { name: 'rainChancePct', type: 'number' },
+            ],
+        },
+    }, async (ctx) => {
+        const latitude = Number(ctx.input.latitude);
+        const longitude = Number(ctx.input.longitude);
+        if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) {
+            throw new Error('latitude/longitude missing or not numbers');
+        }
+        const url = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}` +
+            '&current=temperature_2m,wind_speed_10m,weather_code' +
+            '&daily=temperature_2m_max,temperature_2m_min,precipitation_probability_max' +
+            '&timezone=auto&forecast_days=1';
+        ctx.log('info', `GET ${url}`);
+        const response = await fetch(url);
+        if (!response.ok)
+            throw new Error(`Forecast failed: HTTP ${response.status}`);
+        const data = (await response.json());
+        const output = {
+            temperatureC: data.current.temperature_2m,
+            windKmh: data.current.wind_speed_10m,
+            weatherCode: data.current.weather_code,
+            maxC: data.daily.temperature_2m_max[0],
+            minC: data.daily.temperature_2m_min[0],
+            rainChancePct: data.daily.precipitation_probability_max[0] ?? 0,
+        };
+        ctx.log('info', `Now ${output.temperatureC}°C, wind ${output.windKmh} km/h, code ${output.weatherCode}`);
+        return output;
+    });
+    registry.register({
+        type: 'SummarizeConditions',
+        label: 'Summarize Conditions',
+        description: 'Turns raw forecast numbers into a readable weather advisory.',
+        category: 'logic',
+        traceKind: 'compute',
+        inputSchema: {
+            fields: [
+                { name: 'place', type: 'string', required: true },
+                { name: 'temperatureC', type: 'number', required: true },
+                { name: 'windKmh', type: 'number', required: true },
+                { name: 'weatherCode', type: 'number', required: true },
+                { name: 'maxC', type: 'number' },
+                { name: 'minC', type: 'number' },
+                { name: 'rainChancePct', type: 'number' },
+            ],
+        },
+        outputSchema: {
+            fields: [
+                { name: 'headline', type: 'string' },
+                { name: 'range', type: 'string' },
+                { name: 'advice', type: 'string' },
+                { name: 'place', type: 'string' },
+                { name: 'temperatureC', type: 'number' },
+                { name: 'condition', type: 'string' },
+            ],
+        },
+    }, async (ctx) => {
+        const advisory = buildAdvisory({
+            place: String(ctx.input.place ?? 'Unknown'),
+            temperatureC: Number(ctx.input.temperatureC),
+            windKmh: Number(ctx.input.windKmh),
+            weatherCode: Number(ctx.input.weatherCode),
+            maxC: Number(ctx.input.maxC ?? ctx.input.temperatureC),
+            minC: Number(ctx.input.minC ?? ctx.input.temperatureC),
+            rainChancePct: Number(ctx.input.rainChancePct ?? 0),
+        });
+        ctx.log('info', advisory.headline);
+        ctx.log('info', `Advice: ${advisory.advice}`);
+        return advisory;
+    });
+    registry.register({
+        type: 'ClassifyWeather',
+        label: 'Classify Weather',
+        description: 'Grades conditions as severe or mild from wind and rain thresholds.',
+        category: 'logic',
+        traceKind: 'compute',
+        tags: ['branching'],
+        inputSchema: {
+            fields: [
+                { name: 'windKmh', type: 'number', required: true },
+                { name: 'rainChancePct', type: 'number', required: true },
+                // Optional passthrough so fan-out consumers (e.g. a Collect
+                // gathering one verdict per city) keep the place name attached.
+                { name: 'place', type: 'string' },
+            ],
+        },
+        outputSchema: {
+            fields: [
+                { name: 'severity', type: 'enum', enumValues: ['severe', 'mild'] },
+                { name: 'reason', type: 'string' },
+                { name: 'place', type: 'string' },
+            ],
+        },
+    }, async (ctx) => {
+        const { severity, reason } = classifyWeather(Number(ctx.input.windKmh), Number(ctx.input.rainChancePct));
+        ctx.log('info', `Severity ${severity}: ${reason}`);
+        return {
+            severity,
+            reason,
+            ...(ctx.input.place !== undefined ? { place: ctx.input.place } : {}),
+        };
+    });
+    registry.register({
+        type: 'ComposeAlert',
+        label: 'Compose Alert',
+        description: 'Formats a severe-weather alert line for a place.',
+        category: 'logic',
+        traceKind: 'compute',
+        inputSchema: {
+            fields: [
+                { name: 'place', type: 'string', required: true },
+                { name: 'reason', type: 'string', required: true },
+            ],
+        },
+        outputSchema: {
+            fields: [
+                { name: 'alert', type: 'string' },
+                { name: 'place', type: 'string' },
+            ],
+        },
+    }, async (ctx) => {
+        const place = String(ctx.input.place ?? 'the area');
+        const reason = String(ctx.input.reason ?? 'conditions worsening');
+        const alert = `⚠ Weather alert for ${place}: ${reason}`;
+        ctx.log('info', alert);
+        return { alert, place };
+    });
+}

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@xdelivered/emberflow",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Visual builder and runner for API operations modelled as node graphs, with scenarios, mocks and agent skills.",
+  "keywords": ["api", "workflow", "node-graph", "low-code", "visual-builder", "agent-skills"],
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pmccurley87/emberflow.git"
+  },
+  "bin": { "emberflow": "bin/emberflow.mjs" },
+  "exports": {
+    ".": {
+      "types": "./dist/src/config.d.ts",
+      "default": "./dist/src/config.js"
+    },
+    "./engine": {
+      "types": "./dist/src/engine/index.d.ts",
+      "default": "./dist/src/engine/index.js"
+    },
+    "./server/environments": {
+      "types": "./dist/server/environments.d.ts",
+      "default": "./dist/server/environments.js"
+    }
+  },
+  "files": ["bin", "server", "src", "dist", "studio-dist", "templates", "README.md"],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "build:studio": "vite build",
+    "build:lib": "tsc -p tsconfig.build.json && node scripts/fix-dist-imports.mjs dist",
+    "prepack": "npm run build:studio && npm run build:lib",
+    "prepare": "node scripts/prepare-if-source.mjs",
+    "lint": "oxlint",
+    "typecheck": "tsc -b && tsc --noEmit -p server/tsconfig.json",
+    "preview": "vite preview",
+    "server": "tsx watch server/index.ts",
+    "dev:project": "EMBERFLOW_PROJECT=examples/demo-project tsx watch server/index.ts",
+    "cli": "tsx server/cli.ts",
+    "mcp": "tsx server/mcp.ts",
+    "test": "vitest run",
+    "smoke": "bash scripts/smoke-install.sh"
+  },
+  "dependencies": {
+    "@fontsource-variable/inter": "^5.2.8",
+    "@fontsource/ibm-plex-mono": "^5.2.7",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@radix-ui/react-dialog": "^1.1.18",
+    "@radix-ui/react-popover": "^1.1.18",
+    "@radix-ui/react-slot": "^1.3.0",
+    "@radix-ui/react-tabs": "^1.1.16",
+    "@tailwindcss/vite": "^4.3.2",
+    "@types/suncalc": "^1.9.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "express": "^5.2.1",
+    "lucide-react": "^1.23.0",
+    "pg": "^8.22.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-resizable-panels": "^2.1.9",
+    "react-syntax-highlighter": "^16.1.1",
+    "suncalc": "^2.0.0",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.2",
+    "tw-animate-css": "^1.4.0",
+    "zustand": "^5.0.14"
+  },
+  "peerDependencies": {
+    "tsx": "^4.22.5"
+  },
+  "peerDependenciesMeta": {
+    "tsx": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^24.13.2",
+    "@types/pg": "^8.20.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@types/react-syntax-highlighter": "^15.5.13",
+    "@vitejs/plugin-react": "^6.0.3",
+    "oxlint": "^1.71.0",
+    "tsx": "^4.22.5",
+    "typescript": "~6.0.2",
+    "vite": "^8.1.1",
+    "vitest": "^4.1.9"
+  }
+}

package/server/agentRoute.test.ts

@@ -0,0 +1,157 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+// Task 2 review finding: the `setup-environments` agent intent (route
+// validation added in server/index.ts, ~L712) shipped without a test that
+// boots a real runner and drives POST /agent end to end. This covers the
+// accept path (no flowId/environment required) and the two reject paths
+// (missing instruction; an action outside the allowlist), against a real
+// runner subprocess the way server/mockServe.test.ts does.
+
+const PORT = 8151;
+const base = `http://127.0.0.1:${PORT}`;
+
+async function waitHealthy(url: string, tries = 40): Promise<void> {
+  for (let i = 0; i < tries; i++) {
+    try {
+      if ((await fetch(url)).ok) return;
+    } catch {
+      /* not up yet */
+    }
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  throw new Error('runner did not become healthy');
+}
+
+function git(dir: string, args: string[]): void {
+  execFileSync('git', args, { cwd: dir, stdio: 'ignore' });
+}
+
+let proc: ChildProcess;
+let projectDir: string;
+let codexStubPath: string;
+
+async function postAgent(body: unknown): Promise<Response> {
+  return fetch(`${base}/agent`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+}
+
+beforeAll(async () => {
+  projectDir = mkdtempSync(join(tmpdir(), 'agentroute-'));
+  mkdirSync(join(projectDir, 'emberflow', 'apis', 'default'), { recursive: true });
+  writeFileSync(join(projectDir, 'emberflow.config.mjs'), 'export default {};\n');
+  // Minimal real operation so ask-with-flowId can resolve a relPath.
+  writeFileSync(
+    join(projectDir, 'emberflow', 'apis', 'default', 'hello.json'),
+    JSON.stringify({
+      id: 'default/hello',
+      name: 'Hello',
+      version: 1,
+      nodes: [
+        { id: 'in', type: 'Input', label: 'Input', position: { x: 0, y: 0 }, config: {} },
+        { id: 'out', type: 'Result', label: 'Result', position: { x: 300, y: 0 }, config: {}, inputMap: { value: { sourceNodeId: 'in', sourceField: '$' } } },
+      ],
+      edges: [{ id: 'e1', source: 'in', target: 'out' }],
+      createdAt: '2026-07-12T00:00:00Z',
+      updatedAt: '2026-07-12T00:00:00Z',
+    }),
+  );
+
+  // AgentRunManager.start() requires a git repo (isGitRepo check) before it
+  // will snapshot + spawn — give the fixture project one, with an initial
+  // commit so the snapshot has something to diff against.
+  git(projectDir, ['init']);
+  git(projectDir, ['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'add', '-A']);
+  git(projectDir, ['-c', 'user.email=test@example.com', '-c', 'user.name=Test', 'commit', '-m', 'init']);
+
+  // A harmless stand-in for the codex CLI: an accepted setup-environments
+  // intent spawns the coding agent for real, so without this the test would
+  // shell out to an actual `codex` binary. EMBERFLOW_CODEX_BIN (consumed by
+  // AgentRunManager.start(), server/agents/runManager.ts) overrides the bin
+  // passed to spawnCodex (server/agents/codexAdapter.ts), which spawns it
+  // directly with codex's CLI args and reads its stdout as JSON lines. Exiting
+  // 0 with no stdout is enough for the adapter to reach a clean 'done'/'error'
+  // terminal state without any real agent behavior.
+  codexStubPath = join(projectDir, 'fake-codex.sh');
+  writeFileSync(codexStubPath, '#!/bin/sh\nexit 0\n');
+  chmodSync(codexStubPath, 0o755);
+
+  proc = spawn('npx', ['tsx', 'server/index.ts'], {
+    env: {
+      ...process.env,
+      EMBERFLOW_RUNNER_PORT: String(PORT),
+      EMBERFLOW_PROJECT: projectDir,
+      EMBERFLOW_CODEX_BIN: codexStubPath,
+    },
+    stdio: 'ignore',
+  });
+
+  await waitHealthy(`${base}/healthz`);
+}, 20_000);
+
+afterAll(() => {
+  proc?.kill();
+  if (projectDir) rmSync(projectDir, { recursive: true, force: true });
+});
+
+describe('POST /agent — setup-environments route validation', () => {
+  it('accepts a setup-environments intent WITHOUT flowId or environment', async () => {
+    const res = await postAgent({ intent: { action: 'setup-environments', instruction: 'dev and prod' } });
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(typeof body.agentRunId).toBe('string');
+    expect(body.agentRunId.length).toBeGreaterThan(0);
+  });
+
+  it('400s a setup-environments intent with no instruction', async () => {
+    const res = await postAgent({ intent: { action: 'setup-environments' } });
+    expect(res.status).toBe(400);
+  });
+
+  it('400s an action outside the allowlist, mentioning the unsupported action', async () => {
+    const res = await postAgent({ intent: { action: 'nonsense', instruction: 'x' } });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(typeof body.error).toBe('string');
+    expect(body.error).toContain('nonsense');
+  });
+});
+
+/** The run manager is single-flight per project (409 while a previous stub run
+ *  winds down) — retry briefly so route-validation asserts don't race it. */
+async function postAgentWhenFree(body: unknown): Promise<Response> {
+  for (let i = 0; i < 40; i++) {
+    const res = await postAgent(body);
+    if (res.status !== 409) return res;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return postAgent(body);
+}
+
+describe('POST /agent — ask route validation', () => {
+  it('accepts an ask intent WITHOUT flowId', async () => {
+    const res = await postAgentWhenFree({ intent: { action: 'ask', instruction: 'where is the slack rendering?' } });
+    expect(res.status).toBe(201);
+    const body = await res.json();
+    expect(typeof body.agentRunId).toBe('string');
+  });
+
+  it('accepts an ask intent WITH a flowId', async () => {
+    const res = await postAgentWhenFree({ intent: { action: 'ask', flowId: 'default/hello', instruction: 'what does this op do?' } });
+    expect(res.status).toBe(201);
+  });
+
+  it('400s an ask intent with a non-string flowId', async () => {
+    const res = await postAgent({ intent: { action: 'ask', flowId: 42, instruction: 'x' } });
+    expect(res.status).toBe(400);
+    const body = await res.json();
+    expect(body.error).toContain('flowId');
+  });
+});