@lazyingart/agintiflow 0.20.241 → 0.20.243

package/docs/deep-research-engine.md

@@ -10,6 +10,15 @@ 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.
 
+For a request that combines local workspace evidence with web research, the
+outer agent first receives normal inspection tools. After it has read two
+relevant files, or read one file plus inspected/searched the project, the next
+research turn is constrained to `deep_research` and `finish`. This keeps local
+notes authoritative without letting an agent silently replace a requested
+multi-source review with ad hoc browsing. Tool history is scoped to the newest
+genuine user request, so a completed research call from an older task does not
+suppress a later correction or refresh.
+
 ## Architecture
 
 The implementation follows the strongest production patterns without making
@@ -35,6 +44,11 @@ every query an unbounded agent swarm:
    paper set erase the requested source class. Search snippets can guide
    discovery, but they cannot satisfy verified first-party coverage or enter
    synthesis as cited evidence.
+   Phrases such as “official Temporal docs” retain this requirement even when a
+   product name occurs between `official` and `docs`. Product-owned root pages
+   and vendor blogs are classified using the named discovery route; unrelated
+   third-party pages are not promoted merely because their URL repeats one
+   query word.
    Canonical duplicates found by multiple providers are promoted and retain
    per-provider rank evidence. Multi-domain corpora receive separate bounded `site:`
    queries matched to entity-specific subquestions instead of one fragile OR
@@ -99,6 +113,10 @@ every query an unbounded agent swarm:
    rather than arbitrary page text. Every substantive paragraph and finding
    cites exact evidence IDs instead of merely naming a source. A failed main
    synthesis gets one same-provider fast-model fallback.
+   A request for practical recommendations becomes a completion obligation:
+   every recommendation must cite verified evidence, and the run fails closed
+   rather than delivering an unsupported advice section. The renderer uses the
+   compact research objective instead of dumping the raw task prompt.
 9. **Audit**: deterministic code removes unknown or unverified evidence IDs,
    derives visible source citations from accepted evidence records, removes
    unsupported synthesis statements, then reports claim, quotation, citation,
@@ -110,6 +128,13 @@ every query an unbounded agent swarm:
     guarded workspace-relative `outputPath` when the caller requests a durable
     filename, then sent to the canvas.
 
+The reader-facing report always includes an explicit limitations section and
+separates quote-verified sources from inspected-but-uncited pages. When the
+original request asks for reproducibility or exact quotations, deterministic
+rendering adds a verification procedure, retrieval timestamps and SHA-256
+digests, and a verified-evidence appendix. These sections come from the
+retrieval/evidence ledger, not model memory.
+
 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)
@@ -136,6 +161,8 @@ the authoritative original user goal. A planner may shorten the research
 question, but cannot silently drop requirements such as “compare at least three
 independent primary sources,” “read a paper/PDF when available,” or “include
 negative evidence.” These requirements are fingerprinted and checkpointed.
+The same contract covers practical recommendations, reproducible verification
+methods, and exact-quote evidence appendices.
 
 Planning and evidence extraction deliberately use the configured routing model
 when it belongs to a hosted active provider. Synthesis uses the configured main
