@lazyingart/agintiflow 0.20.115 → 0.20.117

package/README.md

@@ -53,6 +53,8 @@ Most agent tools are either a chat box with hidden state or an expensive one-mod
 | Inspectable beats mysterious | Plans, tool calls, file diffs, command output, canvas artifacts, and session events are saved and resumable. |
 | Disciplined by default | `AGINTI.md` starts with a behavior contract: surface ambiguity, keep edits surgical, avoid speculative complexity, verify outcomes, and respect permission blockers. |
 | Role-based models | Route, main, spare, wrapper, and auxiliary image roles are separate. You can use cheap route models, stronger main models, optional OpenAI/Qwen/Venice routes, and GRS AI/Venice image tools. |
+| Writing without agent noise | `writing_specialist` drafts novels, books, scripts, essays, and paper prose in an isolated writing-only context, then the main agent handles files, formatting, citations, checks, and artifacts. |
+| Visual and web evidence | `read_image` reads screenshots/figures with typed perception artifacts, `web_research` saves sourced research artifacts, and `research_wrapper` can ask Codex `gpt-5.4-mini` medium for a strict-JSON second opinion. |
 | Scouts before big work | Parallel scouts can cheaply map architecture, tests, risks, symbols, and integration points before the main executor edits anything. |
 | SCS for high-risk work | Student-Committee-Supervisor mode adds a typed gate: committee drafts, student approves/monitors, supervisor executes. Use `/scs` or `--scs auto`. |
 | AAPS for large workflows | AAPS describes top-down agentic pipeline scripts; AgInTiFlow can act as the interactive backend that validates, compiles, and executes those workflows. |
@@ -132,12 +134,16 @@ aginti --language de
 | Review current repo | `/review [focus]` |
 | Toggle SCS quality gate | `/scs` |
 | Use SCS only for complex work | `/scs auto` or `aginti --scs auto "task"` |
+| Control dynamic step budgets | `--dynamic-steps auto\|on\|off` |
 | Work with AAPS workflows | `aginti aaps status`, `/aaps validate` |
 | Choose models | `/route`, `/model`, `/spare`, `/wrapper`, `/auxiliary model` |
 | Switch permissions | `-s safe`, `-s normal`, `-s danger`, or `/safe`, `/normal`, `/danger` |
 | Enable Venice shortcut | `/venice` |
 | Generate images | `/auxiliary image`, then ask for an image |
-| Resume current project | `aginti resume` |
+| Read screenshots/images | `/image-read path/to/screenshot.png "what changed?"` |
+| Research with sources | `/web-research latest Android Gradle plugin official docs` |
+| Enable research wrapper | `/research-wrapper gpt-5.4-mini medium` |
+| Resume current project | `aginti resume` (`1` is newest/latest; Space shows more) |
 | Browse all sessions | `aginti resume --all-sessions` |
 | Queue into a running session | `aginti queue <session-id> "extra instruction"` |
 | Clean empty sessions | `aginti --remove-empty-sessions` |
@@ -145,7 +151,9 @@ aginti --language de
 | Sync reviewed skills | `aginti skillmesh status`, `aginti skillmesh sync` |
 | Update CLI | `aginti update` |
 
-Interactive chat supports slash completion, Up/Down selectors, multiline input with `Ctrl+J`, full resume history, Markdown rendering, visible run status, ASAP pipe messages during a run, and clean interruption/resume with `Ctrl+C`. Installed interactive commands also check npm for a newer AgInTiFlow release and show an update/skip selector; source checkouts and non-TTY automation are left alone.
+Interactive chat supports slash completion, Up/Down selectors, a newest-first resume selector with direct Space pagination, multiline input with `Ctrl+J`, full resume history, Markdown rendering, visible run status, ASAP pipe messages during a run, and clean interruption/resume with `Ctrl+C`. Installed interactive commands also check npm for a newer AgInTiFlow release and show an update/skip selector; source checkouts and non-TTY automation are left alone.
+
+AgInTiFlow treats `maxSteps` as an initial budget, not a silent infinite loop. By default, real-provider runs can receive a bounded extension only near the limit, only when recent tool/file/artifact evidence shows concrete progress, and never to bypass permission, package, host, or secret guardrails. Use `--dynamic-steps off` for a strict hard stop, or `--dynamic-steps on` to test the budget gate in mock/offline runs.
 
 For a fully controlled one-shot resume, use an explicit session id and choose the task profile deliberately. Use `auto` for normal routing or `android` when the work is Android/emulator-specific:
 
@@ -202,12 +210,14 @@ The website keeps the visual walkthrough in a carousel so this README can stay f
 | --- | --- |
 | CLI agent workspace | Persistent terminal chat with project cwd, session resume, visible model/tool state, and clean command hints. |
 | Local web workspace | Browser UI for sessions, runtime logs, artifacts, model settings, project controls, canvas previews, and sandbox status. |
