@lazyingart/agintiflow 0.20.200 → 0.20.202

package/.env.example

@@ -6,6 +6,7 @@ LOCALLLM_BASE_URL=http://127.0.0.1:8008/v1
 LOCALLLM_API_KEY=local-dev-key
 AGINTI_LOCALLLM_ROUTE_MODEL=localllm-fast
 AGINTI_LOCALLLM_MAIN_MODEL=localllm-deep
+AGINTI_LOCALLLM_CODE_MODEL=localllm-code
 AGINTI_LOCALLLM_MAX_MODEL=localllm-max
 AGINTI_LOCALLLM_ALLOW_AUTO_MAX=false
 AGINTI_LOCALLLM_VISION_MODEL=localllm-vision-xl
@@ -13,8 +14,10 @@ AGINTI_LOCALLLM_CONTEXT_TOKENS=32768
 AGINTI_LOCALLLM_MAX_OUTPUT_TOKENS=8192
 AGINTI_LOCALLLM_TOOL_SCHEMA_TOKENS=4096
 
-# Auto-Max is off unless explicitly enabled. Enabled runs still require authenticated
-# alias discovery plus a fresh RAM/swap/GPU headroom check before selecting Max.
+# Genuine implementation work uses the code alias only after authenticated model
+# discovery confirms that exact configured alias; otherwise it remains on Deep.
+# Auto-Max is off unless explicitly enabled. Enabled non-code runs still require
+# authenticated alias discovery plus a fresh RAM/swap/GPU headroom check.
 # Hosted provider keys below never act as a LocalLLM failure fallback.
 
 # Optional explicit hosted upgrades. They are never automatic fallbacks.
@@ -22,6 +25,8 @@ DEEPSEEK_API_KEY=
 OPENAI_API_KEY=
 AGINTI_ALLOW_HOSTED_IMAGE_PERCEPTION=false
 AGINTI_ALLOW_HOSTED_WEB_RESEARCH=false
+AGINTI_WEB_SEARCH_PROVIDER=auto
+# BRAVE_SEARCH_API_KEY=only_when_AGINTI_WEB_SEARCH_PROVIDER_is_brave
 AGINTI_ALLOW_HOSTED_JSON_SPECIALIST=false
 # A cross-provider writer needs both an explicit target and the permission below.
 AGINTI_WRITING_PROVIDER=

package/README.md

@@ -54,7 +54,7 @@ Most agent tools are either a chat box with hidden state or an expensive one-mod
 | 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. LocalLLM supplies the default fast/deep lanes; DeepSeek, OpenAI, OpenRouter, Qwen, and Venice are optional explicit routes. |
 | Writing without agent noise | `writing_specialist` drafts novels, books, scripts, essays, and paper prose in an isolated writing-only context on the active provider. Cross-provider writing requires explicit permission; ambient keys and model arguments cannot silently switch a LocalLLM session to a hosted model. The main agent then handles files, formatting, citations, checks, and artifacts. |
-| Visual and web evidence | `read_image` uses the loopback LocalLLM vision model in local sessions and never falls through to a hosted provider. `web_research` saves sourced snippet artifacts for local synthesis. OpenAI perception/research and wrapper second opinions require explicit provider/tool permission. |
+| Visual and web evidence | `read_image` keeps local pixels local. Fast search has provider fallback; exact page reads preserve hashes and metadata; `deep_research` adds resumable planning, parallel retrieval, exact-quote evidence, gap filling, synthesis, and citation auditing on the active provider. |
 | Scouts before big work | Parallel scouts can cheaply map architecture, tests, risks, symbols, and integration points before the main executor edits anything. |
 | SCS by default | Student-Committee-Supervisor mode adds a typed gate: committee drafts, student approves/monitors, supervisor executes. Use `/scs off` or `--no-scs` only when speed matters more than validation. |
 | 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. |
@@ -85,7 +85,7 @@ aginti init --template aaps
 aginti init --template supervision
 ```
 
-By default, AgInTiFlow connects to the sibling LocalLLM gateway at `http://127.0.0.1:8008/v1`, using `localllm-fast` for routing and the installed 30B-A3B Q4 `localllm-deep` for substantive coding and agent work. The Q8 `localllm-max` remains resource-gated on every new or resumed run (24 GiB available RAM, no more than 75% swap use, and 40 GiB aggregate free NVIDIA memory). The automatic Vision policy requires both a trusted image-input signal and confirmed model capability; the shipped CLI/web currently use the readiness-checked local `read_image` tool or an explicit `localllm-vision-xl` selection rather than inferring vision from prompt keywords. Routing does not load a model. Startup checks the LocalLLM service, its Ollama runtime, selected aliases, and any required Max headroom before inference. A local failure stops with an actionable error; it never silently sends the task to a hosted provider.
+By default, AgInTiFlow connects to the sibling LocalLLM gateway at `http://127.0.0.1:8008/v1`, using `localllm-fast` for routing and the installed 30B-A3B Q4 `localllm-deep` for substantive general agent work. High-confidence coding and repository implementation requests begin on Deep, then switch to the provider-neutral `localllm-code` capability alias only after bearer-authenticated `/v1/models` discovery confirms that exact configured alias. If it is absent, the run stays on Deep; writing, research, documentation, design, explanation-only code questions, explicit providers, and manual model choices are not silently rerouted. Set `AGINTI_LOCALLLM_CODE_MODEL` to another LocalLLM capability alias without coupling AgInTiFlow to an engine tag. The Q8 `localllm-max` remains resource-gated on every new or resumed run (24 GiB available RAM, no more than 75% swap use, and 40 GiB aggregate free NVIDIA memory). The automatic Vision policy requires both a trusted image-input signal and confirmed model capability; the shipped CLI/web currently use the readiness-checked local `read_image` tool or an explicit `localllm-vision-xl` selection rather than inferring vision from prompt keywords. Routing does not load a model. Startup checks the LocalLLM service, its Ollama runtime, selected aliases, and any required Max headroom before inference. A local failure stops with an actionable error; it never silently sends the task to a hosted provider.
 
 Hosted providers are optional, explicit upgrades. When you select DeepSeek, OpenAI, OpenRouter, Qwen, or Venice, the auth wizard can save that provider's key account-wide in `~/.agintiflow/.env` with restricted permissions. Current project `.aginti/.env` files can still override account defaults when needed. You can rerun setup any time:
 
