iris is the framework alone; the app is one crate in app-rust/
Iris: "the organization of the rust rewrite is a mess right now... there shouldn't be anything related to the app inside of iris. Iris is supposed to be the UI framework alone." And, on the crate count: "I'm confused why the app only code needs more than one crate though." Nine cargo workspaces become three, and the port's project code -- which sat in five places, four of them inside the framework -- becomes one crate, `ai-app`, in `app-rust/`: client-core -> app-rust/src/client iris/transcript-ui -> app-rust/src/ui iris/transcript-fixture -> app-rust/src/ui/fixture.rs + tests/ + touch/ iris/desktop-app -> app-rust/src/desktop + src/bin_desktop.rs iris/android-app -> app-rust/src/android + android-project/ android-shell -> app-rust/src/shell iris/ keeps core, macro, the iris crate, tabs-ui and rig-input, and now mentions no session, transcript, setup or server anywhere. Only two of the old splits had a reason that survived reading. event-model stays a crate at the repo root because server/ depends on it too, so a crate is what makes the backend and the app agree by construction. The two Android .so names looked like a hard constraint -- a package produces one library artifact -- until P2 turned out to already plan merging those two Android apps into one; both faces now come out of libai_app.so, picked apart by features so `--no-default-features --features shell` keeps wgpu, parley and iris out of the Compose app's APK. docs/RUST.md's "One app crate" has the rest, including what each remaining feature is for. DECISIONS.md and SUBAGENTS.md move into docs/ with everything else. Verified: ./run-tests.sh and `cd iris && cargo test` green, clippy and fmt clean in all five workspaces, `cargo ndk -t x86_64` links libai_app.so, build-apk.sh produces an APK that installs and launches on this checkout's emulator (Gl ... virgl, as expected), and the phone-sized headless screenshot renders the transcript unchanged. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
irisandClaude Opus 5 committed
1 parent
e9a6562dc6
commit
6d5a231f5c
100 files changed
+924
-3295
No files matched your search
+29
-24
@@ -1,21 +1,26 @@
|
||||
# client-core
|
||||
# `app-rust`'s `client` module
|
||||
|
||||
`client-core/` is the app's pure logic held once instead of twice, per
|
||||
RUST.md's recommendation item 1. It is a plain Rust library crate with no UI
|
||||
framework dependency of any kind, so it can outlive whichever one the app
|
||||
ends up drawing with (Masonry, iris, or something else -- see RUST.md).
|
||||
`event-model/` is its sibling: the wire shape both this crate and `server/`
|
||||
share, extracted from `server/src/session/driver.rs` and
|
||||
`session/transcript.rs` on 2026-09-04.
|
||||
**Renamed 2026-09-08.** This was the `client-core` crate; it is now
|
||||
`app-rust/src/client/`, a module of the one app crate rather than a crate
|
||||
of its own (docs/RUST.md's "One app crate"). Nothing about what it *is*
|
||||
changed: it is still the app's pure logic held once instead of twice, per
|
||||
RUST.md's recommendation item 1, and still has **no UI framework
|
||||
dependency of any kind** -- the `iris` dependency sits behind the `screens`
|
||||
feature and nothing under `src/client` may reach it. That independence is
|
||||
what lets it outlive whichever framework the app draws with, and it is now
|
||||
an invariant of a module rather than of a manifest, so it is worth stating
|
||||
plainly: a `use iris::` under `src/client/` is a defect.
|
||||
|
||||
Neither crate is wired into anything yet. `server/` re-exports `event-model`
|
||||
so its own behaviour is unchanged (`./run-tests.sh` covers it); `client-core`
|
||||
has no caller -- it exists for whichever experiment in RUST.md picks it up
|
||||
next (a Masonry or iris transcript screen, most likely).
|
||||
`event-model/` stayed a crate, and is the one split in the port that was
|
||||
never optional: it is the wire shape both this app and `server/` depend on,
|
||||
extracted from `server/src/session/driver.rs` and `session/transcript.rs`
|
||||
on 2026-09-04, so a crate is what makes the two agree by construction.
|
||||
|
||||
Paths below are written as `src/client/…`, relative to `app-rust/`.
|
||||
|
||||
## What's here, and what Kotlin file it replaces
|
||||
|
||||
| `client-core/src/…` | Kotlin original | Status |
|
||||
| `src/client/…` | Kotlin original | Status |
|
||||
|------------------------------------------|-------------------------------------------|--------|
|
||||
| `event-model/src/lib.rs` (shared crate) | `Events.kt` (the enum mirror) | Done |
|
||||
| `ansi.rs` | `Ansi.kt` | Done, ported test-for-test |
|
||||
@@ -118,7 +123,7 @@ has no `Unknown`/catch-all variant, unlike `Events.kt`'s hand-kept mirror.
|
||||
A server newer than this build that adds an event type will fail to parse
|
||||
that line rather than degrading to a placeholder row. Closing this means
|
||||
deciding how `event_model` itself represents "a shape I don't recognise"
|
||||
-- a shared-model decision affecting `server/` too, not a `client-core`-only
|
||||
-- a shared-model decision affecting `server/` too, not a `client`-only
|
||||
fix, so it is recorded here rather than silently worked around.
|
||||
|
||||
## `config.rs`: `EnrolledServer`
|
||||
@@ -130,11 +135,11 @@ parses on the phone -- so any Rust client enrols from the same text a
|
||||
phone would scan as a QR, with no second format invented for it (RUST.md's
|
||||
E4, DECISIONS.md 2026-09-05). Deliberately does not decide where it is
|
||||
persisted or under what file permissions -- a phone seals its token in the
|
||||
Android Keystore, `iris/desktop-app/src/config.rs` writes it to
|
||||
Android Keystore, `src/desktop/config.rs` writes it to
|
||||
`$XDG_CONFIG_HOME/ai-app-desktop/enrollment.json` at 0600 -- since that is
|
||||
caller-specific (the code rules' "ask for the least you need"). Its only
|
||||
caller today is `desktop-app`; a future Android build of this crate would
|
||||
be a second one, not a reason to move the type.
|
||||
caller today is `src/desktop`; the Android entry point is a second one, not
|
||||
a reason to move the type.
|
||||
|
||||
## What `transcript_source.rs` covers, and what it does not
|
||||
|
||||
@@ -184,7 +189,7 @@ thread. Both are wall-clock/thread-lifetime policy that belongs to
|
||||
whichever runtime embeds this crate (iris's own timers, a Tokio task, a
|
||||
Kotlin coroutine scope), not to this pure logic -- `follow` is the same
|
||||
"write to the cache, then hand the frame to the caller" decorator
|
||||
`iris/desktop-app/src/app.rs` and `iris/android-app/src/transcript_client.rs`
|
||||
`src/desktop/app.rs` and `src/android/transcript_client.rs`
|
||||
already hand-wrote around `event_stream::follow_session_events` before this
|
||||
existed; the cache write moved into one shared place so a third caller
|
||||
does not repeat it again by hand.
|
||||
@@ -198,7 +203,7 @@ does not repeat it again by hand.
|
||||
block instead of the message (docs/RUST.md's Task B). What it
|
||||
deliberately does **not** build is the tree below that: nested list
|
||||
items, table cells, inline spans. Inline styling is still the renderer's
|
||||
own job per block (`iris/transcript-ui/src/markdown.rs`), and nothing
|
||||
own job per block (`src/ui/markdown.rs`), and nothing
|
||||
has needed the rest yet. `CodeFence.kt`'s use of `org.intellij.markdown`
|
||||
for a full CommonMark AST is Compose rendering plumbing, not something
|
||||
to port as-is.
|
||||
@@ -209,8 +214,8 @@ does not repeat it again by hand.
|
||||
|
||||
## Verifying
|
||||
|
||||
`./run-tests.sh` from the repo root now runs `event-model`, `client-core`
|
||||
and `server` in that order (each `cargo test`, forwarding arguments the
|
||||
same way it always has). From `client-core/` directly: `cargo test`
|
||||
(119 tests), `cargo clippy --all-targets`, `cargo fmt` -- all clean as of
|
||||
this writing (2026-09-06).
|
||||
`./run-tests.sh` from the repo root runs `event-model`, `server` and
|
||||
`app-rust` in that order (each `cargo test`, forwarding arguments the same
|
||||
way it always has). From `app-rust/` directly: `cargo test`, `cargo clippy
|
||||
--all-targets`, `cargo fmt` -- all clean as of 2026-09-08, 229 tests across
|
||||
the crate and its headless harness suites.
|
||||
@@ -5,6 +5,30 @@ they can be judged and reversed later. Detail lives in RUST.md (and IRIS.md
|
||||
for iris API changes); this file is only the summary. Newest first. Items
|
||||
marked **DEFERRED** are ones the agent chose not to decide alone.
|
||||
|
||||
## 2026-09-08 (the port is one crate, and iris is framework-only)
|
||||
|
||||
Asked for by Iris directly, so the shape rather than the fact is what is
|
||||
open to review. `app-rust/` is one crate, `ai-app`, with `client`, `ui`,
|
||||
`desktop`, `android` and `shell` as modules; `iris/` holds only `core`,
|
||||
`macro`, `iris`, `tabs-ui` and `rig-input`. docs/RUST.md's "One app crate"
|
||||
has the table and the reason each old split did or did not survive.
|
||||
|
||||
Three calls made inside that, none of which she named:
|
||||
|
||||
1. **`event-model` stayed at the repo root** rather than moving into
|
||||
`app-rust/` -- her choice when asked, since `server/` depends on it too.
|
||||
2. **The Android application id and Java package were left alone**
|
||||
(`dev.iris.android.demo`, label "iris android-view demo"), though both
|
||||
now name the wrong thing. Renaming them makes the next install
|
||||
side-by-side rather than an upgrade on her phone, and changes the
|
||||
`DevLogProvider` authority Dev Updater reads. Say the word and it is a
|
||||
small change.
|
||||
3. **The `bench` fixture is behind a `fixture` feature that is on by
|
||||
default**, with `build-apk.sh` passing `--no-default-features` so an APK
|
||||
carries the 1.9 MB fixture only when it asked for `bench`. The
|
||||
alternative -- default off -- would have made `cargo test` silently skip
|
||||
the six harness suites, which is the worse failure.
|
||||
|
||||
## 2026-09-08 (last: scrolling moves out of the list)
|
||||
|
||||
Agreed with Iris in the exchange that followed, so most of this is her
|
||||
|
||||
+108
-1
@@ -2089,7 +2089,7 @@ column above.
|
||||
`Tasks::redraw_handle`'s design had anticipated) -- both in I5's own box,
|
||||
both in `IRIS.md`.
|
||||
- **Design choices for the two pieces before this are summarised in
|
||||
`DECISIONS.md`** at the repo root, which is the file Iris reads for
|
||||
`DECISIONS.md`** in `docs/`, which is the file Iris reads for
|
||||
choices made without her.
|
||||
- **E4 done, 2026-09-05.** `iris/desktop-app`: a winit window with a
|
||||
session list beside `transcript-ui`'s screen (`build_tree`), against a
|
||||
@@ -8394,3 +8394,110 @@ again `--features iris/force-gles` on virgl, identical output. Layer 3:
|
||||
`build-apk.sh release` (arm64) builds, and the x86_64 debug bench ran a
|
||||
full fling/stream/type/keyboard cycle on the emulator's GLES adapter with
|
||||
no crash.
|
||||
|
||||
## One app crate, 2026-09-08 (the repository reorganised)
|
||||
|
||||
Iris, reading the tree: *"the organization of the rust rewrite is a mess
|
||||
right now… there shouldn't be anything related to the app inside of iris.
|
||||
Iris is supposed to be the UI framework alone."* Then, on the crate count:
|
||||
*"I'm confused why the app only code needs more than one crate though."*
|
||||
|
||||
### What it was
|
||||
|
||||
Nine cargo workspaces, each with its own `Cargo.lock` and `target/`, and
|
||||
the port's project code in five places — `iris/transcript-ui`,
|
||||
`iris/transcript-fixture`, `iris/desktop-app`, `iris/android-app` (all
|
||||
*inside* the framework), plus `client-core` and `android-shell` at the
|
||||
root. Two root markdown files (`DECISIONS.md`, `SUBAGENTS.md`) sat outside
|
||||
`docs/`.
|
||||
|
||||
### What it is
|
||||
|
||||
**One crate, `ai-app`, in `app-rust/`.** Modules, not crates:
|
||||
|
||||
| was | is |
|
||||
|----------------------------------------|-----------------------------------|
|
||||
| `client-core` | `src/client` |
|
||||
| `iris/transcript-ui` | `src/ui` |
|
||||
| `iris/transcript-fixture` | `src/ui/fixture.rs` + `tests/`, `touch/` |
|
||||
| `iris/desktop-app` | `src/desktop` + `src/bin_desktop.rs` |
|
||||
| `iris/android-app` | `src/android` + `android-project/` |
|
||||
| `android-shell` | `src/shell` |
|
||||
|
||||
`iris/` now holds `core`, `macro`, the `iris` crate, `tabs-ui` and
|
||||
`rig-input` — framework only, with no mention of a session, a transcript,
|
||||
a setup or a server anywhere in it.
|
||||
|
||||
### Why one crate really is enough
|
||||
|
||||
Each split had a stated reason at the time; on inspection only two
|
||||
survived, and one of those is not in `app-rust` at all.
|
||||
|
||||
- **`client-core` separate from the UI** was "pure logic with no framework
|
||||
dependency". That property is worth keeping and does not need a crate:
|
||||
`iris` is behind the `screens` feature and `src/client/` may not reach
|
||||
it. An invariant on a module instead of on a manifest, stated in
|
||||
docs/CLIENT_CORE.md.
|
||||
- **`transcript-fixture` separate from `transcript-ui`** was so the
|
||||
headless harness and a desktop window opened the same bytes. Both are
|
||||
now the same crate, so it is `src/ui/fixture.rs` behind a `fixture`
|
||||
feature (1.9 MB of `include_str!` must not reach a phone build) with the
|
||||
six harness suites in `tests/`.
|
||||
- **Two Android `.so` names**, `libmain.so` for the iris app and
|
||||
`libandroid_shell.so` for the Kotlin shell's JNI bridge, looked like the
|
||||
one hard constraint: a package produces exactly one library artifact.
|
||||
It dissolves because **P2 already plans to merge those two Android apps
|
||||
into one**. So both faces come out of one package as `libai_app.so`,
|
||||
picked apart by features (`--no-default-features --features shell` keeps
|
||||
wgpu, parley and iris out of the Compose app's APK), which is the
|
||||
direction of travel rather than a workaround. `xtask apk` and
|
||||
`app/shellApp`'s `System.loadLibrary` were updated to match.
|
||||
- **A desktop binary and an Android cdylib in one package** is not a
|
||||
problem: `iris` itself already target-gates winit against android-view
|
||||
in one manifest, and the same table does it here. `build-apk.sh` passes
|
||||
`--lib` so `cargo ndk` never tries to build the desktop binary.
|
||||
- **`event-model` stays a crate**, and is the one split that was never
|
||||
optional: `server/` depends on it too, so a crate is what makes the
|
||||
backend and the app agree by construction. Iris chose to leave it at the
|
||||
repo root rather than inside `app-rust/`, since it is the contract
|
||||
between the two rather than app code.
|
||||
|
||||
So: three workspaces where there were nine — `event-model`, `server`,
|
||||
`app-rust` — plus `iris` and `xtask`.
|
||||
|
||||
### Things that moved with it, worth knowing
|
||||
|
||||
- **The toolchain pin is per directory.** `app-rust/rust-toolchain.toml` is
|
||||
a copy of `iris/`'s, because `client-core` used to build on stable and
|
||||
now shares iris's dated nightly. Two consequences appeared immediately:
|
||||
two `needless_range_loop` warnings in the markdown highlighter (fixed),
|
||||
and four `AtomicBool::fetch_update` deprecations from inside `jni`
|
||||
0.22's `native_method!` macro. The last are not ours to migrate — the
|
||||
fix is a `jni` release — so `src/lib.rs` carries an `#[allow(deprecated)]`
|
||||
scoped to `mod shell` with that reason written at it.
|
||||
- **The Android release profile is `android-release`, not `release`.** The
|
||||
aggressive settings `iris/android-app` had (`panic = "abort"`,
|
||||
`opt-level = "s"`, fat LTO) would otherwise apply to the desktop build
|
||||
too, which is a testing surface. `build-apk.sh` passes
|
||||
`--profile android-release` / `--profile android-dev`.
|
||||
- **`iris/run-headless.sh` grew `--dir DIR`**, defaulting to `iris/`. The
|
||||
rig belongs to the framework; the examples it usually runs no longer do.
|
||||
`replay-touch` is still built from `iris/`.
|
||||
- **The log target changed** from `client_core` to `ai_app`
|
||||
(`src/client/log_ring.rs`'s `is_own_target`).
|
||||
- **Not renamed, deliberately:** the Android application id and Java
|
||||
package are still `dev.iris.android.demo` and the label is still "iris
|
||||
android-view demo", both now misleading. Changing them changes the app's
|
||||
identity on Iris's phone (a side-by-side install rather than an upgrade)
|
||||
and the `DevLogProvider` authority Dev Updater reads, so it is hers to
|
||||
decide rather than a tidy-up to make quietly.
|
||||
|
||||
### Verified
|
||||
|
||||
`./run-tests.sh` (event-model, server, app-rust) and `cd iris && cargo
|
||||
test` green; `cargo clippy --all-targets` and `cargo fmt` clean in every
|
||||
workspace. `cargo ndk -t x86_64` links `libai_app.so`; `./build-apk.sh
|
||||
debug --abi x86_64` produces an installable APK; installed and launched on
|
||||
this checkout's emulator, drawing through `Gl … virgl` as expected. The
|
||||
phone-sized headless screenshot (`run-headless.sh phone --phone --dir
|
||||
../app-rust --shot …`) renders the transcript unchanged.
|
||||
@@ -0,0 +1,141 @@
|
||||
# Subagents
|
||||
|
||||
A session's subagents -- the helpers a Claude Code session starts through its
|
||||
Task tool -- each get a transcript of their own, listed under the session's
|
||||
card and readable in the same transcript view the session has. Designed
|
||||
2026-09-05; the decisions Bryan has not yet reviewed are in `SUBAGENTS_DECISIONS.md`.
|
||||
|
||||
## What a subagent is here
|
||||
|
||||
**A subagent is a second transcript owned by a session, in the same event
|
||||
model, with no process and no controls.** It is not a session: it cannot be
|
||||
messaged, stopped or started, and it has no setup, model or usage of its
|
||||
own. Everything it shares with a session -- the transcript file format, the
|
||||
paging routes, the SSE stream, the phone's cache and rendering -- is reused
|
||||
by addressing, not by copying.
|
||||
|
||||
The CLI reports a subagent's messages on the parent's own stream-json
|
||||
output, each carrying `parent_tool_use_id` = the id of the Task `tool_use`
|
||||
that started it. Before this the translator dropped those lines
|
||||
(`subagent_events_are_not_duplicated_into_the_transcript`); now it routes
|
||||
them to that subagent's own translator and transcript. The parent's
|
||||
transcript still shows only the Task call itself.
|
||||
|
||||
## Storage
|
||||
|
||||
Under the session directory:
|
||||
|
||||
```
|
||||
<session>/subagents/<tool_use_id>/meta.json {title, created}
|
||||
<session>/subagents/<tool_use_id>/transcript.jsonl same SeqEvent lines as the session's
|
||||
```
|
||||
|
||||
The id is the Task tool_use id (`toolu_…`), which is unique, stable across a
|
||||
backend restart, and already the key everything on the parent side uses.
|
||||
Only ids matching `[A-Za-z0-9_-]+` are ever created or looked up, since the
|
||||
id becomes a path.
|
||||
|
||||
The transcript's sequence numbers are its own, starting at 1. `Transcript`,
|
||||
`read_window`, `catch_up` and `read_after` work on it unchanged.
|
||||
|
||||
Its path out: deleting the session deletes its directory, subagents included.
|
||||
There is no separate delete.
|
||||
|
||||
## Lifecycle, as events in the subagent's transcript
|
||||
|
||||
1. Created on the first child line for an unseen parent id (or, when the
|
||||
parent Task call was seen, at that call). First lines written:
|
||||
`Status Running`, then `UserMessage { text: <the Task's prompt> }` when
|
||||
the prompt is known -- it genuinely is the subagent's first user turn.
|
||||
2. Every child line is translated by that subagent's own `Translator`
|
||||
(one per subagent: tool ids are unique but streaming deltas are by
|
||||
content-block index, and parallel subagents interleave).
|
||||
3. **The parent's `tool_result` never finishes a subagent.** The Task tool
|
||||
runs in the background by default: the `tool_result` -- "Async agent
|
||||
launched..." -- arrives the moment it *starts*, while the subagent goes
|
||||
on working for however long its own turn takes, sometimes minutes. What
|
||||
ends it is its own turn ending: the raw API's `message_delta` on its
|
||||
stream carrying `stop_reason: "end_turn"` (a `stop_reason` of `tool_use`
|
||||
is the model about to call one, not an end), or a `result` line for its
|
||||
own turn if a future CLI version ever sends one. Either maps to
|
||||
`Status Exited`; the subagent's vocabulary has no `Idle`, so the
|
||||
equivalent event `dispatch` produces for an ordinary session is dropped
|
||||
rather than written. A shipped version of this finished on the
|
||||
`tool_result` instead, which read a running background agent as
|
||||
"finished" with its transcript truncated at the moment it launched.
|
||||
4. **A child line for a subagent that already finished reopens it**
|
||||
(`Status Running`) rather than being dropped: a background Task can be
|
||||
sent another message long after its first turn ended, and that is
|
||||
exactly what a further line for it means. Same transcript, same child
|
||||
`Translator`, just picking back up.
|
||||
5. When the parent session's process exits (`Status Exited` on the
|
||||
session), every subagent still `Running` gets `Status Exited` too: its
|
||||
process was the parent's.
|
||||
|
||||
A subagent that was mid-flight when the backend restarted keeps working:
|
||||
the registry reopens the existing transcript on the next child line, and
|
||||
the file continues its sequence -- the same reopening #4 describes, whether
|
||||
what closed it was a restart or its own `end_turn`. If its turn ended while
|
||||
the backend was down nothing recorded that until the next line arrives, so
|
||||
its last status stays `Running`, which the list reports as **unknown**
|
||||
rather than as running (see the wire shape) until then.
|
||||
|
||||
Title: the Task call's `description` input, then ` (<subagent_type>)` when
|
||||
one is given; falling back to the tool's name when the child arrives before
|
||||
(or without) the parent call being seen.
|
||||
|
||||
## Server layout
|
||||
|
||||
- `session/subagent.rs` -- the registry: `Subagents` (per session, in
|
||||
`Shared`), `Subagent` (its `Transcript` behind a mutex plus a
|
||||
`broadcast::Sender<SeqEvent>`), `record(id, event)`, `start(id, title,
|
||||
prompt)`, `finish(id)`, `reopen(id)`, `finish_all()`, `list()` from disk. Drivers get an
|
||||
`Arc<Subagents>` beside their `EventSink`; llama ignores it.
|
||||
- `session/claude/translate.rs` -- routes child lines by parent id, holds
|
||||
one child `Translator` per subagent, remembers pending Task calls'
|
||||
description/prompt/subagent_type.
|
||||
- `session/echo.rs` -- `/subagent [n]`: the test rig. Starts *n* (default 1)
|
||||
subagents at once, each named "helper k". Each writes the prompt as its
|
||||
user message, streams a few words of text, runs one `Bash` tool call, then
|
||||
finishes about three seconds after starting, and the parent's Task calls
|
||||
end when their subagent does. Three seconds so the running state can be
|
||||
seen on the phone.
|
||||
- `routes.rs` -- three routes, in the doc table.
|
||||
|
||||
## Wire shape
|
||||
|
||||
```
|
||||
GET /sessions/{id} SessionInfo gains `subagents: N` (count, 0 when none)
|
||||
GET /sessions same field on each row
|
||||
GET /sessions/{id}/subagents [{id, title, status, created, lastActivity}], oldest first
|
||||
GET /sessions/{id}/subagents/{sub}/transcript exactly the session transcript's query and answer
|
||||
GET /sessions/{id}/subagents/{sub}/events?after=N exactly the session events stream
|
||||
```
|
||||
|
||||
`status` is the transcript's last `Status` event, serialised like a session's
|
||||
(`running`, `exited`), except that a subagent whose session is not itself
|
||||
running cannot be running: the list answers `unknown` for that one. The
|
||||
phone words these as *running*, *finished* and *unknown* on the subcard.
|
||||
|
||||
The count on `SessionInfo` is a directory listing, so the list stays cheap.
|
||||
The per-subagent status is only read when the list route is asked for.
|
||||
|
||||
## Phone
|
||||
|
||||
- `SessionSummary.subagents: Int`. A card with a non-zero count ends in an
|
||||
expander row -- a full-width `Chevron(Pointing.Down)` row that flips to
|
||||
`Pointing.Up` -- collapsed by default. Expanding fetches
|
||||
`/sessions/{id}/subagents` and draws one `OutlinedCard` per subagent,
|
||||
indented inside the session card, the way dev-updater draws a project's
|
||||
components: title, then the status word and a relative time. The
|
||||
expansion state is per session id and survives a refresh of the list.
|
||||
- Tapping a subcard opens `Screen.Subagent`, which is `SessionScreen` in
|
||||
**read-only** form: the same transcript, paging, cache, selection,
|
||||
images and status row, with the composer, the process button, the model
|
||||
picker, the files button, the settings cog and the usage bar left out.
|
||||
The header shows the subagent's title with the session's title beneath
|
||||
it. Back returns to the list.
|
||||
- Addressing: `fetchTranscript`, `EventStream`, `TranscriptSource` and the
|
||||
cache take a transcript address rather than a session id --
|
||||
`sessions/{id}` or `sessions/{id}/subagents/{sub}` -- so the cache nests a
|
||||
subagent's copy under its session's and the same code serves both.
|
||||
@@ -0,0 +1,44 @@
|
||||
# Decisions awaiting review
|
||||
|
||||
Choices made while working autonomously, for Bryan to keep or change. Each
|
||||
says what was picked and why; the detail is in the design doc it names.
|
||||
Delete an entry once it has been looked at.
|
||||
|
||||
## Subagent views (2026-09-05, `SUBAGENTS.md`)
|
||||
|
||||
Made on my own judgement, limited blast radius:
|
||||
|
||||
1. **A subagent is a transcript, not a session.** It has no process,
|
||||
controls or settings; it is addressed as `/sessions/{id}/subagents/{sub}`
|
||||
and stored under the session's directory, so deleting the session takes
|
||||
it. Alternative rejected: registering it as a session of its own, which
|
||||
would give it a card in the main list and a driver that can do nothing.
|
||||
2. **Read-only view is the session screen minus its controls**, rather than
|
||||
a second, simpler transcript screen. Keeps paging, caching, selection
|
||||
and rendering in one place. Cost: a `readOnly` mode threaded through
|
||||
`SessionScreen`.
|
||||
3. **The list only carries a count.** Each session row says how many
|
||||
subagents it has; their titles and statuses are fetched when the card is
|
||||
expanded. Keeps `GET /sessions` from reading every subagent transcript.
|
||||
Consequence: an expanded card's statuses refresh with the list, not live.
|
||||
4. **Expanded/collapsed is remembered per session on the phone**, not on
|
||||
the server. Collapsed by default, per the transcript convention that new
|
||||
things arrive collapsed.
|
||||
5. **Subagents of imported sessions are not shown.** The import path still
|
||||
skips `isSidechain` records; the CLI's own `subagents/agent-*.jsonl` files
|
||||
are not read. Only subagents run while this backend was watching exist.
|
||||
6. **Echo grows `/subagent [n]`** as the test rig, so nothing here needs a
|
||||
paid turn to exercise.
|
||||
|
||||
Deferred, because they reach further than this feature:
|
||||
|
||||
- **Live status on the list.** Whether the session list should follow a
|
||||
stream at all (it refreshes on demand today) decides whether subagent
|
||||
status can ever be live there. Not changed.
|
||||
- **Nested subagents.** A subagent's own Task calls are shown as tool calls
|
||||
in its transcript and are not given transcripts of their own. Supporting
|
||||
that is the same mechanism one level down, but the UI would need nested
|
||||
expanders.
|
||||
|
||||
- **The subagent status row says "context unknown".** Nothing measures a
|
||||
subagent's context; the row could leave it out rather than admit it.
|
||||
Reference in new issue
Block a user