feat: automatic model fallback system with background support

[stranger2904]

Summary\n\nAdds an automatic model fallback system that gracefully handles API failures by retrying with configured fallback models. Background tasks now properly support model fallback chains, ensuring reliability even for async operations.\n\n## Features\n\n### Automatic Fallback on Transient Errors\n- Rate limits and HTTP 429 errors\n- Service unavailable (HTTP 503, 502)\n- Capacity issues (overloaded, capacity, unavailable)\n- Network errors (timeout, ECONNREFUSED, ENOTFOUND)\n\nNon-model errors (authentication failures, invalid input) are NOT retried.\n\n### Background Task Support\n- Background tasks properly use modelChain for fallback\n- Ensures reliability for async operations\n\n### Validated Configuration\n- maxAttempts >= 1 enforced to prevent silent failures\n- Clean error handling: only aborts on configuration errors, continues on model errors\n\n## Implementation\n\nCore module src/features/model-fallback/ provides utilities for model parsing, chain building, error detection, and retry logic with validation. Integrated with sisyphus-task for seamless fallback handling.\n\n## Fixes from Review\n

• P1: maxAttempts validation (Math.max(1, ...))\n- P2: Error matching scoped to agent.name only\n- P2: Background LaunchInput supports modelChain\n- P2: BackgroundTask stores modelChain field\n- P2: Background manager passes modelChain\n\n## Testing\n
  ✅ 36/36 model-fallback tests passing\n✅ Build successful\n✅ TypeScript types valid\n\nAll commits authored by stranger2904 with GitHub noreply email.\nClean PR without auto-generated descriptions.\n\nRelated: Fixes PR feat: automatic model fallback system with user notification #785 authorship issue.

---

Summary by cubic

Adds an automatic model fallback system for both sync and background tasks to keep prompts running through transient API failures. Also adds HTTP transport for MCP servers.

• New Features

  • Retries with fallback models on 429, 502/503, capacity, timeouts, and common network errors; skips auth/validation errors.
  • Background tasks now accept and pass modelChain for fallback.
  • Config options: fallback[], fallbackDelayMs (100–30000ms), fallbackRetryCount (1–5); schemas updated; default categories define fallback chains.
  • Task completion output includes the model used and a fallback notice when applicable.
  • Skill MCP: HTTP transport with optional headers, auto-detects HTTP vs stdio, backward compatible.

• Bug Fixes

  • Enforce maxAttempts >= 1.
  • Preserve variant on the primary model in modelChain.
  • Narrow error matching to agent.name for config issues.
  • Clean up subagentSessions on early returns.

^{Written for commit aa1c1dc. Summary will update on new commits.}

[cubic-dev-ai]

4 issues found across 12 files

Confidence score: 3/5

• Duplicate session.prompt invocation in src/features/background-agent/manager.ts can double-run the same task and leak concurrency before registration, which is a concrete regression risk.
• parseModelString in src/features/model-fallback/index.ts currently accepts empty provider/model pieces, so malformed specs could enter the fallback chain and trigger unexpected fallbacks.
• src/features/skill-mcp-manager/manager.test.ts doesn’t confirm headers reach the transport layer, leaving header regressions undetected even though the test would still pass.
• Pay close attention to src/features/background-agent/manager.ts, src/features/skill-mcp-manager/manager.test.ts, src/features/model-fallback/index.ts, pr_790_body.txt - functionality and documentation mismatches need to be resolved.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="pr_790_body.txt">

<violation number="1" location="pr_790_body.txt:3">
P2: PR body describes HTTP transport for SkillMcpManager, which does not match the PR title about automatic model fallback, likely misleading reviewers/release notes.</violation>
</file>

<file name="src/features/background-agent/manager.ts">

<violation number="1" location="src/features/background-agent/manager.ts:94">
P1: Duplicate session.prompt calls in launch() cause double execution and potential concurrency leak before task registration</violation>
</file>

<file name="src/features/skill-mcp-manager/manager.test.ts">

<violation number="1" location="src/features/skill-mcp-manager/manager.test.ts:47">
P2: HTTP headers test does not verify headers reach the transport; regression dropping headers would still pass</violation>
</file>

<file name="src/features/model-fallback/index.ts">

<violation number="1" location="src/features/model-fallback/index.ts:10">
P2: parseModelString treats empty provider/model segments as valid, allowing malformed model specs into the fallback chain</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: HTTP headers test does not verify headers reach the transport; regression dropping headers would still pass

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/features/skill-mcp-manager/manager.test.ts, line 47:

<comment>HTTP headers test does not verify headers reach the transport; regression dropping headers would still pass</comment>

<file context>
@@ -3,46 +3,326 @@ import { SkillMcpManager } from "./manager"
-        /missing required 'command' field/
-      )
+        // #when / #then
+        await expect(manager.getOrCreateClient(info, config)).rejects.toThrow(
+          /no valid connection configuration/
+        )
</file context>

[github-actions]

All contributors have signed the CLA. Thank you! ✅
_{Posted by the CLA Assistant Lite bot.}

[stranger29]

I have read the CLA Document and I hereby sign the CLA

[cubic-dev-ai]

6 issues found across 41 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="src/tools/lsp/tools.ts">

<violation number="1">
P2: `lsp_symbols` can throw when `limit` ≤ 0 because it accesses `limited[0]` after slicing to an empty array.</violation>
</file>

<file name="src/tools/sisyphus-task/tools.ts">

<violation number="1">
P1: User-controlled resume session ID is joined into filesystem path without validation, allowing path traversal outside MESSAGE_STORAGE.</violation>
</file>

<file name="README.md">

<violation number="1">
P2: Beta release link still points to v3.0.0-beta.1 while install text references v3.0.0-beta.6, causing user-facing version mismatch.</violation>
</file>

<file name="src/tools/AGENTS.md">

<violation number="1">
P3: Documentation inconsistency: overview still says LSP has 11 tools while this row indicates 7, causing conflicting guidance about available LSP tools.</violation>
</file>

<file name="src/tools/sisyphus-task/constants.ts">

<violation number="1">
P2: Default category configs no longer define fallback chains, so modelChain has no alternatives and the new automatic fallback system doesn’t activate for category/background tasks.</violation>
</file>

<file name="src/tools/sisyphus-task/tools.test.ts">

<violation number="1">
P2: Test reimplements model source detection instead of exercising production modelInfo logic, so it can pass even if the real bug remains.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P1: User-controlled resume session ID is joined into filesystem path without validation, allowing path traversal outside MESSAGE_STORAGE.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/tools/sisyphus-task/tools.ts, line 251:

<comment>User-controlled resume session ID is joined into filesystem path without validation, allowing path traversal outside MESSAGE_STORAGE.</comment>

<file context>
@@ -239,9 +248,18 @@ Use \`background_output\` with task_id="${task.id}" to check progress.`
         })
 
         try {
+          const resumeMessageDir = getMessageDir(args.resume)
+          const resumeMessage = resumeMessageDir ? findNearestMessageWithFields(resumeMessageDir) : null
+          const resumeAgent = resumeMessage?.agent
</file context>

[stranger2904]

Replaced by #797 with clean commit history and proper conflict resolution.