@@ -174,6 +174,7 @@ aginti --language de
 | Generate images | `/auxiliary image`, then ask for an image |
 | Read screenshots/images | `/image-read path/to/screenshot.png "what changed?"` |
 | Research with sources | `/web-research latest Android Gradle plugin official docs` |
+| Run deep research | `/deep-research standard compare current research-agent citation methods` |
 | 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` |
@@ -252,11 +253,11 @@ The website keeps the visual walkthrough in a carousel so this README can stay f
 | 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 | LocalLLM Fast/Deep defaults, explicit and resource-gated Max, image-capability-gated Vision XL, explicit DeepSeek/OpenAI/OpenRouter/Qwen/Venice/mock routes, and optional spare/wrapper/auxiliary models. |
+| Model routing | LocalLLM Fast/Deep defaults, authenticated implementation-only Code capability, explicit and resource-gated Max, image-capability-gated Vision XL, explicit DeepSeek/OpenAI/OpenRouter/Qwen/Venice/mock routes, and optional spare/wrapper/auxiliary 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 | LocalLLM sessions send pixels only to the loopback vision endpoint. `web_research` preserves source lists for the active model to synthesize. Hosted OpenAI and wrapper paths are explicit opt-ins, never credential-driven fallbacks. |
+| Image reading and web research | LocalLLM sessions keep pixels on the loopback vision endpoint. `web_search`, `read_web_page`, and `deep_research` provide fast discovery, exact source extraction, resumable evidence gathering, and claim-level citation audits. Hosted paths remain explicit opt-ins. |
 | SCS mode | Default Student-Committee-Supervisor quality gate with independent planning, execution, and validation roles. |
 | AAPS adapter | Optional `@lazyingart/aaps` integration for `.aaps` workflow init, validate, parse, compile, dry-run, and run commands. |
 | AgentLink | Local-first collaboration between AgInTi sessions through boards, typed messages, action contracts, safe summaries, and evidence bundles. |
@@ -274,6 +275,7 @@ AgInTiFlow does not treat "the model" as one global setting. It has roles:
 | --- | --- | --- |
 | Route | `localllm/localllm-fast` | Local planner, triage, short tasks, and routing decisions. |
 | Main | `localllm/localllm-deep` | Local complex executor for coding, debugging, writing, research, and long tasks. |
+| Code capability | `localllm/localllm-code` | Smart implementation-only upgrade after authenticated alias discovery; unavailable aliases fall back to Deep. |
 | Spare | `localllm/localllm-deep` medium | Local cross-check lane; a hosted spare requires explicit selection. |
 | 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` (off) | Explicitly enabled image generation and other non-text helper tools; no credential-driven provider failover. |
@@ -371,6 +373,7 @@ LOCALLLM_BASE_URL=http://127.0.0.1:8008/v1
 LOCALLLM_API_KEY=local-dev-key
 AGINTI_LOCALLLM_ROUTE_MODEL=localllm-fast
 AGINTI_LOCALLLM_MAIN_MODEL=localllm-deep
+AGINTI_LOCALLLM_CODE_MODEL=localllm-code
 
 # Optional explicit hosted upgrades; never automatic LocalLLM fallbacks.
 DEEPSEEK_API_KEY=...
@@ -404,6 +407,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/deep-research-engine.md](docs/deep-research-engine.md)
 - [docs/cli-i18n.md](docs/cli-i18n.md)
 - [docs/skillmesh.md](docs/skillmesh.md)
 
@@ -420,6 +424,7 @@ More detail:
 | 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) |
+| Deep research engine | [docs/deep-research-engine.md](docs/deep-research-engine.md) |
 | Server-owned text-only fallback | [docs/safe-chat.md](docs/safe-chat.md) |
 | Skill Mesh | [docs/skillmesh.md](docs/skillmesh.md) |
 | Housekeeping logs | [docs/housekeeping.md](docs/housekeeping.md) |

