@lazyingart/agintiflow 0.20.121 → 0.20.123

package/README.md

@@ -103,11 +103,13 @@ Provider signup and key pages:
 | Qwen / DashScope | [https://bailian.console.aliyun.com/](https://bailian.console.aliyun.com/) | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` |
 | GRS AI image tools | [https://grsai.ai/dashboard/api-keys](https://grsai.ai/dashboard/api-keys) | Configure with `/auxiliary grsai` or `aginti login grsai` |
 
-Launch the web UI from the same project:
+The CLI auto-starts or reuses the local web UI from the same project. It tries `http://127.0.0.1:3210` first, then `3211`, `3212`, and so on if the port is already occupied. The active URL is shown in the CLI launch header.
+
+Launch the web UI explicitly when you want a foreground web server:
 
 ```bash
 aginti web --port 3210
-# open http://127.0.0.1:3210
+# opens http://127.0.0.1:3210, or the next available port
 ```
 
 Run without live model credentials for smoke tests:
@@ -129,7 +131,7 @@ aginti --language de
 | Goal | Command |
 | --- | --- |
 | Start interactive chat | `aginti` or `aginti chat` |
-| Start local web app | `aginti web --port 3210` |
+| Start local web app | Auto-starts with `aginti`; foreground mode is `aginti web --port 3210` |
 | Save provider keys | `aginti auth`, `/auth`, `/login` |
 | Review current repo | `/review [focus]` |
 | Toggle SCS quality gate | `/scs` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.121",
+  "version": "0.20.123",
   "type": "module",
   "description": "AgInTiFlow is a project-aware agent workspace for hybrid wet-dry R&D, hardware-aware intelligence, software automation, and industrial workflows.",
   "license": "Apache-2.0",
@@ -68,7 +68,9 @@
     "scripts/smoke-skillmesh.js",
     "scripts/smoke-tmux-tools.js",
     "scripts/smoke-toolchain-docker.js",
+    "scripts/smoke-web-autostart.js",
     "scripts/smoke-web-api.js",
+    "scripts/smoke-web-port-fallback.js",
     "src/",
     "run.js",
     "skills/",
@@ -100,11 +102,13 @@
     "smoke:permission-modes": "node scripts/smoke-permission-modes.js",
     "smoke:tmux-tools": "node scripts/smoke-tmux-tools.js",
     "smoke:web-api": "node scripts/smoke-web-api.js",
+    "smoke:web-autostart": "node scripts/smoke-web-autostart.js",
+    "smoke:web-port-fallback": "node scripts/smoke-web-port-fallback.js",
     "smoke:autoupdate": "node scripts/smoke-auto-update.js",
     "real:deepseek": "node scripts/real-deepseek-capabilities.js",
     "supervision:seed": "node scripts/seed-supervised-homework.js",
     "storage:migrate": "node bin/aginti-cli.js storage migrate",
-    "test": "npm run check && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:auth && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:tmux-tools && npm run smoke:cli-chat && npm run smoke:inbox",
+    "test": "npm run check && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:web-autostart && npm run smoke:web-port-fallback && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:auth && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:tmux-tools && npm run smoke:cli-chat && npm run smoke:inbox",
     "pack:dry-run": "npm pack --dry-run",
     "smoke:capabilities": "node scripts/smoke-capabilities.js"
   },

package/references/agintiflow-aaps-slogan-subtext-v3.md

@@ -14,7 +14,7 @@ AgInTiFlow is a project-aware agent workspace for hybrid wet-dry R&D, hardware-a
 
 Project-oriented programming for agentic workflows.
 
-AAPS is a prompt-native programming language and visual studio for turning prompts into structured, verifiable pipelines. It connects wet and dry experiments, hardware and software, and human intent with executable agent work through tasks, typed inputs, declared outputs, validation gates, recovery steps, and durable artifacts.
+AAPS is a project oriented and prompt-native programming language and visual studio for turning prompts into structured, verifiable pipelines. It connects wet and dry experiments, hardware and software, and human intent with executable agent work through tasks, typed inputs, declared outputs, validation gates, recovery steps, and durable artifacts.
 
 ## Shorter Version
 

package/scripts/smoke-cli-chat.js

@@ -317,6 +317,15 @@ try {
   if (launchHeader.includes("launchTagline")) {
     throw new Error("empty launch tagline should not render the i18n key name");
   }
+  const launchHeaderWithWeb = buildLaunchHeaderLines({
+    width: 120,
+    packageVersion: "0.0.0",
+    animated: false,
+    webAppUrl: "http://127.0.0.1:3210",
+  }).join("\n");
+  if (!launchHeaderWithWeb.includes("webapp: http://127.0.0.1:3210")) {
+    throw new Error("launch header did not render the active webapp URL in the tagline row");
+  }
   if (
     formatElapsedDuration(0) !== "00:00" ||
     formatElapsedDuration(65_000) !== "01:05" ||
@@ -746,6 +755,30 @@ try {
     throw new Error("resume history should render full saved messages instead of compact previews");
   }
 
+  const explicitCwd = path.join(tempRoot, "explicit-cwd");
+  await fs.mkdir(explicitCwd, { recursive: true });
+  await runCli([
+    "--no-auto-update",
+    "--provider",
+    "mock",
+    "--routing",
+    "manual",
+    "--cwd",
+    explicitCwd,
+    "--sandbox-mode",
+    "host",
+    "--allow-file-tools",
+    "Create reports/cwd-smoke.md with a one-line cwd smoke note.",
+  ], "");
+  const explicitCwdOutput = path.join(explicitCwd, "reports", "cwd-smoke.md");
+  const wrongCwdOutput = path.join(tempRoot, "reports", "cwd-smoke.md");
+  if (!(await fs.stat(explicitCwdOutput).then((stat) => stat.isFile()).catch(() => false))) {
+    throw new Error("one-shot --cwd did not write into the explicit command cwd");
+  }
+  if (await fs.stat(wrongCwdOutput).then((stat) => stat.isFile()).catch(() => false)) {
+    throw new Error("one-shot --cwd wrote into the process cwd instead of the explicit command cwd");
+  }
+
   await runTmuxInterruptSmoke({ key: "Escape", expected: /Active run stopped|Session saved/ });
   await runTmuxInterruptSmoke({ key: "C-c", expected: /EXIT:130|Session stopped by ctrl-c|Interrupted\. Session saved/ });
 
@@ -787,6 +820,7 @@ try {
           "interactive-chat",
           "mock-file-write",
           "run-status",
+          "one-shot-cwd",
           "tmux-escape-active-run-stop",
           "tmux-ctrl-c-session-stop",
           "resume-latest",

package/scripts/smoke-permission-modes.js

@@ -65,6 +65,16 @@ async function main() {
   assert(parsedDanger.sandboxMode === "host", "danger should set host sandbox");
   assert(parsedDanger.allowDestructive === true, "danger should allow destructive shell");
   assert(parsedDanger.allowOutsideWorkspaceFileTools === true, "danger should allow outside workspace file tools");
+  const explicitPackageBeforeSafety = parseArgs(["--package-install-policy", "block", "-s", "normal", "--provider", "mock", "hello"]);
+  assert(
+    explicitPackageBeforeSafety.packageInstallPolicy === "block",
+    "CLI -s normal should not override an explicit earlier --package-install-policy block"
+  );
+  const explicitSandboxBeforeSafety = parseArgs(["--sandbox-mode", "docker-readonly", "-s", "danger", "--provider", "mock", "hello"]);
+  assert(
+    explicitSandboxBeforeSafety.sandboxMode === "docker-readonly",
+    "CLI -s danger should not override an explicit earlier --sandbox-mode docker-readonly"
+  );
 
   const safe = configFor("safe");
   assert(safe.permissionMode === "safe", "runtime safe mode not set");

package/scripts/smoke-web-autostart.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureAgintiWebApp } from "../src/web-autostart.js";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const runtimeDir = await fs.mkdtemp(path.join(os.tmpdir(), "agintiflow-web-autostart-"));
+const preferredPort = 44500 + Math.floor(Math.random() * 1000);
+let childPid = 0;
+
+try {
+  const first = await ensureAgintiWebApp({
+    packageDir: repoRoot,
+    cwd: runtimeDir,
+    preferredPort,
+    host: "127.0.0.1",
+  });
+  if (!first.ok || !first.started || !first.url.includes(`:${preferredPort}`)) {
+    throw new Error(`expected auto-start on preferred port, got ${JSON.stringify(first)}`);
+  }
+  childPid = Number(first.pid) || 0;
+  const health = await fetch(`${first.url}/health`).then((response) => response.json());
+  if (!health.ok || Number(health.port) !== preferredPort) {
+    throw new Error(`auto-started web health was invalid: ${JSON.stringify(health)}`);
+  }
+  const second = await ensureAgintiWebApp({
+    packageDir: repoRoot,
+    cwd: runtimeDir,
+    preferredPort,
+    host: "127.0.0.1",
+  });
+  if (!second.ok || !second.reused || second.url !== first.url) {
+    throw new Error(`expected second auto-start call to reuse existing webapp, got ${JSON.stringify(second)}`);
+  }
+  console.log(`web auto-start smoke passed: ${first.url}`);
+} finally {
+  if (childPid) {
+    try {
+      process.kill(childPid, "SIGTERM");
+    } catch {
+      // The child may have already exited during a failed smoke test.
+    }
+  }
+  await fs.rm(runtimeDir, { recursive: true, force: true });
+}

package/scripts/smoke-web-port-fallback.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const runtimeDir = await fs.mkdtemp(path.join(os.tmpdir(), "agintiflow-web-port-fallback-"));
+const host = "127.0.0.1";
+const occupiedPort = 43100 + Math.floor(Math.random() * 1200);
+
+function listenOccupier(port) {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once("error", reject);
+    server.listen(port, host, () => resolve(server));
+  });
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitForPrintedPort(child, stdout, stderr) {
+  const deadline = Date.now() + 12000;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) break;
+    const match = stdout().match(/http:\/\/127\.0\.0\.1:(\d+)/);
+    if (match) return Number(match[1]);
+    await delay(100);
+  }
+  throw new Error(`web fallback URL was not printed. stdout=${stdout()} stderr=${stderr()}`);
+}
+
+async function waitForHealth(port, child, stdout, stderr) {
+  const deadline = Date.now() + 12000;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) break;
+    try {
+      const response = await fetch(`http://${host}:${port}/health`);
+      const body = await response.json();
+      if (response.ok && body.ok && Number(body.port) === port) return body;
+    } catch {
+      await delay(200);
+    }
+  }
+  throw new Error(`web fallback health failed. stdout=${stdout()} stderr=${stderr()}`);
+}
+
+const occupier = await listenOccupier(occupiedPort);
+let stdout = "";
+let stderr = "";
+const child = spawn(process.execPath, [path.join(repoRoot, "bin/aginti-cli.js"), "web", "--port", String(occupiedPort), "--host", host], {
+  cwd: runtimeDir,
+  env: {
+    ...process.env,
+    AGINTIFLOW_RUNTIME_DIR: runtimeDir,
+    AGINTIFLOW_HOME: path.join(runtimeDir, ".agintiflow-home"),
+  },
+  stdio: ["ignore", "pipe", "pipe"],
+});
+child.stdout.on("data", (chunk) => {
+  stdout += chunk.toString();
+});
+child.stderr.on("data", (chunk) => {
+  stderr += chunk.toString();
+});
+
+try {
+  const actualPort = await waitForPrintedPort(child, () => stdout.slice(-500), () => stderr.slice(-500));
+  if (actualPort <= occupiedPort) {
+    throw new Error(`web command did not move past occupied port ${occupiedPort}; got ${actualPort}`);
+  }
+  await waitForHealth(actualPort, child, () => stdout.slice(-500), () => stderr.slice(-500));
+  console.log(`web port fallback smoke passed: ${occupiedPort} -> ${actualPort}`);
+} finally {
+  child.kill("SIGTERM");
+  occupier.close();
+  await fs.rm(runtimeDir, { recursive: true, force: true });
+}

