docs: cover mid-session forking (/branch + praisonai session fork) - #2734
Conversation
|
@coderabbitai review |
|
/review |
✅ Action performedReview finished.
|
Qodo reviews are paused for this user.Troubleshooting steps vary by plan Learn more → On a Teams plan? Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center? |
MervinPraison
added
pipeline/awaiting-merge-gate
|
Important Review skippedBot user detected. To trigger a single review, invoke the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughThe documentation adds session forking guidance for the REPL and CLI. It covers fork points, parent-child lineage, JSON output, validation, errors, related commands, and navigation. ChangesSession Forking Documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related issues
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches 💡 1⚔️ Resolve merge conflicts 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 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 `@docs/cli/interactive-tui.mdx`:
- Around line 162-164: Update the `/help` output example in the interactive TUI
documentation to include both `/branch` and `/session`, matching the command
table; alternatively, clearly mark the transcript as abbreviated.
In `@docs/cli/session.mdx`:
- Line 186: Update the later JSON output (--json) example in
docs/cli/session.mdx to include a "parent_id": null field in each session
record, keeping it consistent with the session list --json description and the
existing specimen structure.
In `@docs/features/session-forking.mdx`:
- Around line 102-105: Update the Store return step in the fork_session sequence
diagram to describe the returned value as the forked session ID, not a fork
session object, while leaving the surrounding session rebinding flow unchanged.
- Around line 155-170: Add a Default column to both fork option tables in
docs/features/session-forking.mdx (lines 155-170) and docs/cli/session.mdx
(lines 249-253), documenting the SDK defaults for every option. Include None for
from_message_index/--at-message and title, and the appropriate defaults for the
remaining options; update each table’s header and rows consistently.
🪄 Autofix
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: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: b1ed8959-dcc0-42aa-a48b-6f7ec55e1d05
📒 Files selected for processing (4)
docs/cli/interactive-tui.mdxdocs/cli/session.mdxdocs/docs.jsondocs/features/session-forking.mdx
| | `/branch [title]` | Fork the current conversation here and switch onto the fork; parent stays resumable | | ||
| | `/branch --at N` | Fork from N user turns back | | ||
| | `/session` | Show current session info, including `Forked from:` / `Forks:` lineage when set | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Keep the /help example consistent with the command table.
The table now lists /branch and /session, but the /help output below omits both commands. Add them to the output or mark the transcript as abbreviated.
🤖 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 `@docs/cli/interactive-tui.mdx` around lines 162 - 164, Update the `/help`
output example in the interactive TUI documentation to include both `/branch`
and `/session`, matching the command table; alternatively, clearly mark the
transcript as abbreviated.
| | `--all` | Show sessions from all projects | | ||
| | `--project <id>` | Show sessions for a specific project ID — that project's store only | | ||
| | `--json` | Output as JSON (includes `usage`, `total_tokens`, and `cost` per session) | | ||
| | `--json` | Output as JSON (includes `usage`, `total_tokens`, `cost`, and `parent_id` per session) | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Keep both session list --json examples consistent.
This line says every session record includes parent_id. The later JSON output (--json) example at lines 147-164 omits that field. Add "parent_id": null to that specimen.
🤖 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 `@docs/cli/session.mdx` at line 186, Update the later JSON output (--json)
example in docs/cli/session.mdx to include a "parent_id": null field in each
session record, keeping it consistent with the session list --json description
and the existing specimen structure.
| REPL->>Store: fork_session(current_id, ...) | ||
| Store->>Fork: Create with parent_id set | ||
| Store-->>REPL: fork session object | ||
| REPL->>REPL: Rebind session + reload history |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Correct the store return value in the diagram.
HierarchicalSessionStore.fork_session returns the new session ID as str. Change “fork session object” to “forked session ID.”
🤖 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 `@docs/features/session-forking.mdx` around lines 102 - 105, Update the Store
return step in the fork_session sequence diagram to describe the returned value
as the forked session ID, not a fork session object, while leaving the
surrounding session rebinding flow unchanged.
| | Option | Type | Description | | ||
| |--------|------|-------------| | ||
| | `[title]` | `str` | Optional name for the fork (anything after the command that isn't `--at N`). | | ||
| | `--at N` / `-a N` | `int` | Fork from `N` **user turns** back. Must be `> 0` and `≤` total user turns. | | ||
|
|
||
| **`praisonai session fork` — CLI verb** | ||
|
|
||
| ```bash | ||
| praisonai session fork <session_id> [--at-message N] [--title "..."] | ||
| ``` | ||
|
|
||
| | Argument / Flag | Type | Description | | ||
| |-----------------|------|-------------| | ||
| | `session_id` | `str` | Session to fork. Resolved project store first, then global. | | ||
| | `--at-message N` | `int` | Fork from this **0-based message index**. Valid range is `0..count-1`. | | ||
| | `--title "..."` | `str` | Optional title for the forked session. | |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
ast-grep outline praisonaiagents/session/hierarchy.py --items all
ast-grep outline praisonai_code/cli --items all --type function --match 'fork|session'
rg -n -C 8 --type py '\bfork_session\s*\(|at_message|at-message|session.*fork' \
praisonai_code/cli praisonaiagents/session/hierarchy.pyRepository: MervinPraison/PraisonAIDocs
Length of output: 42426
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Files matching session.*mdx:"
fd -a 'session.*\.mdx$' docs/features docs/cli 2>/dev/null | sed 's#^\./##' || true
echo
echo "Relevant option tables:"
if [ -f docs/features/session-forking.mdx ]; then
sed -n '140,180p' docs/features/session-forking.mdx
fi
if [ -f docs/cli/session.mdx ]; then
sed -n '235,258p' docs/cli/session.mdx
fi
echo
echo "Search docs for session fork defaults/required/no:"
rg -n --type mdx '\s*(Default\s*=|Default:)|\bRequired\b|No Default|None' docs/features docs/cli || trueRepository: MervinPraison/PraisonAIDocs
Length of output: 4293
Add the missing Default values to fork tables.
Both fork tables should include the SDK default for each option, including the None defaults for from_message_index / --at-message and title.
docs/features/session-forking.mdx#L155-L170: add a Default column to the REPL and CLI option tables.docs/cli/session.mdx#L249-L253: add a Default column to thesession forkoption table.
📍 Affects 2 files
docs/features/session-forking.mdx#L155-L170(this comment)docs/cli/session.mdx#L249-L253
🤖 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 `@docs/features/session-forking.mdx` around lines 155 - 170, Add a Default
column to both fork option tables in docs/features/session-forking.mdx (lines
155-170) and docs/cli/session.mdx (lines 249-253), documenting the SDK defaults
for every option. Include None for from_message_index/--at-message and title,
and the appropriate defaults for the remaining options; update each table’s
header and rows consistently.
Source: Coding guidelines
|
Automated merge-conflict rebase started (in-band Claude). Rebasing onto latest |
…ssion fork CLI verb (fixes #2733) Add docs/features/session-forking.mdx and update session.mdx and interactive-tui.mdx to document /branch, praisonai session fork, fork lineage (parent_id/children_ids, session list Parent column, /session Forked from/Forks), and guardrails. Verified against PraisonAI merge commit 6ca4b97. Co-authored-by: MervinPraison <MervinPraison@users.noreply.github.com>
e2d6181 to
71acf79
Compare
|
Rebase complete ✓ Resolved merge conflicts and rebased Files resolved:
Auto-merged cleanly:
Verified:
|
MervinPraison
added
pipeline/blocked:ci
|
Merge gate scan — eligible for assessment. Claude merge gate will assess and may auto-merge on an APPROVE verdict. |
MervinPraison
added
claude-merge-gate-active
pipeline/awaiting-merge-gate
|
MERGE_GATE_VERDICT: APPROVE Review summary
Content quality: |
MervinPraison
added
pipeline/merge-ready
|
Merged by Claude PR merge gate ( |
|
Merge gate scan — not eligible for auto-merge.
Actions: wait for CI and the Claude review chain, or add label |
1 participant
Fixes #2733
Summary
docs/features/session-forking.mdx— the mid-session forking feature page (hero mermaid,<Steps>Quick Start, choice-guide + sequence diagrams, guardrails, JSON output,<AccordionGroup>best practices,<CardGroup>related).docs/cli/session.mdx— new Fork a Session section (praisonai session fork <id> [--at-message N] [--title]),session listParent column added to sample output / notes /--json, forked-child line linked, help block + Related card updated.docs/cli/interactive-tui.mdx—/branch [title],/branch --at N, and/sessionlineage rows added to the command table; Related link added.docs/docs.json—features/session-forkingadded under the Features → State & Sessions group.Source verification
Verified against PraisonAI merge commit
6ca4b97:/branch [title]/--at N(-a N, positive, ≤ user turns), worker-busy refusal,No active session/Could not forkfallbacks —interactive_legacy.py::_handle_branch_command.session fork <id> --at-message N(0-based, validated0..count-1),--title, JSON{forked, parent_id, session_id, from_message_index, title}—commands/session.py::session_fork.session listParent column (8-char prefix,-for root) + JSONparent_id;/sessionprintsForked from:/Forks:.All new pages placed in
docs/features/(neverdocs/concepts/).docs.jsonvalidated as JSON.Generated with Claude Code
Summary by CodeRabbit
/branch,/branch --at N, andsession forkcommands, including options, validation, errors, and JSON output.