feat(agent-core-v2): add runtime subagent model failover

[xiayh0107]

Related Issue

No linked issue. This draft PR is intended to align on the runtime failover design before it is considered ready for review.

Problem

Subagents can select a secondary model when they are created, but an already-running subagent cannot recover by switching models when its provider remains unavailable. Existing step retries only replay the same driver with the same model, error recovery stops after the first matching handler declines, and each turn keeps a frozen request configuration.

As a result, retry exhaustion or a structured provider quota error fails the turn even when an ordered fallback model is configured. Retried streams can also leave abandoned partial text or tool frames in transcript and Web projections.

What changed

• Add the experimental [subagent_failover] configuration and KIMI_CODE_EXPERIMENTAL_MODEL_FAILOVER flag with ordered model/effort bindings, trigger selection, and a per-turn switch limit.
• Let loop error handlers decline recovery and continue to later handlers, so same-model retry remains first and model failover runs only after retry exhaustion. Structured quota exhaustion can switch immediately.
• Rebind model and thinking effort atomically, invalidate the current turn's request snapshot, and replay the same failed driver. The switched profile binding is persisted for resume.
• Restrict failover to subagents and an explicit structured error allowlist. Cancellation, safety filtering, authentication errors, context overflow, invalid configuration, tool failures, and unclassified provider errors fail closed.
• Add model.failover wire records and turn.step.failover events with model, provider, effort, reason, and switch-budget metadata.
• Remove abandoned text, thinking, and tool frames when retry or failover replays a step. Transcript operations, reconnect snapshots, and Web task/side-chat projections converge without duplicate output.
• Add generated config/state/wire manifests, a minor changeset, and coverage for routing, retry handoff, quota handling, bounds, safety exclusions, warnings, persistence, agent isolation, partial streams, and tool/result deduplication.

The first version intentionally does not change the v1 engine or interactive TUI.

Documentation note: the gen-docs skill was run, but its prerequisite check requires docs/scripts/sync-changelog.mjs and a root CHANGELOG.md; neither exists in this repository. The skill therefore stopped as instructed. Generated agent-core-v2 manifests are included.

Validation:

• pnpm typecheck
• pnpm lint (0 errors; repository baseline warnings remain)
• agent-core-v2 changed suites: 158 tests
• transcript changed suites: 69 tests
• kap-server changed suites: 137 tests
• kimi-web changed suites: 71 tests
• pnpm --filter @moonshot-ai/agent-core-v2 lint:domain
• pnpm exec changeset status

Checklist

• I have read the CONTRIBUTING document.
• I have linked a related issue, or explained the problem above.
• I have added tests that prove my feature works.
• Ran gen-changesets skill, or this PR needs no changeset.
• Ran gen-docs skill, or this PR needs no doc update. See the prerequisite note above.

[changeset-bot]

🦋 Changeset detected

Latest commit: db38bab

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@moonshot-ai/kimi-code	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[xiayh0107]

内核机制与安全边界

Kimi Web 中用户实际看到的恢复过程