package/docs/deep-research-engine.md

@@ -0,0 +1,172 @@
+# Deep Research Engine
+
+AgInTiFlow has two deliberately different research paths:
+
+- `web_search` is a fast lookup tool.
+- `deep_research` is a bounded, resumable evidence workflow for questions that
+  need multiple sources, disagreement analysis, or a durable report.
+
+Simple questions should stay on the fast path. A deep-research run spends more
+queries and model calls only when breadth, verification, and traceability add
+real value.
+
+## Architecture
+
+The implementation follows the strongest production patterns without making
+every query an unbounded agent swarm:
+
+1. **Plan**: the active provider decomposes the question into non-overlapping
+   subquestions, search queries, preferred source types, and exclusions.
+2. **Search**: queries run with bounded concurrency. The no-key default falls
+   back from DuckDuckGo HTML to Bing RSS. An explicitly configured Brave Search
+   route is optional. Multi-domain corpora receive separate bounded `site:`
+   queries matched to entity-specific subquestions instead of one fragile OR
+   expression.
+3. **Rank, diversify, and deduplicate**: canonical URLs remove tracking state;
+   primary, official, scholarly, and high-relevance results rank ahead of
+   summaries, while a bounded diversity penalty prevents one domain from
+   crowding every selected source.
+4. **Read exact sources**: `read_web_page` validates every redirect before the
+   next request, rejects private DNS resolutions, streams bounded bytes, strips
+   scripts/navigation, extracts article/main text and metadata, records hashes,
+   and marks all retrieved text as untrusted evidence.
+5. **Extract evidence**: isolated structured-output calls identify relevant
+   subquestions, claims, exact quotations, confidence, and limitations.
+6. **Verify**: deterministic code checks that quoted passages occur in the
+   exact retrieved source. Unverified quotations do not enter synthesis.
+7. **Fill gaps**: standard/deep runs may issue one bounded follow-up pass for
+   uncovered subquestions when query and source budgets remain.
+8. **Synthesize**: the active provider receives verified evidence rather than
+   arbitrary page text. Every substantive paragraph and finding carries source
+   IDs.
+9. **Audit**: deterministic code removes invented source IDs and unsupported
+   synthesis statements whose cited sources produced no verified evidence,
+   then reports claim, quotation, citation, question, domain, and
+   primary-source coverage.
+10. **Persist**: every stage checkpoints one JSON state file. The final cited
+    Markdown report is saved beside it and sent to the canvas.
+
+This combines the orchestrator/worker and separate citation-pass lessons
+described by [Anthropic's production research
+system](https://www.anthropic.com/engineering/multi-agent-research-system)
+with the iterative plan/search/read/gap/synthesize and background-resume model
+documented for [Gemini Deep
+Research](https://ai.google.dev/gemini-api/docs/deep-research). AgInTiFlow keeps
+the fan-out explicitly bounded and stays on the active DeepSeek, LocalLLM, or
+other selected provider.
+
+## Research Budgets
+
+| Depth | Queries | Sources | Gap passes | Intended use |
+| --- | ---: | ---: | ---: | --- |
+| `quick` | 3 | 6 | 0 | Small comparison or source check |
+| `standard` | 6 | 12 | 1 | Normal multi-source research |
+| `deep` | 10 | 20 | 1 | Broad review, contested topic, or decision report |
+
+The caller may reduce these budgets, but hard caps remain 12 queries and 24
+sources. Search/page concurrency is bounded to six and defaults to three or
+four.
+
+## Usage
+
+Interactive:
+
+```text
+/deep-research standard Compare current primary-source approaches to citation verification in research agents
+/deep-research deep Review recent optical biosensing methods, emphasizing original papers and unresolved limitations
+```
+
+An agent can call:
+
+```json
+{
+  "query": "What evidence supports the current design choices?",
+  "depth": "standard",
+  "sourcePolicy": "primary",
+  "domains": ["docs.example.org", "arxiv.org"]
+}
+```
+
+To resume a partial or completed same-query run, pass the returned
+`researchId`. A completed same-day run is returned from its checkpoint unless
+`refresh=true` is explicit. A transient run that retrieved zero allowed sources
+is marked failed, preserves its attempts, and retries retrieval on resume
+instead of caching an empty report as success. Checkpoint schema changes
+invalidate old cached runs automatically.
+
+## Artifacts
+
+Each session stores:
+
+```text
+artifacts/deep-research-RESEARCH_ID.json
+artifacts/deep-research-RESEARCH_ID.md
+```
+
+The JSON includes:
+
+- objective, plan, query/source budgets, and source policy;
+- every search attempt and provider failure/fallback;
+- canonical source URLs, metadata, retrieval timestamps, and SHA-256 hashes;
+- readable source text and ranked passages;
+- extracted claims, exact quotations, limitations, and question mappings;
+- missing questions, source diversity, and quote-verification rates;
+- final synthesis and citation audit;
+- stage/status fields used for crash-safe resume.
+
+## Search Providers
+
+The default `auto` policy uses public no-key providers:
+
+```text
+DuckDuckGo HTML -> Bing RSS
+```
+
+For an explicitly configured Brave Search account:
+
+```bash
+export AGINTI_WEB_SEARCH_PROVIDER=brave
+export BRAVE_SEARCH_API_KEY=...
+```
+
+An ambient key does not select Brave. The provider must be selected explicitly
+through configuration or a tool argument.
+
+## Safety And Evidence Rules
+
+- Only public HTTP/HTTPS URLs are accepted. Embedded credentials, single-label
+  internal hosts, loopback, RFC1918, link-local, multicast, `.local`, private
+  DNS resolutions, and redirected private targets are rejected before fetch.
+- Domain allowlists and blocklists apply to search results, direct reads, and
+  redirect targets.
+- Tracking parameters and fragments are removed before deduplication.
+- Page bytes are bounded while streaming; extracted characters are bounded too.
+- HTML scripts, forms, navigation, footers, and similar noise are removed.
+- Retrieved text is always labeled untrusted and never treated as tool or agent
+  instructions.
+- PDFs are hash-verified but not misrepresented as parsed by the dependency-free
+  page reader. A document/PDF tool remains responsible for full PDF extraction.
+- Synthesis sees only verified evidence records. Unknown citation IDs and
+  citations to sources without verified evidence are removed and reported.
+- Provider selection remains explicit. Deep research uses the active provider;
+  it does not silently escape LocalLLM or DeepSeek because another API key is
+  present.
+
+## Quality Signals
+
+The report audit exposes evidence quality rather than hiding it behind fluent
+prose:
+
+- question coverage;
+- readable source count;
+- primary/scholarly source count;
+- independent-domain count;
+- exact-quote verification rate;
+- statement-level citation coverage;
+- unknown/invented citation IDs;
+- unsupported synthesis statements removed before report rendering;
+- contradictions, uncertainties, and unresolved questions.
+
+These metrics are diagnostic gates, not a guarantee that a source is correct.
+High-stakes work still requires domain review and, where appropriate, direct
+inspection of the underlying paper, standard, dataset, or official record.

package/docs/local-first-agent-runtime.md

@@ -30,6 +30,7 @@ health:          http://127.0.0.1:8008/healthz
 models:          authenticated GET /v1/models
 route lane:      localllm-fast
 main lane:       localllm-deep
+coding lane:     localllm-code (authenticated, implementation-only capability upgrade)
 maximum lane:    localllm-max
 vision:          localllm-vision-xl
 embedding:       localllm-embed (sibling-service alias; not an AgInTi text-routing tier)
@@ -39,7 +40,7 @@ The default bearer value used by the local deployment is an interoperability pla
 
 Readiness requires both `health.ok === true` and `health.ollama.ok === true`, followed by an authenticated `/v1/models` check that confirms the requested alias exists. Health alone is not sufficient.
 
-The installed local ladder is capability- and resource-aware. `localllm-fast` handles short routing and bounded work; substantive coding and agent tasks use the 30B-A3B Q4 `localllm-deep` lane. The 30B-A3B Q8 `localllm-max` lane remains explicitly selectable, but every new or resumed Max run performs a fresh pre-inference gate after authenticated alias discovery. It requires at least 24 GiB available host RAM, swap use no higher than 75%, and 40 GiB aggregate free NVIDIA memory (Q8 weights plus working reserve). Missing GPU telemetry fails closed. Automatic Max is off by default and requires `AGINTI_LOCALLLM_ALLOW_AUTO_MAX=true`; an eligible run confirms the configured Max alias and fresh headroom before upgrading the actual model client from Deep. If the optional upgrade cannot be proven safe, it continues on Deep rather than failing. The automatic Vision policy requires both a trusted image-input signal and confirmed model capability. The shipped CLI/web currently reach vision through the local `read_image` tool or explicit `localllm-vision-xl` selection; both paths readiness-check the selected alias, and prompt keywords alone never activate Vision XL.
+The installed local ladder is capability- and resource-aware. `localllm-fast` handles short routing and bounded work; substantive general agent tasks use the 30B-A3B Q4 `localllm-deep` lane. High-confidence implementation work begins on Deep and may upgrade to the independently configured `AGINTI_LOCALLLM_CODE_MODEL` alias only when the same bearer-authenticated `/v1/models` response reports it. Missing or unverified availability stays on Deep, never a hosted provider. The implementation classifier excludes writing, research, paper, book, novel, design, documentation, slides, education, and image profiles, and requires an implementation action rather than a bare code mention or explanation request. The effective selection and a secret-free candidate policy are durable: selected coding sessions resume exactly, while a Deep fallback may re-evaluate authenticated availability on a later resume. Manual models and explicit providers remain exact. The 30B-A3B Q8 `localllm-max` lane remains explicitly selectable, but every new or resumed Max run performs a fresh pre-inference gate after authenticated alias discovery. It requires at least 24 GiB available host RAM, swap use no higher than 75%, and 40 GiB aggregate free NVIDIA memory (Q8 weights plus working reserve). Missing GPU telemetry fails closed. Automatic Max is off by default and requires `AGINTI_LOCALLLM_ALLOW_AUTO_MAX=true`; an eligible non-code run confirms the configured Max alias and fresh headroom before upgrading the actual model client from Deep. If the optional upgrade cannot be proven safe, it continues on Deep rather than failing. The automatic Vision policy requires both a trusted image-input signal and confirmed model capability. The shipped CLI/web currently reach vision through the local `read_image` tool or explicit `localllm-vision-xl` selection; both paths readiness-check the selected alias, and prompt keywords alone never activate Vision XL.
 
 ## Provider-neutral capabilities
 
@@ -171,6 +172,7 @@ Offline deterministic tests run on every change:
 - timeout before output, cancellation, and no post-cancel dispatch;
 - context calculation includes tool schemas and output reserve;
 - no silent hosted fallback;
+- implementation-only coding alias selection requires authenticated exact availability, with Deep fallback and durable resume behavior;
 - session resume preserves provider, model, capability profile, and executed-tool ledger.
 
 Live compatibility tests are opt-in because they load local models:
@@ -180,6 +182,7 @@ Live compatibility tests are opt-in because they load local models:
 | `localllm-pocket` / 4B (direct sibling-service compatibility alias, not an automatic AgInTi tier) | direct answer, one-tool selection, malformed-output recovery, truthful blocker |
 | `localllm-fast` / 8B | focused code inspection/edit/test loop, cancellation, resumed turn |
 | `localllm-deep` / 30B-A3B Q4 | multi-step plan, repair after failed tool evidence, long-context compaction |
+| `localllm-code` / configured coding capability | repository implementation/tool loop, exact-alias readiness, Deep fallback, resumed selection |
 | `localllm-max` / 30B-A3B Q8 | explicit opt-in, resource preflight, highest-fidelity local code task |
 | `localllm-vision-xl` / 30B-A3B Q4 | attached-image understanding with no keyword-only activation |
 | DeepSeek/OpenAI | same fixtures, plus explicit escalation and stronger-model quality comparison |

package/docs/model-selection.md

@@ -20,10 +20,11 @@ The local tier policy uses the workstation's installed aliases without treating
 | --- | --- | --- |
 | `localllm-fast` | Qwen3 8B Q4 routing and bounded work | Default for simple work. |
 | `localllm-deep` | Qwen3 30B-A3B Q4 substantive coding/agent work | Default for complex work. |
+| `localllm-code` | Provider-neutral coding capability (the sibling catalog currently maps it to Qwen3-Coder 30B-A3B Q4) | Smart selection only for high-confidence implementation work and only after authenticated availability; otherwise Deep. |
 | `localllm-max` | Qwen3 30B-A3B Q8 highest-fidelity local text/code | Explicit selection; automatic use additionally requires opt-in, authenticated availability, fresh resource readiness, and no shared-workstation pressure. |
 | `localllm-vision-xl` | Qwen3-VL 30B-A3B Q4 image understanding | The automatic policy requires a trusted image-input signal plus confirmed capability. The shipped CLI/web currently use readiness-checked `read_image` or explicit selection; prompt keywords alone do not activate it. |
 
-Installed aliases are not loaded during routing. Automatic Max is off by default; set `AGINTI_LOCALLLM_ALLOW_AUTO_MAX=true` to opt in. An opted-in high-complexity run starts on Deep, confirms the Max alias through authenticated `/v1/models`, and only then samples current resources. Unknown or pressured resource state stays on Deep. Explicit Max also cannot bypass the live gate: immediately before client creation, each new or resumed run rechecks at least 24 GiB available RAM, swap use at or below 75%, and 40 GiB aggregate free NVIDIA memory. A blocked explicit gate creates no model client and performs no inference.
+Installed aliases are not loaded during routing. A genuine coding/implementation request starts on Deep, checks the authenticated model inventory, and selects the exact `AGINTI_LOCALLLM_CODE_MODEL` value only when present. Missing or unverified capability stays on Deep; the decision and effective model are recorded so fallback sessions can re-evaluate and selected sessions resume on the same model. Explanation-only code questions and non-code writing/research/documentation/design keep their existing route. Automatic Max is off by default; set `AGINTI_LOCALLLM_ALLOW_AUTO_MAX=true` to opt in. An opted-in high-complexity non-code run starts on Deep, confirms the Max alias through authenticated `/v1/models`, and only then samples current resources. Unknown or pressured resource state stays on Deep. Explicit Max also cannot bypass the live gate: immediately before client creation, each new or resumed run rechecks at least 24 GiB available RAM, swap use at or below 75%, and 40 GiB aggregate free NVIDIA memory. A blocked explicit gate creates no model client and performs no inference.
 
 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. It follows the active LocalLLM provider by default even when hosted keys exist. Cross-provider writing requires both an explicit target (`AGINTI_WRITING_PROVIDER` or a per-run provider override) and `AGINTI_ALLOW_HOSTED_WRITING_SPECIALIST=true` (or the equivalent per-run permission flag); language detection and ambient credentials never grant that permission.
 
@@ -75,7 +76,7 @@ Provider families:
 
 | Family | Models |
 | --- | --- |
-| LocalLLM | `localllm-fast`, `localllm-deep`, `localllm-max`, `localllm-vision-xl`; Max and Vision retain the gates above |
+| LocalLLM | `localllm-fast`, `localllm-deep`, `localllm-code`, `localllm-max`, `localllm-vision-xl`; Code, Max, and Vision retain the gates above |
 | DeepSeek | `deepseek-v4-flash`, `deepseek-v4-pro` |
 | Venice | `venice-uncensored-1-2`, `venice-uncensored`, `gemma-4-uncensored` |
 | OpenAI | `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-5.3-codex-spark`, `gpt-5.2`; each has low/medium/high/xhigh reasoning |
@@ -148,7 +149,7 @@ It keeps smart routing enabled. If the Venice key is missing, run `/auth venice`
 
 ## Keys
 
-The LocalLLM baseline uses `http://127.0.0.1:8008/v1` and the installation's loopback key (`local-dev-key` in the documented local setup). `AGINTI_LOCALLLM_MODEL` or `LOCALLLM_MODEL` is the shared local text override; role-specific `AGINTI_LOCALLLM_ROUTE_MODEL` and `AGINTI_LOCALLLM_MAIN_MODEL` take precedence. Optional `AGINTI_LOCALLLM_MAX_MODEL` and `AGINTI_LOCALLLM_VISION_MODEL` name the gated heavyweight aliases. LocalLLM overrides must remain loopback URLs. Generic `LLM_*` values do not redefine the local provider.
+The LocalLLM baseline uses `http://127.0.0.1:8008/v1` and the installation's loopback key (`local-dev-key` in the documented local setup). `AGINTI_LOCALLLM_MODEL` or `LOCALLLM_MODEL` is the shared local text override; role-specific `AGINTI_LOCALLLM_ROUTE_MODEL` and `AGINTI_LOCALLLM_MAIN_MODEL` take precedence. `AGINTI_LOCALLLM_CODE_MODEL` names the independently configurable coding capability alias; AgInTiFlow never needs the underlying engine tag. Optional `AGINTI_LOCALLLM_MAX_MODEL` and `AGINTI_LOCALLLM_VISION_MODEL` name the other gated heavyweight aliases. LocalLLM overrides must remain loopback URLs. Generic `LLM_*` values do not redefine the local provider.
 
 Keys are saved account-wide in `~/.agintiflow/.env` by default. Use `--project` only when the current project needs an override in ignored `.aginti/.env`:
 

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

@@ -8,7 +8,9 @@ AgInTiFlow separates visual understanding, web search, and wrapper advice so eac
 | --- | --- | --- |
 | `read_image` | Read workspace screenshots, plots, scanned text, diagrams, or allowed remote image URLs. | Saves JSON and Markdown reports under `artifacts/perception/`, records image hashes, and sends the Markdown report to the canvas when used by an agent run. |
 | `web_search` | Cheap raw search snippets. | Returns compact titles, URLs, snippets, and fallback search URL. |
+| `read_web_page` | Read one exact public source instead of relying on a snippet. | Returns bounded article text, metadata, canonical URL, relevant passages, retrieval time, and content hash. |
 | `web_research` | Sourced research unit for current or external information. | Saves `artifacts/research/*-web-research.json` with query, mode, source list, and answer. |
+| `deep_research` | Plan, retrieve, verify, synthesize, and audit a genuinely multi-source question. | Saves resumable JSON state and a cited Markdown report with coverage metrics. |
 | `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
@@ -18,6 +20,8 @@ AgInTiFlow separates visual understanding, web search, and wrapper advice so eac
 - Codex image reading requires both `provider=codex` and explicitly enabled wrapper tools. It is not an automatic fallback.
 - OpenAI image reading defaults to `AGINTI_PERCEPTION_MODEL=gpt-5.4-mini` and `AGINTI_PERCEPTION_REASONING=medium`, with fallback models remaining inside the same explicitly selected OpenAI provider.
 - `web_research` defaults to lightweight snippet mode. The active LocalLLM can synthesize those returned snippets and sources during the next agent step without a second provider call.
+- `web_search` automatically falls back from DuckDuckGo HTML to Bing RSS. Brave Search is available only when explicitly selected and configured.
+- `deep_research` uses the active provider for planning, evidence extraction, and synthesis. It never treats another provider's ambient credentials as permission.
 - `web_research mode=openai` is accepted only for an active OpenAI session or when `allowHostedWebResearch=true`. A denied or failed hosted synthesis is returned with `ok=false`; any preserved snippets are labeled fallback evidence rather than hosted success.
 - `json_specialist` stays on the active provider. A different provider requires `allowHostedJsonSpecialist=true`; ambient hosted keys and model-generated provider arguments cannot escalate a LocalLLM session.
 - `research_wrapper` defaults to `AGINTI_RESEARCH_WRAPPER_MODEL=gpt-5.4-mini` and `AGINTI_RESEARCH_WRAPPER_REASONING=medium`.
@@ -30,6 +34,7 @@ AgInTiFlow separates visual understanding, web search, and wrapper advice so eac
 /image-read artifacts/screenshots/app.png what looks wrong?
 /image-read --codex artifacts/screenshots/app.png what looks wrong?
 /web-research latest Android Gradle plugin official docs
+/deep-research standard compare current citation-verification methods using primary sources
 /research-wrapper gpt-5.4-mini medium
 /research-wrapper off
 ```
@@ -40,6 +45,8 @@ Use `read_image` when pixels matter. Do not guess from filenames or surrounding
 
 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 `deep_research` when one lookup is insufficient: literature reviews, disputed claims, broad comparisons, technical decisions, or reports that require explicit coverage and citation auditing. See [Deep Research Engine](deep-research-engine.md).
+
 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
@@ -47,6 +54,7 @@ Use `research_wrapper` when a second model should cross-check image/web/research
 - 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.
+- Web page reads reject private/local network targets and private redirect destinations.
 - Images are capped at 10 MB and four inputs per call.
 - Artifacts preserve hashes and metadata but never store API keys.
 - Provider selection is credential-neutral: an ambient key authenticates only a backend that the run already selected and permitted.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.200",
+  "version": "0.20.202",
   "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",
@@ -77,6 +77,7 @@
     "scripts/smoke-inbox.js",
     "scripts/smoke-long-jobs.js",
     "scripts/smoke-localllm-auto-max.js",
+    "scripts/smoke-localllm-code-routing.js",
     "scripts/smoke-local-resource-policy.js",
     "scripts/smoke-localllm-model-tiers.js",
     "scripts/smoke-localllm-provider.js",
@@ -92,6 +93,7 @@
     "scripts/smoke-model-roles.js",
     "scripts/smoke-platform.js",
     "scripts/smoke-perception-research.js",
+    "scripts/smoke-deep-research.js",
     "scripts/smoke-permission-modes.js",
     "scripts/smoke-public-research-wrapper.js",
     "scripts/smoke-safe-chat.js",
@@ -143,6 +145,7 @@
     "smoke:run-stdin": "node scripts/smoke-run-stdin.js",
     "smoke:runtime-core": "node scripts/smoke-runtime-core.js",
     "smoke:localllm-auto-max": "node scripts/smoke-localllm-auto-max.js",
+    "smoke:localllm-code-routing": "node scripts/smoke-localllm-code-routing.js",
     "smoke:local-resource-policy": "node scripts/smoke-local-resource-policy.js",
     "smoke:context-budget-recovery": "node scripts/smoke-context-budget-recovery.js",
     "smoke:localllm-model-tiers": "node scripts/smoke-localllm-model-tiers.js",
@@ -154,6 +157,7 @@
     "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:deep-research": "node scripts/smoke-deep-research.js",
     "smoke:permission-modes": "node scripts/smoke-permission-modes.js",
     "smoke:public-research": "node scripts/smoke-public-research-wrapper.js",
     "smoke:safe-chat": "node scripts/smoke-safe-chat.js",
@@ -175,7 +179,7 @@
     "storage:migrate": "node bin/aginti-cli.js storage migrate",
     "publish:env": "node scripts/npm-publish-from-env.js publish --access public",
     "publish:env:whoami": "node scripts/npm-publish-from-env.js whoami",
-    "test": "npm run check && npm run smoke:localllm-provider && npm run smoke:localllm-model-tiers && npm run smoke:localllm-auto-max && npm run smoke:local-resource-policy && npm run smoke:context-budget-recovery && npm run smoke:session-runtime && npm run smoke:runtime-core && npm run smoke:progressive-tools && npm run smoke:truthful-completion && npm run smoke:writing-specialist-routing && npm run eval:local-first-agent && npm run eval:provider-attribution && npm run smoke:runtime-compat && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:math-rendering && npm run smoke:web-ui && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:execution-policy && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:public-research && npm run smoke:safe-chat && npm run smoke:auth && npm run smoke:agentlink && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:mcp && 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:long-jobs && npm run smoke:run-stdin && npm run smoke:cli-chat && npm run smoke:inbox",
+    "test": "npm run check && npm run smoke:localllm-provider && npm run smoke:localllm-model-tiers && npm run smoke:localllm-code-routing && npm run smoke:localllm-auto-max && npm run smoke:local-resource-policy && npm run smoke:context-budget-recovery && npm run smoke:session-runtime && npm run smoke:runtime-core && npm run smoke:progressive-tools && npm run smoke:truthful-completion && npm run smoke:writing-specialist-routing && npm run eval:local-first-agent && npm run eval:provider-attribution && npm run smoke:runtime-compat && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:math-rendering && npm run smoke:web-ui && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:execution-policy && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:deep-research && npm run smoke:public-research && npm run smoke:safe-chat && npm run smoke:auth && npm run smoke:agentlink && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:mcp && 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:long-jobs && npm run smoke:run-stdin && 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-auth.js

@@ -4,26 +4,22 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { authProviderKeyHelp, authProviderKeyUrl, normalizeAuthProvider } from "../src/auth-onboarding.js";
-import { getProviderDefaults } from "../src/model-routing.js";
-import { maskProviderKey, providerKeyPreview, providerKeyStatus, setProviderKey } from "../src/project.js";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "agintiflow-auth-"));
-const envKeys = [
-  "DEEPSEEK_API_KEY",
-  "OPENAI_API_KEY",
-  "OPENROUTER_API_KEY",
-  "LLM_API_KEY",
-  "QWEN_API_KEY",
-  "VENICE_API_KEY",
-  "GRSAI",
-  "GRSAI_API_KEY",
-];
-const originalEnv = Object.fromEntries(envKeys.map((key) => [key, process.env[key]]));
-const originalAgintiflowHome = process.env.AGINTIFLOW_HOME;
-for (const key of envKeys) delete process.env[key];
+const CONFIG_ENV_PATTERN = /^(?:AGENT|AGINTI|AGINTIFLOW|LOCALLLM|LOCAL_LLM|LLM|DEEPSEEK|OPENAI|OPENROUTER|QWEN|VENICE|GRSAI|BRAVE|ALLOW_|WRAPPER_|MAX_STEPS$|SANDBOX_MODE$|USE_DOCKER_SANDBOX$|PACKAGE_INSTALL_POLICY$|COMMAND_CWD$|PREFERRED_WRAPPER$)/u;
+for (const key of Object.keys(process.env)) {
+  if (CONFIG_ENV_PATTERN.test(key)) delete process.env[key];
+}
 process.env.AGINTIFLOW_HOME = path.join(tempRoot, ".agintiflow-home");
