fix(agents): classify non-interactive provider errors in managed DCode patch

[kagura-agent]

Summary

Managed Deep Agents Code non-interactive failures now replace raw exception output at DCode's internal error boundary with bounded, structured diagnostics. The observed provider-capacity failure is retryable for the failing thread, while MCP, gateway, policy, and unknown failures remain sanitized.

Related Issue

Closes #7415

Product Scope

Product-scope verdict: this change stays within the existing managed DCode integration. Maintainer-authored issue #7415 defines the failure, supported behavior, security boundary, and acceptance criteria. This verdict is independent of GitHub's mergeStateStatus.

Changes

• Replace DCode 0.1.34's internal non-interactive exception handler so the managed diagnostic runs before DCode converts the exception to exit code 1.
• Read at most five 4 KiB __error__ values from the failing thread in the managed writes table.
• Classify only the observed APIError('ResourceExhausted: Worker local total request limit reached (...)') provider-capacity signature.
• Emit fixed error_class, category, retryable, and thread correlation fields without exception, request, model, tool, or checkpoint content.
• Exercise the patched runtime boundary, cross-thread isolation, negative MCP, gateway, and policy cases, missing diagnostics, and sensitive-data sanitization.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: Current docs do not specify DCode exception text or error classification. The change adds no command, flag, configuration, default, workflow, or supported contract.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Not complete. Automated Codex Desktop nine-category security review on 6da4f49223ca found no findings, but independent human sensitive-path review remains required.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Security Review

This is an automated Codex Desktop review of upstream/main...6da4f49223ca, not human or sensitive-path review. The PR patch is unchanged from the prior review.

Category	Verdict	Evidence
Secrets and credentials	PASS	The diff contains no credential material. Test strings are inert disclosure sentinels, and the diff-aware gitleaks hook passed.
Input validation and data sanitization	PASS	The database path is fixed, the thread query is parameterized, reads are limited to five 4 KiB values, and classification uses one exact allowlisted signature.
Authentication and authorization	PASS	The diff adds no authentication, authorization, endpoint, or resource-access behavior.
Dependencies and third-party libraries	PASS	The diff adds no dependency or package-version change.
Error handling and logging	PASS	The handler emits fixed fields and a correlation ID without logging the exception or checkpoint row. Diagnostic failures preserve exit code 1.
Cryptography and data protection	PASS	The diff adds no cryptographic operation or sensitive-data persistence.
Configuration and security headers	PASS	The diff changes no container, network, HTTP, permission, or security-header configuration.
Security testing	PASS	Runtime tests cover cross-thread isolation, MCP, gateway, and policy negatives, unavailable diagnostics, and secret-content suppression.
System security	PASS	SQLite is opened read-only, classification cannot change the failure result, and the patch does not weaken an existing sandbox control.

Findings: none.

Files reviewed:

• agents/langchain-deepagents-code/patch-managed-deepagents-code.py
• test/helpers/langchain-deepagents-code-patch-fixture.ts
• test/langchain-deepagents-code-progressive-tool-disclosure.test.ts
• test/non-interactive-error-classification.test.ts

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: No docs change is needed because the runtime patch changes only bounded, sanitized diagnostics for an existing managed DCode headless failure path. The follow-up commits strengthen redaction coverage and align the progressive-disclosure synthetic fixture with the patcher's current source contract. Current docs do not specify exception text or error classification. The subagent reviewed changed comments, messages, fixtures, sentinel assertions, and test titles against WRITING.md; no blocking or advisory writing issue was found. This was an automated Codex Desktop review, not human review.
• Agent: Codex Desktop (documentation-writer subagent)

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable; scripts/prepare-dgx-station-host.sh is unchanged in the PR diff.
• Station profile/scenario: Not applicable.
• Result: Not applicable.
• Supporting evidence: Not applicable.

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — npx vitest run --project integration test/non-interactive-error-classification.test.ts test/langchain-deepagents-code-progressive-tool-disclosure.test.ts test/langchain-deepagents-code-direct-module-patch.test.ts test/langchain-deepagents-code-fetch-proxy.test.ts test/langchain-deepagents-code-provider-label.test.ts test/langchain-deepagents-code-retry-boundary.test.ts: 6 files passed, 85 tests passed, 1 skipped.
• Applicable broad gate passed — not applicable to this focused managed diagnostic boundary. Required CI provides the authoritative broad evidence.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Julie Yaunches jyaunches@nvidia.com
Signed-off-by: kagura-agent kagura.agent.ai@gmail.com

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

