Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
1fcb93c
feat(tui): show delegated child sessions clearly in the parent
nori-agent Nov 15, 2026
b6806ef
docs(tui): describe readable delegation, session trees and parent_ses…
nori-agent Nov 15, 2026
541911a
fix(tui): keep delegation results readable across frontends
nori-agent Nov 15, 2026
456b4d6
fix(tui): fit the attached child breadcrumb to the terminal width
nori-agent Nov 15, 2026
768df02
style(tui): spell the breadcrumb key hint as an if expression
nori-agent Nov 15, 2026
a61a000
fix(host): keep host ls aligned and titled at any terminal width
nori-agent Nov 15, 2026
444cbcd
fix(delegation): name finished, declined and delegating sessions plainly
nori-agent Nov 15, 2026
87d748b
fix(tui): fit session paths to the terminal and name sessions alike
nori-agent Nov 15, 2026
3137aaa
docs(tui): describe width-aware session paths, done status and host l…
nori-agent Nov 15, 2026
40837dc
fix(tui): keep narrow session lines within the width and titles alike…
nori-agent Nov 15, 2026
1224863
fix(tui): keep drafts across attach jumps and cut session names in th…
nori-agent Nov 15, 2026
4aae7d7
docs(tui): describe attach drafts, middle-cut names and the restarted…
nori-agent Nov 15, 2026
3c1e431
fix(tui): keep whole drafts and readable parent names when sessions s…
nori-agent Nov 15, 2026
985a39b
fix(tui): keep long session names apart in lists and let requests ans…
nori-agent Nov 16, 2026
f58a3ef
docs(tui): describe middle-cut list titles and request keys that answ…
nori-agent Nov 16, 2026
54fcdeb
fix(tui): hold the keyboard for a request shown in nori attach
nori-agent Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion docs/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,12 +134,14 @@ ACP v1 defines prompt turns but no agent-initiated turn primitive.
| Term | Definition | Aliases to avoid |
| -------------------- | ------------------------------------------------------------------------------------------------- | ------------------ |
| **Session envelope** | A session event tagged with its **conversation ID**, agent, and per-conversation sequence number. | Frame, message |
| **Session status** | A managed session's coarse state: starting, working, waiting on you, ready, failed, or closed. | Phase, turn status |
| **Session status** | A managed session's coarse state: starting, working, waiting on you, ready, failed, closed, or done (a delegated child whose task finished). | Phase, turn status |
| **Session family** | A top-level **session** plus all of its descendants, whose **session statuses** roll up into one. | Thread, tree |
| **Request resolved** | A **session envelope** announcing that a client answered a pending agent request, and which one. | Approval event |
| **Active session** | The one **session** the TUI shows; the prompt, terminal title, and scrollback belong to it. | Current tab |
| **Parked session** | A live **session** the TUI holds off screen with its own transcript, input, and pending requests. | Hidden, paused |
| **Session cap** | The most managed **sessions** that may run at once, set by `[tui] max_sessions`. | Limit, quota |
| **Delegated child** | A **session** the **session manager** starts for a parent through `/delegate` or the MCP `delegate` tool; named by the first line of its task. | Subagent, worker |
| **Delegation origin** | Who asked for a **delegated child**: the parent's agent (`agent`) or the user (`user`). | Requester, source |

### Session lifecycle

Expand Down Expand Up @@ -180,6 +182,7 @@ ACP v1 defines prompt turns but no agent-initiated turn primitive.
- A **request resolved** envelope removes that request from the ones keeping a **session status** at "waiting on you"; requests cleared by idle, cancel, or session end get none.
- When the **session manager** restarts a failed session, its **conversation ID**, family position, and envelope sequence continue across the new agent process. Remote targets, subscriptions, and replay cursors keep using that ID.
- With `[features] multi_session`, replacing the **active session** parks it instead of closing it; a **parked session** keeps running and receiving its events.
- A **delegated child** belongs to its parent's **session family** and, in the local TUI, is a **parked session** until the user moves to it; its result returns to the parent as a queued prompt.

### Example dialogue

Expand Down
67 changes: 54 additions & 13 deletions docs/remote-control.md
Original file line number Diff line number Diff line change
Expand Up @@ -336,8 +336,9 @@ prompts; the WebSocket extension controls sessions already owned by the TUI.
| `_nori/session/delegate` | Optional parent `session_id`, `agent`, `task` | Delegation record |
| `_nori/session/delegation/resolve` | Optional parent `session_id`, delegation `request_id`, `approved` boolean | Updated delegation record |