-| File tools | `inspect_project`, `list_files`, `read_file`, `search_files`, `write_file`, `apply_patch`, `open_workspace_file`, and `preview_workspace`. |
+| File tools | `inspect_project`, `list_files`, `read_file`, `search_files`, `write_file`, `apply_patch`, `open_workspace_file`, `preview_workspace`, and `read_image`. |
 | Shell tools | Guarded host or Docker workspace shell execution with package-install policy and command safety checks. |
 | Browser tools | Playwright browser actions with lazy startup and optional domain allowlists. |
 | Model routing | DeepSeek fast/pro defaults, manual OpenAI/Qwen/Venice/mock routes, spare models, wrapper models, and auxiliary image models. |
+| Writing specialist | A dedicated writing-only LLM call for prose, chapters, scripts, books, essays, research-paper sections, and revisions, with formatter handoff notes for Markdown/LaTeX/Final Draft. |
 | Patch workflow | Codex-style patch envelopes, unified diffs, exact replacements, hashes, compact diffs, and path guardrails. |
 | Parallel scouts | Optional scout calls for architecture, implementation, review, tests, git flow, research, symbol tracing, and dependency risk. |
+| Image reading and web research | `read_image` uses OpenAI vision for workspace images when `OPENAI_API_KEY` is configured. `web_research` preserves source lists, and optional OpenAI hosted web search or `research_wrapper` can be used for higher-confidence research. |
 | SCS mode | Optional Student-Committee-Supervisor quality gate for complicated or risky tasks. |
 | AAPS adapter | Optional `@lazyingart/aaps` integration for `.aaps` workflow init, validate, parse, compile, dry-run, and run commands. |
 | Image generation | Optional GRS AI and Venice image tools with saved manifests and canvas artifact previews. |
@@ -224,7 +234,7 @@ AgInTiFlow does not treat "the model" as one global setting. It has roles:
 | Route | `deepseek/deepseek-v4-flash` | Cheap planner, triage, short tasks, routing decisions. |
 | Main | `deepseek/deepseek-v4-pro` | Complex coding, debugging, writing, research, long tasks. |
 | Spare | `openai/gpt-5.4` medium | Optional fallback or cross-check route. |
-| Wrapper | `codex/gpt-5.5` medium | Optional external coding-agent advisor. |
+| Wrapper | `codex/gpt-5.5` medium | Optional external coding-agent advisor; `research_wrapper` defaults to `gpt-5.4-mini` medium for image/web second opinions. |
 | Auxiliary | `grsai/nano-banana-2` | Image generation and other non-text helper tools. |
 
 Useful selectors:
@@ -339,6 +349,7 @@ More detail:
 
 - [docs/model-selection.md](docs/model-selection.md)
 - [docs/auxiliary-image-generation.md](docs/auxiliary-image-generation.md)
+- [docs/perception-and-web-research.md](docs/perception-and-web-research.md)
 - [docs/cli-i18n.md](docs/cli-i18n.md)
 - [docs/skillmesh.md](docs/skillmesh.md)
 
@@ -352,6 +363,7 @@ More detail:
 | Large-codebase engineering | [docs/large-codebase-engineering.md](docs/large-codebase-engineering.md) |
 | Runtime modes and autonomy | [docs/runtime-modes-and-autonomy.md](docs/runtime-modes-and-autonomy.md) |
 | Skills and tools | [docs/skills-and-tools.md](docs/skills-and-tools.md) |
+| Image reading and web research | [docs/perception-and-web-research.md](docs/perception-and-web-research.md) |
 | Skill Mesh | [docs/skillmesh.md](docs/skillmesh.md) |
 | Housekeeping logs | [docs/housekeeping.md](docs/housekeeping.md) |
 | npm publishing | [docs/npm-publishing.md](docs/npm-publishing.md) |

package/docs/large-codebase-engineering.md

@@ -52,6 +52,24 @@ Mature coding agents avoid keeping an entire growing project in the prompt. AgIn
 
 This keeps the main executor sober: it knows where it is in the repo, but it still re-reads exact files before editing and validates with commands rather than trusting stale memory.
 
+## Surgical Context Pack
+
+For complex engineering tasks where parallel scouts are disabled or unavailable, AgInTiFlow now prepares a lightweight surgical context pack before planning/execution:
+
+- refreshes `.aginti/codebase-map.json` with `inspect_project`
+- saves a session artifact named `surgical-context-pack.json`
+- injects a compact repo overview into the model history
+- includes an explicit surgical editing contract and evidence-card template
+- carries the context handle in runtime snapshots so later steps can rehydrate exact files by path/search
+
+This is intentionally not a whole-repo dump. The context pack is an overview handle. The executor must still search and read exact files before patching, state the active boundary, patch the smallest coherent surface, inspect the diff, and run focused checks.
+
+The effective loop is:
+
+```text
+overview map -> active evidence card -> exact file windows -> surgical patch -> focused check -> diff review -> broader check if needed
+```
+
 ## Git Discipline
 
 When asked to commit, pull, merge, or push, the agent should run `git status --short` and `git diff --stat` first. It should commit only intended changes, use `git fetch` and `git pull --ff-only` when remote state matters, and stop for the user on conflicts, divergence, unrelated dirty files, or any merge/rebase/reset choice. Web and CLI logs fold long command output but keep full command summaries visible.

