@lazyingart/agintiflow 0.8.3 → 0.8.5

package/README.md

@@ -54,7 +54,7 @@ aginti
 aginti chat
 ```
 
-Inside chat, type normal requests such as `write a small Python CLI app with tests`. The default is now Docker workspace mode with approved package installs, so coding, plotting, and LaTeX tasks can set up project-local tools without touching the host. Use `/help` for commands, `/latex on` for PDF work, `/docker off` only when you intentionally want host mode, `/sessions` to list project runs, and `/resume <session-id>` to continue work. Ctrl+C exits cleanly and prints a resume command when a session exists.
+Inside chat, type normal requests such as `write a small Python CLI app with tests`. The default is Docker workspace mode with approved package installs, so coding, plotting, and LaTeX tasks can set up project-local tools without touching the host. Use `/help` for commands, `/latex on` for PDF work, `/docker off` only when you intentionally want host mode, `/sessions` to list project runs, and `/resume latest` or `/resume <session-id>` to continue work. Esc or Ctrl+C stops the active run cleanly and prints the resume command.
 
 Launch the local web UI from an installed package:
 
@@ -80,6 +80,8 @@ aginti capabilities
 aginti doctor --capabilities
 aginti sessions list
 aginti sessions show <session-id>
+aginti resume
+aginti resume latest
 aginti resume <session-id> "continue with a short follow-up"
 aginti queue <session-id> "extra instruction for the running agent"
 aginti --profile code "write a small Python CLI app with tests"
@@ -338,7 +340,7 @@ Package policy values:
 
 Toolchain commands such as `python3 plot.py`, `latexmk -pdf paper.tex`, and `pdflatex -interaction=nonstopmode -halt-on-error paper.tex` are allowlisted only when the shell tool is enabled. In Docker mode the project folder is mounted as `/workspace`; any file written to `/workspace/report.pdf` appears on the host as `<your-project>/report.pdf`. CLI runs print both the host workspace and the Docker mapping before execution. File and canvas tools accept both normal relative paths and Docker virtual paths like `/workspace/report.pdf`, while other absolute host paths remain blocked.
 
-The web chat mirrors the CLI session store. Enter sends, Ctrl+J inserts a newline, and Tab submits/queues the message. Queued input is written to `.sessions/<session-id>/inbox.jsonl`; the running agent drains that pipe between steps and after tool calls.
+The web chat mirrors the CLI session store. Enter sends, Ctrl+J inserts a newline, Tab submits/queues the message, and Esc stops the active run. Queued input is written to `.sessions/<session-id>/inbox.jsonl`; the running agent drains that pipe between steps and after tool calls. Generated local sites should use the built-in `preview_workspace` or `open_workspace_file` tools; AgInTiFlow avoids transient localhost servers inside Docker because those containers stop between commands and their ports are not host-published.
 
 Safe preflight endpoints:
 

package/docs/agent-runtime-pipe.md

@@ -9,6 +9,10 @@ AgInTiFlow keeps CLI and web runs equivalent by using the project folder as the
 
 When a run is active, the web chat and `aginti queue <session-id> "..."` append messages to the inbox instead of trying to mutate the running process directly. The runner drains the inbox at safe boundaries: before each model step and after tool execution. This mirrors the event-queue style used by mature agent UIs while keeping the backend decoupled from any specific frontend.
 
+Runs can be stopped without corrupting session state. The CLI listens for Esc or Ctrl+C during an active run, and the web UI exposes a Stop button plus Esc. Both paths send an abort signal, persist `session.stopped`, and leave the session resumable through `aginti resume <session-id>`.
+
 Default execution is Docker workspace mode with package installs approved inside the sandbox. The project is mounted at `/workspace`; persistent agent toolchain folders are mounted at `/aginti-home`, `/aginti-cache`, and `/aginti-env` from `~/.agintiflow/docker/`. Python, conda, and other language-level environments should be installed under `/aginti-env` so they survive across runs. Apt/apk package changes are ephemeral unless the Docker image is rebuilt.
 
+Generated local websites should use `preview_workspace` or `open_workspace_file`. The preview tool serves the host workspace on an automatically selected `127.0.0.1` port and opens it in the browser. AgInTiFlow blocks common transient Docker preview commands such as `python -m http.server` because each shell tool call runs in a short-lived container with no published host port.
+
 The failed `f(f(x)) = f'(x)` LaTeX task exposed three issues: host-mode command policy blocked setup/path commands, a 15-step budget was too small for iterative numerical work plus TeX output, and follow-up input could not be queued while the agent was running. The current runtime defaults and inbox pipe address those without hardcoding that specific math task.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "type": "module",
   "description": "AgInTiFlow is a resumable Playwright website-control agent with OpenAI-compatible tool calling.",
   "license": "Apache-2.0",

package/public/app.js

