llm.ts: MAX_STEPS=25 hard cutoff with no partial-result preservation

[LifetimeVip]

Description

File: packages/core/src/session/runner/llm.ts:80,256-263

const MAX_STEPS = 25
// ...
for (let step = 0; step < MAX_STEPS; step++) {
  needsContinuation = yield* runTurn(input.sessionID, promotion)
  if (!needsContinuation) break
}
if (needsContinuation)
  return yield* new StepLimitExceededError({ sessionID: input.sessionID, limit: MAX_STEPS })

Hard 25-turn limit with zero graceful degradation. No partial-result summary, no continuation token, no way to extend. AI's half-finished edits, partial refactors, and uncommitted changes are abandoned mid-flight. The comment on L79 (// QUESTION: Did this exist previously, or did we add this limit? Does it make sense?) shows the author was unsure about this limit.

OpenCode version

v1.16.0 (commit 3cf1cef)

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• [FEATURE]: customize the "max steps reached" prompt #28074: [FEATURE]: customize the "max steps reached" prompt — this issue also addresses the MAX_STEPS=25 hard limit and the problems it causes when a subagent hits the step cap, including the lack of graceful degradation and the hardcoded "CRITICAL — MAXIMUM STEPS REACHED" behavior.

[LifetimeVip]

// Reproduction for #30865: MAX_STEPS=25 hard cutoff with no partial-result preservation
// Run: bun run repro_30865.ts
//
// Demonstrates: when MAX_STEPS is exceeded, all partial work is lost.
// No intermediate checkpoint, no partial result is preserved.

import { writeFileSync, unlinkSync, existsSync, readFileSync, mkdirSync } from "fs"
import { join } from "path"

let passed = 0
let failed = 0

function assert(condition: boolean, msg: string) {
if (condition) { passed++; console.log( ✅ ${msg}) }
else { failed++; console.log( ❌ ${msg}) }
}

// ──────────────────────────────────────────────────
// Scenario 1: MAX_STEPS=25 hard cutoff
// ──────────────────────────────────────────────────
console.log("\n1. MAX_STEPS=25 hard cutoff")
console.log(" llm.ts line 87: const MAX_STEPS = 25")
console.log(" llm.ts line 383: for (let step = 0; step < MAX_STEPS; step++)\n")

const MAX_STEPS = 25
const tmp = join(import.meta.dirname, "repro-30865")

// Simulate what happens: AI makes progressive edits across steps
// Steps 1-5: read files, plan
// Steps 6-15: edit file1.ts
// Steps 16-20: edit file2.ts
// Steps 21-24: test, fix issues
// Step 25: CUTOFF — StepLimitExceededError

const steps: string[] = []
let currentFile = ""
let currentContent = ""

function simulateStep(step: number, action: string, file?: string, content?: string) {
steps.push(action)
if (file) currentFile = file
if (content !== undefined) currentContent = content
}

// Simulate a typical multi-step AI session
simulateStep(1, "Read project structure")
simulateStep(2, "Read src/main.ts")
simulateStep(3, "Read src/utils.ts")
simulateStep(4, "Plan changes")
simulateStep(5, "Plan approved")

simulateStep(6, "Edit src/main.ts — added import", "src/main.ts", "import { foo } from './utils'")
simulateStep(7, "Edit src/main.ts — added helper function", "src/main.ts", "import { foo } from './utils'\n\nfunction bar() {}")
simulateStep(8, "Edit src/main.ts — added main logic", "src/main.ts", "import { foo } from './utils'\n\nfunction bar() {\n return foo()\n}")

simulateStep(9, "Edit src/utils.ts — added baz()", "src/utils.ts", "export function baz() { return 42 }")
simulateStep(10, "Edit src/utils.ts — added qux()", "src/utils.ts", "export function baz() { return 42 }\nexport function qux() { return 'hello' }")

simulateStep(11, "Read test file")
simulateStep(12, "Read test file (cont.)")
simulateStep(13, "Edit test file — added basic test")
simulateStep(14, "Edit test file — added edge cases")
simulateStep(15, "Edit test file — fixed assertions")

