@lazyingart/agintiflow 0.16.2 → 0.17.1

package/README.md

@@ -28,7 +28,7 @@ It is designed for workflows where an AI agent should act, but every tool, log,
 | Core loop | Plan -> use tools -> log events -> finish or resume |
 | Browser control | Playwright, lazy browser startup, domain allowlists |
 | Model layer | Smart routing over DeepSeek fast/pro presets with manual OpenAI-compatible fallback |
-| Local tools | Guarded workspace file tools, Codex-style patching, optional shell commands, Docker sandbox support, and advisory agent wrappers |
+| Local tools | Guarded workspace file tools, Codex-style patching, optional shell commands, tmux session control, Docker sandbox support, and advisory agent wrappers |
 | Memory | Session state, persisted web settings, chat continuation |
 | Operator UX | Multilingual web UI with provider selection, run output, and conversation history |
 
@@ -85,6 +85,8 @@ For current docs, install errors, package/toolchain setup, and source discovery,
 
 For raster image work, AgInTiFlow has an optional `image_generation` skill backed by the `generate_image` tool and a local `GRSAI` key. The skill tells DeepSeek when image generation is appropriate; the tool calls GRS AI Nano Banana, saves manifests/images under `artifacts/images`, and sends the result to the canvas. See [docs/auxiliary-image-generation.md](docs/auxiliary-image-generation.md).
 
