@lazyingart/agintiflow 0.20.197 → 0.20.198

package/.env.example

@@ -0,0 +1,34 @@
+# Local-only credentials template. Copy to .env and keep it untracked.
+# Do not commit real values.
+
+# Default local-first text provider. Keep LocalLLM on loopback.
+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_MAX_MODEL=localllm-max
+AGINTI_LOCALLLM_ALLOW_AUTO_MAX=false
+AGINTI_LOCALLLM_VISION_MODEL=localllm-vision-xl
+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.
+# Hosted provider keys below never act as a LocalLLM failure fallback.
+
+# Optional explicit hosted upgrades. They are never automatic fallbacks.
+DEEPSEEK_API_KEY=
+OPENAI_API_KEY=
+AGINTI_ALLOW_HOSTED_IMAGE_PERCEPTION=false
+AGINTI_ALLOW_HOSTED_WEB_RESEARCH=false
+AGINTI_ALLOW_HOSTED_JSON_SPECIALIST=false
+# A cross-provider writer needs both an explicit target and the permission below.
+AGINTI_WRITING_PROVIDER=
+AGINTI_WRITING_MODEL=
+AGINTI_ALLOW_HOSTED_WRITING_SPECIALIST=false
+
+# Optional local npm publish fallback. Prefer GitHub Actions Trusted Publishing.
+NPM_TOKEN=
+NODE_AUTH_TOKEN=
+NPM_CONFIG_REGISTRY=https://registry.npmjs.org/

package/AGENTS.md

@@ -20,7 +20,7 @@
 - `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`, `AGENT_PROVIDER=deepseek`, or `AGENT_PROVIDER=mock` when running locally.
+Use `AGENT_PROVIDER=localllm` for the default loopback LocalLLM runtime. Select `AGENT_PROVIDER=openai`, `AGENT_PROVIDER=deepseek`, or another hosted provider only as an explicit upgrade; saved or ambient hosted keys authenticate that choice but never select it or create a fallback. Use `AGENT_PROVIDER=mock` for deterministic offline tests.
 
 ## Coding Style & Naming Conventions
 

package/README.md

