feat(dcode): add managed non-interactive JSON envelope

[sandl99]

Summary

Make managed dcode -n <prompt> --json emit one bounded, schema-versioned JSON envelope instead of mixing assistant and progress text on stdout. The change preserves text mode, classifies terminal outcomes, and gives host-agnostic automation a fail-closed result boundary.

Related Issue

Fixes #7773

Changes

• Forward the public --json selection into the pinned Deep Agents Code non-interactive runtime and produce one schema version 1 envelope for success, agent failure, process failure, timeout, turn limit, cancellation, and output-limit outcomes.
• Add a bounded assistant-text capture layer for the managed automation consumer. Forwarding the flag alone is insufficient because upstream Deep Agents Code writes progress and assistant text through the same stdout surface; test/dcode-non-interactive-json.test.ts protects framing, status, timeout, cancellation, size-limit, and unchanged text-mode behavior.
• Update the live Deep Agents Code image smoke check to validate the structured PONG envelope for login-shell and direct-exec paths, rejecting any prefixed, suffixed, or multiple JSON documents.
• Document the in-sandbox and host-wrapper commands, schema, exit behavior, stderr boundary, and 1 MiB maximum output.

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:
• 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: Codex Desktop security review PASS for head 6d36977fd5a1eb003336a8d52752ec7f85fe3472; no findings. The constant-memory process-level stdout drain strengthens fail-closed framing without retaining untrusted output and introduces no credential, authorization, dependency, cryptography, or privilege changes. Earlier detailed review: feat(dcode): add managed non-interactive JSON envelope #7797 (comment)
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: The exact-head constant-memory pipe drain discards direct-descriptor and child-process stdout while retaining only an unexpected-output boolean, and the 2.4 MB regression preserves the single JSON envelope; docs/get-started/quickstart-langchain-deepagents-code.mdx and docs/reference/commands.mdx remain accurate; 33 focused tests and 152 broader managed-runtime tests passed, with 1 existing skip.
• Agent: Codex Desktop — managed Deep Agents Code headless automation

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

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 — command/result or justification: focused integration suite, 91 passed and 1 existing skip; earlier smoke suite, 32 passed; descriptor-boundary suite (npm exec -- vitest run test/dcode-non-interactive-json.test.ts test/langchain-deepagents-code-headless-runtime.test.ts test/langchain-deepagents-code-image.test.ts), 33 passed; broader managed-runtime suite, 152 passed with 1 existing skip.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: local npm test did not complete after two attempts because unrelated macOS/environment-sensitive suites timed out or required unavailable host services; GitHub CI remains authoritative
• 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: San Dang sdang@nvidia.com

Summary by CodeRabbit

• New Features

  • Added a managed --json output mode for non-interactive Deep Agents Code runs that emits exactly one schema-versioned JSON envelope, suppresses unintended stdout/progress, and enforces a 1 MiB bounded output limit with structured metadata.
  • Introduced distinct handling and classifications for success, timeouts vs cancellations, agent/process failures, and output-size overflow.

• Documentation

  • Expanded quickstart and command/reference docs with the JSON schema, status/exit-code behavior, stdout vs stderr rules, and envelope-limit semantics.

• Tests

  • Added end-to-end and headless acceptance coverage for the JSON success contract, error classification, output overflow behavior, and unchanged text-mode output.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Managed non-interactive dcode -n ... --json now propagates JSON mode, emits one bounded versioned envelope, classifies terminal outcomes, and suppresses unframed output. Fixtures, unit tests, headless checks, image assertions, and documentation validate the contract.

Changes

Managed DCode JSON output

Layer / File(s)	Summary
JSON execution path agents/langchain-deepagents-code/patch-managed-deepagents-code.py	The patcher forwards output format and timeout values, injects bounded JSON envelope handling, and validates and applies the required source transformations.
Fixture and JSON contract tests test/helpers/langchain-deepagents-code-patch-fixture.ts, test/dcode-non-interactive-json.test.ts	Fixtures model CLI forwarding and asynchronous execution; tests cover success, failures, cancellation, timeout, output limits, stdout suppression, and legacy text mode.
Headless envelope acceptance test/langchain-deepagents-code-headless-runtime.test.ts, test/e2e/e2e-cloud-experimental/checks/07-deepagents-code-headless-inference.sh, test/langchain-deepagents-code-image.test.ts	Headless checks require a single valid JSON PONG envelope with matching response metadata and reject invalid or nonzero-exit results.
JSON mode documentation docs/get-started/quickstart-langchain-deepagents-code.mdx, docs/reference/commands.mdx	Documentation describes the envelope schema, terminal statuses, exit behavior, wrapper forwarding, and 1 MiB output limit.

