@lazyingart/agintiflow 0.20.197 → 0.20.199

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/bin/aginti-cli.js

@@ -1,7 +1,22 @@
 #!/usr/bin/env node
-import { main } from "../src/cli.js";
+import fs from "node:fs";
 
-main().catch((error) => {
+const argv = process.argv.slice(2);
+
+function fail(error) {
   console.error(error);
   process.exit(1);
-});
+}
+
+try {
+  if (["--version", "version", "-v"].includes(argv[0])) {
+    const packageJson = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    console.log(packageJson.version);
+  } else {
+    import("../src/cli.js")
+      .then(({ main }) => main(argv))
+      .catch(fail);
+  }
+} catch (error) {
+  fail(error);
+}

package/docs/agent-runtime-pipe.md

@@ -8,6 +8,30 @@ AgInTiFlow keeps CLI and web runs equivalent by using a project-local session in
 - Canonical session store: `~/.agintiflow/sessions/<session-id>/`.
 - Runtime inbox: `~/.agintiflow/sessions/<session-id>/inbox.jsonl`.
 
+## Persistence Guarantees
+
+Long-lived processes reuse one SQLite session-index connection and prepared
+statement set per resolved `AGINTIFLOW_HOME`. The index enables WAL mode and a
+bounded busy timeout so CLI, web, and bridge processes can update the
+rebuildable index without repeatedly reopening and migrating the database.
+Call `closeSessionIndexConnections()` in tests or embedding hosts that switch
+runtime homes inside one process.
+
+Each `SessionStore` memoizes directory/pointer initialization and serializes
+its event appends. Concurrent callers therefore retain call order without
+recreating the session pointer for every event. `state.json` remains an atomic,
+fsynced save boundary. A missing state file is resumably absent; malformed JSON
+raises `SESSION_STATE_CORRUPT` instead of silently looking like a new session.
+
+## Machine Run Input
+
+`aginti run` uses deterministic input precedence: explicit `--stdin` reads
+standard input, otherwise a positional prompt wins, and piped standard input is
+used only when no positional prompt exists. This keeps positional automation
+working in subprocesses whose stdin is non-interactive while preserving both
+explicit and implicit pipe workflows. `aginti --version` is handled by the
+lightweight launcher without loading the full agent and web runtime.
+
 When a run is active, the web chat and `aginti queue <session-id> "..."` append messages to the inbox instead of trying to mutate the running process directly. The web API exposes `GET /api/sessions/:id/inbox`, `POST /api/sessions/:id/inbox`, `PATCH /api/sessions/:id/inbox/:itemId`, and `DELETE /api/sessions/:id/inbox/:itemId` so browser users can inspect, edit, or remove pending pipe messages before the runner consumes them. The runner drains the inbox at safe boundaries: before each model step and after tool execution. This mirrors the event-queue style used by mature agent UIs while keeping the backend decoupled from any specific frontend.
 
 The interactive CLI keeps the input panel visible while a run is working. Enter sends the current draft as an ASAP pipe message and displays it as `→`; the runner drains those messages before normal inbox items and before after-finish queued prompts. Tab stores the draft as an after-finish queue item and displays it as `↳`; those prompts run only after the current run completes. Alt+Up moves the last pending `→` message back into the editor, and Shift+Left moves the last pending `↳` message back into the editor. Idle Esc is ignored so it does not redraw the prompt into the transcript. During a run, Esc waits when `→` pipe messages are still pending and stops the run only when no ASAP pipe message is pending; Ctrl+C always stops. The current command cwd is rendered below the input panel in both idle and running states.

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/labcanvas-chatops-fallback.md

@@ -0,0 +1,46 @@
+# LabCanvas ChatOps Fallback
+
+AgInTiFlow is a reasoning and tool-supervision fallback for LabCanvas. LabCanvas remains the owner of chat transport, schedules, exact-source media resolution, durable task state, routine selection, artifact validation, and delivery.
+
+## Contract
+
+LabCanvas should pass one bounded task packet containing:
+
+- exact current request and source-chat identity;
+- latest same-chat interruptions and a small amount of attributed context;
+- one selected routine and its contract paths;
+- current deterministic preflight and stage state;
+- exact artifact directory and irreversible-action gates.
+
+AgInTi should read `AGENTS.md` and the selected routine contract, then call established commands. It should not invent a second scheduler, publication pipeline, media downloader, CAD generator, or delivery mechanism.
+
+The default provider chain is `deepseek,localllm`. Switching providers is safe only when the first provider failed before inference or tool execution. Never replay an unknown task failure or timeout on another provider because the first attempt may already have caused a side effect.
+
+## Evidence Scope
+
+ChatOps prompts may include a trusted single-line marker:
+
+```text
+AGINTI_EVIDENCE_SCOPE_JSON: {"mode":"chat-response","request":"Produce only the requested chat response."}
+```
+
+or:
+
+```text
+AGINTI_EVIDENCE_SCOPE_JSON: {"mode":"task","request":"Create the requested PDF from the supplied evidence."}
+```
+
+For `chat-response`, ordinary conversation and routing do not require file or command evidence. For `task`, evidence requirements are inferred only from the exact request, not from surrounding wrapper prose. Artifact requests still require real artifacts.
+
+## Local Context Recovery
+
+LocalLLM planning compacts oversized goals to a bounded head-and-tail representation. Runtime compaction retains the first request and latest interruptions. A `LocalContextBudgetError` triggers one compact-and-retry cycle at the same step and records private recovery events. It does not authorize replaying task side effects.
+
+Validate with:
+
+```bash
+npm run check
+npm run smoke:context-budget-recovery
+npm run smoke:truthful-completion
+```
+

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.