@lazyingart/agintiflow 0.20.122 → 0.20.124

package/README.md

@@ -103,11 +103,15 @@ 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 quietly 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. If startup is blocked or unavailable, the same header row shows the recovery hint; run `/webapp [port]` inside the CLI to retry.
+
+Package installation also makes a best-effort, non-blocking webapp initialization. Install never fails because the optional local webapp could not start.
+
+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 +133,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.122",
+  "version": "0.20.124",
   "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",
@@ -50,6 +50,7 @@
     "scripts/install-docker-ubuntu.sh",
     "scripts/setup-agent-toolchain-docker.sh",
     "scripts/real-deepseek-capabilities.js",
+    "scripts/postinstall-webapp.js",
     "scripts/smoke-auxiliary-tools.js",
     "scripts/smoke-auth.js",
     "scripts/smoke-aaps-adapter.js",
@@ -68,7 +69,10 @@
     "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-webapp-command.js",
+    "scripts/smoke-web-port-fallback.js",
     "src/",
     "run.js",
     "skills/",
@@ -100,11 +104,15 @@
     "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:webapp-command": "node scripts/smoke-webapp-command.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",
+    "postinstall": "node scripts/postinstall-webapp.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:webapp-command && 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/postinstall-webapp.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ensureAgintiWebApp } from "../src/web-autostart.js";
+
+const packageDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const cwd = process.env.INIT_CWD || process.cwd();
+
+if (process.env.CI === "true" || process.env.AGINTIFLOW_SKIP_POSTINSTALL_WEBAPP === "1") {
+  process.exit(0);
+}
+
+try {
+  await ensureAgintiWebApp({
+    packageDir,
+    cwd,
+    host: process.env.AGINTI_WEB_HOST || "127.0.0.1",
+    preferredPort: process.env.AGINTI_WEB_PORT || 3210,
+    language: process.env.AGINTI_LANGUAGE || "",
+  });
+} catch {
+  // Installation must not fail because the optional local webapp could not be started.
+}

package/scripts/smoke-cli-chat.js

