@lazyingart/agintiflow 0.20.83 → 0.20.85

package/README.md

@@ -157,6 +157,8 @@ aginti --resume <session-id> \
 
 Permission behavior is intentionally consistent: writes inside the current project are allowed through file tools, network/setup runs are normal in approved Docker workspace mode, and outside-project or trusted-host actions stop with a clear blocker plus a suggested rerun command. See [runtime modes and autonomy](docs/runtime-modes-and-autonomy.md) for the full contract.
 
+Tmux follows the same rule. In Docker sandbox mode, `tmux_start_session` and `tmux_send_keys` are durable host tools, but their commands must stay workspace-bound. Use `--sandbox-mode host` when a tmux task needs absolute host paths outside the project.
+
 ## Permission Recipes
 
 Use these when you want explicit control instead of the default interactive policy:
@@ -256,7 +258,7 @@ Inside chat:
 /aaps dry-run workflows/main.aaps
 ```
 
-Use AAPS when the task is bigger than a single chat: app development with stages, paper/book workflows, validation gates, recovery steps, artifact production, or top-down agentic scripts. The current adapter is intentionally lightweight: prompt-only AAPS tasks are reported as handoffs and do not automatically execute an LLM/backend agent yet, so AgInTiFlow warns when a run has no executable steps or misses a declared output. See [docs/aaps.md](docs/aaps.md) and the package [https://www.npmjs.com/package/@lazyingart/aaps](https://www.npmjs.com/package/@lazyingart/aaps).
+Use AAPS when the task is bigger than a single chat: app development with stages, paper/book workflows, validation gates, recovery steps, artifact production, or top-down agentic scripts. There are two bridge directions: AgInTiFlow can inspect/validate/compile/run `.aaps` workflows with `aginti aaps ...`, and AAPS can call AgInTiFlow as the backend implementation agent with `aaps prompt "goal" --backend aginti`. See [docs/aaps.md](docs/aaps.md) and the package [https://www.npmjs.com/package/@lazyingart/aaps](https://www.npmjs.com/package/@lazyingart/aaps).
 
 ## Local API Quick Reference
 

package/docs/aaps.md

@@ -9,6 +9,11 @@ The integration is intentionally lightweight. AgInTiFlow does not vendor the AAP
 3. `aaps` on `PATH`.
 4. A sibling development checkout at `~/ProjectsLFS/AAPS/scripts/aaps.js` when present.
 
+There are two useful bridge directions:
+
+- `aginti aaps ...`: AgInTiFlow is the interactive runtime and calls the AAPS CLI to inspect, validate, compile, dry-run, or run project workflows.
+- `aaps prompt "goal" --backend aginti`: AAPS writes a durable backend-agent handoff under `.aaps-work/prompts/` and invokes AgInTiFlow as the implementation agent for the goal.
+
 ## CLI
 
 ```bash
@@ -46,6 +51,16 @@ Current lightweight adapter boundary: prompt-only AAPS tasks are recorded as han
 
 `aginti aaps install` installs `@lazyingart/aaps` as a project dev dependency only when the current project has `package.json`. Use `aginti aaps install global` only when you intentionally want a global npm install.
 
+If you want AAPS itself to hand a top-level goal to AgInTiFlow, use the AAPS CLI:
+
+```bash
+aaps prompt "Create and validate an executable workflow that writes reports/smoke.md" --project . --backend aginti
+aaps "Create a small AAPS workflow and run it" --project . --backend aginti
+aaps prompt "Prepare the backend prompt only" --project . --backend print --json
+```
+
+The generated AAPS handoff is sandbox-aware: it asks the backend to prefer installed `aaps`, use Docker-safe `npx -y @lazyingart/aaps@<version>` when package installs/network are approved, and use a source checkout only when that path is visible inside the active sandbox.
+
 ## Project Shape
 
 `aginti aaps init` creates a starter project without overwriting existing files:

package/docs/runtime-modes-and-autonomy.md

@@ -13,6 +13,8 @@ The failed task was expected under the current Docker design, but the agent shou
 
 The fix is guidance plus guardrails: raw `tmux` shell commands are blocked inside Docker `run_command`, and the model is told to use host tmux tools for durable sessions.
 
