@lazyingart/agintiflow 0.20.336-integration.2 → 0.20.337-integration.0

package/aginti-work-examples/README.md

@@ -0,0 +1,22 @@
+# AgInTiFlow Work Examples
+
+This directory records supervised AgInTiFlow homework runs. It is not a generic demo gallery; each entry should include evidence that AgInTiFlow actually completed the task.
+
+## Rule
+
+Do not record a task as complete only because the agent said it was complete. Each example needs durable proof such as:
+
+- source files or commits,
+- build/test logs,
+- screenshots or PDFs,
+- session id and tmux session name,
+- artifact paths that still exist,
+- notes about flaws found and AgInTiFlow upgrades made.
+
+## Current Examples
+
+| Example | Profile | Status | Evidence |
+| --- | --- | --- | --- |
+| `android-tipsplit` | `android` + `auto` capability hardening | Verified | Android app built/tested/installed/launched; durable screenshot copied here |
+
+Future runs should add a subfolder per task, plus a row in `homework-ledger.md`.

package/aginti-work-examples/deepseek-cli-fallback-20261001.md

@@ -0,0 +1,73 @@
+# DeepSeek CLI fallback acceptance — 2026-10-01
+
+## Scope
+
+Improve everyday CLI work without a Codex wrapper: inspect files, create a
+summary, repair a small project, run real tests, and continue the same session.
+AgInTi performed all target-workspace edits through DeepSeek. The supervising
+agent changed AgInTi itself, supplied synthetic fixtures and ordinary requests,
+and independently checked outputs. No user's project was used as a test fixture.
+
+The installed baseline was `0.20.331`. Development started from `486c56c`, which
+already contained the undeployed request-lifecycle and read-only-input fixes on
+top of integration `bf9c3e0`. The new release is `0.20.337-integration.0`, an opt-in
+integration release rather than a promotion of the npm `latest` channel.
+
+## Failures were reproduced, not inferred
+
+| Observation | Evidence | Repair or conclusion |
+| --- | --- | --- |
+| Baseline summary request temporarily changed `risks.txt` | Live Flash tool events showed an unwanted patch, a compensating restoration, and then the output; 8 model turns / 14 seconds | Deploy the existing source/output contract repair. The same request took 4 turns / 6 seconds and never edited either source. Timings are individual observations, not a benchmark. |
+| Fast/manual selection silently ran Main | Offline config reproduced Flash becoming Pro, and an explicit DeepSeek manual model becoming a separately configured OpenAI main model | Keep the selected executor while retaining SCS planning and completion validation. |
+| Could enable wrappers but could not explicitly disable them on resume | `--no-wrappers` was rejected; a stored true value had no matching negative CLI patch | Add symmetric parsing and durable resume support, including an ambient-true regression. |
+| Retry could outlive its deadline | Earlier deterministic reproduction and eight lifecycle regressions | Include the previous cancellation/deadline repair; do not claim provider token generation became faster. |
+| Final read-only discovery stopped an otherwise fixed task | A real `find` pipeline omitted `-maxdepth`; the CLI paused asking for broad host permission | Keep the command blocked but classify it as recoverable discovery. Preserve denial through pipelines/sequences. The same session continued and completed with unchanged permissions. |
+| Optional inline JavaScript stopped a second restricted-host run | A compound `npm test; node -e ...` command was not admitted | Keep that host restriction. Describe host tool limits to the model and recommend Normal Docker workspace for general coding. Do not expand arbitrary host execution just to make a test pass. |
+| The prompt itself encouraged unrelated cache searches | Engineering guidance suggested unbounded Python-cache discovery irrespective of stack | Use relevant-stack, bounded inspection and scoped claims; no unrelated cleanup requirement. |
+
+The first Pro code fix passed its supplied tests, but an independent `10.075`
+rounding example failed. A normal follow-up in the same session produced a
+decimal-string repair and a new regression, passing the independent check. This
+is useful evidence of resumability, and also a reminder that passing supplied
+tests alone does not establish complete correctness. No money-specific patch was
+added to AgInTi core.
+
+## Verification
+
+- Full existing `npm test`: passed, with live provider-attribution probing off.
+  Existing occupied-port skips in document-worker checks remain skips, not passes
+  for those external services.
+- Eight request-lifecycle regressions passed.
+- Five new CLI routing/wrapper/discovery tests passed; the routing and discovery
+  reproductions failed before their repairs.
+- Coding-tool policy, model-role, syntax, and CLI checks cover the changed paths.
+- A denied discovery command is still denied. Mutating find actions, shell
+  execution, redirection, and destructive commands are not admitted by the repair.
+- Live evaluator: `scripts/eval-deepseek-cli.mjs`. It retains each failed attempt
+  rather than overwriting it with a later pass. Its default follows the shipped
+  Normal Docker workspace; `AGINTIFLOW_EVAL_SANDBOX=host` exercises restricted host
+  behavior. A failed case exits nonzero.
+
+Synthetic prompts, model results, events, independent test logs, and original
+input hashes remain in a private acceptance directory. Credentials and raw
+session history are not part of this public record or npm package.
+
+The final fresh-workspace run passed all three cases with the Flash executor:
+
+| Case | Model turns | Wall time | Independent result |
+| --- | ---: | ---: | --- |
+| Read two sources and write a summary | 5 | 9.1 s | Both sources unchanged; summary names both sources |
+| Repair invoice utility and add regression coverage | 15 | 107.7 s | Project tests and 22 external oracle assertions passed |
+| Resume for Chinese README instructions | 7 more | 17.3 s | Same session, next goal revision, implementation/tests byte-identical; tests and oracle still passed |
+
+This is one successful run after the documented failures, not a success-rate or
+speed claim. Model calls, planning, validation, and tool use all contribute to
+wall time. No external Codex/Claude/Gemini agent wrapper was called. The existing
+Docker image was reused; no GPU model, GUI desktop, or dependency rebuild was
+needed. The test-created containers exited after each command.
+
+## Usage
+
+See [DeepSeek CLI fallback](../docs/deepseek-cli-fallback.md) for start/resume,
+permissions, model selection, and reproducible checks. No task is automatically
+moved out of Codex when quota expires, and no Codex history is rewritten.

