Skip to content

docs: document agent session state paths#4116

Merged
cv merged 2 commits into
NVIDIA:mainfrom
glenn-agent:docs/session-state-paths
Jun 3, 2026
Merged

docs: document agent session state paths#4116
cv merged 2 commits into
NVIDIA:mainfrom
glenn-agent:docs/session-state-paths

Conversation

@glenn-agent

@glenn-agent glenn-agent commented May 23, 2026 •
edited by coderabbitai Bot
Loading

Copy link
Copy Markdown
Contributor

Summary

  • Document where agent session state is stored inside the sandbox: session JSONL, trajectory JSONL, and sessions.json.
  • Add host-side examples for inspecting and downloading those files with nemoclaw.
  • Warn that exported session logs may contain prompts, tool outputs, file paths, and other sensitive runtime context.

Related issue

Fixes #3978

Validation

  • npm run docs
  • git diff --check HEAD~1..HEAD
  • python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx --dry-run

Signed-off-by: Glenn-Agent glenn_agent@163.com

Summary by CodeRabbit

  • Documentation
    • Added guidance for inspecting agent session state in the sandbox, describing per-session JSONL event logs, trajectory data, and session index usage.
    • Clarified the differences between lifecycle/gateway logs and exported per-session state.
    • Added host-side commands to list and download session logs for offline review.
    • Included a security advisory about sensitive content in exported logs.

@glenn-agent
docs: document agent session state paths
457848f 
Signed-off-by: Glenn-Agent <glenn_agent@163.com>
@copy-pr-bot

copy-pr-bot Bot commented May 23, 2026

Copy link
Copy Markdown

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

coderabbitai Bot commented May 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 2f4e9f73-83ee-4906-b0b2-5749773ae047

📥 Commits

Reviewing files that changed from the base of the PR and between 457848f and 2d948b0.

📒 Files selected for processing (1)
  • docs/monitoring/monitor-sandbox-activity.mdx
💤 Files with no reviewable changes (1)
  • docs/monitoring/monitor-sandbox-activity.mdx
📝 Walkthrough

Walkthrough

Adds docs to clarify that nemoclaw <name> logs streams gateway lifecycle output but not per-session agent state, and adds an "Inspect Agent Session State" section describing sandbox paths, file purposes, host commands to list/download session logs, and a sensitivity warning.

Changes

Agent Session State Inspection Documentation

Layer / File(s) Summary
Session state inspection guide
docs/monitoring/monitor-sandbox-activity.mdx		 Clarifies that nemoclaw logs excludes structured per-session agent state. Adds "Inspect Agent Session State" with sandbox paths (.openclaw/agents/main/sessions/), explanations of <session-id>.jsonl, <session-id>.trajectory.jsonl, and sessions.json, host-side commands to list and download session logs, and a warning about sensitive contents (prompts, tool I/O, file paths, cost metadata).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Suggested labels

documentation

Poem

A rabbit whispers by the log-lined trail,
"Sessions live in hidden JSON mail.
List, fetch, and read with cautious care—
Prompts and traces sleeping there.
Hoppy findings, neatly shown! 🐇✨"

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely summarizes the main change: documenting agent session state paths in the docs.
Linked Issues check ✅ Passed The pull request fully addresses issue #3978 by documenting agent session state paths, explaining where files are stored, clarifying how logs differ from session state, and including host-side inspection examples.
Out of Scope Changes check ✅ Passed All changes are directly related to the documentation objective; only one file (docs/monitoring/monitor-sandbox-activity.mdx) was modified to add the requested documentation without unrelated alterations.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Comment @coderabbitai help to get the list of available commands and usage tips.

@wscurran

wscurran commented May 26, 2026

Copy link
Copy Markdown
Contributor

✨ Thanks for submitting this detailed PR about documenting agent session state paths. This proposes a way to improve documentation by adding guidance on inspecting agent session state stored in the sandbox and providing host-side commands for session log management.

Related open issues:

1 similar comment
@wscurran

wscurran commented May 26, 2026

Copy link
Copy Markdown
Contributor

✨ Thanks for submitting this detailed PR about documenting agent session state paths. This proposes a way to improve documentation by adding guidance on inspecting agent session state stored in the sandbox and providing host-side commands for session log management.

Related open issues:

@wscurran wscurran added the v0.0.58 Release target label Jun 2, 2026
@wscurran wscurran added bug-fix PR fixes a bug or regression area: docs Documentation, examples, guides, or docs build and removed fix labels Jun 3, 2026
@cjagwani cjagwani requested a review from miyoungc June 3, 2026 19:20
cjagwani
cjagwani approved these changes Jun 3, 2026
View reviewed changes

@cjagwani cjagwani left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving — clear docs add for the session state files + correct host-side inspection/download commands, with the right "treat as sensitive" warning. Fixes #3978.

@cv cv merged commit dfe498f into NVIDIA:main Jun 3, 2026
18 of 20 checks passed
@miyoungc miyoungc mentioned this pull request Jun 4, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cjagwani cjagwani cjagwani approved these changes

@miyoungc miyoungc Awaiting requested review from miyoungc

Assignees

@cjagwani cjagwani

Labels

area: docs Documentation, examples, guides, or docs build bug-fix PR fixes a bug or regression v0.0.58 Release target

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[docs] Agent session JSONL / trajectory paths are stable but undocumented

4 participants

@glenn-agent @wscurran @cjagwani @cv