@lazyingart/agintiflow 0.20.251 → 0.20.252

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.252",
   "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/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 {
@@ -11058,7 +11059,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 +11159,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 +11338,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 +13026,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 +13092,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,
+    },
+  };
+}