@@ -317,6 +317,24 @@ 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");
+  }
+  const launchHeaderWithWebError = buildLaunchHeaderLines({
+    width: 120,
+    packageVersion: "0.0.0",
+    animated: false,
+    webAppNotice: "webapp unavailable - use /webapp to retry; error: smoke failure",
+  }).join("\n");
+  if (!launchHeaderWithWebError.includes("webapp unavailable - use /webapp to retry")) {
+    throw new Error("launch header did not render webapp recovery advice in the tagline row");
+  }
   if (
     formatElapsedDuration(0) !== "00:00" ||
     formatElapsedDuration(65_000) !== "01:05" ||
@@ -641,6 +659,7 @@ try {
     !helpResult.stdout.includes("/auxiliary") ||
     !helpResult.stdout.includes("/review") ||
     !helpResult.stdout.includes("/scs") ||
+    !helpResult.stdout.includes("/webapp") ||
     !helpResult.stdout.includes("/safe") ||
     helpResult.stdout.includes("helpReview") ||
     helpResult.stdout.includes("helpRename") ||

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/scripts/smoke-webapp-command.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { execFile as execFileCallback, spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+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-webapp-command-"));
+const execFile = promisify(execFileCallback);
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+async function waitFor(predicate, child, label, output) {
+  const deadline = Date.now() + 12000;
+  while (Date.now() < deadline) {
+    if (predicate()) return true;
+    if (child.exitCode !== null) break;
+    await delay(150);
+  }
+  const { stdout, stderr } = output;
+  throw new Error(`${label} timed out. stdout=${stdout.slice(-1000)} stderr=${stderr.slice(-1000)}`);
+}
+
+async function killPort(port) {
+  try {
+    const { stdout: pids } = await execFile("lsof", [`-tiTCP:${port}`, "-sTCP:LISTEN"]);
+    for (const pid of pids.split(/\s+/).filter(Boolean)) {
+      try {
+        process.kill(Number(pid), "SIGTERM");
+      } catch {
+        // Ignore already-exited listeners.
+      }
+    }
+  } catch {
+    // lsof may be unavailable; the temporary port listener will otherwise be reusable by later tests.
+  }
+}
+
+async function runCase({ port, env = {}, expectHeader, label }) {
+  const output = { stdout: "", stderr: "" };
+  const child = spawn(process.execPath, [path.join(repoRoot, "bin/aginti-cli.js"), "chat", "--provider", "mock", "--routing", "manual", "--port", String(port)], {
+    cwd: runtimeDir,
+    env: {
+      ...process.env,
+      AGINTIFLOW_NO_ANIMATION: "1",
+      AGINTIFLOW_HOME: path.join(runtimeDir, `.agintiflow-home-${label}`),
+      ...env,
+    },
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  child.stdout.on("data", (chunk) => {
+    output.stdout += chunk.toString();
+  });
+  child.stderr.on("data", (chunk) => {
+    output.stderr += chunk.toString();
+  });
+
+  try {
+    await waitFor(() => output.stdout.includes(expectHeader), child, `${label} launch header`, output);
+    child.stdin.write(`/webapp ${port}\n`);
+    await waitFor(() => output.stdout.includes(`webapp=http://127.0.0.1:${port}`), child, `${label} /webapp command`, output);
+    const health = await fetch(`http://127.0.0.1:${port}/health`).then((response) => response.json());
+    if (!health.ok || health.app !== "agintiflow" || Number(health.port) !== port) {
+      throw new Error(`invalid /webapp health response for ${label}: ${JSON.stringify(health)}`);
+    }
+  } finally {
+    child.kill("SIGTERM");
+    await killPort(port);
+  }
+}
+
+const autoPort = 45600 + Math.floor(Math.random() * 300);
+const manualPort = autoPort + 301;
+
+try {
+  await runCase({
+    port: autoPort,
+    expectHeader: `webapp: http://127.0.0.1:${autoPort}`,
+    label: "auto-start",
+  });
+  await runCase({
+    port: manualPort,
+    env: { AGINTIFLOW_NO_WEB_AUTO_START: "1" },
+    expectHeader: "webapp auto-start disabled - use /webapp to start manually",
+    label: "manual-disabled",
+  });
+  console.log(`webapp slash command smoke passed: http://127.0.0.1:${autoPort}, http://127.0.0.1:${manualPort}`);
+} finally {
+  await killPort(autoPort);
+  await killPort(manualPort);
+  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,29 @@ 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) };
+  }
+}
+
+function webAppNotice(result) {
+  if (!result || result.ok) return "";
+  if (result.disabled) return "webapp auto-start disabled - use /webapp to start manually";
+  const error = String(result.error || "unknown").replace(/\s+/g, " ").trim();
+  const compact = error.length > 84 ? `${error.slice(0, 83)}…` : error;
+  return `webapp unavailable - use /webapp to retry; error: ${compact}`;
+}
+
 const CLI_VALUE_OPTIONS = new Set([
   "--port",
   "--host",
@@ -1734,9 +1758,12 @@ export async function main(argv = process.argv.slice(2)) {
     if (!prompt) {
       const parsedResumeOptions = parseArgs(resumeOptions.optionArgv);
       exitOnUnknownOptions(parsedResumeOptions);
+      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 : "",
+        webAppNotice: webAppNotice(webLaunch),
       });
       return;
     }
@@ -1744,6 +1771,7 @@ export async function main(argv = process.argv.slice(2)) {
     exitOnUnknownOptions(parsedResumeArgs);
     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;
@@ -1763,7 +1791,13 @@ 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 : "",
+      webAppNotice: webAppNotice(webLaunch),
+    });
     return;
   }
 
@@ -1808,6 +1842,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/i18n.js

@@ -139,6 +139,7 @@ const TRANSLATIONS = {
     helpSkills: "List Markdown skills selected for a topic.",
     helpSkillMesh: "Manage strict reviewed skill sharing.",
     helpProfile: "Set task profile, e.g. code, website, latex, maintenance.",
+    helpWebapp: "Start or reuse the local webapp and print its URL.",
     helpWebSearch: "Enable or disable the web_search tool.",
     helpEnableScs: "Toggle Student-Committee-Supervisor gated execution.",
     helpScouts: "Enable parallel DeepSeek scouts and set scout count.",

package/src/interactive-cli.js

@@ -43,6 +43,7 @@ import {
   permissionModeForApprovalCategory,
   permissionModeLabel,
 } from "./permission-modes.js";
+import { ensureAgintiWebApp } from "./web-autostart.js";
 
 const useColor = Boolean(input.isTTY && output.isTTY && process.env.AGINTIFLOW_NO_COLOR !== "1");
 const ansi = {
@@ -95,6 +96,8 @@ const SLASH_COMMANDS = [
   "/skillsync",
   "/profile",
   "/web-search",
+  "/webapp",
+  "/web",
   "/web-research",
   "/image-read",
   "/research-wrapper",
@@ -772,10 +775,19 @@ 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 = "",
+  webAppNotice = "",
+} = {}) {
   const subtitle = t("launchSubtitle", language);
   const credit = t("launchCredit", language);
-  const tagline = t("launchTagline", language);
+  const webappLine = webAppUrl ? `webapp: ${webAppUrl}` : webAppNotice;
+  const tagline = webappLine || 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);
@@ -794,16 +806,16 @@ export function buildLaunchHeaderLines({ packageVersion = "", frame = 2, width =
     row(centerLine(subtitle, contentWidth), ansi.dim),
     row(centerLine(credit, contentWidth), ansi.dim),
     tagline ? mid : "",
-    tagline ? row(centerLine(tagline, contentWidth), ansi.cyan) : "",
+    tagline ? row(centerLine(compactLine(tagline, contentWidth), contentWidth), webAppUrl ? ansi.cyan : ansi.yellow) : "",
     bottom,
   ].filter(Boolean);
   const indent = " ".repeat(Math.max(Math.floor((terminalColumns - Math.max(...boxLines.map((line) => visualLength(line)))) / 2), 0));
   return boxLines.map((line) => `${indent}${line}`);
 }
 
-async function renderLaunchHeader(packageVersion = "", language = cliLanguage) {
+async function renderLaunchHeader(packageVersion = "", language = cliLanguage, webAppUrl = "", webAppNotice = "") {
   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, webAppNotice }).join("\n"));
     return;
   }
 