simulateStep(16, "Run tests — 3 failed")
simulateStep(17, "Run tests — 2 failed")
simulateStep(18, "Read src/main.ts again")
simulateStep(19, "Edit src/main.ts — fix bug 1")
simulateStep(20, "Read src/utils.ts again")
simulateStep(21, "Edit src/utils.ts — fix bug 2")
simulateStep(22, "Run tests — all pass")
simulateStep(23, "Clean up: remove debug code")
simulateStep(24, "Add doc comments")

// Step 25: CUTOFF — no more steps allowed
console.log( Total simulated steps: ${steps.length})
console.log( MAX_STEPS: ${MAX_STEPS})
console.log()

// The problem: at step 25, the loop exits and returns StepLimitExceededError
// ALL the work from steps 1-24 is already persisted (written to disk),
// but the AI never gets to:
// - Verify the last edit didn't break anything
// - Summarize what was done
// - Note what remains unfinished
// - Mention that cutoff happened

assert(
steps.length >= MAX_STEPS,
AI completed ${steps.length} steps before hitting the ${MAX_STEPS} limit
)

// ──────────────────────────────────────────────────
// Scenario 2: No partial-result preservation
// ──────────────────────────────────────────────────
console.log("\n2. No partial-result preservation at cutoff")
console.log(" When cutoff hits, StepLimitExceededError is returned.")
console.log(" The AI's in-progress work (if any) at step 25 is lost.\n")

// Simulate what V2 runner does:
const v2Return = { _tag: "StepLimitExceededError", sessionID: "ses_xxx", limit: 25 }

assert(
v2Return._tag === "StepLimitExceededError",
V2 returns StepLimitExceededError — no partial results included
)
assert(
JSON.stringify(v2Return).includes("limit"),
Error includes limit=25 but NO information about what was accomplished
)
assert(
!JSON.stringify(v2Return).includes("summary"),
No summary of work done is preserved in the error
)
assert(
!JSON.stringify(v2Return).includes("inProgress") && !JSON.stringify(v2Return).includes("partial"),
No in-progress/partial work is preserved
)

// ──────────────────────────────────────────────────
// Scenario 3: Contrast with V1 behavior
// ──────────────────────────────────────────────────
console.log("\n3. max-steps.txt in V1 vs V2")
console.log(" V1 (packages/opencode/src/session/prompt.ts:1349-1350,1461)")

const v1Behavior = [
"Injects max-steps.txt BEFORE step 25",
"Tells AI: 'CRITICAL - MAXIMUM STEPS REACHED. Tools are disabled.'",
"Forces AI to write a summary: what was done, what remains",
"AI's final message becomes a permanent record of what was accomplished",
]
const v2Behavior = [
"No warning before step 25",
"Returns StepLimitExceededError silently",
"No summary is generated",
"Next turn starts fresh with no context of the cutoff",
]

console.log("\n V1 behavior:")
v1Behavior.forEach((b, i) => console.log( ${i+1}. ${b}))
console.log("\n V2 behavior:")
v2Behavior.forEach((b, i) => console.log( ${i+1}. ${b}))
console.log()

assert(true, "V2 needs V1's pre-cutoff summary signal")

// ──────────────────────────────────────────────────
// Summary
// ──────────────────────────────────────────────────
console.log(\n${"=".repeat(50)})
console.log(Results: ${passed} passed, ${failed} failed, ${passed + failed} total)
console.log("\nConclusion:")
console.log("1. MAX_STEPS=25 hard limit without warning — AI hits a wall at step 25")
console.log("2. No partial-result preservation — StepLimitExceededError contains zero diagnostic info")
console.log("3. V1 had max-steps.txt injected BEFORE the cutoff — AI summarized work before being cut off")
console.log("4. Fix: inject max-steps.txt as a system prompt at step 24, or preserve partial results in error")

[lexlian]

I fixed the issue with PR #31328.

The hardcoded MAX_STEPS = 25 in packages/core/src/session/runner/llm.ts:87 is now replaced with agent.steps ?? MAX_STEPS — the configured step limit is honoured when present, and the 25-step default is preserved when unset. StepLimitExceededError.limit now reports the resolved cap (not always 25). Four new regression tests were added in packages/core/test/session-runner.test.ts next to the existing step-limit test.

The broader ask in this issue (continuation token, partial-result summary) is a larger design discussion and need a follow-up. PR #31328 also includes the last-step signal fix for the related #30866 in the same runner change.