@lazyingart/agintiflow 0.20.251 → 0.20.253

package/docs/model-selection.md

@@ -26,6 +26,8 @@ The local tier policy uses the workstation's installed aliases without treating
 
 Installed aliases are not loaded during routing. A genuine coding/implementation request starts on Deep, checks the authenticated model inventory, and selects the exact `AGINTI_LOCALLLM_CODE_MODEL` value only when present. Missing or unverified capability stays on Deep; the decision and effective model are recorded so fallback sessions can re-evaluate and selected sessions resume on the same model. Explanation-only code questions and non-code writing/research/documentation/design keep their existing route. Automatic Max is off by default; set `AGINTI_LOCALLLM_ALLOW_AUTO_MAX=true` to opt in. An opted-in high-complexity non-code run starts on Deep, confirms the Max alias through authenticated `/v1/models`, and only then samples current resources. Unknown or pressured resource state stays on Deep. Explicit Max also cannot bypass the live gate: immediately before client creation, each new or resumed run rechecks at least 24 GiB available RAM, swap use at or below 75%, and 40 GiB aggregate free NVIDIA memory. A blocked explicit gate creates no model client and performs no inference.
 
+Smart hosted routes fail over only toward the local trust boundary. If a hosted provider returns an authentication, quota, rate-limit, model-availability, capacity, or network failure, AgInTiFlow records `provider.handoff_requested`, patches the same durable session to `localllm-deep`, verifies LocalLLM readiness, records `provider.handoff_activated`, and continues without replaying the user request or prior side effects. Manual routing remains exact and never changes provider automatically. Retained integration profiles also keep their pinned provider identity. Set `AGINTI_PROVIDER_HANDOFF=false` to disable the smart hosted-to-local handoff or `AGINTI_PROVIDER_HANDOFF_MODEL` to select another verified local fallback model.
+
 Long writing tasks use an additional tool boundary: `writing_specialist`. The main model still plans the run, manages files, formats Markdown/LaTeX/Final Draft output, compiles/checks artifacts, and finishes. The specialist gets only the writing brief, canon, style guide, prior draft, target, audience, constraints, and format intent, then returns prose plus a formatter handoff. It follows the active LocalLLM provider by default even when hosted keys exist. Cross-provider writing requires both an explicit target (`AGINTI_WRITING_PROVIDER` or a per-run provider override) and `AGINTI_ALLOW_HOSTED_WRITING_SPECIALIST=true` (or the equivalent per-run permission flag); language detection and ambient credentials never grant that permission.
 
 ## CLI Commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.251",
+  "version": "0.20.253",
   "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",
@@ -174,6 +174,7 @@
     "smoke:localllm-code-routing": "node scripts/smoke-localllm-code-routing.js",
     "smoke:local-failure-recovery": "node scripts/smoke-local-failure-recovery.js",
     "smoke:planning-timeout-recovery": "node scripts/smoke-planning-timeout-recovery.js",
+    "smoke:provider-handoff": "node scripts/smoke-provider-handoff.js",
     "smoke:local-resource-policy": "node scripts/smoke-local-resource-policy.js",
     "smoke:context-budget-recovery": "node scripts/smoke-context-budget-recovery.js",
     "smoke:localllm-model-tiers": "node scripts/smoke-localllm-model-tiers.js",
@@ -228,7 +229,7 @@
     "publish:env": "node scripts/npm-publish-from-env.js publish --access public",
     "publish:env:whoami": "node scripts/npm-publish-from-env.js whoami",
     "pretest": "npm run smoke:planning-timeout-recovery",
-    "test": "npm run check && npm run smoke:integration-production-mount && npm run smoke:integration-production-runtime-bundle && npm run smoke:integration-retained-idempotency-store && 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 smoke:workspace-secret-false-positive && 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-retained-idempotency-store && 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 smoke:workspace-secret-false-positive && npm run smoke:provider-handoff && 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-context-budget-recovery.js