+Important boundary: host tmux tools are durable, but they are not a permission escape hatch. In `docker-readonly` and `docker-workspace` modes, `tmux_start_session` and `tmux_send_keys` are still workspace-bound. Startup commands and sent shell text must use relative paths under the project, not absolute host paths outside the project. If a task really needs `/home/...`, `/etc/...`, an emulator outside the project, or whole-host maintenance, rerun explicitly with `--sandbox-mode host`.
+
 ## Execution Modes
 
 | Mode | Similar Codex idea | Best use | What persists | Risk |
@@ -137,7 +139,7 @@ Durable tmux task:
 aginti "start a tmux session named demo, run ls in it, keep it open, and tell me how to attach"
 ```
 
-The agent should use `tmux_start_session`, `tmux_send_keys`, and `tmux_capture_pane`, not Docker `run_command`.
+The agent should use `tmux_start_session`, `tmux_send_keys`, and `tmux_capture_pane`, not Docker `run_command`. In Docker sandbox mode, tmux commands must stay inside the project. For trusted whole-host tmux work, use the host recipe above.
 
 ## Future Persistent Container Mode
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.83",
+  "version": "0.20.85",
   "type": "module",
   "description": "Low-cost, project-aware Web and CLI agents with DeepSeek/Venice/OpenAI routing, visible tool calls, durable sessions, scouts, AAPS, SCS, and guarded local execution.",
   "license": "Apache-2.0",

package/scripts/smoke-tmux-tools.js

@@ -22,6 +22,12 @@ const config = {
   allowShellTool: true,
   commandCwd: workspace,
 };
+const dockerConfig = {
+  ...config,
+  useDockerSandbox: true,
+  sandboxMode: "docker-workspace",
+  packageInstallPolicy: "allow",
+};
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -65,23 +71,66 @@ try {
   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");
 
+  const outsidePath = path.join(os.tmpdir(), "agintiflow-outside-workspace-canary.txt");
+  const workspacePath = path.join(workspace, "inside-workspace.txt");
+  const dockerTmuxOutsideStart = checkToolUse({
+    toolName: "tmux_start_session",
+    args: { name: `${session}-outside`, cwd: ".", command: `cat ${outsidePath}` },
+    config: dockerConfig,
+  });
+  assert.equal(dockerTmuxOutsideStart.allowed, false, "Docker-mode tmux_start_session should block outside host paths");
+  assert.equal(dockerTmuxOutsideStart.category, "tmux", "outside tmux path block should be categorized as tmux");
+
+  const dockerTmuxOutsideSend = checkTmuxToolUse(
+    "tmux_send_keys",
+    { target: start.target, text: `cat ${outsidePath}` },
+    dockerConfig
+  );
+  assert.equal(dockerTmuxOutsideSend.allowed, false, "Docker-mode tmux_send_keys should block outside host paths");
+
+  const directOutsideStart = await startTmuxSession(
+    { name: `${session}-direct-outside`, cwd: ".", command: `cat ${outsidePath}` },
+    dockerConfig
+  );
+  assert.equal(directOutsideStart.ok, false, "tmux_start_session should enforce outside host path guard at execution time");
+
+  const directOutsideSend = await sendTmuxKeys(
+    { target: start.target, text: `cat ${outsidePath}`, enter: false },
+    dockerConfig
+  );
+  assert.equal(directOutsideSend.ok, false, "tmux_send_keys should enforce outside host path guard at execution time");
+
+  const dockerTmuxWorkspaceStart = checkToolUse({
+    toolName: "tmux_start_session",
+    args: { name: `${session}-inside`, cwd: ".", command: `cat ${workspacePath}` },
+    config: dockerConfig,
+  });
+  assert.equal(dockerTmuxWorkspaceStart.allowed, true, "Docker-mode tmux_start_session should allow project absolute paths");
+
+  const dockerTmuxRelativeStart = checkToolUse({
+    toolName: "tmux_start_session",
+    args: { name: `${session}-relative`, cwd: ".", command: "cat inside-workspace.txt" },
+    config: dockerConfig,
+  });
+  assert.equal(dockerTmuxRelativeStart.allowed, true, "Docker-mode tmux_start_session should allow workspace-relative paths");
+
   const dockerTmuxCommand = checkToolUse({
     toolName: "run_command",
     args: { command: "tmux new-session -d -s should-not-run" },
-    config: { ...config, useDockerSandbox: true, sandboxMode: "docker-workspace", packageInstallPolicy: "allow" },
+    config: dockerConfig,
   });
   assert.equal(dockerTmuxCommand.allowed, false, "Docker run_command tmux usage should be blocked in favor of host tmux tools");
   const dockerTmuxSearch = checkToolUse({
     toolName: "run_command",
     args: { command: "rg tmux README.md" },
-    config: { ...config, useDockerSandbox: true, sandboxMode: "docker-workspace", packageInstallPolicy: "allow" },
+    config: dockerConfig,
   });
   assert.equal(dockerTmuxSearch.allowed, true, "Docker run_command should still allow harmless tmux text searches");
 
   const dockerNpxAginti = checkToolUse({
     toolName: "run_command",
     args: { command: "npx aginti doctor --json" },
-    config: { ...config, useDockerSandbox: true, sandboxMode: "docker-workspace", packageInstallPolicy: "allow" },
+    config: dockerConfig,
   });
   assert.equal(dockerNpxAginti.allowed, false, "Docker run_command should block npx aginti self-invocation");
   assert.equal(dockerNpxAginti.category, "nested-aginti", "npx aginti block should be categorized");
@@ -89,7 +138,7 @@ try {
   const dockerNestedAginti = checkToolUse({
     toolName: "run_command",
     args: { command: "aginti storage status" },
-    config: { ...config, useDockerSandbox: true, sandboxMode: "docker-workspace", packageInstallPolicy: "allow" },
+    config: dockerConfig,
   });
   assert.equal(dockerNestedAginti.allowed, false, "Docker run_command should block nested aginti CLI calls");
   assert.equal(dockerNestedAginti.category, "nested-aginti", "nested aginti block should be categorized");
@@ -107,6 +156,10 @@ try {
           "list-sessions",
           "secret-guardrail",
           "destructive-guardrail",
+          "docker-tmux-start-outside-path-guardrail",
+          "docker-tmux-send-outside-path-guardrail",
+          "docker-tmux-start-project-path-allowed",
+          "docker-tmux-start-relative-path-allowed",
           "docker-run-command-tmux-guardrail",
           "docker-run-command-tmux-search-allowed",
           "docker-run-command-npx-aginti-guardrail",

package/src/agent-runner.js

@@ -428,7 +428,7 @@ async function createInitialState(config, sessionId) {
           "Permission contract: current-workspace file writes are allowed through workspace file tools when enabled. Outside-workspace paths, host sudo, host OS package installs, destructive git/shell actions, and blocked network/setup must not be bypassed by retrying variants. If a tool result includes permissionAdvice or suggestedCommand, stop, explain the blocker, copy the exact suggestedCommand when giving a rerun path, and ask the user to approve/rerun that mode or choose a safer workspace-relative path. Never invent legacy AgInTi syntax such as `aginti run --sandbox host`; use the exact flags from permissionAdvice.",
           "If an operation fails but a directory, artifact, or file already exists, treat it as pre-existing unless you have evidence this run created or updated it. Verify expected outputs before claiming success.",
           config.allowShellTool
-        ? "Host tmux tools are available for long-running terminals: list sessions, capture panes, send safe keys/text, and start detached sessions. Prefer these tools for monitoring long installs/tests/dev servers without blocking; capture before sending input and never send secrets or sudo passwords. Do not start or install tmux inside Docker run_command containers because those containers are short-lived."
+        ? "Host tmux tools are available for long-running terminals: list sessions, capture panes, send safe keys/text, and start detached sessions. Prefer these tools for monitoring long installs/tests/dev servers without blocking; capture before sending input and never send secrets or sudo passwords. Do not start or install tmux inside Docker run_command containers because those containers are short-lived. In Docker sandbox mode, tmux start/send commands must stay workspace-bound and must not reference absolute host paths outside the project; ask for --sandbox-mode host for trusted whole-host work."
         + " For one-shot tmux commands, redirect stdout/stderr and exit status to a durable workspace log or keep the pane alive for capture; if capture fails because the session ended, do not infer output or exit status."
         : "",
           config.allowFileTools
@@ -894,7 +894,7 @@ async function captureSyntheticSnapshot(store, step, config) {
           : `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. Docker run_command containers are ephemeral, so tmux there will not persist. For one-shot tmux commands, redirect output and exit status to a durable workspace log or keep the pane alive for capture; if capture fails because the session ended, do not infer output or exit status."