package/src/cli.js

@@ -37,6 +37,7 @@ import { handleSkillMeshCommand } from "./skillmesh.js";
 import { handleAapsCliCommand } from "./aaps-adapter.js";
 import { formatInstructionTemplateList, normalizeInstructionTemplate } from "./behavior-contract.js";
 import { applyPermissionMode, normalizePermissionMode } from "./permission-modes.js";
+import { ensureAgintiWebApp } from "./web-autostart.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -91,6 +92,21 @@ function printUnknownCliOptions(options = []) {
   console.error("Use `--` before a prompt that intentionally starts with a dash.");
 }
 
+async function maybeEnsureDefaultWebApp(args = {}, { commandCwd = process.cwd() } = {}) {
+  if (args.web) return { ok: false, url: "" };
+  try {
+    return await ensureAgintiWebApp({
+      packageDir,
+      cwd: args.commandCwd || commandCwd || process.cwd(),
+      host: args.host || process.env.AGINTI_WEB_HOST || "127.0.0.1",
+      preferredPort: args.port || process.env.AGINTI_WEB_PORT || 3210,
+      language: args.language ? resolveLanguage(args.language) : "",
+    });
+  } catch (error) {
+    return { ok: false, url: "", error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
 const CLI_VALUE_OPTIONS = new Set([
   "--port",
   "--host",
@@ -513,7 +529,7 @@ export function parseArgs(argv) {
     }
     if (arg === "-s" || arg === "--safety" || arg === "--permission-mode") {
       const mode = normalizePermissionMode(readOption(argv, i), "");
-      if (mode) applyPermissionMode(result, mode, { override: true });
+      if (mode) applyPermissionMode(result, mode, { override: false });
       i += 1;
       continue;
     }
@@ -1606,19 +1622,20 @@ export async function main(argv = process.argv.slice(2)) {
   if (commandArgv[0] === "doctor") {
     const parsed = parseArgs(commandArgv.slice(1).filter((arg) => arg !== "--json" && arg !== "--capabilities"));
     exitOnUnknownOptions(parsed);
+    const effectiveCommandCwd = parsed.commandCwd || commandCwd;
     const config = loadConfig(
       {
         ...parsed,
         goal: "doctor",
-        commandCwd,
+        commandCwd: effectiveCommandCwd,
         allowShellTool: parsed.allowShellTool ?? true,
         allowFileTools: parsed.allowFileTools ?? true,
       },
-      { packageDir, baseDir: commandCwd }
+      { packageDir, baseDir: effectiveCommandCwd }
     );
     const report = commandArgv.includes("--capabilities")
-      ? await buildCapabilityReport(commandCwd, packageJson.version, config)
-      : await doctorReport(commandCwd, packageJson.version, config);
+      ? await buildCapabilityReport(effectiveCommandCwd, packageJson.version, config)
+      : await doctorReport(effectiveCommandCwd, packageJson.version, config);
     if (commandArgv.includes("--json")) console.log(JSON.stringify(report, null, 2));
     else if (commandArgv.includes("--capabilities")) printCapabilityReport(report);
     else printDoctorReport(report);
@@ -1628,17 +1645,18 @@ export async function main(argv = process.argv.slice(2)) {
   if (commandArgv[0] === "capabilities") {
     const parsed = parseArgs(commandArgv.slice(1).filter((arg) => arg !== "--json"));
     exitOnUnknownOptions(parsed);
+    const effectiveCommandCwd = parsed.commandCwd || commandCwd;
     const config = loadConfig(
       {
         ...parsed,
         goal: "capabilities",
-        commandCwd,
+        commandCwd: effectiveCommandCwd,
         allowShellTool: parsed.allowShellTool ?? true,
         allowFileTools: parsed.allowFileTools ?? true,
       },
-      { packageDir, baseDir: commandCwd }
+      { packageDir, baseDir: effectiveCommandCwd }
     );
-    const report = await buildCapabilityReport(commandCwd, packageJson.version, config);
+    const report = await buildCapabilityReport(effectiveCommandCwd, packageJson.version, config);
     if (commandArgv.includes("--json")) console.log(JSON.stringify(report, null, 2));
     else printCapabilityReport(report);
     return;
@@ -1732,22 +1750,26 @@ export async function main(argv = process.argv.slice(2)) {
     if (!prompt) {
       const parsedResumeOptions = parseArgs(resumeOptions.optionArgv);
       exitOnUnknownOptions(parsedResumeOptions);
-      await startInteractiveCli(agentDefaults({ ...parsedResumeOptions, resume: sessionId, commandCwd }), {
+      const webLaunch = await maybeEnsureDefaultWebApp(parsedResumeOptions, { commandCwd });
+      await startInteractiveCli(agentDefaults({ ...parsedResumeOptions, resume: sessionId, commandCwd: parsedResumeOptions.commandCwd || commandCwd }), {
         packageDir,
         packageVersion: packageJson.version,
+        webAppUrl: webLaunch.ok ? webLaunch.url : "",
       });
       return;
     }
     const parsedResumeArgs = parseArgs([...resumeOptions.optionArgv, prompt]);
     exitOnUnknownOptions(parsedResumeArgs);
-    const resumeArgs = agentDefaults({ ...parsedResumeArgs, resume: sessionId, goal: prompt, commandCwd });
+    const resumeArgs = agentDefaults({ ...parsedResumeArgs, resume: sessionId, goal: prompt, commandCwd: parsedResumeArgs.commandCwd || commandCwd });
     if (!(await ensureDeepSeekKeyForOneShot(resumeArgs))) process.exit(1);
+    await maybeEnsureDefaultWebApp(resumeArgs, { commandCwd });
     const config = loadConfig(resumeArgs, { packageDir });
     await runAgent(config);
     return;
   }
 
-  const args = { ...parseArgs(commandArgv), commandCwd };
+  const parsedArgs = parseArgs(commandArgv);
+  const args = { ...parsedArgs, commandCwd: parsedArgs.commandCwd || commandCwd };
   exitOnUnknownOptions(args);
 
   if (args.web) {
@@ -1760,7 +1782,8 @@ export async function main(argv = process.argv.slice(2)) {
   }
 
   if (args.interactive || (!args.goal && !args.resume && process.stdin.isTTY)) {
-    await startInteractiveCli(agentDefaults(args), { packageDir, packageVersion: packageJson.version });
+    const webLaunch = await maybeEnsureDefaultWebApp(args, { commandCwd });
+    await startInteractiveCli(agentDefaults(args), { packageDir, packageVersion: packageJson.version, webAppUrl: webLaunch.ok ? webLaunch.url : "" });
     return;
   }
 
@@ -1805,6 +1828,7 @@ export async function main(argv = process.argv.slice(2)) {
 
   const finalArgs = agentDefaults(args);
   if (!(await ensureDeepSeekKeyForOneShot(finalArgs))) process.exit(1);
+  await maybeEnsureDefaultWebApp(finalArgs, { commandCwd });
   const config = loadConfig(finalArgs, { packageDir });
   await runAgent(config);
 }

package/src/interactive-cli.js

@@ -772,10 +772,10 @@ function launchTitleLines(contentWidth) {
   return largeWidth <= contentWidth ? LARGE_LAUNCH_TITLE : COMPACT_LAUNCH_TITLE;
 }
 
-export function buildLaunchHeaderLines({ packageVersion = "", frame = 2, width = terminalWidth(), animated = true, language = cliLanguage } = {}) {
+export function buildLaunchHeaderLines({ packageVersion = "", frame = 2, width = terminalWidth(), animated = true, language = cliLanguage, webAppUrl = "" } = {}) {
   const subtitle = t("launchSubtitle", language);
   const credit = t("launchCredit", language);
-  const tagline = t("launchTagline", language);
+  const tagline = webAppUrl ? `webapp: ${webAppUrl}` : t("launchTagline", language);
   const version = packageVersion ? `v${packageVersion}` : "";
   const terminalColumns = Math.max(Number(width) || 80, 50);
   const contentWidth = Math.min(Math.max(terminalColumns - 8, 58), 112);
@@ -801,9 +801,9 @@ export function buildLaunchHeaderLines({ packageVersion = "", frame = 2, width =
   return boxLines.map((line) => `${indent}${line}`);
 }
 
-async function renderLaunchHeader(packageVersion = "", language = cliLanguage) {
+async function renderLaunchHeader(packageVersion = "", language = cliLanguage, webAppUrl = "") {
   if (!useColor || process.env.AGINTIFLOW_NO_ANIMATION === "1") {
-    console.log(buildLaunchHeaderLines({ packageVersion, animated: false, language }).join("\n"));
+    console.log(buildLaunchHeaderLines({ packageVersion, animated: false, language, webAppUrl }).join("\n"));
     return;
   }
 
@@ -812,7 +812,7 @@ async function renderLaunchHeader(packageVersion = "", language = cliLanguage) {
   let previousLineCount = 0;
   output.write(ansi.cursorHide);
   for (let frame = 0; frame < 18; frame += 1) {
-    const lines = [...paddingLines, ...buildLaunchHeaderLines({ packageVersion, frame, animated: true, language })];
+    const lines = [...paddingLines, ...buildLaunchHeaderLines({ packageVersion, frame, animated: true, language, webAppUrl })];
     if (previousLineCount > 0) output.write(`\x1b[${previousLineCount}A`);
     output.write(lines.map((line) => `\r${ansi.clearLine}${line}`).join("\n"));
     output.write("\n");
@@ -3808,7 +3808,7 @@ async function runPrompt(prompt, state, packageDir, { approvalDepth = 0 } = {})
   return queuedAfterFinish;
 }
 
-export async function startInteractiveCli(args = {}, { packageDir, packageVersion } = {}) {
+export async function startInteractiveCli(args = {}, { packageDir, packageVersion, webAppUrl = "" } = {}) {
   const state = createState(args);
   const detachProcessInterrupts = installProcessInterruptHandlers();
   setCliLanguage(state.language);
@@ -3822,7 +3822,7 @@ export async function startInteractiveCli(args = {}, { packageDir, packageVersio
           completer: commandCompleter,
         });
 
-  await renderLaunchHeader(packageVersion, state.language);
+  await renderLaunchHeader(packageVersion, state.language, webAppUrl);
   printSystemLine(`${tr("project")}: ${process.cwd()}`);
   await maybeOnboardDeepSeekKey(state);
   printAgentMessage(tr("interactiveIntro"));

package/src/web-autostart.js

@@ -0,0 +1,121 @@
+import { spawn } from "node:child_process";
+import http from "node:http";
+import net from "node:net";
+import path from "node:path";
+
+const DEFAULT_HOST = "127.0.0.1";
+const DEFAULT_PORT = 3210;
+const MAX_PORT_ATTEMPTS = 50;
+
+function normalizeHost(host) {
+  return String(host || process.env.AGINTI_WEB_HOST || process.env.HOST || DEFAULT_HOST).trim() || DEFAULT_HOST;
+}
+
+function normalizePort(port) {
+  const parsed = Number(port || process.env.AGINTI_WEB_PORT || process.env.PORT || DEFAULT_PORT);
+  return Number.isInteger(parsed) && parsed > 0 && parsed < 65536 ? parsed : DEFAULT_PORT;
+}
+
+function webUrl(host, port) {
+  return `http://${host}:${port}`;
+}
+
+function fetchHealth(host, port, timeoutMs = 450) {
+  return new Promise((resolve) => {
+    const req = http.get(`${webUrl(host, port)}/health`, { timeout: timeoutMs }, (res) => {
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => {
+        body += chunk;
+      });
+      res.on("end", () => {
+        try {
+          const json = JSON.parse(body || "{}");
+          resolve(Boolean(res.statusCode === 200 && json.ok && (json.app === "agintiflow" || Number(json.port) === port)));
+        } catch {
+          resolve(false);
+        }
+      });
+    });
+    req.on("timeout", () => {
+      req.destroy();
+      resolve(false);
+    });
+    req.on("error", () => resolve(false));
+  });
+}
+
+function canListen(host, port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.listen(port, host, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+async function waitForHealth(host, port, timeoutMs = 7000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await fetchHealth(host, port, 350)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 150));
+  }
+  return false;
+}
+
+export async function findReusableOrFreeWebPort({ host = DEFAULT_HOST, preferredPort = DEFAULT_PORT, attempts = MAX_PORT_ATTEMPTS } = {}) {
+  const startPort = normalizePort(preferredPort);
+  const normalizedHost = normalizeHost(host);
+  for (let offset = 0; offset < attempts; offset += 1) {
+    const port = startPort + offset;
+    if (port >= 65536) break;
+    if (await fetchHealth(normalizedHost, port)) {
+      return { port, host: normalizedHost, url: webUrl(normalizedHost, port), reused: true, available: false };
+    }
+    if (await canListen(normalizedHost, port)) {
+      return { port, host: normalizedHost, url: webUrl(normalizedHost, port), reused: false, available: true };
+    }
+  }
+  return { port: 0, host: normalizedHost, url: "", reused: false, available: false };
+}
+
+export async function ensureAgintiWebApp({
+  packageDir = process.cwd(),
+  cwd = process.cwd(),
+  host = DEFAULT_HOST,
+  preferredPort = DEFAULT_PORT,
+  language = "",
+} = {}) {
+  if (process.env.AGINTI_NO_WEB_AUTO_START === "1" || process.env.AGINTIFLOW_NO_WEB_AUTO_START === "1") {
+    return { ok: false, disabled: true, url: "" };
+  }
+
+  const candidate = await findReusableOrFreeWebPort({ host, preferredPort });
+  if (!candidate.port) {
+    return { ok: false, error: `No available AgInTiFlow web port from ${normalizePort(preferredPort)}.`, url: "" };
+  }
+  if (candidate.reused) {
+    return { ok: true, reused: true, started: false, ...candidate };
+  }
+
+  const child = spawn(process.execPath, [path.join(packageDir, "web.js")], {
+    cwd,
+    detached: true,
+    stdio: "ignore",
+    env: {
+      ...process.env,
+      HOST: candidate.host,
+      PORT: String(candidate.port),
+      AGINTIFLOW_RUNTIME_DIR: cwd,
+      AGINTIFLOW_PACKAGE_DIR: packageDir,
+      ...(language ? { AGINTI_LANGUAGE: language } : {}),
+    },
+  });
+  child.unref();
+
+  const healthy = await waitForHealth(candidate.host, candidate.port);
+  return healthy
+    ? { ok: true, reused: false, started: true, pid: child.pid, ...candidate }
+    : { ok: false, error: `Started web process ${child.pid}, but ${candidate.url}/health did not become ready.`, url: "" };
+}

package/web.js

@@ -58,7 +58,7 @@ loadProjectEnv(baseDir);
 await ensureProjectSessionStorage(baseDir);
 
 const app = express();
-const port = Number(process.env.PORT || 3210);
+let port = Number(process.env.PORT || 3210);
 const host = process.env.HOST || "127.0.0.1";
 const runs = new Map();
 const db = new WebDatabase(baseDir);
@@ -1337,12 +1337,39 @@ app.post("/api/runs/:sessionId/stop", async (req, res) => {
 });
 
 app.get("/health", (_req, res) => {
-  res.json({ ok: true, port });
+  res.json({ ok: true, app: "agintiflow", port, url: `http://${host}:${port}` });
 });
 
 await fs.mkdir(sessionsDir, { recursive: true });
 await syncStoredSessions();
 
-app.listen(port, host, () => {
-  console.log(`Website control agent UI running on http://${host}:${port}`);
-});
+function listenOnPort(candidatePort) {
+  return new Promise((resolve, reject) => {
+    const server = app.listen({ port: candidatePort, host });
+    server.once("error", (error) => reject(error));
+    server.once("listening", () => resolve(server));
+  });
+}
+
+async function listenWithFallback(preferredPort, attempts = 50) {
+  const startPort = Number.isInteger(Number(preferredPort)) && Number(preferredPort) > 0 ? Number(preferredPort) : 3210;
+  let lastError = null;
+  for (let offset = 0; offset < attempts; offset += 1) {
+    const candidatePort = startPort + offset;
+    if (candidatePort >= 65536) break;
+    try {
+      return await listenOnPort(candidatePort);
+    } catch (error) {
+      lastError = error;
+      if (error?.code !== "EADDRINUSE") throw error;
+    }
+  }
+  const error = new Error(`No available AgInTiFlow web port from ${startPort} after ${attempts} attempts.`);
+  error.cause = lastError;
+  throw error;
+}
+
+export const webServer = await listenWithFallback(port);
+port = webServer.address()?.port || port;
+export const webUrl = `http://${host}:${port}`;
+console.log(`Website control agent UI running on ${webUrl}`);