package/docs/model-selection.md

@@ -14,6 +14,8 @@ AgInTiFlow treats model choice as a role-based control plane. A provider supplie
 
 Smart routing still works as before: normal work goes to the route model, and complex work goes to the main model. Manual provider/model selection remains available for one-off runs.
 
+Long writing tasks use an additional tool boundary: `writing_specialist`. The main model still plans the run, manages files, formats Markdown/LaTeX/Final Draft output, compiles/checks artifacts, and finishes. The specialist gets only the writing brief, canon, style guide, prior draft, target, audience, constraints, and format intent, then returns prose plus a formatter handoff. This avoids polluting fiction/manuscript drafting with shell, browser, safety, and agent-runtime context. Set `AGINTI_WRITING_PROVIDER` or `AGINTI_WRITING_MODEL` to route this isolated writer separately from the main agent.
+
 ## CLI Commands
 
 ```bash

package/docs/perception-and-web-research.md

@@ -0,0 +1,48 @@
+# Image Reading And Web Research
+
+AgInTiFlow separates visual understanding, web search, and wrapper advice so each output has a clear evidence trail.
+
+## Tools
+
+| Tool | Purpose | Evidence |
+| --- | --- | --- |
+| `read_image` | Read workspace screenshots, plots, scanned text, diagrams, or allowed remote image URLs. | Saves `artifacts/perception/*-read-image.json` in the central session store with image hashes, MIME type, size, model, prompt, and typed result. |
+| `web_search` | Cheap raw search snippets. | Returns compact titles, URLs, snippets, and fallback search URL. |
+| `web_research` | Sourced research unit for current or external information. | Saves `artifacts/research/*-web-research.json` with query, mode, source list, and answer. |
+| `research_wrapper` | Read-only strict-JSON second opinion from the selected wrapper. | Saves `artifacts/wrappers/*-research-wrapper.json` with wrapper, model, reasoning, metadata, result, and raw fallback output. |
+
+## Defaults
+
+- `read_image` uses OpenAI Responses vision when `OPENAI_API_KEY` is configured.
+- `read_image` defaults to `AGINTI_PERCEPTION_MODEL=gpt-5.4-mini` and `AGINTI_PERCEPTION_REASONING=medium`, then falls back through `AGINTI_PERCEPTION_FALLBACK_MODELS` or `gpt-4o-mini` if the account lacks access to the preferred model.
+- `web_research` defaults to lightweight snippet mode; use `mode=openai` only when hosted OpenAI web search is needed and configured.
+- `web_research mode=openai` defaults to `AGINTI_WEB_RESEARCH_MODEL=gpt-5.4-mini` / `medium`, then falls back through `AGINTI_WEB_RESEARCH_FALLBACK_MODELS` or `gpt-4o-mini`.
+- `research_wrapper` defaults to `AGINTI_RESEARCH_WRAPPER_MODEL=gpt-5.4-mini` and `AGINTI_RESEARCH_WRAPPER_REASONING=medium`.
+- Wrapper advice is not evidence by itself. Verify file paths, sources, hashes, and artifacts before claiming completion.
+
+## Interactive Commands
+
+```text
+/image-read artifacts/screenshots/app.png what looks wrong?
+/web-research latest Android Gradle plugin official docs
+/research-wrapper gpt-5.4-mini medium
+/research-wrapper off
+```
+
+## Agent Usage
+
+Use `read_image` when pixels matter. Do not guess from filenames or surrounding text if the user asks about a screenshot, chart, microscopy image, or scanned page.
+
+Use `web_research` when freshness, sources, package docs, standards, or current external information matter. Use `domains` to restrict research to official or primary sources.
+
+Use `research_wrapper` when a second model should cross-check image/web/research conclusions. The wrapper receives a strict JSON contract and should preserve uncertainty when it cannot directly inspect a source.
+
+## Safety
+
+- Local image paths must stay inside the workspace unless the run is explicitly trusted host mode.
+- `.env`, credential files, private keys, and secret-looking paths are blocked.
+- Remote images require web access and respect domain allowlists.
+- Images are capped at 10 MB and four inputs per call.
+- Artifacts preserve hashes and metadata but never store API keys.
+
+See the design note in [references/multimodal-research-wrapper-design.md](../references/multimodal-research-wrapper-design.md).

package/docs/skills-and-tools.md

@@ -6,7 +6,7 @@ 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`, `tmux_capture_pane`, or `send_to_canvas`.
+**Tool**: A deterministic or bounded callable capability exposed to the model, such as `inspect_project`, `read_file`, `apply_patch`, `run_command`, `web_search`, `web_research`, `read_image`, `writing_specialist`, `research_wrapper`, `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.
 
@@ -56,3 +56,18 @@ Selected skills are injected into the plan and execution prompts. The LLM still
 Create `skills/<id>/SKILL.md` with valid YAML frontmatter and a short Markdown body. Keep descriptions strings, not YAML arrays, because loaders expect `id`, `label`, and `description` as scalar strings.
 
 Good skills are small, actionable, and tool-aware. They should say what to inspect, what to create or verify, and what to avoid. They should not hard-code one exact task.
+
+For visual or current-information tasks, prefer:
+
+- `read_image` for screenshots, plots, diagrams, microscopy images, scanned text, and UI debugging.
+- `web_research` for sourced research artifacts with source URLs and optional domain restrictions.
+- `research_wrapper` for strict-JSON second opinions from the selected read-only wrapper, usually Codex `gpt-5.4-mini` medium.
+
+See [Image Reading And Web Research](perception-and-web-research.md).
+
+For substantial writing tasks, prefer:
+
+- `writing_specialist` for isolated prose, scene, chapter, paper-section, script, book, essay, and revision drafting.
+- The main agent for all non-writing work around that draft: file names, workspace edits, citations, Markdown/LaTeX/Final Draft formatting, PDF compilation, canvas publishing, and verification.
+
+The writer receives only writing context: brief, canon, style guide, prior draft, target, audience, constraints, length, and downstream format intent. It should not receive shell/file/browser policy or agent-runtime details.

package/docs/student-committee-supervisor.md

@@ -66,6 +66,12 @@ The current implementation is deliberately bounded:
 
 Auto mode stays off for simple turns.
 
+## Dynamic Step Budgets
+
+AgInTiFlow treats `maxSteps` as the initial run budget. Near the boundary, the runtime may grant a bounded extension only when recent tool/file/artifact evidence shows concrete progress and no permission blocker is being bypassed.
+
+Normal mode uses a lightweight deterministic monitor. `/scs on` and activated `/scs auto` runs add the SCS student budget gate, which can emit `extend_steps`, `deny_extension`, or `rethink_plan`. More steps never escalate permissions, package policy, host access, destructive actions, or secret access. Use `--dynamic-steps off` when a strict hard stop is required. The detailed design is tracked in [references/dynamic-step-budget-and-scs-auto.md](../references/dynamic-step-budget-and-scs-auto.md).
+
 ## When To Use It
 
 Use SCS for:

package/i18n/README.ar.md

@@ -20,7 +20,7 @@
 
 **وكلاء منخفضو التكلفة وواعون بالمشروع للمشكلات الواقعية.**
 
-استخدم مساحة عمل الوكيل نفسها من Web أو CLI، مع توجيه DeepSeek/Venice/OpenAI، واستدعاءات أدوات مرئية، وجلسات دائمة، وscouts، وإشراف SCS، وسير عمل AAPS، وتنفيذ محلي محمي.
+AgInTiFlow هو مساحة عمل project-aware agent للبحث والتطوير hybrid wet-dry، والذكاء المدرك للعتاد، وأتمتة البرمجيات، وسير العمل الصناعي. من تخطيط المختبر إلى تحليل البيانات، ومن التحكم بالعتاد إلى سكربتات الإنتاج، ومن microscopy والطائرات بدون طيار والروبوتات إلى التقارير، يساعد الوكلاء على العمل عبر API أو Web أو CLI مع إشراف SCS وسير عمل AAPS والتنفيذ المحمي والأدلة الدائمة.
 
 باختصار: شغّل `aginti` داخل مشروع، أعطه مهمة، افحص خطته، شاهد كل استدعاء أداة، استأنف لاحقاً، واحتفظ بالمخرجات داخل مساحة العمل.
 

package/i18n/README.de.md

@@ -20,7 +20,7 @@
 
 **Günstige, projektbewusste Agenten für reale Probleme.**
 
-Nutze denselben Agenten-Workspace aus Web oder CLI, mit DeepSeek/Venice/OpenAI-Routing, sichtbaren Tool-Calls, dauerhaften Sessions, Scouts, SCS-Supervision, AAPS-Workflows und geschützter lokaler Ausführung.
+AgInTiFlow ist ein project-aware Agent-Workspace für hybride Wet-Dry-R&D, hardware-aware Intelligence, Software-Automatisierung und industrielle Workflows. Von Laborplanung zu Datenanalyse, von Hardwaresteuerung zu Produktionsskripten und von Mikroskopie, Drohnen und Robotern zu Berichten hilft es Agenten, über API, Web oder CLI mit SCS-Supervision, AAPS-Workflows, geschützter Ausführung und dauerhafter Evidenz zu arbeiten.
 
 Kurz gesagt: Führe `aginti` in einem Projekt aus, gib eine Aufgabe vor, prüfe den Plan, sieh jeden Tool-Call, setze später fort und behalte die Ergebnisse im Workspace.
 

package/i18n/README.es.md

@@ -20,7 +20,7 @@
 
 **Agentes de bajo costo y conscientes del proyecto para problemas reales.**
 
-Usa el mismo workspace de agente desde Web o CLI, con routing DeepSeek/Venice/OpenAI, llamadas de herramientas visibles, sesiones durables, scouts, supervisión SCS, workflows AAPS y ejecución local protegida.
+AgInTiFlow es un workspace de agentes project-aware para I+D híbrida wet-dry, inteligencia hardware-aware, automatización de software y workflows industriales. Desde planificación de laboratorio hasta análisis de datos, desde control de hardware hasta scripts de producción, y desde microscopía, drones y robots hasta informes, ayuda a los agentes a trabajar mediante API, Web o CLI con supervisión SCS, workflows AAPS, ejecución protegida y evidencia duradera.
 
 La idea breve: ejecuta `aginti` dentro de un proyecto, dale una tarea, revisa el plan, ve cada llamada de herramienta, reanuda más tarde y conserva las salidas dentro de tu workspace.
 

package/i18n/README.fr.md

@@ -20,7 +20,7 @@
 
 **Des agents à faible coût, conscients du projet, pour des problèmes réels.**
 
-Utilisez le même espace de travail agent depuis le Web ou le CLI, avec routage DeepSeek/Venice/OpenAI, appels d’outils visibles, sessions durables, scouts, supervision SCS, workflows AAPS et exécution locale protégée.
+AgInTiFlow est un espace de travail d'agents project-aware pour la R&D hybride wet-dry, l'intelligence hardware-aware, l'automatisation logicielle et les workflows industriels. De la planification de laboratoire à l'analyse de données, du contrôle matériel aux scripts de production, et de la microscopie, des drones et des robots aux rapports, il aide les agents à travailler via API, Web ou CLI avec supervision SCS, workflows AAPS, exécution protégée et preuves durables.
 
 En bref : lancez `aginti` dans un projet, donnez-lui une tâche, inspectez son plan, voyez chaque appel d’outil, reprenez plus tard et gardez les sorties dans votre workspace.
 

package/i18n/README.ja.md

@@ -20,7 +20,7 @@
 
 **実際の問題に向けた、低コストでプロジェクトを理解するエージェント。**
 
-Web または CLI から同じエージェントワークスペースを使い、DeepSeek/Venice/OpenAI ルーティング、見えるツール呼び出し、永続セッション、scouts、SCS 監督、AAPS ワークフロー、保護されたローカル実行を扱えます。
+AgInTiFlow は、ハイブリッド wet-dry R&D、hardware-aware intelligence、ソフトウェア自動化、産業ワークフローのための project-aware agent workspace です。実験計画からデータ解析、ハードウェア制御から生産スクリプト、顕微鏡画像・ドローン・ロボットからレポートまで、SCS 監督、AAPS ワークフロー、保護された実行、永続的な証拠を備えて、API、Web、CLI からエージェントが作業できるようにします。
 
 要するに、プロジェクト内で `aginti` を実行し、タスクを渡し、計画とツール呼び出しを確認し、後で再開し、成果物をワークスペースに残せます。
 

package/i18n/README.ko.md

@@ -20,7 +20,7 @@
 
 **실제 문제를 위한 저비용, 프로젝트 인식 에이전트.**
 
-Web 또는 CLI에서 같은 에이전트 작업공간을 사용하며 DeepSeek/Venice/OpenAI 라우팅, 보이는 도구 호출, 영구 세션, scouts, SCS 감독, AAPS 워크플로, 보호된 로컬 실행을 제공합니다.
+AgInTiFlow는 hybrid wet-dry R&D, hardware-aware intelligence, software automation, industrial workflow를 위한 project-aware agent workspace입니다. 실험 계획부터 데이터 분석까지, 하드웨어 제어부터 production script까지, microscopy, drone, robot부터 report까지, SCS supervision, AAPS workflow, guarded execution, durable evidence와 함께 API, Web, CLI로 에이전트가 작업하게 합니다.
 
 짧게 말하면, 프로젝트 안에서 `aginti`를 실행하고 작업을 맡긴 뒤 계획과 모든 도구 호출을 확인하며, 나중에 다시 이어서 실행하고 결과물을 작업공간에 남길 수 있습니다.
 

package/i18n/README.ru.md

@@ -20,7 +20,7 @@
 
 **Недорогие, проектно-ориентированные агенты для реальных задач.**
 
-Используйте одно и то же агентное рабочее пространство из Web или CLI: маршрутизация DeepSeek/Venice/OpenAI, видимые вызовы инструментов, долговечные сессии, scouts, SCS-супервизия, AAPS-workflows и защищенное локальное выполнение.
+AgInTiFlow — project-aware рабочее пространство для агентов, предназначенное для hybrid wet-dry R&D, hardware-aware intelligence, автоматизации software и промышленных workflow. От планирования лабораторных работ до анализа данных, от управления hardware до production scripts, от microscopy, drones и robots до отчетов, оно помогает агентам работать через API, Web или CLI с SCS supervision, AAPS workflows, guarded execution и долговечной доказательной базой.
 
 Коротко: запустите `aginti` внутри проекта, дайте задачу, проверьте план, увидьте каждый tool call, возобновите работу позже и сохраняйте результаты в рабочей папке.
 

package/i18n/README.vi.md

@@ -20,7 +20,7 @@
 
 **Agent chi phí thấp, hiểu dự án, cho các vấn đề thực tế.**
 
-Dùng cùng một workspace agent từ Web hoặc CLI, với routing DeepSeek/Venice/OpenAI, tool call nhìn thấy được, session bền vững, scouts, giám sát SCS, workflow AAPS và thực thi cục bộ có bảo vệ.
+AgInTiFlow là một project-aware agent workspace cho hybrid wet-dry R&D, hardware-aware intelligence, software automation và industrial workflows. Từ lập kế hoạch thí nghiệm đến phân tích dữ liệu, từ điều khiển phần cứng đến production scripts, và từ microscopy, drones, robots đến reports, nó giúp agent làm việc qua API, Web hoặc CLI với SCS supervision, AAPS workflows, guarded execution và durable evidence.
 
 Nói ngắn gọn: chạy `aginti` trong một dự án, giao nhiệm vụ, xem kế hoạch, kiểm tra từng tool call, tiếp tục lại sau, và giữ kết quả trong workspace.
 

package/i18n/README.zh-Hans.md

@@ -20,7 +20,7 @@
 
 **面向真实问题的低成本、项目感知智能体。**
 
-从 Web 或 CLI 使用同一个智能体工作区，支持 DeepSeek/Venice/OpenAI 路由、可见工具调用、持久会话、scouts、SCS 监督、AAPS 工作流，以及受保护的本地执行。
+AgInTiFlow 是一个 project-aware agent 工作空间，面向混合干湿研发、硬件感知智能、软件自动化和工业工作流。从实验规划到数据分析，从硬件控制到生产脚本，从显微成像、无人机和机器人到报告，它帮助智能体通过 API、Web 或 CLI 工作，并配合 SCS 监督、AAPS 工作流、受保护执行和持久证据。
 
 简短理解：在项目目录里运行 `aginti`，交给它一个任务，检查它的计划，看到每一次工具调用，之后还能恢复会话，并把输出保留在你的工作区里。
 

package/i18n/README.zh-Hant.md

@@ -20,7 +20,7 @@
 
 **面向真實問題的低成本、專案感知智能體。**
 
-從 Web 或 CLI 使用同一個智能體工作區，支援 DeepSeek/Venice/OpenAI 路由、可見工具呼叫、持久會話、scouts、SCS 監督、AAPS 工作流，以及受保護的本地執行。
+AgInTiFlow 是一個 project-aware agent 工作空間，面向混合乾濕研發、硬體感知智能、軟體自動化與工業工作流。從實驗規劃到資料分析，從硬體控制到生產腳本，從顯微成像、無人機和機器人到報告，它幫助智能體透過 API、Web 或 CLI 工作，並配合 SCS 監督、AAPS 工作流、受保護執行與持久證據。
 
 簡短理解：在專案目錄執行 `aginti`，交給它一個任務，檢查它的計畫，看見每一次工具呼叫，之後還能恢復會話，並把輸出保留在你的工作區裡。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.115",
+  "version": "0.20.117",
   "type": "module",
   "description": "AgInTiFlow is a project-aware agent workspace for hybrid wet-dry R&D, hardware-aware intelligence, software automation, and industrial workflows.",
   "license": "Apache-2.0",
@@ -56,11 +56,13 @@
     "scripts/smoke-canvas-artifacts.js",
     "scripts/smoke-cli-chat.js",
     "scripts/smoke-coding-tools.js",
+    "scripts/smoke-dynamic-step-budget.js",
     "scripts/smoke-capabilities.js",
     "scripts/smoke-auto-update.js",
     "scripts/smoke-inbox.js",
     "scripts/smoke-model-roles.js",
     "scripts/smoke-platform.js",
+    "scripts/smoke-perception-research.js",
     "scripts/smoke-permission-modes.js",
     "scripts/smoke-skills.js",
     "scripts/smoke-skillmesh.js",
@@ -82,6 +84,7 @@
     "check": "node --check run.js && node --check web.js && node --check bin/aginti-cli.js && node --check src/*.js && node --check scripts/seed-supervised-homework.js",
     "setup:toolchain-docker": "scripts/setup-agent-toolchain-docker.sh",
     "smoke:coding-tools": "node scripts/smoke-coding-tools.js",
+    "smoke:dynamic-step-budget": "node scripts/smoke-dynamic-step-budget.js",
     "smoke:aaps-adapter": "node scripts/smoke-aaps-adapter.js",
     "smoke:auxiliary-tools": "node scripts/smoke-auxiliary-tools.js",
     "smoke:auth": "node scripts/smoke-auth.js",
@@ -93,6 +96,7 @@
     "smoke:inbox": "node scripts/smoke-inbox.js",
     "smoke:model-roles": "node scripts/smoke-model-roles.js",
     "smoke:platform": "node scripts/smoke-platform.js",
+    "smoke:perception-research": "node scripts/smoke-perception-research.js",
     "smoke:permission-modes": "node scripts/smoke-permission-modes.js",
     "smoke:tmux-tools": "node scripts/smoke-tmux-tools.js",
     "smoke:web-api": "node scripts/smoke-web-api.js",
@@ -100,7 +104,7 @@
     "real:deepseek": "node scripts/real-deepseek-capabilities.js",
     "supervision:seed": "node scripts/seed-supervised-homework.js",
     "storage:migrate": "node bin/aginti-cli.js storage migrate",
-    "test": "npm run check && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:coding-tools && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:auth && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:tmux-tools && npm run smoke:cli-chat && npm run smoke:inbox",
+    "test": "npm run check && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:auth && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:tmux-tools && npm run smoke:cli-chat && npm run smoke:inbox",
     "pack:dry-run": "npm pack --dry-run",
     "smoke:capabilities": "node scripts/smoke-capabilities.js"
   },

package/references/dynamic-step-budget-and-scs-auto.md

@@ -0,0 +1,241 @@
+# Dynamic Step Budget And SCS Auto Routing
+
+This note documents the implemented design for dynamic `maxSteps` extension and SCS auto routing.
+
+## Current State
+
+AgInTiFlow treats `maxSteps` as the initial run budget for real-provider work. The runtime can extend that budget near the boundary when recent evidence shows concrete progress.
+
+Relevant paths:
+
+- `src/cli.js`: parses `--max-steps`, `--dynamic-steps`, and budget tuning flags.
+- `src/config.js`: resolves `config.maxSteps`, `config.dynamicSteps`, and extension caps.
+- `src/engineering-guidance.js`: recommends profile-aware initial step budgets.
+- `src/agent-runner.js`: uses a mutable budget loop and emits `budget.*` events.
+- `src/step-budget-controller.js`: owns deterministic progress/blocker checks, caps, serialization, and extension application.
+- `src/scs-controller.js`: supports `off`, `on`, `auto`, and the SCS student step-budget gate.
+
+SCS auto is supported:
+
+- CLI: `--scs auto`.
+- Interactive: `/scs auto`.
+- Config: `enableScs: "auto"`.
+- Router policy: `shouldActivateScs("auto", { goal, taskProfile, complexityScore })`.
+- Active model policy: when SCS is active, committee/student/supervisor use the main model.
+
+## Goal
+
+Avoid both failure modes:
+
+- Stopping at `maxSteps` while the agent is making good, verifiable progress.
+- Letting a stuck or drifting agent run forever.
+
+The design is not unlimited steps. It is a bounded step-extension application reviewed by a monitor.
+
+## Implemented Concept
+
+At a budget boundary, the runtime asks:
+
+```text
+Should this run receive more steps?
+```
+
+The monitor can approve an extension only when:
+
+- the run is near the current budget limit;
+- recent steps show concrete tool, file, or artifact progress;
+- the requested extra steps fit under a hard cap;
+- no repeated failure loop is active;
+- no permission, install, secret, host, or destructive-action blocker is being bypassed.
+
+## Modes
+
+### Normal Mode
+
+Normal mode uses a deterministic runtime budget gate.
+
+It is deliberately cheap:
+
+- no extra model call;
+- no free-form debate;
+- one extension by default;
+- extension size is normally `+6` to `+12`;
+- hard cap is normally about `2x` the initial budget.
+
+### SCS On Mode
+
+When `/scs on` is active, the deterministic runtime gate first checks that progress exists and no blocker loop is active. Then the SCS student budget gate can emit:
+
+```json
+{
+  "role": "student",
+  "decision": "extend_steps | deny_extension | rethink_plan",
+  "confidence": 0.82,
+  "extra_steps": 8,
+  "evidence": ["file changed", "artifact exists"],
+  "reason": "Progress is concrete; one focused verification pass remains.",
+  "next_required_action": "supervisor_continue"
+}
+```
+
+SCS mode allows a slightly larger budget because the student gate is stricter:
+
+- up to two extensions by default;
+- extension size is normally `+8` to `+16`;
+- hard cap is normally about `2.5x` the initial budget.
+
+### SCS Auto Mode
+
+`/scs auto` means the router may activate SCS for a specific turn. Signals include:
+
+- high smart-routing complexity score;
+- high-friction profiles such as Android, app, code, large-codebase, GitHub, maintenance, QA, research, review, security, supervision, or website;
+- prompt language such as debug, failing, migration, emulator, deploy, PDF, refactor, monitor, or long-running.
+
+If SCS auto activates, dynamic step extension uses the SCS student gate. If SCS auto does not activate, dynamic step extension uses the normal deterministic gate.
+
+## Extension Evidence
+
+The deterministic gate reads compact evidence only:
+
+- user goal and current plan;
+- initial and current step budgets;
+- recent tool results;
+- recent `tool.completed`, `file.changed`, and artifact events;
+- repeated blocked/failed tool evidence;
+- persisted budget state.
+
+It does not include secrets. Tool and event payloads are redacted before persistence.
+
+## Decision Criteria
+
+Approve extension when:
+
+- files or artifacts were created and need verification;
+- a command/check produced useful output;
+- a patch or workflow is mid-flight and the next step is bounded;
+- the task is close to completion and one focused pass remains.
+
+Deny extension when:
+
+- the same command or tool failed repeatedly;
+- a permission blocker requires user approval;
+- host install, destructive action, publish, or outside-workspace access is blocked;
+- no recent concrete progress exists;
+- the hard cap or extension count is reached.
+
+Request rethink in SCS when:
+
+- progress exists but the current plan is stale;
+- a failure class changed;
+- the next phase must be smaller or safer.
+
+## Runtime Events
+
+Implemented compact events:
+
+- `budget.initialized`
+- `budget.near_limit`
+- `budget.extension_requested`
+- `budget.extension_approved`
+- `budget.extension_denied`
+- `scs.student.extend_steps`
+- `scs.student.deny_extension`
+- `scs.student.rethink_plan`
+
+Typical event payload:
+
+```json
+{
+  "initialMaxSteps": 24,
+  "currentMaxSteps": 32,
+  "stepsCompleted": 23,
+  "extraSteps": 8,
+  "approvedExtraSteps": 8,
+  "extensionsUsed": 1,
+  "hardCap": 60,
+  "reason": "Recent verified tool progress exists."
+}
+```
+
+## User-Facing Output
+
+Normal mode:
+
+```text
+budget: monitor approved +8 steps (23/32); Recent verified tool progress exists
+```
+
+Denied:
+
+```text
+budget: extension denied; Recent blocker requires a different permission/setup path
+```
+
+SCS:
+
+```text
+SCS: student approved +8 steps (23/32); one focused verification pass remains
+```
+
+## Config
+
+CLI:
+
+```bash
+aginti --max-steps 24 --dynamic-steps auto "..."
+aginti --dynamic-steps off "..."
+aginti --dynamic-steps on --provider mock "..."
+aginti --dynamic-step-limit 2 "..."
+aginti --dynamic-step-size 10 "..."
+aginti --dynamic-step-hard-cap 72 "..."
+aginti --scs auto "..."
+```
+
+Environment:
+
+```text
+AGINTI_DYNAMIC_STEPS=off|auto|on
+AGINTI_STEP_EXTENSION_LIMIT=2
+AGINTI_STEP_EXTENSION_SIZE=10
+AGINTI_STEP_EXTENSION_HARD_CAP=72
+```
+
+Defaults:
+
+- `dynamicSteps=auto`.
+- Real-provider runs can auto-extend when evidence justifies it.
+- Mock runs do not auto-extend unless explicitly run with `--dynamic-steps on`.
+
+## Interaction With `/scs auto`
+
+Routing semantics:
+
+- `/scs off`: never use SCS; dynamic budget uses normal deterministic monitoring if enabled.
+- `/scs on`: always use SCS; dynamic budget uses the student budget gate.
+- `/scs auto`: router decides per run; if activated, dynamic budget uses the student gate.
+
+For observability, state preserves:
+
+- configured mode: `enableScs = "auto"`;
+- actual run activation: `scsActive = true|false`;
+- budget state: `state.meta.stepBudget`.
+
+## Guardrail
+
+A step extension is not permission escalation.
+
+If the run lacks permission to write outside the project, install host packages, publish, use credentials, read secrets, or run destructive commands, more steps should not help. The monitor denies extension and the normal permission advice/rerun path remains authoritative.
+
+## Regression Coverage
+
+`scripts/smoke-dynamic-step-budget.js` checks:
+
+- dynamic mode normalization;
+- `/scs auto` activation for complex prompts and non-activation for trivial prompts;
+- deterministic approval when recent file/tool progress exists;
+- denial for repeated permission/blocker loops;
+- mock-provider auto disablement;
+- a real runner smoke where a one-step mock run creates a file, earns a bounded extension, finishes, and persists `budget.extension_approved`.
+
+This keeps AgInTiFlow persistent without making it unbounded.

package/references/model-routing-provider-design.md

@@ -24,6 +24,15 @@ The UI should be role-first rather than provider-first:
 - **Wrapper (`/wrapper`):** external coding assistant. Default Codex with `gpt-5.5` medium reasoning, disabled unless wrapper tools are enabled.
 - **Auxiliary (`/auxiliary`):** media/image tools. Default `grsai/nano-banana-2`; Venice image models are optional.
 
+Writing has a separate tool boundary rather than a separate always-on agent identity:
+
+- **`writing_specialist`:** isolated prose/argument/scene drafting. It receives only writing brief, canon, style guide, prior draft, target, audience, constraints, length, and downstream format intent.
+- **Main agent:** owns project state, files, formatting, shell/browser/tool policy, citations, LaTeX/PDF compilation, canvas artifacts, and final verification.
+
+This protects writing quality from agent-side context overload. The writer should not be told about shell tools, file tools, routing policy, guardrails, Docker, or browser state unless the user explicitly needs those details inside the text itself.
+
+The specialist can follow the main provider/model, or be routed separately with `AGINTI_WRITING_PROVIDER` and `AGINTI_WRITING_MODEL`.
+
 This keeps the mental model stable: providers are supply, roles are policy.
 
 ## Current Commands