package/bin/aginti-execution-worker.js

@@ -6,6 +6,11 @@ import {
 } from "../src/execution-worker-server.js";
 
 try {
+  if (Number.parseInt(process.versions.node, 10) < 22) {
+    throw Object.assign(new Error("The execution worker requires Node 22 or later."), {
+      code: "EXECUTION_WORKER_NODE_UNSUPPORTED",
+    });
+  }
   const config = await loadExecutionWorkerServerConfig();
   const runtime = await createProductionExecutionWorkerServer({ config });
   installExecutionWorkerShutdownHandlers(runtime.server);

package/docs/deepseek-cli-fallback.md

@@ -0,0 +1,134 @@
+# DeepSeek as a practical CLI fallback
+
+Use AgInTiFlow for small coding, documentation, and workspace tasks when Codex is
+unavailable. It runs its own tool loop with DeepSeek API credentials; a Codex
+subscription or a working Codex CLI is not required. DeepSeek API usage has its
+own billing and availability.
+
+## Start in the project you want to work on
+
+Configure credentials once if needed:
+
+```bash
+aginti auth deepseek
+```
+
+From the project's terminal:
+
+```bash
+aginti --provider deepseek --routing fast --no-wrappers
+```
+
+Type an ordinary request, such as “Fix the failing tests and explain the change.”
+The default Normal permission mode allows project edits and uses the Docker
+workspace. It does not grant unrestricted host access. To use installed host
+tools for a small, trusted project while keeping the existing command policy:
+
+```bash
+aginti --provider deepseek --routing fast --no-wrappers --sandbox-mode host
+```
+
+Host mode is not an OS sandbox. Commands still run as your user. Keep the project
+scope narrow; use the Docker workspace when isolation is important. There is no
+need to switch to Danger mode merely to read files, make patches, or run ordinary
+tests. Arbitrary inline interpreter snippets can still stop in restricted host
+mode; the normal Docker workspace is recommended for general coding. New
+processes pick up an installed upgrade; no desktop reboot is needed.
+
+One task, followed by a resumable exit:
+
+```bash
+aginti run --provider deepseek --routing fast --no-wrappers \
+  "Read notes.txt and risks.txt. Write summary.md. Leave the inputs unchanged."
+```
+
+Resume from the same project:
+
+```bash
+aginti resume
+aginti resume latest --no-wrappers
+aginti resume SESSION_ID --no-wrappers "Continue and run the tests."
+```
+
+AgInTi sessions and Codex sessions are separate. These commands resume AgInTi
+history; they do not load a Codex JSONL file. For a quota handoff, leave a short
+project note with the current task, files changed, checks already run, and next
+step, then ask AgInTi to read it. Do not include account tokens or private keys.
+
+To change a saved AgInTi session explicitly to DeepSeek Flash:
+
+```bash
+aginti resume SESSION_ID --provider deepseek --model deepseek-v4-flash \
+  --routing manual --route-provider deepseek --route-model deepseek-v4-flash \
+  --main-provider deepseek --main-model deepseek-v4-pro \
+  --spare-provider deepseek --spare-model deepseek-v4-pro --no-wrappers
+```
+
+Ordinary resume preserves saved runtime choices. An ambient environment change
+does not silently switch the saved account/provider/model. `--no-wrappers`
+explicitly disables Codex/Claude/Gemini-style external agent wrappers, including
+when a saved session or environment previously enabled them. It does not disable
+all shell commands or all separately configured external tools.
+
+## Model control and limits
+
+- `--routing fast` keeps the fast executor, currently DeepSeek v4 Flash.
+- `--routing manual --model MODEL` keeps that executor model.
+- `--routing smart` retains automatic task routing and can choose Pro.
+- Planning and completion validation remain active when the task requires them.
+  Their separately configured model roles may use Pro even with a Flash executor;
+  Fast does not mean every auxiliary request uses Flash.
+- Default local-first routing is unchanged. The commands above explicitly choose
+  DeepSeek, rather than silently switching an existing local session to a cloud API.
+- Review the diff and test results. A successful sample is not a promise of Codex
+  parity, error-free code, or completion of every task without follow-up.
+
+## Repairs in 0.20.337-integration.0
+
+This integration build includes two earlier, previously undeployed fixes:
+
+1. The model compatibility retry shares the original deadline and cancellation
+   boundary. A stuck retry cannot keep AgInTi waiting beyond its deadline or
+   turn cancellation into a late success.
+2. Reading input files to create a separate output no longer forces mutations
+   to those inputs. Positive source-edit requests still require real edits.
+
+It also adds:
+
+3. Fast/manual executor selection is preserved when SCS planning and evidence
+   validation activate. Previously these modes could silently run the main model,
+   including a separately configured provider.
+4. `--no-wrappers` works for a new run and as a persistent resume patch. Explicit
+   `--allow-wrappers` can still re-enable them.
+5. Syntactically read-only `find` without a depth bound remains **blocked**, but
+   returns a recoverable discovery error. The agent can choose structured file
+   tools or add a bounded `-maxdepth`, without asking for destructive permission.
+   That denial survives pipelines and command sequences. `-delete`, `-exec`,
+   file output, unknown shell segments, and other writes remain under the existing
+   stronger policies. No permission is silently granted and no denied command runs.
+
+## Reproduce the live acceptance check
+
+This is opt-in, spends DeepSeek credits, and creates a new synthetic workspace.
+It does not point the agent at your current project's source files.
+
+```bash
+AGINTIFLOW_REAL_DEEPSEEK=1 npm run eval:deepseek-cli
+```
+
+Optional: set `AGINTIFLOW_EVAL_ROOT` to a directory for retained private evidence,
+or `AGINTIFLOW_EVAL_CLI` to an installed `bin/aginti-cli.js` to verify that package.
+The default evaluation location is a fresh temporary directory. The evaluator
+uses the default Normal Docker workspace; set `AGINTIFLOW_EVAL_SANDBOX=host` to
+test the more restricted host policy instead. That is a distinct acceptance
+configuration, and a blocked host run is not counted as a pass.
+
+The evaluator checks a two-source summary, a small code repair with real tests,
+and a Chinese README follow-up in the same session. Independent checks compare
+input files, run tests again, exercise an external decimal-rounding oracle, verify
+unchanged implementation/tests during the documentation follow-up, and inspect
+actual model/tool events. Model summaries alone do not establish a pass. A failed
+case produces a nonzero exit and a retained report; it is not relabeled successful.
+
+See [the dated acceptance record](../aginti-work-examples/deepseek-cli-fallback-20261001.md)
+for measured outcomes, failures encountered, and release/install details.

package/docs/general-agent-backend-research-2026-09-27.md

@@ -0,0 +1,213 @@
+# General Agent Backend Research
+
+Date: 2026-09-27. This is a source-based assessment plus an offline runtime
+repair, not a production deployment or a live model-quality benchmark.
+
+## Baseline and Scope
+
+- AgInTiFlow: `bf9c3e0386f86502246e776d25dcf29d43d89216`,
+  `integration/deepseek-analysis-20260910`, `0.20.336-integration.4`.
+- Implementation branch: `fix/provider-request-lifecycle-20260927`, in
+  `AgInTiFlow-worktrees/AgInTiFlow-runtime-responsiveness`.
+- AgenticApp reference HEAD: `7465ec7eece9ef92111ab28284fd7d54c2b2c8be`.
+  Its current source and handoffs were read; its unrelated dirty work was preserved.
+- EchoMind reference HEAD: `190aeb3325dec6f5d31c56be80ed4f0b35d86f13`.
+  Its provider factory, conversation, voice, and single-flight code were read.
+- No private conversation bodies, credentials, or model weights were required.
+  No application services, GPU jobs, provider defaults, or public routes were changed.
+
+The existing SQLite campaign was opened read-only. It contains 69 capability
+rows (6 passed, 63 passed-after-fix) and 114 test rows (8 passed, 104
+passed-after-fix, 2 historical failures). Its latest recorded scenarios use
+0.20.331-era versions. This is substantial regression evidence, but does not
+establish current integration performance or universal task coverage. The
+new request-lifecycle regression is separate evidence, not a rewritten old pass.
+
+## What Already Works Architecturally
+
+AgenticApp's `src/agenticapp/workspace_agent.py::run_aginti_turn` locks its
+conversation registry, selects a persistent AgInTi session, and invokes the
+machine CLI. `_run_aginti_provider_chain` preserves that session when changing
+provider. `_parse_aginti_machine_result` treats stopped, failed, or unresolved
+tool-protocol output as failure. The host registers actual artifact files;
+an assistant mentioning a file is insufficient.
+
+Its `references/aginti-primary-labcanvas-agent-handoff-2026-08-18.md` explicitly
+assigns mature domain routines to their owning applications. This is the right
+general boundary: AgInTi interprets, chooses tools, retains execution context,
+and verifies completion. Applications own account policy, domain APIs, delivery,
+and authorization of irreversible actions. Their chat names, schedules, and
+private transport details should not enter AgInTi's core.
+
+AgInTi already has mechanisms worth retaining:
+
+| Need | Existing implementation | Validation used in this slice |
+| --- | --- | --- |
+| Provider handoff without restarting the task | `src/provider-handoff.js`, `src/agent-runner.js` | `smoke:provider-handoff` |
+| Provider-aware context budgets | `src/context-budget-controller.js` | `smoke:context-budget-recovery` |
+| Bounded tool disclosure and convergence | `src/progressive-tool-selection.js` | `eval:local-first-agent` |
+| Persistent session, inbox, and crash replay | `src/session-store.js`, `src/session-runtime.js` | `smoke:session-runtime`, `smoke:runtime-core`, `smoke:inbox` |
+| Evidence-backed completion | `src/scs-evidence.js`, `src/agent-runner.js` | `smoke:truthful-completion` |
+| Scoped research, computation, documents, and artifacts | `src/integration-analysis-planner.js`, `src/integration-analysis-session-service.js` | `smoke:integration-analysis-planner` |
+| Server-owned public authority | `src/integration-api.js`, `src/integration-auth.js`, `src/integration-policy.js` | Retain existing readiness and ownership gates |
+
+The public analysis planner and the broad workspace runtime have different tool
+surfaces. EchoMind must consume the declared public capability surface; it must
+not assume that a CLI tool available on a developer workstation is a public
+application capability.
+
+## Upstream Comparison
+
+Existing clean reference checkouts were updated with fast-forward-only pulls,
+with Git hooks and recursive submodule updates disabled. No upstream code was
+copied into AgInTi and no upstream dependency installation was performed.
+
+| Reference | Inspected revision | Relevant source and lesson |
+| --- | --- | --- |
+| OpenAI Codex | `41f9084b30812db321a0b592def4f500d1e79cf4` | `codex-rs/core/src/client.rs`, cancellation tokens and consumer-drop handling; `codex-rs/history/src/compaction_checkpoint.rs`, durable context boundaries |
+| Claude Code | `7779afb12e3635f46f56ec823979d68350ae000b` | Public plugins and hook examples only; this checkout is not evidence of its proprietary runtime implementation |
+| Gemini CLI | `2fe7c2d3f065dc40ad573d50b2091116f8a4aa18` | `packages/core/src/utils/retry.ts`, abort-aware retries; `packages/core/src/telemetry/`, stage-specific observations |
+| Qwen Code | `36710ff6908c96a4b95db59c2f46c2b49278d02e` | `packages/core/src/utils/retry.ts`, cancellable delay and explicit retry policy |
+| GitHub Copilot SDK | `d106d29dc6c5112da2abdae59008571b6692f12b` | `nodejs/src/session.ts::awaitWorkflowOperation`, guard before dispatch and abort race; `docs/features/session-persistence.md`, explicit session lifecycle |
+| DeepSeek Harness | `99f6f02fecdb7dff40c3fbc9470f5907c29f74ca` | Pull timed out twice; existing `docs/agent-lifecycle.zh.md` describes durable session events separately from live coordination. This is a dated reference, not a verified current upstream snapshot. |
+
+The reusable lesson is explicit lifecycle control, not more agents per task.
+Anthropic's [context-engineering guidance](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
+supports selective retrieval, small clear tool surfaces, and preserving important
+state during compaction. AgInTi already implements parts of this; improve their
+measured behavior before adding more prompts or parallel workers.
+
+[Gemini's telemetry documentation](https://geminicli.com/docs/cli/telemetry/)
+provides a useful reference for separating model, tool, and agent observations.
+Apply that idea with private-content logging disabled, rather than copying a
+telemetry service or transmitting user data.
+
+## Reproduced Defect and Implemented Repair
+
+`src/model-client.js::createChatCompletion` bounded the first SDK call using
+`Promise.race`, but awaited its unsupported-`reasoning_effort` compatibility
+retry directly. The deadline still aborted a signal, yet the caller could remain
+waiting and accept a late success. Caller cancellation similarly depended on
+the client settling itself, rather than ending AgInTi's wait.
+
+Before editing, a controlled client reproduced a retry still pending 80 ms after
+a 25 ms deadline and then returning success. Eight deterministic tests were
+added; six failed on the original source. A real OpenAI SDK instance with an
+offline fetch implementation also reproduced the problem when the compatibility
+retry entered a 429 Retry-After backoff. No provider request was transmitted.
+
+The repair uses one shared deadline and cancellation outcome for both attempts:
+
+- Already-cancelled work makes zero client calls.
+- Caller cancellation ends the wait and sends abort to the transport.
+- Both attempts share the original deadline; retry does not restart the clock.
+- Late resolution cannot replace cancellation or timeout with success.
+- Cancellation cannot trigger another compatibility attempt.
+- Timers and parent listeners are removed after completion or failure.
+- The optional compatibility retry, normal payloads, and provider-error metadata
+  remain intact. Existing timeout classification can still drive permitted
+  same-session handoff.
+
+This improves a demonstrated waiting failure. It does not make the underlying
+model generate tokens faster, guarantee a remote provider stopped computing,
+or eliminate an SDK-owned backoff timer. The latter is drained in the regression
+and cannot issue another fetch after abort. It also does not change the separate
+public analysis planner's own model-request lifecycle.
+
+## Smallest EchoMind Integration
+
+The inspected EchoMind `EchoMind/echomind/ai_client_factory.py` and
+`mixed_ai_request.py` create provider clients. `voice_processor.py::get_ai_response`
+uses schema-constrained responses, conversation context, and single-flight
+deduplication; `process_audio` calls it through an executor. This is not yet a
+durable AgInTi task interface, and replacing a provider URL cannot provide one.
+
+Recommended boundary for a subsequent, separately tested integration:
+
+```mermaid
+flowchart LR
+  UI[EchoMind chat or voice] --> BFF[Authenticated EchoMind backend]
+  BFF --> API[AgInTi versioned session and run API]
+  API --> Runtime[AgInTi policy, context, tools, evidence]
+  Runtime --> Workers[Admitted execution and artifact workers]
+  Runtime --> Models[Explicit permitted provider routes]
+  API --> Events[Durable public events and verified artifacts]
+  Events --> BFF
+```
+
+Bind each user/conversation to an owned thread, preserve the same run/session
+through reconnect and permitted provider handoff, and use mutation idempotency.
+Use persisted run events for progress and replay. A stop request should cancel
+the scoped run; a disconnected phone should not create a second task. Keep
+speech recognition, TTS, language settings, notifications, and social features
+in EchoMind. Add capabilities incrementally: text-only inference, source-backed
+research, then admitted file/computation work.
+
+`safe-chat` is a bounded stateless response service, not a substitute for this
+session API. Its prose documentation predates the provider-general code, so
+effective source configuration and capability probes must take precedence over
+old DeepSeek-only examples. No EchoMind wiring or deployment was attempted here.
+
+## Prioritized Next Work
+
+1. **Measure latency without prompts in telemetry.** Correlate queue admission,
+   readiness, model attempts, retries, tools, validation, and terminal commit.
+   Existing `model.requested` events do not by themselves describe every SDK
+   attempt or first-token delay. Track p50/p95, request/tool counts, and repair
+   count per task class before claiming speed improvements.
+2. **Turn routine reuse into explicit capability contracts.** Reuse the existing
+   skill/profile/tool mechanisms. Domain owners provide bounded inputs, scope,
+   side-effect class, cancellation, output manifest, and verifier. The runtime
+   should not rediscover an entire repository after receiving an authoritative
+   routine that already answers the request.
+3. **Test the application adapter under real lifecycle failures.** Phone
+   reconnect, duplicate submit, cancellation, provider outage, worker restart,
+   ownership conflicts, and response loss must preserve one durable task and
+   verified outputs. Never replay a side-effecting tool turn as a fresh prompt.
+4. **Make perceived progress honest.** Expose stage and verified tool progress
+   early. If draft text is streamed later, mark it provisional and retain the
+   existing evidence gates before accepting a final answer or artifact.
+5. **Expand measured coverage, not permissions.** Reuse narrow application
+   routines for CAD, media, research, and documents. Unsupported host actions
+   should remain explicit capability limits. Worker readiness and optional-role
+   degradation must remain truthful.
+
+Suggested acceptance prompts are ordinary, imperfect requests: summarize notes
+without writing files; correct a prior answer in the same thread; inspect an
+already-specified read-only routine; research a topic using both official web
+and paper sources; calculate a result and create exactly the requested files;
+cancel while a provider is retrying; reconnect after artifact commit without
+repeating the work. Verify files and durable state from outside the agent.
+
+No current live DeepSeek/LocalLLM latency or quality claim is made. Broad
+production readiness still requires these app-level canaries and configured
+capability proofs. A passing offline regression is evidence for its exact
+contract, not a claim that all repositories or tasks now work perfectly.
+
+## Validation Record
+
+- `node --test test/model-request-lifecycle.test.js`: 8 passed. Before the
+  repair, the same file produced 6 failures and 2 passes.
+- `npm run smoke:model-roles`: passed, including the new regression file.
+- `npm run smoke:provider-handoff`: passed with persisted mock-provider runs.
+- Separate focused passes: `smoke:local-failure-recovery`,
+  `smoke:context-budget-recovery`, `smoke:session-runtime`, `smoke:runtime-core`,
+  `smoke:inbox`, `smoke:truthful-completion`, and
+  `smoke:integration-analysis-planner`.
+- `npm run eval:local-first-agent`: 18 passed, 0 failed, 0 skipped;
+  its offline guard observed zero network attempts.
+- `npm run check`: 300 JavaScript files passed. The new test file also passed
+  its explicit `node --check`.
+- `AGINTIFLOW_PROVIDER_ATTRIBUTION_LIVE=0 npm test`: exit 0, including pretest.
+  The document-worker-server and document-worker-cross-boundary scripts
+  reported occupied-port skips for `127.0.0.1:18102`; its existing listener was
+  left untouched. These two HTTP checks are not claimed as executed passes.
+- Dry-run npm packaging includes the new regression and excludes private
+  session, credential, database, and dependency paths in the inspected file list.
+- `git diff --check`: passed.
+
+Tests reused the baseline dependency installation through a temporary symlink;
+no dependencies were installed or upgraded. Only task-owned smoke autostart
+servers were stopped during cleanup. Package version remains
+`0.20.336-integration.4`; no release, deployment, installed-package change, or
+EchoMind/AgenticApp source change was performed.

package/docs/integration-deep-research.md

@@ -4,6 +4,131 @@ The durable analysis API promotes only explicit deep-research instructions such
 
 An eligible run uses the private LazyEdge-bound LocalLLM task protocol at the exact `create`, `status`, and `cancel` routes. AgInTi fixes the model alias, limits the depth to `quick`, `standard`, or `deep`, polls one stable task identity, cancels incomplete work on abort, and accepts only bounded no-cache responses. Exact domain, DOI, arXiv, and image-grounded requests retain the stricter one-shot Search path instead of weakening their constraints.
 
-The completed report is accepted only with at least one safe source and valid one-based citations. Every source is preserved in one authority-bound `sources` artifact. A pure research request returns that validated report directly; a combined document, file, or execution request carries it forward as untrusted evidence for the remaining agent work.
+Ranked deep research uses the same optional, tool-free topic selection as quick
+Search: at most six verbatim fragments of the current request, persisted before
+dispatch and reused on resume. Topic/filters stay separate from later calculation,
+coding or file-creation actions. The selected query is the actual upstream task
+question, not only an artifact label; a short subject uses the service-owned
+prefix `Research on` to meet the existing question-length contract. Invalid
+selection keeps the original bounded query. No private history is provided to
+the selector, and exact identifier/domain constraints retain their authority.
+The original request still governs all remaining execution and output work.
+
+The completed report is accepted only with at least one safe source and valid one-based citations. Every source is preserved in one authority-bound `sources` artifact. A pure research request returns a successful validated report directly; a combined document, file, or execution request carries it forward as untrusted evidence for the remaining agent work.
+
+If the upstream service explicitly declares its terminal result an evidence
+inventory, AgInTi makes one optional synthesis attempt with the selected model.
+It receives only the current public research question and validated source
+titles/snippets, with no previous conversation, tools, raw pages or credentials.
+The synthesis prompt explicitly takes answer language from the original current
+question or its requested language, never from source language or JSON examples.
+There is no extra search, model escalation or repair loop. A successful report
+is never rewritten, and an inventory with no usable snippets costs no model call.
+
+The recovery reply uses a small JSON claim/evidence schema. Every finding must
+cite a current source with a verbatim supporting snippet excerpt; indices,
+quote containment, output size and plain-text presentation are checked before
+the application renders citation markers. The result is explicitly labeled a
+retrieved-evidence summary, not a full-paper review. These are provenance and
+structure checks, not entailment verification. Source text stays untrusted.
+Model quota, timeout, malformed/truncated output, context overflow, or rejected
+evidence leaves the original inventory and all source cards intact; cancellation
+still cancels the run. Compound tasks retain the accepted summary alongside
+their separately verified results. Other providers and shared LocalLLM services
+keep their configured defaults.
+
+Coordinated computation requests use the same action matcher as standalone
+requests. For example, research followed by “Then use Python to calculate…”
+retains an execution obligation, including after earlier conversation. Quoted,
+historical, explanatory and negated clauses remain non-executing. The research
+report cannot finalize such a compound run before the requested execution.
+
+Research depth comes from a modifier immediately before the research directive:
+“quick deep research” is quick, whereas research about short sequences or
+standard algorithms remains deep. Multiline chat whitespace is normalized when
+deriving the one-line provider query; other control characters, length bounds,
+exact identifiers and source/domain constraints retain their existing checks.
+
+Completed compound requests preserve the validated research report as a distinct
+part of the final answer, followed by the remaining task results. The report is
+not disposable synthesis context: numeric/citation repair and tight-context
+fallbacks retain both research and verified execution output. A calculation-only
+summary needs no artificial research citation; any supplied citation must still
+refer to a current source, and evidence-denial/numeric checks remain enforced.
+This uses the existing final-response and durable callback contract, with no
+extra model call or new artifact kind. The report remains untrusted text, never
+tool authorization, and is scoped to this run only.
+
+The existing bounded chat response reserves space for both result sections and
+capability notices. If a section exceeds its allocation, the UTF-8-safe excerpt
+is explicitly marked as shortened. This is a chat presentation, not a promise
+of full-length document retention or proof that every research claim is correct.
+Long-form document delivery and source-relevance qualification remain separate.
+
+Artifact privacy checks distinguish standalone slash operators followed only by
+sentence punctuation from actual path-like tokens. Public mathematical prose
+such as an operator list may contain the former. Unix paths with filename text,
+file URLs, Windows drive paths and UNC paths retain their existing treatment;
+this lexical correction does not authorize filesystem access or expose a path.
 
 Search/research intent, task activity, artifacts, failures, and terminal state use the same durable session ledger as other Agent work. The next message in the thread does not inherit stale research authority or completed activity. Public capabilities advertise the optional `localllm/research-task/v2` protocol while retaining the original Search contract for older Web clients.
+
+## Explicit application search policy
+
+Applications that send private conversation history can set
+`input.searchInference: false` on `runs/start` or an input-bearing `runs/resume`.
+This prevents text (including quoted historical requests) from implicitly
+enabling grounded search or deep research. Omission or `true` retains the
+existing natural-language inference behavior. Only boolean values are accepted.
+
+An explicit `input.search: {mode: "web" | "papers" | "both", limit: 1..20}`
+still selects bounded search when inference is off. The application should
+provide its separately authorized public query in that phase, rather than
+forwarding private history to a search tool.
+
+The disabled-inference choice is persisted and bound to the run's authority
+snapshot. An input-less resume preserves it across restart/retry. A new input
+selects its own policy, so a subsequent normal request is not accidentally
+restricted by an older private phase. This is tool-routing policy; the hosted
+model still receives the input submitted to it, and worker sandbox/network
+controls remain separate.
+
+## Text-only application inference
+
+For a private routing decision or title, pass
+`input.inference: {responseFormat: "json_object"}` (or `"text"`). This is a
+separate, explicit capability: the planner makes one model completion with no
+tools, before task classification, search, document revision or execution.
+Structured tool-call responses are rejected; quoted tool instructions and code
+examples remain text. JSON output must be a complete object. Applications still
+validate their own response schema.
+
+Text-only inference cannot be combined with search, attachments or enabled
+search inference. It has no retained artifact/image inputs or document lineage, and
+session callbacks cannot issue or commit files. The immutable choice survives
+restart and input-less retry; a new input selects its own policy. Normal runs
+without this field keep their existing tool capabilities. The chosen hosted
+model receives the inference input, so this is tool isolation, not an on-device
+privacy promise.
+
+### Explicit image-aware inference
+
+An application may opt a private routing step into local perception with
+`input.inference: {responseFormat: "json_object", vision: true}` and the normal
+bounded `input.attachments` image descriptors. Require the live
+`attachments.inferenceVision === true` capability before using this extension.
+Old capabilities remain readable and do not imply support. The flag appears
+only while the independent local vision role and retained-image store are ready.
+
+Pixels go to the local vision role. Its validated observations are passed to
+the configured text model as untrusted data, with tools, search, execution and
+file access still disabled. Returned tool calls are protocol errors. This does
+not promise that image-derived observations remain on-device when the text
+provider is hosted. Applications validate their own JSON decision schema.
+
+The choice is durable. Input-less retry of an image-aware run requires
+`reuseAttachments: true` and reuses the same immutable image references. A new
+text-only inference ignores retained images and remains available without the
+optional vision role. Vision opt-in without any current/reused image fails
+before inference. Explicit/inferred public search and artifact/document lineage
+remain separate, and session callbacks cannot create or commit files.