A list row reports identity, agent, status, cwd, lineage, pending request IDs,
`source`, delegation `depth`, the parent's `delegations`, sequence bounds (`latest_seq`, `first_available_seq`), age in seconds, and a
A list row reports identity, agent, status, `family_status` (the most urgent
status across the row's whole session family, rooted at its top-level session),
cwd, lineage, pending request IDs, `source`, delegation `depth`, the parent's `delegations`, sequence bounds (`latest_seq`, `first_available_seq`), age in seconds, and a
title derived from observed session activity. `replay_cursors` includes every
conversation known to the journal. Restarting a failed session with Ctrl+R keeps
its Nori conversation ID, list row, and sequence counter. Existing subscriptions
Expand Down Expand Up @@ -384,7 +385,11 @@ Agents without HTTP MCP support retain user-driven `/delegate`, but have no
stdio agent-tool fallback.

A delegation record contains `request_id`, `parent_id`, `child_id`,
`parent_agent`, `agent`, `task`, `depth`, `status`, and optional `result`.
`parent_agent`, `agent`, `task`, `depth`, `status`, optional `result`, and
`origin`. `origin` is `agent` when the parent agent called the MCP `delegate`
tool and `user` when the request came through the manager directly (`/delegate`
or `_nori/session/delegate`); records from hosts that predate the field
deserialize as `agent`. Clients use it only to word who asked for the child.
The child conversation ID is reserved before approval. The statuses are
`awaiting_approval`, `running`, `declined`, `completed`, `failed`, and
`cancelled`; these describe delegation state, separately from session status.
Expand All @@ -395,7 +400,8 @@ parent-only subscription does not become a subscription to every descendant.

Same-kind children start immediately. A different-kind request returns
`awaiting_approval`; resolve it for the requesting parent and request ID with
`approved: true` (Start) or `approved: false` (Decline). Only the controller may
`approved: true` or `approved: false` (the terminals label these
"Yes, start it" and "No, decline"). Only the controller may
request or resolve delegation. Unknown, resolved, or wrongly attributed
requests fail rather than starting another child. Approval does not reserve a
process indefinitely: actual startup must pass the shared session cap. Depth
Expand All @@ -409,10 +415,23 @@ the new parent identity.

A child's ACP permission request belongs to that child's conversation and
request ID. Answer it after selecting the child, with Alt+Down in the terminal
for next waiting session. Parent notices name the child and parent rather than
opening the child's permission popup in the parent. A completed child's result
is automatically queued as attributed input to the parent, including when the
parent is busy. The manager retains delivery until that parent's correlated
for next waiting session. Instead of opening the child's permission popup in
the parent, the parent receives a notice that names both sessions readably:
`<agent> · <child name> is waiting on you (delegated by <parent agent> · <parent
name>). Press Alt+Down to answer it.` The child name is the first non-empty
line of the task (else `new session`) and the parent name is its recorded
title, each cut to 40 characters in the middle (start, `…`, end) so names
sharing a long prefix stay distinct. A completed child's result is automatically queued as attributed
input to the parent, including when the parent is busy. That prompt's first
line is `[Nori delegation result] from <agent> · <child name> · <outcome>`
(`done`, `failed`, `declined`, or `cancelled`; the child name here is the
task's whole first line), its second is
`Child session: <child id>`, and the rest is the child's result text (its last
turn's message text, with a paragraph break wherever a tool call, permission
request, or other update interrupted it; for a crashed child, the first line of
its failure). A declined delegation never started a child, so its prompt has no
`Child session:` line. The parent's own ID is not included, and the prompt
never becomes the parent's title. The manager retains delivery until that parent's correlated
ACP prompt response, rather than treating queue admission as acknowledgment.
If the parent process crashes before acknowledgment, stable-ID resume submits
the result again. A delegated child with descendants waits for them and its
Expand All @@ -424,6 +443,9 @@ the parent's process has already failed. Parent crash preserves running
children and holds results until stable-ID resume (Ctrl+R). Child failure
returns a failure result without failing the parent. This state belongs to the
current manager lifetime; host restart does not restore it from transcripts.
After a restart a finished child is not listed by `nori host ls` or
`nori attach`, and `/resume` on its transcript reopens it as a live top-level
`ready` session without its parent link.

### Reconnect and retention

Expand Down Expand Up @@ -490,7 +512,7 @@ released after cleanup. Startup and stop do not require a terminal.
| Command | Behavior |
| --- | --- |
| `nori host` | Start the background host, or report the already-running host. |
| `nori host ls` | Print the flat `ID AGENT STATUS AGE TITLE` table; TTY output colors status and truncates titles to the terminal width, while piped output keeps full titles without color. |
| `nori host ls` | Print the `ID AGENT STATUS AGE TITLE` table with delegated children listed under their parent and `├─`/`└─`/`│` tree guides inside TITLE. Top-level rows show their `family_status` when the host sends it. TTY output colors status (waiting on you yellow, working cyan, ready green, failed red, done in the default color, starting and closed dimmed) and fits the terminal: IDs shorten and AGENT and STATUS cut with `…` as the width shrinks, AGE is never cut, and TITLE always gets the remaining cells, keeping its tree guide whole and cutting the name in the middle; piped output keeps full values without color and appends ` (parent <full id>)` to every row with a parent, including a child whose parent is no longer listed and so prints at top level. |
| `nori attach` | Open the host session list; requires `[features] multi_session = true`. |
| `nori attach <id>` | Open the named Nori conversation. |
| `nori attach --host <URL> --token-file <path>` | Connect to an explicit managed endpoint using a private token file. |
Expand Down Expand Up @@ -575,10 +597,29 @@ current session marker appears inside TITLE, leaving its short ID visible.
Session commands address the host; they do not launch local agents.
`/delegate <agent> <task>` is the delegation entry point; the list does not
start delegations. The configured `hotkeys.next_waiting_session` binding
(Alt+Down by default) selects the next waiting child or other session.
Delegated child rows prefix TITLE with the parent identity and hierarchy marker,
so long task titles cannot displace that identity; metadata columns remain fixed
in the attached list and `nori host ls`.
(Alt+Down by default) selects the next waiting child or other session, even
with an unsent draft (with nothing waiting, a draft keeps the key for the
composer), and
`hotkeys.parent_session` (Alt+Up by default) returns from a delegated child to
its parent. Both the attached list and `nori host ls` order children directly
under their parent and draw tree guides inside TITLE, so the ID, AGENT, STATUS,
and AGE columns stay aligned, and both show a top-level row's `family_status`.
Each session keeps its own unsent draft: switching sessions parks the
composer text with the session it was typed in and restores the target's.
The identity line names the selected session; a top-level session shows its
family status, as the lists do. Inside a delegated child (not a fork), it reads
as a breadcrumb of agents and names from the top-level session down to the
child. Both are fitted to the terminal width: the parent key gives way before
the current name is cut, and names are cut in the middle. A second line names
the next other session waiting on you, under its parent, with the jump key. A
delegated child whose task finished lists as `done` (default color); `closed`
(muted) means a session the user closed or shut down. A child's history ends
with `This child finished its task` or `This child session ended`, plus the
parent key. An attached parent shows a delivered result prompt as one
`› delegation result from <agent> · <name> · <status> · delivered to this
session` line, which drops the delivered suffix and then cuts the name to fit
one row. A running child's delegation card reads `started`, because cards are
printed once and do not update.

Socket loss or a receive-liveness deadline starts recovery. Periodic session
list requests keep idle connections observable; receiving JSON renews the
Expand Down
2 changes: 1 addition & 1 deletion justfile
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ test *args:
cd nori-rs && cargo test -p codex-core "$@"
;;
protocol)
cd nori-rs && cargo test -p codex-protocol "$@"
cd nori-rs && cargo test -p nori-protocol "$@"
;;
e2e)
cd nori-rs && cargo build --bin nori && cargo test -p tui-pty-e2e "$@"
Expand Down
2 changes: 2 additions & 0 deletions nori-rs/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions nori-rs/cli/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,7 @@ codex-execpolicy = { workspace = true }
codex-process-hardening = { workspace = true }
codex-stdio-to-uds = { workspace = true }
nori-tui = { workspace = true }
nori-tui-components = { workspace = true }
ctor = { workspace = true }
crossterm = { workspace = true }
unicode-segmentation = { workspace = true }
Expand Down
2 changes: 1 addition & 1 deletion nori-rs/cli/docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ PostHog identity or organization membership itself.
- TUI flags such as `--agent`, approval-bypass options, prompts, images, `-c`, and working-directory overrides can be passed after `resume`; they are merged into the normal interactive CLI configuration before `nori_tui::run_main()`