Estimated code review effort: 4 (Complex) | ~45 minutes

Suggested labels: integration: dcode, area: cli, area: security, feature, needs: review, v0.0.98

Suggested reviewers: cv

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant DcodeCLI
  participant run_non_interactive
  participant JSONRunner
  participant Stdout
  Client->>DcodeCLI: invoke dcode -n task --json
  DcodeCLI->>run_non_interactive: pass output_format and timeout
  run_non_interactive->>JSONRunner: collect response and classify status
  JSONRunner->>Stdout: write one bounded JSON envelope
  DcodeCLI-->>Client: return envelope and exit code

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR implements managed dcode -n --json framing, status/exit handling, stdout suppression, limits, and tests/docs required by #7773.
Out of Scope Changes check	✅ Passed	The changes stay focused on the JSON-mode runtime, fixtures, tests, and docs, with no clear unrelated functionality added.
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 and concisely summarizes the main change: managed non-interactive JSON envelope support for dcode.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Fix failing CI checks

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/7773-dcode-json-envelope

---

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

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-7797.docs.buildwithfern.com/nemoclaw

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 7383493 in the feat/7773-dcode-json... branch remains at 96%, unchanged from commit 2306ad0 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 7383493 in the feat/7773-dcode-json... branch remains at 81%, unchanged from commit 5aacf53 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 5aacf53	feat/7773-dcode-json... 7383493	+/-
src/lib/onboard...ndbox-create.ts	83%	33%	-50%
src/lib/onboard...box-prebuild.ts	92%	74%	-18%
src/lib/actions...ocker-health.ts	82%	65%	-17%
src/lib/actions...confirmation.ts	79%	69%	-10%
src/lib/onboard...ndbox-create.ts	91%	83%	-8%
src/lib/onboard...box-gpu-mode.ts	97%	92%	-5%
src/lib/actions...light-guards.ts	90%	86%	-4%
src/lib/onboard/preflight.ts	80%	80%	0%
src/lib/onboard...host-anchors.ts	90%	94%	+4%
src/lib/onboard/docker-cdi.ts	70%	80%	+10%

---

_{Updated July 29, 2026 14:16 UTC}

[sandl99]

Security review: PASS

Reviewed PR head 94643281f4650adcc574e95588543789960e314f.

The managed DCode JSON-envelope change is safe to merge from a security perspective, subject to normal CI. The review found no vulnerability or security warning. The implementation reduces stdout ambiguity, bounds serialized output, suppresses unframed progress, omits partial assistant content on failures, and avoids exposing exception details.

Findings

No findings.

Detailed analysis

1. Secrets and credentials — PASS. No credentials or secret files were added. Secret-shaped values are synthetic test patterns, and failure tests verify private exception text does not reach stdout or stderr.
2. Input validation and data sanitization — PASS. The public parser continues to validate --json and timeout inputs. JSON serialization uses the standard library with escaping enabled, and the smoke parser requires the exact schema, command, data, and completion fields.
3. Authentication and authorization — PASS. The change adds no endpoint, identity, permission, or authorization path. Existing managed runtime restrictions remain in force.
4. Dependencies and third-party libraries — PASS. No dependency or package-version change was introduced.
5. Error handling and logging — PASS. Failures emit fixed diagnostics without exception text, set response to null, and retain nonzero exit behavior. Timeout and cancellation are classified separately.
6. Cryptography and data protection — PASS. No cryptographic primitive or sensitive-data persistence was introduced.
7. Configuration and security headers — PASS. No service, container, port, origin, policy, or runtime-permission configuration changed.
8. Security testing — PASS. Tests cover exact one-object framing, progress suppression, escaped Unicode/control content, agent and process failures, redaction, timeout, cancellation, turn limits, output limits, malformed smoke envelopes, and unchanged text mode.
9. System security — PASS. The implementation preserves the managed shell/tool restrictions, fails closed when the envelope cannot be bounded or written, and keeps the JSON behavior scoped to a single non-interactive CLI run.

