@lazyingart/agintiflow 0.1.0 → 0.2.0

package/AGENTS.md

@@ -14,10 +14,13 @@
 - `npx aginti-cli --sandbox-status --sandbox-mode docker-readonly`: inspect Docker sandbox readiness.
 - `npx aginti-cli --sandbox-preflight --sandbox-mode docker-readonly`: run safe Docker dependency checks.
 - `npm run web`: start the local web UI on `http://127.0.0.1:3210`.
+- `npx aginti-cli web --port 3210`: start the packaged web UI path.
 - `npm run check`: run syntax checks for `run.js`, `web.js`, and all files in `src/`.
+- `npm run smoke:web-api`: start a temporary web server and verify config, sandbox, mock run, and persisted chat APIs without live model credentials.
+- `npm run smoke:coding-tools`: verify mock workspace writes, patches, and path guardrail blocks.
 - `npm pack --dry-run`: inspect npm package contents before release.
 
-Use `AGENT_PROVIDER=openai` or `AGENT_PROVIDER=deepseek` when running locally.
+Use `AGENT_PROVIDER=openai`, `AGENT_PROVIDER=deepseek`, or `AGENT_PROVIDER=mock` when running locally.
 
 ## Coding Style & Naming Conventions
 
@@ -25,7 +28,7 @@ Use ES modules, 2-space indentation, and semicolons, matching the existing JavaS
 
 ## Testing Guidelines
 
-There is no full automated test suite yet. Treat `npm run check` as the minimum required gate before committing. For behavior changes, do one manual smoke test through either the CLI or the web UI. If you add tests later, place them in a dedicated `test/` directory and name them after the module under test, for example `guardrails.test.js`.
+There is no full automated test suite yet. Treat `npm run check`, `npm run smoke:web-api`, and `npm run smoke:coding-tools` as the minimum required gate before committing. For behavior changes, do one manual smoke test through either the CLI or the web UI. If you add tests later, place them in a dedicated `test/` directory and name them after the module under test, for example `guardrails.test.js`.
 
 ## Commit & Pull Request Guidelines
 
@@ -38,4 +41,4 @@ Commit messages in this repo currently follow short imperative style, for exampl
 
 ## Security & Configuration Tips
 
-Never hard-code API keys. Use environment variables like `OPENAI_API_KEY` and `DEEPSEEK_API_KEY`. Do not expose provider defaults that include API keys through web APIs. Keep wrapper tools advisory and opt-in; do not remove read-only/planning defaults without documenting the risk. Keep npm publish and token commands blocked inside agent runs. Prefer Trusted Publishing through `.github/workflows/npm-publish.yml`; local npm tokens may only live in ignored `.env` or `.npmrc` files and must never be printed or committed. Package installs or venv/conda/npm setup must require the package policy and Docker workspace-write mode. Do not weaken guardrails in `src/guardrails.js` or `src/command-policy.js` without documenting why. Do not commit `.sessions/` artifacts.
+Never hard-code API keys. Use environment variables like `OPENAI_API_KEY` and `DEEPSEEK_API_KEY`. Do not expose provider defaults that include API keys through web APIs. Keep wrapper tools advisory and opt-in; do not remove read-only/planning defaults without documenting the risk. Workspace file tools must stay inside `commandCwd`, block secret-like paths, and preserve before/after hash provenance for writes. Keep npm publish and token commands blocked inside agent runs. Prefer Trusted Publishing through `.github/workflows/npm-publish.yml`; local npm tokens may only live in ignored `.env` or `.npmrc` files and must never be printed or committed. Package installs or venv/conda/npm setup must require the package policy and Docker workspace-write mode. Do not weaken guardrails in `src/guardrails.js`, `src/workspace-tools.js`, or `src/command-policy.js` without documenting why. Do not commit `.sessions/` artifacts.

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 | Optional guarded shell commands, Docker sandbox support, and advisory agent wrappers |
+| Local tools | Guarded workspace file tools, optional shell commands, 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 |
 
