@lazyingart/agintiflow 0.20.199 → 0.20.201

package/.env.example

@@ -22,6 +22,8 @@ DEEPSEEK_API_KEY=
 OPENAI_API_KEY=
 AGINTI_ALLOW_HOSTED_IMAGE_PERCEPTION=false
 AGINTI_ALLOW_HOSTED_WEB_RESEARCH=false
+AGINTI_WEB_SEARCH_PROVIDER=auto
+# BRAVE_SEARCH_API_KEY=only_when_AGINTI_WEB_SEARCH_PROVIDER_is_brave
 AGINTI_ALLOW_HOSTED_JSON_SPECIALIST=false
 # A cross-provider writer needs both an explicit target and the permission below.
 AGINTI_WRITING_PROVIDER=

package/README.md

@@ -54,7 +54,7 @@ Most agent tools are either a chat box with hidden state or an expensive one-mod
 | Disciplined by default | `AGINTI.md` starts with a behavior contract: surface ambiguity, keep edits surgical, avoid speculative complexity, verify outcomes, and respect permission blockers. |
 | Role-based models | Route, main, spare, wrapper, and auxiliary image roles are separate. LocalLLM supplies the default fast/deep lanes; DeepSeek, OpenAI, OpenRouter, Qwen, and Venice are optional explicit routes. |
 | Writing without agent noise | `writing_specialist` drafts novels, books, scripts, essays, and paper prose in an isolated writing-only context on the active provider. Cross-provider writing requires explicit permission; ambient keys and model arguments cannot silently switch a LocalLLM session to a hosted model. The main agent then handles files, formatting, citations, checks, and artifacts. |
-| Visual and web evidence | `read_image` uses the loopback LocalLLM vision model in local sessions and never falls through to a hosted provider. `web_research` saves sourced snippet artifacts for local synthesis. OpenAI perception/research and wrapper second opinions require explicit provider/tool permission. |
+| Visual and web evidence | `read_image` keeps local pixels local. Fast search has provider fallback; exact page reads preserve hashes and metadata; `deep_research` adds resumable planning, parallel retrieval, exact-quote evidence, gap filling, synthesis, and citation auditing on the active provider. |
 | Scouts before big work | Parallel scouts can cheaply map architecture, tests, risks, symbols, and integration points before the main executor edits anything. |
 | SCS by default | Student-Committee-Supervisor mode adds a typed gate: committee drafts, student approves/monitors, supervisor executes. Use `/scs off` or `--no-scs` only when speed matters more than validation. |
 | AAPS for large workflows | AAPS describes top-down agentic pipeline scripts; AgInTiFlow can act as the interactive backend that validates, compiles, and executes those workflows. |
@@ -174,10 +174,18 @@ aginti --language de
 | Generate images | `/auxiliary image`, then ask for an image |
 | Read screenshots/images | `/image-read path/to/screenshot.png "what changed?"` |
 | Research with sources | `/web-research latest Android Gradle plugin official docs` |
+| Run deep research | `/deep-research standard compare current research-agent citation methods` |
 | Enable research wrapper | `/research-wrapper gpt-5.4-mini medium` |
 | Resume current project | `aginti resume` (`1` is newest/latest; Space shows more) |
 | Browse all sessions | `aginti resume --all-sessions` |
 | Queue into a running session | `aginti queue <session-id> "extra instruction"` |
+| Inspect durable goal revisions | `aginti sessions list` and `aginti sessions show <session-id>` |
+
+The runtime uses durable goal lifecycles, safe-boundary inbox interruption,
+progressive tool/context disclosure, bounded read batching, evidence-gated
+completion, and provider attribution. See
+[State-of-the-Art Agent Runtime](docs/state-of-the-art-agent-runtime.md) for the
+embedding and acceptance contract.
 | Clean empty sessions | `aginti --remove-empty-sessions` |
 | Check capabilities | `aginti capabilities`, `aginti doctor --capabilities` |
 | Sync reviewed skills | `aginti skillmesh status`, `aginti skillmesh sync` |