@@ -187,7 +214,10 @@ To resume a partial or completed same-query run, pass the returned
 `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.
+invalidate old cached runs automatically. The public tool result also carries
+the research schema version; the outer session reuses a completed result only
+when that version matches the installed engine. Versionless or older retained
+results are refreshed instead of being presented as current evidence.
 
 `outputPath` is optional and must name a Markdown file inside the active
 workspace. Repository internals such as `.git`, dependency trees such as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.241",
+  "version": "0.20.243",
   "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",
@@ -66,6 +66,7 @@
     "scripts/supervision-ledger.js",
     "scripts/smoke-supervision-ledger.js",
     "scripts/smoke-integration-production-mount.js",
+    "scripts/smoke-integration-production-runtime-bundle.js",
     "scripts/smoke-integration-storage-authority.js",
     "scripts/smoke-integration-retained-durable-common.js",
     "scripts/smoke-integration-retained-file-lock.js",
@@ -203,6 +204,7 @@
     "supervision:ledger": "node scripts/supervision-ledger.js",
     "smoke:supervision-ledger": "node scripts/smoke-supervision-ledger.js",
     "smoke:integration-production-mount": "node scripts/smoke-integration-production-mount.js",
+    "smoke:integration-production-runtime-bundle": "node scripts/smoke-integration-production-runtime-bundle.js",
     "smoke:integration-storage-authority": "node scripts/smoke-integration-storage-authority.js",
     "smoke:integration-retained-durable-common": "node scripts/smoke-integration-retained-durable-common.js",
     "smoke:integration-retained-file-lock": "node scripts/smoke-integration-retained-file-lock.js",
@@ -219,7 +221,7 @@
     "storage:migrate": "node bin/aginti-cli.js storage migrate",
     "publish:env": "node scripts/npm-publish-from-env.js publish --access public",
     "publish:env:whoami": "node scripts/npm-publish-from-env.js whoami",
-    "test": "npm run check && npm run smoke:integration-production-mount && npm run smoke:integration-storage-authority && npm run smoke:integration-retained-durable-common && npm run smoke:integration-retained-file-lock && npm run smoke:integration-retained-event-ledger && npm run smoke:integration-retained-event-ledger-bundle && npm run smoke:integration-retained-repository-kernel && npm run smoke:integration-retained-session-state-store && npm run smoke:integration-retained-native-session-repository-state && npm run smoke:integration-retained-native-execution-evidence && npm run smoke:integration-retained-runtime-repository-surface && npm run smoke:integration-retained-runtime-repository-phase-b && npm run smoke:integration-runtime-repository-contract && npm run smoke:integration-runtime-authority && npm run smoke:localllm-provider && npm run smoke:localllm-model-tiers && npm run smoke:localllm-code-routing && npm run smoke:local-failure-recovery && 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:document-artifact-quality && 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:supervision-ledger && 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:integration-production-mount && npm run smoke:integration-production-runtime-bundle && npm run smoke:integration-storage-authority && npm run smoke:integration-retained-durable-common && npm run smoke:integration-retained-file-lock && npm run smoke:integration-retained-event-ledger && npm run smoke:integration-retained-event-ledger-bundle && npm run smoke:integration-retained-repository-kernel && npm run smoke:integration-retained-session-state-store && npm run smoke:integration-retained-native-session-repository-state && npm run smoke:integration-retained-native-execution-evidence && npm run smoke:integration-retained-runtime-repository-surface && npm run smoke:integration-retained-runtime-repository-phase-b && npm run smoke:integration-runtime-repository-contract && npm run smoke:integration-runtime-authority && npm run smoke:localllm-provider && npm run smoke:localllm-model-tiers && npm run smoke:localllm-code-routing && npm run smoke:local-failure-recovery && 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:document-artifact-quality && 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:supervision-ledger && 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-deep-research.js

@@ -3,7 +3,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
-import { auditResearchSynthesis, deepResearch } from "../src/deep-research.js";
+import { auditResearchSynthesis, deepResearch, RESEARCH_VERSION } from "../src/deep-research.js";
 import { checkToolUse } from "../src/guardrails.js";
 import { flushHousekeeping } from "../src/housekeeping.js";
 import { requestNextStep, toolChoiceForProvider } from "../src/model-client.js";
@@ -59,6 +59,50 @@ async function main() {
     !shouldStartWithDeepResearch(localEvidenceGoal),
     "local-source research incorrectly forced deep_research before workspace inspection"
   );
+  const inspectedLocalEvidenceMessages = [
+    { role: "user", content: localEvidenceGoal },
+    {
+      role: "assistant",
+      tool_calls: [{ id: "inspect-notes", function: { name: "read_file", arguments: '{"path":"PROJECT_NOTES.md"}' } }],
+    },
+    {
+      role: "assistant",
+      tool_calls: [{ id: "inspect-sources", function: { name: "read_file", arguments: '{"path":"sources.json"}' } }],
+    },
+  ];
+  assert(
+    shouldStartWithDeepResearch(localEvidenceGoal, inspectedLocalEvidenceMessages),
+    "local-source research did not enter bounded deep research after workspace inspection"
+  );
+  assert(
+    !shouldStartWithDeepResearch(localEvidenceGoal, [
+      ...inspectedLocalEvidenceMessages,
+      {
+        role: "assistant",
+        tool_calls: [{ id: "current-research", function: { name: "deep_research", arguments: "{}" } }],
+      },
+    ]),
+    "the current request repeated deep research after already requesting it"
+  );
+  assert(
+    shouldStartWithDeepResearch(localEvidenceGoal, [
+      ...inspectedLocalEvidenceMessages,
+      {
+        role: "assistant",
+        tool_calls: [{ id: "old-research", function: { name: "deep_research", arguments: "{}" } }],
+      },
+      { role: "user", content: "Refresh this evidence review because the current report quality is not acceptable." },
+      {
+        role: "assistant",
+        tool_calls: [{ id: "refresh-report", function: { name: "read_file", arguments: '{"path":"agent-reliability-evidence-review.md"}' } }],
+      },
+      {
+        role: "assistant",
+        tool_calls: [{ id: "refresh-sources", function: { name: "read_file", arguments: '{"path":"sources.json"}' } }],
+      },
+    ]),
+    "a completed research call from an older user intent suppressed a fresh bounded research pass"
+  );
   assert(
     shouldStartWithDeepResearch("Write a deep web research report comparing three primary papers."),
     "standalone deep research no longer starts with the bounded research workflow"
@@ -441,6 +485,7 @@ async function main() {
                   ],
                 }],
                 keyFindings: [{ claim: "Claims retain exact evidence IDs.", evidenceIds: ["S1-C1", "S2-C1"], confidence: "high" }],
+                recommendations: [],
                 contradictions: [],
                 uncertainties: [],
                 nextQuestions: [],
@@ -508,6 +553,7 @@ async function main() {
     },
     store
   );
+  assert(research.version === RESEARCH_VERSION, "deep research did not expose its result-schema version");
   assert(research.ok && research.sourceCount === 2, `deep research failed: ${research.error || "unknown"}`);
   assert(
     researchSearchProviders.length === 2 && researchSearchProviders.every((provider) => provider === "multi"),
@@ -601,6 +647,7 @@ async function main() {
                   executiveSummaryEvidenceIds: ["S1-C1"],
                   sections: [{ heading: "Claim", paragraphs: [{ text: "The gain was measured.", evidenceIds: ["S1-C1"] }] }],
                   keyFindings: [],
+                  recommendations: [],
                   contradictions: [],
                   uncertainties: ["The exact source was inaccessible."],
                   nextQuestions: [],
@@ -734,6 +781,7 @@ async function main() {
                     { claim: "A second independent source corroborates the measurement.", evidenceIds: ["S2-C1"], confidence: "high" },
                     { claim: "A third independent source supplies separate evidence.", evidenceIds: ["S3-C1"], confidence: "high" },
                   ],
+                  recommendations: [],
                   contradictions: [],
                   uncertainties: ["Benchmark scope remains limited."],
                   nextQuestions: [],
@@ -1004,6 +1052,95 @@ async function main() {
     "a bounded official PDF was still constrained by the generic 2 MiB page limit"
   );
 
+  const namedOfficialResearch = await deepResearch(
+    {
+      query: "Compare official Temporal docs and official LangGraph docs for durable agent execution.",
+      depth: "quick",
+      sourcePolicy: "primary",
+      maxQueries: 1,
+      maxSources: 2,
+      gapPasses: 0,
+      researchId: "named-official-products-smoke",
+      outputPath: "reports/named-official-products.md",
+      dryRun: true,
+    },
+    {
+      provider: "mock",
+      model: "mock-agent",
+      commandCwd: researchWorkspace,
+      webSearchImpl: async ({ query }) => ({
+        ok: true,
+        toolName: "web_search",
+        provider: "test",
+        query,
+        results: /official system card engineering blog architecture/i.test(query)
+          ? [
+              {
+                rank: 1,
+                title: "Durable Execution Solutions",
+                url: "https://temporal.io/blog/durable-execution-solutions",
+                canonicalUrl: "https://temporal.io/blog/durable-execution-solutions",
+                domain: "temporal.io",
+                snippet: "Temporal explains durable execution and workflow recovery.",
+                provider: "test",
+              },
+              {
+                rank: 2,
+                title: "Third-party retry commentary",
+                url: "https://appscale.example.org/blog/retry-commentary",
+                canonicalUrl: "https://appscale.example.org/blog/retry-commentary",
+                domain: "appscale.example.org",
+                snippet: "A secondary opinion about retry behavior.",
+                provider: "test",
+              },
+            ]
+          : [
+              {
+                rank: 1,
+                title: "LangGraph",
+                url: "https://www.langchain.com/langgraph",
+                canonicalUrl: "https://www.langchain.com/langgraph",
+                domain: "langchain.com",
+                snippet: "LangGraph provides durable execution for long-running stateful agents.",
+                provider: "test",
+              },
+              {
+                rank: 2,
+                title: "Generic durable systems survey",
+                url: "https://link.springer.com/article/generic-durable-systems",
+                canonicalUrl: "https://link.springer.com/article/generic-durable-systems",
+                domain: "link.springer.com",
+                snippet: "A broad survey with little agent-specific implementation detail.",
+                provider: "test",
+              },
+            ],
+      }),
+      webPageReaderImpl: async ({ url }) => ({
+        ok: true,
+        toolName: "read_web_page",
+        url,
+        title: url.includes("temporal.io") ? "Temporal Durable Execution" : "LangGraph",
+        readable: true,
+        contentType: "text/html",
+        retrievedAt: "2026-08-25T00:00:00.000Z",
+        sha256: (url.includes("temporal.io") ? "1" : "2").repeat(64),
+        content: "The official product page documents durable execution, checkpointing, and recovery behavior.",
+        passages: ["The official product page documents durable execution, checkpointing, and recovery behavior."],
+      }),
+    },
+    new SessionStore(path.join(tempRoot, "sessions"), "named-official-products-smoke")
+  );
+  assert(namedOfficialResearch.ok, `named official product research failed: ${namedOfficialResearch.error || "unknown"}`);
+  assert(namedOfficialResearch.requirements.officialDiscovery, "'official Temporal docs' did not preserve first-party discovery intent");
+  assert(
+    namedOfficialResearch.sources.map((source) => source.domain).sort().join(",") === "langchain.com,temporal.io",
+    `named first-party product pages were displaced by weaker filler: ${namedOfficialResearch.sources.map((source) => source.domain).join(", ")}`
+  );
+  assert(namedOfficialResearch.sources.every((source) => source.firstParty), "a named official product root was not classified as first-party");
+  const namedOfficialReport = await fs.readFile(namedOfficialResearch.reportPath, "utf8");
+  assert(namedOfficialReport.includes("## Limitations, Uncertainties, And Coverage Gaps"), "research report omitted an explicit limitations section");
+  assert(namedOfficialReport.includes("## Sources Inspected But Not Cited"), "dry-run report hid the uncited-source boundary");
+
   const scholarlyGapCalls = [];
   const scholarlyGapResearch = await deepResearch(
     {
@@ -1070,6 +1207,7 @@ async function main() {
                     paragraphs: [{ text: "Two primary sources support the result.", evidenceIds: ["S1-C1", "S2-C1"] }],
                   }],
                   keyFindings: [{ claim: "Independent evidence was recovered.", evidenceIds: ["S1-C1", "S2-C1"], confidence: "high" }],
+                  recommendations: [],
                   contradictions: [],
                   uncertainties: [],
                   nextQuestions: [],
@@ -1209,6 +1347,7 @@ async function main() {
                     evidenceIds: ["S1-C1", "S2-C1", "S3-C1"],
                     confidence: "high",
                   }],
+                  recommendations: [],
                   contradictions: [],
                   uncertainties: ["Real throughput depends on local hardware."],
                   nextQuestions: [],

package/scripts/smoke-dynamic-step-budget.js

@@ -4,6 +4,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { runAgent } from "../src/agent-runner.js";
+import { RESEARCH_VERSION } from "../src/deep-research.js";
 import { resolveRuntimeConfig } from "../src/config.js";
 import { classifyCommand, evaluateCommandPolicy } from "../src/command-policy.js";
 import {
@@ -4338,6 +4339,7 @@ try {
     {
       ok: true,
       toolName: "deep_research",
+      version: RESEARCH_VERSION,
       researchId: "research-one",
       status: "completed",
       reportPath: path.join(workspace, "report.md"),
@@ -4354,6 +4356,16 @@ try {
     reusedResearch?.duplicateSuppressed && reusedResearch.reportPath === path.join(workspace, "report.md"),
     "same-goal deep research did not reuse an already completed exact report"
   );
+  completedResearchState.meta.completedDeepResearch[0].result.version = RESEARCH_VERSION - 1;
+  assert(
+    completedDeepResearchReuse(
+      completedResearchState,
+      { query: "A model-expanded query", outputPath: "report.md", refresh: true },
+      { commandCwd: workspace }
+    ) === null,
+    "a stale deep-research engine result was reused after the report contract changed"
+  );
+  completedResearchState.meta.completedDeepResearch[0].result.version = RESEARCH_VERSION;
   completedResearchState.meta.goalContract = { revision: 2, currentHash: "goal-two" };
   assert(
     completedDeepResearchReuse(

package/scripts/smoke-integration-production-mount.js

@@ -547,6 +547,7 @@ async function verifyPackagedBinAndScriptClosure() {
     "scripts/eval-provider-attribution.js",
     "scripts/smoke-context-budget-recovery.js",
     "scripts/smoke-integration-production-mount.js",
+    "scripts/smoke-integration-production-runtime-bundle.js",
   ]) {
     assert.equal(packageJson.files.includes(requiredFile), true);
   }
@@ -1087,6 +1088,38 @@ async function main() {
       "INTEGRATION_CREDENTIAL_SOURCE_FORBIDDEN"
     );
 
+    let cliCheckOutput = "";
+    await withCanonicalCredentialFixture(async () => {
+      const summary = await integrationCliMain(["check", "--config", configPath], {
+        env: { CREDENTIALS_DIRECTORY: INTEGRATION_SYSTEMD_CREDENTIALS_DIRECTORY },
+        stdout: { write(chunk) { cliCheckOutput += String(chunk); } },
+      });
+      assert.equal(summary.status, "checked-disabled");
+      assert.equal(summary.capability?.enabled, false);
+      assert.equal(summary.implementationReady, false);
+      assert.equal(typeof summary.runtimeBundle?.healthy, "boolean");
+      assert.equal(summary.runtimeBundle?.implementationReady, false);
+      assert.equal(summary.runtimeBundle?.capabilityEnabled, false);
+      assert.equal(summary.runtimeBundle?.httpServingEnabled, false);
+      if (summary.runtimeBundle.healthy) {
+        assert.equal(summary.runtimeBundle.firstBlocker?.component, "idempotencyStore");
+        assert.equal(
+          summary.runtimeBundle.firstBlocker?.code,
+          "INTEGRATION_DESCRIPTOR_BOUND_IDEMPOTENCY_UNAVAILABLE"
+        );
+      } else {
+        assert.equal(summary.runtimeBundle.firstBlocker?.component, "storageAuthority");
+        assert.match(
+          summary.runtimeBundle.firstBlocker?.code || "",
+          /^INTEGRATION_STORAGE_/u
+        );
+      }
+      assert.deepEqual(
+        JSON.parse(cliCheckOutput.trim()),
+        JSON.parse(JSON.stringify(summary))
+      );
+    });
+
     const cliServePort = await unusedLoopbackPort();
     const cliServeConfigPath = path.join(tempRoot, "integration-serve.json");
     await fs.writeFile(