+const [authOnboarding, modelRouting, project] = await Promise.all([
+  import("../src/auth-onboarding.js"),
+  import("../src/model-routing.js"),
+  import("../src/project.js"),
+]);
+const { authProviderKeyHelp, authProviderKeyUrl, normalizeAuthProvider } = authOnboarding;
+const { getProviderDefaults } = modelRouting;
+const { loadProjectEnv, maskProviderKey, providerKeyPreview, providerKeyStatus, setProviderKey } = project;
 
 function assert(condition, message) {
   if (!condition) throw new Error(message);
@@ -35,7 +31,12 @@ async function runCli(args, stdin = "") {
       cwd: tempRoot,
       stdio: ["pipe", "pipe", "pipe"],
       env: {
-        ...process.env,
+        PATH: process.env.PATH || "/usr/bin:/bin",
+        HOME: tempRoot,
+        USERPROFILE: tempRoot,
+        LANG: "C.UTF-8",
+        LC_ALL: "C.UTF-8",
+        AGINTIFLOW_HOME: process.env.AGINTIFLOW_HOME,
         AGINTIFLOW_RUNTIME_DIR: "",
       },
     });
@@ -89,7 +90,17 @@ try {
 
   const projectOnlyRoot = path.join(tempRoot, "project-only");
   await fs.mkdir(path.join(projectOnlyRoot, ".aginti"), { recursive: true });
-  await fs.writeFile(path.join(projectOnlyRoot, ".aginti", ".env"), 'OPENAI_API_KEY="project-only-openai-key"\n', "utf8");
+  await fs.writeFile(
+    path.join(projectOnlyRoot, ".aginti", ".env"),
+    ['OPENAI_API_KEY="project-only-openai-key"', 'AGINTI_LOCALLLM_CODE_MODEL="project-code-alias"', ""].join("\n"),
+    "utf8"
+  );
+  const projectOnlyEnv = loadProjectEnv(projectOnlyRoot);
+  assert(projectOnlyEnv.projectEnv, "project-only LocalLLM code model env was not parsed");
+  assert(
+    process.env.AGINTI_LOCALLLM_CODE_MODEL === "project-code-alias",
+    "AGINTI_LOCALLLM_CODE_MODEL was not loaded from the project env"
+  );
   let projectOnlyStatus = providerKeyStatus(projectOnlyRoot);
   assert(projectOnlyStatus.openai && projectOnlyStatus.projectEnv, "project-only key was not loaded");
   await fs.access(path.join(tempRoot, ".agintiflow-home", ".env"))
@@ -100,6 +111,7 @@ try {
       if (error?.code !== "ENOENT") throw error;
     });
   delete process.env.OPENAI_API_KEY;
+  delete process.env.AGINTI_LOCALLLM_CODE_MODEL;
 
   process.env.DEEPSEEK_API_KEY = "ambient-deepseek-key";
   process.env.OPENROUTER_API_KEY = "ambient-openrouter-key";
@@ -182,6 +194,7 @@ try {
           "openrouter-defaults",
           "venice-defaults",
           "project-key-not-auto-promoted",
+          "project-code-model-env",
           "ambient-key-discovery-is-read-only",
           "project-key-override",
           "qwen-key-status",
@@ -195,11 +208,8 @@ try {
     )
   );
 } finally {
-  for (const key of envKeys) {
-    if (originalEnv[key] === undefined) delete process.env[key];
-    else process.env[key] = originalEnv[key];
+  for (const key of Object.keys(process.env)) {
+    if (CONFIG_ENV_PATTERN.test(key)) delete process.env[key];
   }
-  if (originalAgintiflowHome === undefined) delete process.env.AGINTIFLOW_HOME;
-  else process.env.AGINTIFLOW_HOME = originalAgintiflowHome;
   await fs.rm(tempRoot, { recursive: true, force: true });
 }