@@ -249,7 +257,7 @@ The website keeps the visual walkthrough in a carousel so this README can stay f
 | Writing specialist | A dedicated writing-only LLM call for prose, chapters, scripts, books, essays, research-paper sections, and revisions, with formatter handoff notes for Markdown/LaTeX/Final Draft. |
 | Patch workflow | Codex-style patch envelopes, unified diffs, exact replacements, hashes, compact diffs, and path guardrails. |
 | Parallel scouts | Optional scout calls for architecture, implementation, review, tests, git flow, research, symbol tracing, and dependency risk. |
-| Image reading and web research | LocalLLM sessions send pixels only to the loopback vision endpoint. `web_research` preserves source lists for the active model to synthesize. Hosted OpenAI and wrapper paths are explicit opt-ins, never credential-driven fallbacks. |
+| Image reading and web research | LocalLLM sessions keep pixels on the loopback vision endpoint. `web_search`, `read_web_page`, and `deep_research` provide fast discovery, exact source extraction, resumable evidence gathering, and claim-level citation audits. Hosted paths remain explicit opt-ins. |
 | SCS mode | Default Student-Committee-Supervisor quality gate with independent planning, execution, and validation roles. |
 | AAPS adapter | Optional `@lazyingart/aaps` integration for `.aaps` workflow init, validate, parse, compile, dry-run, and run commands. |
 | AgentLink | Local-first collaboration between AgInTi sessions through boards, typed messages, action contracts, safe summaries, and evidence bundles. |
@@ -397,6 +405,7 @@ More detail:
 - [docs/model-selection.md](docs/model-selection.md)
 - [docs/auxiliary-image-generation.md](docs/auxiliary-image-generation.md)
 - [docs/perception-and-web-research.md](docs/perception-and-web-research.md)
+- [docs/deep-research-engine.md](docs/deep-research-engine.md)
 - [docs/cli-i18n.md](docs/cli-i18n.md)
 - [docs/skillmesh.md](docs/skillmesh.md)
 
@@ -413,6 +422,7 @@ More detail:
 | Runtime modes and autonomy | [docs/runtime-modes-and-autonomy.md](docs/runtime-modes-and-autonomy.md) |
 | Skills and tools | [docs/skills-and-tools.md](docs/skills-and-tools.md) |
 | Image reading and web research | [docs/perception-and-web-research.md](docs/perception-and-web-research.md) |
+| Deep research engine | [docs/deep-research-engine.md](docs/deep-research-engine.md) |
 | Server-owned text-only fallback | [docs/safe-chat.md](docs/safe-chat.md) |
 | Skill Mesh | [docs/skillmesh.md](docs/skillmesh.md) |
 | Housekeeping logs | [docs/housekeeping.md](docs/housekeeping.md) |

package/docs/agent-runtime-pipe.md

@@ -34,6 +34,30 @@ 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.
 
+Embedding hosts can continue the same durable context without scraping terminal
+output:
+
+```bash
+printf '%s' 'Follow up using the existing evidence.' \
+  | aginti resume SESSION_ID --stdin --json
+```
+
+Machine resume emits the same single JSON object as `aginti run --json`, keeps
+the original session ID, restores the saved provider/model/tool/runtime policy,
+and never starts the web UI or writes interactive status lines. Explicit resume
+options may still patch durable runtime fields, but `--stdin` and `--json` are
+transport flags and are not persisted. This is the supported boundary for
+LabCanvas, chat bridges, schedulers, and other embedding hosts that need one
+isolated reusable agent session per conversation.
+
+The object includes `goalRevision` and `goalStatus`. A first request starts at
+revision 1. Every nonempty resume prompt advances the revision while retaining
+the bounded prior-goal ledger. Accepted completion marks that revision
+`completed`; a safe interruption or exhausted bounded run marks it `paused`;
+provider/runtime failure marks it `failed`. The next continuation reactivates
+the same session instead of replaying prior work. `aginti sessions show
+SESSION_ID` exposes both the revision history and lifecycle transitions.
+
 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.
 
 The web UI uses a related but browser-appropriate pattern. Enter sends and Shift+Enter adds a newline. `Pipe to run` writes an ASAP inbox item shared with CLI. `Queue after finish` keeps a browser-local next prompt and starts it after the current web-owned run finishes. Both lanes render in a pending panel with Edit and Remove buttons instead of terminal-only keybindings.