+        ? "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. Docker run_command containers are ephemeral, so tmux there will not persist. In Docker sandbox mode, tmux start/send commands must stay workspace-bound and cannot reference absolute host paths outside the project; use --sandbox-mode host for trusted whole-host work. For one-shot tmux commands, redirect output and exit status to a durable workspace log or keep the pane alive for capture; if capture fails because the session ended, do not infer output or exit status."
         : "",
       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. For new standalone generated content, pick a descriptive non-conflicting filename and avoid overwriting unless explicitly requested.`
@@ -1224,7 +1224,7 @@ async function executeTool(browserState, toolCall, snapshot, config, store, obse
         return result;
       }
       case "tmux_send_keys": {
-        const result = await sendTmuxKeys(args);
+        const result = await sendTmuxKeys(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);

package/src/model-client.js

@@ -512,7 +512,7 @@ export async function createPlan(client, config, state) {
             ? `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. Do not run npx aginti, npm exec aginti, or nested aginti diagnostics from this shell; they may resolve stale project packages or create recursive agent sessions. 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. Do not install or run tmux inside Docker run_command containers; those containers are short-lived and cannot preserve tmux servers."
+            ? "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. Do not install or run tmux inside Docker run_command containers; those containers are short-lived and cannot preserve tmux servers. In Docker sandbox mode, tmux startup/send commands are still workspace-bound: use relative project paths, not absolute host paths outside the workspace. Ask for --sandbox-mode host before whole-host tmux work."
             : "",
           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 newly generated standalone prose/docs/stories/assets, choose a descriptive non-conflicting filename from the topic/language instead of generic names like story.txt or output.txt; do not overwrite existing files unless the user explicitly asked to update/replace/overwrite that file. 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.`
@@ -786,7 +786,7 @@ export async function requestNextStep(client, config, messages) {
         function: {
           name: "tmux_send_keys",
           description:
-            "Send literal text and/or safe control keys to a durable 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.",
+            "Send literal text and/or safe control keys to a durable host tmux pane. Use for interacting with known shells or agent sessions after capturing context. Do not send secrets, passwords, sudo passwords, destructive commands, or absolute host paths outside the workspace unless the run is explicitly in host sandbox mode.",
           parameters: {
             type: "object",
             properties: {
@@ -812,7 +812,7 @@ export async function requestNextStep(client, config, messages) {
         function: {
           name: "tmux_start_session",
           description:
-            "Start a detached durable 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. For one-shot commands, redirect output and exit status to a durable workspace log or keep the shell open so capture can verify; do not claim results from an auto-terminated session. This is the correct tmux path in Docker mode because run_command containers are ephemeral.",
+            "Start a detached durable 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. For one-shot commands, redirect output and exit status to a durable workspace log or keep the shell open so capture can verify; do not claim results from an auto-terminated session. In Docker sandbox mode, startup commands must stay workspace-bound and must not reference absolute host paths outside the project; ask for --sandbox-mode host for trusted whole-host work.",
           parameters: {
             type: "object",
             properties: {

package/src/tmux-tools.js

@@ -30,6 +30,8 @@ const ALLOWED_KEYS = new Set([
 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;
+const ABSOLUTE_PATH_PATTERN = /(^|[\s"'`=(:])((?:\/[A-Za-z0-9._@%+~:-]+)+\/?)/g;
+const ALWAYS_ALLOWED_ABSOLUTE_PATHS = new Set(["/dev/null"]);
 
 export const TMUX_TOOL_NAMES = ["tmux_list_sessions", "tmux_capture_pane", "tmux_send_keys", "tmux_start_session"];
 