**Host and attach:** `nori host` starts a detached Unix process owning an empty
session manager; `host ls` reads its flat table and `host stop` shuts it down.
session manager; `host ls` prints its sessions as a tree-ordered table and `host stop` shuts it down.
The host outlives both attached terminals and its final session. `nori attach`
requires `multi_session`, discovers the local host and token, then opens the
session list or a supplied conversation ID. Explicit `--host` and
Expand Down
52 changes: 43 additions & 9 deletions nori-rs/cli/src/host/docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,13 +47,45 @@ host ls / host stop ---------------+ SessionManager
- Each start generates a token and binds loopback before publishing discovery
state. Administrative clients initialize with `observe: true`, so list and
stop do not claim the controller slot. [List formatting](table.rs) sanitizes
control characters and colors status only on a terminal. Terminal rows fit
the available display cells by truncating titles with an ellipsis at grapheme
boundaries; if metadata alone exceeds the width, that prefix is clipped.
Piped output retains full titles without color or a width limit. Delegated
child rows retain their own ID, agent, status, and age columns; the hierarchy
marker and parent identity prefix TITLE, so long task titles do not displace
parent attribution and indentation never shifts the metadata columns.
control characters and colors status only on a terminal. On a terminal the
ID, AGENT, STATUS, and AGE columns take one of three fixed layouts, chosen
as the widest that still leaves TITLE at least 24 cells:

| Layout | ID | AGENT | STATUS | AGE | Used when |
| --- | --- | --- | --- | --- | --- |
| Wide | 36 | 16 | 16 | 6 | TITLE keeps 24 cells; also every piped listing |
| Compact | 8 | 14 | 16 | 5 | Wide does not fit; matches the `nori attach` list |
| Tight | 8 | 10 | 14 | 4 | Neither fits |

The ID is shortened to the column, AGENT and STATUS are cut with `…`, and
AGE is never cut. TITLE, with its tree guides, gets whatever cells remain
(none only below the tight layout's metadata width). The guide stays whole
and the name is cut in the middle (start, `…`, end) at grapheme boundaries,
so titles sharing a long prefix still read apart; only when the room is no
wider than the guide is the whole title cut from the end. Status color applies on every row. Piped output
keeps full values in the wide layout, without color or a width limit.
- A top-level row (tree depth 0) shows the row's `family_status` when the host
sends one, so a parent reads `waiting on you` while anything under it does;
child rows always show their own `status`. Older hosts omit
`family_status`, and the row falls back to `status`.
- Rows are tree-ordered with the shared
[picker helpers](../../../tui-components/docs.md): `tree_order` builds a
depth-first order from each row's `session_id` and `parent` (a missing
parent makes the row top level), and `tree_guides` supplies `├─`, `└─`, and
`│` prefixes. The guides are written inside TITLE, after the fixed ID, AGENT,
STATUS, and AGE columns, so nesting never shifts metadata. Piped output appends
` (parent <full parent ID>)` to every row that has a parent, including a
child whose parent is no longer listed and so prints at top level, so scripts
keep the exact link; terminal output omits it.

| Status | Terminal color |
| --- | --- |
| waiting on you | yellow |
| working | cyan |
| ready | green |
| failed | red |
| done | default color, so a finished child reads apart from a closed one |
| others (starting, closed) | dimmed |
- Lifecycle requests prepare agents using the host's configuration. Resume
uses the stored agent and working directory while retaining the conversation
identity. Stop closes the server, shuts down the manager, removes discovery
Expand All @@ -72,11 +104,13 @@ host ls / host stop ---------------+ SessionManager
- Delegation requests pass through `ManagedRemoteHost` to the same manager
used by local sessions. Child sessions consume the ordinary session cap;
completing a child releases its process slot but preserves its listed record
and transcript. Closing a parent cancels descendants, while a parent crash
and transcript, and the row then reads `done` rather than `closed`. Closing a parent cancels descendants, while a parent crash
preserves children and holds their results for stable-ID resume.
- The host has no persistent manager snapshot. Transcripts survive normally,
but in-memory registry state and reconnect replay belong to the current host
process. The token rotates when that process starts again.
process. After a restart, earlier sessions, including finished delegated
children, are not listed; `/resume` on a child's transcript reopens it as a
live top-level `ready` session without its parent link. The token rotates when that process starts again.
- [Lifecycle tests](../../tests/host_lifecycle.rs) use isolated homes and
bounded process waits to cover detached startup, privacy, lock ownership,
occupied ports, and explicit stop.
Expand Down
Loading
Loading