@navels/neal 0.5.0 → 0.6.0

package/docs/prompt-specs.md

@@ -175,6 +175,84 @@ older run state.
 
 If a prompt change would force validator or retained parser behavior to change, treat that as a contract change and review the prompt spec, prompt builder, schema builder, and tests together.
 
+## Prompt size bounds
+
+Prompt inputs that grow with run length are either capped at render time or
+deliberately left unbounded with the provider input budget as their backstop,
+and each section below says which. The contract has four parts.
+
+**The completion packet carries a verification tally, not the history.**
+`buildFinalCompletionPacket()` embeds `verificationTally`
+(`buildVerificationTally` in `src/neal/verification-events.ts`): total command
+runs, distinct commands, passed/failed/unknown counts over the latest result
+per distinct command, and the last 10 failing commands with exit codes, each
+command string capped at 300 characters. Both completion prompts embed the
+tally and point at the run directory's `events.ndjson` for the complete
+per-command record. The events file is the source of truth; the packet never
+carries the full history and no extra artifact is written.
+
+**Run-scaling sections are capped where they enter a prompt.** The shared
+helpers live in `src/neal/context/inline-review-context.ts` and truncation is
+render-time only: stored state, persisted artifacts, and schema-validated
+coder outputs are never mutated to satisfy a bound.
+
+- Inlined range-diff sections: `INLINE_SECTION_MAX_CHARS` (200,000
+  characters) via `truncateInlineSectionBody`, with an explicit truncation
+  marker.
+- Operator guidance: `USER_GUIDANCE_MAX_CHARS` (20,000 characters) applies
+  per role file (`src/neal/prompts/guidance.ts`; `neal check` warns when a
+  guidance file exceeds the cap), to the persisted plan-review recovery
+  guidance message, and to the latest blocked-recovery guidance line.
+- Agent-authored free text (completion summaries, finding claims, round
+  summaries, blocked reasons, the last implementation scope's commit
+  subject): `boundFreeTextValues` shares
+  `AGENT_FREE_TEXT_SECTION_MAX_CHARS` (20,000 characters) across each fixed
+  group of values, markers included. The completion packet's completed-scope
+  summary, its scope-accounting summary, and the scope reviewer's recent
+  accepted-scope history are single strings capped at the same constant via
+  `truncateInlineSectionBody`.
+- Changed-file lists: `boundChangedFileList` renders the first
+  `CHANGED_FILE_LIST_LIMIT` (20) paths and collapses the rest to a
+  `(+N more)` entry; the underlying arrays keep every path for non-prompt
+  consumers.
+- Commit-subject lists (the aggregate completion range and the scope
+  review's commits-in-scope list): `boundCommitSubjectList` renders the
+  first `COMMIT_SUBJECT_LIST_LIMIT` (20) subjects under the shared free-text
+  budget and collapses the rest to a `(+N more)` entry.
+- Git diff-stat blocks (aggregate completion range and scope review):
+  `GIT_SUMMARY_SECTION_MAX_CHARS` (20,000 characters) via
+  `truncateInlineSectionBody`.
+
+Every bound is a module constant, not configuration. Three sections are
+intentionally unbounded and rely on the provider input budget below as their
+backstop: the inlined plan text, the progress text, and the review-findings
+selected-range diff (`buildReviewFindingsInlinedDiffSection` in
+`src/neal/review-findings/prompts.ts` inlines the full resolved-range diff
+for read-only reviewers because it is the source of truth for what the range
+changed — only the separate draft-prompt preview is capped, at
+`DIFF_PREVIEW_LIMIT`). The `INLINE_SECTION_MAX_CHARS` cap applies to the
+inlined range-diff sections built through `truncateInlineSectionBody`, not to
+every diff that reaches a prompt.
+
+**Providers with a hard limit reject oversized prompts before the SDK call.**
+A capability role that declares `maxInputChars` gets an adapter-boundary
+preflight on the exact text each turn sends; over-limit prompts fail fast
+with a non-retryable `input_too_large` error naming the prompt size, the
+limit, and the three largest `## ` sections. See
+[providers.md](providers.md) for the capability field, the preflight
+mechanics, and the error kind.
+
+**Input-size failures are recoverable without state surgery.** There is no
+sticky gate: the preflight re-measures the actual rebuilt prompt on every
+attempt, so `neal resume` after the prompt shrinks proceeds normally, while
+an unchanged oversized prompt fails fast before any provider call. While the
+latest failure is `input_too_large`, `neal status` renders a conditional Next
+Action: shrink the named largest input first (trim operator guidance files,
+or upgrade neal so current prompt bounds apply on resume), then resume; if
+the prompt can't fit under the limit, start a new run on a provider with a
+larger or no declared limit, because per-run provider rebinding doesn't
+exist.
+
 ## Provider variants
 
 Provider-specific variants are allowed, but they are not the default escape hatch. Each spec declares `providerVariants` for `shared` (status `default`) plus `openai-codex` and `anthropic-claude` (status `reserved_for_justified_divergence`).

package/docs/providers.md

@@ -72,6 +72,7 @@ Each provider capability role declares:
 
 - whether the role is supported
 - read, write, and shell tool access
+- an optional hard per-turn input limit in characters (`maxInputChars`)
 - session resume support
 - model override support
 - neal structured control protocol support
@@ -85,6 +86,16 @@ structured-advisor capability and read tool access: every reviewer inspects
 the repository directly. Session resume support is required when a persisted
 session handle is present.
 
+A role that declares `maxInputChars` gets an input-budget preflight
+(`src/neal/providers/input-budget.ts`) in the adapter on the exact text each
+SDK turn sends: the bare prompt for plain turns, the protocol-wrapped prompt
+for structured turns, and each generated repair prompt before its repair
+thread is created. Every call site is covered without per-site wiring. A
+prompt over the limit fails fast with a non-retryable `input_too_large` error
+before any SDK call and without consuming API-retry budget; the error message
+names the prompt size, the limit, and the three largest `## ` sections. Roles
+without a declared limit skip the preflight.
+
 Current built-in capabilities are intentionally conservative:
 
 - OpenAI Codex supports coder and structured-advisor roles. The coder role is
@@ -92,6 +103,8 @@ Current built-in capabilities are intentionally conservative:
   broad local access. The structured-advisor (reviewer) role is read capable
   but never write or shell capable (see
   [The read-only reviewer invariant](#the-read-only-reviewer-invariant)).
+  Both roles declare `maxInputChars: 1,048,576` — the size at which Codex's
+  app-server rejects a turn with its `input_too_large` input-error code.
 - Anthropic Claude supports coder and structured-advisor roles. The coder role
   is read, write, and shell capable. The structured-advisor (reviewer) role is
   read capable but never write or shell capable.
@@ -402,6 +415,12 @@ Normalized error kinds are:
 - `structured_output_invalid`
 - `permission_denied`
 - `session_unavailable`
+- `input_too_large` (the assembled prompt exceeds the role's declared
+  `maxInputChars`; thrown by the adapter's preflight before any SDK call, and
+  a provider-side over-limit rejection — Codex's `input_too_large`
+  input-error code — normalizes to the same kind. Always non-retryable; the
+  message names the prompt size, the limit, and the three largest `## `
+  sections)
 - `provider_failed`
 - `unknown`
 

package/neal.yml

@@ -40,7 +40,7 @@
 #
 #   # Maximum number of times final completion review may send execution back
 #   # for more work before neal stops reopening the plan.
-#   final_completion_continue_execution_max: 2
+#   final_completion_continue_execution_max: 3
 #
 #   # Optional local notification command. Leave commented to keep
 #   # notifications disabled.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navels/neal",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A source-first multi-agent CLI for planning, executing, reviewing, and resuming scoped code changes.",
   "license": "MIT",
   "publishConfig": {
@@ -56,7 +56,7 @@
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "3.0.34",
-    "@anthropic-ai/claude-agent-sdk": "0.3.238",
+    "@anthropic-ai/claude-agent-sdk": "0.3.240",
     "@openai/codex-sdk": "0.149.0",
     "ai": "7.0.74",
     "dotenv": "^17.4.2",