@@ -103,6 +105,37 @@ function resolveCwd(config, cwd = ".") {
   return { ok: true, cwd: requested };
 }
 
+function isInsideDirectory(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function uniqueAbsolutePaths(text = "") {
+  const paths = new Set();
+  for (const match of String(text || "").matchAll(ABSOLUTE_PATH_PATTERN)) {
+    const candidate = match[2];
+    if (!candidate || candidate.startsWith("//")) continue;
+    paths.add(candidate.replace(/[),.;]+$/g, ""));
+  }
+  return [...paths].filter(Boolean);
+}
+
+function checkWorkspaceBoundTmuxText(text = "", config = {}, label = "tmux text") {
+  if (!config.useDockerSandbox) return { ok: true };
+  const root = path.resolve(config.commandCwd || process.cwd());
+  for (const candidate of uniqueAbsolutePaths(text)) {
+    if (ALWAYS_ALLOWED_ABSOLUTE_PATHS.has(candidate)) continue;
+    const resolved = path.resolve(candidate);
+    if (!isInsideDirectory(root, resolved)) {
+      return {
+        ok: false,
+        reason: `${label} references an absolute host path outside the configured workspace while Docker sandbox mode is active: ${candidate}. Use a workspace-relative path or rerun with --sandbox-mode host for trusted whole-host access.`,
+      };
+    }
+  }
+  return { ok: true };
+}
+
 function parseSessions(stdout = "") {
   return String(stdout || "")
     .split(/\r?\n/)
@@ -186,7 +219,7 @@ export async function captureTmuxPane(args = {}) {
   };
 }
 