package/docs/deep-research-engine.md

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

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

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

package/docs/state-of-the-art-agent-runtime.md

@@ -0,0 +1,179 @@
+# State-of-the-Art Agent Runtime
+
+AgInTiFlow is designed as an embeddable agent runtime, not a prompt wrapper.
+Its main job is to preserve intent, evidence, and tool progress while providers,
+frontends, and long-running tasks change underneath it.
+
+This architecture draws on proven patterns from durable agent systems,
+including the append-only session and lifecycle ideas in
+[`deepseek-ai/deepseek-harness`](https://github.com/deepseek-ai/deepseek-harness),
+while retaining AgInTiFlow's provider-neutral tool and safety boundaries. The
+implementation is local and does not import that repository as a runtime
+dependency.
+
+## Runtime Invariants
+
+1. One logical conversation owns one durable session ID.
+2. A continuation resumes that session; it does not replay the task from the
+   beginning.
+3. The current user request is authoritative, but prior verified evidence and
+   unfinished requirements remain available.
+4. Tool side effects are accepted only through explicit, validated contracts.
+5. A final answer is successful only when its required evidence exists.
+6. Provider failure is not task success and is not silently converted into it.
+7. Provider handoff preserves the session and goal rather than duplicating
+   external work.
+
+## Durable Goal Contract
+
+Every session stores a versioned goal contract in `state.json`:
+
+- `revision`: advances for every resumed request;
+- `currentHash` and `currentPreview`: identify the authoritative request
+  without placing private raw prompts in operational indexes;
+- `history`: bounded revision history with previous-goal and plan hashes;
+- `status`: `active`, `completed`, `paused`, or `failed`;
+- `lifecycle`: bounded status transitions with reason and timestamp.
+
+Accepted direct answers, evidence-backed assistant answers, and `finish` tool
+calls mark the current revision completed. User interruption, step exhaustion,
+or a repairable tool-contract stop pauses it. Provider timeout, preflight
+failure, and unexpected runtime errors mark it failed. A new continuation
+reactivates the same session at the next revision.
+
+Inspect it without parsing terminal output:
+
+```bash
+aginti sessions list
+aginti sessions show SESSION_ID
+```
+
+Machine responses also expose `goalRevision` and `goalStatus`.
+
+## Append-Only Evidence And Atomic State
+
+The canonical session lives under
+`~/.agintiflow/sessions/<session-id>/`. Atomic `state.json` snapshots hold the
+resumable working state. Append-only JSONL events preserve lifecycle, tool,
+model, evidence, inbox, and recovery facts. A project-local index points to the
+canonical session without copying private history.
+
+Malformed state is treated as corruption, not as a missing session. Event
+appends are serialized, state saves are atomic and fsynced, and the SQLite
+session index uses WAL plus a bounded busy timeout for multiple frontends.
+
+## Safe Interruption And Inbox
+
+`aginti queue SESSION_ID "instruction"`, the CLI composer, and the web app all
+write to the same durable inbox. The runner consumes messages only at safe
+boundaries:
+
+- before a model step;
+- after a tool action;
+- before accepting completion.
+
+This permits an operator or chat bridge to correct, narrow, extend, or cancel
+the current direction without mutating an in-flight model request or replaying
+completed side effects. ASAP input and after-finish input remain distinct.
+
+## Progressive Context And Tool Disclosure
+
+The first model turn receives a focused runtime contract, the current goal,
+relevant project instructions, and only the skills selected for that request.
+It does not receive an indiscriminate dump of every skill or workspace file.
+
+Tool access is progressively disclosed:
+
+- direct chat can answer without tools;
+- unfamiliar repositories begin with bounded inspection and search;
+- relevant routines are preferred over rebuilding mature workflows;
+- a small batch of up to four independent read-only calls may run in one turn;
+- writes, GUI actions, network writes, and irreversible operations remain
+  isolated, ordered calls.
+
+Workspace search is bounded by file count, bytes, and elapsed time. Default
+root scans skip generated outputs, artifacts, and private data, while an
+explicit path remains inspectable when the user actually requested it.
+
+## Truthful Completion
+
+Completion is checked against an evidence scope. Read-only answers and plans do
+not need irrelevant command or visual evidence. File creation, publication,
+GUI work, and other external actions require the corresponding evidence.
+
+The runtime provides:
+
+- one bounded retry when a model claims completion without required evidence;
+- one bounded repair for an empty model answer;
+- a concise fallback only when runtime evidence already verifies completion;
+- a resumable stop instead of a false success when evidence remains absent;
+- short-circuiting after a blocked tool so later calls in that batch are not
+  dispatched against an invalid state.
+
+## Provider Attribution And Handoff
+
+`npm run eval:provider-attribution` compares a raw provider answer with the
+same provider through AgInTiFlow. Results are classified as:
+
+- `both_pass`: provider and orchestration both satisfy the contract;
+- `orchestration_loss_or_help`: the runtime changed the outcome, so inspect
+  prompting, context, tools, or completion gates;
+- `provider_limit`: the raw model itself failed the contract.
+
+This prevents orchestration bugs from being blamed on DeepSeek or a local
+model, and prevents weak model output from triggering unnecessary framework
+rewrites.
+
+Embedding hosts should use a provider chain while preserving the same AgInTi
+session. LabCanvas uses DeepSeek first and LocalLLM second. A handoff occurs
+only after a categorized provider failure and must not replay verified side
+effects. Codex and Claude remain explicit opt-in backends rather than hidden
+fallbacks.
+
+## Machine Host Protocol
+
+The supported subprocess boundary is:
+
+```bash
+printf '%s' 'Do the task.' | aginti run --stdin --json [runtime options]
+printf '%s' 'Continue with this correction.' \
+  | aginti resume SESSION_ID --stdin --json
+```
+
+Exactly one JSON object is emitted. It includes success/failure, session,
+provider, model, resume state, goal revision/status, result, stop state, and
+reason. Interactive banners, update checks, and web startup are suppressed.
+Stopped or failed runs always have `ok: false` even when they contain a useful
+human-facing explanation.
+
+## Established Routines, Not Reinvention
+
+AgInTiFlow is the reasoning and supervision layer. Domain work should use the
+existing routine owned by the relevant project:
+
+- LazyEdit and AutoPublish for subtitle-aware video publication;
+- LALACHAN/Xiaoyunque for story and video generation;
+- Musia for music and song-first MV workflows;
+- LabCanvas CAD, KiCad, Blender, TeX/PDF, presentation, grant, and figure
+  routines;
+- WeChat and WeCom transports for exact-chat delivery.
+
+The agent selects, invokes, monitors, and verifies those routines. It does not
+replace them with prompt-specific shell fragments.
+
+## Acceptance Gates
+
+A primary-backend release is accepted only after all of these pass:
+
+1. Syntax and deterministic runtime tests.
+2. Durable run/resume, goal lifecycle, inbox, and session-isolation tests.
+3. Progressive tool, bounded search, and truthful-completion tests.
+4. Raw-provider versus agent attribution for DeepSeek and LocalLLM.
+5. A live read-only established-routine task with no accidental write.
+6. A live exact artifact-creation task with byte-level verification.
+7. A live LocalLLM direct-response task.
+8. Host project tests, chat-bridge self-tests, package dry run, installed
+   version check, and existing-runtime restart.
+
+These gates keep the architecture fast for ordinary chat, capable for long
+tasks, and honest when a provider or external service is unavailable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.199",
+  "version": "0.20.201",
   "type": "module",
   "description": "AgInTiFlow is a project-aware agent workspace for hybrid wet-dry R&D, hardware-aware intelligence, software automation, and industrial workflows.",
   "license": "Apache-2.0",
@@ -92,6 +92,7 @@
     "scripts/smoke-model-roles.js",
     "scripts/smoke-platform.js",
     "scripts/smoke-perception-research.js",
+    "scripts/smoke-deep-research.js",
     "scripts/smoke-permission-modes.js",
     "scripts/smoke-public-research-wrapper.js",
     "scripts/smoke-safe-chat.js",
@@ -122,7 +123,7 @@
   "scripts": {
     "start": "node run.js",
     "web": "node web.js",
-    "check": "node --check run.js && node --check web.js && node --check bin/aginti-cli.js && node --check bin/aginti-public-research.js && node --check bin/aginti-safe-chat.js && node --check src/*.js && node --check src/mcp/*.js && node --check public/*.js && node --check scripts/postinstall-webapp.js && node --check scripts/seed-supervised-homework.js && node --check scripts/smoke-agentlink.js && node --check scripts/smoke-execution-policy.js && node --check scripts/smoke-math-rendering.js && node --check scripts/smoke-mcp.js && node --check scripts/smoke-public-research-wrapper.js && node --check scripts/smoke-runtime-core.js && node --check scripts/smoke-safe-chat.js && node --check scripts/smoke-web-ui.js && node --check scripts/smoke-scs-evidence-visibility.js && node --check scripts/fixtures/mcp-stdio-smoke-server.mjs",
+    "check": "node --check run.js && node --check web.js && node --check bin/aginti-cli.js && node --check bin/aginti-public-research.js && node --check bin/aginti-safe-chat.js && node --check src/*.js && node --check src/mcp/*.js && node --check public/*.js && node --check scripts/postinstall-webapp.js && node --check scripts/seed-supervised-homework.js && node --check scripts/eval-provider-attribution.js && node --check scripts/smoke-agentlink.js && node --check scripts/smoke-execution-policy.js && node --check scripts/smoke-math-rendering.js && node --check scripts/smoke-mcp.js && node --check scripts/smoke-public-research-wrapper.js && node --check scripts/smoke-runtime-core.js && node --check scripts/smoke-safe-chat.js && node --check scripts/smoke-web-ui.js && node --check scripts/smoke-scs-evidence-visibility.js && node --check scripts/fixtures/mcp-stdio-smoke-server.mjs",
     "setup:toolchain-docker": "scripts/setup-agent-toolchain-docker.sh",
     "smoke:coding-tools": "node scripts/smoke-coding-tools.js",
     "smoke:dynamic-step-budget": "node scripts/smoke-dynamic-step-budget.js",
@@ -154,6 +155,7 @@
     "smoke:model-roles": "node scripts/smoke-model-roles.js",
     "smoke:platform": "node scripts/smoke-platform.js",
     "smoke:perception-research": "node scripts/smoke-perception-research.js",
+    "smoke:deep-research": "node scripts/smoke-deep-research.js",
     "smoke:permission-modes": "node scripts/smoke-permission-modes.js",
     "smoke:public-research": "node scripts/smoke-public-research-wrapper.js",
     "smoke:safe-chat": "node scripts/smoke-safe-chat.js",
@@ -168,13 +170,14 @@
     "smoke:web-port-fallback": "node scripts/smoke-web-port-fallback.js",
     "smoke:autoupdate": "node scripts/smoke-auto-update.js",
     "eval:local-first-agent": "node scripts/local-first-agent-eval.mjs",
+    "eval:provider-attribution": "node scripts/eval-provider-attribution.js",
     "real:deepseek": "node scripts/real-deepseek-capabilities.js",
     "postinstall": "node scripts/postinstall-webapp.js",
     "supervision:seed": "node scripts/seed-supervised-homework.js",
     "storage:migrate": "node bin/aginti-cli.js storage migrate",
     "publish:env": "node scripts/npm-publish-from-env.js publish --access public",
     "publish:env:whoami": "node scripts/npm-publish-from-env.js whoami",
-    "test": "npm run check && npm run smoke:localllm-provider && npm run smoke:localllm-model-tiers && npm run smoke:localllm-auto-max && npm run smoke:local-resource-policy && npm run smoke:context-budget-recovery && npm run smoke:session-runtime && npm run smoke:runtime-core && npm run smoke:progressive-tools && npm run smoke:truthful-completion && npm run smoke:writing-specialist-routing && npm run eval:local-first-agent && npm run smoke:runtime-compat && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:math-rendering && npm run smoke:web-ui && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:execution-policy && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:public-research && npm run smoke:safe-chat && npm run smoke:auth && npm run smoke:agentlink && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:mcp && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:tmux-tools && npm run smoke:long-jobs && npm run smoke:run-stdin && npm run smoke:cli-chat && npm run smoke:inbox",
+    "test": "npm run check && npm run smoke:localllm-provider && npm run smoke:localllm-model-tiers && npm run smoke:localllm-auto-max && npm run smoke:local-resource-policy && npm run smoke:context-budget-recovery && npm run smoke:session-runtime && npm run smoke:runtime-core && npm run smoke:progressive-tools && npm run smoke:truthful-completion && npm run smoke:writing-specialist-routing && npm run eval:local-first-agent && npm run eval:provider-attribution && npm run smoke:runtime-compat && npm run smoke:autoupdate && npm run smoke:web-api && npm run smoke:math-rendering && npm run smoke:web-ui && npm run smoke:web-autostart && npm run smoke:webapp-command && npm run smoke:web-port-fallback && npm run smoke:docker-command && npm run smoke:coding-tools && npm run smoke:dynamic-step-budget && npm run smoke:execution-policy && npm run smoke:aaps-adapter && npm run smoke:auxiliary-tools && npm run smoke:perception-research && npm run smoke:deep-research && npm run smoke:public-research && npm run smoke:safe-chat && npm run smoke:auth && npm run smoke:agentlink && npm run smoke:canvas-artifacts && npm run smoke:capabilities && npm run smoke:mcp && npm run smoke:model-roles && npm run smoke:platform && npm run smoke:permission-modes && npm run smoke:skills && npm run smoke:skillmesh && npm run smoke:tmux-tools && npm run smoke:long-jobs && npm run smoke:run-stdin && npm run smoke:cli-chat && npm run smoke:inbox",
     "pack:dry-run": "npm pack --dry-run",
     "smoke:capabilities": "node scripts/smoke-capabilities.js"
   },

package/scripts/smoke-cli-chat.js

@@ -918,6 +918,23 @@ try {
   ) {
     throw new Error("resume subcommand options after the session id should remain options, not prompt text");
   }
+  const machineResume = parseResumeCommandArgs([
+    "web-agent-smoke",
+    "--stdin",
+    "--json",
+    "--provider",
+    "mock",
+  ]);
+  if (
+    machineResume.sessionId !== "web-agent-smoke" ||
+    !machineResume.stdin ||
+    !machineResume.json ||
+    machineResume.optionArgv.includes("--stdin") ||
+    machineResume.optionArgv.includes("--json") ||
+    parseArgs(machineResume.optionArgv).provider !== "mock"
+  ) {
+    throw new Error("resume machine transport flags should be parsed outside the durable runtime patch");
+  }
   const resumeRuntimeOptions = [
     "--provider",
     "mock",