@@ -341,6 +341,129 @@ assert.ok(
   "DeepSeek runtime compaction exceeded the bounded retry target"
 );
 
+const staleReadAfterMutationState = {
+  goal: "Repair service_ctl.py from current source and verify the service lifecycle tests.",
+  plan: "Use current source state and latest test evidence.",
+  messages: [
+    { role: "system", content: "Preserve current source truth across compaction." },
+    { role: "user", content: "Continue the current service recovery task." },
+    {
+      role: "assistant",
+      content: "",
+      tool_calls: [
+        {
+          id: "stale-source-read",
+          type: "function",
+          function: {
+            name: "read_file",
+            arguments: JSON.stringify({ path: "service_ctl.py", startLine: 1, lineLimit: 40 }),
+          },
+        },
+      ],
+    },
+    {
+      role: "tool",
+      tool_call_id: "stale-source-read",
+      content: JSON.stringify({
+        ok: true,
+        toolName: "read_file",
+        path: "service_ctl.py",
+        startLine: 1,
+        lineLimit: 40,
+        lineCount: 80,
+        bytes: 3200,
+        sha256: "1111111111111111111111111111111111111111111111111111111111111111",
+        contentTruncated: false,
+        content: "STALE-SERVICE-CONTENT command = f'python gateway_service.py'",
+      }),
+    },
+    {
+      role: "assistant",
+      content: "",
+      tool_calls: [
+        {
+          id: "current-source-mutation",
+          type: "function",
+          function: {
+            name: "apply_patch",
+            arguments: JSON.stringify({
+              path: "service_ctl.py",
+              search: "command = f'python gateway_service.py'",
+              replace: "command = [sys.executable, 'gateway_service.py']",
+            }),
+          },
+        },
+      ],
+    },
+    {
+      role: "tool",
+      tool_call_id: "current-source-mutation",
+      content: JSON.stringify({
+        ok: true,
+        toolName: "apply_patch",
+        path: "service_ctl.py",
+        summary: "1 file change applied",
+      }),
+    },
+    {
+      role: "assistant",
+      content: "",
+      tool_calls: [
+        {
+          id: "fresh-source-read",
+          type: "function",
+          function: {
+            name: "read_file",
+            arguments: JSON.stringify({ path: "service_ctl.py", startLine: 41, lineLimit: 40 }),
+          },
+        },
+      ],
+    },
+    {
+      role: "tool",
+      tool_call_id: "fresh-source-read",
+      content: JSON.stringify({
+        ok: true,
+        toolName: "read_file",
+        path: "service_ctl.py",
+        startLine: 41,
+        lineLimit: 40,
+        lineCount: 80,
+        bytes: 3300,
+        sha256: "2222222222222222222222222222222222222222222222222222222222222222",
+        contentTruncated: false,
+        content: "FRESH-SERVICE-CONTENT shell=False and lifecycle helpers are current",
+      }),
+    },
+    ...Array.from({ length: 8 }, (_, index) => readOnlyDiagnosticPair(index + 30)).flat(),
+  ],
+};
+const staleReadAfterMutationMessages = buildContextBudgetCompactionMessages(
+  staleReadAfterMutationState,
+  config,
+  { title: "", url: "" },
+  12,
+  { reason: "discard stale pre-mutation source reads" }
+);
+const staleReadAfterMutationText = staleReadAfterMutationMessages
+  .map((message) => message.content || "")
+  .join("\n");
+assert.ok(
+  !staleReadAfterMutationText.includes("STALE-SERVICE-CONTENT"),
+  "compaction retained a source read that predates a successful mutation of the same file"
+);
+assert.ok(
+  staleReadAfterMutationText.includes("FRESH-SERVICE-CONTENT"),
+  "compaction discarded the bounded source read made after the successful mutation"
+);
+assert.ok(
+  staleReadAfterMutationMessages.some((message) =>
+    Array.isArray(message.tool_calls) &&
+    message.tool_calls.some((call) => call?.function?.name === "apply_patch")
+  ),
+  "compaction discarded the successful mutation while invalidating its stale predecessor read"
+);
+
 function noisyFullReadPair(index, generation) {
   const id = `validator-${generation}-${index}`;
   const file = `tmp/validator-${generation}-${index}.py`;

package/scripts/smoke-local-failure-recovery.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import assert from "node:assert/strict";
+import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -11,7 +12,11 @@ import {
   decideLocalFailureRecovery,
   localFailureRecoveryInstruction,
 } from "../src/local-failure-recovery.js";
-import { nextStepRuntimeConfig, runAgent } from "../src/agent-runner.js";
+import {
+  nextStepRuntimeConfig,
+  repeatedSuccessfulMutationBlock,
+  runAgent,
+} from "../src/agent-runner.js";
 import { resolveRuntimeConfig } from "../src/config.js";
 import { SessionStore } from "../src/session-store.js";
 
@@ -190,6 +195,89 @@ assert.match(instruction, /preserve successful work/i);
 assert.match(instruction, /Do not repeat the failing call/i);
 assert.match(instruction, /rerun the smallest relevant verification/i);
 
+const durablePatchArgs = {
+  path: "service_ctl.py",
+  search: "command = f'python gateway_service.py'",
+  replace: "command = [sys.executable, 'gateway_service.py']",
+};
+const digest = (value) => crypto.createHash("sha256").update(value).digest("hex");
+const durableMutation = {
+  revision: 4,
+  goalRevision: 7,
+  toolName: "apply_patch",
+  paths: ["service_ctl.py"],
+  patch: {
+    path: "./service_ctl.py",
+    searchHash: digest(durablePatchArgs.search),
+    replaceHash: digest(durablePatchArgs.replace),
+  },
+};
+const durablePatchState = {
+  meta: {
+    goalContract: { revision: 7 },
+    toolLoop: {
+      recent: Array.from({ length: 20 }, (_, index) =>
+        failed("apply_patch", `later-failure-${index}`)
+      ),
+      stagnationEpoch: 23,
+    },
+    projectVerification: {
+      mutationRevision: 4,
+      mutationHistory: [durableMutation],
+    },
+  },
+};
+assert.equal(
+  repeatedSuccessfulMutationBlock(durablePatchState, "apply_patch", durablePatchArgs, {
+    commandCwd: process.cwd(),
+  })?.category,
+  "repeated-successful-mutation",
+  "a successful exact patch must remain blocked after it falls out of the short tool-loop window"
+);
+assert.equal(
+  repeatedSuccessfulMutationBlock(
+    {
+      ...durablePatchState,
+      meta: {
+        ...durablePatchState.meta,
+        goalContract: { revision: 8 },
+      },
+    },
+    "apply_patch",
+    durablePatchArgs,
+    { commandCwd: process.cwd() }
+  ),
+  null,
+  "a genuine user continuation must permit deliberate reconsideration of an earlier patch"
+);
+assert.equal(
+  repeatedSuccessfulMutationBlock(
+    {
+      ...durablePatchState,
+      meta: {
+        ...durablePatchState.meta,
+        projectVerification: {
+          mutationRevision: 5,
+          mutationHistory: [
+            durableMutation,
+            {
+              revision: 5,
+              goalRevision: 7,
+              toolName: "write_file",
+              paths: ["service_ctl.py"],
+            },
+          ],
+        },
+      },
+    },
+    "apply_patch",
+    durablePatchArgs,
+    { commandCwd: process.cwd() }
+  ),
+  null,
+  "an intervening successful mutation must permit the same exact patch when source state changed"
+);
+
 function assistant(content, toolCalls = []) {
   return {
     choices: [{ message: { role: "assistant", content, ...(toolCalls.length ? { tool_calls: toolCalls } : {}) } }],

package/src/agent-runner.js

@@ -93,6 +93,7 @@ import { longJobStatus, startLongJob } from "./long-job-tools.js";
 import { executeAgentLinkTool, isAgentLinkTool } from "./agentlink.js";
 import { classifyGoalIntent, isDirectAnswerIntent } from "./goal-intent.js";
 import { normalizeProviderBaseURL, normalizeProviderId, providerRequiresApiKey } from "./provider-contract.js";
+import { resolveProviderHandoff } from "./provider-handoff.js";
 import { ProviderReadinessError, probeProviderRuntime } from "./provider-runtime.js";
 import { probeLocalMaxResources } from "./local-resource-policy.js";
 import {
@@ -876,11 +877,22 @@ function summarizeRetainedSourceEvidence(messages = [], limit = 28) {
     const payload = retained?.payload || safeParseToolContent(message.content);
     if (!payload || payload.ok === false || payload.blocked || payload.skipped) continue;
     const toolName = String(retained?.name || payload.toolName || payload.name || "");
+    const args = retained?.args || payload.args || {};
+    const sourcePath = String(payload.path || args.path || "").trim();
+    if (["apply_patch", "write_file"].includes(toolName) && sourcePath) {
+      for (const [key, record] of bySource.entries()) {
+        if (
+          record.toolName === "read_file" &&
+          retainedPathMatchesAny(record.sourcePath, [sourcePath])
+        ) {
+          bySource.delete(key);
+        }
+      }
+      continue;
+    }
     if (!["read_file", "list_files", "search_files", "inspect_project", "run_command"].includes(toolName)) {
       continue;
     }
-    const args = retained?.args || payload.args || {};
-    const sourcePath = String(payload.path || args.path || "").trim();
     const command = String(args.command || "").trim();
     const readRange = toolName === "read_file" ? retainedReadRange(payload, args) : null;
     const key = `${toolName}:${sourcePath || command}${readRange ? `:${readRange.key}` : ""}`;
@@ -936,9 +948,15 @@ function summarizeRetainedSourceEvidence(messages = [], limit = 28) {
       if (payload.stdout) parts.push(`stdout=${compactSingleLine(payload.stdout, 260)}`);
       if (payload.stderr) parts.push(`stderr=${compactSingleLine(payload.stderr, 220)}`);
     }
-    bySource.set(key, redactSensitiveText(parts.join(" | ")));
+    bySource.set(key, {
+      toolName,
+      sourcePath,
+      text: redactSensitiveText(parts.join(" | ")),
+    });
   }
-  return [...bySource.values()].slice(-Math.max(1, Number(limit) || 28));
+  return [...bySource.values()]
+    .slice(-Math.max(1, Number(limit) || 28))
+    .map((record) => record.text);
 }
 
 const COMPACTION_STATE_TOOL_NAMES = new Set([
@@ -1075,6 +1093,16 @@ function retainedToolStateMessages(messages = [], limit = 12, outputPaths = [],
     if (!COMPACTION_STATE_TOOL_NAMES.has(name)) return;
     if (!payload || payload.ok === false || payload.blocked || payload.skipped) return;
     const sourcePath = String(payload.path || args?.path || "").trim();
+    if (["apply_patch", "write_file"].includes(name) && sourcePath) {
+      for (const [key, record] of recordsByKey.entries()) {
+        if (
+          record.name === "read_file" &&
+          retainedPathMatchesAny(record.sourcePath, [sourcePath])
+        ) {
+          recordsByKey.delete(key);
+        }
+      }
+    }
     const command = String(args?.command || payload.args?.command || "").trim();
     const durableIdentity = String(
       sourcePath || command || payload.researchId || args?.researchId || args?.query || name
@@ -1084,6 +1112,7 @@ function retainedToolStateMessages(messages = [], limit = 12, outputPaths = [],
     recordsByKey.set(key, {
       ordinal: ordinal += 1,
       name,
+      sourcePath,
       args: redactValue(args),
       payload: compactRetainedToolPayload(name, payload, args),
     });
@@ -6199,7 +6228,7 @@ export function repeatedSuccessfulMutationBlock(state, toolName, args = {}, conf
     commandCwd: config.commandCwd,
   });
   const stagnationEpoch = Math.max(0, Number(toolLoop.stagnationEpoch || 0));
-  const alreadyApplied = (Array.isArray(toolLoop.recent) ? toolLoop.recent : []).some(
+  const recentlyApplied = (Array.isArray(toolLoop.recent) ? toolLoop.recent : []).some(
     (entry) =>
       entry?.signature === signature &&
       entry?.toolName === "apply_patch" &&
@@ -6208,6 +6237,41 @@ export function repeatedSuccessfulMutationBlock(state, toolName, args = {}, conf
       entry?.successfulMutation === true &&
       Number(entry?.stagnationEpoch || 0) === stagnationEpoch
   );
+  const verification = state.meta?.projectVerification || {};
+  const history = Array.isArray(verification.mutationHistory)
+    ? verification.mutationHistory
+    : verification.lastMutation
+      ? [verification.lastMutation]
+      : [];
+  const targetPath = typeof args.path === "string" ? safeRecoveryEvidencePath(args.path) : "";
+  const searchHash = typeof args.search === "string" ? hashForLog(args.search) : "";
+  const replaceHash = typeof args.replace === "string" ? hashForLog(args.replace) : "";
+  const currentGoalRevision = Math.max(0, Number(state.meta?.goalContract?.revision || 0));
+  let matchingHistoryIndex = -1;
+  if (targetPath && searchHash && replaceHash) {
+    for (let index = history.length - 1; index >= 0; index -= 1) {
+      const mutation = history[index];
+      if (
+        mutation?.toolName === "apply_patch" &&
+        Number(mutation?.goalRevision || 0) === currentGoalRevision &&
+        safeRecoveryEvidencePath(mutation?.patch?.path) === targetPath &&
+        String(mutation?.patch?.searchHash || "") === searchHash &&
+        String(mutation?.patch?.replaceHash || "") === replaceHash
+      ) {
+        matchingHistoryIndex = index;
+        break;
+      }
+    }
+  }
+  const persistentlyApplied =
+    matchingHistoryIndex >= 0 &&
+    !history.slice(matchingHistoryIndex + 1).some(
+      (mutation) =>
+        Number(mutation?.goalRevision || 0) === currentGoalRevision &&
+        Number(mutation?.revision || 0) >
+          Number(history[matchingHistoryIndex]?.revision || 0)
+    );
+  const alreadyApplied = recentlyApplied || persistentlyApplied;
   if (!alreadyApplied) return null;
   return {
     reason:
@@ -11058,7 +11122,78 @@ async function recordPreInferenceFailure({ error, config, state, store, observer
   emitConsole(config, result, { kind: "error", error: true });
 }
 
-export async function runAgent(config) {
+class ProviderHandoffSignal extends Error {
+  constructor({ sessionId, expectedRuntimeRevision, decision }) {
+    super(`Provider handoff requested for ${decision.sourceProvider} -> ${decision.targetProvider}.`);
+    this.name = "ProviderHandoffSignal";
+    this.sessionId = sessionId;
+    this.expectedRuntimeRevision = expectedRuntimeRevision;
+    this.decision = decision;
+  }
+}
+
+async function prepareProviderHandoff({ error, config, state, store, observers, sessionId, stage = "runtime" }) {
+  const decision = resolveProviderHandoff(error, config, { stage });
+  if (!decision) return null;
+
+  state.meta = state.meta || {};
+  const priorAttempts = Number(state.meta.providerHandoff?.attempts || 0);
+  if (priorAttempts >= 1) return null;
+
+  const at = new Date().toISOString();
+  const detail = {
+    version: 1,
+    attempts: priorAttempts + 1,
+    status: "pending",
+    sourceProvider: decision.sourceProvider,
+    sourceModel: decision.sourceModel,
+    targetProvider: decision.targetProvider,
+    targetModel: decision.targetModel,
+    failureCode: decision.failureCode,
+    httpStatus: decision.status || 0,
+    requestedAt: at,
+  };
+  state.meta.providerHandoff = detail;
+  state.updatedAt = at;
+  updateGoalStatus(state, "active", "provider_handoff", at);
+  await store.saveState(state);
+  await store.appendEvent("provider.handoff_requested", detail);
+  observers.event("provider.handoff_requested", { ...detail, sessionId });
+  emitConsole(
+    config,
+    `${decision.sourceProvider}/${decision.sourceModel} is unavailable (${decision.failureCode}); continuing the same session with ${decision.targetProvider}/${decision.targetModel}.`,
+    { kind: "meta" }
+  );
+  return new ProviderHandoffSignal({
+    sessionId,
+    expectedRuntimeRevision: Number(state.meta.runtimeConfig?.revision || 1),
+    decision,
+  });
+}
+
+async function activatePendingProviderHandoff({ config, state, store, observers, sessionId }) {
+  const handoff = state.meta?.providerHandoff;
+  if (
+    !handoff ||
+    handoff.status !== "pending" ||
+    normalizeProviderId(handoff.targetProvider, "") !== normalizeProviderId(config.provider, "") ||
+    String(handoff.targetModel || "") !== String(config.model || "")
+  ) {
+    return;
+  }
+  const detail = {
+    ...handoff,
+    status: "active",
+    activatedAt: new Date().toISOString(),
+  };
+  state.meta.providerHandoff = detail;
+  state.updatedAt = detail.activatedAt;
+  await store.saveState(state);
+  await store.appendEvent("provider.handoff_activated", detail);
+  observers.event("provider.handoff_activated", { ...detail, sessionId });
+}
+
+async function runAgentOnce(config) {
   assertIntegrationRunAgentInvocation(config);
   const incomingConfig = config;
   const sessionId = config.resume || config.sessionId || `web-agent-${crypto.randomUUID()}`;
@@ -11087,6 +11222,11 @@ export async function runAgent(config) {
     state.meta = state.meta || {};
     state.meta.runtimeConfig = runtime.snapshot;
     config = rebuildResumedRuntimeConfig(incomingConfig, runtime.runtimeOverrides, sessionId);
+    // Keep compatibility fields aligned with the authoritative runtime
+    // snapshot. Provider/model patches otherwise leave stale top-level values
+    // that can mislead later diagnostics and legacy session readers.
+    state.provider = config.provider;
+    state.model = config.model;
     const patchedRuntimeFields = runtime.patched
       ? Object.keys(incomingConfig.runtimePatch || {}).filter((field) => isSessionRuntimeField(field))
       : [];
@@ -11261,10 +11401,22 @@ export async function runAgent(config) {
     }
     client = config.clientFactory ? await config.clientFactory(config) : createClient(config);
   } catch (error) {
+    const handoff = await prepareProviderHandoff({
+      error,
+      config,
+      state,
+      store,
+      observers,
+      sessionId,
+      stage: "preflight",
+    });
+    if (handoff) throw handoff;
     await recordPreInferenceFailure({ error, config, state, store, observers, sessionId });
     throw error;
   }
 
+  await activatePendingProviderHandoff({ config, state, store, observers, sessionId });
+
   ensureChatState(state);
 
   const initialRepair = repairModelMessageHistory(state, config);
@@ -12937,6 +13089,9 @@ export async function runAgent(config) {
       ...goalRunMetadata(state),
     };
   } catch (error) {
+    if (error instanceof ProviderHandoffSignal) throw error;
+    const handoff = await prepareProviderHandoff({ error, config, state, store, observers, sessionId });
+    if (handoff) throw handoff;
     if (isModelTimeoutError(error)) {
       const detail = {
         reason: "model_timeout",
@@ -13000,3 +13155,20 @@ export async function runAgent(config) {
     await flushHousekeeping();
   }
 }
+
+export async function runAgent(config) {
+  try {
+    return await runAgentOnce(config);
+  } catch (error) {
+    if (!(error instanceof ProviderHandoffSignal)) throw error;
+    const decision = error.decision;
+    return runAgentOnce({
+      ...config,
+      goal: "",
+      resume: error.sessionId,
+      sessionId: error.sessionId,
+      runtimePatch: decision.runtimePatch,
+      expectedRuntimeRevision: error.expectedRuntimeRevision,
+    });
+  }
+}

package/src/model-client.js

@@ -148,6 +148,22 @@ function shouldRetryWithoutReasoningEffort(error, payload = {}) {
   return /reasoning[_\s.-]?effort|unsupported parameter|unknown parameter|unrecognized request argument/i.test(message);
 }
 
+function annotateProviderRequestError(error, config = {}, label = "model request") {
+  if (!error || (typeof error !== "object" && typeof error !== "function")) return error;
+  try {
+    Object.defineProperties(error, {
+      agintiProviderRequest: { value: true, configurable: true },
+      agintiProvider: { value: String(config.provider || ""), configurable: true },
+      agintiProviderModel: { value: String(config.model || ""), configurable: true },
+      agintiProviderRequestLabel: { value: String(label || "model request"), configurable: true },
+    });
+  } catch {
+    // Some SDK errors can be non-extensible. Classification still has the
+    // explicit preflight path, while an unmarked runtime error fails normally.
+  }
+  return error;
+}
+
 export async function createChatCompletion(client, payload, config, label = "model request") {
   const preparedPayload = withChatReasoningEffort(payload, config);
   const timeout = resolveModelTimeoutMs(config);
@@ -157,9 +173,13 @@ export async function createChatCompletion(client, payload, config, label = "mod
     } catch (error) {
       if (shouldRetryWithoutReasoningEffort(error, preparedPayload)) {
         const { reasoning_effort: _reasoningEffort, ...retryPayload } = preparedPayload;
-        return client.chat.completions.create(retryPayload, requestOptions(config));
+        try {
+          return await client.chat.completions.create(retryPayload, requestOptions(config));
+        } catch (retryError) {
+          throw annotateProviderRequestError(retryError, config, label);
+        }
       }
-      throw error;
+      throw annotateProviderRequestError(error, config, label);
     }
   }
 
@@ -196,18 +216,22 @@ export async function createChatCompletion(client, payload, config, label = "mod
   } catch (error) {
     if (shouldRetryWithoutReasoningEffort(error, preparedPayload)) {
       const { reasoning_effort: _reasoningEffort, ...retryPayload } = preparedPayload;
-      return await client.chat.completions.create(retryPayload, {
-        ...requestOptions(config),
-        signal: controller.signal,
-      });
+      try {
+        return await client.chat.completions.create(retryPayload, {
+          ...requestOptions(config),
+          signal: controller.signal,
+        });
+      } catch (retryError) {
+        throw annotateProviderRequestError(retryError, config, label);
+      }
     }
     if (timedOut && error?.name !== "ModelTimeoutError") {
       const timeoutError = new Error(`${label} timed out after ${timeout}ms`);
       timeoutError.name = "ModelTimeoutError";
       timeoutError.cause = error;
-      throw timeoutError;
+      throw annotateProviderRequestError(timeoutError, config, label);
     }
-    throw error;
+    throw annotateProviderRequestError(error, config, label);
   } finally {
     if (timer) clearTimeout(timer);
     if (config.abortSignal) {

package/src/provider-handoff.js

@@ -0,0 +1,126 @@
+import { LOCALLLM_MODEL_TIERS } from "./model-routing.js";
+import { normalizeProviderId } from "./provider-contract.js";
+
+const NETWORK_ERROR_CODES = new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+]);
+
+function enabled(value, fallback = true) {
+  if (value === undefined || value === null || String(value).trim() === "") return fallback;
+  return !/^(?:0|false|off|no)$/i.test(String(value).trim());
+}
+
+function providerErrorText(error) {
+  return [
+    error?.code,
+    error?.type,
+    error?.message,
+    error?.error?.code,
+    error?.error?.type,
+    error?.error?.message,
+    error?.response?.data?.error?.code,
+    error?.response?.data?.error?.type,
+    error?.response?.data?.error?.message,
+  ]
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+}
+
+export function classifyProviderHandoffError(error) {
+  const status = Number(error?.status || error?.response?.status || 0);
+  const code = String(error?.code || "").trim().toUpperCase();
+  const text = providerErrorText(error);
+
+  if (
+    status === 402 ||
+    /insufficient[_ -]?(?:quota|balance)|quota exceeded|billing|account balance|credits? exhausted/.test(text)
+  ) {
+    return { eligible: true, code: "provider_quota", status };
+  }
+  if (
+    code === "API_KEY_REQUIRED" ||
+    status === 401 ||
+    status === 403 ||
+    /authentication|unauthorized|invalid[_ -]?api[_ -]?key|permission denied/.test(text)
+  ) {
+    return { eligible: true, code: "provider_auth", status };
+  }
+  if (status === 429 || /rate[_ -]?limit|too many requests/.test(text)) {
+    return { eligible: true, code: "provider_rate_limited", status };
+  }
+  if (
+    status === 404 &&
+    /model|deployment|endpoint|not found|does not exist|unavailable/.test(text)
+  ) {
+    return { eligible: true, code: "provider_model_unavailable", status };
+  }
+  if (
+    status === 408 ||
+    status === 503 ||
+    status === 529 ||
+    status >= 500 ||
+    NETWORK_ERROR_CODES.has(code) ||
+    /overload|overloaded|capacity|temporarily unavailable|connection refused|network unreachable/.test(text)
+  ) {
+    return { eligible: true, code: "provider_unavailable", status };
+  }
+  return { eligible: false, code: "provider_request_failed", status };
+}
+
+export function resolveProviderHandoff(error, config = {}, { stage = "runtime" } = {}) {
+  const sourceProvider = normalizeProviderId(config.provider, "");
+  const targetProvider = normalizeProviderId(
+    config.providerHandoffProvider || process.env.AGINTI_PROVIDER_HANDOFF_PROVIDER || "localllm",
+    ""
+  );
+  if (!enabled(config.allowProviderHandoff ?? process.env.AGINTI_PROVIDER_HANDOFF, true)) return null;
+  if (!sourceProvider || sourceProvider === "mock" || sourceProvider === "localllm") return null;
+  if (!targetProvider || targetProvider !== "localllm" || targetProvider === sourceProvider) return null;
+  if (String(config.routingMode || "smart").trim().toLowerCase() === "manual") return null;
+  if (String(config.integrationSessionProfile || "").trim()) return null;
+  if (stage !== "preflight" && error?.agintiProviderRequest !== true) return null;
+
+  const failure = classifyProviderHandoffError(error);
+  if (!failure.eligible) return null;
+
+  const routeModel =
+    String(config.providerHandoffRouteModel || process.env.AGINTI_LOCALLLM_ROUTE_MODEL || "").trim() ||
+    LOCALLLM_MODEL_TIERS.fast.model;
+  const mainModel =
+    String(
+      config.providerHandoffModel ||
+        process.env.AGINTI_PROVIDER_HANDOFF_MODEL ||
+        process.env.AGINTI_LOCALLLM_MAIN_MODEL ||
+        ""
+    ).trim() || LOCALLLM_MODEL_TIERS.deep.model;
+
+  return {
+    version: 1,
+    sourceProvider,
+    sourceModel: String(config.model || ""),
+    targetProvider,
+    targetModel: mainModel,
+    routeModel,
+    mainModel,
+    spareModel: mainModel,
+    failureCode: failure.code,
+    status: failure.status,
+    runtimePatch: {
+      provider: targetProvider,
+      model: mainModel,
+      routingMode: "manual",
+      routeProvider: targetProvider,
+      routeModel,
+      mainProvider: targetProvider,
+      mainModel,
+      spareProvider: targetProvider,
+      spareModel: mainModel,
+    },
+  };
+}