@@ -45,8 +45,14 @@ aginti --sandbox-status --sandbox-mode docker-readonly --cwd "$PWD"
 Launch the local web UI from an installed package:
 
 ```bash
-aginti-cli --routing smart --allow-shell "List this folder"
-aginti --sandbox-preflight --sandbox-mode docker-readonly --cwd "$PWD"
+aginti web --port 3210
+# then open http://127.0.0.1:3210
+```
+
+Run the installed CLI without a live provider key by using the local mock route:
+
+```bash
+aginti --provider mock --routing manual --allow-shell --cwd "$PWD" "Report the current directory"
 ```
 
 Run from a source checkout:
@@ -73,7 +79,7 @@ npx aginti-cli --routing smart --allow-shell "List this folder"
 npx aginti-cli --list-routes
 npx aginti-cli --list-wrappers
 npx aginti-cli --sandbox-status --sandbox-mode docker-readonly --cwd /home/lachlan/ProjectsLFS/Agent/AgInTiFlow
-npx aginti-cli --sandbox-preflight --sandbox-mode docker-readonly --cwd /home/lachlan/ProjectsLFS/Agent/AgInTiFlow
+npx aginti-cli --sandbox-preflight --sandbox-mode docker-workspace --cwd /home/lachlan/ProjectsLFS/Agent/AgInTiFlow
 ```
 
 Start from a URL:
@@ -95,16 +101,32 @@ The package exposes both `aginti` and `aginti-cli`; they run the same CLI entryp
 The web app includes:
 
 - Routing dropdown for smart, fast, complex, and manual model selection.
-- Provider dropdown for OpenAI and DeepSeek when manual routing is needed.
+- Provider dropdown for DeepSeek, OpenAI, and local mock mode when manual routing is needed.
 - Language dropdown with 11 persisted UI locales.
 - Editable model field, with DeepSeek v4 flash as the fast default and DeepSeek v4 pro as the complex route.
 - Goal, start URL, allowed domains, working directory, and max-step controls.
-- Sandbox mode, Docker image/status, package-install approval state, and recent sandbox logs.
+- Sandbox mode, Docker image/status, package-install approval state, safe setup warnings, and recent sandbox logs.
+- Wrapper capability panel with an opt-in wrapper toggle and a preferred-wrapper selector defaulting to Codex.
+- Workspace Files panel showing file tools, recent file changes, blocked write attempts, hashes, and compact diffs.
+- Canvas & Artifacts modal with agent-selected renders, screenshot/file explorer, text/image preview, notifications, unread badge, select-to-read, and manual mark-seen.
 - Toggleable shell tool, agent wrappers, headless browser, password typing, and destructive actions.
-- Live run logs above a persistent conversation panel.
+- Persistent conversation panel above compact runtime logs, so follow-up messages stay close to the top.
+- Conversation manager modal for auto-renaming, manual renaming, and deleting saved chat history.
 
 `Start URL` is only a suggestion. The browser opens only when the model chooses a browser tool.
 
+## Website
+
+In the source repository, the marketing website lives in `website/`, is published at `https://flow.lazying.art`, and is separate from the app UI in `public/`.
+
+```bash
+python3 -m http.server 4310 --directory website
+node scripts/capture-website-screenshots.js
+```
+
+The screenshot script captures the live app at `http://127.0.0.1:3210/` by default and writes carousel assets to `website/assets/screenshots/`.
+GitHub Pages deploys the `website/` directory through `.github/workflows/pages.yml`; `website/CNAME` sets the custom domain to `flow.lazying.art`.
+
 ## Safety Model
 
 AgInTiFlow is intentionally conservative:
@@ -112,8 +134,11 @@ AgInTiFlow is intentionally conservative:
 - Password typing is blocked unless explicitly enabled.
 - Destructive browser actions are blocked unless explicitly enabled.
 - Shell commands are disabled unless the shell tool is enabled.
+- Workspace file tools stay inside `commandCwd` and block `.env`, secret-like paths, `.git`, node_modules writes, absolute escapes, binary files, and huge files.
+- File writes record before/after SHA-256 hashes and compact redacted diffs.
 - Guarded shell mode only allows inspection, test/build checks, and approved setup commands.
 - Docker read-only mode mounts the workspace read-only and disables container network access.