Files reviewed

• agents/langchain-deepagents-code/patch-managed-deepagents-code.py
• docs/get-started/quickstart-langchain-deepagents-code.mdx
• docs/reference/commands.mdx
• test/dcode-non-interactive-json.test.ts
• test/e2e/e2e-cloud-experimental/checks/07-deepagents-code-headless-inference.sh
• test/helpers/langchain-deepagents-code-patch-fixture.ts
• test/langchain-deepagents-code-headless-runtime.test.ts
• test/langchain-deepagents-code-image.test.ts

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 4 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 4 more warnings, 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: cloud-inference, cloud-onboard, security-posture, inference-routing, network-policy, ubuntu-repo-cloud-langchain-deepagents-code

Workflow run details

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

[coderabbitai]

🧹 Nitpick comments (3)

test/helpers/langchain-deepagents-code-patch-fixture.ts (1)

489-497: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Name the fixture-json-task sentinel where it is shared.

The magic message string couples this fixture to test/dcode-non-interactive-json.test.ts line 57 with no link between them; a rename on either side silently degrades the CLI-forwarding test into a kwargs-returning path rather than failing loudly. Exporting the sentinel from the helper and referencing it in the test would keep the contract explicit.

🤖 Prompt for 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.

In `@test/helpers/langchain-deepagents-code-patch-fixture.ts` around lines 489 -
497, Export a shared sentinel constant from the fixture helper and update the
`fixture-json-task` check in `_run_non_interactive_impl` to use it. Import and
reference that same constant in `test/dcode-non-interactive-json.test.ts` so the
CLI-forwarding contract remains explicit and renames cannot silently diverge.

test/langchain-deepagents-code-image.test.ts (1)

825-832: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

These per-key substring assertions lock in the validator's source text, not its behavior.

test/langchain-deepagents-code-headless-runtime.test.ts already proves the classifier accepts only a well-formed envelope, so the eight quoted key literals here add brittleness without coverage: reordering the set(envelope) != {...} literal or switching to single quotes in the embedded Python breaks this test while behavior is unchanged. Asserting that the image ships the --json invocation (Line 766) plus one envelope-shape marker would be enough.

As per path instructions, "Prefer observable outcomes through the public boundary over source-text, private-shape, or mock-call assertions."

🤖 Prompt for 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.

In `@test/langchain-deepagents-code-image.test.ts` around lines 825 - 832, Replace
the eight per-key substring assertions in the image validation test with a
behavioral assertion at the public boundary: retain the check that the image
includes the --json invocation and add one representative envelope-shape marker.
Remove assertions tied to the validator’s exact source formatting while
preserving coverage that the expected envelope structure is present.

Source: Path instructions

test/dcode-non-interactive-json.test.ts (1)

96-97: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Surface driver stderr when the spawned process fails.

Every test gates on expect(result.status).toBe(0) while the real diagnosis (Python traceback or a failed in-driver assert) sits in result.stderr. Asserting on a combined value keeps failures self-explanatory instead of showing only 0 !== 1.

♻️ Example

-    expect(result.status).toBe(0);
+    expect({ status: result.status, stderr: result.stderr }).toMatchObject({ status: 0 });

🤖 Prompt for 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.

In `@test/dcode-non-interactive-json.test.ts` around lines 96 - 97, Update the
result.status assertion in the test flow before parseEnvelope(result.stdout) to
surface result.stderr when the spawned process fails, while preserving the
successful status check and envelope parsing behavior.

🤖 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.

Nitpick comments:
In `@test/dcode-non-interactive-json.test.ts`:
- Around line 96-97: Update the result.status assertion in the test flow before
parseEnvelope(result.stdout) to surface result.stderr when the spawned process
fails, while preserving the successful status check and envelope parsing
behavior.