@@ -812,7 +824,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, webAppNotice })];
     if (previousLineCount > 0) output.write(`\x1b[${previousLineCount}A`);
     output.write(lines.map((line) => `\r${ansi.clearLine}${line}`).join("\n"));
     output.write("\n");
@@ -849,6 +861,7 @@ function printHelp() {
       `  ${command("/skills [query]", "List Markdown skills selected for a topic.", "helpSkills")}`,
       `  ${command("/skillmesh [status|off|record|share|sync]", "Manage strict reviewed skill sharing.", "helpSkillMesh")}`,
       `  ${command("/profile <name>", "Set task profile, e.g. code, website, latex, maintenance.", "helpProfile")}`,
+      `  ${command("/webapp [port]", "Start or reuse the local webapp and print its URL.", "helpWebapp")}`,
       `  ${command("/web-search on|off", "Enable or disable the web_search tool.", "helpWebSearch")}`,
       `  ${command("/web-research <query>", "Run a sourced web_research turn with persisted evidence.", "helpWebSearch")}`,
       `  ${command("/image-read <path> [question]", "Run read_image on a workspace screenshot/image.", "helpWebSearch")}`,
@@ -2170,6 +2183,8 @@ function createState(args = {}) {
     dynamicStepHardCap: args.dynamicStepHardCap,
     dynamicStepExtensionSize: args.dynamicStepExtensionSize,
     sessionId: args.resume || "",
+    webAppUrl: args.webAppUrl || "",
+    webAppNotice: args.webAppNotice || "",
   };
 }
 
@@ -2975,6 +2990,28 @@ async function handleCommand(line, state, packageDir) {
     );
     return true;
   }
+  if (command === "webapp" || command === "web") {
+    const port = Number(value) || Number(process.env.AGINTI_WEB_PORT || process.env.PORT || 3210);
+    printSystemLine("webapp=starting");
+    const result = await ensureAgintiWebApp({
+      packageDir,
+      cwd: state.commandCwd || process.cwd(),
+      host: process.env.AGINTI_WEB_HOST || process.env.HOST || "127.0.0.1",
+      preferredPort: port,
+      language: state.language,
+      respectAutoStartDisable: false,
+    }).catch((error) => ({ ok: false, error: error instanceof Error ? error.message : String(error), url: "" }));
+    if (result.ok) {
+      state.webAppUrl = result.url;
+      state.webAppNotice = "";
+      printSystemLine(`webapp=${result.url} ${result.reused ? "reused" : "started"}`);
+    } else {
+      state.webAppUrl = "";
+      state.webAppNotice = `webapp unavailable - use /webapp to retry; error: ${compactLine(result.error || "unknown", 72)}`;
+      printSystemLine(state.webAppNotice);
+    }
+    return true;
+  }
   if (command === "language" || command === "lang") {
     if (!value) {
       printSystemLine(tr("languageSet", { language: state.language || cliLanguage, label: languageLabel(state.language || cliLanguage) }));
@@ -3599,12 +3636,6 @@ async function handleCommand(line, state, packageDir) {
     printAgentMessage(`initialized project=${result.projectRoot}\nAGINTI.md=${result.instructionsPath}\ntemplate=${result.template}`);
     return true;
   }
-  if (command === "web") {
-    const port = value || "3220";
-    printAgentMessage(`Run in another terminal: aginti web --port ${port}`);
-    return true;
-  }
-
   const typed = `/${command}`;
   const suggestions = SLASH_COMMANDS.filter((candidate) => candidate.startsWith(typed));
   printAgentMessage(
@@ -3808,8 +3839,8 @@ async function runPrompt(prompt, state, packageDir, { approvalDepth = 0 } = {})
   return queuedAfterFinish;
 }
 
-export async function startInteractiveCli(args = {}, { packageDir, packageVersion } = {}) {
-  const state = createState(args);
+export async function startInteractiveCli(args = {}, { packageDir, packageVersion, webAppUrl = "", webAppNotice = "" } = {}) {
+  const state = createState({ ...args, webAppUrl, webAppNotice });
   const detachProcessInterrupts = installProcessInterruptHandlers();
   setCliLanguage(state.language);
   const rl =
@@ -3822,7 +3853,7 @@ export async function startInteractiveCli(args = {}, { packageDir, packageVersio
           completer: commandCompleter,
         });
 
-  await renderLaunchHeader(packageVersion, state.language);
+  await renderLaunchHeader(packageVersion, state.language, state.webAppUrl, state.webAppNotice);
   printSystemLine(`${tr("project")}: ${process.cwd()}`);
   await maybeOnboardDeepSeekKey(state);
   printAgentMessage(tr("interactiveIntro"));

package/src/web-autostart.js

@@ -0,0 +1,122 @@
+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 = "",
+  respectAutoStartDisable = true,
+} = {}) {
+  if (respectAutoStartDisable && (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}`);