+For long-running shell work, AgInTiFlow exposes host-side tmux tools when the shell tool is enabled: `tmux_list_sessions`, `tmux_capture_pane`, `tmux_send_keys`, and `tmux_start_session`. Use normal prompts such as `start this test server in tmux and monitor it` or `check my tmux session`. The agent captures panes before interacting, redacts outputs, blocks secret-like sends, and avoids sending sudo passwords or destructive commands.
+
 AgInTiFlow now ships a Markdown skill library in `skills/<id>/SKILL.md`. Skills are prompt playbooks, while tools are deterministic actions such as `apply_patch`, `run_command`, `web_search`, `generate_image`, and `send_to_canvas`. Built-in skills cover code, websites/apps, LaTeX manuscripts, books, Word documents, image generation, GitHub, system maintenance, Android, R/Stan, Python, C/C++, shell, AAPS, and novel writing. See [docs/skills-and-tools.md](docs/skills-and-tools.md).
 
 ```bash

package/docs/skills-and-tools.md

@@ -6,13 +6,13 @@ AgInTiFlow separates **skills** from **tools** so the agent can stay general whi
 
 **Skill**: Markdown guidance stored at `skills/<id>/SKILL.md`. A skill describes when to use a workflow, what to inspect first, which outputs matter, and which tools are usually useful. Skills are prompt context, not executable code.
 
-**Tool**: A deterministic callable capability exposed to the model, such as `inspect_project`, `read_file`, `apply_patch`, `run_command`, `web_search`, `generate_image`, `preview_workspace`, or `send_to_canvas`.
+**Tool**: A deterministic callable capability exposed to the model, such as `inspect_project`, `read_file`, `apply_patch`, `run_command`, `web_search`, `generate_image`, `preview_workspace`, `tmux_capture_pane`, or `send_to_canvas`.
 
 **Profile**: A broad runtime mode such as `auto`, `code`, `latex`, or `maintenance`. Profiles tune routing, max steps, and general behavior. Skills can combine across profiles.
 
 ## Built-In Skills
 
-The package ships built-in skills for code engineering, website/app building, LaTeX manuscripts, books, Microsoft Word documents, image generation, GitHub maintenance, system maintenance, Android, R/Stan, Python, C/C++, shell scripting, AAPS, and novel writing.
+The package ships built-in skills for code engineering, website/app building, LaTeX manuscripts, books, Microsoft Word documents, image generation, GitHub maintenance, system maintenance, tmux session control, Android, R/Stan, Python, C/C++, shell scripting, AAPS, and novel writing.
 
 List them from a project:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.16.2",
+  "version": "0.17.1",
   "type": "module",
   "description": "AgInTiFlow is a resumable Playwright website-control agent with OpenAI-compatible tool calling.",
   "license": "Apache-2.0",
@@ -49,6 +49,7 @@
     "scripts/smoke-inbox.js",
     "scripts/smoke-platform.js",
     "scripts/smoke-skills.js",
+    "scripts/smoke-tmux-tools.js",
     "scripts/smoke-toolchain-docker.js",
     "scripts/smoke-web-api.js",
     "src/",
@@ -73,9 +74,10 @@
     "smoke:toolchain-docker": "node scripts/smoke-toolchain-docker.js",
     "smoke:inbox": "node scripts/smoke-inbox.js",
     "smoke:platform": "node scripts/smoke-platform.js",
+    "smoke:tmux-tools": "node scripts/smoke-tmux-tools.js",
     "smoke:web-api": "node scripts/smoke-web-api.js",
     "real:deepseek": "node scripts/real-deepseek-capabilities.js",
-    "test": "npm run check && npm run smoke:web-api && npm run smoke:coding-tools && npm run smoke:auxiliary-tools && npm run smoke:auth && npm run smoke:capabilities && npm run smoke:platform && npm run smoke:skills && npm run smoke:cli-chat && npm run smoke:inbox",
+    "test": "npm run check && npm run smoke:web-api && npm run smoke:coding-tools && npm run smoke:auxiliary-tools && npm run smoke:auth && npm run smoke:capabilities && npm run smoke:platform && npm run smoke:skills && 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/scripts/smoke-capabilities.js

@@ -56,6 +56,10 @@ try {
     capabilities.checks.some((check) => check.name === "bash-syntax-policy" && check.ok),
     "bash -n maintenance script policy is not allowed"
   );
+  assert(
+    capabilities.checks.some((check) => check.name === "tmux"),
+    "capabilities did not report tmux availability"
+  );
   assert(
     capabilities.checks.some((check) => check.name === "git-status-policy" && check.ok),
     "git status policy is not allowed"

package/scripts/smoke-cli-chat.js

@@ -144,6 +144,10 @@ try {
   if (!skillsResult.stdout.includes("website-app") || !skillsResult.stdout.includes("Website And App Builder")) {
     throw new Error("interactive /skills did not show matching built-in skills");
   }
+  const abbreviatedSkillsResult = await runChat("/sk website\n/ex\n");
+  if (abbreviatedSkillsResult.stdout.includes("Unknown command") || !abbreviatedSkillsResult.stdout.includes("website-app")) {
+    throw new Error("interactive slash command prefix did not auto-select the first matching command");
+  }
   await runChat("remember that this project prefers pytest smoke tests in AGINTI.md\n/exit\n");
   const updatedInstructions = await fs.readFile(path.join(tempRoot, "AGINTI.md"), "utf8");
   if (!updatedInstructions.includes("pytest smoke tests")) {
@@ -181,7 +185,7 @@ try {
       {
         ok: true,
         projectRoot: tempRoot,
-        checks: ["markdown-render", "markdown-table-no-duplicate", "patch-diff-render", "prompt-layout", "user-prompt-label", "escape-policy", "live-input-status-layout", "agent-response-gutter", "aginti-md", "instructions-command", "skills-command", "instructions-chat-edit", "interactive-chat", "mock-file-write", "run-status", "resume-latest", "resume-history-full"],
+        checks: ["markdown-render", "markdown-table-no-duplicate", "patch-diff-render", "prompt-layout", "user-prompt-label", "escape-policy", "live-input-status-layout", "agent-response-gutter", "aginti-md", "instructions-command", "skills-command", "slash-prefix-autoselect", "instructions-chat-edit", "interactive-chat", "mock-file-write", "run-status", "resume-latest", "resume-history-full"],
       },
       null,
       2

package/scripts/smoke-skills.js

@@ -26,6 +26,7 @@ for (const required of [
   "image-generation",
   "latex-manuscript",
   "system-maintenance",
+  "tmux-session",
   "website-app",
   "word-documents",
 ]) {
@@ -37,6 +38,7 @@ assert(selectedIds("write a LaTeX paper and compile a PDF").includes("latex-manu
 assert(selectedIds("edit a Microsoft Word docx and preserve the original").includes("word-documents"), "docx prompt did not select word-documents");
 assert(selectedIds("generate a logo image with grsai nanobanana").includes("image-generation"), "image prompt did not select image-generation");
 assert(selectedIds("git status commit push with gh").includes("github-maintenance"), "git prompt did not select github-maintenance");
+assert(selectedIds("monitor a long running tmux session").includes("tmux-session"), "tmux prompt did not select tmux-session");
 assert(selectedIds("create an .aaps example for @lazyingart/aaps").includes("aaps"), "AAPS prompt did not select aaps");
 assert(selectedIds("debug a C++ CMake build").includes("c-cpp"), "C++ prompt did not select c-cpp");
 assert(selectedIds("set up Stan and CmdStanR reproducibly").includes("r-stan"), "Stan prompt did not select r-stan");

package/scripts/smoke-tmux-tools.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { execFile as execFileCallback } 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 {
+  captureTmuxPane,
+  checkTmuxToolUse,
+  listTmuxSessions,
+  sendTmuxKeys,
+  startTmuxSession,
+  tmuxAvailable,
+} from "../src/tmux-tools.js";
+
+const execFile = promisify(execFileCallback);
+const workspace = await fs.mkdtemp(path.join(os.tmpdir(), "agintiflow-tmux-"));
+const session = `aginti-smoke-${process.pid}`;
+const config = {
+  allowShellTool: true,
+  commandCwd: workspace,
+};
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+try {
+  if (!(await tmuxAvailable())) {
+    console.log(JSON.stringify({ ok: true, skipped: true, reason: "tmux is not installed" }, null, 2));
+    process.exit(0);
+  }
+
+  const start = await startTmuxSession({ name: session }, config);
+  assert.equal(start.ok, true, start.error || start.reason);
+  await sleep(250);
+
+  const send = await sendTmuxKeys({
+    target: start.target,
+    text: "printf 'aginti tmux smoke\\n'; pwd",
+    enter: true,
+  });
+  assert.equal(send.ok, true, send.error || send.reason);
+  await sleep(500);
+
+  const capture = await captureTmuxPane({ target: start.target, lines: 40 });
+  assert.equal(capture.ok, true, capture.error || capture.reason);
+  assert.match(capture.content, /aginti tmux smoke/, "tmux capture did not include command output");
+  assert.match(capture.content, new RegExp(workspace.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")), "tmux cwd was not workspace");
+
+  const list = await listTmuxSessions({ includePanes: true });
+  assert.equal(list.ok, true, list.error || list.reason);
+  assert(list.sessions.some((item) => item.name === session), "tmux list did not include smoke session");
+  assert(list.panes.some((item) => item.target === start.target), "tmux list did not include smoke pane");
+
+  const blocked = checkTmuxToolUse(
+    "tmux_send_keys",
+    { target: start.target, text: "OPENAI_API_KEY=secret-value" },
+    config
+  );
+  assert.equal(blocked.allowed, false, "tmux guardrail did not block secret-like text");
+
+  const destructive = checkTmuxToolUse("tmux_send_keys", { target: start.target, text: "rm -rf /" }, config);
+  assert.equal(destructive.allowed, false, "tmux guardrail did not block destructive text");
+
+  console.log(
+    JSON.stringify(
+      {
+        ok: true,
+        session,
+        workspace,
+        checks: ["start-session", "send-keys", "capture-pane", "list-sessions", "secret-guardrail", "destructive-guardrail"],
+      },
+      null,
+      2
+    )
+  );
+} finally {
+  await execFile("tmux", ["kill-session", "-t", session]).catch(() => {});
+  await fs.rm(workspace, { recursive: true, force: true });
+}

package/skills/tmux-session/SKILL.md

@@ -0,0 +1,32 @@
+---
+id: tmux-session
+label: Tmux Session Control
+description: Monitor and interact with long-running tmux terminals, agent sessions, dev servers, installs, and test jobs.
+triggers:
+  - tmux
+  - terminal session
+  - long running
+  - monitor
+  - background job
+  - pane
+  - session
+tools:
+  - tmux_list_sessions
+  - tmux_capture_pane
+  - tmux_send_keys
+  - tmux_start_session
+  - run_command
+---
+# Tmux Session Control
+
+Use tmux tools for work that should keep running while the agent remains responsive: installs, builds, tests, dev servers, external agents, and monitored shells.
+
+Workflow:
+
+1. Discover with `tmux_list_sessions` unless the user gave an exact target.
+2. Capture with `tmux_capture_pane` before sending input so context is current.
+3. Use `tmux_start_session` for new durable jobs rooted in the workspace.
+4. Use `tmux_send_keys` sparingly and never send secrets, sudo passwords, destructive commands, or unreviewed pasted scripts.
+5. For long commands, capture progress periodically and summarize the latest useful lines instead of flooding the chat.
+
+If a package or sudo install is missing, report the exact command and whether it should run in Docker, host, or a user-owned tmux session.

package/src/agent-runner.js

@@ -24,6 +24,7 @@ import { runParallelScouts, shouldRunParallelScouts } from "./parallel-scouts.js
 import { readProjectInstructions } from "./project.js";
 import { formatSkillsForPrompt, selectSkillsForGoal } from "./skill-library.js";
 import { hostShellOption, platformInfo, platformLabel } from "./platform.js";
+import { captureTmuxPane, listTmuxSessions, sendTmuxKeys, startTmuxSession } from "./tmux-tools.js";
 
 const exec = promisify(execCallback);
 const BROWSER_TOOLS = new Set(["open_url", "open_workspace_file", "preview_workspace", "click", "type", "scroll", "press", "back"]);
@@ -306,6 +307,9 @@ async function createInitialState(config, sessionId) {
               ? `A shell command tool is available inside Docker sandbox mode ${config.sandboxMode}. Docker workspace mode with approved package installs supports broader setup and network commands. The project is mounted at /workspace and the persistent agent toolchain is mounted at /aginti-env with caches under /aginti-cache.`
               : `A host shell command tool is available under the configured trust policy on ${platformLabel(platform)}. On native Windows, prefer PowerShell/cmd-compatible commands or switch to WSL/Docker for bash-like toolchains.`
             : "No shell command tool is available.",
+          config.allowShellTool
+            ? "Host tmux tools are available for long-running terminals: list sessions, capture panes, send safe keys/text, and start detached sessions. Prefer tmux for monitoring long installs/tests/dev servers without blocking; capture before sending input and never send secrets or sudo passwords."
+            : "",
           config.allowFileTools
             ? `Workspace file tools are available in ${config.commandCwd}: inspect_project, list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, and preview_workspace. For large or unfamiliar repositories, call inspect_project first, then search/read AGINTI.md/AGENTS.md/README/manifests as relevant before editing. apply_patch supports exact single-file replacements plus Codex-style/unified multi-file patches; prefer it for source edits after reading/searching the relevant context. 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.",