📝 Walkthrough

Walkthrough

The managed non-interactive path now classifies persisted provider-capacity errors for the active thread, emits sanitized diagnostics with a correlation ID, and returns exit code 1. Tests cover classification, thread isolation, unknown failures, patch wiring, and sensitive-data redaction.

Changes

Managed non-interactive error reporting

Layer / File(s)	Summary
Persisted error classification and reporting agents/langchain-deepagents-code/patch-managed-deepagents-code.py	Reads recent __error__ checkpoint entries for the active thread, recognizes provider capacity exhaustion, emits bounded structured diagnostics, and returns 1 without exposing original exception or checkpoint content.
Patch wiring and runtime coverage agents/langchain-deepagents-code/patch-managed-deepagents-code.py, test/helpers/langchain-deepagents-code-patch-fixture.ts, test/non-interactive-error-classification.test.ts	Validates marker and patch uniqueness, wires the replacement and appended reporter payload, and tests provider classification, cross-thread isolation, unknown errors, and output sanitization.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant NonInteractiveRunner
  participant ErrorReporter
  participant SessionsDatabase
  participant Console
  NonInteractiveRunner->>ErrorReporter: report failure for thread_id
  ErrorReporter->>SessionsDatabase: read recent __error__ writes
  SessionsDatabase-->>ErrorReporter: persisted error text
  ErrorReporter->>ErrorReporter: classify capacity exhaustion or unknown
  ErrorReporter->>Console: print bounded message with correlation_id
  ErrorReporter-->>NonInteractiveRunner: return 1

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The patch adds safe provider-capacity classification, retryability, correlation IDs, and redaction for managed non-interactive errors as requested.
Out of Scope Changes check	✅ Passed	The changes stay focused on managed non-interactive error classification and its tests, with no obvious unrelated additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly reflects the main change: classifying non-interactive provider errors in the managed Deep Agents Code patch.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@agents/langchain-deepagents-code/patch-managed-deepagents-code.py`:
- Around line 756-760: Update _NEMOCLAW_KNOWN_PROVIDER_ERRORS and its
classification flow to require trusted provider exception types/modules or
validated provider response fields before assigning upstream categories. Do not
classify generic messages such as MCP connection failures, gateway timeouts, or
unrelated 429 responses; leave them unknown, and add negative-path coverage
proving MCP, policy, and gateway errors remain distinguishable.

In `@test/non-interactive-error-classification.test.ts`:
- Around line 4-12: Update the imports in
non-interactive-error-classification.test.ts to include the CLI source module
under test, while preserving the existing fixture-helper, Node, and Vitest
imports.
- Around line 26-28: Replace the source-text marker assertions in
test/non-interactive-error-classification.test.ts:26-28 with an observable
run_non_interactive contract test. In
test/non-interactive-error-classification.test.ts:55-82, stub
_nemoclaw_original_run_non_interactive to raise controlled provider and unknown
exceptions, invoke run_non_interactive, capture its log record, and assert the
category, retryability, sanitized message, and identity-preserving rethrow;
cover both affected sites as part of this runtime-focused test update.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 782c8b65-53fe-4de9-ab4c-38011f11b8a0

📥 Commits

Reviewing files that changed from the base of the PR and between d13e34a and 560c8b3.

📒 Files selected for processing (2)

• agents/langchain-deepagents-code/patch-managed-deepagents-code.py
• test/non-interactive-error-classification.test.ts

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Canonical ledger: 0 blocker(s), 1 warning(s), 0 suggestion(s).

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections match; Nemotron reported the same number of blockers, 1 fewer warning, the same number of suggestions.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: None

1 optional E2E recommendation

• ubuntu-repo-cloud-langchain-deepagents-code

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Document the checkpoint-schema workaround boundary

• Location: agents/langchain-deepagents-code/patch-managed-deepagents-code.py:794
• Category: architecture
• Problem: The managed patch reads the upstream checkpoint database to recover an error that the upstream non-interactive handler hides. The code does not identify the state that creates this dependency, why the upstream source cannot be changed here, or the condition that permits removal.
• Impact: A changed checkpoint schema or error serialization silently changes provider-capacity failures to unknown errors. Maintainers have no recorded source boundary or removal condition for this workaround.
• Recommendation: Add a concise code comment or nearby maintained documentation that names the upstream serialization limitation, the `writes.__error__` dependency, and the upstream hook or contract change that removes this patch.
• Verification: Read the classifier and the upstream non-interactive exception path. Confirm the recorded dependency identifies the checkpoint schema and a removal condition.
• Test coverage: The existing classifier tests can continue to prove the fallback is sanitized when the checkpoint contract is unavailable; no additional behavior test is required for the documentation change.
• Evidence: `_nemoclaw_classify_persisted_error` opens `/sandbox/.deepagents/.state/sessions.db` and queries `writes` rows with `channel = '__error__'`. The only adjacent comment states that diagnostics must not replace the original exit result; it does not document why the persisted database is required or when this dependency can be removed. The linked issue describes generic upstream serialization, but PR and issue text are untrusted and do not establish a checked-in source-of-truth record.

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[kagura-agent]

Pushed fix addressing PR Review Advisor findings:

PRA-1 (blocker): The classifier now walks the full __cause__/__context__ exception chain, so a generic RemoteException whose chained cause is a provider error (e.g. ResourceExhausted) is correctly classified. When chain walking yields no match, a new fallback reads the most recent __error__ entries from the managed LangGraph checkpoint DB at /sandbox/.deepagents/.state/sessions.db, recovering the original provider failure text that LangGraph strips during remote exception serialization.

PRA-2 (warning): Replaced hex(id(exc)) with a UUID4 correlation_id that has defined diagnostic scope across process boundaries.

PRA-3 (warning): Added a test verifying that classification results contain only fixed category fields — sensitive exception content (tokens, model names, message bodies) does not appear in the returned tuple.

New tests cover: chained exception classification, persisted checkpoint DB fallback (with temporary SQLite fixture), UUID correlation ID presence, and classification result non-disclosure.

[wscurran]

✨ Thanks for the fix. This adds structured error classification for known upstream provider errors in the managed DCode non-interactive path. Maintainers will review the classification logic and retryable flag design.

---

Related open issues:

• #7415 Managed DCode non-interactive API errors hide the persisted ResourceExhausted cause

[senthilr-nv]

Reviewed exact-head Advisor PRA-1; no code change. requirements.lock hash-locks deepagents-code==0.1.34, langgraph-api==0.10.0, and langgraph-checkpoint-sqlite==3.1.0, and the image installs them with --require-hashes. The patcher also rejects upstream source-marker drift. The runtime regression exercises the exact thread_id / channel / value query and the sanitized unknown fallback. This schema cannot drift independently of a reviewed dependency-lock update, so another source-shape assertion would duplicate the immutable pin without testing a distinct behavior boundary. Remove the workaround when upstream exposes the persisted cause through a bounded, sanitized non-interactive hook. I am treating this non-blocking architecture warning as advisory; independent human review remains required.

[senthilr-nv]

Approved for PR #7422 at exact head 0fed023 against base fac91e6. Product scope is established by #7415. I found no blocking review issues. Merge remains conditional on all required CI, E2E / PR Gate Coordination, and E2E / PR Gate passing for this exact SHA pair. Any head or base change requires renewed review and evidence.