@@ -13,7 +13,7 @@
 ![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?logo=nodedotjs&logoColor=white)
 ![Playwright](https://img.shields.io/badge/Browser-Playwright-2EAD33?logo=playwright&logoColor=white)
 ![CLI + Web](https://img.shields.io/badge/Interface-CLI%20%2B%20Web-0ea5e9)
-![Text Models](https://img.shields.io/badge/Text-DeepSeek%20%2B%20Venice%20%2B%20OpenAI%20%2B%20Qwen-2563eb)
+![Text Models](https://img.shields.io/badge/Text-LocalLLM%20%2B%20Optional%20Hosted-2563eb)
 ![Aux Image](https://img.shields.io/badge/Aux%20Image-GRS%20AI%20%2B%20Venice-ec4899)
 ![Sandbox](https://img.shields.io/badge/Shell-Docker%20Sandbox-f97316)
 ![Status](https://img.shields.io/badge/Status-Prototype-7c3aed)
@@ -49,12 +49,12 @@ Most agent tools are either a chat box with hidden state or an expensive one-mod
 
 | Principle | What it means in practice |
 | --- | --- |
-| Cheap intelligence changes the architecture | DeepSeek V4 Flash and Pro make it practical to spend more calls on routing, scouting, review, and recovery instead of forcing one expensive call to do everything. |
+| Local intelligence changes the architecture | The baseline uses the sibling LocalLLM gateway for private route and main lanes. Stronger hosted models remain explicit upgrades, not hidden fallbacks. |
 | 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 JSON and Markdown perception artifacts, uses OpenAI vision when configured, and falls back to `codex exec --image` when Codex is available. `web_research` saves sourced research artifacts, and `research_wrapper` can ask Codex `gpt-5.4-mini` medium for a strict-JSON second opinion. |
+| 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. |
 | 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,9 @@ aginti init --template aaps
 aginti init --template supervision
 ```
 
-On first interactive use, AgInTiFlow opens an auth wizard if no main model key is found. Pick DeepSeek, OpenAI, OpenRouter, Qwen, or Venice, paste the key, and it saves account-wide to `~/.agintiflow/.env` with restricted permissions. Current project `.aginti/.env` files can still override account defaults when needed. You can rerun setup any time:
+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.
+
+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:
 
 ```bash
 aginti auth
@@ -100,6 +102,7 @@ Provider signup and key pages:
 
 | Provider | Register / key page | API base URL used by AgInTiFlow |
 | --- | --- | --- |
+| LocalLLM | Local sibling service; no signup | `http://127.0.0.1:8008/v1` |
 | DeepSeek | [https://platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys) | `https://api.deepseek.com` |
 | OpenRouter | [https://openrouter.ai/settings/keys](https://openrouter.ai/settings/keys) | `https://openrouter.ai/api/v1` |
 | Venice | [https://venice.ai/settings/api](https://venice.ai/settings/api) | `https://api.venice.ai/api/v1` |
@@ -180,7 +183,7 @@ aginti --language de
 | Sync reviewed skills | `aginti skillmesh status`, `aginti skillmesh sync` |
 | Update CLI | `aginti update` |
 
-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.
+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`. A resumed session keeps its versioned provider/model/tool-policy snapshot; current preferences do not silently change it, and explicit changes use revision checks. 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.
 
@@ -242,15 +245,15 @@ 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 | DeepSeek fast/pro defaults, manual OpenAI/Qwen/Venice/mock routes, spare models, wrapper models, and auxiliary image models. |
+| 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. |
 | 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, otherwise it can fall back to Codex CLI image attachments when available. It saves JSON and Markdown reports and can surface the report in the canvas. `web_research` preserves source lists, and optional OpenAI hosted web search or `research_wrapper` can be used for higher-confidence research. |
+| 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. |
 | 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. |
-| Image generation | Optional GRS AI and Venice image tools with saved manifests and canvas artifact previews. |
+| Image generation | Optional, default-off GRS AI and Venice image tools with saved manifests and canvas previews. Credentials authenticate the selected provider but never select or fail over providers. |
 | Skill library | Built-in Markdown skills plus project-local `.aginti/skills/<id>/SKILL.md` skills for reusable workflow knowledge that should not be hard-coded into the runtime. |
 | External skill packs | Whole Agent Skills repositories can be loaded as grouped packs without flattening. A sibling `../scientific-agent-skills` checkout is discovered as the `scientific` category, so commands like `aginti skills rdkit` and `aginti skills "single cell scanpy"` expose K-Dense Scientific Agent Skills when present. |
 | Skill Mesh | Optional strict skill recording/sharing for reviewed reusable skill packs. If unused, AgInTiFlow runs normally without background sharing. |
@@ -262,11 +265,11 @@ AgInTiFlow does not treat "the model" as one global setting. It has roles:
 
 | Role | Default | Purpose |
 | --- | --- | --- |
-| 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. |
+| 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. |
+| 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` | Image generation and other non-text helper tools. |
+| Auxiliary | `grsai/nano-banana-2` (off) | Explicitly enabled image generation and other non-text helper tools; no credential-driven provider failover. |
 
 Useful selectors:
 
@@ -280,7 +283,7 @@ Useful selectors:
 /venice
 ```
 
-Venice routes can be used for optional uncensored or less restricted creative work. DeepSeek remains the economic default for normal engineering workflows. See [docs/model-selection.md](docs/model-selection.md) and [references/venice-model-reference.md](references/venice-model-reference.md).
+Venice routes can be used for optional uncensored or less restricted creative work. DeepSeek and the other hosted providers remain explicit upgrades for tasks that benefit from them. See [docs/model-selection.md](docs/model-selection.md), [docs/local-first-agent-runtime.md](docs/local-first-agent-runtime.md), and [references/venice-model-reference.md](references/venice-model-reference.md).
 OpenRouter is available as a first-class OpenAI-compatible provider with one key and company-grouped model buckets such as OpenRouter OpenAI, Anthropic, Google, DeepSeek, Qwen, Meta, Mistral, Moonshot, and xAI.
 
 ## AAPS And Large Workflows
@@ -356,6 +359,13 @@ Detailed runtime notes are in [docs/runtime-modes-and-autonomy.md](docs/runtime-
 Common environment variables:
 
 ```bash
+AGENT_PROVIDER=localllm
+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
+
+# Optional explicit hosted upgrades; never automatic LocalLLM fallbacks.
 DEEPSEEK_API_KEY=...
 OPENAI_API_KEY=...
 OPENROUTER_API_KEY=...
@@ -364,7 +374,6 @@ OPENROUTER_MODEL=openrouter/auto
 QWEN_API_KEY=...
 VENICE_API_KEY=...
 GRSAI_API_KEY=...
-AGENT_PROVIDER=deepseek
 AGENT_ROUTING_MODE=smart
 AGINTI_TASK_PROFILE=auto
 AGINTI_LANGUAGE=en
@@ -398,6 +407,7 @@ More detail:
 | AAPS adapter | [docs/aaps.md](docs/aaps.md) |
 | AgentLink | [docs/agentlink.md](docs/agentlink.md) |
 | Model selection and roles | [docs/model-selection.md](docs/model-selection.md) |
+| Local-first provider and agent boundary | [docs/local-first-agent-runtime.md](docs/local-first-agent-runtime.md) |
 | SCS mode | [docs/student-committee-supervisor.md](docs/student-committee-supervisor.md) |
 | 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) |

package/docs/auxiliary-image-generation.md

@@ -7,6 +7,8 @@ AgInTiFlow separates **skills** from **tools**:
 
 The optional image-generation skills are `image_generation` and `venice_image_generation`. Both use the deterministic `generate_image` tool.
 
+Hosted image generation is off by default. Enable the auxiliary mode explicitly with `/auxiliary on`, `/auxiliary image`, the corresponding UI toggle, or `allowAuxiliaryTools=true`. Merely storing `GRSAI` or `VENICE_API_KEY` does not expose or authorize `generate_image` in an agent run.
+
 `generate_image` is a raster-image tool. It does not produce true SVG/vector output. If a caller requests `svg`, the tool records
 `requestedFormat: "svg"`, generates a PNG fallback with `actualFormat: "png"`, and returns a `formatNotice`. If the task truly requires
 editable vectors, use AgInTiFlow file tools to write deterministic SVG/LaTeX/HTML instead of calling `generate_image`.
@@ -32,6 +34,8 @@ Inside interactive chat, use either spelling:
 
 Keys are saved in `~/.agintiflow/.env` by default as `GRSAI` or `VENICE_API_KEY` with `0600` permissions. Project `.aginti/.env` can override them. The CLI and web app only report whether a key exists; they never return raw values.
 
+Provider selection is independent of key discovery. The selected auxiliary provider remains GRS AI or Venice for the whole call. If its key is missing or the request fails, the tool stops visibly; it never switches to the other provider because that provider's ambient key happens to exist. When no provider is selected, the deterministic default is GRS AI.
+
 ## Runtime Flow
 
 For image, cover, poster, illustration, photo, or logo-concept requests, the model can call:
@@ -118,3 +122,5 @@ Generated images are sent to the canvas automatically when available.
 ## Guardrails
 
 Output paths must stay inside the project workspace. Secret paths, `.git`, `node_modules` writes, and oversized reference images are blocked. Reference images may be workspace files, HTTPS URLs, or data URLs.
+
+The mode gate is enforced inside `generate_image` as well as in progressive tool exposure, so a handcrafted model tool call cannot bypass a disabled auxiliary mode.

package/docs/external-skill-packs.md

@@ -6,7 +6,7 @@ them into AgInTiFlow's built-in `skills/` directory.
 
 ## Scientific Agent Skills
 
-When `/home/lachlan/ProjectsLFS/Agent/scientific-agent-skills` exists,
+When a sibling `../scientific-agent-skills` checkout exists,
 AgInTiFlow automatically discovers it as:
 
 - pack: `scientific-agent-skills`

package/docs/large-codebase-engineering.md

@@ -13,11 +13,11 @@ Local agent references informed the design:
 - Claw-style `doctor` discipline: check health and environment before treating system symptoms as code bugs.
 - Claude/Codex-style context discipline: read project instructions, manifests, entry points, and failing tests before touching broad files.
 
-The shared pattern is not “put the whole repo in context.” It is: build a cheap map, choose the next exact evidence, edit with deterministic patches, verify, then compact what changed. AgInTiFlow uses cheap DeepSeek calls to add more independent eyes around that loop, not to replace it.
+The shared pattern is not “put the whole repo in context.” It is: build a cheap map, choose the next exact evidence, edit with deterministic patches, verify, then compact what changed. AgInTiFlow can use bounded scout calls on the explicitly selected provider to add more independent eyes around that loop, not to replace it.
 
 ## Skill vs Tool
 
-The `large-codebase` profile is a skill: it changes the model’s engineering behavior. It tells DeepSeek v4 pro to orient first, plan minimally, patch incrementally, and verify.
+The `large-codebase` profile is a skill: it changes the model’s engineering behavior. It tells the active main model—LocalLLM Deep by default—to orient first, plan minimally, patch incrementally, and verify.
 
 The `inspect_project` function is a tool: it deterministically scans the workspace and returns:
 
@@ -48,7 +48,7 @@ Mature coding agents avoid keeping an entire growing project in the prompt. AgIn
 - Project map: `inspect_project` summaries, language counts, source/test directories, and recommended reads.
 - Active evidence: exact search hits, selected files, failing command output, and compact git status/diff.
 - Patch context: only the nearby code needed for `apply_patch`, plus before/after hashes and compact diffs.
-- Scout synthesis: cheap parallel DeepSeek scouts produce bounded advice, then a coordinator summary is injected instead of every long transcript becoming permanent context.
+- Scout synthesis: bounded parallel scouts use the explicitly selected provider, then a coordinator summary is injected instead of every long transcript becoming permanent context.
 
 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.
 
@@ -84,7 +84,7 @@ aginti --profile large-codebase "fix the failing tests"
 
 or choose **Large codebase engineering** in the web task-profile dropdown.
 
-Smart routing sends this profile to DeepSeek v4 pro even when the user prompt is short.
+Smart routing sends this profile to LocalLLM Deep even when the user prompt is short. Hosted providers are used only when selected explicitly; their presence in saved or ambient credentials does not activate them or create a fallback.
 
 ## Auto Profile Behavior
 
@@ -100,11 +100,11 @@ aginti "fix the Rust workspace build"
 aginti "repair the Docker setup and run the Node tests"
 ```
 
-These route to DeepSeek v4 pro when the complexity score is high enough.
+These route to LocalLLM Deep when the complexity score is high enough.
 
 ## Parallel Scout Mode
 
-DeepSeek calls are cheap enough that complex tasks can use several short advisory calls before the main executor starts. When enabled, AgInTiFlow runs bounded scouts in parallel:
+Complex tasks can use several short advisory calls before the main executor starts. When explicitly enabled, AgInTiFlow runs bounded scouts in parallel on the selected provider:
 
 - Architect: decomposes the task and identifies first files/logs/commands.
 - Implementer: predicts patch boundaries and focused checks.
@@ -139,7 +139,7 @@ aginti --no-web-search "work fully offline"
 
 ## Cross-Language Playbook
 
-AgInTiFlow gives DeepSeek stack-specific reminders without hardcoding a solution:
+AgInTiFlow gives the active executor stack-specific reminders without hardcoding a solution:
 
 - JS/TS: inspect package scripts and lockfiles, then run focused `node`, `tsc`, or test commands.
 - Python: inspect `pyproject.toml` or requirements, prefer project-local venv/conda/Docker, then run focused pytest/module checks.

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

@@ -0,0 +1,199 @@
+# Local-First Agent Runtime
+
+Status: active architecture and implementation goal
+
+## Objective
+
+AgInTiFlow must remain a general agent that can plan, select tools, execute guarded work, verify evidence, and finish truthfully. Its dependable baseline is the sibling LocalLLM service. DeepSeek, OpenAI, and other hosted providers remain optional upgrades, never hidden prerequisites or silent fallbacks.
+
+The projects stay decoupled:
+
+```text
+AgInTiFlow orchestration
+  -> provider/capability contract
+    -> LocalLLM /v1 (baseline)
+    -> DeepSeek / OpenAI / compatible gateways (explicit upgrades)
+```
+
+AgInTiFlow owns sessions, plans, permissions, tool dispatch, idempotency, context compaction, recovery, and verification. LocalLLM owns bounded stateless inference. AgInTiFlow must not depend on LocalLLM's web UI, SQLite conversations, or `/api/agent/*` management routes.
+
+## Baseline provider contract
+
+The canonical provider id is `localllm`. User-facing aliases `local`, `local-llm`, and `local_llm` may normalize to it, but raw engine labels such as `ollama` or `lmstudio` must not silently become LocalLLM. Saved sessions and events use the canonical id.
+
+Default connection:
+
+```text
+base URL:        http://127.0.0.1:8008/v1
+placeholder key: local-dev-key
+health:          http://127.0.0.1:8008/healthz
+models:          authenticated GET /v1/models
+route lane:      localllm-fast
+main lane:       localllm-deep
+maximum lane:    localllm-max
+vision:          localllm-vision-xl
+embedding:       localllm-embed (sibling-service alias; not an AgInTi text-routing tier)
+```
+
+The default bearer value used by the local deployment is an interoperability placeholder, not a security boundary. Configuration must still send it as a normal bearer token and must never log it. Local endpoints remain loopback-only. A non-loopback LocalLLM base URL is rejected instead of quietly exporting prompts.
+
+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.
+
+## Provider-neutral capabilities
+
+Provider identity and model capability are separate. The current public provider contract normalizes `provider`, `label`, `openaiCompatible`, `local`, `requiresApiKey`, `toolProtocol`, `structuredOutput`, `supportsReasoningEffort`, and `textToolFallback`. The reusable target contract will expand that record with model- and runtime-specific fields instead of scattering provider-name checks:
+
+```text
+local
+requiresApiKey
+nativeTools
+textToolFallback
+jsonObject
+strictJsonSchema
+vision
+embeddings
+reasoningEffort
+effectiveContext
+maxOutput
+maxConcurrency
+```
+
+Current LocalLLM request policy starts conservatively:
+
+- native OpenAI-compatible function calls are tried first and locally validated;
+- parallel tool calls are disabled;
+- `json_object` plus strict post-validation is preferred over recursive `oneOf`/`$defs` schemas;
+- a bounded text-tool protocol is a fallback path, not the default;
+- remote images are fetched only when web access is enabled and any configured domain allowlist permits them; the provider receives bounded data URLs rather than the original remote URL;
+- cancellation closes the active HTTP request; it does not imply provider-side rollback;
+- the main agent loop is sequential, but the general runtime does not yet enforce a provider-wide semaphore across sessions; explicitly enabled scouts and specialist batches use their own bounded concurrency.
+
+DeepSeek and OpenAI use the same normalized interface. A stronger model may receive a larger context, broader tool set, or higher step budget, but it does not get weaker permissions or a different truthfulness contract.
+
+## Local-model execution ladder
+
+The runtime should choose the least expensive lane that can satisfy the request:
+
+1. **Direct answer** — ordinary conversation or a bounded knowledge question, with no tool schemas.
+2. **Focused agent** — one task-shaped tool bundle, a small step budget, and no separate planning call unless needed.
+3. **Thorough agent** — explicit plan, broader task-shaped tools, evidence checks, and context compaction.
+4. **Supervised/SCS** — high-risk or long work with separate review and truthful blocker handling.
+
+This is progressive capability disclosure, not capability removal. A focused coding request initially needs workspace inspection, search/read, patch/write, a guarded command, and finish. It does not need browser, MCP, writing, image, AgentLink, tmux, and research schemas in the same first call. A later turn may add a capability only when task routing or observed evidence justifies it.
+
+Suggested compact bundles:
+
+| Bundle | Initial tools |
+| --- | --- |
+| Workspace/code | `inspect_project`, `list_files`, `search_files`, `read_file`, `apply_patch`, `write_file`, `run_command`, `finish` |
+| Browser | `open_url`, `click`, `type`, `scroll`, `press`, `back`, `wait`, `finish` |
+| Research | `web_search`, `web_research`, `finish` |
+| Long job | `start_long_job`, `long_job_status`, `finish` |
+| Coordination | selected AgentLink or tmux tools plus `finish` |
+
+Disabled tools stay impossible to dispatch even if a model names them in text or JSON.
+
+## Tool-call recovery
+
+Every model-selected action passes the same server-side registry and argument validator. Model output is never executable authority.
+
+For one agent step:
+
+1. Try a simple native function call.
+2. Reject unknown, disabled, duplicate, malformed, or over-budget calls locally.
+3. If the provider/model is known to need repair, request one plain JSON or text-protocol repair with only the relevant tools.
+4. Revalidate the repair from scratch.
+5. If repair fails, return a deterministic safe blocker or use an explicitly configured stronger lane.
+
+Never replay a mutating tool merely because a model request timed out. The persisted tool ledger must prove a call has not already completed before retrying it.
+
+Plain assistant content with no tool call is a valid finish only when the execution policy permits a direct answer or the evidence ledger shows the requested work is already complete. Otherwise the runtime asks once for the missing action/evidence, then stops truthfully instead of pretending completion.
+
+## Context and output budgets
+
+Character-only history accounting is not enough because tool schemas and UTF-8 density also consume context. The request budget includes:
+
+```text
+system instructions
++ selected tool schemas
++ conversation and compacted evidence
++ current task/snapshot
++ output reserve
+```
+
+Conservative LocalLLM defaults:
+
+- configured request envelope: 32K total context, including messages, selected tool schemas, and output allowance;
+- planning response: at most 2K output inside that same configured request envelope;
+- normal agent step: an 8K output allowance and 4K tool-schema reserve leave a 20K compaction input ceiling under the default 32K envelope;
+- final answer: at most 8K output unless the task explicitly requires more;
+- compaction target: preserve goal, permissions, plan, unresolved blockers, file/tool evidence, and recent turns;
+- concurrency is controlled by each execution path: the main loop is sequential, while explicitly enabled batch/helper paths may issue bounded parallel requests.
+
+If a model returns empty visible content and no valid tool call, retry once with a compacted prompt and adequate output headroom. Repeated emptiness becomes a visible model limitation, not an infinite loop.
+
+## Durable session runtime
+
+Each session stores a versioned, revisioned runtime snapshot containing only safe provider, model-role, tool-policy, sandbox, context-budget, wrapper, auxiliary, and network-scope choices. It never stores API keys, bearer values, base URLs, environment maps, clients, callbacks, or abort signals.
+
+On resume, the saved snapshot is authoritative. Current shell variables and current web preferences cannot silently replace its provider or role models. Credentials are freshly resolved for the saved provider after the snapshot is loaded. An explicit runtime change must carry the current revision; stale changes and continuations fail with a conflict before readiness checks or model-client creation. Web preferences seed new sessions only. The same contract applies to CLI, interactive, and web continuations.
+
+Legacy sessions without a snapshot are migrated conservatively: route, main, and spare roles all inherit their saved top-level provider/model so migration cannot introduce a hosted lane. The web execution gate serializes same-process continuations; independent processes should not concurrently mutate one session.
+
+## Hosted upgrades and privacy
+
+Cloud escalation is opt-in and visible. A local failure must not silently send the workspace, prompt, images, tool results, or compacted history to DeepSeek/OpenAI.
+
+An escalation policy records:
+
+```text
+allowed providers
+reason for escalation
+maximum context exported
+whether artifacts/images may leave the host
+whether the user approved this run or configured a durable policy
+```
+
+Provider failure before any tool executes may retry or switch according to that policy. After a tool executes, failover reuses the persisted result and never repeats the action without an idempotency proof.
+
+## Evaluation gates
+
+Offline deterministic tests run on every change:
+
+- LocalLLM defaults, aliases, loopback enforcement, and no-key onboarding;
+- smart route/main selection for `localllm-fast` and `localllm-deep`;
+- compact tool bundle size and disabled-tool rejection;
+- valid native tool call and complete tool-result round trip;
+- malformed arguments, unknown tool, duplicate call id, and one bounded repair;
+- no-tool direct answer versus incomplete-work retry/blocker;
+- timeout before output, cancellation, and no post-cancel dispatch;
+- context calculation includes tool schemas and output reserve;
+- no silent hosted fallback;
+- session resume preserves provider, model, capability profile, and executed-tool ledger.
+
+Live compatibility tests are opt-in because they load local models:
+
+| Lane | Minimum cases |
+| --- | --- |
+| `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-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 |
+
+Record pass/fail, latency, prompt size, tool accuracy, repair count, repeated-call count, completion truthfulness, and peak context. Quality promotion requires deterministic safety gates first; a fluent answer is not evidence that work completed.
+
+## Delivery sequence
+
+1. Add the provider contract and make LocalLLM the credential-free local-first default.
+2. Remove DeepSeek-only assumptions from routing, auth, specialists, CLI, web settings, and saved preferences.
+3. Add provider-aware request budgets and progressive tool disclosure.
+4. Add bounded native-tool repair and incomplete-work detection.
+5. Add offline conformance fixtures, then opt-in live LocalLLM evaluations.
+6. Add explicit cloud escalation policy and comparative quality routing.
+7. Expose the provider-neutral agent runtime as a reusable library/API so LocalLLM may later mount AgInTi capabilities without importing AgInTiFlow UI or storage internals.
+
+The final integration direction is dependency inversion: LocalLLM can call a packaged AgInTi runtime adapter later, and AgInTiFlow can call any conforming inference provider today. Neither repository becomes the other's internal implementation detail.

package/docs/model-selection.md

@@ -6,15 +6,26 @@ AgInTiFlow treats model choice as a role-based control plane. A provider supplie
 
 | Role | CLI command | Default | Purpose |
 | --- | --- | --- | --- |
-| Route | `/route` | `deepseek/deepseek-v4-flash` | Fast planner, triage, short tasks, and routing decisions. |
-| Main | `/model` or `/main` | `deepseek/deepseek-v4-pro` | Complex executor for coding, debugging, writing, and long tasks. |
-| Spare | `/spare` | `openai/gpt-5.4` with `medium` reasoning | Optional fallback or cross-check model. |
+| Route | `/route` | `localllm/localllm-fast` | Local fast planner, triage, short tasks, and routing decisions. |
+| Main | `/model` or `/main` | `localllm/localllm-deep` | Local complex executor for coding, debugging, writing, and long tasks. |
+| Spare | `/spare` | `localllm/localllm-deep` with `medium` reasoning | Local cross-check lane; hosted spares require explicit selection. |
 | Wrapper | `/wrapper` | `codex gpt-5.5 medium` | External coding assistant when wrapper tools are enabled. |
-| Auxiliary | `/auxiliary` | `grsai/nano-banana-2` | Image/media tools; Venice image models are optional. |
+| Auxiliary | `/auxiliary` | `grsai/nano-banana-2` (tool off) | Explicitly enabled image/media tools; Venice image models are optional. |
 
-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.
+Smart routing sends normal work to the LocalLLM route model and complex work to the LocalLLM main model. Manual hosted provider/model selection remains available for explicit one-off upgrades. A local error fails closed instead of changing providers.
 
-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.
+The local tier policy uses the workstation's installed aliases without treating model presence as permission to load a heavy model:
+
+| Alias | Installed role | Automatic policy |
+| --- | --- | --- |
+| `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-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.
+
+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.
 
 ## CLI Commands
 
@@ -23,8 +34,8 @@ aginti models
 aginti --list-models
 aginti --list-routes
 
-# one-shot overrides
-aginti --route-model deepseek-v4-flash --main-model deepseek-v4-pro "fix this project"
+# local-first defaults and one-shot overrides
+aginti --route-model localllm-fast --main-model localllm-deep "fix this project"
 aginti --provider openrouter --model openrouter/auto --routing manual "try a gateway route"
 aginti --provider openrouter --model anthropic/claude-sonnet-4.6 --routing manual "draft a design review"
 aginti --provider venice --model venice-uncensored-1-2 --routing manual "draft a note"
@@ -43,6 +54,8 @@ Interactive commands:
 /route
 /model
 /spare
+/route localllm/localllm-fast
+/model localllm/localllm-deep
 /route deepseek/deepseek-v4-flash
 /model deepseek/deepseek-v4-pro
 /spare openai/gpt-5.4 medium
@@ -62,6 +75,7 @@ Provider families:
 
 | Family | Models |
 | --- | --- |
+| LocalLLM | `localllm-fast`, `localllm-deep`, `localllm-max`, `localllm-vision-xl`; 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 |
@@ -90,11 +104,11 @@ Disable Venice
 
 For scripts or non-interactive terminals, `/venice` uses Venice 1.2 for both roles. You can also set both roles directly with `/venice 1.2`, `/venice 1.1`, or `/venice gemma`. Use two values to set route and main separately, for example `/venice 1.2 gemma`.
 
-Use `/venice off` to switch back to the DeepSeek defaults:
+Use `/venice off` to switch back to the LocalLLM defaults:
 
 ```text
-/route deepseek/deepseek-v4-flash
-/model deepseek/deepseek-v4-pro
+/route localllm/localllm-fast
+/model localllm/localllm-deep
 ```
 
 It keeps smart routing enabled. If the Venice key is missing, run `/auth venice`.
@@ -103,7 +117,8 @@ It keeps smart routing enabled. If the Venice key is missing, run `/auth venice`
 
 | Bucket | Provider | Typical use |
 | --- | --- | --- |
-| `deepseek` | DeepSeek | Default route/main because V4 Flash and V4 Pro are cheap and strong. |
+| `localllm` | LocalLLM | Default private route/main through the sibling loopback gateway. |
+| `deepseek` | DeepSeek | Explicit hosted route for economical stronger-model work. |
 | `openai` | OpenAI | Spare/frontier checks, Codex-family work, and explicit manual routes. |
 | `openrouter` | OpenRouter | OpenAI-compatible gateway with auto/free/code routers. |
 | `openrouter-openai` | OpenRouter | OpenAI-family models through OpenRouter. |
@@ -133,6 +148,8 @@ 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.
+
 Keys are saved account-wide in `~/.agintiflow/.env` by default. Use `--project` only when the current project needs an override in ignored `.aginti/.env`:
 
 ```bash

package/docs/patch-tools.md

@@ -14,4 +14,4 @@ All paths must stay inside the configured workspace. Secret-like paths, `.git`,
 
 For large codebases, the model should first use `list_files`, `search_files`, and `read_file` to identify the relevant files. It should then call `apply_patch`, run safe tests or linters when available, and summarize changed files and residual risk.
 
-Smart routing treats patch/refactor/edit/database tasks as complex work, so DeepSeek v4 pro is selected by default unless the user explicitly chooses another route.
+Smart routing treats patch/refactor/edit/database tasks as complex work, so the LocalLLM `localllm-deep` main lane is selected by default unless the user explicitly chooses another route.

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

@@ -13,13 +13,15 @@ AgInTiFlow separates visual understanding, web search, and wrapper advice so eac
 
 ## Defaults
 
-- `read_image` uses OpenAI Responses vision when `OPENAI_API_KEY` is configured.
-- If OpenAI vision is unavailable, `read_image` falls back to `codex exec --image` when the Codex CLI is installed and wrapper tools are enabled.
-- Wrapper tools default on when Codex is available, and can still be disabled with `/wrapper off` or `--no-wrapper`-style runtime settings.
-- `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 OpenAI 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`.
+- In a LocalLLM session, `read_image provider=auto` sends bounded image data to the loopback LocalLLM Chat Completions endpoint with `AGINTI_LOCALLLM_VISION_MODEL` or `localllm-vision-xl`. It does not try OpenAI or a wrapper after a local failure.
+- In an OpenAI session, `read_image provider=auto` uses OpenAI Responses vision. A non-OpenAI session must set `allowHostedImagePerception=true` before `provider=openai` is accepted. `OPENAI_API_KEY` by itself grants no permission.
+- 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_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`.
+- Wrapper tools and auxiliary image generation are opt-in. Installed CLIs or saved provider keys do not enable them by themselves.
 - Wrapper advice is not evidence by itself. Verify file paths, sources, hashes, and artifacts before claiming completion.
 
 ## Interactive Commands
@@ -47,5 +49,6 @@ Use `research_wrapper` when a second model should cross-check image/web/research
 - 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.
+- Provider selection is credential-neutral: an ambient key authenticates only a backend that the run already selected and permitted.
 
 See the design note in [references/multimodal-research-wrapper-design.md](../references/multimodal-research-wrapper-design.md).