@@ -697,6 +701,9 @@ async function captureSyntheticSnapshot(store, step, config) {
           ? `Shell tool available in Docker with mounted workspace /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 tool available in: ${config.commandCwd} on ${platformLabel(platform)}. Use OS-compatible commands; prefer WSL/Docker for bash-heavy workflows on Windows.`
         : "Shell tool disabled.",
+      config.allowShellTool
+        ? "Host tmux tools available: tmux_list_sessions, tmux_capture_pane, tmux_send_keys, tmux_start_session. Use them for long-running jobs and agent terminals; capture before sending input."
+        : "",
       config.allowFileTools
         ? `Workspace file tools available in: ${config.commandCwd}. Use inspect_project first for large or unfamiliar codebases, then search/read exact files before editing. Use workspace-relative paths. Use apply_patch for code edits; it supports exact single-file replacement and multi-file Codex-style/unified patches.`
         : "Workspace file tools disabled.",
@@ -955,6 +962,34 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
         observers.event("tool.completed", result);
         return result;
       }
+      case "tmux_list_sessions": {
+        const result = await listTmuxSessions(args);
+        const eventResult = sanitizeToolResult(result);
+        await store.appendEvent(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        observers.event(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        return result;
+      }
+      case "tmux_capture_pane": {
+        const result = await captureTmuxPane(args);
+        const eventResult = sanitizeToolResult(result);
+        await store.appendEvent(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        observers.event(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        return result;
+      }
+      case "tmux_send_keys": {
+        const result = await sendTmuxKeys(args);
+        const eventResult = sanitizeToolResult(result);
+        await store.appendEvent(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        observers.event(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        return result;
+      }
+      case "tmux_start_session": {
+        const result = await startTmuxSession(args, config);
+        const eventResult = sanitizeToolResult(result);
+        await store.appendEvent(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        observers.event(result.ok ? "tool.completed" : "tool.failed", eventResult);
+        return result;
+      }
       case "delegate_agent": {
         const wrapperResult = await runAgentWrapper(
           {

package/src/capabilities.js

@@ -122,6 +122,7 @@ export async function buildCapabilityReport(projectRoot, packageVersion, config)
     commandAvailable("R", ["--version"]),
     commandAvailable("pdflatex", ["--version"]),
     commandAvailable("latexmk", ["--version"]),
+    commandAvailable("tmux", ["-V"]),
   ];
   if (platform.isMac) commandChecks.push(commandAvailable("brew", ["--version"]));
   if (platform.isWindows) commandChecks.push(commandAvailable("wsl", ["--status"]));
@@ -132,9 +133,9 @@ export async function buildCapabilityReport(projectRoot, packageVersion, config)
     readProjectInstructions(projectRoot, { maxBytes: 1 }),
     readCodebaseMap(projectRoot),
   ]);
-  const [node, npm, python, conda, r, pdflatex, latexmk] = commands;
-  const homebrew = platform.isMac ? commands[7] : undefined;
-  const wsl = platform.isWindows ? commands[7] : undefined;
+  const [node, npm, python, conda, r, pdflatex, latexmk, tmux] = commands;
+  const homebrew = platform.isMac ? commands[8] : undefined;
+  const wsl = platform.isWindows ? commands[8] : undefined;
 
   const npmPrefixPolicy = evaluateCommandPolicy("npm --prefix round9-node-app test", config);
   const cdNpmTestPolicy = evaluateCommandPolicy("cd round9-node-app && npm test", config);
@@ -154,6 +155,7 @@ export async function buildCapabilityReport(projectRoot, packageVersion, config)
     capability("R", r.available, r.available ? r : { ...r, setup: "Optional. Generate a project-local R setup plan; do not install globally from the agent." }),
     capability("pdflatex", pdflatex.available, pdflatex.available ? pdflatex : { ...pdflatex, setup: "LaTeX tasks should create .tex source and an honest setup report when TeX is unavailable." }),
     capability("latexmk", latexmk.available, latexmk.available ? latexmk : { ...latexmk, setup: "latexmk is optional if pdflatex is available." }),
+    capability("tmux", tmux.available, tmux.available ? tmux : { ...tmux, setup: "Optional for monitoring long-running host sessions. Install tmux or use normal run_command." }),
     ...(platform.isMac ? [capability("homebrew", homebrew?.available, homebrew?.available ? homebrew : { ...homebrew, setup: "Optional on macOS for host-mode tool installs." })] : []),
     ...(platform.isWindows ? [capability("wsl", wsl?.available, wsl?.available ? wsl : { ...wsl, setup: "Recommended for Windows. Install WSL2 for the most compatible shell and Docker workflow." })] : []),
     capability("docker", Boolean(dockerStatus?.dockerAvailable), dockerStatus || {}),

package/src/guardrails.js

@@ -1,6 +1,7 @@
 import { evaluateCommandPolicy } from "./command-policy.js";
 import { checkWorkspaceToolUse, WORKSPACE_TOOL_NAMES } from "./workspace-tools.js";
 import { normalizeWrapperName } from "./tool-wrappers.js";
+import { checkTmuxToolUse, TMUX_TOOL_NAMES } from "./tmux-tools.js";
 
 const DESTRUCTIVE_KEYWORDS = [
   "delete",
@@ -57,6 +58,10 @@ export function checkToolUse({ toolName, args, snapshot, config }) {
     return checkWorkspaceToolUse(toolName, args, config);
   }
 
+  if (TMUX_TOOL_NAMES.includes(toolName)) {
+    return checkTmuxToolUse(toolName, args, config);
+  }
+
   if (toolName === "open_url") {
     if (!/^https?:\/\//.test(String(args.url || ""))) {
       return { allowed: false, reason: "Only http and https URLs are allowed." };

package/src/interactive-cli.js

@@ -153,6 +153,15 @@ function commandSuggestions(line = "") {
   return SLASH_COMMANDS.filter((command) => command.startsWith(trimmed)).slice(0, 8);
 }
 
+function resolveSlashCommand(command = "") {
+  const raw = String(command || "").trim();
+  if (!raw) return raw;
+  const slashCommand = `/${raw}`;
+  if (SLASH_COMMANDS.includes(slashCommand)) return raw;
+  const suggestion = SLASH_COMMANDS.find((candidate) => candidate.startsWith(slashCommand));
+  return suggestion ? suggestion.slice(1) : raw;
+}
+
 function clamp(value, min, max) {
   return Math.min(Math.max(value, min), max);
 }
@@ -1465,7 +1474,8 @@ async function promptAndSaveProviderKey(provider = "", state = null) {
 }
 
 async function handleCommand(line, state, packageDir) {
-  const [command, ...rest] = line.slice(1).trim().split(/\s+/);
+  const [rawCommand, ...rest] = line.slice(1).trim().split(/\s+/);
+  const command = resolveSlashCommand(rawCommand);
   const value = rest.join(" ").trim();
 
   if (!command || command === "help" || command === "?") {

package/src/model-client.js

@@ -226,6 +226,9 @@ export async function createPlan(client, config, state) {
           config.allowShellTool
             ? `Shell tool is enabled in ${config.commandCwd}. Host platform: ${platformLabel(platform)}. 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. On native Windows host mode, prefer PowerShell/cmd-compatible commands or WSL/Docker for bash-like toolchains.`
             : "",
+          config.allowShellTool
+            ? "Host tmux tools are enabled for long-running sessions. Plan to use tmux_start_session for durable jobs, tmux_capture_pane to monitor, tmux_send_keys to interact after capture, and tmux_list_sessions to discover existing sessions."
+            : "",
           config.allowFileTools
             ? `Workspace file tools are enabled in ${config.commandCwd}: inspect_project, list_files, read_file, search_files, write_file, apply_patch, open_workspace_file, preview_workspace. For large or unfamiliar repos, plan to call inspect_project first, then search/read AGINTI.md/AGENTS.md/README/manifests and exact files. apply_patch supports exact single-file replacements and Codex-style/unified multi-file patches; prefer it for edits after reading relevant context. 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.`
             : "",
@@ -457,22 +460,101 @@ export async function requestNextStep(client, config, messages) {
   }
 
   if (config.allowShellTool) {
-    tools.splice(-1, 0, {
-      type: "function",
-      function: {
-        name: "run_command",
-        description:
-          "Run a terminal command in the configured working directory under the active shell policy. Secrets and npm publishing are always blocked; Docker workspace mode with approved package installs supports broader network/setup commands, while host destructive or privileged work requires explicit trust.",
-        parameters: {
-          type: "object",
-          properties: {
-            command: { type: "string" },
+    tools.splice(
+      -1,
+      0,
+      {
+        type: "function",
+        function: {
+          name: "tmux_list_sessions",
+          description:
+            "List host tmux sessions and panes. Use this to discover long-running terminals, agent sessions, dev servers, or jobs before interacting with them. tmux tools run host-side even when command execution is Docker-sandboxed.",
+          parameters: {
+            type: "object",
+            properties: {
+              includePanes: { type: "boolean", description: "Include pane targets, current paths, and running commands. Defaults to true." },
+            },
+            additionalProperties: false,
           },
-          required: ["command"],
-          additionalProperties: false,
         },
       },
-    });
+      {
+        type: "function",
+        function: {
+          name: "tmux_capture_pane",
+          description:
+            "Capture recent text from a host tmux pane by target such as session:0.0. Use this to monitor progress or inspect a long-running job without interrupting it.",
+          parameters: {
+            type: "object",
+            properties: {
+              target: { type: "string", description: "tmux pane target, for example aginti-test:0.0 or %12." },
+              lines: { type: "integer", description: "Recent lines to capture, 1 to 500. Defaults to 80." },
+            },
+            required: ["target"],
+            additionalProperties: false,
+          },
+        },
+      },
+      {
+        type: "function",
+        function: {
+          name: "tmux_send_keys",
+          description:
+            "Send literal text and/or safe control keys to a host tmux pane. Use for interacting with known shells or agent sessions after capturing context. Do not send secrets, passwords, sudo passwords, or destructive commands.",
+          parameters: {
+            type: "object",
+            properties: {
+              target: { type: "string", description: "tmux pane target, for example aginti-test:0.0 or %12." },
+              text: { type: "string", description: "Literal text to send before keys." },
+              enter: { type: "boolean", description: "Append Enter after text/keys. Defaults to true." },
+              keys: {
+                type: "array",
+                items: {
+                  type: "string",
+                  enum: ["Enter", "C-c", "C-d", "Escape", "Tab", "Up", "Down", "Left", "Right", "Backspace", "C-a", "C-e", "C-u", "C-k"],
+                },
+                description: "Optional safe tmux key names.",
+              },
+            },
+            required: ["target"],
+            additionalProperties: false,
+          },
+        },
+      },
+      {
+        type: "function",
+        function: {
+          name: "tmux_start_session",
+          description:
+            "Start a detached host tmux session rooted inside the workspace, optionally with a startup command. Use for long-running local jobs that should be monitored with tmux_capture_pane instead of blocking the agent.",
+          parameters: {
+            type: "object",
+            properties: {
+              name: { type: "string", description: "Safe tmux session name. Defaults to aginti-<timestamp>." },
+              cwd: { type: "string", description: "Workspace-relative cwd. Defaults to ." },
+              command: { type: "string", description: "Optional non-secret startup command." },
+            },
+            additionalProperties: false,
+          },
+        },
+      },
+      {
+        type: "function",
+        function: {
+          name: "run_command",
+          description:
+            "Run a terminal command in the configured working directory under the active shell policy. Secrets and npm publishing are always blocked; Docker workspace mode with approved package installs supports broader network/setup commands, while host destructive or privileged work requires explicit trust.",
+          parameters: {
+            type: "object",
+            properties: {
+              command: { type: "string" },
+            },
+            required: ["command"],
+            additionalProperties: false,
+          },
+        },
+      }
+    );
   }
 
   if (config.allowFileTools) {

package/src/tmux-tools.js

@@ -0,0 +1,315 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify } from "node:util";
+import { redactSensitiveText } from "./redaction.js";
+
+const execFile = promisify(execFileCallback);
+const MAX_CAPTURE_LINES = 500;
+const MAX_SEND_BYTES = 12000;
+const MAX_COMMAND_BYTES = 4000;
+const TARGET_PATTERN = /^[A-Za-z0-9_.:@%+-]{1,120}$/;
+const SESSION_PATTERN = /^[A-Za-z0-9_.+-]{1,80}$/;
+const FIELD_SEPARATOR = "|";
+const ALLOWED_KEYS = new Set([
+  "Enter",
+  "C-c",
+  "C-d",
+  "Escape",
+  "Tab",
+  "Up",
+  "Down",
+  "Left",
+  "Right",
+  "Backspace",
+  "C-a",
+  "C-e",
+  "C-u",
+  "C-k",
+]);
+const SECRET_PATTERN = /(api[_-]?key|auth[_-]?token|npm[_-]?token|_authToken|password|passwd|secret|bearer\s+[A-Za-z0-9._-]+)/i;
+const DESTRUCTIVE_PATTERN =
+  /\b(rm\s+-[^\n;]*[rf][^\n;]*(\/|\*|~|\$HOME)|mkfs(?:\.[a-z0-9]+)?\b|dd\s+if=.*\s+of=\/dev\/|shutdown\b|reboot\b|poweroff\b)/i;
+
+export const TMUX_TOOL_NAMES = ["tmux_list_sessions", "tmux_capture_pane", "tmux_send_keys", "tmux_start_session"];
+
+function safeEnv() {
+  return {
+    PATH: process.env.PATH || "/usr/local/bin:/usr/bin:/bin",
+    HOME: process.env.HOME || "/tmp",
+    TERM: process.env.TERM || "xterm-256color",
+  };
+}
+
+async function runTmux(args, options = {}) {
+  try {
+    const result = await execFile("tmux", args, {
+      timeout: options.timeout ?? 12000,
+      maxBuffer: options.maxBuffer ?? 220 * 1024,
+      env: safeEnv(),
+    });
+    return {
+      ok: true,
+      stdout: redactSensitiveText(result.stdout || ""),
+      stderr: redactSensitiveText(result.stderr || ""),
+    };
+  } catch (error) {
+    const message = redactSensitiveText(error instanceof Error ? error.message : String(error));
+    return {
+      ok: false,
+      stdout: redactSensitiveText(String(error?.stdout || "")),
+      stderr: redactSensitiveText(String(error?.stderr || message)),
+      error: message,
+      exitCode: Number.isInteger(error?.code) ? error.code : 1,
+    };
+  }
+}
+
+export async function tmuxAvailable() {
+  const result = await runTmux(["-V"], { timeout: 4000, maxBuffer: 16 * 1024 });
+  return Boolean(result.ok);
+}
+
+function clampInteger(value, fallback, min, max) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(Math.max(Math.trunc(parsed), min), max);
+}
+
+function validateTarget(target) {
+  const normalized = String(target || "").trim();
+  if (!normalized) return { ok: false, reason: "tmux target is required." };
+  if (!TARGET_PATTERN.test(normalized)) {
+    return { ok: false, reason: "tmux target contains unsupported characters." };
+  }
+  return { ok: true, target: normalized };
+}
+
+function validateSessionName(name) {
+  const normalized = String(name || `aginti-${Date.now()}`).trim();
+  if (!SESSION_PATTERN.test(normalized)) {
+    return { ok: false, reason: "tmux session name must use letters, numbers, dot, underscore, plus, or dash." };
+  }
+  return { ok: true, name: normalized };
+}
+
+function resolveCwd(config, cwd = ".") {
+  const root = path.resolve(config.commandCwd || process.cwd());
+  const requested = path.resolve(root, String(cwd || "."));
+  const relative = path.relative(root, requested);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    return { ok: false, reason: "tmux cwd must stay inside the configured workspace." };
+  }
+  return { ok: true, cwd: requested };
+}
+
+function parseSessions(stdout = "") {
+  return String(stdout || "")
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => {
+      const [name, windows, attached, created, activity] = line.split(FIELD_SEPARATOR);
+      return {
+        name,
+        windows: Number(windows) || 0,
+        attached: Number(attached) || 0,
+        created: Number(created) || 0,
+        activity: Number(activity) || 0,
+      };
+    });
+}
+
+function parsePanes(stdout = "") {
+  return String(stdout || "")
+    .split(/\r?\n/)
+    .filter(Boolean)
+    .map((line) => {
+      const [target, cwd, command, active, title] = line.split(FIELD_SEPARATOR);
+      return {
+        target,
+        cwd,
+        command,
+        active: active === "1",
+        title,
+      };
+    });
+}
+
+export async function listTmuxSessions(args = {}) {
+  const sessionsResult = await runTmux([
+    "list-sessions",
+    "-F",
+    "#{session_name}|#{session_windows}|#{session_attached}|#{session_created}|#{session_activity}",
+  ]);
+  if (!sessionsResult.ok && /no server running|failed to connect/i.test(`${sessionsResult.stderr} ${sessionsResult.error}`)) {
+    return { ok: true, toolName: "tmux_list_sessions", sessions: [], panes: [], summary: "No tmux server is running." };
+  }
+  if (!sessionsResult.ok) return { ok: false, toolName: "tmux_list_sessions", error: sessionsResult.stderr || sessionsResult.error };
+
+  let panes = [];
+  if (args.includePanes !== false) {
+    const panesResult = await runTmux([
+      "list-panes",
+      "-a",
+      "-F",
+      "#{session_name}:#{window_index}.#{pane_index}|#{pane_current_path}|#{pane_current_command}|#{pane_active}|#{pane_title}",
+    ]);
+    if (panesResult.ok) panes = parsePanes(panesResult.stdout);
+  }
+  const sessions = parseSessions(sessionsResult.stdout);
+  return {
+    ok: true,
+    toolName: "tmux_list_sessions",
+    sessions,
+    panes,
+    summary: `${sessions.length} tmux session(s), ${panes.length} pane(s).`,
+  };
+}
+
+export async function captureTmuxPane(args = {}) {
+  const target = validateTarget(args.target);
+  if (!target.ok) return { ok: false, toolName: "tmux_capture_pane", blocked: true, reason: target.reason };
+  const lines = clampInteger(args.lines, 80, 1, MAX_CAPTURE_LINES);
+  const result = await runTmux(["capture-pane", "-t", target.target, "-p", "-S", `-${lines}`], {
+    timeout: 8000,
+    maxBuffer: 260 * 1024,
+  });
+  if (!result.ok) return { ok: false, toolName: "tmux_capture_pane", target: target.target, error: result.stderr || result.error };
+  const content = redactSensitiveText(result.stdout || "").replace(/\s+$/g, "");
+  return {
+    ok: true,
+    toolName: "tmux_capture_pane",
+    target: target.target,
+    lines,
+    content,
+    contentBytes: Buffer.byteLength(content, "utf8"),
+  };
+}
+
+export async function sendTmuxKeys(args = {}) {
+  const target = validateTarget(args.target);
+  if (!target.ok) return { ok: false, toolName: "tmux_send_keys", blocked: true, reason: target.reason };
+  const text = String(args.text || "");
+  const keys = Array.isArray(args.keys) ? args.keys.map(String).filter(Boolean) : [];
+  const enter = args.enter !== false;
+  if (text && Buffer.byteLength(text, "utf8") > MAX_SEND_BYTES) {
+    return { ok: false, toolName: "tmux_send_keys", blocked: true, reason: "tmux text payload is too large." };
+  }
+  if (SECRET_PATTERN.test(text)) {
+    return { ok: false, toolName: "tmux_send_keys", blocked: true, reason: "tmux text appears to contain a secret." };
+  }
+  if (DESTRUCTIVE_PATTERN.test(text)) {
+    return { ok: false, toolName: "tmux_send_keys", blocked: true, reason: "tmux text appears destructive; ask the user before sending it." };
+  }
+  for (const key of keys) {
+    if (!ALLOWED_KEYS.has(key)) {
+      return { ok: false, toolName: "tmux_send_keys", blocked: true, reason: `Unsupported tmux key: ${key}` };
+    }
+  }
+
+  const steps = [];
+  if (text) {
+    const sent = await runTmux(["send-keys", "-t", target.target, "-l", text], { timeout: 8000 });
+    if (!sent.ok) return { ok: false, toolName: "tmux_send_keys", target: target.target, error: sent.stderr || sent.error };
+    steps.push("literal-text");
+  }
+  const keyArgs = [...keys];
+  if (enter) keyArgs.push("Enter");
+  if (keyArgs.length > 0) {
+    const sent = await runTmux(["send-keys", "-t", target.target, ...keyArgs], { timeout: 8000 });
+    if (!sent.ok) return { ok: false, toolName: "tmux_send_keys", target: target.target, error: sent.stderr || sent.error };
+    steps.push(...keyArgs);
+  }
+
+  return {
+    ok: true,
+    toolName: "tmux_send_keys",
+    target: target.target,
+    sentTextBytes: Buffer.byteLength(text, "utf8"),
+    sentTextSha256: text ? crypto.createHash("sha256").update(text).digest("hex") : "",
+    keys: keyArgs,
+    steps,
+  };
+}
+
+export async function startTmuxSession(args = {}, config = {}) {
+  const name = validateSessionName(args.name);
+  if (!name.ok) return { ok: false, toolName: "tmux_start_session", blocked: true, reason: name.reason };
+  const cwd = resolveCwd(config, args.cwd || ".");
+  if (!cwd.ok) return { ok: false, toolName: "tmux_start_session", blocked: true, reason: cwd.reason };
+  const command = String(args.command || "").trim();
+  if (command && Buffer.byteLength(command, "utf8") > MAX_COMMAND_BYTES) {
+    return { ok: false, toolName: "tmux_start_session", blocked: true, reason: "tmux startup command is too large." };
+  }
+  if (SECRET_PATTERN.test(command)) {
+    return { ok: false, toolName: "tmux_start_session", blocked: true, reason: "tmux startup command appears to contain a secret." };
+  }
+  if (DESTRUCTIVE_PATTERN.test(command)) {
+    return {
+      ok: false,
+      toolName: "tmux_start_session",
+      blocked: true,
+      reason: "tmux startup command appears destructive; ask the user before starting it.",
+    };
+  }
+
+  const tmuxArgs = ["new-session", "-d", "-s", name.name, "-c", cwd.cwd];
+  if (command) tmuxArgs.push(command);
+  const result = await runTmux(tmuxArgs, { timeout: 10000 });
+  if (!result.ok) return { ok: false, toolName: "tmux_start_session", session: name.name, error: result.stderr || result.error };
+  return {
+    ok: true,
+    toolName: "tmux_start_session",
+    session: name.name,
+    target: `${name.name}:0.0`,
+    cwd: cwd.cwd,
+    command: command ? redactSensitiveText(command) : "",
+  };
+}
+
+export function checkTmuxToolUse(toolName, args = {}, config = {}) {
+  if (!config.allowShellTool) {
+    return { allowed: false, reason: "tmux tools require the shell tool to be enabled.", category: "tmux" };
+  }
+  if (toolName === "tmux_list_sessions") return { allowed: true, category: "tmux" };
+  if (toolName === "tmux_capture_pane") {
+    const target = validateTarget(args.target);
+    return target.ok ? { allowed: true, category: "tmux" } : { allowed: false, reason: target.reason, category: "tmux" };
+  }
+  if (toolName === "tmux_send_keys") {
+    const target = validateTarget(args.target);
+    if (!target.ok) return { allowed: false, reason: target.reason, category: "tmux" };
+    const text = String(args.text || "");
+    if (Buffer.byteLength(text, "utf8") > MAX_SEND_BYTES) {
+      return { allowed: false, reason: "tmux text payload is too large.", category: "tmux" };
+    }
+    if (SECRET_PATTERN.test(text)) {
+      return { allowed: false, reason: "tmux text appears to contain a secret.", category: "tmux" };
+    }
+    if (DESTRUCTIVE_PATTERN.test(text)) {
+      return { allowed: false, reason: "tmux text appears destructive; ask the user before sending it.", category: "tmux" };
+    }
+    for (const key of Array.isArray(args.keys) ? args.keys : []) {
+      if (!ALLOWED_KEYS.has(String(key))) return { allowed: false, reason: `Unsupported tmux key: ${key}`, category: "tmux" };
+    }
+    return { allowed: true, category: "tmux" };
+  }
+  if (toolName === "tmux_start_session") {
+    const name = validateSessionName(args.name);
+    if (!name.ok) return { allowed: false, reason: name.reason, category: "tmux" };
+    const cwd = resolveCwd(config, args.cwd || ".");
+    if (!cwd.ok) return { allowed: false, reason: cwd.reason, category: "tmux" };
+    const command = String(args.command || "");
+    if (Buffer.byteLength(command, "utf8") > MAX_COMMAND_BYTES) {
+      return { allowed: false, reason: "tmux startup command is too large.", category: "tmux" };
+    }
+    if (SECRET_PATTERN.test(command)) {
+      return { allowed: false, reason: "tmux startup command appears to contain a secret.", category: "tmux" };
+    }
+    if (DESTRUCTIVE_PATTERN.test(command)) {
+      return { allowed: false, reason: "tmux startup command appears destructive; ask the user before starting it.", category: "tmux" };
+    }
+    return { allowed: true, category: "tmux" };
+  }
+  return { allowed: true, category: "tmux" };
+}