-export async function sendTmuxKeys(args = {}) {
+export async function sendTmuxKeys(args = {}, config = {}) {
   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 || "");
@@ -201,6 +234,10 @@ export async function sendTmuxKeys(args = {}) {
   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." };
   }
+  const workspaceBound = checkWorkspaceBoundTmuxText(text, config, "tmux text");
+  if (!workspaceBound.ok) {
+    return { ok: false, toolName: "tmux_send_keys", blocked: true, reason: workspaceBound.reason };
+  }
   for (const key of keys) {
     if (!ALLOWED_KEYS.has(key)) {
       return { ok: false, toolName: "tmux_send_keys", blocked: true, reason: `Unsupported tmux key: ${key}` };
@@ -252,6 +289,10 @@ export async function startTmuxSession(args = {}, config = {}) {
       reason: "tmux startup command appears destructive; ask the user before starting it.",
     };
   }
+  const workspaceBound = checkWorkspaceBoundTmuxText(command, config, "tmux startup command");
+  if (!workspaceBound.ok) {
+    return { ok: false, toolName: "tmux_start_session", blocked: true, reason: workspaceBound.reason };
+  }
 
   const tmuxArgs = ["new-session", "-d", "-s", name.name, "-c", cwd.cwd];
   if (command) tmuxArgs.push(command);
@@ -289,6 +330,8 @@ export function checkTmuxToolUse(toolName, args = {}, config = {}) {
     if (DESTRUCTIVE_PATTERN.test(text)) {
       return { allowed: false, reason: "tmux text appears destructive; ask the user before sending it.", category: "tmux" };
     }
+    const workspaceBound = checkWorkspaceBoundTmuxText(text, config, "tmux text");
+    if (!workspaceBound.ok) return { allowed: false, reason: workspaceBound.reason, 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" };
     }
@@ -309,6 +352,8 @@ export function checkTmuxToolUse(toolName, args = {}, config = {}) {
     if (DESTRUCTIVE_PATTERN.test(command)) {
       return { allowed: false, reason: "tmux startup command appears destructive; ask the user before starting it.", category: "tmux" };
     }
+    const workspaceBound = checkWorkspaceBoundTmuxText(command, config, "tmux startup command");
+    if (!workspaceBound.ok) return { allowed: false, reason: workspaceBound.reason, category: "tmux" };
     return { allowed: true, category: "tmux" };
   }
   return { allowed: true, category: "tmux" };