In `@test/helpers/langchain-deepagents-code-patch-fixture.ts`:
- Around line 489-497: Export a shared sentinel constant from the fixture helper
and update the `fixture-json-task` check in `_run_non_interactive_impl` to use
it. Import and reference that same constant in
`test/dcode-non-interactive-json.test.ts` so the CLI-forwarding contract remains
explicit and renames cannot silently diverge.

In `@test/langchain-deepagents-code-image.test.ts`:
- Around line 825-832: Replace the eight per-key substring assertions in the
image validation test with a behavioral assertion at the public boundary: retain
the check that the image includes the --json invocation and add one
representative envelope-shape marker. Remove assertions tied to the validator’s
exact source formatting while preserving coverage that the expected envelope
structure is present.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 9f933171-f3ca-48ae-babe-9108838cbba5

📥 Commits

Reviewing files that changed from the base of the PR and between eeab81c and 9464328.

📒 Files selected for processing (8)

• agents/langchain-deepagents-code/patch-managed-deepagents-code.py
• docs/get-started/quickstart-langchain-deepagents-code.mdx
• docs/reference/commands.mdx
• test/dcode-non-interactive-json.test.ts
• test/e2e/e2e-cloud-experimental/checks/07-deepagents-code-headless-inference.sh
• test/helpers/langchain-deepagents-code-patch-fixture.ts
• test/langchain-deepagents-code-headless-runtime.test.ts
• test/langchain-deepagents-code-image.test.ts

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

test/e2e/e2e-cloud-experimental/checks/07-deepagents-code-headless-inference.sh (1)

598-598: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Delimit the injected exit marker from JSON output.

If dcode --json emits a valid envelope without a final newline, Line 598 produces }DCODE_EXIT:0; Lines 370-373 cannot strip that marker, so this compliant envelope is rejected. Print a leading newline before the marker and add a no-final-newline regression case.

Proposed fix

-headless_output="$(sandbox_login_exec "cd /sandbox && timeout ${HEADLESS_TIMEOUT} dcode -n 'Reply with exactly one word: PONG' --json; echo \"DCODE_EXIT:\$?\"" || true)"
+headless_output="$(sandbox_login_exec "cd /sandbox && timeout ${HEADLESS_TIMEOUT} dcode -n 'Reply with exactly one word: PONG' --json; dcode_status=\$?; printf '\nDCODE_EXIT:%s\n' \"\$dcode_status\"" || true)"

🤖 Prompt for 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.

In
`@test/e2e/e2e-cloud-experimental/checks/07-deepagents-code-headless-inference.sh`
at line 598, Update the headless_output capture command to print a leading
newline before the DCODE_EXIT marker, ensuring the marker is separated from JSON
even when dcode emits no trailing newline. Add a regression case covering a
valid JSON envelope without a final newline and verify the existing
marker-stripping logic accepts it.

🤖 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
`@test/e2e/e2e-cloud-experimental/checks/07-deepagents-code-headless-inference.sh`:
- Around line 414-418: Strengthen envelope validation after JSON parsing so each
required field has the exact declared type and content: reject booleans where
numeric values are expected, require integer values for schema_version,
duration_ms, exit_code, and response_bytes as appropriate, and require the
health response string to equal PONG without surrounding whitespace. Update the
validation logic around the existing envelope checks and preserve rejection of
non-dict envelopes and other malformed values.

---

Outside diff comments:
In
`@test/e2e/e2e-cloud-experimental/checks/07-deepagents-code-headless-inference.sh`:
- Line 598: Update the headless_output capture command to print a leading
newline before the DCODE_EXIT marker, ensuring the marker is separated from JSON
even when dcode emits no trailing newline. Add a regression case covering a
valid JSON envelope without a final newline and verify the existing
marker-stripping logic accepts it.

🪄 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: eecf8cfa-35bb-459a-9816-52a73a2aa149

📥 Commits

Reviewing files that changed from the base of the PR and between 84c325d and a2bf825.

📒 Files selected for processing (2)

• test/e2e/e2e-cloud-experimental/checks/07-deepagents-code-headless-inference.sh
• test/langchain-deepagents-code-headless-runtime.test.ts