From 27ef5166955b5deaecc367a4b3393909b0ccc9f9 Mon Sep 17 00:00:00 2001
From: liruifengv <liruifeng1024@gmail.com>
Date: Thu, 25 Jun 2026 15:49:44 +0800
Subject: [PATCH] feat(agent-core): add config hint to max-steps-per-turn error
 (#1097)

* feat(agent-core): add config hint to max-steps-per-turn error

* test(agent-core): assert config hint in max-steps error
---
 .changeset/max-steps-config-hint.md         |  5 +++++
 packages/agent-core/src/errors/codes.ts     |  2 +-
 packages/agent-core/src/loop/errors.ts      | 11 ++++++++---
 packages/agent-core/test/agent/turn.test.ts |  1 +
 4 files changed, 15 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/max-steps-config-hint.md

diff --git a/.changeset/max-steps-config-hint.md b/.changeset/max-steps-config-hint.md
new file mode 100644
index 000000000..434a36ed3
--- /dev/null
+++ b/.changeset/max-steps-config-hint.md
@@ -0,0 +1,5 @@
+---
+"@moonshot-ai/kimi-code": patch
+---
+
+Add a hint to the per-turn step limit error pointing users to the loop_control.max_steps_per_turn config option.
diff --git a/packages/agent-core/src/errors/codes.ts b/packages/agent-core/src/errors/codes.ts
index 80dd108f9..04f18baa9 100644
--- a/packages/agent-core/src/errors/codes.ts
+++ b/packages/agent-core/src/errors/codes.ts
@@ -301,7 +301,7 @@ export const KIMI_ERROR_INFO = {
     title: 'Turn exceeded max steps',
     retryable: false,
     public: true,
-    action: 'Increase loop_control.max_steps_per_turn or split the task.',
+    action: 'Increase loop_control.max_steps_per_turn in config.toml or split the task.',
   },
   'provider.api_error': {
     title: 'Provider API error',
diff --git a/packages/agent-core/src/loop/errors.ts b/packages/agent-core/src/loop/errors.ts
index 43f7199d7..23fc7dc95 100644
--- a/packages/agent-core/src/loop/errors.ts
+++ b/packages/agent-core/src/loop/errors.ts
@@ -5,9 +5,14 @@
 import { ErrorCodes, KimiError, isKimiError } from '#/errors';
 
 export function createMaxStepsExceededError(maxSteps: number, message?: string): KimiError {
-  return new KimiError(ErrorCodes.LOOP_MAX_STEPS_EXCEEDED, message ?? `Turn exceeded maxSteps=${maxSteps}`, {
-    details: { maxSteps },
-  });
+  return new KimiError(
+    ErrorCodes.LOOP_MAX_STEPS_EXCEEDED,
+    message ??
+      `Turn exceeded maxSteps=${maxSteps}. If max_steps_per_turn is too small, raise it in config.toml (loop_control.max_steps_per_turn).`,
+    {
+      details: { maxSteps },
+    },
+  );
 }
 
 export function isMaxStepsExceededError(error: unknown): boolean {
diff --git a/packages/agent-core/test/agent/turn.test.ts b/packages/agent-core/test/agent/turn.test.ts
index e4dba7fee..c3e6d01e6 100644
--- a/packages/agent-core/test/agent/turn.test.ts
+++ b/packages/agent-core/test/agent/turn.test.ts
@@ -1208,6 +1208,7 @@ describe('Agent turn flow', () => {
           reason: 'failed',
           error: expect.objectContaining({
             code: 'loop.max_steps_exceeded',
+            message: expect.stringContaining('config.toml'),
             details: expect.objectContaining({
               maxSteps: 1,
             }),