@@ -76,6 +76,9 @@ const translations = {
     dockerImageLabel: "Docker image",
     dockerImagePlaceholder: "agintiflow-sandbox:latest",
     startRunButton: "Start run",
+    stopRunButton: "Stop",
+    stoppingRun: "Stopping...",
+    stopRunFailed: "Failed to stop run.",
     runOutputTitle: "Run output",
     noRunStarted: "No run started.",
     conversationTitle: "Conversation",
@@ -643,6 +646,7 @@ const packageInstallPolicyField = document.querySelector("#packageInstallPolicy"
 const packageWarningEl = document.querySelector("#package-warning");
 const logsEl = document.querySelector("#logs");
 const runMetaEl = document.querySelector("#run-meta");
+const stopRunButton = document.querySelector("#stop-run");
 const keyStatusEl = document.querySelector("#key-status");
 const allowWrapperToolsField = document.querySelector("#allowWrapperTools");
 const preferredWrapperField = document.querySelector("#preferredWrapper");
@@ -697,6 +701,7 @@ let routingPresets = {};
 let taskProfiles = [];
 let projectInfo = null;
 let currentSessionId = "";
+let currentRunStatus = "";
 let pollTimer = null;
 let saveTimer = null;
 let lastChatEntries = [];
@@ -728,6 +733,12 @@ function setLogs(text, mode = "active") {
   logsEl.textContent = text;
 }
 
+function updateStopRunButton() {
+  if (!stopRunButton) return;
+  stopRunButton.hidden = currentRunStatus !== "running";
+  stopRunButton.disabled = currentRunStatus !== "running";
+}
+
 function renderKeyStatus(status = lastKeyStatus) {
   lastKeyStatus = status;
   if (!status) return;
@@ -949,6 +960,7 @@ function applyLanguage(language, { persist = true } = {}) {
   renderSessionManager();
   renderChat(lastChatEntries);
   renderArtifactShell();
+  updateStopRunButton();
   if (persist) schedulePreferenceSave();
 }
 
@@ -1429,11 +1441,13 @@ async function refreshRun() {
   const response = await fetch(`/api/runs/${encodeURIComponent(currentSessionId)}`);
   if (!response.ok) return;
   const run = await response.json();
+  currentRunStatus = run.status || "";
+  updateStopRunButton();
   runMetaEl.textContent = `${run.status} · ${run.sessionId}`;
   renderLogs(run);
   await refreshArtifacts({ loadSelected: artifactTunnelDialog?.open });
 
-  if (run.status === "finished" || run.status === "failed") {
+  if (run.status === "finished" || run.status === "failed" || run.status === "stopped") {
     clearInterval(pollTimer);
     pollTimer = null;
     await refreshChat();
@@ -1443,6 +1457,22 @@ async function refreshRun() {
   }
 }
 
+async function stopCurrentRun() {
+  if (!currentSessionId || currentRunStatus !== "running") return;
+  stopRunButton.disabled = true;
+  chatStatusEl.textContent = t("stoppingRun");
+  const response = await fetch(`/api/runs/${encodeURIComponent(currentSessionId)}/stop`, {
+    method: "POST",
+  });
+  if (!response.ok) {
+    const data = await response.json().catch(() => ({}));
+    chatStatusEl.textContent = data.error || t("stopRunFailed");
+    updateStopRunButton();
+    return;
+  }
+  await refreshRun();
+}
+
 async function refreshChat() {
   if (!currentSessionId) {
     renderChat([]);
@@ -1771,6 +1801,24 @@ chatInputEl.addEventListener("keydown", (event) => {
   }
 });
 
+stopRunButton?.addEventListener("click", () => {
+  stopCurrentRun().catch((error) => {
+    chatStatusEl.textContent = String(error);
+    updateStopRunButton();
+  });
+});
+
+window.addEventListener("keydown", (event) => {
+  if (event.key !== "Escape" || currentRunStatus !== "running") return;
+  const tag = event.target?.tagName?.toLowerCase();
+  if (tag === "select" || tag === "button") return;
+  event.preventDefault();
+  stopCurrentRun().catch((error) => {
+    chatStatusEl.textContent = String(error);
+    updateStopRunButton();
+  });
+});
+
 form.addEventListener("submit", async (event) => {
   event.preventDefault();
 
@@ -1802,6 +1850,8 @@ form.addEventListener("submit", async (event) => {
   }
 
   currentSessionId = data.sessionId;
+  currentRunStatus = "running";
+  updateStopRunButton();
   sessionSelectEl.value = currentSessionId;
   runMetaEl.textContent = `${t("runningStatus").replace("...", "")} · ${currentSessionId}`;
   await refreshSessions();
@@ -1817,6 +1867,8 @@ form.addEventListener("submit", async (event) => {
 sessionSelectEl.addEventListener("change", async () => {
   currentSessionId = sessionSelectEl.value;
   if (!currentSessionId) {
+    currentRunStatus = "";
+    updateStopRunButton();
     runMetaEl.textContent = "";
     setLogs(t("noRunSelected"), "empty");
     renderChat([]);
@@ -1862,6 +1914,8 @@ chatFormEl.addEventListener("submit", async (event) => {
   }
 
   currentSessionId = data.sessionId;
+  currentRunStatus = data.queued ? currentRunStatus : "running";
+  updateStopRunButton();
   chatInputEl.value = "";
   chatStatusEl.textContent = data.queued ? t("queuedStatus") : t("runningStatus");
   if (data.queued) {

package/public/index.html

@@ -307,7 +307,10 @@
         <section class="panel output-panel">
           <div class="header-row">
             <h2 data-i18n="runOutputTitle">Run output</h2>
-            <div id="run-meta" class="subtle"></div>
+            <div class="run-header-actions">
+              <button id="stop-run" type="button" class="secondary danger" data-i18n="stopRunButton" hidden>Stop</button>
+              <div id="run-meta" class="subtle"></div>
+            </div>
           </div>
           <pre id="logs" class="logs" data-i18n="noRunStarted">No run started.</pre>
         </section>

package/public/styles.css

@@ -346,6 +346,15 @@ button.danger {
   justify-content: space-between;
 }
 
+.run-header-actions {
+  display: flex;
+  min-width: 0;
+  flex-wrap: wrap;
+  gap: 10px;
+  align-items: center;
+  justify-content: flex-end;
+}
+
 .sandbox-card {
   display: grid;
   gap: 12px;

package/scripts/smoke-cli-chat.js

@@ -10,19 +10,19 @@ const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "agintiflow-cli-chat-")
 const binPath = path.join(repoRoot, "bin/aginti-cli.js");
 
 function runChat(inputText) {
+  return runCli(["chat", "--provider", "mock", "--routing", "manual", "--profile", "code"], inputText);
+}
+
+function runCli(args, inputText) {
   return new Promise((resolve, reject) => {
-    const child = spawn(
-      process.execPath,
-      [binPath, "chat", "--provider", "mock", "--routing", "manual", "--profile", "code"],
-      {
-        cwd: tempRoot,
-        stdio: ["pipe", "pipe", "pipe"],
-        env: {
-          ...process.env,
-          AGINTIFLOW_RUNTIME_DIR: "",
-        },
-      }
-    );
+    const child = spawn(process.execPath, [binPath, ...args], {
+      cwd: tempRoot,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        AGINTIFLOW_RUNTIME_DIR: "",
+      },
+    });
 
     let stdout = "";
     let stderr = "";
@@ -60,12 +60,21 @@ try {
   if (!result.stdout.includes("Interactive agent chat")) {
     throw new Error("interactive chat did not print its banner");
   }
+  if (!result.stdout.includes("status=running workingOn=") || !result.stdout.includes("status=idle session=")) {
+    throw new Error("interactive chat did not print simple run status updates");
+  }
+
+  const latest = await runCli(["resume"], "/exit\n");
+  if (!latest.stdout.includes("session=") || !latest.stdout.includes("Interactive agent chat")) {
+    throw new Error("bare aginti resume did not open the latest session interactively");
+  }
+
   console.log(
     JSON.stringify(
       {
         ok: true,
         projectRoot: tempRoot,
-        checks: ["interactive-chat", "mock-file-write"],
+        checks: ["interactive-chat", "mock-file-write", "run-status", "resume-latest"],
       },
       null,
       2

package/src/agent-runner.js

@@ -1,6 +1,9 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
-import { exec as execCallback } from "node:child_process";
+import net from "node:net";
+import path from "node:path";
+import { exec as execCallback, spawn } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { promisify } from "node:util";
 import { chromium } from "playwright";
 import { createClient, createPlan, requestNextStep } from "./model-client.js";
@@ -11,13 +14,132 @@ import { ensureDockerSandboxReady, runDockerSandboxCommand } from "./docker-sand
 import { normalizeWrapperName, runAgentWrapper, wrapperStatusText } from "./tool-wrappers.js";
 import { evaluateCommandPolicy } from "./command-policy.js";
 import { redactSensitiveText, redactValue } from "./redaction.js";
-import { executeWorkspaceTool, summarizeWorkspaceTools, WORKSPACE_TOOL_NAMES } from "./workspace-tools.js";
+import { executeWorkspaceTool, resolveWorkspacePath, summarizeWorkspaceTools, WORKSPACE_TOOL_NAMES } from "./workspace-tools.js";
 import { normalizeCanvasPayload } from "./artifact-tunnel.js";
 import { getTaskProfile } from "./task-profiles.js";
 
 const exec = promisify(execCallback);
-const BROWSER_TOOLS = new Set(["open_url", "click", "type", "scroll", "press", "back"]);
+const BROWSER_TOOLS = new Set(["open_url", "open_workspace_file", "preview_workspace", "click", "type", "scroll", "press", "back"]);
 const WORKSPACE_TOOLS = new Set(WORKSPACE_TOOL_NAMES);
+const STATIC_PREVIEW_SERVER_PATH = fileURLToPath(new URL("./static-preview-server.js", import.meta.url));
+const previewServers = new Map();
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function throwIfAborted(config) {
+  if (config.abortSignal?.aborted) {
+    const reason = config.abortSignal.reason;
+    const error = reason instanceof Error ? reason : new Error("Run interrupted by user.");
+    error.name = error.name || "AbortError";
+    throw error;
+  }
+}
+
+function isAbortError(error, config = {}) {
+  return Boolean(
+    config.abortSignal?.aborted ||
+      error?.name === "AbortError" ||
+      error?.code === "ABORT_ERR" ||
+      /aborted|interrupted/i.test(String(error?.message || ""))
+  );
+}
+
+function abortable(promise, signal) {
+  if (!signal) return promise;
+  if (signal.aborted) {
+    return Promise.reject(signal.reason instanceof Error ? signal.reason : new Error("Run interrupted by user."));
+  }
+
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(signal.reason instanceof Error ? signal.reason : new Error("Run interrupted by user."));
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      }
+    );
+  });
+}
+
+async function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.once("listening", () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+async function findAvailablePort(preferredPort = 8765) {
+  const preferred = Number(preferredPort);
+  const start = Number.isFinite(preferred) && preferred > 0 ? preferred : 8765;
+  for (let port = start; port < start + 80; port += 1) {
+    if (await isPortAvailable(port)) return port;
+  }
+  throw new Error(`No available preview port found near ${start}.`);
+}
+
+async function waitForPort(port, signal) {
+  for (let attempt = 0; attempt < 30; attempt += 1) {
+    if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error("Preview interrupted.");
+    const connected = await new Promise((resolve) => {
+      const socket = net.connect({ host: "127.0.0.1", port });
+      socket.once("connect", () => {
+        socket.destroy();
+        resolve(true);
+      });
+      socket.once("error", () => {
+        socket.destroy();
+        resolve(false);
+      });
+      socket.setTimeout(500, () => {
+        socket.destroy();
+        resolve(false);
+      });
+    });
+    if (connected) return;
+    await sleep(100);
+  }
+  throw new Error(`Preview server did not become ready on port ${port}.`);
+}
+
+async function startPreviewServer(root, preferredPort, signal) {
+  const key = path.resolve(root);
+  const existing = previewServers.get(key);
+  if (existing && existing.child.exitCode === null) {
+    return existing;
+  }
+
+  const port = await findAvailablePort(preferredPort);
+  const child = spawn(process.execPath, [STATIC_PREVIEW_SERVER_PATH, key, String(port)], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  const server = { root: key, port, child, url: `http://127.0.0.1:${port}/` };
+  previewServers.set(key, server);
+  await waitForPort(port, signal);
+  return server;
+}
+
+function normalizeUrlPath(relativePath) {
+  const normalized = String(relativePath || ".").replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!normalized || normalized === ".") return "";
+  return normalized
+    .split("/")
+    .filter(Boolean)
+    .map((part) => encodeURIComponent(part))
+    .join("/");
+}
 
 function preserveAssistantMessage(message) {
   const preserved = {
@@ -148,7 +270,7 @@ function createInitialState(config, sessionId) {
               : "A host shell command tool is available under the configured trust policy."
             : "No shell command tool is available.",
           config.allowFileTools
-            ? `Workspace file tools are available in ${config.commandCwd}: list_files, read_file, search_files, write_file, and apply_patch. Always use workspace-relative paths such as plot_fx.svg or docs/report.tex, never absolute host paths. Secret paths, .git internals, node_modules writes, and huge files are blocked.`
+            ? `Workspace file tools are available in ${config.commandCwd}: list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, and preview_workspace. Always use workspace-relative paths such as plot_fx.svg or docs/report.tex, never absolute host paths. Secret paths, .git internals, node_modules writes, and huge files are blocked. For generated local websites/pages, use open_workspace_file or preview_workspace instead of starting a localhost server inside Docker.`
             : "No workspace file tools are available.",
           config.allowWrapperTools
             ? `External coding-agent wrappers are available as advisory tools only. Use the selected wrapper only: ${normalizeWrapperName(config.preferredWrapper)}. Wrapper status: ${wrapperStatusText()}.`
@@ -159,6 +281,7 @@ function createInitialState(config, sessionId) {
           "Work like a practical coding agent: inspect when useful, edit with file tools, run safe checks when they add confidence, and keep outputs inside the workspace.",
           "Use the canvas tunnel for outputs the user would likely want to inspect visually, such as figures, PDFs, screenshots, images, important markdown, or generated files.",
           "For environment or system-maintenance work, use the configured sandbox and package policy; Docker workspace mode is the preferred place for installs and toolchain setup.",
+          "If the user asks to open a generated local website or file, use open_workspace_file for a file or preview_workspace for a static site. Do not keep retrying the same localhost URL when a preview fails.",
           "Docker language/toolchain installs should prefer /aginti-env or project files so they persist across runs; apt/apk changes are ephemeral unless the image is rebuilt.",
           "If the run is close to the max-step limit, finish with the best complete artifact and honest limitations instead of starting a new approach.",
           "When the requested outcome is complete and a useful check has passed or been honestly skipped, stop and call finish.",
@@ -176,7 +299,9 @@ function createInitialState(config, sessionId) {
               ? `Shell working directory mounted into Docker as /workspace from ${config.commandCwd}. Use relative paths or /workspace paths, not absolute host temp paths. Persistent Docker env: /aginti-env, caches: /aginti-cache. Sandbox mode: ${config.sandboxMode}. Package install policy: ${config.packageInstallPolicy}.`
               : `Shell working directory: ${config.commandCwd}`
             : "",
-          config.allowFileTools ? `Workspace file tools enabled in: ${config.commandCwd}. Use workspace-relative paths.` : "",
+          config.allowFileTools
+            ? `Workspace file tools enabled in: ${config.commandCwd}. Use workspace-relative paths. Local preview tools available: open_workspace_file and preview_workspace.`
+            : "",
           config.allowWrapperTools
             ? `Agent wrappers: selected=${normalizeWrapperName(config.preferredWrapper)}; ${wrapperStatusText()}`
             : "",
@@ -278,7 +403,9 @@ function applyContinuationPrompt(state, config, observers) {
           ? `Shell working directory mounted into Docker as /workspace from ${config.commandCwd}. Use relative paths or /workspace paths. Persistent Docker env: /aginti-env, caches: /aginti-cache. Sandbox mode: ${config.sandboxMode}. Package install policy: ${config.packageInstallPolicy}.`
           : `Shell working directory: ${config.commandCwd}`
         : "",
-      config.allowFileTools ? `Workspace file tools enabled in: ${config.commandCwd}. Use workspace-relative paths.` : "",
+      config.allowFileTools
+        ? `Workspace file tools enabled in: ${config.commandCwd}. Use workspace-relative paths. For generated local files/sites, use open_workspace_file or preview_workspace.`
+        : "",
       config.allowWrapperTools
         ? `Agent wrappers: selected=${normalizeWrapperName(config.preferredWrapper)}; ${wrapperStatusText()}`
         : "",
@@ -374,16 +501,68 @@ function sanitizeToolResult(result) {
   return safeResult;
 }
 
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+async function applyToolLoopGuard(state, toolResult, store, observers) {
+  if (!toolResult || toolResult.done || toolResult.ok !== false) return;
+  state.meta.toolLoop = state.meta.toolLoop || { recent: [], warned: [] };
+  const signature = `${toolResult.toolName}:${stableStringify(toolResult.args || {})}`;
+  const entry = {
+    signature,
+    toolName: toolResult.toolName,
+    ok: Boolean(toolResult.ok),
+    blocked: Boolean(toolResult.blocked),
+    error: toolResult.error || toolResult.reason || "",
+    at: new Date().toISOString(),
+  };
+  state.meta.toolLoop.recent.push(entry);
+  state.meta.toolLoop.recent = state.meta.toolLoop.recent.slice(-20);
+
+  const failures = state.meta.toolLoop.recent.filter((item) => item.signature === signature && item.ok === false).length;
+  if (failures < 2 || state.meta.toolLoop.warned.includes(signature)) return;
+
+  state.meta.toolLoop.warned.push(signature);
+  state.meta.toolLoop.warned = state.meta.toolLoop.warned.slice(-20);
+  const message = [
+    `Loop guard: ${toolResult.toolName} with the same arguments has failed or been blocked ${failures} times.`,
+    "Do not repeat that exact call.",
+    "If this is a local workspace preview, use open_workspace_file or preview_workspace instead of repeatedly starting localhost servers or opening the same URL.",
+    "If enough work is complete, call finish with the usable local path or preview URL.",
+  ].join(" ");
+  state.messages.push({ role: "user", content: message });
+  await store.appendEvent("loop.guard", {
+    toolName: toolResult.toolName,
+    failures,
+    message,
+  });
+  observers.event("loop.guard", {
+    toolName: toolResult.toolName,
+    failures,
+    message,
+  });
+}
+
 async function runShellCommand(command, config, policy = evaluateCommandPolicy(command, config)) {
   try {
+    throwIfAborted(config);
     const result = config.useDockerSandbox
-      ? await runDockerSandboxCommand(command, config, policy)
+      ? await runDockerSandboxCommand(command, config, policy, { signal: config.abortSignal })
       : await exec(command, {
           cwd: config.commandCwd,
           timeout: 30000,
           maxBuffer: 200 * 1024,
           shell: "/bin/bash",
           env: safeExecutionEnv(),
+          signal: config.abortSignal,
         });
 
     return {
@@ -393,6 +572,7 @@ async function runShellCommand(command, config, policy = evaluateCommandPolicy(c
       stderr: redactSensitiveText(result.stderr).trim().slice(0, 4000),
     };
   } catch (error) {
+    if (isAbortError(error, config)) throw error;
     return {
       ok: false,
       exitCode: Number.isInteger(error?.code) ? error.code : 1,
@@ -424,6 +604,7 @@ async function captureSyntheticSnapshot(store, step, config) {
       "For draw/plot/graph/chart/diagram/figure requests, publish a canvas artifact proactively.",
       "For LaTeX/PDF requests, publish the source and compiled PDF artifacts when available. Keep subfolder outputs beside their source and use pdflatex-compatible figure formats.",
       "Use open_url only if the task actually needs the web.",
+      "For generated local HTML/SVG/PDF/site output, use open_workspace_file or preview_workspace instead of shelling a transient local server.",
     ]
       .filter(Boolean)
       .join(" "),
@@ -469,6 +650,7 @@ async function injectQueuedUserMessages(store, state, observers) {
 }
 
 async function executeTool(browserState, toolCall, snapshot, config, store, observers, state) {
+  throwIfAborted(config);
   const args = JSON.parse(toolCall.function.arguments || "{}");
   const safeArgs = sanitizeToolArgs(toolCall.function.name, args);
   const guard = checkToolUse({
@@ -520,8 +702,45 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
 
     switch (toolCall.function.name) {
       case "open_url":
-        await browserState.page.goto(String(args.url), { waitUntil: "domcontentloaded" });
+        await abortable(browserState.page.goto(String(args.url), { waitUntil: "domcontentloaded" }), config.abortSignal);
         break;
+      case "open_workspace_file": {
+        const target = resolveWorkspacePath(config, args.path || args.file || ".");
+        const stat = await fs.stat(target.absolutePath);
+        if (!stat.isFile()) throw new Error(`Workspace preview target is not a file: ${target.relativePath}`);
+        const fileUrl = pathToFileURL(target.absolutePath).href;
+        await abortable(browserState.page.goto(fileUrl, { waitUntil: "domcontentloaded" }), config.abortSignal);
+        const result = {
+          ok: true,
+          toolName: "open_workspace_file",
+          args: safeArgs,
+          path: target.relativePath,
+          url: browserState.page.url(),
+        };
+        await store.appendEvent("tool.completed", result);
+        observers.event("tool.completed", result);
+        return result;
+      }
+      case "preview_workspace": {
+        const target = resolveWorkspacePath(config, args.path || args.file || ".");
+        const stat = await fs.stat(target.absolutePath);
+        const server = await startPreviewServer(config.commandCwd, args.port || 8765, config.abortSignal);
+        const urlPath = stat.isDirectory() ? normalizeUrlPath(target.relativePath === "." ? "" : `${target.relativePath}/`) : normalizeUrlPath(target.relativePath);
+        const previewUrl = `${server.url}${urlPath}`;
+        await abortable(browserState.page.goto(previewUrl, { waitUntil: "domcontentloaded" }), config.abortSignal);
+        const result = {
+          ok: true,
+          toolName: "preview_workspace",
+          args: safeArgs,
+          path: target.relativePath,
+          url: browserState.page.url(),
+          port: server.port,
+          root: server.root,
+        };
+        await store.appendEvent("tool.completed", result);
+        observers.event("tool.completed", result);
+        return result;
+      }
       case "click": {
         const locator = browserState.page.locator(`[data-agent-id="${args.id}"]`).first();
         await locator.scrollIntoViewIfNeeded();
@@ -714,6 +933,7 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
     observers.event("tool.completed", result);
     return result;
   } catch (error) {
+    if (isAbortError(error, config)) throw error;
     const result = {
       ok: false,
       toolName: toolCall.function.name,
@@ -776,6 +996,7 @@ export async function runAgent(config) {
   });
 
   try {
+    throwIfAborted(config);
     if (!state.plan) {
       const plan = await createPlan(client, config, state);
       state.plan = plan;
@@ -834,6 +1055,7 @@ export async function runAgent(config) {
     }
 
     for (let step = state.stepsCompleted + 1; step <= config.maxSteps; step += 1) {
+      throwIfAborted(config);
       await injectQueuedUserMessages(store, state, observers);
       const snapshot = await buildSnapshot(browserState, store, step, config);
       state.meta.lastUrl = snapshot.url || state.meta.lastUrl;
@@ -881,6 +1103,7 @@ export async function runAgent(config) {
         })}`,
       });
 
+      throwIfAborted(config);
       const response = await requestNextStep(client, config, state.messages);
       const assistantMessage = response.choices[0]?.message;
       if (!assistantMessage) {
@@ -927,12 +1150,14 @@ export async function runAgent(config) {
       }
 
       for (const toolCall of toolCalls) {
+        throwIfAborted(config);
         const toolResult = await executeTool(browserState, toolCall, snapshot, config, store, observers, state);
         state.messages.push({
           role: "tool",
           tool_call_id: toolCall.id,
           content: JSON.stringify(toolResult),
         });
+        await applyToolLoopGuard(state, toolResult, store, observers);
 
         if (toolResult.toolName === "run_command") {
           observers.log("command.output", {
@@ -1014,6 +1239,24 @@ export async function runAgent(config) {
       stopped: true,
       reason: "max_steps_reached",
     };
+  } catch (error) {
+    if (!isAbortError(error, config)) throw error;
+    state.stepsCompleted = state.stepsCompleted || 0;
+    state.updatedAt = new Date().toISOString();
+    await store.saveState(state).catch(() => {});
+    await store.appendEvent("session.stopped", {
+      reason: "user_interrupt",
+    });
+    observers.event("session.stopped", {
+      reason: "user_interrupt",
+      sessionId,
+    });
+    return {
+      sessionId,
+      result: "",
+      stopped: true,
+      reason: "user_interrupt",
+    };
   } finally {
     await closeBrowser(browserState, store);
   }

package/src/cli.js

@@ -219,7 +219,7 @@ export function parseArgs(argv) {
 
 function printUsage() {
   console.log(
-    'Usage: aginti [chat] OR aginti web [--port 3210] OR aginti resume <session-id> ["prompt"] OR aginti queue <session-id> "message" OR aginti [--latex] [--routing smart|fast|complex|manual] [--provider deepseek|openai|mock] [--sandbox-mode host|docker-readonly|docker-workspace] [--package-install-policy block|prompt|allow] [--approve-package-installs] [--allow-shell|--no-shell] [--allow-destructive] [--allow-file-tools|--no-file-tools] [--allow-wrappers --wrapper codex] [--sandbox-status|--sandbox-preflight] "your task"'
+    'Usage: aginti [chat] OR aginti web [--port 3210] OR aginti resume [latest|<session-id>] ["prompt"] OR aginti queue <session-id> "message" OR aginti [--latex] [--routing smart|fast|complex|manual] [--provider deepseek|openai|mock] [--sandbox-mode host|docker-readonly|docker-workspace] [--package-install-policy block|prompt|allow] [--approve-package-installs] [--allow-shell|--no-shell] [--allow-destructive] [--allow-file-tools|--no-file-tools] [--allow-wrappers --wrapper codex] [--sandbox-status|--sandbox-preflight] "your task"'
   );
 }
 
@@ -356,6 +356,13 @@ async function handleSessionsCommand(argv) {
   process.exit(1);
 }
 
+async function resolveResumeSessionId(sessionId) {
+  if (sessionId && sessionId !== "latest") return sessionId;
+  const sessions = await listProjectSessions(process.cwd(), 1);
+  if (sessions[0]?.sessionId) return sessions[0].sessionId;
+  throw new Error("No project-local sessions found. Run `aginti sessions list` to check this folder.");
+}
+
 async function handleQueueCommand(argv) {
   const sessionId = argv[0] || "";
   const content = argv.slice(1).join(" ").trim();
@@ -456,23 +463,21 @@ export async function main(argv = process.argv.slice(2)) {
   }
 
   if (argv[0] === "resume") {
-    const sessionId = argv[1] || "";
+    let sessionId = argv[1] || "";
     const prompt = argv.slice(2).join(" ").trim();
-    if (!sessionId) {
-      console.error('Usage: aginti resume <session-id> ["new prompt"]');
+    try {
+      sessionId = await resolveResumeSessionId(sessionId);
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
       process.exit(1);
     }
-    if (!prompt && process.stdin.isTTY) {
+    if (!prompt) {
       await startInteractiveCli(agentDefaults({ ...parseArgs([]), resume: sessionId }), {
         packageDir,
         packageVersion: packageJson.version,
       });
       return;
     }
-    if (!prompt) {
-      console.error('Usage: aginti resume <session-id> "new prompt"');
-      process.exit(1);
-    }
     const config = loadConfig(agentDefaults({ ...parseArgs([prompt]), resume: sessionId, goal: prompt }), { packageDir });
     await runAgent(config);
     return;

package/src/docker-sandbox.js

@@ -37,6 +37,7 @@ async function execDocker(args, options = {}) {
   const execOptions = {
     timeout: options.timeout ?? 30000,
     maxBuffer: options.maxBuffer ?? 200 * 1024,
+    signal: options.signal,
   };
   recordSandboxLog("docker.command", { args });
 
@@ -283,11 +284,12 @@ function dockerRunArgs(command, config, policy = evaluateCommandPolicy(command,
   ];
 }
 
-export async function runDockerSandboxCommand(command, config, policy = evaluateCommandPolicy(command, config)) {
+export async function runDockerSandboxCommand(command, config, policy = evaluateCommandPolicy(command, config), options = {}) {
   const persistentDirs = await ensurePersistentDockerDirs(config);
   const result = await execDocker(dockerRunArgs(command, config, policy, persistentDirs), {
     timeout: policy.needsNetwork ? 120000 : policy.category === "toolchain" ? 90000 : 15000,
     maxBuffer: 300 * 1024,
+    signal: options.signal,
   });
 
   const payload = {

package/src/guardrails.js

@@ -31,6 +31,12 @@ const DESTRUCTIVE_PROMPT_HINTS = [
   "publish",
 ];
 
+function isTransientDockerPreviewCommand(command) {
+  return /\bpython3?\s+-m\s+http\.server\b|\bnpx\s+(?:--yes\s+)?(?:serve|http-server)\b|\bnpm\s+exec\s+(?:serve|http-server)\b|\bphp\s+-S\s+127\.0\.0\.1:/i.test(
+    command
+  );
+}
+
 function normalizeDomain(hostname) {
   return hostname.replace(/^www\./, "").toLowerCase();
 }
@@ -66,6 +72,13 @@ export function checkToolUse({ toolName, args, snapshot, config }) {
     return { allowed: true };
   }
 
+  if (toolName === "open_workspace_file" || toolName === "preview_workspace") {
+    if (!config.allowFileTools) {
+      return { allowed: false, reason: "Workspace preview tools require file tools to be enabled.", category: "workspace-tools" };
+    }
+    return checkWorkspaceToolUse("read_file", { path: args.path || args.file || "." }, config);
+  }
+
   if (toolName === "click") {
     const element = snapshot.elements.find((item) => item.id === String(args.id));
     if (!element) return { allowed: false, reason: `Element ${args.id} is not in the latest snapshot.` };
@@ -96,6 +109,14 @@ export function checkToolUse({ toolName, args, snapshot, config }) {
 
   if (toolName === "run_command") {
     const command = String(args.command || "").trim();
+    if (config.useDockerSandbox && isTransientDockerPreviewCommand(command)) {
+      return {
+        allowed: false,
+        reason:
+          "Transient localhost preview servers inside Docker are not useful because command containers stop and ports are not published. Use preview_workspace/open_workspace_file, or switch to host mode for a persistent dev server.",
+        category: "preview-server",
+      };
+    }
     return evaluateCommandPolicy(command, config);
   }
 

package/src/interactive-cli.js

@@ -1,4 +1,5 @@
 import readline from "node:readline/promises";
+import { emitKeypressEvents } from "node:readline";
 import { stdin as input, stdout as output } from "node:process";
 import { runAgent } from "./agent-runner.js";
 import { loadConfig } from "./config.js";
@@ -27,6 +28,7 @@ function printHelp() {
       "  /exit                     Quit.",
       "",
       "Type a normal request to run the agent. Example: write a Python CLI app with tests",
+      "While a run is active, press Esc or Ctrl+C once to stop gracefully and print a resume command.",
     ].join("\n")
   );
 }
@@ -35,6 +37,8 @@ function printStatus(state) {
   console.log(`project=${process.cwd()}`);
   console.log(`cwd=${state.commandCwd || process.cwd()}`);
   console.log(`session=${state.sessionId || "new"}`);
+  console.log(`status=${state.status || "idle"}${state.activeGoal ? ` workingOn=${state.activeGoal}` : ""}`);
+  if (state.lastEvent) console.log(`last=${state.lastEvent}`);
   console.log(`provider=${state.provider || "auto"} routing=${state.routingMode} model=${state.model || "auto"}`);
   console.log(`profile=${state.taskProfile} maxSteps=${state.maxSteps}`);
   console.log(
@@ -49,7 +53,46 @@ function isAbortError(error) {
   return error?.code === "ABORT_ERR" || error?.name === "AbortError";
 }
 
-function printResumeHint(state) {
+function formatSessionLine(session) {
+  const goal = session.goal ? ` ${session.goal.slice(0, 72)}` : "";
+  return `${session.sessionId} ${session.provider || "unknown"}/${session.model || "unknown"} ${session.updatedAt || ""}${goal}`.trim();
+}
+
+async function latestSession() {
+  const sessions = await listProjectSessions(process.cwd(), 1);
+  return sessions[0] || null;
+}
+
+function printStatusEvent(state, label, details = "") {
+  state.lastEvent = details ? `${label}: ${details}` : label;
+  console.log(`status=${state.status || "running"} ${state.lastEvent}`);
+}
+
+function attachRunInterrupts(controller) {
+  if (!input.isTTY || typeof input.setRawMode !== "function") return () => {};
+
+  emitKeypressEvents(input);
+  const wasRaw = Boolean(input.isRaw);
+  input.setRawMode(true);
+  const handler = (_str, key = {}) => {
+    const isEscape = key.name === "escape";
+    const isCtrlC = key.ctrl && key.name === "c";
+    if (!isEscape && !isCtrlC) return;
+    if (controller.signal.aborted) return;
+    const reason = isEscape ? "escape" : "ctrl-c";
+    console.log(`\nstatus=stopping reason=${reason}`);
+    controller.abort(new Error(`Interrupted by ${reason}.`));
+  };
+  input.on("keypress", handler);
+  return () => {
+    input.off("keypress", handler);
+    if (typeof input.setRawMode === "function") {
+      input.setRawMode(wasRaw);
+    }
+  };
+}
+
+async function printResumeHint(state) {
   const sessionId = state.sessionId || "";
   console.log("");
   if (sessionId) {
@@ -58,7 +101,15 @@ function printResumeHint(state) {
     console.log(`One-shot: aginti resume ${sessionId} "continue"`);
   } else {
     console.log("Interrupted. No active session yet.");
-    console.log("Restart: aginti");
+    const sessions = await listProjectSessions(process.cwd(), 5).catch(() => []);
+    if (sessions.length > 0) {
+      console.log("Recent sessions:");
+      for (const session of sessions) console.log(`  ${formatSessionLine(session)}`);
+      console.log(`Resume latest: aginti resume ${sessions[0].sessionId}`);
+      console.log("List all: aginti sessions list");
+    } else {
+      console.log("Restart: aginti");
+    }
   }
 }
 
@@ -101,8 +152,15 @@ async function handleCommand(line, state, packageDir) {
     return true;
   }
   if (command === "resume") {
-    if (!value) console.log("Usage: /resume <session-id>");
-    else {
+    if (!value || value === "latest") {
+      const latest = await latestSession();
+      if (!latest) {
+        console.log("No project-local sessions found. Use /new or type a request to start one.");
+      } else {
+        state.sessionId = latest.sessionId;
+        console.log(`Resuming latest ${formatSessionLine(latest)}`);
+      }
+    } else {
       state.sessionId = value;
       console.log(`Resuming ${state.sessionId}`);
     }
@@ -194,6 +252,7 @@ async function handleCommand(line, state, packageDir) {
 }
 
 async function runPrompt(prompt, state, packageDir) {
+  const controller = new AbortController();
   const config = loadConfig(
     {
       provider: state.provider,
@@ -216,8 +275,51 @@ async function runPrompt(prompt, state, packageDir) {
     { packageDir, baseDir: process.cwd() }
   );
 
-  const result = await runAgent(config);
+  state.sessionId = config.resume || config.sessionId || state.sessionId;
+  state.status = "running";
+  state.activeGoal = prompt.replace(/\s+/g, " ").slice(0, 120);
+  state.lastEvent = "";
+  console.log(`session=${state.sessionId}`);
+  console.log(`status=running workingOn=${state.activeGoal}`);
+
+  const detachInterrupts = attachRunInterrupts(controller);
+  let result;
+  try {
+    result = await runAgent({
+      ...config,
+      abortSignal: controller.signal,
+      onEvent: (type, data = {}) => {
+        if (type === "plan.created") {
+          printStatusEvent(state, "planned");
+        } else if (type === "tool.started") {
+          printStatusEvent(state, "tool", data.toolName || "unknown");
+        } else if (type === "tool.completed") {
+          printStatusEvent(state, "tool_done", data.toolName || "unknown");
+        } else if (type === "tool.blocked") {
+          printStatusEvent(state, "tool_blocked", data.toolName || data.reason || "unknown");
+        } else if (type === "loop.guard") {
+          printStatusEvent(state, "loop_guard", data.toolName || "");
+        } else if (type === "conversation.queued_input_applied") {
+          printStatusEvent(state, "queued_input_applied");
+        } else if (type === "session.finished") {
+          printStatusEvent(state, "finished");
+        } else if (type === "session.stopped") {
+          printStatusEvent(state, "stopped", data.reason || "");
+        } else if (type === "model.responded") {
+          printStatusEvent(state, "model_responded", data.content ? data.content.slice(0, 80).replace(/\s+/g, " ") : "");
+        }
+      },
+    });
+  } finally {
+    detachInterrupts();
+  }
   state.sessionId = result.sessionId || state.sessionId;
+  state.status = result.stopped ? "stopped" : "idle";
+  state.activeGoal = "";
+  console.log(`status=${state.status} session=${state.sessionId}`);
+  if (result.stopped && result.reason === "user_interrupt") {
+    await printResumeHint(state);
+  }
 }
 
 export async function startInteractiveCli(args = {}, { packageDir, packageVersion } = {}) {
@@ -237,7 +339,7 @@ export async function startInteractiveCli(args = {}, { packageDir, packageVersio
       } catch (error) {
         if (error?.code === "ERR_USE_AFTER_CLOSE") break;
         if (isAbortError(error)) {
-          printResumeHint(state);
+          await printResumeHint(state);
           break;
         }
         throw error;
@@ -254,7 +356,7 @@ export async function startInteractiveCli(args = {}, { packageDir, packageVersio
         await runPrompt(line, state, packageDir);
       } catch (error) {
         if (isAbortError(error)) {
-          printResumeHint(state);
+          await printResumeHint(state);
           break;
         }
         console.error(`error: ${error.message}`);

package/src/model-client.js

@@ -53,6 +53,10 @@ function prepareMessages(config, messages) {
   });
 }
 
+function requestOptions(config) {
+  return config.abortSignal ? { signal: config.abortSignal } : undefined;
+}
+
 function mockCommandForGoal(goal = "") {
   const text = String(goal).toLowerCase();
   if (/\blist\b|folder contents|directory contents|files?/.test(text)) return "ls -la";
@@ -94,6 +98,18 @@ function mockWorkspaceToolForGoal(goal = "") {
   return null;
 }
 
+function mockPreviewToolForGoal(goal = "") {
+  const text = String(goal).toLowerCase();
+  if (!/(open|preview|view|browser|website|web\s*site)/.test(text)) return null;
+  const targetPath = mockPathForGoal(goal);
+  if (targetPath === "mock-output.txt") return null;
+  if (!/\.(html|htm|svg|png|jpe?g|webp|pdf|txt|md)$/i.test(targetPath)) return null;
+  return mockToolCall("preview_workspace", {
+    path: targetPath,
+    port: 8765,
+  });
+}
+
 function mockCanvasToolForGoal(goal = "") {
   const text = String(goal).toLowerCase();
   if (!/canvas|artifact|image|figure|visual|preview|render/.test(text)) return null;
@@ -130,10 +146,11 @@ export async function createPlan(client, config, state) {
     ].join("\n");
   }
 
-  const response = await client.chat.completions.create({
-    model: config.model,
-    temperature: 0,
-    messages: [
+  const response = await client.chat.completions.create(
+    {
+      model: config.model,
+      temperature: 0,
+      messages: [
       {
         role: "system",
         content:
@@ -149,7 +166,7 @@ export async function createPlan(client, config, state) {
             ? `Shell tool is enabled in ${config.commandCwd}. In Docker, this path is mounted as /workspace with persistent /aginti-env and /aginti-cache mounts. Use relative paths or /workspace paths, not absolute host temp paths. Sandbox mode: ${config.sandboxMode}. Package install policy: ${config.packageInstallPolicy}. For npm/pip/conda/venv setup, explain the need and wait for approval unless policy is allow.`
             : "",
           config.allowFileTools
-            ? `Workspace file tools are enabled in ${config.commandCwd}: list_files, read_file, search_files, write_file, apply_patch. Keep all paths workspace-relative, for example plot_fx.svg or docs/report.tex, and avoid secrets.`
+            ? `Workspace file tools are enabled in ${config.commandCwd}: list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, preview_workspace. Keep all paths workspace-relative, for example plot_fx.svg or docs/report.tex, and avoid secrets. For generated local HTML/SVG/PDF/static sites, plan to use open_workspace_file or preview_workspace rather than starting a localhost server inside Docker.`
             : "",
           config.allowWrapperTools
             ? `Agent wrappers are enabled. Use the selected wrapper only: ${normalizeWrapperName(config.preferredWrapper)}. Status: ${wrapperStatusText()}.`
@@ -160,6 +177,7 @@ export async function createPlan(client, config, state) {
           "Use the canvas tunnel for outputs the user would likely want to inspect visually, such as figures, PDFs, screenshots, images, important markdown, or generated files.",
           "For environment or system-maintenance work, prefer project-local dry-run plans/scripts unless the configured policy explicitly allows stronger actions.",
           "Docker language/toolchain installs should prefer /aginti-env or project files so they persist across runs; apt/apk changes are ephemeral unless the image is rebuilt.",
+          "If a localhost/browser preview fails, do not loop on the same URL. Switch to open_workspace_file or preview_workspace, or finish with the local path and honest limitation.",
           "If the run is close to the max-step limit, finish with the best complete artifact and honest limitations instead of starting a new approach.",
           "Plan for a complete result, not endless exploration; finish once the request is satisfied and checks have passed or been honestly skipped.",
           "Return a numbered plan only.",
@@ -167,8 +185,10 @@ export async function createPlan(client, config, state) {
           .filter(Boolean)
           .join("\n"),
       },
-    ],
-  });
+      ],
+    },
+    requestOptions(config)
+  );
 
   return response.choices[0]?.message?.content?.trim() || "1. Inspect the page.\n2. Use the smallest safe action.\n3. Finish with a concise answer.";
 }
@@ -179,7 +199,8 @@ export async function requestNextStep(client, config, messages) {
       type: "function",
       function: {
         name: "open_url",
-        description: "Open an absolute http or https URL in the browser.",
+        description:
+          "Open a remote absolute http or https URL in the browser. Do not use this for generated local workspace files or localhost preview loops; use open_workspace_file or preview_workspace when available.",
         parameters: {
           type: "object",
           properties: {
@@ -296,6 +317,45 @@ export async function requestNextStep(client, config, messages) {
     },
   ];
 
+  if (config.allowFileTools) {
+    tools.splice(
+      0,
+      0,
+      {
+        type: "function",
+        function: {
+          name: "open_workspace_file",
+          description:
+            "Open a workspace-local file directly in the browser, such as generated HTML, SVG, PNG, PDF, or text. Prefer this over starting a localhost server when the user asks to open a generated local page.",
+          parameters: {
+            type: "object",
+            properties: {
+              path: { type: "string", description: "Workspace-relative file path to open." },
+            },
+            required: ["path"],
+            additionalProperties: false,
+          },
+        },
+      },
+      {
+        type: "function",
+        function: {
+          name: "preview_workspace",
+          description:
+            "Start a persistent host-side static preview server for a workspace file or directory, automatically choosing a free port, then open it in the browser. Use this for generated local websites instead of running python -m http.server inside Docker or repeatedly opening localhost URLs.",
+          parameters: {
+            type: "object",
+            properties: {
+              path: { type: "string", description: "Workspace-relative file or directory to preview. Defaults to ." },
+              port: { type: "integer", description: "Preferred localhost port. The runtime chooses another if busy." },
+            },
+            additionalProperties: false,
+          },
+        },
+      }
+    );
+  }
+
   if (config.allowShellTool) {
     tools.splice(-1, 0, {
       type: "function",
@@ -495,6 +555,13 @@ export async function requestNextStep(client, config, messages) {
       ]);
     }
 
+    if (config.allowFileTools) {
+      const previewTool = mockPreviewToolForGoal(config.goal);
+      if (previewTool) {
+        return mockChatResponse("Mock mode will exercise the workspace preview tool.", [previewTool]);
+      }
+    }
+
     const canvasTool = mockCanvasToolForGoal(config.goal);
     if (canvasTool) {
       return mockChatResponse("Mock mode will publish a canvas artifact for the UI tunnel.", [canvasTool]);
@@ -520,12 +587,15 @@ export async function requestNextStep(client, config, messages) {
     ]);
   }
 
-  return client.chat.completions.create({
-    model: config.model,
-    temperature: 0,
-    tool_choice: "auto",
-    parallel_tool_calls: false,
-    messages: prepareMessages(config, messages),
-    tools,
-  });
+  return client.chat.completions.create(
+    {
+      model: config.model,
+      temperature: 0,
+      tool_choice: "auto",
+      parallel_tool_calls: false,
+      messages: prepareMessages(config, messages),
+      tools,
+    },
+    requestOptions(config)
+  );
 }

package/src/static-preview-server.js

@@ -0,0 +1,105 @@
+import fs from "node:fs/promises";
+import http from "node:http";
+import path from "node:path";
+
+const root = path.resolve(process.argv[2] || process.cwd());
+const port = Number(process.argv[3] || 0);
+const host = "127.0.0.1";
+
+const MIME_TYPES = new Map([
+  [".html", "text/html; charset=utf-8"],
+  [".htm", "text/html; charset=utf-8"],
+  [".css", "text/css; charset=utf-8"],
+  [".js", "text/javascript; charset=utf-8"],
+  [".mjs", "text/javascript; charset=utf-8"],
+  [".json", "application/json; charset=utf-8"],
+  [".svg", "image/svg+xml"],
+  [".png", "image/png"],
+  [".jpg", "image/jpeg"],
+  [".jpeg", "image/jpeg"],
+  [".gif", "image/gif"],
+  [".webp", "image/webp"],
+  [".pdf", "application/pdf"],
+  [".txt", "text/plain; charset=utf-8"],
+  [".md", "text/markdown; charset=utf-8"],
+]);
+
+function send(res, statusCode, body, headers = {}) {
+  res.writeHead(statusCode, {
+    "Cache-Control": "no-store",
+    "X-Content-Type-Options": "nosniff",
+    ...headers,
+  });
+  res.end(body);
+}
+
+function normalizeUrlPath(urlPath) {
+  const decoded = decodeURIComponent(urlPath.split("?")[0] || "/");
+  const withoutLeadingSlash = decoded.replace(/^\/+/, "") || "index.html";
+  return path.normalize(withoutLeadingSlash);
+}
+
+function isInsideRoot(target) {
+  const relative = path.relative(root, target);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function isBlockedPath(relativePath) {
+  const segments = relativePath.split(path.sep).filter(Boolean);
+  const lowerBase = (segments.at(-1) || "").toLowerCase();
+  const lowerPath = segments.join("/").toLowerCase();
+  if (segments.includes(".git") || segments.includes("node_modules") || segments.includes(".sessions")) return true;
+  if (lowerBase === ".env" || lowerBase.startsWith(".env.")) return true;
+  if (lowerBase === ".npmrc" || lowerBase === ".pypirc") return true;
+  return /(^|\/)(secrets?|tokens?|passwords?|private[-_]?keys?|credentials?)(\/|\.|$)/i.test(lowerPath);
+}
+
+const server = http.createServer(async (req, res) => {
+  if (!["GET", "HEAD"].includes(req.method || "")) {
+    send(res, 405, "Method Not Allowed");
+    return;
+  }
+
+  try {
+    const relative = normalizeUrlPath(req.url || "/");
+    const target = path.resolve(root, relative);
+    if (!isInsideRoot(target) || isBlockedPath(path.relative(root, target))) {
+      send(res, 403, "Forbidden");
+      return;
+    }
+
+    let filePath = target;
+    const stat = await fs.stat(filePath).catch(() => null);
+    if (stat?.isDirectory()) {
+      filePath = path.join(filePath, "index.html");
+    }
+
+    const finalStat = await fs.stat(filePath).catch(() => null);
+    if (!finalStat?.isFile()) {
+      send(res, 404, "Not Found");
+      return;
+    }
+
+    const contentType = MIME_TYPES.get(path.extname(filePath).toLowerCase()) || "application/octet-stream";
+    res.writeHead(200, {
+      "Content-Type": contentType,
+      "Content-Length": finalStat.size,
+      "Cache-Control": "no-store",
+      "X-Content-Type-Options": "nosniff",
+    });
+    if (req.method === "HEAD") {
+      res.end();
+      return;
+    }
+    const content = await fs.readFile(filePath);
+    res.end(content);
+  } catch (error) {
+    send(res, 500, error instanceof Error ? error.message : String(error));
+  }
+});
+
+server.listen(port, host, () => {
+  const address = server.address();
+  const actualPort = typeof address === "object" && address ? address.port : port;
+  console.log(`AgInTiFlow static preview http://${host}:${actualPort}/ root=${root}`);
+});

package/src/workspace-tools.js

@@ -145,7 +145,7 @@ export function summarizeWorkspaceTools(config) {
   return {
     enabled: Boolean(config.allowFileTools),
     workspace: workspaceRoot(config),
-    tools: WORKSPACE_TOOL_NAMES,
+    tools: [...WORKSPACE_TOOL_NAMES, "open_workspace_file", "preview_workspace"],
     writeTools: WORKSPACE_WRITE_TOOL_NAMES,
     limits: {
       maxReadBytes: MAX_READ_BYTES,

package/web.js

@@ -455,6 +455,8 @@ function createRunRecord(config, goal, existingLogs = []) {
 }
 
 function wireRun(record, config) {
+  const abortController = new AbortController();
+  record.abortController = abortController;
   const push = (kind, message, data = {}) => {
     record.logs.push({
       at: new Date().toISOString(),
@@ -470,6 +472,7 @@ function wireRun(record, config) {
 
   void runAgent({
     ...config,
+    abortSignal: abortController.signal,
     onLog: (message, data = {}) => push("log", message, data),
     onEvent: (type, data = {}) => push("event", type, data),
   })
@@ -846,6 +849,30 @@ app.get("/api/runs/:sessionId", async (req, res) => {
   res.json(stored);
 });
 
+app.post("/api/runs/:sessionId/stop", async (req, res) => {
+  const run = runs.get(req.params.sessionId);
+  if (!run) {
+    res.status(404).json({ error: "Run not found." });
+    return;
+  }
+  if (run.status !== "running") {
+    res.status(409).json({ error: "Run is not active.", status: run.status });
+    return;
+  }
+
+  run.abortController?.abort(new Error("Stopped from web UI."));
+  run.logs.push({
+    at: new Date().toISOString(),
+    kind: "event",
+    message: "session.stop_requested",
+    data: { source: "web" },
+  });
+  run.updatedAt = new Date().toISOString();
+  db.upsertSession(run);
+  await sessionStore(req.params.sessionId).appendEvent("session.stop_requested", { source: "web" }).catch(() => {});
+  res.json({ ok: true, sessionId: req.params.sessionId });
+});
+
 app.get("/health", (_req, res) => {
   res.json({ ok: true, port });
 });