+- Docker workspace-write mode is the web UI default so plot, PDF, and test outputs can be written inside the mounted workspace.
 - Docker workspace-write mode is required for approved package or environment setup.
 - Package installs default to `prompt`, so npm/pip/conda/venv setup is blocked until explicitly approved.
 - NPM publishing, npm token commands, sudo, destructive git actions, curl/wget, and shell chaining are blocked.
@@ -130,8 +155,9 @@ DEEPSEEK_API_KEY=...
 MAX_STEPS=15
 HEADLESS=true
 ALLOWED_DOMAINS=news.ycombinator.com,github.com
-ALLOW_SHELL_TOOL=false
-SANDBOX_MODE=docker-readonly
+ALLOW_SHELL_TOOL=true
+ALLOW_FILE_TOOLS=true
+SANDBOX_MODE=docker-workspace
 PACKAGE_INSTALL_POLICY=prompt
 USE_DOCKER_SANDBOX=true
 DOCKER_SANDBOX_IMAGE=agintiflow-sandbox:latest
@@ -156,7 +182,7 @@ Provider credentials:
 
 ## Agent Wrappers
 
-AgInTiFlow can expose external coding agents as advisory tools when `ALLOW_WRAPPER_TOOLS=true` or the web UI toggle is enabled. Wrappers are not a replacement for the core runner; they are used for second opinions, codebase analysis, or planning when they are installed and authenticated.
+AgInTiFlow can expose external coding agents as advisory tools when `ALLOW_WRAPPER_TOOLS=true` or the web UI toggle is enabled. Wrappers are not a replacement for the core runner; they are used for second opinions, codebase analysis, or planning when they are installed and authenticated. The preferred wrapper defaults to Codex and can be changed with `PREFERRED_WRAPPER=codex`, `aginti --allow-wrappers --wrapper codex`, or the web UI dropdown.
 
 Current wrappers:
 
@@ -217,13 +243,22 @@ DOCKER_TARGET_USER=lachlan ./scripts/install-docker-ubuntu.sh
 
 Open a new login shell, or run `newgrp docker`, before testing non-root Docker access.
 
+Build the companion agent toolchain sandbox:
+
+```bash
+./scripts/setup-agent-toolchain-docker.sh
+npm run smoke:toolchain-docker
+```
+
+The setup script idempotently builds `agintiflow-sandbox:latest` from `docker/sandbox.Dockerfile` and verifies Node, npm, Python, NumPy, Matplotlib, `latexmk`, and `pdflatex` inside Docker. The smoke script runs Python plot generation, LaTeX PDF compilation, and PDF artifact preview against the same workspace-mounted sandbox path used by the agent.
+
 ## Sandbox Modes
 
 | Mode | Workspace mount | Network | Intended use |
 | --- | --- | --- | --- |
 | `host` | local process | host network | legacy read-only inspection only |
-| `docker-readonly` | read-only `/workspace` | none | default safe coding inspection and tests |
-| `docker-workspace` | writable `/workspace` | none by default, enabled only for approved package installs | environment setup inside the mounted project |
+| `docker-readonly` | read-only `/workspace` | none | safe coding inspection and tests that do not write files |
+| `docker-workspace` | writable `/workspace` | none by default, enabled only for approved package installs | web UI default for environment setup, plotting, and LaTeX/PDF compilation inside the mounted project |
 
 Package policy values:
 
@@ -233,16 +268,28 @@ Package policy values:
 | `prompt` | Return a clear approval-required error; the UI can switch to approved. |
 | `allow` | Permit allowlisted setup commands only in `docker-workspace`. |
 
+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 they require `docker-workspace` because they write outputs back to `/workspace`. File and canvas tools accept both normal relative paths and Docker virtual paths like `/workspace/report.pdf`, while other absolute host paths remain blocked.
+
 Safe preflight endpoints:
 
 ```bash
 curl http://127.0.0.1:3210/api/sandbox/status
 curl -X POST http://127.0.0.1:3210/api/sandbox/preflight \
   -H 'Content-Type: application/json' \
-  -d '{"sandboxMode":"docker-readonly","buildImage":true}'
+  -d '{"sandboxMode":"docker-workspace","buildImage":true}'
+curl http://127.0.0.1:3210/api/workspace/changes
+curl "http://127.0.0.1:3210/api/sessions/<session-id>/artifacts"
 ```
 
-These endpoints report Docker/image/workspace readiness and recent sandbox logs without returning API keys or npm tokens.
+These endpoints report Docker/image/workspace readiness, recent sandbox logs, file-change provenance, and renderable artifact metadata without returning API keys or npm tokens. Artifact content is loaded on demand through guarded session/workspace reads.
+
+Credential-free API smoke test:
+
+```bash
+npm run smoke:web-api
+```
+
+The smoke script starts the web server on a random localhost port, checks `/api/config`, `/api/sandbox/status`, `/api/sandbox/preflight`, runs mock agent tasks, verifies persisted chat history, and exercises the canvas/artifacts selection API.
 
 ## Runtime Artifacts
 
@@ -257,6 +304,8 @@ Each run stores state under `.sessions/<session-id>/`:
 | `artifacts/step-XXX.png` | Screenshots |
 | `artifacts/step-XXX.snapshot.json` | DOM snapshots |
 
+The web UI derives the Canvas & Artifacts tunnel from `canvas.item`, `canvas.selected`, snapshot, file-change, and final-answer events. Models can call `send_to_canvas` to highlight a text block, diff, image, or workspace file; otherwise the user can manually select any derived artifact in the explorer.
+
 ## Project Structure
 
 ```text
@@ -269,6 +318,7 @@ AgInTiFlow/
 ├── logos/                  # Brand assets and crop notes
 ├── references/             # Design philosophy and research notes
 ├── tools/                  # Reusable project documentation helpers
+├── website/                # Static marketing site and screenshot carousel
 ├── run.js                  # CLI entrypoint
 └── web.js                  # Express web server
 ```
@@ -277,9 +327,12 @@ AgInTiFlow/
 
 ```bash
 npm run check
+npm run smoke:web-api
+npm run smoke:coding-tools
+npm test
 ```
 
-The check validates JavaScript syntax for the CLI, web server, and runtime modules.
+`npm run check` validates JavaScript syntax for the CLI, web server, and runtime modules. The smoke scripts use the local mock provider, so they do not require DeepSeek or OpenAI credentials.
 
 ## Prompt Tools
 

package/docker/sandbox.Dockerfile

@@ -12,11 +12,19 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
   grep \
   npm \
   nodejs \
+  latexmk \
+  poppler-utils \
+  python3-matplotlib \
+  python3-numpy \
   python3-pip \
   python3-venv \
   python3 \
   ripgrep \
   sed \
+  texlive-fonts-recommended \
+  texlive-latex-base \
+  texlive-latex-extra \
+  texlive-latex-recommended \
   && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /workspace

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "AgInTiFlow is a resumable Playwright website-control agent with OpenAI-compatible tool calling.",
   "license": "Apache-2.0",
-  "homepage": "https://github.com/lazyingart/AgInTiFlow#readme",
+  "homepage": "https://flow.lazying.art",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lazyingart/AgInTiFlow.git"
@@ -39,6 +39,10 @@
     "logos/logo.png",
     "public/",
     "scripts/install-docker-ubuntu.sh",
+    "scripts/setup-agent-toolchain-docker.sh",
+    "scripts/smoke-coding-tools.js",
+    "scripts/smoke-toolchain-docker.js",
+    "scripts/smoke-web-api.js",
     "src/",
     "run.js",
     "web.js"
@@ -51,7 +55,11 @@
     "start": "node run.js",
     "web": "node web.js",
     "check": "node --check run.js && node --check web.js && node --check bin/aginti-cli.js && node --check src/*.js",
-    "test": "npm run check",
+    "setup:toolchain-docker": "scripts/setup-agent-toolchain-docker.sh",
+    "smoke:coding-tools": "node scripts/smoke-coding-tools.js",
+    "smoke:toolchain-docker": "node scripts/smoke-toolchain-docker.js",
+    "smoke:web-api": "node scripts/smoke-web-api.js",
+    "test": "npm run check && npm run smoke:web-api && npm run smoke:coding-tools",
     "pack:dry-run": "npm pack --dry-run"
   },
   "dependencies": {