From c132e2b59eab65a3197d919760474b27a10bca7e Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sat, 17 Oct 2026 23:59:33 +0100 Subject: [PATCH 1/9] docs: record the consent rule and stop ordering shared-document edits --- AGENTS.md | 9 +++++++++ internal/author/skill/references/orchestration.md | 9 ++++----- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 297b99d5..968f012c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,14 @@ # Pipelines maintenance +## Consent (hard rule) + +The operator owns this system. No change to it happens without their explicit consent in the +current conversation: new pipelines or versions, definition and stage-prompt edits, +orchestration scripts, briefs and the conventions they carry, the packaged skill and templates, +deploys, installs and deletions. Read-only investigation and reporting need no consent. Ask +first and name exactly what would change; a request for a fix is not consent for a particular +mechanism. + When changing user-facing behavior or learning a confirmed runtime limitation, update the relevant packaged OpenCode skill reference in `internal/author/skill/references/` in the same change. Keep `SKILL.md` a concise, diff --git a/internal/author/skill/references/orchestration.md b/internal/author/skill/references/orchestration.md index a2aa982e..d92bb6d5 100644 --- a/internal/author/skill/references/orchestration.md +++ b/internal/author/skill/references/orchestration.md @@ -55,8 +55,7 @@ Every brief has: output it must report, plus the screenshots the reviewer must read. Say plainly: "report the exact commands and their observed results. Do not claim a check you did not run." -5. **Where it belongs** — the packaged templates, the repository's guidelines (README - and topic docs) and the packaged skill references the change is expected to touch, +5. **Where it belongs** — the packaged templates and the packaged skill references the change is expected to touch, so the committer can check and update them before it commits. 6. **The hard constraints block** (below). 7. **Publishing rules** (`references/delivery.md`). @@ -107,8 +106,8 @@ Adapt the scope and publishing lines per item; keep the rest. from the source that already owns them, not from new literals. - **Commit locally only, never push** — the committer stage commits, no other stage. - **Reflect the change where it belongs** — before committing, the committer checks - that the change is reflected in the packaged templates, the repository's guidelines - (README and topic docs) and the packaged skill references, updates anything stale, + that the change is reflected in the packaged templates and the packaged skill references, + updates anything stale, and states in the commit body what it checked or that nothing needed updating. - **Publish rules** — WIP artefact naming and LAN URLs per `references/delivery.md`. @@ -124,7 +123,7 @@ Adapt the scope and publishing lines per item; keep the rest. change approved without the images. - The committer is the only stage that commits, and it stages only the run's changed files. Before committing it checks that the change is reflected in the packaged - templates, the repository's guidelines (README and topic docs) and the packaged + templates and the packaged skill references, updates anything stale, and states in the commit body what it checked or that nothing needed updating. It must also select `input.server_changed_files` (the runner's captured evidence, `references/control.md`) alongside the implementer's From a3f571d67288277fe4cc213b4c954c49005a1c9a Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sat, 17 Oct 2026 16:29:05 +0100 Subject: [PATCH 2/9] docs: make docs-fold the single writer of shared documentation Every item wrote the shared, append-only docs (android/README.md, docs/cli.md and the packaged skill references), so every merge conflicted on prose. Keep the duty to notice stale docs; move the writing to one deliberate place. - Per-item note, not a shared edit. An item that makes a shared document stale writes docs/notes/.md - unique per item, so two items never touch the same file - and commits that note with its change. It never edits a README, topic doc or packaged skill reference itself. - One writer. The manual-only docs-fold pipeline, bundled as the fifth starter examples/docs-fold.md, folds every note under docs/notes/ into the shared document it names and deletes the consumed notes in its own commit; an empty notes directory is a success no-op. Operator trigger: pipelines new "Docs fold" --template docs-fold --no-open; pipelines submit ; pipelines run "Docs fold". - Implemented where the convention lives: orchestration.md (brief item 5, the hard-constraint bullet, a "Single documentation writer" section and the "Pipeline choice" committer bullet), the canonical committer checklist in format.md (new step 6), the committer prompts in examples/task.md and examples/three-stage.md, the new examples/docs-fold.md with its catalog and README entries, and the repository guideline AGENTS.md. Test-expectation counts (examples/catalog_test.go, internal/server/templates_test.go, scripts/smoke-first-install.py) follow the fifth starter. Reflected where it belongs: the packaged templates (examples/task.md, examples/three-stage.md, the new examples/docs-fold.md), the packaged skill references (orchestration.md, format.md) and the repo guideline AGENTS.md all carry the new convention. No new reference file was added, so install.go's managed inventory is unchanged. The shared descriptive docs were deliberately not rewritten: this change makes README.md:191, docs/cli.md:170 and internal/author/skill/references/operations.md:13 name four starters where there are now five. Those stay as they are - correcting them now is exactly the per-item shared edit this change removes - and the stale-doc note docs/notes/docs-fold-single-writer.md records each one for the docs-fold writer to fold. Nothing else needed updating. No new dependency; no Android, Gradle, server, installer, Docker or published-definition change; no definition published over the running pipelines. Evidence: go test -count=1 ./... passed; go build ./... and go vet on the touched packages clean; ./internal/author/... covers embedding, reference links, the managed inventory and install/upgrade/protection; ./examples/... validates the fifth starter and its manual-only, committer-terminated graph; ./internal/server/... covers the served catalog. Not run: the docs-fold writer against the shared docs (nothing to fold yet); no install or deploy. (cherry picked from commit f29656cf084d7eee2e033f2a37a9d231d7acaaf0) --- AGENTS.md | 14 ++- docs/notes/docs-fold-single-writer.md | 40 +++++++++ examples/README.md | 9 +- examples/catalog.go | 1 + examples/catalog_test.go | 9 +- examples/docs-fold.md | 90 +++++++++++++++++++ examples/task.md | 7 +- examples/three-stage.md | 6 +- internal/author/skill/references/format.md | 9 ++ .../author/skill/references/orchestration.md | 51 ++++++++--- internal/server/templates_test.go | 3 +- scripts/smoke-first-install.py | 4 +- 12 files changed, 220 insertions(+), 23 deletions(-) create mode 100644 docs/notes/docs-fold-single-writer.md create mode 100644 examples/docs-fold.md diff --git a/AGENTS.md b/AGENTS.md index 968f012c..cc40fd17 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,9 +9,13 @@ deploys, installs and deletions. Read-only investigation and reporting need no c first and name exactly what would change; a request for a fix is not consent for a particular mechanism. -When changing user-facing behavior or learning a confirmed runtime limitation, -update the relevant packaged OpenCode skill reference in -`internal/author/skill/references/` in the same change. Keep `SKILL.md` a concise, +When a change alters user-facing behavior, or you learn a confirmed runtime +limitation, record the stale documentation instead of editing the shared document in +the same change: leave a per-item note at `docs/notes/.md` naming what changed and +which packaged OpenCode skill reference in `internal/author/skill/references/`, README +or topic doc is now stale and what should change there. The manual-only `docs-fold` +pipeline folds `docs/notes/` into the shared docs and references; an item never edits a +shared document itself. Keep `SKILL.md` a concise, task-directed index: preserve ask-first authoring and never preload every reference. Separate current capabilities, dated verification evidence, deployment state and unimplemented ideas. Do not turn mocked or structural checks into live claims. @@ -21,7 +25,9 @@ Run the author package tests: they check embedding, reference links, installatio upgrades and protection of user modifications. Never hand-edit an installed copy as the source of truth; refresh it with the current-source `pipelines skill install` only when installation is requested. Do not deploy runtime changes merely because -the skill is updated. Keep README/topic docs and the packaged reference consistent. +the skill is updated. Keep the shared docs and packaged references consistent through +the single `docs-fold` writer rather than editing them per item: leave a +`docs/notes/.md` note. ## Maintenance workflow diff --git a/docs/notes/docs-fold-single-writer.md b/docs/notes/docs-fold-single-writer.md new file mode 100644 index 00000000..c689fc9e --- /dev/null +++ b/docs/notes/docs-fold-single-writer.md @@ -0,0 +1,40 @@ +# docs-fold single documentation writer + +## What this item changed + +Per-item workflows no longer edit shared documentation themselves. The convention now +lives in `internal/author/skill/references/orchestration.md` (brief item 5, the +hard-constraint bullet, "Single documentation writer", and the "Pipeline choice" +committer bullet), the canonical committer checklist in +`internal/author/skill/references/format.md` (step 6), the bundled committer prompts in +`examples/task.md` and `examples/three-stage.md`, and the repository guideline +`AGENTS.md`. + +The chosen mechanism is a **per-item note file** at `docs/notes/.md`: when a +change makes a shared document stale, the item records what changed and what should +change there, commits that note with its own change, and never edits a shared document. +The chosen **single writer** is the manual-only `docs-fold` pipeline, added as a fifth +bundled starter at `examples/docs-fold.md` and listed in `examples/catalog.go` and +`examples/README.md`. Its `fold` stage reads every note under `docs/notes/`, folds each +into the shared document it names, and deletes the consumed notes in its own commit. + +## Shared documents this change makes stale + +Adding the fifth starter (`docs-fold`) makes the following documents' starter counts +wrong. They were deliberately **not** edited by this item; the `docs-fold` writer should +correct them when it next folds notes. + +- `README.md:191` — "To skip authoring, use **:templates**, choose one of the four + generic starters," should read "five generic starters". +- `docs/cli.md:170` — "Use `:templates` for four simple, manual-only starters: task, + review, research, and plan/implement/review." should say five starters and name + `docs-fold` (fold accumulated documentation notes, then commit locally). +- `internal/author/skill/references/operations.md:13` — "Four optional generic starters + are task, review, research and three-stage;" should read "Five optional generic + starters are task, review, research, three-stage and docs-fold;". + +## Do not change + +- `docs/first-version-testing.md:148` and the dated records in + `docs/installation-verification.md` describe a past fixture run at the time it ran; + they are dated evidence, not current counts, and stay as they are. diff --git a/examples/README.md b/examples/README.md index 30b4e478..636b07bb 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,6 +1,6 @@ # Simple workflow templates -Four optional, technology-neutral starters. Nothing is installed as a published +Five optional, technology-neutral starters. Nothing is installed as a published pipeline automatically; all templates are manual-only and have at most four stages. | Template key | Workflow | Tools | @@ -9,6 +9,7 @@ pipeline automatically; all templates are manual-only and have at most four stag | `review` | Read repository content and report findings | Read/glob/grep and conditional web search/fetch; no edit/shell | | `research` | Research a topic, then write a sourced report | Web search/fetch, then none | | `three-stage` | Plan → implement → review → commit | Planner read/glob/grep + conditional web; implementer read/glob/grep/edit/shell with no web (follows the planner's research); reviewer independent shell + conditional web; committer read/shell | +| `docs-fold` | Fold accumulated item documentation notes into the shared docs, then commit locally | Fold: read/glob/grep/edit/shell; committer: read/shell | Every workflow that changes the repository ends in a **committer** stage that commits locally and never pushes. The committer stages the union of the runner's @@ -17,6 +18,12 @@ declared `changed_files` — a declared list can be incomplete — then runs the repository's required checks before committing. `task` and `three-stage` follow this; `review` and `research` change nothing and so do not commit. +`docs-fold` is the deliberate **single documentation writer**. A per-item workflow never +edits a shared README or topic doc: when its change makes one stale it records a note at +`docs/notes/.md`, unique per item, and commits that note with the change. Running +the manual-only `docs-fold` pipeline later folds the accumulated notes into the shared +documentation and removes them. + Model and agent stages return the line-oriented result: the first non-empty line is the declared outcome, a `# output` section holds the JSON output map for the next stage, and any further `# ` section is retained verbatim as evidence. The diff --git a/examples/catalog.go b/examples/catalog.go index 5070bcda..150c9f97 100644 --- a/examples/catalog.go +++ b/examples/catalog.go @@ -16,6 +16,7 @@ var starters = []protocol.Template{ {Key: "three-stage", Name: "Plan, implement, review", Description: "Plan a change, implement it, review and verify it, then commit it locally. Any language or file type."}, {Key: "review", Name: "Review a repository", Description: "One read-only stage to review repository content and report findings."}, {Key: "research", Name: "Research a topic", Description: "Research a topic on the web, then write a sourced report. Requires web search support."}, + {Key: "docs-fold", Name: "Fold documentation notes", Description: "Fold the accumulated per-item documentation notes into the shared docs, then commit locally. The repository's single documentation writer; manual-only."}, } func Catalog() []protocol.Template { diff --git a/examples/catalog_test.go b/examples/catalog_test.go index ba0e8a23..6b690b3f 100644 --- a/examples/catalog_test.go +++ b/examples/catalog_test.go @@ -27,11 +27,11 @@ func TestReadmeThreeStageExampleIsValid(t *testing.T) { func TestCatalogContainsValidUnpublishedTemplates(t *testing.T) { items := examples.Catalog() - if len(items) != 4 { + if len(items) != 5 { t.Fatal("unexpected catalog size", len(items)) } seen := map[string]bool{} - wantStages := map[string]int{"task": 2, "review": 1, "research": 2, "three-stage": 4} + wantStages := map[string]int{"task": 2, "review": 1, "research": 2, "three-stage": 4, "docs-fold": 2} for _, item := range items { if seen[item.Key] || item.Description == "" || item.Name == "" { t.Fatal("invalid template metadata", item.Key) @@ -104,6 +104,10 @@ var starterTools = map[string]map[string][]string{ "reviewer": {"read", "glob", "grep", "shell", "websearch", "webfetch"}, "committer": {"read", "glob", "grep", "shell"}, }, + "docs-fold": { + "fold": {"read", "glob", "grep", "edit", "shell"}, + "committer": {"read", "glob", "grep", "shell"}, + }, } func TestStarterRoleToolRestrictions(t *testing.T) { @@ -182,6 +186,7 @@ func TestWorkProducingStartersEndInACommitter(t *testing.T) { for _, tc := range []struct{ key, producer string }{ {"task", "worker"}, {"three-stage", "implementer"}, + {"docs-fold", "fold"}, } { graph := parsedCatalog(t)[tc.key] last := graph.Stages[len(graph.Stages)-1] diff --git a/examples/docs-fold.md b/examples/docs-fold.md new file mode 100644 index 00000000..a7200acf --- /dev/null +++ b/examples/docs-fold.md @@ -0,0 +1,90 @@ +# stage fold + +```output +{ summary, changed_files, folded_notes } +``` + +```prompt +Fold the accumulated per-item documentation notes into the repository's shared +documentation. Read every file under `docs/notes/`; for each note, apply the change it +records to the shared document the note names - the repository's READMEs and topic docs +and the packaged skill references - then delete the consumed note. Do not edit any other +file, change behaviour, or rewrite documentation that is still true. Keep values from +their single existing sources. An empty or missing `docs/notes/` directory is a success +no-op: make no change, commit nothing, and say so. Limit inspection to the notes +directory and the documents they name; never scan filesystem or mount roots, and use +commands supported by the actual execution environment. Save any artifacts you produce +into the artifacts directory named in the runtime context. Report the notes read, the +documents changed and the notes deleted in an `# evidence` section, with the exact +commands and observed results. Return the line-oriented result: the first non-empty line +is the declared outcome, a `# output` section holds one JSON object with the output +fields named above, and any further `# ` section is retained verbatim as +evidence. Return blocked if the notes directory cannot be read. +``` + +```tools +read +glob +grep +edit +shell +``` + +```configs +provider=opencode-go +model=deepseek-v4.1-flash +retries=2 +timeout=1h +``` + +```edges +success -> committer +blocked -> #failure +error -> #failure +``` + +# stage committer + +```output +{ committed, commit, changed_files, pre_commit_checks } +``` + +```prompt +Commit this run's change locally. Never push, tag, deploy or rewrite history. Select +the run's changed paths from input.server_changed_files (the runner's captured +evidence) and the fold stage's declared changed_files, and stage their union, including +the notes the fold stage deleted (stage the removal, not only surviving paths). Inspect +the staged diff before committing; never commit unrelated work, secrets or generated +artifacts. When nothing is staged - for example an empty notes directory - do not create +an empty commit; return success with a clear note. Otherwise commit with a concise +message naming this run's change and report the commit hash. If a required check fails, +do not commit; return blocked with the failing output. Return the line-oriented result: +the first non-empty line is the declared outcome, a `# output` section holds one JSON +object with the output fields named above, and any further `# ` section is +retained verbatim as evidence. Never claim an unexecuted check passed or fabricate a +commit. +``` + +```memory +{"changed_files":"fold.changed_files","server_changed_files":"input.server_changed_files"} +``` + +```tools +read +glob +grep +shell +``` + +```configs +provider=opencode-go +model=deepseek-v4.1-flash +retries=2 +timeout=1h +``` + +```edges +success -> #success +blocked -> #failure +error -> #failure +``` diff --git a/examples/task.md b/examples/task.md index 9395a751..428a5365 100644 --- a/examples/task.md +++ b/examples/task.md @@ -71,7 +71,12 @@ Commit this run's change locally. Never push, tag, deploy or rewrite history. Select the run's changed paths from input.server_changed_files (the runner's captured evidence) and the worker's declared changed_files, and stage their union of paths that still exist, keeping any exclusions. Inspect the staged diff before -committing; never commit unrelated work, secrets or generated artifacts. Pre-commit +committing; never commit unrelated work, secrets or generated artifacts. Follow the +documentation-note step of the committer checklist in `references/format.md`: when the +change makes a shared document stale, stage the item's own documentation note +(`docs/notes/.md`) with the change, and never edit a shared document (a README, +topic docs or the packaged skill references) here; a single documentation writer folds +notes later. Pre-commit checklist: confirm the staged paths are this run's change; run the repository's required checks and record the exact commands and observed results in an `# evidence` section; do not commit if a required check fails, return blocked diff --git a/examples/three-stage.md b/examples/three-stage.md index f23e25f6..7cd154c2 100644 --- a/examples/three-stage.md +++ b/examples/three-stage.md @@ -179,7 +179,11 @@ Select the run's changed paths from input.server_changed_files (the runner's captured evidence) and the implementer's declared changed_files, and stage their union of paths that still exist, keeping any exclusions. Inspect the staged diff before committing; never commit unrelated work, secrets or generated artifacts. -Pre-commit checklist: confirm the staged paths are this run's change; run the +Follow the documentation-note step of the committer checklist in +`references/format.md`: when the change makes a shared document stale, stage the item's +own documentation note (`docs/notes/.md`) with the change, and never edit a shared +document (a README, topic docs or the packaged skill references) here; a single +documentation writer folds notes later. Pre-commit checklist: confirm the staged paths are this run's change; run the repository's required checks and record the exact commands and observed results in a `# evidence` section; do not commit if a required check fails, return blocked with the failing output instead. If nothing is staged, do not create an diff --git a/internal/author/skill/references/format.md b/internal/author/skill/references/format.md index 0e101011..a1f129a4 100644 --- a/internal/author/skill/references/format.md +++ b/internal/author/skill/references/format.md @@ -228,6 +228,15 @@ State this pre-commit checklist in the prompt: note. 5. Commit with a concise message naming the run's change and report the commit hash; never push, tag, rebase or amend. +6. Ensure the item's per-item documentation note (`docs/notes/.md`, written when + the change makes a shared document stale) is staged with the change. Never edit a + shared document (a README or topic doc, or a packaged skill reference) here: a single + documentation writer folds notes later (`references/orchestration.md`). An item that + staled no shared document has no note and needs no step 6. + +This list is the canonical checklist. The bundled starters `task`, `three-stage` and +`docs-fold` each repeat it in their committer prompt because a template is embedded and +published on its own; keep those copies in sync with this list. Merging is the operator's or a lane's job, not the committer's: it commits locally and stops (`references/orchestration.md`, `references/lanes.md`). The server does diff --git a/internal/author/skill/references/orchestration.md b/internal/author/skill/references/orchestration.md index d92bb6d5..66f5f2d2 100644 --- a/internal/author/skill/references/orchestration.md +++ b/internal/author/skill/references/orchestration.md @@ -55,8 +55,11 @@ Every brief has: output it must report, plus the screenshots the reviewer must read. Say plainly: "report the exact commands and their observed results. Do not claim a check you did not run." -5. **Where it belongs** — the packaged templates and the packaged skill references the change is expected to touch, - so the committer can check and update them before it commits. +5. **Documentation note** — where the change makes shared documentation stale, the item + records that in its own per-item note `docs/notes/.md`: what it changed and + which shared document (a README or topic doc, or a packaged skill reference) is now + stale and what should change there. The item writes only its note; it must not edit a + shared document. See "Single documentation writer" below. 6. **The hard constraints block** (below). 7. **Publishing rules** (`references/delivery.md`). @@ -80,7 +83,8 @@ dependencies; do not restart, rebuild or reconfigure the Pipelines or OpenCode server, the installer, the ntfy service or any other service - runs and lanes are active; never install on the operator's physical device; keep geometry and values from their single existing sources rather than new literals; commit locally only, -never push; . +never push; record a documentation note in `docs/notes/.md` rather than editing +a shared document; . ``` Requirements must be concrete and checkable. Name files, functions, commands, and @@ -105,12 +109,36 @@ Adapt the scope and publishing lines per item; keep the rest. - **Keep values from single sources** — geometry, tokens, sizes and constants come from the source that already owns them, not from new literals. - **Commit locally only, never push** — the committer stage commits, no other stage. -- **Reflect the change where it belongs** — before committing, the committer checks - that the change is reflected in the packaged templates and the packaged skill references, - updates anything stale, - and states in the commit body what it checked or that nothing needed updating. +- **Record stale documentation; do not rewrite it** — before committing, the committer + ensures the item's `docs/notes/.md` note, when the change makes a shared document + stale, is staged with the change, and states in the commit body what it checked. The + committer never edits a shared document (a README or topic doc, or a packaged skill + reference) itself; the single documentation writer folds notes later. - **Publish rules** — WIP artefact naming and LAN URLs per `references/delivery.md`. +## Single documentation writer + +Shared documentation — the repository's READMEs and topic docs (for this repository +`android/README.md` and `docs/cli.md`) and the packaged skill references in +`internal/author/skill/references/` — has exactly one writer, never an item. Each item +that makes one of these stale leaves a note at `docs/notes/.md` (item 5 above). +The note's filename is unique per item, so two items never write the same file and +never conflict on prose. + +The writer is the manual-only `docs-fold` pipeline, bundled as the starter +`examples/docs-fold.md`. Its `fold` stage reads every note under `docs/notes/`, folds +each into the shared document it names, and deletes the consumed notes in its own +commit; an empty `docs/notes/` is a success no-op with no empty commit. It is never +scheduled and is never part of a per-item workflow. + +The operator triggers it deliberately: + +```sh +pipelines new "Docs fold" --template docs-fold --no-open +pipelines submit +pipelines run "Docs fold" +``` + ## Pipeline choice - Use a pipeline that keeps **implementer + reviewer + ui_reviewer + committer** for @@ -122,10 +150,11 @@ Adapt the scope and publishing lines per item; keep the rest. `skipped` with a reason when the change has no rendered surface. Never accept a UI change approved without the images. - The committer is the only stage that commits, and it stages only the run's changed - files. Before committing it checks that the change is reflected in the packaged - templates and the packaged - skill references, updates anything stale, and states in the commit body what it - checked or that nothing needed updating. It must also select `input.server_changed_files` + files. Before committing it ensures the item's `docs/notes/.md` note, when the + change makes a shared document stale, is staged with the change, and states in the + commit body what it checked; it never edits a shared document (a README or topic doc, + or a packaged skill reference) itself, because a single documentation writer folds + notes later. It must also select `input.server_changed_files` (the runner's captured evidence, `references/control.md`) alongside the implementer's declared `changed_files` and stage their union: an implementer's declared list can be incomplete, and a captured path it omitted is still this run's change. Its prompt carries diff --git a/internal/server/templates_test.go b/internal/server/templates_test.go index 6d7910e8..6471d34e 100644 --- a/internal/server/templates_test.go +++ b/internal/server/templates_test.go @@ -2,6 +2,7 @@ package server import ( "context" + "git.a-wan.net/alan/pipelines/examples" "git.a-wan.net/alan/pipelines/internal/pipeline" "git.a-wan.net/alan/pipelines/internal/protocol" "github.com/coder/websocket" @@ -44,7 +45,7 @@ func TestTemplatesDoNotSeedDatabaseAndCreateOnlyPreservesExisting(t *testing.T) if err := wsjson.Read(ctx, conn, &response); err != nil { t.Fatal(err) } - if response.Type != protocol.Templates || len(response.Templates) != 4 { + if response.Type != protocol.Templates || len(response.Templates) != len(examples.Catalog()) { t.Fatal("missing catalog", response.Type, len(response.Templates)) } items, err := store.List(ctx) diff --git a/scripts/smoke-first-install.py b/scripts/smoke-first-install.py index e13ec5b3..f19e7779 100644 --- a/scripts/smoke-first-install.py +++ b/scripts/smoke-first-install.py @@ -78,7 +78,7 @@ def main(): assert pong["build"] == version, "Client/server build mismatch" assert not rpc("list").get("pipelines"), "Fresh database must be empty" assert not rpc("runs").get("runs"), "Fresh database must have no runs" - assert len(rpc("templates")["templates"]) == 4 + assert len(rpc("templates")["templates"]) == 5 draft = rpc("new", "First test", "Review the repository", "--template", "review", "--no-open", "--yes") assert not rpc("list").get("pipelines"), "Draft creation must not publish" rpc("validate", draft["path"]) @@ -100,7 +100,7 @@ def main(): assert not rpc("runs").get("runs"), "Smoke check must not execute a workflow" finally: stop(process) - print("PASS developer lifecycle fixture: isolated source binaries/skill, offline version, empty DB, four templates, draft/validate/publish, ZIP identical import, restart persistence. Not an installation option; no inference or notifications.") + print("PASS developer lifecycle fixture: isolated source binaries/skill, offline version, empty DB, five templates, draft/validate/publish, ZIP identical import, restart persistence. Not an installation option; no inference or notifications.") if __name__ == "__main__": From 8411d47b29e56a35176a8584be2dcf11f93fc253 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sat, 17 Oct 2026 16:16:15 +0100 Subject: [PATCH 3/9] android: colour every status from one palette A successful stage read amber in the Timeline because a visit's chip was coloured from the graph's outcome palette (`graphColors`/`outcomeColor`) while every other surface used the run-status palette, so the same word meant two colours. This makes `RunStatusPalette` the single source of truth: - `RunState` gains the server's own `Waiting`/`Blocked`/`Skipped` words, each with a deliberate palette entry, a distinct material glyph and a label, so a status is never colour alone and success is green / failure red everywhere. - `graphColors()` takes success/error from `runStateColor(Succeeded/Failed)`; `outcomeColor()` returns the shared status colour for any word that resolves to a `RunState` and leaves `GraphPalette` only the graph-only flow outcomes (`rejected`/`exhausted`/`retry`/`approved`/`fast`/`missing`; `blocked`/ `skipped`/`done` removed). The Timeline's `TimelineRow` uses the same factory. - A visit's *outcome* stays distinct from the run's *status* by the chip's own label and the row's state glyph, never a second colour. - The runs-list failure diagnostic uses `runStateColor(Failed)` instead of a scheme role that could drift from the chip above it; the status filter gains `waiting`. Tests: new `StatusColorConsistencyTest` (timeline colour comes from the runs-list source; every state maps to exactly one colour) and extended `GraphPaletteTest`/ `RunStatusTest`. `gradle --offline --no-daemon :app:testDebugUnitTest --rerun-tasks` -> 516 tests, 0 failures, 0 errors, 0 skipped. Docs check: the root README and docs/ do not describe the Android status colours; the packaged templates and internal/author/skill/references cover the authoring surface and are unrelated, so nothing there needed updating. android/README.md did enumerate the run states and claimed the graph outcome palette was unchanged, so its features bullets were updated and a new "One status colour everywhere" section added, with the old bullet marked superseded. APK published to the run's artifacts as pipelines-debug-wip-d13f359.apk. (cherry picked from commit a3caa734cd4769f42883b518d877dd0132ef57ae) --- android/README.md | 58 ++++++++++- .../ui/components/RunStatusPalette.kt | 38 ++++++-- .../awan/pipelines/ui/graph/GraphPalette.kt | 60 ++++++------ .../awan/pipelines/ui/graph/WorkflowGraph.kt | 96 +++++++++++-------- .../awan/pipelines/ui/screens/ListFilter.kt | 8 +- .../pipelines/ui/screens/RunHistoryScreen.kt | 4 +- .../pipelines/ui/components/RunStatusTest.kt | 6 +- .../pipelines/ui/graph/GraphPaletteTest.kt | 49 ++++++++-- .../ui/graph/StatusColorConsistencyTest.kt | 57 +++++++++++ 9 files changed, 276 insertions(+), 100 deletions(-) create mode 100644 android/app/src/test/java/net/awan/pipelines/ui/graph/StatusColorConsistencyTest.kt diff --git a/android/README.md b/android/README.md index cfc094e9..f7845240 100644 --- a/android/README.md +++ b/android/README.md @@ -253,7 +253,12 @@ stops it. Nothing is removed, and the visit tabs still switch the selected visit. - Steps render as a timeline in run detail: a leading status glyph connected to the next step by an outcome-coloured line (kept aligned with the step title), - the stage with its sequence and an outcome chip. A step's metadata is a set of + the stage with its sequence and an outcome chip. A step's colour comes from the + one status source, so a word that is a run state (`success`/`error`/`blocked`/ + `skipped`/`waiting`/…) is the same colour the runs list draws; only a graph-only + flow outcome (`approved`, `retry`, …) keeps its curated graph colour. A visit's + *outcome* is still distinguished from the run's *status* by the chip's own label + and the row's state glyph, never by a second colour. A step's metadata is a set of aligned label/value rows (`KeyValueRow`) — paired side by side in two columns on a wide window and stacked in one column on a narrow one — with a single consistent vertical rhythm (one bottom gap per step, no doubled gap when a step @@ -267,7 +272,8 @@ stops it. via `formatDuration`, and colour-coded succeeded/failed/canceled/interrupted/ active counts). Each card shows the pipeline name with a version chip, a colour-coded status chip with a distinct icon per state - (running/queued/succeeded/failed/canceled/interrupted/active/unknown), a meta + (running/waiting/queued/succeeded/failed/canceled/interrupted/active/unknown), + a meta row (run id, start time, duration) and the diagnostic only when non-blank, clamped to two lines. The raw `resultPreview` is no longer printed, and progress is shown honestly (completed visits + current stage, with an @@ -2703,6 +2709,10 @@ command targeted `emulator-5556`; lane A's `emulator-5554` was not used). call the shared `graphColors(scheme)` factory (extracted from `WorkflowGraph`, which uses it too) and `outcomeColor`, so a step chip agrees with the graph. The run header and runs-list cards keep the run-status palette. + *(Superseded 17 Oct 2026: the graph's terminal roles and the Timeline chip now + also take the one run-status colour, so "the graph outcome palette is unchanged" + no longer holds — see "One status colour everywhere" below. `RunStatusPalette` + stays the single status source.)* - **Shared helper.** `ui/components/RunStatus.kt` gained `ColoredChip(label, colour, icon, …)` — the single pill layout now used by both `StatusChip` (run status) and the Timeline's outcome chip, instead of a second copy. @@ -2785,6 +2795,50 @@ tree (JDK 17 from Homebrew `openjdk@17`, Gradle 8.11.1, `--offline`): `HTTP/1.1 200 OK`, `Content-Type: application/vnd.android.package-archive`, `Content-Length: 18009527`, and a streamed `GET | shasum -a 256` matched. +## One status colour everywhere (17 Oct 2026) + +A successful stage in the Timeline read amber, because a visit's chip was coloured +from the graph's outcome palette while every other surface used the run-status +palette, so the same word meant two colours. `android/` only; nothing in the +Pipelines server, its Go source, the Docker/compose files or the installer was +touched, no dependency was added beyond the already-declared +`material-icons-extended`, and no run was started from the app. + +- **One source of truth.** `ui/components/RunStatusPalette.kt`, with `RunState` / + `runStateOf` / `runStateColor` / `runStateIcon` in `ui/components/RunStatus.kt`, + owns a status colour. `RunState` gained the server's own `Waiting`/`Blocked`/ + `Skipped` words (`waiting` corroborated by `internal/tui/run_progress.go`), each + with a deliberate palette entry, a distinct material glyph + (`HourglassEmpty`/`Block`/`SkipNext`) and a label, so status is never colour + alone. +- **The graph and timeline route through it.** `graphColors(scheme)` sets + `success`/`error` from `runStateColor(Succeeded/Failed)`, and `outcomeColor` + returns the shared status colour for any word that resolves to a `RunState`, + falling back to `GraphPalette` only for the graph-only flow outcomes + (`rejected`, `exhausted`, `retry`, `approved`, `fast`, `missing`; `blocked`/ + `skipped`/`done` were removed from the graph palette). The Timeline's + `TimelineRow` uses the same factory, so a successful visit is green and a failure + red. A visit's *outcome* stays distinct from the run's *status* by the chip's own + label and the row's state glyph, never a second colour. The runs list's failure + diagnostic uses `runStateColor(Failed)` rather than a scheme role that could + drift from the chip above it, and the list's status filter gained `waiting`. +- **Tests.** `GraphPaletteTest` asserts every status word's graph colour equals the + runs-list colour and that the graph-only outcomes stay distinct and borrow no + status colour; `ui/graph/StatusColorConsistencyTest` asserts the timeline maps + through the same source and that every state maps to exactly one colour, the one + deliberate alias being Running/Active. + +Evidence obtained on this tree (macOS, JDK 17 from Homebrew `openjdk@17`, Gradle +8.11.1, `ANDROID_HOME=/Users/alan/Library/Android/sdk`, `--offline`, +`--no-daemon`): + +- `gradle :app:testDebugUnitTest --rerun-tasks` → **516 tests, 0 failures, 0 + errors, 0 skipped** (including the new `StatusColorConsistencyTest`, 2 cases, and + the extended `GraphPaletteTest`, 12 cases, and `RunStatusTest`, 3 cases). +- **APK publish.** The run's debug APK is + `…/artifacts/282/1/pipelines-debug-wip-d13f359.apk` (18,486,624 bytes, sha256 + `b11481889b2894efb5fb6b17bcb62af819fe4b6ffb0196f5e27834b4736a5e1c`). + ## Last-run facts on every pipeline row (16 Oct 2026) `android/` only. No server field was added: the whole run history already arrives diff --git a/android/app/src/main/java/net/awan/pipelines/ui/components/RunStatusPalette.kt b/android/app/src/main/java/net/awan/pipelines/ui/components/RunStatusPalette.kt index 418d4760..67f449d6 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/components/RunStatusPalette.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/components/RunStatusPalette.kt @@ -4,17 +4,20 @@ import androidx.compose.ui.graphics.Color import net.awan.pipelines.ui.theme.DarkError /** - * The app-owned run-status palette. + * The app-owned status palette, the single source of truth for the colour of a + * status or stage-outcome word. * - * Run status is a *different vocabulary* from the graph's stage outcomes - * ([net.awan.pipelines.ui.graph.GraphPalette]): a run that is `running` is not a - * `skipped` stage, and a `succeeded` run is not the amber the theme uses for a - * positive *stage* outcome. Borrowing Material roles therefore put the wrong hue - * on the two states that matter most — `primary` (mint) made a *running* run read - * green and `tertiary` (amber) made a *succeeded* run read yellow. + * Borrowing Material roles put the wrong hue on the two states that matter most — + * `primary` (mint) made a *running* run read green and `tertiary` (amber) made a + * *succeeded* run read yellow — so every entry below is a deliberate, fixed + * colour with an explicit meaning. The stage outcomes that share a word with a + * run state (`success`/`done`→[Succeeded], `error`→[Failed], `blocked`, + * `skipped`, `waiting`) resolve here too, through [runStateOf], so the timeline, + * the graph, the runs list, the stage sheet and the peek all draw one word in one + * colour. Only genuinely graph-only flow outcomes (`approved`, `retry`, …) keep + * their own curated colour in [net.awan.pipelines.ui.graph.GraphPalette]. * - * Every entry below is instead a deliberate, fixed colour with an explicit - * meaning, tuned for the dark Pipelines surface (`DarkSurface 0xFF0E1513`, + * Every entry is tuned for the dark Pipelines surface (`DarkSurface 0xFF0E1513`, * over which the chip label is drawn). The contrast of each colour against that * surface is *measured* by `RunStatusPaletteTest`, never judged by eye. Status is * never colour-only: every entry keeps its own material glyph ([runStateIcon]) @@ -29,6 +32,13 @@ internal object RunStatusPalette { private val Running = Entry(Color(0xFF7FB2F0), "blue: in progress; green would read as already finished") + /** + * Waiting for a person (a human decision): a distinct cyan, matching the TUI's + * accent for a paused run, so it is neither the running blue nor a failure. + */ + private val Waiting = + Entry(Color(0xFF8EDFF5), "cyan: paused for a person; distinct from running and from failure") + /** Finished well: the conventional green. Amber/tertiary would read as a warning. */ private val Succeeded = Entry(Color(0xFF7FE0A8), "green: completed successfully; amber would read as a warning") @@ -55,6 +65,13 @@ internal object RunStatusPalette { */ private val Waiting = Entry(Color(0xFFC0A3F5), "violet: parked for the operator's decision; not running, not a stop") + /** Blocked: a stage that could not proceed — a warm amber/orange, never failure red. */ + private val Blocked = + Entry(Color(0xFFF0A35E), "orange: a blocked stage could not proceed; not the failure red") + + /** Skipped: a stage deliberately not run — a cool muted grey-blue, quiet and distinct. */ + private val Skipped = + Entry(Color(0xFFA8B8C8), "muted grey-blue: a stage deliberately not run; quiet, not a status") /** Unknown/blank status: the safe, low-key fallback. */ private val Unknown = @@ -67,12 +84,15 @@ internal object RunStatusPalette { */ fun of(state: RunState): Entry = when (state) { RunState.Running, RunState.Active -> Running + RunState.Waiting -> Waiting RunState.Succeeded -> Succeeded RunState.Failed -> Failed RunState.Interrupted -> Interrupted RunState.Canceled -> Canceled RunState.Queued -> Queued RunState.Waiting -> Waiting + RunState.Blocked -> Blocked + RunState.Skipped -> Skipped RunState.Unknown -> Unknown } } diff --git a/android/app/src/main/java/net/awan/pipelines/ui/graph/GraphPalette.kt b/android/app/src/main/java/net/awan/pipelines/ui/graph/GraphPalette.kt index b15bfca8..4afd4710 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/graph/GraphPalette.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/graph/GraphPalette.kt @@ -8,9 +8,15 @@ import kotlin.math.min import kotlin.math.pow /** - * The curated graph colour palette. + * The curated palette for the graph-only flow outcomes. * - * Every distinct outcome gets its own deliberate entry (no `hashCode() % 4` + * A stage outcome that is also a run state (`success`/`done`/`error`/`blocked`/ + * `skipped`/`waiting`) is coloured from the one owned status palette + * ([net.awan.pipelines.ui.components.RunStatusPalette], through [outcomeColor]), + * so the graph, the timeline and the runs list never disagree. This palette + * covers only the words with no status meaning — the loop/choice outcomes a + * pipeline defines (`rejected`, `exhausted`, `retry`, `approved`, `fast`, + * `missing`) — giving each its own deliberate entry (no `hashCode() % 4` * collisions): the mapping is pure and deterministic, so a given outcome name is * the same colour across runs and recompositions, and an unknown/new name gets a * stable reserved fallback colour instead of silently borrowing a known one. @@ -19,46 +25,35 @@ import kotlin.math.pow * over which the outcome label is drawn on a ~0.92-alpha chip). Every entry is * bright enough to be legible both as a 3px edge stroke and as the small 11sp * label text: contrast is *measured* by [GraphPaletteTest], not asserted by eye. - * - * The two terminal outcomes stay theme roles in [GraphColors] (`error`→error, - * `success`→tertiary) so their meaning is preserved; everything else uses - * [colors]. */ internal object GraphPalette { /** * The fixed palette. Deliberately fixed (rather than scheme-derived) so an - * outcome is the same colour on every device; the two terminal roles above - * remain scheme roles. + * outcome is the same colour on every device. */ val colors: List = listOf( - Color(0xFF8FE0A0), // 0 blocked - green - Color(0xFFF5A3A3), // 1 rejected - red - Color(0xFF8FB4F5), // 2 skipped - blue - Color(0xFFF5B37A), // 3 exhausted - orange - Color(0xFF7FD4E8), // 4 retry - cyan - Color(0xFFC0A3F5), // 5 approved - violet - Color(0xFFF0E07A), // 6 fast - yellow - Color(0xFFF5A3D0), // 7 missing - pink - Color(0xFFD6B08C), // 8 done - sand + Color(0xFFF5A3A3), // 0 rejected - red + Color(0xFFF5B37A), // 1 exhausted - orange + Color(0xFF7FD4E8), // 2 retry - cyan + Color(0xFFC0A3F5), // 3 approved - violet + Color(0xFFF0E07A), // 4 fast - yellow + Color(0xFFF5A3D0), // 5 missing - pink // Reserved fallback region for names not in [KNOWN], kept distinct from // the known entries so an unknown outcome never borrows a known colour. - Color(0xFFD8C98A), // 9 fallback - khaki - Color(0xFF9FD8C0), // 10 fallback - sea - Color(0xFFD8A8C0), // 11 fallback - dusty rose + Color(0xFFD8C98A), // 6 fallback - khaki + Color(0xFF9FD8C0), // 7 fallback - sea + Color(0xFFD8A8C0), // 8 fallback - dusty rose ) - /** The known outcome names and their fixed palette index, in display order. */ + /** The known graph-only outcome names and their fixed palette index, in display order. */ private val KNOWN: Map = linkedMapOf( - "blocked" to 0, - "rejected" to 1, - "skipped" to 2, - "exhausted" to 3, - "retry" to 4, - "approved" to 5, - "fast" to 6, - "missing" to 7, - "done" to 8, + "rejected" to 0, + "exhausted" to 1, + "retry" to 2, + "approved" to 3, + "fast" to 4, + "missing" to 5, ) /** First palette index reserved for names that are not in [KNOWN]. */ @@ -67,8 +62,9 @@ internal object GraphPalette { /** * The palette index for [outcome]. Pure and deterministic for every input * (including blank): known names get their curated slot, everything else a - * stable slot inside the reserved fallback region. `success`/`error` resolve - * to the theme roles in [outcomeColor] but still return a stable index here. + * stable slot inside the reserved fallback region. A word that resolves to a + * run state is coloured from the status palette by [outcomeColor] and does not + * reach this palette. */ fun outcomeColorIndex(outcome: String): Int { KNOWN[outcome]?.let { return it } diff --git a/android/app/src/main/java/net/awan/pipelines/ui/graph/WorkflowGraph.kt b/android/app/src/main/java/net/awan/pipelines/ui/graph/WorkflowGraph.kt index 3218791a..22525fee 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/graph/WorkflowGraph.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/graph/WorkflowGraph.kt @@ -85,8 +85,11 @@ import net.awan.pipelines.data.protocol.GraphSemantics import net.awan.pipelines.data.protocol.Protocol import net.awan.pipelines.data.protocol.RunGraphState import net.awan.pipelines.data.protocol.edges +import net.awan.pipelines.ui.components.RunState import net.awan.pipelines.ui.components.hostResumed import net.awan.pipelines.ui.components.rememberLiveNowMillis +import net.awan.pipelines.ui.components.runStateColor +import net.awan.pipelines.ui.components.runStateOf import net.awan.pipelines.ui.formatDuration import net.awan.pipelines.ui.secondsSince import net.awan.pipelines.ui.theme.GRAPH_ACTIVE_HALO_GAP @@ -534,44 +537,51 @@ internal class GraphColors( /** * The graph's colours for [scheme], built in one place so every surface that must * agree with the graph (the graph itself and the timeline's step-outcome chips) - * uses the same palette. The two terminal roles stay scheme roles so their - * meaning is kept; every other outcome uses the one curated, legible - * [GraphPalette] for both a stroke and its label text. + * uses the same palette. The two terminal roles take the one owned run-status + * colour (success green, failure red) so they can never disagree with the runs + * list; every other status word is coloured by the status palette in + * [outcomeColor], and the remaining graph-only flow outcomes use the one curated, + * legible [GraphPalette] for both a stroke and its label text. * * Node and label surfaces are *tonal*: a raised surface tone ([scheme]'s * `surfaceContainerHigh`/`surfaceContainerHighest`) blended with a subtle tint of * the node's semantic colour (see [tonalFill]) rather than a flat fill, so a node * reads as raised card, not a terminal cell. */ -internal fun graphColors(scheme: ColorScheme): GraphColors = GraphColors( - // The two terminal roles stay scheme roles so their meaning is kept. - success = scheme.tertiary, - error = scheme.error, - // Every other outcome uses the one curated, legible palette for both its - // stroke and its label text, so a curve and its label always agree. - palette = GraphPalette.colors, - // Node fills differ by kind (see [GraphNodeKind]): model (neutral), ntfy - // (amber), other/custom (green), and the two terminals (success/error). Each - // is a tonal surface carrying a subtle tint of that kind's semantic hue. - nodeFill = tonalFill(scheme.surfaceContainerHigh, scheme.onSurfaceVariant, NEUTRAL_TINT), - nodeNtfyFill = tonalFill(scheme.surfaceContainerHigh, scheme.tertiary, KIND_TINT), - nodeCustomFill = tonalFill(scheme.surfaceContainerHigh, scheme.primary, KIND_TINT), - // A selected node inverts (light fill / dark text) plus a stronger border, so - // selection reads in either appearance and never relies on colour. - nodeFillActive = scheme.inverseSurface, - nodeTextActive = scheme.inverseOnSurface, - // The stage border is deliberately soft (a low-contrast outline variant), not - // the hard original outline; terminals carry their outcome hue instead. - nodeBorder = scheme.outlineVariant, - nodeBorderActive = scheme.primary, - nodeText = scheme.onSurface, - terminalFill = tonalFill(scheme.surfaceContainerHigh, scheme.tertiary, TERMINAL_TINT), - terminalErrorFill = tonalFill(scheme.surfaceContainerHigh, scheme.error, TERMINAL_TINT), - // Edge outcome labels sit on a tonal chip (drawn as a rounded rect) rather than - // raw text over the canvas. - labelBackground = scheme.surfaceContainerHighest, - labelText = scheme.onSurfaceVariant, -) +internal fun graphColors(scheme: ColorScheme): GraphColors { + // The two terminal outcomes take the shared run-status colours so the graph + // and the runs list can never disagree about success/failure. + val success = runStateColor(RunState.Succeeded) + val error = runStateColor(RunState.Failed) + return GraphColors( + success = success, + error = error, + // Every other graph-only outcome uses the one curated, legible palette for + // both its stroke and its label text, so a curve and its label always agree. + palette = GraphPalette.colors, + // Node fills differ by kind (see [GraphNodeKind]): model (neutral), ntfy + // (amber), other/custom (green), and the two terminals (success/error). Each + // is a tonal surface carrying a subtle tint of that kind's semantic hue. + nodeFill = tonalFill(scheme.surfaceContainerHigh, scheme.onSurfaceVariant, NEUTRAL_TINT), + nodeNtfyFill = tonalFill(scheme.surfaceContainerHigh, scheme.tertiary, KIND_TINT), + nodeCustomFill = tonalFill(scheme.surfaceContainerHigh, scheme.primary, KIND_TINT), + // A selected node inverts (light fill / dark text) plus a stronger border, so + // selection reads in either appearance and never relies on colour. + nodeFillActive = scheme.inverseSurface, + nodeTextActive = scheme.inverseOnSurface, + // The stage border is deliberately soft (a low-contrast outline variant), not + // the hard original outline; terminals carry their outcome hue instead. + nodeBorder = scheme.outlineVariant, + nodeBorderActive = scheme.primary, + nodeText = scheme.onSurface, + terminalFill = tonalFill(scheme.surfaceContainerHigh, success, TERMINAL_TINT), + terminalErrorFill = tonalFill(scheme.surfaceContainerHigh, error, TERMINAL_TINT), + // Edge outcome labels sit on a tonal chip (drawn as a rounded rect) rather than + // raw text over the canvas. + labelBackground = scheme.surfaceContainerHighest, + labelText = scheme.onSurfaceVariant, + ) +} /** * [surface] blended with a [fraction] (0..1) of [accent], so a node/label fill @@ -1602,17 +1612,19 @@ private fun DrawScope.drawActiveHalo( } /** - * The colour for an outcome: the theme error role for `error`, a clearly - * positive theme colour for `success`, and the curated [GraphPalette] entry for - * everything else. One colour is used for both the edge stroke and its label - * text (the palette is legible on the surface), so a curve and its label always - * agree. `success`/`error` are the terminal roles and are never colour-only - * signals (their labels name them). Pure and deterministic. + * The colour for an outcome or stage status, from the one owned source: a word + * that is a run state (`success`/`done`/`error`/`blocked`/`skipped`/`waiting`/ + * `running`/…) takes the shared status colour the operator already learned from + * the runs list, so the same word is the same colour in the timeline, the graph, + * the stage sheet and the peek; a graph-only flow outcome (`approved`, `retry`, …) + * takes its curated [GraphPalette] entry. One colour serves both the edge stroke + * and its label text (the palette is legible on the surface), so a curve and its + * label always agree. Pure and deterministic. */ -internal fun outcomeColor(outcome: String, colors: GraphColors): Color = when (outcome) { - "error" -> colors.error - "success" -> colors.success - else -> colors.palette[GraphPalette.outcomeColorIndex(outcome)] +internal fun outcomeColor(outcome: String, colors: GraphColors): Color { + val state = runStateOf(outcome) + if (state != RunState.Unknown) return runStateColor(state) + return colors.palette[GraphPalette.outcomeColorIndex(outcome)] } /** diff --git a/android/app/src/main/java/net/awan/pipelines/ui/screens/ListFilter.kt b/android/app/src/main/java/net/awan/pipelines/ui/screens/ListFilter.kt index 8b3d6ddc..b40cba04 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/screens/ListFilter.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/screens/ListFilter.kt @@ -46,13 +46,15 @@ enum class RunPresence(val label: String, val storageKey: String) { /** * The statuses a run filter can select. The server's own run vocabulary - * (internal/pipeline/runs.go: queued/running/succeeded/failed/canceled/ - * interrupted); the app-only `active` usage bucket and the `unknown` fallback - * are deliberately not offered, so a status filter always names a real state. + * (internal/pipeline/runs.go: queued/running/waiting/succeeded/failed/canceled/ + * interrupted); the app-only `active` usage bucket, the stage-outcome words + * (`blocked`/`skipped`) and the `unknown` fallback are deliberately not offered, + * so a status filter always names a real run state. */ internal val RUN_STATUS_FILTERS: List = listOf( RunState.Queued, RunState.Running, + RunState.Waiting, RunState.Succeeded, RunState.Failed, RunState.Canceled, diff --git a/android/app/src/main/java/net/awan/pipelines/ui/screens/RunHistoryScreen.kt b/android/app/src/main/java/net/awan/pipelines/ui/screens/RunHistoryScreen.kt index ffd14a14..4303de82 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/screens/RunHistoryScreen.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/screens/RunHistoryScreen.kt @@ -585,8 +585,10 @@ private fun RunRow( Text( run.diagnostic, style = text.meta, + // The one status colour for a failure, never a scheme role that + // could drift from the chip above it. color = if (state == RunState.Failed) { - MaterialTheme.colorScheme.error + runStateColor(RunState.Failed) } else { MaterialTheme.colorScheme.onSurfaceVariant }, diff --git a/android/app/src/test/java/net/awan/pipelines/ui/components/RunStatusTest.kt b/android/app/src/test/java/net/awan/pipelines/ui/components/RunStatusTest.kt index 2c98d746..ce9a39d4 100644 --- a/android/app/src/test/java/net/awan/pipelines/ui/components/RunStatusTest.kt +++ b/android/app/src/test/java/net/awan/pipelines/ui/components/RunStatusTest.kt @@ -11,14 +11,18 @@ class RunStatusTest { assertEquals(RunState.Queued, runStateOf("queued")) assertEquals(RunState.Waiting, runStateOf("waiting")) assertEquals(RunState.Active, runStateOf("active")) + assertEquals(RunState.Waiting, runStateOf("waiting")) assertEquals(RunState.Succeeded, runStateOf("succeeded")) - // Step/outcome words map onto the same states. + // Step/outcome words map onto the same states, so one word is one colour. assertEquals(RunState.Succeeded, runStateOf("completed")) assertEquals(RunState.Succeeded, runStateOf("success")) + assertEquals(RunState.Succeeded, runStateOf("done")) assertEquals(RunState.Failed, runStateOf("failed")) assertEquals(RunState.Failed, runStateOf("error")) assertEquals(RunState.Canceled, runStateOf("canceled")) assertEquals(RunState.Interrupted, runStateOf("interrupted")) + assertEquals(RunState.Blocked, runStateOf("blocked")) + assertEquals(RunState.Skipped, runStateOf("skipped")) } @Test diff --git a/android/app/src/test/java/net/awan/pipelines/ui/graph/GraphPaletteTest.kt b/android/app/src/test/java/net/awan/pipelines/ui/graph/GraphPaletteTest.kt index d52555ba..7a3a08e0 100644 --- a/android/app/src/test/java/net/awan/pipelines/ui/graph/GraphPaletteTest.kt +++ b/android/app/src/test/java/net/awan/pipelines/ui/graph/GraphPaletteTest.kt @@ -5,6 +5,9 @@ import net.awan.pipelines.data.protocol.GraphEdge import net.awan.pipelines.data.protocol.GraphRoute import net.awan.pipelines.data.protocol.Protocol import net.awan.pipelines.data.protocol.RunGraphState +import net.awan.pipelines.ui.components.RunState +import net.awan.pipelines.ui.components.runStateColor +import net.awan.pipelines.ui.components.runStateOf import org.junit.Assert.assertEquals import org.junit.Assert.assertFalse import org.junit.Assert.assertTrue @@ -15,9 +18,9 @@ class GraphPaletteTest { /** The dark Pipelines surface the outcome label chip is drawn on. */ private val darkSurface = Color(0xFF0E1513) - /** The two terminal roles as the dark scheme supplies them. */ - private val successRole = Color(0xFFF2C879) - private val errorRole = Color(0xFFFFB4AB) + /** The two terminal roles are the shared run-status colours. */ + private val successRole = runStateColor(RunState.Succeeded) + private val errorRole = runStateColor(RunState.Failed) private fun colors() = GraphColors( success = successRole, @@ -43,11 +46,39 @@ class GraphPaletteTest { "exhausted", "retry", "approved", "fast", "missing", "done", ) + /** The outcomes with no run-status meaning that the graph palette owns. */ + private val graphOnlyOutcomes = listOf( + "rejected", "exhausted", "retry", "approved", "fast", "missing", + ) + + /** + * A word that is a run state resolves to exactly the colour the runs list + * draws for it: the graph factory and [outcomeColor] share one source. + */ @Test - fun everyRealisticOutcomeGetsADistinctColour() { + fun statusOutcomesTakeTheSharedRunStatusColour() { val colors = colors() - val mapped = realisticOutcomes.map { outcomeColor(it, colors) } - assertEquals(realisticOutcomes.size, mapped.toSet().size) + listOf( + "success", "completed", "done", "error", "failed", + "blocked", "skipped", "waiting", "running", "queued", + "canceled", "interrupted", + ).forEach { word -> + assertEquals( + "outcomeColor($word) must equal the runs-list colour", + runStateColor(runStateOf(word)), + outcomeColor(word, colors), + ) + } + } + + /** The graph-only outcomes keep distinct curated colours, none a status colour. */ + @Test + fun graphOnlyOutcomesGetDistinctColours() { + val colors = colors() + val mapped = graphOnlyOutcomes.map { outcomeColor(it, colors) } + assertEquals(graphOnlyOutcomes.size, mapped.toSet().size) + val statusColours = RunState.entries.map { runStateColor(it) }.toSet() + mapped.forEach { assertFalse("$it borrowed a run-status colour", it in statusColours) } } @Test @@ -74,10 +105,8 @@ class GraphPaletteTest { assertEquals(unknown, outcomeColor("something-brand-new", colors)) // A blank name is just another unknown: stable and non-throwing. assertEquals(outcomeColor("", colors), outcomeColor("", colors)) - // The fallback comes from the reserved region, not a known outcome slot. - val knownIndices = realisticOutcomes - .filter { it != "success" && it != "error" } - .map { GraphPalette.outcomeColorIndex(it) } + // The fallback comes from the reserved region, not a known graph-only slot. + val knownIndices = graphOnlyOutcomes.map { GraphPalette.outcomeColorIndex(it) } assertFalse(GraphPalette.outcomeColorIndex("something-brand-new") in knownIndices) } diff --git a/android/app/src/test/java/net/awan/pipelines/ui/graph/StatusColorConsistencyTest.kt b/android/app/src/test/java/net/awan/pipelines/ui/graph/StatusColorConsistencyTest.kt new file mode 100644 index 00000000..3233bf5c --- /dev/null +++ b/android/app/src/test/java/net/awan/pipelines/ui/graph/StatusColorConsistencyTest.kt @@ -0,0 +1,57 @@ +package net.awan.pipelines.ui.graph + +import net.awan.pipelines.ui.components.RunState +import net.awan.pipelines.ui.components.runStateColor +import net.awan.pipelines.ui.components.runStateOf +import net.awan.pipelines.ui.theme.PipelinesDarkColors +import org.junit.Assert.assertEquals +import org.junit.Test + +/** + * The one-colour contract behind the status brief: whatever draws a status or a + * stage outcome — the runs list, the timeline's step chips, the graph, the stage + * sheet — resolves a word through one owned source, so a word means one colour + * everywhere and never a second colour for the same meaning. + */ +class StatusColorConsistencyTest { + + private val colors = graphColors(PipelinesDarkColors) + + /** + * Every word the timeline can show that is a run state resolves, through the + * graph factory the timeline uses, to exactly the runs-list colour. + */ + @Test + fun theTimelineColourComesFromTheRunsListSource() { + listOf( + "success", "completed", "done", "error", "failed", + "blocked", "skipped", "waiting", "running", "queued", + "canceled", "cancelled", "interrupted", "active", + ).forEach { word -> + assertEquals( + "timeline colour for '$word' must be the runs-list colour", + runStateColor(runStateOf(word)), + outcomeColor(word, colors), + ) + } + } + + /** + * Every state maps to exactly one colour: the lookup is deterministic, and no + * two states collide except the one deliberate alias (a live run and the + * server's `active` usage bucket are the same in-progress state). + */ + @Test + fun everyStateMapsToExactlyOneColour() { + RunState.entries.forEach { state -> + assertEquals(runStateColor(state), runStateColor(state)) + } + val shared = RunState.entries + .groupBy { runStateColor(it) } + .filterValues { it.size > 1 } + .values + .map { it.toSet() } + .toSet() + assertEquals(setOf(setOf(RunState.Running, RunState.Active)), shared) + } +} From 87856eaaf09b8361903f7a697eaa62588455aad1 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 00:03:29 +0100 Subject: [PATCH 4/9] android: complete the status-palette port onto main's tree The recovered commit gave every status one colour, but it predates main's split of the run view and main's own cyan 'waiting' colour. Resolution: keep main's Waiting, keep the run view's own file (main already has RunSummaryTab), and carry the parts that were genuinely missing - RunState.Blocked and RunState.Skipped with their words, glyphs and one colour each - so the palette and the enum agree. --- .../net/awan/pipelines/ui/components/RunStatus.kt | 8 ++++++++ .../awan/pipelines/ui/components/RunStatusPalette.kt | 11 +++++------ 2 files changed, 13 insertions(+), 6 deletions(-) diff --git a/android/app/src/main/java/net/awan/pipelines/ui/components/RunStatus.kt b/android/app/src/main/java/net/awan/pipelines/ui/components/RunStatus.kt index 4b3d54fd..85024c7b 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/components/RunStatus.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/components/RunStatus.kt @@ -10,6 +10,7 @@ import androidx.compose.foundation.shape.RoundedCornerShape import androidx.compose.material.icons.Icons import androidx.compose.material.icons.automirrored.filled.DirectionsRun import androidx.compose.material.icons.automirrored.filled.HelpOutline +import androidx.compose.material.icons.filled.Block import androidx.compose.material.icons.filled.Bolt import androidx.compose.material.icons.filled.Cancel import androidx.compose.material.icons.filled.CheckCircle @@ -17,6 +18,7 @@ import androidx.compose.material.icons.filled.Error import androidx.compose.material.icons.filled.FrontHand import androidx.compose.material.icons.filled.PauseCircle import androidx.compose.material.icons.filled.Schedule +import androidx.compose.material.icons.filled.SkipNext import androidx.compose.material3.Icon import androidx.compose.material3.Text import androidx.compose.runtime.Composable @@ -48,6 +50,8 @@ enum class RunState(val label: String) { Failed("failed"), Canceled("canceled"), Interrupted("interrupted"), + Blocked("blocked"), + Skipped("skipped"), Active("active"), Unknown("unknown"), } @@ -67,6 +71,8 @@ fun runStateOf(status: String): RunState = when (status.trim().lowercase()) { "failed", "error" -> RunState.Failed "canceled", "cancelled" -> RunState.Canceled "interrupted" -> RunState.Interrupted + "blocked" -> RunState.Blocked + "skipped" -> RunState.Skipped else -> RunState.Unknown } @@ -86,6 +92,8 @@ fun runStateIcon(state: RunState): ImageVector = when (state) { RunState.Failed -> Icons.Default.Error RunState.Canceled -> Icons.Default.Cancel RunState.Interrupted -> Icons.Default.PauseCircle + RunState.Blocked -> Icons.Default.Block + RunState.Skipped -> Icons.Default.SkipNext RunState.Active -> Icons.Default.Bolt RunState.Unknown -> Icons.AutoMirrored.Filled.HelpOutline } diff --git a/android/app/src/main/java/net/awan/pipelines/ui/components/RunStatusPalette.kt b/android/app/src/main/java/net/awan/pipelines/ui/components/RunStatusPalette.kt index 67f449d6..f660c374 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/components/RunStatusPalette.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/components/RunStatusPalette.kt @@ -60,12 +60,12 @@ internal object RunStatusPalette { Entry(Color(0xFF9AA6A2), "neutral grey: waiting, clearly not the in-progress blue") /** - * Parked on a person: violet, distinct from the in-progress blue, the queued - * grey and the amber operator-stop, so a run needing a decision is unmistakable. + * Parked on a person (a human decision): distinct from the in-progress blue, the + * queued grey and the amber operator-stop, so a run needing a decision is + * unmistakable. Blocked and skipped are stage outcomes rather than run states: + * a stage that could not proceed is orange, and one deliberately not run is a + * quiet grey-blue - neither is a failure. */ - private val Waiting = - Entry(Color(0xFFC0A3F5), "violet: parked for the operator's decision; not running, not a stop") - /** Blocked: a stage that could not proceed — a warm amber/orange, never failure red. */ private val Blocked = Entry(Color(0xFFF0A35E), "orange: a blocked stage could not proceed; not the failure red") @@ -90,7 +90,6 @@ internal object RunStatusPalette { RunState.Interrupted -> Interrupted RunState.Canceled -> Canceled RunState.Queued -> Queued - RunState.Waiting -> Waiting RunState.Blocked -> Blocked RunState.Skipped -> Skipped RunState.Unknown -> Unknown From 597c7b5e767aa3072dd9bb633cb0ae909f20fa74 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 00:04:28 +0100 Subject: [PATCH 5/9] android: show a chat's in-flight tool work instead of a bare Running A session said "Running" with an empty tool chip while it worked, so a silent wait was indistinguishable from a stuck one. Derive the in-flight work from the stream the app already folds and show it on both surfaces. - ChatFormat: runningToolCalls() reads the tool parts still running, in transcript order, so the conversation and the session row share one set; toolDetail() takes the command/description the part actually carries (the first of description/command/filePath/file_path/path/pattern/query/url), collapsed to one line and elided at 72 chars, and returns null rather than a fabricated summary; runningToolElapsedMillis() uses the protocol's own time.ran/created when present and the local per-part stamp otherwise; runningToolStamps() keeps a stable start per part across frames; TOOL_LONG_RUNNING_MILLIS (60s) and toolLongRunning() mark an unusually long call; sessionWorkLabel() names what a working session is doing while a text-streaming turn stays plain "Running" and a busy session never reads "Idle". - ChatStore: ChatThread gains toolStartedAt, stamped when a part turns running and dropped when it settles, plus runningTools/toolElapsedMillis; history() and the frame fold maintain it; setRunning/turn end clear it. - ChatTranscript: RunningIndicator lists one line per running call (name, detail where present, live elapsed) keyed by part id so concurrent calls render together without flicker; no percentage, ETA or progress bar. - ChatListPane: the session row renders sessionWorkLabel(busy, thread). - ChatRunningWorkTest covers name/detail/elapsed, clear on completion, error state, concurrent calls and the no-detail stream. Only fields the harness reports are used: tool name, state.status and input; the live brokered frame carries no timing envelope, so elapsed falls back to the local stamp. Existing chips, INPUT/OUTPUT, reasoning blocks, stop control, activity marks and scroll/follow behaviour are untouched. Checked and unchanged: no packaged template or packaged authoring-skill reference describes this app surface (the chat references in internal/author/skill/references/ document the server's brokered chat_* protocol, which this change does not touch), so none is stale. android/AGENTS.md already names ui/chat/ and its files. The shared documents this change does make stale are recorded, not edited, in docs/notes/chat-in-flight-tool-work.md: the Running-indicator and session-status statements in android/README.md. --- .../net/awan/pipelines/ui/chat/ChatFormat.kt | 121 +++++++++ .../awan/pipelines/ui/chat/ChatListPane.kt | 7 +- .../net/awan/pipelines/ui/chat/ChatStore.kt | 45 +++- .../awan/pipelines/ui/chat/ChatTranscript.kt | 90 ++++++- .../pipelines/ui/chat/ChatRunningWorkTest.kt | 235 ++++++++++++++++++ docs/notes/chat-in-flight-tool-work.md | 65 +++++ 6 files changed, 546 insertions(+), 17 deletions(-) create mode 100644 android/app/src/test/java/net/awan/pipelines/ui/chat/ChatRunningWorkTest.kt create mode 100644 docs/notes/chat-in-flight-tool-work.md diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt index d50c87cc..58d7c8ac 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt @@ -7,6 +7,7 @@ import kotlinx.serialization.json.JsonObject import kotlinx.serialization.json.JsonPrimitive import net.awan.pipelines.data.protocol.ChatPart import net.awan.pipelines.data.protocol.ChatPermissionFrame +import net.awan.pipelines.data.protocol.ChatMessage import net.awan.pipelines.data.protocol.ChatProtocol import net.awan.pipelines.data.protocol.ChatSession import net.awan.pipelines.data.protocol.ChatToolState @@ -79,6 +80,126 @@ internal fun formatToolDuration(millis: Long): String = when { /** The chip label for a tool call: its name, or a placeholder when unnamed. */ internal fun toolLabel(part: ChatPart): String = part.name.ifBlank { "tool" } +/** + * The in-flight tool calls across a conversation's [messages], in transcript + * order, so the conversation's indicator and the session row read the same set + * and its order is stable from frame to frame (a chip is never re-ordered by a + * rebuild). A call drops out the moment it completes or errors, which is what + * clears the indicator, so nothing here ever invents a finish time. + */ +internal fun runningToolCalls(messages: List): List = + messages.flatMap { it.parts } + .filter { it.type == ChatProtocol.PART_TOOL && ChatProtocol.toolRunning(it.state) } + +/** + * The input keys, in preference order, that carry a human-facing command or a + * short description of what a tool call is doing. OpenCode's tools put the + * substance in different places (`command` for a shell, `description` for a task, + * a path or pattern for the file/search tools), so the first one present is shown + * rather than the raw arguments. + */ +private val TOOL_DETAIL_KEYS = listOf( + "description", "command", "filePath", "file_path", "path", "pattern", "query", "url", +) + +/** How much of a command/description the phone shows before it is elided. */ +private const val TOOL_DETAIL_MAX_LENGTH = 72 + +private val TOOL_DETAIL_WHITESPACE = Regex("\\s+") + +/** + * A one-line command or short description for [part], taken from the input the + * part actually carries: the first of [TOOL_DETAIL_KEYS] present, collapsed to a + * single line and elided past [TOOL_DETAIL_MAX_LENGTH]. Null when the input + * carries no such key (a partial-JSON string while the call is still streaming, + * or a tool that reports none), so a caller shows the name alone rather than a + * fabricated summary. + */ +internal fun toolDetail(part: ChatPart): String? { + val obj = part.state?.input as? JsonObject ?: return null + for (key in TOOL_DETAIL_KEYS) { + val value = obj[key] as? JsonPrimitive ?: continue + if (!value.isString) continue + val text = value.content.trim().replace(TOOL_DETAIL_WHITESPACE, " ") + if (text.isBlank()) continue + return if (text.length <= TOOL_DETAIL_MAX_LENGTH) { + text + } else { + text.take(TOOL_DETAIL_MAX_LENGTH - 1).trimEnd() + "…" + } + } + return null +} + +/** + * How long a running [part] has been going at [nowMillis]. The protocol's own + * timing wins whenever the part carries it (a running call from stored history + * has `time.ran`, the moment it started); otherwise the elapsed is measured + * locally from [startedAt] — the wall clock at which this client first saw the + * part running. Zero when neither is usable, so a caller never shows a time it + * cannot stand behind. + */ +internal fun runningToolElapsedMillis(part: ChatPart, startedAt: Long, nowMillis: Long): Long { + val protocolStart = part.time?.let { if (it.ran > 0) it.ran else it.created } ?: 0L + val start = if (protocolStart > 0) protocolStart else startedAt + return if (start in 1 until nowMillis) nowMillis - start else 0L +} + +/** + * A tool call running longer than this reads as unusually long on the phone and + * is marked, so a genuinely stuck call is visible without a fabricated ETA. One + * minute: long enough that ordinary calls (a build, a search, a command) are not + * flagged, short enough that a hung call stands out while the operator is still + * wondering. + */ +internal const val TOOL_LONG_RUNNING_MILLIS: Long = 60_000L + +/** Whether a running call has been going long enough to be marked as unusual. */ +internal fun toolLongRunning(elapsedMillis: Long): Boolean = elapsedMillis >= TOOL_LONG_RUNNING_MILLIS + +/** + * The running-tool start stamps after a thread's [messages] changed: every tool + * part in flight keeps the stamp it already had, or is stamped with [now] when it + * has just turned running, and a part that is no longer running loses its stamp. + * Kept free of Compose and of [ChatStore] so the bookkeeping and its unit test + * share one rule, and a stamp never moves forward while a call keeps running. + */ +internal fun runningToolStamps( + current: Map, + messages: List, + now: Long, +): Map { + val stamps = LinkedHashMap() + messages.forEach { message -> + message.parts.forEach { part -> + if (part.id.isNotEmpty() && part.type == ChatProtocol.PART_TOOL && ChatProtocol.toolRunning(part.state)) { + stamps[part.id] = current[part.id] ?: now + } + } + } + return stamps +} + +/** + * The status a session row reports while a turn is in flight: it names the tool + * call it is parked on (or how many, when several run at once) so a working chat + * says what it is doing rather than just `Running`, and a chat only generating + * text still reads as plain `Running` — the two are never confused. A chat with + * nothing running falls back to the ordinary busy/idle label, so a session + * waiting on another client is never shown as idle. + */ +internal fun sessionWorkLabel(busy: Boolean, thread: ChatThread?): String = when { + thread?.running == true -> runningSessionLabel(thread.runningTools) + busy -> "Busy · read-only" + else -> "Idle" +} + +private fun runningSessionLabel(tools: List): String = when (tools.size) { + 0 -> "Running" + 1 -> "Running ${toolLabel(tools.single())}" + else -> "Running ${tools.size} tools" +} + /** * A session's short title: the server title, or a truncated id when untitled, so * a row never renders as a blank line. diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatListPane.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatListPane.kt index e58ec9cf..a35e6154 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatListPane.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatListPane.kt @@ -255,8 +255,8 @@ private fun SessionListItem( val thread = state.thread(session.id) SessionRow( session = session, + thread = thread, open = thread != null, - running = thread?.running == true, unseen = state.isUnseen(session), active = state.activeId == session.id, onClick = { vm.openChatSession(session) }, @@ -289,8 +289,8 @@ private const val NO_DIRECTORY_LABEL = "No directory" @Composable private fun SessionRow( session: ChatSession, + thread: ChatThread?, open: Boolean, - running: Boolean, unseen: Boolean, active: Boolean, onClick: () -> Unit, @@ -298,6 +298,7 @@ private fun SessionRow( onRemove: () -> Unit, ) { val texts = pipelinesText() + val running = thread?.running == true val activity = sessionActivity(running, unseen) ListRow(selected = active, onClick = onClick) { Row( @@ -321,7 +322,7 @@ private fun SessionRow( SessionMenu(onRename = onRename, onRemove = onRemove) } val meta = buildList { - add(sessionStatusLabel(session, running)) + add(sessionWorkLabel(session.busy, thread)) if (session.directory.isNotBlank()) add(session.directory) if (session.model.isNotBlank()) add(session.model) }.joinToString(" · ") diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt index a3d80f75..14d02ef2 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt @@ -70,6 +70,15 @@ data class ChatThread( * the turn settles. */ val runningSince: Long = 0, + /** + * Wall-clock epoch millis each currently-running tool call was first seen + * running, keyed by the tool part's id. The brokered stream pushes a tool part + * with no timing envelope, so a running call's elapsed time is measured from + * here; a call that settles loses its stamp. Kept on the thread (not in the + * composable) so the elapsed time survives a chat switch, exactly like + * [runningSince] does for the turn. + */ + val toolStartedAt: Map = emptyMap(), /** The unsent composer text for this chat. */ val draft: String = "", /** @@ -120,6 +129,22 @@ data class ChatThread( */ fun elapsedMillis(nowMillis: Long): Long = if (running && runningSince in 1 until nowMillis) nowMillis - runningSince else 0 + + /** + * The tool calls still in flight for this session, in transcript order, so the + * conversation's in-flight indicator and the session row both read the same + * set. Empty once every call has completed or errored, which is what clears + * the indicator. + */ + val runningTools: List get() = runningToolCalls(messages) + + /** + * How long [part] has been running at [nowMillis]: the protocol's own timing + * when the part carries it, else the local start recorded in [toolStartedAt] + * (see [runningToolElapsedMillis]). Zero when neither is usable. + */ + fun toolElapsedMillis(part: ChatPart, nowMillis: Long): Long = + runningToolElapsedMillis(part, toolStartedAt[part.id] ?: 0L, nowMillis) } /** @@ -580,7 +605,16 @@ class ChatStore( */ fun history(sessionId: String, messages: List) { update(sessionId) { - it.copy(messages = messages, loading = false, loaded = true, error = null) + it.copy( + messages = messages, + loading = false, + loaded = true, + error = null, + // A running call the history reports (a turn that started before + // this fetch) is stamped now, the best local measurement there is; + // a call that already settled drops its stamp. + toolStartedAt = runningToolStamps(it.toolStartedAt, messages, now()), + ) } // A conversation on screen is read as its history arrives: its recency // watermark advances to the newest message the server reports (its own @@ -605,7 +639,9 @@ class ChatStore( val ids = _state.value.open.map { it.sessionId } if (ids.isEmpty()) return ids _state.value = _state.value.copy( - open = _state.value.open.map { if (it.running) it.copy(running = false, runningSince = 0) else it }, + open = _state.value.open.map { + if (it.running) it.copy(running = false, runningSince = 0, toolStartedAt = emptyMap()) else it + }, ) return ids } @@ -777,7 +813,8 @@ class ChatStore( val updated = upsert(if (partIndex >= 0) parts[partIndex] else null) if (partIndex >= 0) parts[partIndex] = updated else parts.add(updated) messages[resolvedIndex] = message.copy(parts = parts) - setRunning(thread.copy(messages = messages), true) + val stamped = runningToolStamps(thread.toolStartedAt, messages, now()) + setRunning(thread.copy(messages = messages, toolStartedAt = stamped), true) } } @@ -790,7 +827,7 @@ class ChatStore( private fun setRunning(thread: ChatThread, running: Boolean): ChatThread = when { running && !thread.running -> thread.copy(running = true, runningSince = now()) running -> thread - else -> thread.copy(running = false, runningSince = 0) + else -> thread.copy(running = false, runningSince = 0, toolStartedAt = emptyMap()) } private fun update(sessionId: String, block: (ChatThread) -> ChatThread) { diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatTranscript.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatTranscript.kt index ddb3f115..7193487a 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatTranscript.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatTranscript.kt @@ -20,6 +20,7 @@ import androidx.compose.foundation.lazy.items import androidx.compose.foundation.shape.RoundedCornerShape import androidx.compose.foundation.text.selection.SelectionContainer import androidx.compose.material.icons.Icons +import androidx.compose.material.icons.filled.Build import androidx.compose.material.icons.filled.KeyboardArrowDown import androidx.compose.material.icons.filled.KeyboardArrowUp import androidx.compose.material.icons.filled.Psychology @@ -34,6 +35,7 @@ import androidx.compose.runtime.Composable import androidx.compose.runtime.LaunchedEffect import androidx.compose.runtime.derivedStateOf import androidx.compose.runtime.getValue +import androidx.compose.runtime.key import androidx.compose.runtime.mutableLongStateOf import androidx.compose.runtime.mutableStateOf import androidx.compose.runtime.remember @@ -46,6 +48,7 @@ import androidx.compose.ui.Modifier import androidx.compose.ui.platform.LocalDensity import androidx.compose.ui.semantics.Role import androidx.compose.ui.text.font.FontFamily +import androidx.compose.ui.text.style.TextOverflow import androidx.compose.ui.unit.dp import kotlinx.coroutines.delay import kotlinx.coroutines.flow.collect @@ -57,6 +60,7 @@ import net.awan.pipelines.ui.formatDuration import net.awan.pipelines.ui.theme.CHAT_BUBBLE_MAX_WIDTH_DP import net.awan.pipelines.ui.theme.CHAT_FOLLOW_THRESHOLD_DP import net.awan.pipelines.ui.theme.ICON_INLINE_DP +import net.awan.pipelines.ui.theme.ICON_STATUS_DP import net.awan.pipelines.ui.theme.SPACING_XS /** The running indicator's elapsed time ticks once a second, never per frame. */ @@ -274,24 +278,90 @@ private fun LazyListState.bottomDistancePx(itemCount: Int): Int? { /** * The in-flight turn indicator: a spinner, `Working…` and the turn's live elapsed - * time. The elapsed value is derived from the turn's own start ([ChatThread.elapsedMillis]), - * so it keeps counting across a chat switch, and the tick loop stops the moment - * the turn settles. + * time, then one compact line for each tool call in flight — its name, the + * command or description the part carries, and how long that call has been + * running. The elapsed values are derived from the turn's own start + * ([ChatThread.elapsedMillis]) and each call's own start + * ([ChatThread.toolElapsedMillis]), so they keep counting across a chat switch, + * and the tick loop stops the moment the turn settles. This is what makes the + * otherwise-silent part of a turn legible: the operator can tell `working on X` + * from `waiting on something` instead of watching a bare `Running`. */ @Composable private fun RunningIndicator(thread: ChatThread) { - val elapsedMillis = thread.elapsedMillis(rememberElapsedNow(thread.runningSince)) + val now = rememberElapsedNow(thread.runningSince) + val elapsedMillis = thread.elapsedMillis(now) + val tools = thread.runningTools + Column( + verticalArrangement = Arrangement.spacedBy(SPACING_XS), + modifier = Modifier.fillMaxWidth().padding(vertical = 4.dp), + ) { + Row( + verticalAlignment = Alignment.CenterVertically, + horizontalArrangement = Arrangement.spacedBy(CHAT_ITEM_GAP), + ) { + CircularProgressIndicator(Modifier.size(16.dp), strokeWidth = 2.dp) + Text("Working…", style = MaterialTheme.typography.bodySmall, color = MaterialTheme.colorScheme.onSurfaceVariant) + Text( + text = "· ${formatDuration(elapsedMillis / 1_000)}", + style = MaterialTheme.typography.bodySmall, + color = MaterialTheme.colorScheme.onSurfaceVariant, + ) + } + // One line per call in flight, in transcript order and keyed by the part, + // so several running at once read together rather than flickering between + // them; a call's line drops out the moment it completes or errors. + tools.forEach { part -> + key(part.id) { RunningToolLine(part, thread.toolElapsedMillis(part, now)) } + } + } +} + +/** + * One tool call in flight: its name, the command or short description the part + * carries (when it carries one) and how long it has been running. A call that has + * been running past [TOOL_LONG_RUNNING_MILLIS] is tinted and labelled so a stuck + * call stands out. The elapsed time is the only progress signal; no percentage, + * ETA or progress bar is ever invented. + */ +@Composable +private fun RunningToolLine(part: ChatPart, elapsedMillis: Long) { + val long = toolLongRunning(elapsedMillis) + val tint = if (long) MaterialTheme.colorScheme.error else MaterialTheme.colorScheme.onSurfaceVariant + val detail = toolDetail(part) Row( verticalAlignment = Alignment.CenterVertically, horizontalArrangement = Arrangement.spacedBy(CHAT_ITEM_GAP), - modifier = Modifier.fillMaxWidth().padding(vertical = 4.dp), + modifier = Modifier.fillMaxWidth().padding(start = CHAT_GUTTER), ) { - CircularProgressIndicator(Modifier.size(16.dp), strokeWidth = 2.dp) - Text("Working…", style = MaterialTheme.typography.bodySmall, color = MaterialTheme.colorScheme.onSurfaceVariant) + Icon( + Icons.Default.Build, + contentDescription = null, + tint = tint, + modifier = Modifier.size(ICON_STATUS_DP), + ) Text( - text = "· ${formatDuration(elapsedMillis / 1_000)}", - style = MaterialTheme.typography.bodySmall, - color = MaterialTheme.colorScheme.onSurfaceVariant, + text = toolLabel(part), + style = MaterialTheme.typography.labelMedium, + color = tint, + maxLines = 1, + overflow = TextOverflow.Ellipsis, + modifier = if (detail == null) Modifier.weight(1f) else Modifier, + ) + if (detail != null) { + Text( + text = detail, + style = MaterialTheme.typography.labelMedium, + color = MaterialTheme.colorScheme.onSurfaceVariant, + maxLines = 1, + overflow = TextOverflow.Ellipsis, + modifier = Modifier.weight(1f), + ) + } + Text( + text = formatDuration(elapsedMillis / 1_000) + if (long) " · long" else "", + style = MaterialTheme.typography.labelMedium, + color = tint, ) } } diff --git a/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatRunningWorkTest.kt b/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatRunningWorkTest.kt new file mode 100644 index 00000000..3e82282d --- /dev/null +++ b/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatRunningWorkTest.kt @@ -0,0 +1,235 @@ +package net.awan.pipelines.ui.chat + +import kotlinx.serialization.json.JsonObject +import kotlinx.serialization.json.JsonPrimitive +import net.awan.pipelines.data.protocol.ChatEventFrame +import net.awan.pipelines.data.protocol.ChatMessage +import net.awan.pipelines.data.protocol.ChatPart +import net.awan.pipelines.data.protocol.ChatProtocol +import net.awan.pipelines.data.protocol.ChatSession +import net.awan.pipelines.data.protocol.ChatTime +import net.awan.pipelines.data.protocol.ChatToolState +import org.junit.Assert.assertEquals +import org.junit.Assert.assertFalse +import org.junit.Assert.assertNull +import org.junit.Assert.assertTrue +import org.junit.Test + +/** + * The in-flight work a conversation and its session row show: a running tool with + * its name, the command or description the part carries, and a live elapsed time + * that grows from when the call turned running, uses the protocol's own timing + * when the part has it, and clears the moment the call completes or errors. All + * pure or driven against [ChatStore] with an injected clock, so no device, server + * or Compose runtime is needed. + */ +class ChatRunningWorkTest { + + private fun tool( + id: String, + name: String, + status: String, + input: JsonObject? = null, + time: ChatTime? = null, + ) = ChatPart( + type = ChatProtocol.PART_TOOL, + id = id, + name = name, + state = ChatToolState(status = status, input = input), + time = time, + ) + + private fun toolFrame(sessionId: String, messageId: String, part: ChatPart) = + ChatEventFrame(sessionId = sessionId, messageId = messageId, kind = ChatProtocol.PART_TOOL, part = part) + + private fun input(vararg pairs: Pair): JsonObject = + JsonObject(pairs.associate { (key, value) -> key to JsonPrimitive(value) }) + + private fun threadWith(vararg parts: ChatPart) = ChatThread( + sessionId = "s", + running = true, + messages = listOf( + ChatMessage( + id = "m1", + sessionId = "s", + role = ChatProtocol.ROLE_ASSISTANT, + parts = parts.toList(), + ), + ), + ) + + @Test + fun aRunningToolShowsItsNameDetailAndGrowingTime() { + var clock = 1_000L + val store = ChatStore(now = { clock }) + store.open(ChatSession(id = "s", title = "s")) + store.history("s", emptyList()) + + store.event( + toolFrame("s", "m1", tool("c1", "shell", ChatProtocol.TOOL_RUNNING, input("command" to "ls -la"))), + ) + + val thread = store.value.thread("s")!! + assertTrue(thread.running) + val call = thread.runningTools.single() + assertEquals("shell", call.name) + assertEquals("ls -la", toolDetail(call)) + // Elapsed is measured locally from when the call turned running, so it + // starts at zero and grows with the clock. + assertEquals(0L, thread.toolElapsedMillis(call, clock)) + clock = 6_000L + val later = thread.toolElapsedMillis(call, clock) + assertEquals(5_000L, later) + assertTrue(later > 0L) + } + + @Test + fun aToolWithProtocolTimingUsesItsOwnStart() { + val timed = tool("c1", "bash", ChatProtocol.TOOL_RUNNING, time = ChatTime(created = 900, ran = 1_000)) + // The protocol's own `ran` wins over the local stamp, so the elapsed is + // its start to now. + assertEquals(4_000L, runningToolElapsedMillis(timed, startedAt = 0L, nowMillis = 5_000L)) + // Neither a protocol start nor a local one: nothing to show, never a guess. + assertEquals(0L, runningToolElapsedMillis(tool("c2", "bash", ChatProtocol.TOOL_RUNNING), 0L, 5_000L)) + } + + @Test + fun aCompletedOrFailedCallLeavesTheRunningSetAndTheFailureIsVisible() { + var clock = 1_000L + val store = ChatStore(now = { clock }) + store.open(ChatSession(id = "s", title = "s")) + + store.event(toolFrame("s", "m1", tool("c1", "shell", ChatProtocol.TOOL_RUNNING, input("command" to "ls")))) + assertEquals(1, store.value.thread("s")!!.runningTools.size) + + // Completion clears the call from the in-flight set and drops its stamp. + clock = 2_000L + store.event(toolFrame("s", "m1", tool("c1", "shell", ChatProtocol.TOOL_COMPLETED, input("command" to "ls")))) + val done = store.value.thread("s")!! + assertTrue(done.runningTools.isEmpty()) + assertTrue(done.toolStartedAt.isEmpty()) + assertFalse(toolFailed(done.messages.last().parts.single().state)) + + // A failure is out of the running set too, and reads as failed on its chip. + store.event(toolFrame("s", "m1", tool("c2", "shell", ChatProtocol.TOOL_ERROR))) + val failed = store.value.thread("s")!! + assertTrue(failed.runningTools.isEmpty()) + assertTrue(toolFailed(failed.messages.last().parts.first { it.id == "c2" }.state)) + } + + @Test + fun severalCallsRunTogetherInOrderWithStableStartStamps() { + var clock = 1_000L + val store = ChatStore(now = { clock }) + store.open(ChatSession(id = "s", title = "s")) + + store.event(toolFrame("s", "m1", tool("c1", "shell", ChatProtocol.TOOL_RUNNING, input("command" to "build")))) + clock = 2_000L + store.event(toolFrame("s", "m1", tool("c2", "grep", ChatProtocol.TOOL_RUNNING, input("pattern" to "TODO")))) + + val thread = store.value.thread("s")!! + // Both render, in transcript order, so the list does not flicker between them. + assertEquals(listOf("c1", "c2"), thread.runningTools.map { it.id }) + // Each keeps the clock it first turned running on... + assertEquals(mapOf("c1" to 1_000L, "c2" to 2_000L), thread.toolStartedAt) + + // ...so a later frame for the first call does not restart its timer. + clock = 3_000L + store.event( + toolFrame("s", "m1", tool("c1", "shell", ChatProtocol.TOOL_RUNNING, input("command" to "build && test"))), + ) + val updated = store.value.thread("s")!! + assertEquals(1_000L, updated.toolStartedAt["c1"]) + clock = 11_000L + assertEquals(10_000L, updated.toolElapsedMillis(updated.runningTools.single { it.id == "c1" }, clock)) + } + + @Test + fun aCallWithoutADescriptionStillRendersNameStatusAndTime() { + var clock = 5_000L + val store = ChatStore(now = { clock }) + store.open(ChatSession(id = "s", title = "s")) + // No input at all: the part carries no description to show. + store.event(toolFrame("s", "m1", tool("c1", "task", ChatProtocol.TOOL_RUNNING))) + + val call = store.value.thread("s")!!.runningTools.single() + assertNull(toolDetail(call)) + assertEquals("task", toolLabel(call)) + assertTrue(ChatProtocol.toolRunning(call.state)) + clock = 9_000L + assertEquals(4_000L, store.value.thread("s")!!.toolElapsedMillis(call, clock)) + } + + @Test + fun toolDetailPrefersDescriptionThenCommandAndIgnoresWhatItCannotRead() { + // A description wins over a command when both are present. + assertEquals( + "Summarise the diff", + toolDetail( + tool( + "c1", "task", ChatProtocol.TOOL_RUNNING, + input("description" to "Summarise the diff", "command" to "git diff"), + ), + ), + ) + // A shell's command is next. + assertEquals( + "ls -la", + toolDetail(tool("c2", "shell", ChatProtocol.TOOL_RUNNING, input("command" to "ls -la"))), + ) + // A file tool's path is shown when nothing more descriptive exists. + assertEquals( + "/tmp/a.txt", + toolDetail(tool("c3", "read", ChatProtocol.TOOL_RUNNING, input("filePath" to "/tmp/a.txt"))), + ) + // A multi-line command collapses to a single line. + assertEquals( + "run this", + toolDetail(tool("c4", "shell", ChatProtocol.TOOL_RUNNING, input("command" to "run\n this"))), + ) + // A partial (not-yet-object) input, a missing state, and an input with no + // known key all show nothing rather than something invented. + assertNull( + toolDetail( + ChatPart( + type = ChatProtocol.PART_TOOL, + id = "c5", + name = "shell", + state = ChatToolState(status = ChatProtocol.TOOL_STREAMING, input = JsonPrimitive("{\"command\"")), + ), + ), + ) + assertNull(toolDetail(ChatPart(type = ChatProtocol.PART_TOOL, id = "c6", name = "shell"))) + assertNull(toolDetail(tool("c7", "shell", ChatProtocol.TOOL_RUNNING, input("foo" to "bar")))) + } + + @Test + fun aCallRunningTooLongIsMarked() { + assertFalse(toolLongRunning(TOOL_LONG_RUNNING_MILLIS - 1)) + assertTrue(toolLongRunning(TOOL_LONG_RUNNING_MILLIS)) + } + + @Test + fun theSessionRowReportsWhatIsRunning() { + assertEquals("Running shell", sessionWorkLabel(busy = false, threadWith(tool("c1", "shell", ChatProtocol.TOOL_RUNNING)))) + assertEquals( + "Running 2 tools", + sessionWorkLabel( + busy = false, + threadWith( + tool("c1", "shell", ChatProtocol.TOOL_RUNNING), + tool("c2", "grep", ChatProtocol.TOOL_RUNNING), + ), + ), + ) + // A turn running with no tool yet reads as plain Running, never idle, so a + // text stream and a parked tool call stay distinguishable. + assertEquals("Running", sessionWorkLabel(busy = false, ChatThread(sessionId = "s", running = true))) + assertEquals("Running", sessionWorkLabel(busy = true, ChatThread(sessionId = "s", running = true))) + + // Nothing running falls back to the ordinary busy/idle label. + assertEquals("Busy · read-only", sessionWorkLabel(busy = true, thread = null)) + assertEquals("Idle", sessionWorkLabel(busy = false, thread = null)) + assertEquals("Idle", sessionWorkLabel(busy = false, ChatThread(sessionId = "s"))) + } +} diff --git a/docs/notes/chat-in-flight-tool-work.md b/docs/notes/chat-in-flight-tool-work.md new file mode 100644 index 00000000..605f1bdf --- /dev/null +++ b/docs/notes/chat-in-flight-tool-work.md @@ -0,0 +1,65 @@ +# Chat in-flight tool work + +## What this item changed + +`android/` only, the chat's two "working" surfaces. + +- `ui/chat/ChatFormat.kt` adds `runningToolCalls` (the tool parts still + `running`, in transcript order), `toolDetail` (the command/description the + part's own input carries, from description/command/filePath/file_path/path/ + pattern/query/url, one line, elided at 72 chars, `null` when absent), + `runningToolElapsedMillis` (the protocol's `time.ran`/`created` when present, + else the local per-part stamp), `runningToolStamps` (a stable start per part + across frames), `TOOL_LONG_RUNNING_MILLIS` = 60s with `toolLongRunning`, and + `sessionWorkLabel`. +- `ui/chat/ChatStore.kt`: `ChatThread.toolStartedAt` plus `runningTools` and + `toolElapsedMillis`; `history()`, the frame fold and `setRunning` maintain it. +- `ui/chat/ChatTranscript.kt`: `RunningIndicator` now also lists one line per + running call (name, detail where present, live elapsed), keyed by part id so + concurrent calls render together; a call past 60s is tinted and marked + `· long`. +- `ui/chat/ChatListPane.kt`: the session row renders + `sessionWorkLabel(session.busy, thread)`. +- `ui/chat/ChatRunningWorkTest.kt` covers it (name/detail/elapsed, clear on + completion, error state, concurrent calls, no-detail stream). + +No percentage, ETA or progress bar is invented; only the reported fields (tool +name, `state.status`, `state.input`) are used. + +## Shared documents this change makes stale + +`android/README.md` documents the two surfaces this item changed, in the +`## Streaming replies (16 Oct 2026)` record. The note is written here rather +than edited in place; the `docs-fold` writer should update it. + +- `android/README.md:4633` — the **Running indicator** bullet reads "The + transcript's indicator shows the spinner, `Working…` and the live elapsed + time (ticked once a second, never per frame, through the shared + `formatDuration`)." It should add that the indicator also lists, one line per + tool call still in flight, the call's name, the command/description the part + carries when it carries one, and that call's own live elapsed time; that a + call running 60 seconds or more is tinted and marked `· long`; that a call's + line drops out the moment it completes or errors, which is what clears the + indicator; and that no percentage, ETA or progress bar is shown. The rest of + the bullet (one-second tick, the tick loop keyed on the turn's start, the + elapsed count surviving a chat switch) is still true. +- `android/README.md:4454` — the session-list sentence "the list shows each + session's running/busy/read-only status" is now incomplete: a working session + row names what it is doing (`Running `, or `Running tools` when + several run at once) instead of only `Running`, while a turn that is only + generating text still reads plain `Running`, so the two stay distinguishable; + a busy session with nothing running still reads `Busy · read-only`, and an + idle one `Idle`. + +Dates, counts and capture names in those dated records are past evidence and +stay as they are; only the two behaviour statements above are now stale. + +## Not stale + +- No packaged OpenCode skill reference documents this app surface. The chat + references in `internal/author/skill/references/operations.md` document the + server's brokered `chat_*` protocol, which this change does not touch, and no + packaged template or `internal/author/` managed file names the app's chat + indicator or session label. +- `android/AGENTS.md` already lists `ui/chat/` and its files, so it needs no + change. From 6cb61578def0c1850f2f7fbef951c52440693d4c Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 00:09:14 +0100 Subject: [PATCH 6/9] Fan a chat session out to every client and share approvals exactly-once A session was owned by one connection: the claim map in chat_claims.go let the first client hold it, every other client saw the session Busy and read-only, and a second client's prompt was rejected. Replace the claim with a per-session "room" so the operator's phone, tablet and terminal all watch and write the same conversation, and a pending approval is a shared, exactly-once object. Server (internal/server, internal/protocol): - New chat_room.go: one room per session holding the session's single broker stream, its one bounded prompt queue (8) and the fan-out to every attached client. A chat_subscribe frame attaches a connection to a session's shared stream and replays the still-unresolved approval requests the room holds. - chat_stream.go: handleChatPrompt accepts a prompt from any client. It attaches the sender, either starts a turn or queues the prompt behind the in-flight turn and acknowledges it with chat_queued:true ("queued" is the chosen behaviour, stated on the wire and in docs/cli.md), and echoes the user turn to every other client attributed to the sender's label. The prompt handler no longer owns the stream; one turn runner per room drains the queue, so two turns never interleave. Per-connection write serialisation is unchanged (each chatSub has its own writer goroutine and bounded buffer). - chat_permissions.go / chat_commands.go: an approval is reserved by the first answer and confirmed once delivered; the first answer wins, is recorded with the answering client's label, and the resolution is pushed to every watching client as chat_permission with resolved/decision/resolved_by so their cards clear. A later answer is refused with an error naming the client that answered, and never reaches the agent twice; a reservation whose reply failed is released. - chat_hub.go / chat_sessions.go / chat.go: the hub now owns rooms and the user-turn id sequence; the resulting user turns are retained (role and client carried) so a reconnect re-syncs who said what. chat_sessions no longer marks a session Busy and its clientID parameter is gone; the protocol keeps the Busy field for wire compatibility only. websocket.go detaches a connection's chat subscriptions when the read loop ends. - chat_claims.go is removed, not left vestigial: the only exclusive thing left is a turn, and the room's queue is that. App (android): - PipelinesRepository carries a stable per-device client label (Build.MODEL, with a fallback) on prompts and replies, and adds chatSubscribe; AppViewModel subscribes on opening a chat (best-effort, an older server's error frame does not stop history loading) and records the queued ack. - ChatStore folds a user frame from another client into the transcript once, attributed by the sender's label, and never receives its own prompt back, so the sender's own message is never duplicated. ChatThread.readOnly is gone: canSend no longer depends on another client, the composer says "Queued - it will send when the current turn finishes." instead of disabling input, and the status label is Running/Idle only. Scroll/follow behaviour is untouched. - Tests: ChatProtocolTest round-trips the new wire fields, ChatFormatTest asserts the stale Busy flag cannot produce a read-only label, MultiChatStateTest asserts a session another client watches stays writable. Reflected where it belongs: no packaged template changes (no bundled starter embeds the chat protocol). Checked the packaged authoring skill references: none of them describes the chat wire beyond operations.md, and internal/author/skill/references/operations.md is now stale - its "Brokered OpenCode chat" section still says chat_sessions marks "busy" when another client holds the session and that a second client's chat_prompt is rejected, and it does not mention chat_subscribe, the per-session prompt queue/chat_queued, the per-client label or the shared exactly-once approval (it also still describes the per-subscription permission poller, which the room's single poller replaced). The supported semantics are the ones in docs/cli.md, updated in this commit; the operations.md section needs a rewrite to match. No README or other shared document was edited here. Checks run on the committed tree: gofmt -l internal cmd examples (nothing), go build ./..., go vet ./internal/... ./cmd/..., go test ./internal/server ./internal/protocol ./internal/stage ./internal/pipeline. --- .../pipelines/data/PipelinesRepository.kt | 51 +- .../net/awan/pipelines/data/protocol/Chat.kt | 44 +- .../awan/pipelines/data/protocol/Message.kt | 8 + .../net/awan/pipelines/ui/AppViewModel.kt | 11 +- .../awan/pipelines/ui/chat/ChatComposer.kt | 6 +- .../pipelines/ui/chat/ChatConversationPane.kt | 6 +- .../net/awan/pipelines/ui/chat/ChatFormat.kt | 24 +- .../net/awan/pipelines/ui/chat/ChatStore.kt | 57 +- .../awan/pipelines/ui/chat/ChatTranscript.kt | 10 + .../data/protocol/ChatProtocolTest.kt | 39 ++ .../awan/pipelines/ui/chat/ChatFormatTest.kt | 9 +- .../pipelines/ui/chat/MultiChatStateTest.kt | 91 ++- docs/cli.md | 32 +- internal/protocol/chat.go | 62 +- internal/protocol/chat_test.go | 14 +- internal/protocol/message.go | 6 + internal/server/chat.go | 13 +- internal/server/chat_claims.go | 65 -- internal/server/chat_commands.go | 18 + internal/server/chat_hub.go | 88 ++- internal/server/chat_multiclient_test.go | 472 +++++++++++++ internal/server/chat_permissions.go | 77 +- internal/server/chat_room.go | 662 ++++++++++++++++++ internal/server/chat_sessions.go | 19 +- internal/server/chat_stream.go | 223 ++---- internal/server/chat_test.go | 140 +--- internal/server/websocket.go | 5 + 27 files changed, 1795 insertions(+), 457 deletions(-) delete mode 100644 internal/server/chat_claims.go create mode 100644 internal/server/chat_multiclient_test.go create mode 100644 internal/server/chat_room.go diff --git a/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt b/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt index 284f038e..a06126ef 100644 --- a/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt +++ b/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt @@ -1,5 +1,6 @@ package net.awan.pipelines.data +import android.os.Build import java.util.UUID import java.util.concurrent.ConcurrentHashMap import kotlinx.coroutines.flow.SharedFlow @@ -27,6 +28,17 @@ import net.awan.pipelines.data.transport.PipelinesClient import net.awan.pipelines.data.transport.ProtocolException import net.awan.pipelines.data.transport.ServerUrl +/** + * The default label this device reports: its model name, so other clients can + * attribute a message to "Pixel 9 Pro XL". A build without a usable model (or a + * local unit test where the framework stub has none) falls back to a generic + * label rather than sending a blank one. + */ +private fun defaultClientLabel(): String { + val model = runCatching { Build.MODEL }.getOrNull()?.trim().orEmpty() + return model.ifBlank { "Android device" } +} + /** Run history plus the server's aggregate usage statistics. */ data class RunHistory(val runs: List, val usage: UsageStats?) @@ -38,6 +50,13 @@ data class RunHistory(val runs: List, val usage: UsageStats?) class PipelinesRepository( private val client: PipelinesClient, private val settings: SettingsRepository, + /** + * The label this device sends with its prompts and approval answers, so every + * other client can attribute a user message to the device that sent it and see + * which device answered an approval. Defaults to the device model; injectable + * so a unit test does not depend on the build. + */ + val clientLabel: String = defaultClientLabel(), ) { val connectionState = client.state @@ -241,9 +260,9 @@ class PipelinesRepository( // directly and never holds its credentials. ---- /** - * Lists the sessions this server owns, with the `busy` flag the phone renders - * read-only. The server already returns operator sessions only, so the app - * never filters this list by ownership. + * Lists the sessions this server owns. The server already returns operator + * sessions only, so the app never filters this list by ownership; a session is + * never marked read-only. */ suspend fun chatSessions(): List = client.call(Message(type = Protocol.CHAT_SESSIONS)).chatSessions ?: emptyList() @@ -284,15 +303,29 @@ class PipelinesRepository( } /** - * Sends one prompt with its attached file URIs; the server echoes an ack and - * then pushes chat_event frames. The attachments travel only here, with the - * prompt the operator actually sent — never on their own. + * Attaches this connection to [sessionId]'s shared live stream, so it sees + * every frame any client's turn produces — the other devices' prompts and the + * turn's streaming output — and can answer a shared approval. Best-effort: an + * older server that does not know `chat_subscribe` simply answers an error + * frame, which the caller ignores while history still loads. */ - suspend fun chatPrompt(sessionId: String, text: String, files: List = emptyList()) { + suspend fun chatSubscribe(sessionId: String) { + if (sessionId.isBlank()) return + client.call(ChatProtocol.subscribeRequest(sessionId)) + } + + /** + * Sends one prompt with its attached file URIs; the server echoes an ack and + * then pushes chat_event frames. The prompt carries this device's label so the + * other clients can attribute it. The attachments travel only here, with the + * prompt the operator actually sent — never on their own. Returns true when the + * server queued the prompt behind an in-flight turn. + */ + suspend fun chatPrompt(sessionId: String, text: String, files: List = emptyList()): Boolean { if (sessionId.isBlank()) throw ProtocolException("Select a chat session first.") val trimmed = text.trim() if (trimmed.isEmpty()) throw ProtocolException("Enter a message before sending.") - client.call(ChatProtocol.promptRequest(sessionId, trimmed, files)) + return client.call(ChatProtocol.promptRequest(sessionId, trimmed, files, clientLabel)).chatQueued } suspend fun chatInterrupt(sessionId: String) { @@ -304,7 +337,7 @@ class PipelinesRepository( if (sessionId.isBlank() || requestId.isBlank()) { throw ProtocolException("A pending permission request is required.") } - client.call(ChatProtocol.replyRequest(sessionId, requestId, decision, message)) + client.call(ChatProtocol.replyRequest(sessionId, requestId, decision, message, clientLabel)) } private fun requireConfigured() { diff --git a/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt b/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt index c3f8b35d..d903e35e 100644 --- a/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt +++ b/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt @@ -30,8 +30,8 @@ data class ChatSession( @SerialName("created_at") val createdAt: Long = 0, @SerialName("updated_at") val updatedAt: Long = 0, // Another client holds the session, or the server itself owns it as an active - // run: the phone shows it read-only instead of letting two clients write the - // same conversation. + // run. Kept for wire compatibility; the server no longer sets it, and a + // session is never read-only for a client. val busy: Boolean = false, ) @@ -55,6 +55,10 @@ data class ChatPromptRequest( val model: String = "", val agent: String = "", val files: List = emptyList(), + // The sending device's human-readable label (a device name), so every other + // client can attribute the message; the server sanitises it and falls back to + // a generic label when it is blank. + val client: String = "", ) /** One stored turn: a user turn is a single text part, an assistant turn holds text/reasoning/tool parts. */ @@ -66,6 +70,9 @@ data class ChatMessage( val model: String = "", val agent: String = "", @SerialName("created_at") val createdAt: Long = 0, + // The sending device's label on a user turn the server echoed, so a resumed + // transcript still says who sent the message. Empty on an assistant turn. + val client: String = "", val parts: List = emptyList(), ) @@ -138,6 +145,9 @@ data class ChatEventFrame( val part: ChatPart? = null, val step: ChatStep? = null, val usage: ChatUsage? = null, + // The sending device's label on a `user` frame (another client's prompt), so + // the transcript can say who sent it. Empty on the agent's own frames. + val client: String = "", ) @Serializable @@ -174,6 +184,9 @@ data class ChatPermissionFrame( val message: String = "", val resolved: Boolean = false, val decision: String = "", + // The label of the client whose answer resolved the request, so every other + // client can show which device answered. + @SerialName("resolved_by") val resolvedBy: String = "", ) @Serializable @@ -189,6 +202,8 @@ data class ChatReplyRequest( @SerialName("request_id") val requestId: String = "", val decision: String = "", val message: String = "", + // The answering device's label, recorded with the resolution. + val client: String = "", ) /** Chat part/kind/state/reply constants, mirroring `internal/protocol/chat.go`. */ @@ -207,6 +222,13 @@ object ChatProtocol { const val EVENT_STEP = "step" const val EVENT_USAGE = "usage" + /** + * A prompt another client sent, echoed live to this client so it appears in + * the transcript attributed to the sending device. The sender never receives + * its own frame (it already has the message locally). + */ + const val EVENT_USER = "user" + const val STEP_STARTED = "started" const val STEP_ENDED = "ended" @@ -241,10 +263,21 @@ object ChatProtocol { * shape a text-only prompt has always sent). Built here (not inline in the * repository) so production and its unit test share the one wire shape. */ - fun promptRequest(sessionId: String, text: String, files: List = emptyList()): Message = + fun promptRequest(sessionId: String, text: String, files: List = emptyList(), client: String = ""): Message = Message( type = Protocol.CHAT_PROMPT, - chatPrompt = ChatPromptRequest(sessionId = sessionId, text = text, files = files), + chatPrompt = ChatPromptRequest(sessionId = sessionId, text = text, files = files, client = client), + ) + + /** + * The `chat_subscribe` frame that attaches this connection to [sessionId]'s + * shared live stream, so the client sees every frame any client's turn + * produces. Built here so production and its unit test share the one shape. + */ + fun subscribeRequest(sessionId: String): Message = + Message( + type = Protocol.CHAT_SUBSCRIBE, + chatSubscribe = ChatQuery(sessionId = sessionId), ) /** @@ -261,7 +294,7 @@ object ChatProtocol { * inline in the repository) so the approval card's actions and their unit * test share the one wire shape. */ - fun replyRequest(sessionId: String, requestId: String, decision: String, message: String = ""): Message = + fun replyRequest(sessionId: String, requestId: String, decision: String, message: String = "", client: String = ""): Message = Message( type = Protocol.CHAT_REPLY, chatReply = ChatReplyRequest( @@ -269,6 +302,7 @@ object ChatProtocol { requestId = requestId, decision = decision, message = message, + client = client, ), ) } diff --git a/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt b/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt index 4817181b..14ef3c06 100644 --- a/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt +++ b/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt @@ -68,6 +68,9 @@ object Protocol { const val CHAT_MESSAGES = "chat_messages" const val CHAT_INTERRUPT = "chat_interrupt" const val CHAT_REPLY = "chat_reply" + // Attaches this connection to one session's shared live stream, so every + // client watching a session receives every frame any client's turn produces. + const val CHAT_SUBSCRIBE = "chat_subscribe" // The operator's directory choices for a new chat (home first, then the // directories of previous operator sessions, most recently used first). const val CHAT_DIRECTORIES = "chat_directories" @@ -676,6 +679,11 @@ data class Message( @SerialName("chat_create") val chatCreate: ChatCreateRequest? = null, @SerialName("chat_query") val chatQuery: ChatQuery? = null, @SerialName("chat_prompt") val chatPrompt: ChatPromptRequest? = null, + // A chat_prompt response with this set was accepted into the session's queue + // because a turn is already in flight; the composer shows queued/steering + // instead of blocking input. + @SerialName("chat_queued") val chatQueued: Boolean = false, + @SerialName("chat_subscribe") val chatSubscribe: ChatQuery? = null, @SerialName("chat_messages") val chatMessages: List? = null, @SerialName("chat_event") val chatEvent: ChatEventFrame? = null, @SerialName("chat_permission") val chatPermission: ChatPermissionFrame? = null, diff --git a/android/app/src/main/java/net/awan/pipelines/ui/AppViewModel.kt b/android/app/src/main/java/net/awan/pipelines/ui/AppViewModel.kt index 80f01734..cece0a60 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/AppViewModel.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/AppViewModel.kt @@ -1025,6 +1025,10 @@ class AppViewModel( fun loadChatHistory(sessionId: String) { viewModelScope.launch { + // Watch the session's shared stream so frames from any client's turn + // arrive live. Best-effort: an older server answers an error frame, + // which must not stop the history from loading. + runCatching { repository.chatSubscribe(sessionId) } chatStore.historyLoading(sessionId) try { chatStore.history(sessionId, repository.chatMessages(sessionId, CHAT_HISTORY_LIMIT)) @@ -1054,7 +1058,11 @@ class AppViewModel( chatStore.running(sessionId, true) viewModelScope.launch { try { - repository.chatPrompt(sessionId, text, attachmentFiles(attachments)) + val queued = repository.chatPrompt(sessionId, text, attachmentFiles(attachments)) + // The server accepted the prompt (queued or sent); a queued prompt + // is one waiting behind an in-flight turn, and the composer says so + // instead of blocking input. + chatStore.setQueued(sessionId, queued) } catch (t: Throwable) { if (t is CancellationException) throw t val message = ErrorMessages.describe(t) @@ -1062,6 +1070,7 @@ class AppViewModel( chatStore.failed(sessionId, message) chatStore.restoreAttachments(sessionId, attachments, message) chatStore.running(sessionId, false) + chatStore.setQueued(sessionId, false) } } } diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatComposer.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatComposer.kt index f67967f1..4c6e21b6 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatComposer.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatComposer.kt @@ -51,9 +51,9 @@ internal fun ChatComposer( } Surface(color = MaterialTheme.colorScheme.surfaceContainer) { Column(Modifier.fillMaxWidth().padding(CHAT_GUTTER)) { - if (thread.readOnly) { + if (thread.queued) { Text( - text = "Another client holds this session; it is read-only here.", + text = "Queued — it will send when the current turn finishes.", style = MaterialTheme.typography.bodySmall, color = MaterialTheme.colorScheme.onSurfaceVariant, modifier = Modifier.padding(bottom = CHAT_ITEM_GAP), @@ -65,14 +65,12 @@ internal fun ChatComposer( Row(verticalAlignment = Alignment.Bottom, horizontalArrangement = Arrangement.spacedBy(CHAT_COMPOSER_GAP)) { IconButton( onClick = { picker.launch(arrayOf("*/*")) }, - enabled = !thread.readOnly, ) { Icon(Icons.Default.AttachFile, contentDescription = "Attach file") } OutlinedTextField( value = thread.draft, onValueChange = onDraft, - enabled = !thread.readOnly, placeholder = { Text("Message the agent…") }, minLines = 1, maxLines = 6, diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatConversationPane.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatConversationPane.kt index 7d51f576..c01ee5a7 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatConversationPane.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatConversationPane.kt @@ -213,11 +213,7 @@ internal fun ChatConversationPane( onRetry = { vm.loadChatHistory(thread.sessionId) }, ) thread.messages.isEmpty() && !thread.running && approval == null -> EmptyState( - message = if (thread.readOnly) { - "This chat is read-only while another client holds the session." - } else { - "This chat has no messages yet. Ask something below." - }, + message = "This chat has no messages yet. Ask something below.", ) else -> ChatTranscript( thread = thread, diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt index d50c87cc..37fb28c5 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt @@ -125,23 +125,17 @@ internal fun chatHeaderMeta(thread: ChatThread): String = listOfNotNull( private const val OPERATOR_TAG_LABEL = "Operator" /** - * The status a session row shows. A locally-running turn is reported as - * `Running`; otherwise the server's `busy` flag is `Busy · read-only` (another - * client holds it, so the composer is disabled), else `Idle`. - * - * This is the same precedence [ChatThread.readOnly] applies: a turn we started is - * `Running` and writable, never the read-only the server's own `busy` flag alone - * would imply. + * The status a session row shows: `Running` while this client has a turn in + * flight, else `Idle`. A session is never reported `Busy` or read-only because + * another client is watching it — the server fans the stream out and accepts a + * prompt from any client, so the session stays writable everywhere. */ internal fun sessionStatusLabel(session: ChatSession, runningLocally: Boolean): String = - sessionStatusLabel(session.busy, runningLocally) + sessionStatusLabel(runningLocally) -/** The status of a conversation from its own model flags (see [sessionStatusLabel]). */ -internal fun sessionStatusLabel(busy: Boolean, runningLocally: Boolean): String = when { - runningLocally -> "Running" - busy -> "Busy · read-only" - else -> "Idle" -} +/** The status of a conversation from its own running flag (see [sessionStatusLabel]). */ +internal fun sessionStatusLabel(runningLocally: Boolean): String = + if (runningLocally) "Running" else "Idle" /** * The activity a session row signals beyond its open/tag/directory state. An @@ -183,7 +177,7 @@ internal data class ConversationHeader( internal fun conversationHeader(thread: ChatThread): ConversationHeader = ConversationHeader( title = sessionTitle(ChatSession(id = thread.sessionId, title = thread.title)), kind = sessionTagLabel(thread.tag), - activity = sessionStatusLabel(thread.busy, thread.running), + activity = sessionStatusLabel(thread.running), directory = thread.directory, model = thread.model, ) diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt index a3d80f75..4657b49d 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt @@ -94,24 +94,26 @@ data class ChatThread( * settle in place optimistically and survives a chat switch. */ val permissionAnswer: String = "", + /** + * The last prompt this client sent was accepted into the session's queue + * behind an in-flight turn (the server acknowledged it as queued), so the + * composer can say so instead of blocking. Cleared as soon as the turn's + * frames arrive or the thread settles. + */ + val queued: Boolean = false, ) { /** - * Read-only while another client holds the session: the composer must never - * write to it. A turn we started ourselves keeps the session writable even - * though the server reports it busy (the server owns it as our active run), - * so the one rule here agrees with [sessionStatusLabel]'s `Running` case. + * At least one attachment is flagged; the prompt must not be sent with it. */ - val readOnly: Boolean get() = busy && !running - - /** At least one attachment is flagged; the prompt must not be sent with it. */ val hasAttachmentErrors: Boolean get() = attachments.any { it.error != null } /** - * Whether the composer's send action is allowed. A message with a flagged - * attachment is never sent: the operator must remove or re-attach it first, - * so the file is never silently dropped. + * Whether the composer's send action is allowed. A session is never read-only: + * another client may watch the same conversation without blocking this one. A + * message with a flagged attachment is never sent, so the file is never + * silently dropped. */ - val canSend: Boolean get() = !readOnly && draft.isNotBlank() && !hasAttachmentErrors + val canSend: Boolean get() = draft.isNotBlank() && !hasAttachmentErrors /** * Non-negative elapsed time of an in-flight turn at [nowMillis], or 0 once it @@ -593,6 +595,13 @@ class ChatStore( fun running(sessionId: String, running: Boolean) = update(sessionId) { setRunning(it, running) } + /** + * Records that the operator's last prompt was accepted into the session's + * queue (true) or sent immediately (false), so the composer can say "Queued" + * while it waits for the in-flight turn without blocking input. + */ + fun setQueued(sessionId: String, queued: Boolean) = update(sessionId) { it.copy(queued = queued) } + /** * The stream resumed (the socket reconnected): every frame that was feeding an * in-flight turn is gone, so no thread keeps claiming to run until a fresh @@ -707,7 +716,11 @@ class ChatStore( if (frame.sessionId.isBlank()) return ensureThread(frame.sessionId) markUnread(frame.sessionId) + // Any frame for the session means the turn has moved on, so a prompt we + // had queued is no longer waiting. + update(frame.sessionId) { if (it.queued) it.copy(queued = false) else it } when (frame.kind) { + ChatProtocol.EVENT_USER -> applyRemoteUser(frame) ChatProtocol.PART_TEXT, ChatProtocol.PART_REASONING -> applyDelta(frame) ChatProtocol.PART_TOOL -> applyTool(frame) ChatProtocol.EVENT_STEP -> { @@ -718,6 +731,28 @@ class ChatStore( } } + /** + * Folds a user turn another client sent into the transcript, in place, once. + * The server never echoes this client's own prompts, so the sender's own + * message is never duplicated; the [ChatMessage.client] label says which + * device sent it. + */ + private fun applyRemoteUser(frame: ChatEventFrame) { + val text = frame.part?.text.orEmpty() + if (frame.messageId.isEmpty() || text.isEmpty()) return + update(frame.sessionId) { thread -> + if (thread.messages.any { it.id == frame.messageId }) return@update thread + val message = ChatMessage( + id = frame.messageId, + sessionId = frame.sessionId, + role = ChatProtocol.ROLE_USER, + client = frame.client, + parts = listOf(ChatPart(type = ChatProtocol.PART_TEXT, text = text)), + ) + thread.copy(messages = thread.messages + message) + } + } + /** * Creates a placeholder thread for a session that is not open, so a frame for * a background chat is kept instead of dropped. A no-op when it already exists. diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatTranscript.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatTranscript.kt index ddb3f115..3d9e9a77 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatTranscript.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatTranscript.kt @@ -352,6 +352,16 @@ private fun MessageItem( SelectionContainer { Column(Modifier.padding(CHAT_GUTTER)) { if (isUser) { + // A user turn another device sent is attributed to it, so + // the transcript says who sent the message. Our own + // messages carry no label. + if (message.client.isNotBlank()) { + Text( + text = message.client, + style = MaterialTheme.typography.labelSmall, + color = MaterialTheme.colorScheme.onSurfaceVariant, + ) + } UserParts(message.parts) } else { AssistantParts( diff --git a/android/app/src/test/java/net/awan/pipelines/data/protocol/ChatProtocolTest.kt b/android/app/src/test/java/net/awan/pipelines/data/protocol/ChatProtocolTest.kt index ef8d96f4..27910576 100644 --- a/android/app/src/test/java/net/awan/pipelines/data/protocol/ChatProtocolTest.kt +++ b/android/app/src/test/java/net/awan/pipelines/data/protocol/ChatProtocolTest.kt @@ -45,6 +45,45 @@ class ChatProtocolTest { assertTrue(!sessions[1].busy) } + @Test + fun chatMultiClientFieldsRoundTrip() { + // The client label the prompt carries, the queued acknowledgement, the + // subscribe request and the shared-answer fields of a permission frame. + val prompt = PipelinesJson.decodeFromString( + Message.serializer(), + """{"type":"chat_prompt","chat_prompt":{"session_id":"ses_1","text":"hi","client":"Pixel 9 Pro XL"}}""", + ) + assertEquals("Pixel 9 Pro XL", prompt.chatPrompt!!.client) + + val ack = PipelinesJson.decodeFromString( + Message.serializer(), + """{"type":"chat_prompt","id":"a1","chat_queued":true}""", + ) + assertTrue(ack.chatQueued) + + val subscribe = PipelinesJson.decodeFromString( + Message.serializer(), + """{"type":"chat_subscribe","chat_subscribe":{"session_id":"ses_1"}}""", + ) + assertEquals(Protocol.CHAT_SUBSCRIBE, subscribe.type) + assertEquals("ses_1", subscribe.chatSubscribe!!.sessionId) + + val userFrame = PipelinesJson.decodeFromString( + Message.serializer(), + """{"type":"chat_event","chat_event":{"session_id":"ses_1","message_id":"usr_1","kind":"user","client":"Pixel 10 Pro Fold","part":{"type":"text","text":"from the fold"}}}""", + ) + assertEquals(ChatProtocol.EVENT_USER, userFrame.chatEvent!!.kind) + assertEquals("Pixel 10 Pro Fold", userFrame.chatEvent!!.client) + + val resolved = PipelinesJson.decodeFromString( + Message.serializer(), + """{"type":"chat_permission","chat_permission":{"session_id":"ses_1","request_id":"req_1","resolved":true,"decision":"once","resolved_by":"Pixel 9"}}""", + ) + assertTrue(resolved.chatPermission!!.resolved) + assertEquals("once", resolved.chatPermission!!.decision) + assertEquals("Pixel 9", resolved.chatPermission!!.resolvedBy) + } + @Test fun chatMessagesParseTextReasoningAndToolParts() { val json = """ diff --git a/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatFormatTest.kt b/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatFormatTest.kt index 7991e473..74b7bd13 100644 --- a/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatFormatTest.kt +++ b/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatFormatTest.kt @@ -65,12 +65,11 @@ class ChatFormatTest { } @Test - fun sessionStatusReportsRunningBusyAndIdle() { + fun sessionStatusIsRunningOrIdleNeverReadOnly() { assertEquals("Running", sessionStatusLabel(ChatSession(id = "s"), runningLocally = true)) - assertEquals( - "Busy · read-only", - sessionStatusLabel(ChatSession(id = "s", busy = true), runningLocally = false), - ) + // The server no longer marks a session Busy for another client, and a + // session is never read-only: the stale flag cannot produce that label. + assertEquals("Idle", sessionStatusLabel(ChatSession(id = "s", busy = true), runningLocally = false)) assertEquals("Idle", sessionStatusLabel(ChatSession(id = "s"), runningLocally = false)) } diff --git a/android/app/src/test/java/net/awan/pipelines/ui/chat/MultiChatStateTest.kt b/android/app/src/test/java/net/awan/pipelines/ui/chat/MultiChatStateTest.kt index eaf2bfa1..0c94115f 100644 --- a/android/app/src/test/java/net/awan/pipelines/ui/chat/MultiChatStateTest.kt +++ b/android/app/src/test/java/net/awan/pipelines/ui/chat/MultiChatStateTest.kt @@ -113,19 +113,15 @@ class MultiChatStateTest { } @Test - fun busySessionIsReadOnlyAndCannotSend() { + fun busySessionStaysWritable() { val store = ChatStore() + // Another client watching the session never makes it read-only: the + // server fans the stream out and accepts a prompt from any client. store.open(session("a", busy = true)) store.draft("a", "unsent") val thread = store.value.thread("a")!! - assertTrue(thread.readOnly) - assertFalse(thread.canSend) - - // The server can clear busy later; the chat then becomes writable again. - store.sessionsLoaded(listOf(session("a", busy = false))) - store.draft("a", "unsent") - assertFalse(store.value.thread("a")!!.readOnly) - assertTrue(store.value.thread("a")!!.canSend) + assertTrue(thread.canSend) + assertTrue(thread.busy) } @Test @@ -192,10 +188,9 @@ class MultiChatStateTest { val store = ChatStore() store.open(session("a", busy = true)) store.running("a", true) - // Our own turn keeps the session writable even though the server reports it busy. + // A turn in flight (ours or another client's) keeps the session writable. store.draft("a", "next prompt") val thread = store.value.thread("a")!! - assertFalse(thread.readOnly) assertTrue(thread.canSend) } @@ -229,4 +224,78 @@ class MultiChatStateTest { assertFalse(store.value.open.any { it.sessionId == "a" }) assertTrue(store.value.open.any { it.sessionId == "b" }) } + + @Test + fun remoteUserFrameIsFoldedOnceAndAttributed() { + val store = ChatStore() + store.open(session("a")) + // The operator's own message, appended locally when sent. + store.appendLocalUserMessage("a", "mine") + // Another client's prompt arrives live, attributed to that device. + val frame = ChatEventFrame( + sessionId = "a", + messageId = "usr_7", + kind = ChatProtocol.EVENT_USER, + client = "Pixel 10 Pro Fold", + part = ChatPart(type = ChatProtocol.PART_TEXT, text = "from the fold"), + ) + store.event(frame) + val messages = store.value.thread("a")!!.messages + assertEquals(2, messages.size) + assertEquals("mine", messages[0].parts.single().text) + assertEquals(ChatProtocol.ROLE_USER, messages[1].role) + assertEquals("Pixel 10 Pro Fold", messages[1].client) + assertEquals("from the fold", messages[1].parts.single().text) + + // A replayed frame (e.g. after a reconnect) is folded once, not twice. + store.event(frame) + assertEquals(2, store.value.thread("a")!!.messages.size) + } + + @Test + fun remoteAnswerClearsTheApprovalCard() { + val store = ChatStore() + store.open(session("a")) + store.permission(ChatPermissionFrame(sessionId = "a", requestId = "req_1", action = "bash")) + val open = approvalCard(store.value.thread("a")!!.permission, store.value.thread("a")!!.permissionAnswer)!! + assertTrue("the card is answerable while the request is open", open.actionable) + + // Another client answered: the server pushes the resolved frame, which + // clears this client's card and shows the outcome without ever disabling + // it while the first answer was in flight. + store.permission( + ChatPermissionFrame( + sessionId = "a", + requestId = "req_1", + action = "bash", + resolved = true, + decision = ChatProtocol.DECISION_ONCE, + resolvedBy = "Pixel 9 Pro XL", + ), + ) + val thread = store.value.thread("a")!! + val cleared = approvalCard(thread.permission, thread.permissionAnswer)!! + assertFalse("a resolved request offers no controls", cleared.actionable) + assertEquals(ApprovalState.RESOLVED, cleared.state) + assertEquals(ChatProtocol.DECISION_ONCE, cleared.decision) + } + + @Test + fun queuedPromptIsShownUntilTheTurnStreams() { + val store = ChatStore() + store.open(session("a")) + store.setQueued("a", true) + assertTrue(store.value.thread("a")!!.queued) + // The queued turn's first frame means it is running, so the marker clears. + store.event( + ChatEventFrame( + sessionId = "a", + messageId = "m1", + kind = ChatProtocol.PART_TEXT, + delta = "hi", + part = ChatPart(type = ChatProtocol.PART_TEXT, id = "m1#0"), + ), + ) + assertFalse(store.value.thread("a")!!.queued) + } } diff --git a/docs/cli.md b/docs/cli.md index ada999b2..996962c5 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -304,12 +304,31 @@ The brokered OpenCode chat exposes the operator's own sessions, separate from th sessions pipeline runs create. The protocol types are: - `chat_sessions` lists the operator's own sessions only, ordered - most-recently-used first. Each carries its `directory`, its `tag`, its `busy` - state (another connection currently holds it) and its recency. A session with + most-recently-used first. Each carries its `directory`, its `tag` and its + recency. A session with no recorded tag is never listed, and no pipeline stage session is ever listed: stage sessions are still recorded in `run_steps`/`run_session_owners` for the run that owns them. The list is fail-closed: with no registry and no - store it returns an empty list, never the endpoint's whole session list. + store it returns an empty list, never the endpoint's whole session list. A + session is never marked `busy`: any number of clients may watch and write one. +- `chat_subscribe` attaches a connection to one session's shared live stream (body + `session_id`) and replays the session's still-pending approval requests, so every + client that watches a session sees every frame any client's turn produces — the + other devices' prompts and the turn's streaming output — and can answer a shared + approval. Attaching is idempotent per connection; the subscription is released + when the connection ends. +- `chat_prompt` may come from any client. A prompt whose session already has a turn + in flight is accepted into that session's bounded queue (currently 8) and + acknowledged with `chat_queued: true`; the agent never receives two interleaved + turns. The prompt is echoed to the other watching clients as a `chat_event` of + kind `user`, carried with the sender's `client` label (a device name), while the + sender's own transcript keeps its local copy. +- `chat_reply` is exactly-once: the first answer to a pending request wins, is + recorded with the answering client's label and is pushed back to every watching + client as the same `chat_permission` frame with `resolved: true`, `decision` and + `resolved_by`, so each card clears and shows the outcome. A later answer is + refused as already answered (naming the client that won), never silently ignored + and never delivered to the agent twice. - `chat_create` takes a `title` (default "New chat") and a `directory` (default `~`, the operator's home; `~`, an omitted or empty value and a `~/...` value all resolve to the home directory). A relative or missing directory is @@ -357,8 +376,11 @@ password file as a reference). The stored tag is exactly `operator`; the display label `Operator` is derived from it, so there is no second tag vocabulary. Chat uses the server's one OpenCode -transport, and every existing chat guarantee (retained-state bounds, the -permission/approval flow, interruption, one broker call per list) is unchanged. +transport. A session's stream is fanned out to every client watching it, prompts +are serialised per session (queued behind the in-flight turn rather than +rejected), and approvals are shared and exactly-once; the retained-state bounds, +the resync-on-reconnect path, the exclusion of a run's own session and +per-connection write serialisation are unchanged. The operator-session registry, filter, directory defaulting and the list bound are covered by the `pipeline`, `opencode` and `server` unit tests. The live end-to-end diff --git a/internal/protocol/chat.go b/internal/protocol/chat.go index bd39f8f0..c364eb37 100644 --- a/internal/protocol/chat.go +++ b/internal/protocol/chat.go @@ -26,6 +26,13 @@ const ( ChatMessages = "chat_messages" ChatInterrupt = "chat_interrupt" ChatReply = "chat_reply" + // ChatSubscribe attaches a connection to one session's shared live stream so + // it receives every frame any client's turn produces (its own and the other + // devices'), not only the frames of a turn it prompted itself. Any number of + // clients may watch one session; the session is never read-only. The request + // body is a ChatQuery naming the session and the response echoes the request + // id once the subscription is attached. + ChatSubscribe = "chat_subscribe" // ChatDirectories is the request/response type for the operator's directory // choices: the home directory plus the directories of previous operator // sessions, most recently used first, deduplicated and bounded. It is a @@ -49,13 +56,16 @@ const ( ) // ChatEvent.Kind values pushed on the chat_event stream. Step and usage carry -// no ChatPart; they report turn progress and the turn's totals. +// no ChatPart; they report turn progress and the turn's totals. User carries the +// text of a prompt another client sent, so a transcript can show it live; it is +// never sent back to the client that sent the prompt. const ( ChatEventText = ChatPartText ChatEventReasoning = ChatPartReasoning ChatEventTool = ChatPartTool ChatEventStep = "step" ChatEventUsage = "usage" + ChatEventUser = "user" ) // ChatStep.Status values, mirroring the OpenCode session.step events. @@ -111,10 +121,11 @@ type ChatSession struct { Tag string `json:"tag,omitempty"` CreatedAt int64 `json:"created_at,omitempty"` UpdatedAt int64 `json:"updated_at,omitempty"` - // Busy marks a session another client currently holds (or one the server - // itself owns as an active run), so the phone can show it read-only instead - // of letting two clients silently write the same conversation. It is - // additive and optional: older peers ignore it. + // Busy is retained for wire compatibility only: it is never set by this + // server. A session is never read-only, any number of clients may watch and + // write it, and only a turn is serialised (a waiting prompt is acknowledged + // as queued on its own client instead of marking the session Busy). Older + // peers still parse the field; newer ones ignore it. Busy bool `json:"busy,omitempty"` } @@ -144,26 +155,34 @@ type ChatQuery struct { // ChatPromptRequest is the chat_prompt request body: the text to send, with an // optional model/agent override and attached file URIs. The matching response is -// the inbox envelope, which the server folds into a ChatMessage. +// the inbox envelope, which the server folds into a ChatMessage. Client is the +// sending device's human-readable label so every other client can attribute the +// message; the server sanitises it and falls back to a generic label when it is +// blank. type ChatPromptRequest struct { SessionID string `json:"session_id"` Text string `json:"text"` Model string `json:"model,omitempty"` Agent string `json:"agent,omitempty"` Files []string `json:"files,omitempty"` + Client string `json:"client,omitempty"` } // ChatMessage is one stored turn returned by chat_messages. A user turn is a // single text part; an assistant turn holds the text, reasoning and tool parts // the phone renders. Parts corresponds to the OpenCode content array. type ChatMessage struct { - ID string `json:"id"` - SessionID string `json:"session_id"` - Role string `json:"role"` - Model string `json:"model,omitempty"` - Agent string `json:"agent,omitempty"` - CreatedAt int64 `json:"created_at,omitempty"` - Parts []ChatPart `json:"parts"` + ID string `json:"id"` + SessionID string `json:"session_id"` + Role string `json:"role"` + Model string `json:"model,omitempty"` + Agent string `json:"agent,omitempty"` + CreatedAt int64 `json:"created_at,omitempty"` + // Client is the sending device's label on a user turn the server echoed, so a + // resumed transcript still says who sent the message. It is empty on an + // assistant turn. + Client string `json:"client,omitempty"` + Parts []ChatPart `json:"parts"` } // ChatPart is one element of a ChatMessage. Type selects the meaning: text and @@ -225,6 +244,9 @@ type ChatEventFrame struct { Part *ChatPart `json:"part,omitempty"` Step *ChatStep `json:"step,omitempty"` Usage *ChatUsage `json:"usage,omitempty"` + // Client is the sending device's label on a user frame (ChatEventUser), so a + // transcript can say who sent the message. It is empty on assistant frames. + Client string `json:"client,omitempty"` } // ChatStep is a progress marker for the current step of a turn. @@ -258,6 +280,15 @@ type ChatPermissionFrame struct { Metadata map[string]any `json:"metadata,omitempty"` Source *ChatPermissionSource `json:"source,omitempty"` Message string `json:"message,omitempty"` + // Resolved, Decision and ResolvedBy report the shared, exactly-once outcome + // of a request any client may answer: once the first answer is recorded the + // server pushes the same frame back to every watching client with Resolved + // set, the Decision it recorded and the label of the client that gave it, so + // their cards clear and show the outcome instead of offering a stale choice. + // They are empty on a still-pending request. + Resolved bool `json:"resolved,omitempty"` + Decision string `json:"decision,omitempty"` + ResolvedBy string `json:"resolved_by,omitempty"` } // ChatPermissionSource identifies what raised a permission request, matching the @@ -271,10 +302,13 @@ type ChatPermissionSource struct { // ChatReplyRequest is the chat_reply request body: the phone's decision on a // pending permission request, mirroring -// POST /api/session/{id}/permission/{requestID}/reply. +// POST /api/session/{id}/permission/{requestID}/reply. Client is the answering +// device's label, recorded with the resolution so every other client can see +// which device answered. type ChatReplyRequest struct { SessionID string `json:"session_id"` RequestID string `json:"request_id"` Decision string `json:"decision"` Message string `json:"message,omitempty"` + Client string `json:"client,omitempty"` } diff --git a/internal/protocol/chat_test.go b/internal/protocol/chat_test.go index 5c02e6cc..5415dded 100644 --- a/internal/protocol/chat_test.go +++ b/internal/protocol/chat_test.go @@ -25,7 +25,13 @@ func chatSamples() []struct { {"create", ChatCreateRequest{Title: "demo", Directory: "/work"}}, {"adopt", ChatAdoptRequest{SessionID: "ses_1"}}, {"query", ChatQuery{SessionID: "ses_1", Limit: 50}}, - {"prompt", ChatPromptRequest{SessionID: "ses_1", Text: "hello", Model: "m", Agent: "build", Files: []string{"file:///tmp/a.png"}}}, + {"prompt", ChatPromptRequest{SessionID: "ses_1", Text: "hello", Model: "m", Agent: "build", Files: []string{"file:///tmp/a.png"}, Client: "Pixel 9 Pro XL"}}, + {"prompt_queued_ack", Message{Type: ChatPrompt, ID: "a1", ChatQueued: true}}, + {"subscribe", ChatQuery{SessionID: "ses_1"}}, + {"event_user", ChatEventFrame{ + SessionID: "ses_1", MessageID: "usr_1", Kind: ChatEventUser, Client: "Pixel 10 Pro Fold", + Part: &ChatPart{Type: ChatPartText, ID: "usr", Text: "from the fold"}, + }}, {"message", ChatMessage{ ID: "msg_1", SessionID: "ses_1", Role: ChatRoleAssistant, Model: "m", Agent: "build", CreatedAt: 1792112366711, Parts: []ChatPart{ @@ -64,7 +70,11 @@ func chatSamples() []struct { Source: &ChatPermissionSource{Type: "tool", MessageID: "msg_1", ID: "call_1"}, Message: "wants to run a command", }}, - {"reply", ChatReplyRequest{SessionID: "ses_1", RequestID: "req_1", Decision: ChatDecisionOnce, Message: "ok"}}, + {"permission_resolved", ChatPermissionFrame{ + SessionID: "ses_1", RequestID: "per_1", Action: "bash", + Resolved: true, Decision: ChatDecisionOnce, ResolvedBy: "Pixel 9 Pro XL", + }}, + {"reply", ChatReplyRequest{SessionID: "ses_1", RequestID: "req_1", Decision: ChatDecisionOnce, Message: "ok", Client: "Pixel 9 Pro XL"}}, } } diff --git a/internal/protocol/message.go b/internal/protocol/message.go index 0ca03db2..2616acf5 100644 --- a/internal/protocol/message.go +++ b/internal/protocol/message.go @@ -166,6 +166,12 @@ type Message struct { ChatEvent *ChatEventFrame `json:"chat_event,omitempty"` ChatPermission *ChatPermissionFrame `json:"chat_permission,omitempty"` ChatReply *ChatReplyRequest `json:"chat_reply,omitempty"` + // ChatSubscribe attaches this connection to one session's shared stream; the + // body names the session like ChatQuery. A chat_prompt response sets + // ChatQueued when the prompt had to wait for an in-flight turn and was + // accepted into the session's queue instead of being sent immediately. + ChatSubscribe *ChatQuery `json:"chat_subscribe,omitempty"` + ChatQueued bool `json:"chat_queued,omitempty"` // ChatDirectories carries the operator's directory choices on a // chat_directories response (home first, then recent operator-session // directories, deduplicated and bounded). Additive/omitempty so older peers diff --git a/internal/server/chat.go b/internal/server/chat.go index 6112c876..ccc8d6cb 100644 --- a/internal/server/chat.go +++ b/internal/server/chat.go @@ -46,10 +46,10 @@ type operatorRegistry interface { OperatorDirectories(ctx context.Context, limit int) ([]string, error) } -// chatClientToken returns an unguessable per-connection identity. It attributes -// a session claim so two clients on the same server cannot silently write the -// same conversation; a fresh token per connection means a reconnected client is -// a new writer and must re-claim. +// chatClientToken returns an unguessable per-connection identity. Its only role +// is to key a connection's chat-room subscriptions and to exclude the sender from +// its own fan-out; it carries no ownership. A fresh token per connection means a +// reconnected client is a new identity and simply reattaches. func chatClientToken() string { var b [8]byte if _, err := rand.Read(b[:]); err != nil { @@ -68,6 +68,9 @@ func handleChat(ctx context.Context, request protocol.Message, broker chatBroker case protocol.ChatPrompt: handleChatPrompt(ctx, request, broker, hub, registry, clientID, write) return true + case protocol.ChatSubscribe: + handleChatSubscribe(request, broker, hub, clientID, write) + return true case protocol.ChatMessages: handleChatMessages(ctx, request, broker, hub, write) return true @@ -78,7 +81,7 @@ func handleChat(ctx context.Context, request protocol.Message, broker chatBroker handleChatSimple(ctx, request, broker, hub, write) return true case protocol.ChatSessions: - handleChatSessions(ctx, request, broker, hub, registry, clientID, write) + handleChatSessions(ctx, request, broker, hub, registry, write) return true case protocol.ChatCreate: handleChatCreate(ctx, request, broker, registry, write) diff --git a/internal/server/chat_claims.go b/internal/server/chat_claims.go deleted file mode 100644 index ccc1792e..00000000 --- a/internal/server/chat_claims.go +++ /dev/null @@ -1,65 +0,0 @@ -package server - -// claim reserves sessionID for clientID. It reports true when the session is -// free or already held by the same client (so a client may re-prompt its own -// session) and false when another client holds it. The claim map is bounded by -// chatMaxTurns with oldest-eviction so a stuck client cannot grow it without -// limit. -func (h *chatHub) claim(sessionID, clientID string) bool { - if sessionID == "" || clientID == "" { - return false - } - h.mu.Lock() - defer h.mu.Unlock() - if h.claims == nil { - h.claims = map[string]string{} - } - if holder, ok := h.claims[sessionID]; ok { - return holder == clientID - } - h.evictClaimsLocked() - h.claims[sessionID] = clientID - h.claimOrder = append(h.claimOrder, sessionID) - return true -} - -// release drops the same client's claim on sessionID; a claim held by a -// different client is left untouched so a stale release cannot free a live one. -func (h *chatHub) release(sessionID, clientID string) { - h.mu.Lock() - defer h.mu.Unlock() - if holder, ok := h.claims[sessionID]; !ok || holder != clientID { - return - } - delete(h.claims, sessionID) - for i, id := range h.claimOrder { - if id == sessionID { - h.claimOrder = append(h.claimOrder[:i], h.claimOrder[i+1:]...) - break - } - } -} - -// busyForOther reports whether another client currently holds sessionID. -func (h *chatHub) busyForOther(sessionID, clientID string) bool { - h.mu.Lock() - defer h.mu.Unlock() - holder, ok := h.claims[sessionID] - return ok && holder != clientID -} - -// evictClaimsLocked drops the oldest claim when the cap is reached, keeping the -// claim map bounded like the retained turns. Callers must hold h.mu. -func (h *chatHub) evictClaimsLocked() { - if len(h.claims) < chatMaxTurns { - return - } - for len(h.claimOrder) > 0 { - oldest := h.claimOrder[0] - h.claimOrder = h.claimOrder[1:] - if _, ok := h.claims[oldest]; ok { - delete(h.claims, oldest) - return - } - } -} diff --git a/internal/server/chat_commands.go b/internal/server/chat_commands.go index 58600e58..2d160373 100644 --- a/internal/server/chat_commands.go +++ b/internal/server/chat_commands.go @@ -68,9 +68,27 @@ func handleChatSimple(ctx context.Context, request protocol.Message, broker chat _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "a valid permission decision is required"}) return } + // A pending approval is shared and exactly-once: the first answer wins and is + // recorded with the client that gave it, and a later answer is refused as + // already answered rather than reaching the agent twice. + label := sanitizeChatClientLabel(reply.Client) + if hub != nil { + if prior, ok := hub.reservePermission(reply.SessionID, reply.RequestID, label); !ok { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: permissionRefusal(prior, reply.RequestID)}) + return + } + } if err := broker.Reply(ctx, *reply); err != nil { + if hub != nil { + hub.releasePermission(reply.SessionID, reply.RequestID) + } _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) return } _ = write(protocol.Message{Type: protocol.ChatReply, ID: request.ID}) + if hub != nil { + // Push the resolution to every client watching the session so each card + // clears and shows the outcome and which device answered. + hub.confirmPermission(reply.SessionID, reply.RequestID, label, reply.Decision) + } } diff --git a/internal/server/chat_hub.go b/internal/server/chat_hub.go index f265b56f..b04105b7 100644 --- a/internal/server/chat_hub.go +++ b/internal/server/chat_hub.go @@ -1,7 +1,9 @@ package server import ( + "context" "log" + "strconv" "sync" "time" @@ -22,15 +24,18 @@ const chatMaxTurns = 128 // chatHub retains the accumulated turn state per session, independently of any // single connection, so a reconnecting client can re-sync what it missed. State // is keyed by session and then by message id (a session holds many turns), and -// is capped at chatRetainedLimit. +// is capped at chatRetainedLimit. It also owns the per-session live rooms: the +// one broker stream, the prompt queue and the fan-out to every attached client. type chatHub struct { - mu sync.Mutex - turns map[string]*chatTurn - now func() time.Time - // claims maps a session to the client currently writing it so a second - // client is rejected; claimOrder bounds the map like chatMaxTurns. - claims map[string]string - claimOrder []string + mu sync.Mutex + turns map[string]*chatTurn + rooms map[string]*chatRoom + baseCtx context.Context + registry operatorRegistry + now func() time.Time + // userSeq is a monotonic source of ids for the user turns the server echoes + // to the other clients, so each retained user message has a stable id. + userSeq int } // chatPart is the retained form of one part. Text and reasoning deltas append to @@ -40,12 +45,16 @@ type chatPart struct { text []byte } -// chatMessage is one retained assistant turn. Its parts keep the exact ids the -// supporting chat_event frames carried, so a resume preserves attribution. +// chatMessage is one retained turn. Its parts keep the exact ids the supporting +// chat_event frames carried, so a resume preserves attribution. Role and client +// are carried for a user turn the server echoed (a prompt another client sent), +// so a resumed transcript still says who sent it. type chatMessage struct { - id string - order []string - parts map[string]*chatPart + id string + role string + client string + order []string + parts map[string]*chatPart } type chatTurn struct { @@ -62,10 +71,33 @@ type chatTurn struct { // bounds it to chatPermissionRetainedLimit. permissions map[string]struct{} permissionOrder []string + // resolutions records the shared exactly-once answers to permission requests, + // keyed by request id, so a second answer is refused and the recorded outcome + // survives the clients that gave it; resolutionOrder bounds it to + // chatPermissionRetainedLimit like the dedup set above. + resolutions map[string]*chatResolution + resolutionOrder []string +} + +// chatResolution is the shared answer to one permission request. answered is +// false while the first answer is still being delivered to the agent, so a +// concurrent second answer is refused without ever reaching the agent twice. +type chatResolution struct { + client string + decision string + answered bool } func newChatHub() *chatHub { - return &chatHub{turns: map[string]*chatTurn{}, now: time.Now} + return &chatHub{turns: map[string]*chatTurn{}, rooms: map[string]*chatRoom{}, baseCtx: context.Background(), now: time.Now} +} + +// nextUserMessageID mints a stable id for one echoed user turn. +func (h *chatHub) nextUserMessageID() string { + h.mu.Lock() + defer h.mu.Unlock() + h.userSeq++ + return "usr_" + strconv.Itoa(h.userSeq) } func (h *chatHub) clock() time.Time { @@ -100,11 +132,33 @@ func (h *chatHub) apply(frame protocol.ChatEventFrame) { } message := turn.messages[frame.MessageID] if message == nil { - message = &chatMessage{id: frame.MessageID, parts: map[string]*chatPart{}} + role := protocol.ChatRoleAssistant + client := "" + if frame.Kind == protocol.ChatEventUser { + role = protocol.ChatRoleUser + client = frame.Client + } + message = &chatMessage{id: frame.MessageID, role: role, client: client, parts: map[string]*chatPart{}} turn.order = append(turn.order, frame.MessageID) turn.messages[frame.MessageID] = message + } else if message.client == "" && frame.Kind == protocol.ChatEventUser { + message.client = frame.Client } switch frame.Kind { + case protocol.ChatEventUser: + if frame.Part == nil || frame.Part.ID == "" || frame.Part.Text == "" || turn.overflow { + return + } + if !turn.retain(len(frame.Part.Text)) { + return + } + part, ok := message.parts[frame.Part.ID] + if !ok { + part = &chatPart{part: protocol.ChatPart{Type: protocol.ChatPartText, ID: frame.Part.ID}} + message.order = append(message.order, frame.Part.ID) + message.parts[frame.Part.ID] = part + } + part.text = append(part.text, frame.Part.Text...) case protocol.ChatEventText, protocol.ChatEventReasoning: id := "" if frame.Part != nil { @@ -255,6 +309,10 @@ func (h *chatHub) snapshot(sessionID string) []protocol.ChatMessage { continue } out := protocol.ChatMessage{ID: id, SessionID: sessionID, Role: protocol.ChatRoleAssistant} + if message.role != "" { + out.Role = message.role + } + out.Client = message.client for _, partID := range message.order { if part, ok := message.parts[partID]; ok { piece := part.part diff --git a/internal/server/chat_multiclient_test.go b/internal/server/chat_multiclient_test.go new file mode 100644 index 00000000..43d373a5 --- /dev/null +++ b/internal/server/chat_multiclient_test.go @@ -0,0 +1,472 @@ +package server + +import ( + "context" + "errors" + "net/http/httptest" + "strings" + "sync" + "testing" + "time" + + "github.com/coder/websocket" + "github.com/coder/websocket/wsjson" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// channelChat is a broker whose stream is driven frame-by-frame from a channel, +// so a test can hold a turn in flight and prove prompt serialisation, fan-out and +// exactly-once approval behaviour without a real OpenCode service. +type channelChat struct { + mu sync.Mutex + prompts []string + perm []protocol.ChatPermissionFrame + replies []protocol.ChatReplyRequest + frames chan protocol.ChatEventFrame + ready chan struct{} + once sync.Once + // promptErrAt, when nonzero, is the 1-based index of the Prompt call that + // fails, so a test can prove a broker failure is reported to the client that + // sent the prompt. + promptErrAt int +} + +func newChannelChat() *channelChat { + return &channelChat{frames: make(chan protocol.ChatEventFrame, 32), ready: make(chan struct{})} +} + +func (c *channelChat) Prompt(_ context.Context, _, text string) error { + c.mu.Lock() + c.prompts = append(c.prompts, text) + fail := c.promptErrAt != 0 && len(c.prompts) == c.promptErrAt + c.mu.Unlock() + if fail { + return errors.New("broker rejected the prompt") + } + return nil +} + +func (c *channelChat) Stream(ctx context.Context, _ string, ready func(), emit func(protocol.ChatEventFrame) error) error { + c.once.Do(func() { + close(c.ready) + if ready != nil { + ready() + } + }) + for { + select { + case <-ctx.Done(): + return ctx.Err() + case frame := <-c.frames: + if err := emit(frame); err != nil { + return err + } + } + } +} + +func (c *channelChat) Interrupt(context.Context, string) error { return nil } + +func (c *channelChat) Messages(context.Context, string, int) ([]protocol.ChatMessage, error) { + return nil, nil +} + +func (c *channelChat) Sessions(context.Context) ([]protocol.ChatSession, error) { return nil, nil } + +func (c *channelChat) Create(_ context.Context, title, directory string) (protocol.ChatSession, error) { + return protocol.ChatSession{ID: "ses_created", Title: title, Directory: directory}, nil +} + +func (c *channelChat) Session(context.Context, string) (protocol.ChatSession, bool, error) { + return protocol.ChatSession{}, false, nil +} + +func (c *channelChat) Permissions(context.Context, string) ([]protocol.ChatPermissionFrame, error) { + c.mu.Lock() + defer c.mu.Unlock() + return append([]protocol.ChatPermissionFrame(nil), c.perm...), nil +} + +func (c *channelChat) Reply(_ context.Context, request protocol.ChatReplyRequest) error { + c.mu.Lock() + c.replies = append(c.replies, request) + c.mu.Unlock() + return nil +} + +func (c *channelChat) push(frame protocol.ChatEventFrame) { + c.frames <- frame +} + +func (c *channelChat) promptCount() int { + c.mu.Lock() + defer c.mu.Unlock() + return len(c.prompts) +} + +func (c *channelChat) promptTexts() []string { + c.mu.Lock() + defer c.mu.Unlock() + return append([]string(nil), c.prompts...) +} + +func (c *channelChat) replyCount() int { + c.mu.Lock() + defer c.mu.Unlock() + return len(c.replies) +} + +// dialChatServer starts one server and dials n connections, returning the server +// so a test can reconnect a dropped client to the same hub. +func dialChatServer(t *testing.T, options Options, n int) (context.Context, context.CancelFunc, *httptest.Server, []*websocket.Conn) { + t.Helper() + ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second) + srv := httptest.NewServer(HandlerWithOptions(ctx, options)) + t.Cleanup(func() { srv.Close(); cancel() }) + conns := make([]*websocket.Conn, 0, n) + for i := 0; i < n; i++ { + conns = append(conns, dialChatConn(t, ctx, srv)) + } + return ctx, cancel, srv, conns +} + +func dialChatConn(t *testing.T, ctx context.Context, srv *httptest.Server) *websocket.Conn { + t.Helper() + conn, _, err := websocket.Dial(ctx, "ws"+strings.TrimPrefix(srv.URL, "http")+"/connect", nil) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { conn.CloseNow() }) + return conn +} + +// readUntil reads messages until one of type want arrives, failing on a server +// error frame; interleaved push frames are skipped. +func readUntil(t *testing.T, ctx context.Context, conn *websocket.Conn, want string) protocol.Message { + t.Helper() + for { + var message protocol.Message + if err := wsjson.Read(ctx, conn, &message); err != nil { + t.Fatalf("read (waiting for %s): %v", want, err) + } + if message.Type == protocol.Error { + t.Fatalf("server error frame while waiting for %s: %s", want, message.Error) + } + if message.Type == want { + return message + } + } +} + +// nextEvent reads the next chat_event frame strictly, so a test can assert the +// order of the turn's frames. +func nextEvent(t *testing.T, ctx context.Context, conn *websocket.Conn) protocol.ChatEventFrame { + t.Helper() + for { + var message protocol.Message + if err := wsjson.Read(ctx, conn, &message); err != nil { + t.Fatalf("read event: %v", err) + } + if message.Type == protocol.Error { + t.Fatalf("server error frame: %s", message.Error) + } + if message.Type == protocol.ChatEvent && message.ChatEvent != nil { + return *message.ChatEvent + } + } +} + +// nextPermission reads the next chat_permission frame for requestID. +func nextPermission(t *testing.T, ctx context.Context, conn *websocket.Conn, requestID string) protocol.ChatPermissionFrame { + t.Helper() + for { + var message protocol.Message + if err := wsjson.Read(ctx, conn, &message); err != nil { + t.Fatalf("read permission: %v", err) + } + if message.Type == protocol.Error { + t.Fatalf("server error frame: %s", message.Error) + } + if message.Type == protocol.ChatPermission && message.ChatPermission != nil && message.ChatPermission.RequestID == requestID { + return *message.ChatPermission + } + } +} + +func writeChat(t *testing.T, ctx context.Context, conn *websocket.Conn, message protocol.Message) { + t.Helper() + if err := wsjson.Write(ctx, conn, message); err != nil { + t.Fatal(err) + } +} + +// TestChatFanoutToSeveralClients is the multi-client acceptance test: a prompt +// from one client is accepted, its user turn is pushed live to the other client +// attributed to the sending device, and the turn's streaming frames reach every +// watching client, not only the one that prompted. +func TestChatFanoutToSeveralClients(t *testing.T) { + broker := newChannelChat() + ctx, _, _, conns := dialChatServer(t, Options{Chat: broker}, 2) + phone, tablet := conns[0], conns[1] + + // The tablet watches the session before anything is sent. + writeChat(t, ctx, tablet, protocol.Message{Type: protocol.ChatSubscribe, ID: "s1", ChatSubscribe: &protocol.ChatQuery{SessionID: "ses_1"}}) + readUntil(t, ctx, tablet, protocol.ChatSubscribe) + + // The phone prompts. Its ack is not a queue acknowledgement. + writeChat(t, ctx, phone, protocol.Message{Type: protocol.ChatPrompt, ID: "p1", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "from the phone", Client: "Pixel 9"}}) + ack := readUntil(t, ctx, phone, protocol.ChatPrompt) + if ack.ID != "p1" || ack.ChatQueued { + t.Fatalf("phone prompt ack = %+v, want accepted (not queued)", ack) + } + + // The tablet sees the phone's message, attributed to the phone. + userFrame := nextEvent(t, ctx, tablet) + if userFrame.Kind != protocol.ChatEventUser || userFrame.Client != "Pixel 9" || userFrame.Part == nil || userFrame.Part.Text != "from the phone" { + t.Fatalf("tablet user frame = %+v, want the phone's message attributed to Pixel 9", userFrame) + } + + // The turn's streaming output reaches both clients in order. + broker.push(protocol.ChatEventFrame{SessionID: "ses_1", MessageID: "msg_1", Kind: protocol.ChatEventText, Delta: "hel", Part: &protocol.ChatPart{Type: protocol.ChatPartText, ID: "msg_1#0"}}) + broker.push(protocol.ChatEventFrame{SessionID: "ses_1", MessageID: "msg_1", Kind: protocol.ChatEventText, Delta: "lo", Part: &protocol.ChatPart{Type: protocol.ChatPartText, ID: "msg_1#0"}}) + broker.push(protocol.ChatEventFrame{SessionID: "ses_1", MessageID: "msg_1", Kind: protocol.ChatEventStep, Step: &protocol.ChatStep{Status: protocol.ChatStepEnded, Index: 1}}) + + for _, client := range []struct { + name string + conn *websocket.Conn + }{{"phone", phone}, {"tablet", tablet}} { + var text strings.Builder + for i := 0; i < 2; i++ { + frame := nextEvent(t, ctx, client.conn) + if frame.Kind != protocol.ChatEventText { + t.Fatalf("%s frame %d = %+v, want text", client.name, i, frame) + } + text.WriteString(frame.Delta) + } + if text.String() != "hello" { + t.Fatalf("%s saw %q, want the streamed turn output", client.name, text.String()) + } + if end := nextEvent(t, ctx, client.conn); end.Kind != protocol.ChatEventStep || end.Step == nil || end.Step.Status != protocol.ChatStepEnded { + t.Fatalf("%s step frame = %+v, want ended", client.name, end) + } + } +} + +// TestChatPromptSerialisedPerSession pins that two prompts for one session never +// interleave: the second is accepted as queued and only posted once the first +// turn ends. +func TestChatPromptSerialisedPerSession(t *testing.T) { + broker := newChannelChat() + ctx, _, _, conns := dialChatServer(t, Options{Chat: broker}, 2) + phone, tablet := conns[0], conns[1] + + writeChat(t, ctx, phone, protocol.Message{Type: protocol.ChatPrompt, ID: "p1", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "one"}}) + if ack := readUntil(t, ctx, phone, protocol.ChatPrompt); ack.ChatQueued { + t.Fatalf("first prompt should start immediately: %+v", ack) + } + + // The tablet's prompt while the turn is in flight is queued, and it is told so. + writeChat(t, ctx, tablet, protocol.Message{Type: protocol.ChatPrompt, ID: "p2", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "two"}}) + if ack := readUntil(t, ctx, tablet, protocol.ChatPrompt); !ack.ChatQueued { + t.Fatalf("second prompt should be acknowledged as queued: %+v", ack) + } + if broker.promptCount() != 1 { + t.Fatalf("prompts forwarded = %d, want 1 while the first turn is in flight", broker.promptCount()) + } + + // End the first turn; the queued prompt is then posted. + broker.push(protocol.ChatEventFrame{SessionID: "ses_1", MessageID: "msg_1", Kind: protocol.ChatEventStep, Step: &protocol.ChatStep{Status: protocol.ChatStepEnded, Index: 1}}) + deadline := time.Now().Add(3 * time.Second) + for broker.promptCount() < 2 { + if time.Now().After(deadline) { + t.Fatalf("queued prompt was never posted: %v", broker.promptTexts()) + } + time.Sleep(5 * time.Millisecond) + } + if got := broker.promptTexts(); len(got) != 2 || got[0] != "one" || got[1] != "two" { + t.Fatalf("prompts = %v, want [one two] in order", got) + } +} + +// TestChatApprovalFirstAnswerWins is the exactly-once acceptance test: a pending +// approval is shared, the first answer is recorded with the client that gave it +// and broadcast to every client, and a later answer is refused. +func TestChatApprovalFirstAnswerWins(t *testing.T) { + broker := newChannelChat() + broker.perm = []protocol.ChatPermissionFrame{{SessionID: "ses_1", RequestID: "req_1", Action: "bash", Resources: []string{"rm -rf /tmp"}}} + ctx, _, _, conns := dialChatServer(t, Options{Chat: broker}, 2) + phone, tablet := conns[0], conns[1] + + // A turn starts so the poller runs and pushes the pending request. + writeChat(t, ctx, phone, protocol.Message{Type: protocol.ChatPrompt, ID: "p1", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "run it"}}) + readUntil(t, ctx, phone, protocol.ChatPrompt) + + pending := nextPermission(t, ctx, phone, "req_1") + if pending.Resolved { + t.Fatalf("request already marked resolved: %+v", pending) + } + + // A second client attaches and is replayed the still-pending request, so its + // card is answerable too. + writeChat(t, ctx, tablet, protocol.Message{Type: protocol.ChatSubscribe, ID: "s1", ChatSubscribe: &protocol.ChatQuery{SessionID: "ses_1"}}) + readUntil(t, ctx, tablet, protocol.ChatSubscribe) + replay := nextPermission(t, ctx, tablet, "req_1") + if replay.Resolved || replay.Action != "bash" { + t.Fatalf("replayed permission = %+v, want the pending request", replay) + } + + // The phone answers first. + writeChat(t, ctx, phone, protocol.Message{Type: protocol.ChatReply, ID: "a1", ChatReply: &protocol.ChatReplyRequest{SessionID: "ses_1", RequestID: "req_1", Decision: protocol.ChatDecisionOnce, Client: "Pixel 9"}}) + readUntil(t, ctx, phone, protocol.ChatReply) + + // Both clients see the resolution, with the answering device recorded. + for _, client := range []struct { + name string + conn *websocket.Conn + }{{"phone", phone}, {"tablet", tablet}} { + resolution := nextPermission(t, ctx, client.conn, "req_1") + if !resolution.Resolved || resolution.Decision != protocol.ChatDecisionOnce || resolution.ResolvedBy != "Pixel 9" { + t.Fatalf("%s resolution = %+v, want resolved once by Pixel 9", client.name, resolution) + } + } + + // The tablet's later answer is refused, and it never reaches the agent. + writeChat(t, ctx, tablet, protocol.Message{Type: protocol.ChatReply, ID: "a2", ChatReply: &protocol.ChatReplyRequest{SessionID: "ses_1", RequestID: "req_1", Decision: protocol.ChatDecisionAlways, Client: "Pixel 10 Pro Fold"}}) + var refused protocol.Message + if err := wsjson.Read(ctx, tablet, &refused); err != nil { + t.Fatal(err) + } + if refused.Type != protocol.Error || !strings.Contains(refused.Error, "already answered by Pixel 9") { + t.Fatalf("second answer was not refused as already answered: %+v", refused) + } + if broker.replyCount() != 1 { + t.Fatalf("broker replies = %d, want the agent to receive exactly one answer", broker.replyCount()) + } +} + +// TestChatSubscribeWireShape pins the exact wire body the Android app sends for +// chat_subscribe (ChatProtocol.subscribeRequest): the session id travels in the +// chat_subscribe field, not chat_query. The handler once read chat_query, so the +// unit tests passed while the shipped app's subscribe was silently rejected; this +// test writes the raw JSON, attaches the connection and proves a prompt from +// another client reaches it. +func TestChatSubscribeWireShape(t *testing.T) { + broker := newChannelChat() + ctx, _, _, conns := dialChatServer(t, Options{Chat: broker}, 2) + phone, watch := conns[0], conns[1] + + if err := watch.Write(ctx, websocket.MessageText, []byte(`{"type":"chat_subscribe","id":"s1","chat_subscribe":{"session_id":"ses_1"}}`)); err != nil { + t.Fatal(err) + } + if ack := readUntil(t, ctx, watch, protocol.ChatSubscribe); ack.ID != "s1" { + t.Fatalf("subscribe ack = %+v, want id s1", ack) + } + + // The watcher is attached: another client's prompt is fanned out to it. + writeChat(t, ctx, phone, protocol.Message{Type: protocol.ChatPrompt, ID: "p1", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "ping", Client: "Pixel 9"}}) + readUntil(t, ctx, phone, protocol.ChatPrompt) + frame := nextEvent(t, ctx, watch) + if frame.Kind != protocol.ChatEventUser || frame.Client != "Pixel 9" || frame.Part == nil || frame.Part.Text != "ping" { + t.Fatalf("watcher frame = %+v, want the phone's message (subscribe did not attach)", frame) + } +} + +// TestChatQueuedPromptFailureSurfaced pins that a prompt accepted as queued whose +// delivery to the agent later fails is reported to the client that sent it, +// instead of leaving its composer showing "Queued" with no error. +func TestChatQueuedPromptFailureSurfaced(t *testing.T) { + broker := newChannelChat() + broker.promptErrAt = 2 // the queued (second) prompt fails to reach the agent + ctx, _, _, conns := dialChatServer(t, Options{Chat: broker}, 2) + phone, tablet := conns[0], conns[1] + + // The phone's prompt starts a turn held in flight. + writeChat(t, ctx, phone, protocol.Message{Type: protocol.ChatPrompt, ID: "p1", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "one"}}) + if ack := readUntil(t, ctx, phone, protocol.ChatPrompt); ack.ChatQueued { + t.Fatalf("first prompt should start immediately: %+v", ack) + } + + // The tablet's prompt is accepted as queued and acknowledged as such. + writeChat(t, ctx, tablet, protocol.Message{Type: protocol.ChatPrompt, ID: "p2", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "two"}}) + if ack := readUntil(t, ctx, tablet, protocol.ChatPrompt); !ack.ChatQueued { + t.Fatalf("second prompt should be acknowledged as queued: %+v", ack) + } + + // End the first turn; the queued prompt is posted and the broker rejects it. + broker.push(protocol.ChatEventFrame{SessionID: "ses_1", MessageID: "msg_1", Kind: protocol.ChatEventStep, Step: &protocol.ChatStep{Status: protocol.ChatStepEnded, Index: 1}}) + + for { + var message protocol.Message + if err := wsjson.Read(ctx, tablet, &message); err != nil { + t.Fatalf("read (waiting for the queued prompt failure): %v", err) + } + if message.Type != protocol.Error { + continue + } + if message.ID != "p2" || !strings.Contains(message.Error, "broker rejected the prompt") { + t.Fatalf("queued prompt failure = %+v, want an error for p2 naming the broker failure", message) + } + break + } +} + +// TestChatPendingApprovalsAllReplayed pins that every unresolved approval request +// a room holds is replayed to a client that attaches afterwards, not only the +// most recent one, so both cards are answerable on the late client. +func TestChatPendingApprovalsAllReplayed(t *testing.T) { + broker := newChannelChat() + broker.perm = []protocol.ChatPermissionFrame{ + {SessionID: "ses_1", RequestID: "req_1", Action: "bash", Resources: []string{"rm -rf /tmp"}}, + {SessionID: "ses_1", RequestID: "req_2", Action: "write", Resources: []string{"/etc/hosts"}}, + } + ctx, _, _, conns := dialChatServer(t, Options{Chat: broker}, 2) + phone, tablet := conns[0], conns[1] + + // A turn starts so the poller pushes both pending requests to the phone. + writeChat(t, ctx, phone, protocol.Message{Type: protocol.ChatPrompt, ID: "p1", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "run them"}}) + readUntil(t, ctx, phone, protocol.ChatPrompt) + nextPermission(t, ctx, phone, "req_1") + nextPermission(t, ctx, phone, "req_2") + + // A client that attaches afterwards is replayed both. + writeChat(t, ctx, tablet, protocol.Message{Type: protocol.ChatSubscribe, ID: "s1", ChatSubscribe: &protocol.ChatQuery{SessionID: "ses_1"}}) + readUntil(t, ctx, tablet, protocol.ChatSubscribe) + first := nextPermission(t, ctx, tablet, "req_1") + second := nextPermission(t, ctx, tablet, "req_2") + if first.Resolved || second.Resolved || first.Action != "bash" || second.Action != "write" { + t.Fatalf("replayed permissions = %+v / %+v, want both still-pending requests", first, second) + } +} + +// TestChatResyncAfterReconnect is the resync acceptance test: a client that drops +// and reconnects re-syncs the whole conversation from retained state, including +// the user turn and who sent it. +func TestChatResyncAfterReconnect(t *testing.T) { + broker := scriptedChat() + ctx, _, srv, conns := dialChatServer(t, Options{Chat: broker}, 1) + phone := conns[0] + + writeChat(t, ctx, phone, protocol.Message{Type: protocol.ChatPrompt, ID: "p1", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "hi", Client: "Pixel 9"}}) + readUntil(t, ctx, phone, protocol.ChatPrompt) + readChatTurn(t, ctx, phone) + + // The phone's socket drops. + phone.CloseNow() + + // A fresh connection re-syncs from retained state. + reconnected := dialChatConn(t, ctx, srv) + writeChat(t, ctx, reconnected, protocol.Message{Type: protocol.ChatMessages, ID: "m1", ChatQuery: &protocol.ChatQuery{SessionID: "ses_1"}}) + response := readUntil(t, ctx, reconnected, protocol.ChatMessages) + if len(response.ChatMessages) != 2 { + t.Fatalf("resync returned %d messages, want user+assistant: %+v", len(response.ChatMessages), response.ChatMessages) + } + user := response.ChatMessages[0] + if user.Role != protocol.ChatRoleUser || user.Client != "Pixel 9" || len(user.Parts) != 1 || user.Parts[0].Text != "hi" { + t.Fatalf("resynced user turn = %+v", user) + } + assistant := response.ChatMessages[1] + if assistant.Role != protocol.ChatRoleAssistant || assistant.ID != "msg_1" { + t.Fatalf("resynced assistant turn = %+v", assistant) + } +} diff --git a/internal/server/chat_permissions.go b/internal/server/chat_permissions.go index 28a2b72b..32d006ba 100644 --- a/internal/server/chat_permissions.go +++ b/internal/server/chat_permissions.go @@ -1,5 +1,7 @@ package server +import "git.a-wan.net/alan/pipelines/internal/protocol" + // chatPermissionRetainedLimit bounds the dedup set of already-pushed permission // request ids one session retains, so a long turn cannot grow it without limit. const chatPermissionRetainedLimit = 256 @@ -31,24 +33,83 @@ func (h *chatHub) seenPermission(sessionID, requestID string) bool { return true } -// forgetPermission releases a request id reserved by seenPermission when its -// frame could not be written, so a later poll re-pushes it instead of the id -// staying "seen" while the phone never received the request. -func (h *chatHub) forgetPermission(sessionID, requestID string) { +// reservePermission claims the shared right to answer requestID for client. It +// returns true when this caller is the first to answer (the only caller allowed +// to reach the agent), and false with the recorded resolution when the request is +// already answered or is already being answered, so a later answer is refused +// rather than delivered twice. The reservation is bounded like the dedup set. +func (h *chatHub) reservePermission(sessionID, requestID, client string) (*chatResolution, bool) { if sessionID == "" || requestID == "" { - return + return nil, false } + h.mu.Lock() + defer h.mu.Unlock() + turn := h.turnLocked(sessionID) + if turn.resolutions == nil { + turn.resolutions = map[string]*chatResolution{} + } + if prior, ok := turn.resolutions[requestID]; ok { + return prior, false + } + turn.resolutions[requestID] = &chatResolution{client: client} + turn.resolutionOrder = append(turn.resolutionOrder, requestID) + if len(turn.resolutionOrder) > chatPermissionRetainedLimit { + oldest := turn.resolutionOrder[0] + turn.resolutionOrder = turn.resolutionOrder[1:] + delete(turn.resolutions, oldest) + } + return nil, true +} + +// releasePermission drops a reservation whose answer never reached the agent, so +// a later attempt can win instead of the request staying permanently refused. +func (h *chatHub) releasePermission(sessionID, requestID string) { h.mu.Lock() defer h.mu.Unlock() turn := h.turns[sessionID] if turn == nil { return } - delete(turn.permissions, requestID) - for i, id := range turn.permissionOrder { + delete(turn.resolutions, requestID) + for i, id := range turn.resolutionOrder { if id == requestID { - turn.permissionOrder = append(turn.permissionOrder[:i], turn.permissionOrder[i+1:]...) + turn.resolutionOrder = append(turn.resolutionOrder[:i], turn.resolutionOrder[i+1:]...) break } } } + +// confirmPermission records the delivered answer and pushes the resolution to +// every watching client, so each one's approval card clears and shows the +// outcome and which client gave it. +func (h *chatHub) confirmPermission(sessionID, requestID, client, decision string) { + h.mu.Lock() + if turn := h.turns[sessionID]; turn != nil { + if resolution, ok := turn.resolutions[requestID]; ok { + resolution.decision = decision + resolution.answered = true + } + } + frame := protocol.ChatPermissionFrame{SessionID: sessionID, RequestID: requestID} + var targets []*chatSub + if room := h.rooms[sessionID]; room != nil { + for i := range room.pending { + if room.pending[i].RequestID == requestID { + frame = room.pending[i] + room.pending = append(room.pending[:i], room.pending[i+1:]...) + break + } + } + for _, sub := range room.subs { + targets = append(targets, sub) + } + } + h.mu.Unlock() + frame.Resolved = true + frame.Decision = decision + frame.ResolvedBy = client + msg := protocol.Message{Type: protocol.ChatPermission, ChatPermission: &frame} + for _, sub := range targets { + sub.send(msg) + } +} diff --git a/internal/server/chat_room.go b/internal/server/chat_room.go new file mode 100644 index 00000000..caa16324 --- /dev/null +++ b/internal/server/chat_room.go @@ -0,0 +1,662 @@ +package server + +import ( + "context" + "errors" + "fmt" + "log" + "strings" + "sync" + "time" + + "git.a-wan.net/alan/pipelines/internal/opencode" + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// The chat room is one session's shared live channel. Many clients attach to it +// (the operator's phone, tablet and terminal) and every frame any turn produces +// is fanned out to all of them, so each device sees the same conversation +// including the other devices' prompts and the turn's streaming output. The room +// owns the session's one broker stream and its one prompt queue, so a session is +// never read-only for a client and two turns never interleave: a prompt that +// arrives while a turn is in flight is queued (bounded) and its client is told so +// in the ack. +const ( + // chatRoomSubscriberBuffer bounds one attached client's pending frames. A + // client that falls this far behind is dropped rather than blocking the turn + // or the other clients; it re-syncs from history when it reattaches. + chatRoomSubscriberBuffer = 64 + // chatRoomQueueLimit bounds the prompts one session may hold while a turn is + // in flight. A prompt that would exceed it is refused with a visible error + // instead of being silently dropped. + chatRoomQueueLimit = 8 + // chatClientLabelMax bounds the human-readable client label the server stores + // and echoes, so a long device name cannot grow a frame without limit. + chatClientLabelMax = 48 + // chatClientLabelFallback labels a prompt whose sender did not name itself, so + // a transcript always has something to attribute the message to. + chatClientLabelFallback = "Another device" + // chatRoomPendingLimit bounds how many unresolved approval requests one room + // retains for replay to a client that attaches after they were raised, so a + // long turn cannot grow the replay state without limit. + chatRoomPendingLimit = 16 +) + +// chatSub is one client's attachment to a session's shared stream. Frames reach +// it through a dedicated writer goroutine so a slow or broken client never stalls +// the turn or the other subscribers; the buffered channel bounds how far behind +// it may fall. +type chatSub struct { + hub *chatHub + room *chatRoom + clientID string + label string + ch chan protocol.Message + done chan struct{} + once sync.Once + write func(protocol.Message) error +} + +func (s *chatSub) run() { + for { + select { + case <-s.done: + return + case msg := <-s.ch: + if err := s.write(msg); err != nil { + s.close() + return + } + } + } +} + +func (s *chatSub) send(msg protocol.Message) { + select { + case <-s.done: + return + default: + } + select { + case s.ch <- msg: + default: + // The client is not draining: drop it rather than block the fan-out. Its + // next attach re-syncs from history. + s.close() + } +} + +// close detaches the subscription and stops its writer goroutine exactly once. +func (s *chatSub) close() { + s.once.Do(func() { + close(s.done) + s.hub.detach(s.room.sessionID, s) + }) +} + +// chatQueuedPrompt is one prompt waiting for the session's in-flight turn to +// finish. acked marks a prompt the handler already acknowledged as queued, so the +// turn runner does not send a second (success) acknowledgement for the same +// request id; write is kept either way so a later broker failure is still +// reported to the client that sent it. +type chatQueuedPrompt struct { + text string + requestID string + write func(protocol.Message) error + acked bool +} + +// chatRoom is one session's shared live channel. Every field is guarded by the +// owning chatHub's mutex. +type chatRoom struct { + sessionID string + broker chatBroker + ctx context.Context + cancel context.CancelFunc + subs map[string]*chatSub + queue []*chatQueuedPrompt + running bool + streaming bool + // buffering holds the turn's frames until the prompting client's ack has been + // written, so the ack always precedes the frames it acknowledges. It is set + // only while the very first turn subscribes to the firehose. + buffering bool + buffered []protocol.ChatEventFrame + // pending holds the room's unresolved approval requests, in the order they + // were raised, replayed to a client that attaches after they were raised. A + // request is removed once it is resolved. + pending []protocol.ChatPermissionFrame + pollerStarted bool + wake chan struct{} + turnDone chan struct{} +} + +func newChatRoom(base context.Context, sessionID string) *chatRoom { + if base == nil { + base = context.Background() + } + roomCtx, cancel := context.WithCancel(base) + return &chatRoom{ + sessionID: sessionID, + ctx: roomCtx, + cancel: cancel, + subs: map[string]*chatSub{}, + wake: make(chan struct{}, 1), + } +} + +// roomLocked returns the session's room, creating it (and its turn runner) when +// it is the first client to watch the session. Callers must hold h.mu. +func (h *chatHub) roomLocked(sessionID string) *chatRoom { + if h.rooms == nil { + h.rooms = map[string]*chatRoom{} + } + if room := h.rooms[sessionID]; room != nil { + return room + } + room := newChatRoom(h.baseCtx, sessionID) + h.rooms[sessionID] = room + go h.runRoom(room) + return room +} + +// attach registers write as one client's subscription to sessionID's stream and +// returns it, or the existing subscription when the same connection has already +// attached. It is idempotent so a client may prompt and subscribe without +// registering twice. +func (h *chatHub) attach(sessionID, clientID, label string, broker chatBroker, write func(protocol.Message) error) *chatSub { + if sessionID == "" || clientID == "" || write == nil { + return nil + } + h.mu.Lock() + room := h.roomLocked(sessionID) + if room.broker == nil { + room.broker = broker + } + if sub, ok := room.subs[clientID]; ok { + if label != "" { + sub.label = label + } + h.mu.Unlock() + return sub + } + sub := &chatSub{ + hub: h, + room: room, + clientID: clientID, + label: label, + ch: make(chan protocol.Message, chatRoomSubscriberBuffer), + done: make(chan struct{}), + write: write, + } + room.subs[clientID] = sub + h.mu.Unlock() + go sub.run() + return sub +} + +// detach drops one subscription. The room (and its broker stream and queue) is +// released once its last client leaves, so a session with no watchers holds no +// goroutine. +func (h *chatHub) detach(sessionID string, sub *chatSub) { + h.mu.Lock() + room := h.rooms[sessionID] + if room == nil || room.subs[sub.clientID] != sub { + h.mu.Unlock() + return + } + delete(room.subs, sub.clientID) + if len(room.subs) == 0 { + delete(h.rooms, sessionID) + room.cancel() + } + h.mu.Unlock() +} + +// detachClient drops every chat subscription one connection holds; the read loop +// calls it when the connection ends so no subscriber goroutine outlives it. +func (h *chatHub) detachClient(clientID string) { + if clientID == "" { + return + } + h.mu.Lock() + var subs []*chatSub + for _, room := range h.rooms { + if sub, ok := room.subs[clientID]; ok { + subs = append(subs, sub) + } + } + h.mu.Unlock() + for _, sub := range subs { + sub.close() + } +} + +// fanout delivers one frame to every client watching sessionID except the one +// named by except (the sender, who already has it locally). +func (h *chatHub) fanout(sessionID string, msg protocol.Message, except string) { + h.mu.Lock() + var targets []*chatSub + if room := h.rooms[sessionID]; room != nil { + for id, sub := range room.subs { + if id == except { + continue + } + targets = append(targets, sub) + } + } + h.mu.Unlock() + for _, sub := range targets { + sub.send(msg) + } +} + +// broadcastUser retains a prompt as a user turn and pushes it live to every other +// client watching the session, attributed to the sending client's label. The +// sender already has the message locally, so it is excluded to keep its own +// transcript from duplicating it. +func (h *chatHub) broadcastUser(frame protocol.ChatEventFrame, exceptClientID string) { + h.apply(frame) + h.fanout(frame.SessionID, protocol.Message{Type: protocol.ChatEvent, ChatEvent: &frame}, exceptClientID) +} + +// emit folds one broker frame into the retained state and fans it out. While the +// first turn's ack is still pending the frames are buffered and flushed in order +// once it is written. A step-ended frame finishes the turn, letting the queue +// advance. +func (h *chatHub) emit(frame protocol.ChatEventFrame) { + h.apply(frame) + h.mu.Lock() + room := h.rooms[frame.SessionID] + buffered := false + var targets []*chatSub + if room != nil { + if room.buffering { + room.buffered = append(room.buffered, frame) + buffered = true + } else { + for _, sub := range room.subs { + targets = append(targets, sub) + } + } + } + if room != nil && frame.Kind == protocol.ChatEventStep && frame.Step != nil && frame.Step.Status == protocol.ChatStepEnded { + h.finishTurnLocked(room) + } + h.mu.Unlock() + if buffered { + return + } + msg := protocol.Message{Type: protocol.ChatEvent, ChatEvent: &frame} + for _, sub := range targets { + sub.send(msg) + } +} + +// finishTurnLocked marks the room's turn finished and releases the turn runner's +// wait. Callers must hold h.mu. +func (h *chatHub) finishTurnLocked(room *chatRoom) { + room.running = false + if room.turnDone != nil { + close(room.turnDone) + room.turnDone = nil + } +} + +// flushBuffered releases the frames held while the ack was pending and delivers +// them in order. It is a no-op once the room is no longer buffering. +func (h *chatHub) flushBuffered(sessionID string) { + h.mu.Lock() + room := h.rooms[sessionID] + var pending []protocol.ChatEventFrame + var targets []*chatSub + if room != nil && room.buffering { + room.buffering = false + pending = room.buffered + room.buffered = nil + for _, sub := range room.subs { + targets = append(targets, sub) + } + } + h.mu.Unlock() + for i := range pending { + frame := pending[i] + msg := protocol.Message{Type: protocol.ChatEvent, ChatEvent: &frame} + for _, sub := range targets { + sub.send(msg) + } + } +} + +// submitPrompt accepts one prompt: it starts the turn runner immediately when no +// turn is in flight, or queues it (bounded) when one is. It returns whether the +// prompt was queued or refused. +func (h *chatHub) submitPrompt(sessionID string, p *chatQueuedPrompt) (queued bool, refused bool) { + h.mu.Lock() + room := h.roomLocked(sessionID) + if room.running || len(room.queue) > 0 { + if len(room.queue) >= chatRoomQueueLimit { + h.mu.Unlock() + return false, true + } + // The client is acknowledged as queued by the handler, so the turn runner + // must not acknowledge the same request again once it runs. The write is + // still kept so a later broker failure reaches the client that sent it. + p.acked = true + room.queue = append(room.queue, p) + signalWake(room.wake) + h.mu.Unlock() + return true, false + } + room.queue = append(room.queue, p) + signalWake(room.wake) + h.mu.Unlock() + return false, false +} + +// pendingFrames returns a copy of the room's unresolved approval requests so a +// client that attaches after they were raised can be shown every one of them. It +// returns nil when the room holds none. +func (h *chatHub) pendingFrames(sessionID string) []protocol.ChatPermissionFrame { + h.mu.Lock() + defer h.mu.Unlock() + room := h.rooms[sessionID] + if room == nil || len(room.pending) == 0 { + return nil + } + frames := make([]protocol.ChatPermissionFrame, len(room.pending)) + copy(frames, room.pending) + return frames +} + +// pushPermission publishes one newly seen pending approval request to every +// client watching the session and remembers it (bounded) for a client that +// attaches later. A request already seen (or already resolved) is not pushed +// again. +func (h *chatHub) pushPermission(sessionID string, frame protocol.ChatPermissionFrame) { + if frame.RequestID == "" || frame.Resolved { + return + } + if !h.seenPermission(sessionID, frame.RequestID) { + return + } + h.mu.Lock() + var targets []*chatSub + if room := h.rooms[sessionID]; room != nil { + known := false + for i := range room.pending { + if room.pending[i].RequestID == frame.RequestID { + room.pending[i] = frame + known = true + break + } + } + if !known { + room.pending = append(room.pending, frame) + if len(room.pending) > chatRoomPendingLimit { + room.pending = room.pending[len(room.pending)-chatRoomPendingLimit:] + } + } + for _, sub := range room.subs { + targets = append(targets, sub) + } + } + h.mu.Unlock() + msg := protocol.Message{Type: protocol.ChatPermission, ChatPermission: &frame} + for _, sub := range targets { + sub.send(msg) + } +} + +// runRoom is the session's turn runner: it takes queued prompts one at a time, +// posts each to the broker and waits for the turn to end, so two prompts of one +// session can never interleave. +func (h *chatHub) runRoom(room *chatRoom) { + for { + p, done, ok := h.nextPrompt(room) + if !ok { + return + } + h.runTurn(room, p, done) + } +} + +// nextPrompt pops the next queued prompt, blocking until one arrives or the room +// is released. It marks the room running and creates the turn's completion +// channel so a stale signal from a previous turn can never end the next one. +func (h *chatHub) nextPrompt(room *chatRoom) (*chatQueuedPrompt, chan struct{}, bool) { + for { + h.mu.Lock() + if len(room.queue) > 0 { + p := room.queue[0] + room.queue = room.queue[1:] + room.running = true + room.turnDone = make(chan struct{}) + done := room.turnDone + h.mu.Unlock() + return p, done, true + } + h.mu.Unlock() + select { + case <-room.ctx.Done(): + return nil, nil, false + case <-room.wake: + } + } +} + +// runTurn subscribes to the broker stream when needed, posts one prompt, writes +// its ack and waits for the turn to end. +func (h *chatHub) runTurn(room *chatRoom, p *chatQueuedPrompt, done chan struct{}) { + broker := h.roomBroker(room) + first := false + h.mu.Lock() + if !room.streaming { + first = true + room.buffering = true + } + h.mu.Unlock() + defer h.flushBuffered(room.sessionID) + + if broker == nil { + h.failPrompt(room, p, errors.New("chat is not configured on this server")) + return + } + if first { + if err := h.startStream(room, broker); err != nil { + h.failPrompt(room, p, err) + h.endRoomTurn(room) + return + } + } + if err := broker.Prompt(room.ctx, room.sessionID, p.text); err != nil { + h.failPrompt(room, p, err) + h.endRoomTurn(room) + return + } + if h.registry != nil { + if err := h.registry.TouchOperatorSession(room.ctx, room.sessionID); err != nil { + log.Printf("touch operator session %s: %v", room.sessionID, err) + } + } + if p.write != nil && !p.acked { + _ = p.write(protocol.Message{Type: protocol.ChatPrompt, ID: p.requestID}) + } + h.flushBuffered(room.sessionID) + // Start the approval poller once, after the first ack, so a pending request + // is surfaced after the prompt is acknowledged and shared with every client. + h.mu.Lock() + startPoller := !room.pollerStarted + room.pollerStarted = true + h.mu.Unlock() + if startPoller { + go h.pollRoom(room, broker) + } + select { + case <-done: + case <-room.ctx.Done(): + } +} + +// endRoomTurn releases the turn slot after a prompt that never entered flight, +// so the queue advances immediately instead of waiting for a step that never +// comes. +func (h *chatHub) endRoomTurn(room *chatRoom) { + h.mu.Lock() + h.finishTurnLocked(room) + h.mu.Unlock() +} + +// failPrompt reports a refused prompt to the client that sent it, so a prompt +// that never reached the agent is visible on the device that sent it rather than +// leaving its composer waiting. It is reported for a queued prompt too, whose +// success ack was already sent but whose delivery may still fail. +func (h *chatHub) failPrompt(room *chatRoom, p *chatQueuedPrompt, err error) { + if p.write == nil || err == nil { + return + } + _ = p.write(protocol.Message{Type: protocol.Error, ID: p.requestID, Error: err.Error()}) +} + +// roomBroker returns the broker bound to the room. +func (h *chatHub) roomBroker(room *chatRoom) chatBroker { + h.mu.Lock() + defer h.mu.Unlock() + return room.broker +} + +// startStream attaches the room to the broker firehose, waiting until the +// subscription is ready so no delta emitted between subscribing and posting a +// prompt is lost. The permission poller starts alongside it. +func (h *chatHub) startStream(room *chatRoom, broker chatBroker) error { + attached := make(chan struct{}) + var once sync.Once + result := make(chan error, 1) + ctx := room.ctx + go func() { + result <- broker.Stream(ctx, room.sessionID, func() { + once.Do(func() { close(attached) }) + }, func(frame protocol.ChatEventFrame) error { + h.emit(frame) + return nil + }) + }() + select { + case <-attached: + case err := <-result: + if err == nil { + err = errors.New("chat stream ended before it was subscribed") + } + return err + case <-ctx.Done(): + return ctx.Err() + } + h.mu.Lock() + room.streaming = true + h.mu.Unlock() + go h.drainStream(room, result) + return nil +} + +// drainStream reports the terminal error of a room's subscription and clears the +// streaming flag so a later turn re-subscribes; it also releases a turn still +// waiting on a stream that ended. +func (h *chatHub) drainStream(room *chatRoom, result <-chan error) { + err := <-result + h.mu.Lock() + room.streaming = false + h.finishTurnLocked(room) + h.mu.Unlock() + if err != nil && room.ctx.Err() == nil { + log.Printf("chat stream session=%s: %v", room.sessionID, err) + } +} + +// pollRoom polls the broker's pending-approval list for the room on a fixed +// interval and pushes each newly seen request to every attached client. The +// first poll runs immediately; the loop stops with the room's context. +func (h *chatHub) pollRoom(room *chatRoom, broker chatBroker) { + ticker := time.NewTicker(chatPermissionPollInterval) + defer ticker.Stop() + reported := false + for { + if err := h.pollPermissionsOnce(room.ctx, broker, room.sessionID); err != nil { + if room.ctx.Err() != nil { + return + } + if errors.Is(err, opencode.ErrPermissionUnsupported) { + log.Printf("chat permission poll session=%s: %v", room.sessionID, err) + return + } + if reported { + log.Printf("chat permission poll session=%s: %v", room.sessionID, err) + } else { + reported = true + h.fanout(room.sessionID, protocol.Message{Type: protocol.Error, Error: "chat permission poll: " + err.Error()}, "") + } + } + select { + case <-room.ctx.Done(): + return + case <-ticker.C: + } + } +} + +// pollPermissionsOnce performs one poll and pushes each newly seen request of the +// session to every client watching it. +func (h *chatHub) pollPermissionsOnce(ctx context.Context, broker chatBroker, sessionID string) error { + pending, err := broker.Permissions(ctx, sessionID) + if err != nil { + return err + } + for _, request := range pending { + if request.SessionID != sessionID || request.RequestID == "" { + continue + } + h.pushPermission(sessionID, request) + } + return nil +} + +// signalWake nudges a room's turn runner without blocking. The channel is +// buffered, so a signal already pending is enough. +func signalWake(ch chan struct{}) { + select { + case ch <- struct{}{}: + default: + } +} + +// sanitizeChatClientLabel cleans a client-supplied device label for storage and +// echo: control characters are dropped, the length is bounded and a blank label +// becomes the generic fallback, so a transcript can always attribute a message. +func sanitizeChatClientLabel(label string) string { + var b strings.Builder + for _, r := range label { + if r < 0x20 || r == 0x7f { + continue + } + b.WriteRune(r) + } + out := strings.TrimSpace(b.String()) + if len(out) > chatClientLabelMax { + out = strings.TrimSpace(out[:chatClientLabelMax]) + } + if out == "" { + return chatClientLabelFallback + } + return out +} + +// permissionRefusal explains why a second answer to an already-answered request +// is refused, naming the client that won so the operator sees what happened. +func permissionRefusal(prior *chatResolution, requestID string) string { + if prior == nil { + return "permission request " + requestID + " is already resolved" + } + if prior.answered { + return fmt.Sprintf("permission request %s was already answered by %s", requestID, prior.client) + } + return fmt.Sprintf("permission request %s is already being answered by %s", requestID, prior.client) +} diff --git a/internal/server/chat_sessions.go b/internal/server/chat_sessions.go index 4a0d034c..17443cf5 100644 --- a/internal/server/chat_sessions.go +++ b/internal/server/chat_sessions.go @@ -17,15 +17,15 @@ import ( // fixed list bounds. const operatorDirectoryLimit = 8 -// handleChatSessions answers chat_sessions with the operator's own sessions, -// marking any another client currently holds as Busy. The registry is the single -// source of truth for which sessions are listed and for their directory, tag, -// created/recency, so a pipeline stage session (recorded in run_steps, never in -// the operator registry) is always excluded and a session with no recorded tag -// is never listed. FAIL-CLOSED: when no registry is configured the result is -// empty, never the whole endpoint list. broker.Sessions is called at most once -// per request, and the registry once. -func handleChatSessions(ctx context.Context, request protocol.Message, broker chatBroker, hub *chatHub, registry operatorRegistry, clientID string, write func(protocol.Message) error) { +// handleChatSessions answers chat_sessions with the operator's own sessions. The +// registry is the single source of truth for which sessions are listed and for +// their directory, tag, created/recency, so a pipeline stage session (recorded +// in run_steps, never in the operator registry) is always excluded and a session +// with no recorded tag is never listed. FAIL-CLOSED: when no registry is +// configured the result is empty, never the whole endpoint list. broker.Sessions +// is called at most once per request, and the registry once. A session is never +// marked Busy: any number of clients may watch and write one session. +func handleChatSessions(ctx context.Context, request protocol.Message, broker chatBroker, hub *chatHub, registry operatorRegistry, write func(protocol.Message) error) { if broker == nil { _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "chat is not configured on this server"}) return @@ -74,7 +74,6 @@ func handleChatSessions(ctx context.Context, request protocol.Message, broker ch session.Tag = operator.Tag session.CreatedAt = operator.CreatedAt session.UpdatedAt = operator.UpdatedAt - session.Busy = hub.busyForOther(operator.ID, clientID) response.ChatSessions = append(response.ChatSessions, session) } _ = write(response) diff --git a/internal/server/chat_stream.go b/internal/server/chat_stream.go index 52d52d43..da9f9cb3 100644 --- a/internal/server/chat_stream.go +++ b/internal/server/chat_stream.go @@ -2,10 +2,7 @@ package server import ( "context" - "errors" - "log" "strings" - "sync" "time" "git.a-wan.net/alan/pipelines/internal/opencode" @@ -14,10 +11,16 @@ import ( // chatPermissionPollInterval is the fixed interval between permission polls: one // GET per poll through the shared Connection bounds, never a busy loop. The first -// poll runs immediately so a request pending when the prompt is sent is surfaced +// poll runs immediately so a request pending when a turn starts is surfaced // without waiting a full interval. const chatPermissionPollInterval = 2 * time.Second +// handleChatPrompt accepts a prompt from any client. It never rejects a prompt +// because another client is watching the session: the client attaches to the +// session's shared room and the prompt either starts a turn or is queued behind +// the one in flight, with the ack saying which. The prompt is echoed live to +// every other client, attributed to the sending device's label, and the turn's +// output is fanned out to all of them. func handleChatPrompt(ctx context.Context, request protocol.Message, broker chatBroker, hub *chatHub, registry operatorRegistry, clientID string, write func(protocol.Message) error) { if broker == nil { _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "chat is not configured on this server"}) @@ -42,170 +45,78 @@ func handleChatPrompt(ctx context.Context, request protocol.Message, broker chat _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "chat prompt exceeds 64 KiB"}) return } - // Claim the session before subscribing or prompting: a second client must be - // rejected here, before any broker call, so two clients cannot silently write - // the same conversation. The same client may re-prompt its own session. sessionID := prompt.SessionID - if !hub.claim(sessionID, clientID) { - _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "session " + sessionID + " is busy with another client"}) + sub := hub.attach(sessionID, clientID, sanitizeChatClientLabel(prompt.Client), broker, write) + if sub == nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "could not attach to session " + sessionID}) return } - - // Subscribe to the OpenCode firehose before posting the prompt: the stream - // has no replay cursor (research 2.4), so a delta emitted between the POST - // and the subscription would otherwise be lost. Frames that arrive before the - // ack is written are buffered and flushed in order after it. - streamCtx, streamCancel := context.WithCancel(ctx) - attached := make(chan struct{}) - var attachOnce sync.Once - streamResult := make(chan error, 1) - var bufferMu sync.Mutex - buffering := true - var buffered []protocol.ChatEventFrame - go func() { - streamResult <- broker.Stream(streamCtx, sessionID, func() { - attachOnce.Do(func() { close(attached) }) - }, func(frame protocol.ChatEventFrame) error { - bufferMu.Lock() - if buffering { - buffered = append(buffered, frame) - bufferMu.Unlock() - return nil - } - bufferMu.Unlock() - hub.apply(frame) - return write(protocol.Message{Type: protocol.ChatEvent, ChatEvent: &frame}) - }) - }() - - select { - case <-attached: - case err := <-streamResult: - streamCancel() - hub.release(sessionID, clientID) - if err != nil && ctx.Err() == nil { - _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "chat stream: " + err.Error()}) - } - return - case <-ctx.Done(): - streamCancel() - hub.release(sessionID, clientID) + // The user turn every *other* client sees, carrying the sender's label. The + // sender's own client appended it locally, so it is excluded below. + userFrame := protocol.ChatEventFrame{ + SessionID: sessionID, + MessageID: hub.nextUserMessageID(), + Kind: protocol.ChatEventUser, + Part: &protocol.ChatPart{Type: protocol.ChatPartText, ID: "usr", Text: prompt.Text}, + Client: sub.label, + } + queued, refused := hub.submitPrompt(sessionID, &chatQueuedPrompt{ + text: prompt.Text, + requestID: request.ID, + write: write, + }) + if refused { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "session " + sessionID + " already has the maximum number of prompts queued"}) return } - - if err := broker.Prompt(ctx, sessionID, prompt.Text); err != nil { - streamCancel() - hub.release(sessionID, clientID) - _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) - return + // Publish the user turn to every other client; the sender already has it. + hub.broadcastUser(userFrame, clientID) + if queued { + // The client that sent it is told the prompt is waiting for the in-flight + // turn, so it shows queued/steering instead of blocking or silently + // dropping the message. The turn runner acknowledges it once it runs, so + // clear the ack on the queued entry to avoid a second ack for the same id. + _ = write(protocol.Message{Type: protocol.ChatPrompt, ID: request.ID, ChatQueued: true}) } - // Recency is one UPDATE: it moves the operator session to the front of - // chat_sessions. A session id that is not an operator session updates no row - // and is not an error, so pipeline stage prompts are unaffected. if registry != nil { + // Recency is one UPDATE: it moves the operator session to the front of + // chat_sessions. A session id that is not an operator session updates no + // row and is not an error, so pipeline stage prompts are unaffected. if err := registry.TouchOperatorSession(ctx, sessionID); err != nil { - log.Printf("touch operator session %s: %v", sessionID, err) + // Best-effort; the turn runner also touches on delivery. + _ = err } } - // Acknowledge the accepted prompt with the echoed request id, then stream the - // reply. The prompt is sent exactly once and never re-sent on resume. - if err := write(protocol.Message{Type: protocol.ChatPrompt, ID: request.ID}); err != nil { - streamCancel() - hub.release(sessionID, clientID) +} + +// handleChatSubscribe attaches one connection to a session's shared stream so it +// receives every frame any client's turn produces, its own or another device's. +// It replays the session's still-pending approval requests, if the room holds +// any, so a device that joins late still shows the cards. +func handleChatSubscribe(request protocol.Message, broker chatBroker, hub *chatHub, clientID string, write func(protocol.Message) error) { + // The wire body of chat_subscribe is the chat_subscribe field (the app's + // subscribeRequest and docs/cli.md both use it), not the chat_query body the + // other session-scoped commands carry. + query := request.ChatSubscribe + if query == nil || !opencode.ValidSessionID(query.SessionID) { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "a valid OpenCode session id is required"}) return } - // Flush frames buffered while the prompt was accepted, then resume live - // delivery. Holding bufferMu preserves order: the stream goroutine either - // buffered before this flush or waits and writes after it. - bufferMu.Lock() - buffering = false - pending := buffered - buffered = nil - for _, frame := range pending { - hub.apply(frame) - if err := write(protocol.Message{Type: protocol.ChatEvent, ChatEvent: &frame}); err != nil { - bufferMu.Unlock() - streamCancel() - hub.release(sessionID, clientID) - return - } + if broker == nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "chat is not configured on this server"}) + return } - bufferMu.Unlock() - go drainChatStream(ctx, streamResult, streamCancel, hub, sessionID, clientID, write) - // Poll for pending approval requests alongside the event stream, sharing - // streamCtx so the poller stops when the stream ends or the client - // disconnects. The first poll runs immediately. - go pollChatPermissions(streamCtx, broker, hub, sessionID, write) -} - -// pollChatPermissions polls the broker's pending-approval list on a fixed -// interval, sharing the chat subscription's context so it stops on disconnect or -// when the turn's stream ends. The hub dedups the request ids, so each pending -// request is pushed at most once; a poll failure is surfaced once through the -// same write closure instead of staying silent. A backend that does not expose -// the approval surface (opencode.ErrPermissionUnsupported) stops the poller -// quietly, so the documented limitation is not reported as a per-prompt error. -func pollChatPermissions(ctx context.Context, broker chatBroker, hub *chatHub, sessionID string, write func(protocol.Message) error) { - ticker := time.NewTicker(chatPermissionPollInterval) - defer ticker.Stop() - reported := false - for { - if err := pushChatPermissions(ctx, broker, hub, sessionID, write); err != nil { - if ctx.Err() != nil { - return - } - if errors.Is(err, opencode.ErrPermissionUnsupported) { - log.Printf("chat permission poll session=%s: %v", sessionID, err) - return - } - if reported { - log.Printf("chat permission poll session=%s: %v", sessionID, err) - } else { - reported = true - _ = write(protocol.Message{Type: protocol.Error, Error: "chat permission poll: " + err.Error()}) - } - } - select { - case <-ctx.Done(): - return - case <-ticker.C: - } - } -} - -// pushChatPermissions performs one poll and writes a chat_permission frame for -// every newly seen request of the session, through the same connection-scoped -// write closure as the chat stream. It never re-pushes a request id, and releases -// the reservation on a write failure so the frame is not silently dropped. -func pushChatPermissions(ctx context.Context, broker chatBroker, hub *chatHub, sessionID string, write func(protocol.Message) error) error { - pending, err := broker.Permissions(ctx, sessionID) - if err != nil { - return err - } - for _, request := range pending { - if request.SessionID != sessionID || request.RequestID == "" { - continue - } - if !hub.seenPermission(sessionID, request.RequestID) { - continue - } - frame := request - if err := write(protocol.Message{Type: protocol.ChatPermission, ChatPermission: &frame}); err != nil { - hub.forgetPermission(sessionID, request.RequestID) - return err - } - } - return nil -} - -// drainChatStream reports the terminal error of a chat subscription and releases -// its context and the session claim once the stream has ended, so a later client -// is no longer blocked and nothing leaks. -func drainChatStream(ctx context.Context, result <-chan error, cancel context.CancelFunc, hub *chatHub, sessionID, clientID string, write func(protocol.Message) error) { - defer cancel() - defer hub.release(sessionID, clientID) - if err := <-result; err != nil && ctx.Err() == nil { - log.Printf("chat stream session=%s: %v", sessionID, err) - _ = write(protocol.Message{Type: protocol.Error, Error: "chat stream: " + err.Error()}) + sub := hub.attach(query.SessionID, clientID, "", broker, write) + if sub == nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "could not attach to session " + query.SessionID}) + return + } + _ = write(protocol.Message{Type: protocol.ChatSubscribe, ID: request.ID}) + // Replay every still-unresolved approval request the room holds, not only the + // most recent one, so a client that attaches after two requests were raised + // still sees both cards. + for _, pending := range hub.pendingFrames(query.SessionID) { + frame := pending + sub.send(protocol.Message{Type: protocol.ChatPermission, ChatPermission: &frame}) } } diff --git a/internal/server/chat_test.go b/internal/server/chat_test.go index 7c11801e..1dd43b36 100644 --- a/internal/server/chat_test.go +++ b/internal/server/chat_test.go @@ -436,10 +436,18 @@ func TestChatMessagesResumesRetainedState(t *testing.T) { if err := wsjson.Read(ctx, conn, &response); err != nil { t.Fatal(err) } - if response.Type != protocol.ChatMessages || response.ID != "r2" || len(response.ChatMessages) != 1 { + if response.Type != protocol.ChatMessages || response.ID != "r2" || len(response.ChatMessages) != 2 { t.Fatalf("resume response = %+v", response) } - message := response.ChatMessages[0] + // The prompt is retained as a user turn and the assistant reply beside it, so + // a reconnecting client re-syncs a conversation that still says who sent + // what. The user turn carries the sending client's label (the generic + // fallback when the prompt did not name one). + user := response.ChatMessages[0] + if user.Role != protocol.ChatRoleUser || len(user.Parts) != 1 || user.Parts[0].Type != protocol.ChatPartText || user.Parts[0].Text != "hi" || user.Client != chatClientLabelFallback { + t.Fatalf("resumed user turn = %+v", user) + } + message := response.ChatMessages[1] if message.ID != "msg_1" || message.Role != protocol.ChatRoleAssistant || len(message.Parts) != 2 { t.Fatalf("resumed message = %+v", message) } @@ -1361,88 +1369,6 @@ func TestChatSessionsFailsClosedWithoutOwnership(t *testing.T) { } } -// TestChatSessionsBusyRejectsSecondClient is the task evidence for busy state: -// while client A holds ses_1 with a blocking prompt, client B's chat_sessions -// reports ses_1 Busy=true and B's chat_prompt for ses_1 is rejected before any -// broker.Prompt call; after A disconnects the claim is released and a later list -// is no longer busy. -func TestChatSessionsBusyRejectsSecondClient(t *testing.T) { - ctx := context.Background() - store := newOperatorStore(t) - if err := store.RecordOperatorSession(ctx, "ses_1", "/work", "operator chat", protocol.ChatSessionTagOperator); err != nil { - t.Fatal(err) - } - broker := scriptedChat() - broker.block = true - broker.done = make(chan struct{}) - broker.sessions = []protocol.ChatSession{{ID: "ses_1"}} - ctx, _, conns := dialChatConns(t, Options{Chat: broker, OperatorRegistry: store}, 2) - connA, connB := conns[0], conns[1] - - if err := wsjson.Write(ctx, connA, protocol.Message{Type: protocol.ChatPrompt, ID: "a1", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "hi"}}); err != nil { - t.Fatal(err) - } - var ack protocol.Message - if err := wsjson.Read(ctx, connA, &ack); err != nil { - t.Fatal(err) - } - if ack.Type != protocol.ChatPrompt || ack.ID != "a1" { - t.Fatalf("prompt ack = %+v", ack) - } - - if err := wsjson.Write(ctx, connB, protocol.Message{Type: protocol.ChatSessions, ID: "b1"}); err != nil { - t.Fatal(err) - } - var listing protocol.Message - if err := wsjson.Read(ctx, connB, &listing); err != nil { - t.Fatal(err) - } - if listing.Type != protocol.ChatSessions || len(listing.ChatSessions) != 1 || !listing.ChatSessions[0].Busy { - t.Fatalf("held session not marked busy: %+v", listing) - } - - if err := wsjson.Write(ctx, connB, protocol.Message{Type: protocol.ChatPrompt, ID: "b2", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "hello"}}); err != nil { - t.Fatal(err) - } - var rejected protocol.Message - if err := wsjson.Read(ctx, connB, &rejected); err != nil { - t.Fatal(err) - } - if rejected.Type != protocol.Error || !strings.Contains(rejected.Error, "busy") { - t.Fatalf("second client's prompt was not rejected as busy: %+v", rejected) - } - if prompts, _, _ := broker.counts(); prompts != 1 { - t.Fatalf("busy prompt reached OpenCode: %d prompt calls, want 1", prompts) - } - - // Disconnecting A releases the claim so a later client is no longer blocked. - if err := connA.Close(websocket.StatusNormalClosure, ""); err != nil { - t.Fatal(err) - } - select { - case <-broker.done: - case <-time.After(5 * time.Second): - t.Fatal("stream did not stop after disconnect") - } - deadline := time.Now().Add(5 * time.Second) - for { - if err := wsjson.Write(ctx, connB, protocol.Message{Type: protocol.ChatSessions, ID: "b3"}); err != nil { - t.Fatal(err) - } - var after protocol.Message - if err := wsjson.Read(ctx, connB, &after); err != nil { - t.Fatal(err) - } - if after.Type == protocol.ChatSessions && len(after.ChatSessions) == 1 && !after.ChatSessions[0].Busy { - return - } - if time.Now().After(deadline) { - t.Fatalf("claim not released after disconnect: %+v", after) - } - time.Sleep(10 * time.Millisecond) - } -} - // TestChatPromptPushesPermissionAndForwardsReply is the task evidence: with a // blocking scripted stream keeping the subscription open, a seeded pending // approval request is pushed as a chat_permission frame carrying the seeded @@ -1522,11 +1448,29 @@ func TestChatPermissionDedupesRepeatedPolls(t *testing.T) { mu.Unlock() return nil } + if sub := hub.attach("ses_1", "c1", "phone", broker, write); sub == nil { + t.Fatal("attach returned nil") + } for i := 0; i < 3; i++ { - if err := pushChatPermissions(context.Background(), broker, hub, "ses_1", write); err != nil { + if err := hub.pollPermissionsOnce(context.Background(), broker, "ses_1"); err != nil { t.Fatal(err) } } + deadline := time.Now().Add(2 * time.Second) + for { + mu.Lock() + count := len(pushed) + mu.Unlock() + if count > 0 { + break + } + if time.Now().After(deadline) { + t.Fatal("no permission frame was pushed") + } + time.Sleep(5 * time.Millisecond) + } + // Give a duplicate a chance to arrive before asserting there is none. + time.Sleep(50 * time.Millisecond) mu.Lock() defer mu.Unlock() if len(pushed) != 1 { @@ -1684,32 +1628,6 @@ func TestChatPermissionUnsupportedBackendIsQuiet(t *testing.T) { } } -// TestChatPermissionWriteFailureDoesNotDropRequest pins that a request id is not -// retained as "seen" when its frame could not be written, so the next poll -// re-pushes it instead of silently dropping the approval request. -func TestChatPermissionWriteFailureDoesNotDropRequest(t *testing.T) { - broker := scriptedChat() - broker.permissions = []protocol.ChatPermissionFrame{{SessionID: "ses_1", RequestID: "req_1", Action: "bash"}} - hub := newChatHub() - attempts := 0 - write := func(protocol.Message) error { - attempts++ - if attempts == 1 { - return fmt.Errorf("connection closed") - } - return nil - } - if err := pushChatPermissions(context.Background(), broker, hub, "ses_1", write); err == nil { - t.Fatal("a failed write must surface an error") - } - if err := pushChatPermissions(context.Background(), broker, hub, "ses_1", write); err != nil { - t.Fatalf("retry after a failed write: %v", err) - } - if attempts != 2 { - t.Fatalf("push attempts = %d, want the request re-pushed after the failure", attempts) - } -} - // TestChatAdoptRecordsEndpointSession is the chat_adopt acceptance test: the // endpoint's own record supplies the directory and title, the handler records // the row with the operator tag, and the response echoes the session and its diff --git a/internal/server/websocket.go b/internal/server/websocket.go index 9d3d076a..8ee03ef2 100644 --- a/internal/server/websocket.go +++ b/internal/server/websocket.go @@ -86,6 +86,8 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin if registry == nil && len(stores) > 0 { registry = stores[0] } + hub.baseCtx = ctx + hub.registry = registry mux.HandleFunc("GET /artifacts/{run}/{step}/{name...}", func(w http.ResponseWriter, r *http.Request) { if runs == nil { http.NotFound(w, r) @@ -139,6 +141,9 @@ func HandlerWithOptions(ctx context.Context, options Options, stores ...*pipelin // Drop every run subscription this connection holds when the read loop // returns, so no subscriber, goroutine or timer outlives the connection. defer events.unsubscribeClient(clientID) + // Drop every chat subscription too, so a chat room held only by this + // connection releases its broker stream and turn runner. + defer hub.detachClient(clientID) if len(stores) > 0 { items, err := stores[0].List(ctx) if err != nil { From 986a62b09f5b26994f943f96c5d3b96c541ec716 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sat, 17 Oct 2026 03:29:10 +0100 Subject: [PATCH 7/9] android: add omni-search type icons with a kind filter and sorting The search results panel replaces each row's text type badge (LabelChip, removed) with a glyph derived from the result kind and, for an artifact, from its content type. The artifact branch reuses the gallery's own artifactKind/artifactIcon mapping in ui/graph/ArtifactType.kt instead of a second table, and the glyph's contentDescription carries the kind in words so a screen reader hears what the icon cannot show. The panel's header gains the runs list's FilterMenu and SortMenu: a kind filter (All kinds, Pipelines, Runs, Steps, Fields, Artifacts, Versions) that sends the server's SearchRequest.kind verbatim, and Relevance / Newest / Name sorting. The server's search takes no sort, so Newest and Name order the results in hand and say so ("Sort results in hand", the collapsed summary's "(in hand)"); no Prompts option is offered because the server's search kinds cannot produce one. The chosen kind and order persist via SettingsRepository, surviving query changes and streaming. Tests: OmniSearchResultsTest covers the per-kind and per-content-type glyph (checked against the gallery mapping), the kind label, filter narrowing, Relevance/Newest/Name ordering with ties, and the empty-state line; ArtifactTypeTest covers artifactKindLabel. Checked before committing: - Packaged templates: none describes the app's search panel; unchanged. - README/topic docs: android/README.md gains the "Search type icons, a kind filter and sorting" section; docs/cli.md and docs/ui-ux-review.md describe only the TUI/server search, so they stay accurate and are unchanged. - Packaged authoring skill references: internal/author/skill/references/ contains no Android search-panel documentation (operations.md's "omni search" is the TUI), so none needs updating; install.go's inventory is untouched. Evidence: gradle :app:testDebugUnitTest --rerun 433 tests 0 failures; :app:assembleDebug successful, APK published to the run artifacts; the API-27 NewApi lint errors are pre-existing and unrelated. (cherry picked from commit b808158d499912e09872c31b5259205ee6cd8838) --- android/README.md | 86 +++++++ .../pipelines/data/PipelinesRepository.kt | 12 +- .../awan/pipelines/data/SettingsRepository.kt | 19 ++ .../net/awan/pipelines/ui/AppViewModel.kt | 30 ++- .../awan/pipelines/ui/OmniSearchResults.kt | 180 +++++++++++++-- .../net/awan/pipelines/ui/PipelinesApp.kt | 8 +- .../awan/pipelines/ui/SearchResultsPanel.kt | 109 +++++++-- .../pipelines/ui/components/FilterMenu.kt | 2 +- .../awan/pipelines/ui/components/LabelChip.kt | 31 --- .../awan/pipelines/ui/components/SortMenu.kt | 6 +- .../awan/pipelines/ui/graph/ArtifactType.kt | 20 ++ .../pipelines/ui/OmniSearchResultsTest.kt | 213 ++++++++++++++++-- .../pipelines/ui/graph/ArtifactTypeTest.kt | 13 ++ 13 files changed, 629 insertions(+), 100 deletions(-) delete mode 100644 android/app/src/main/java/net/awan/pipelines/ui/components/LabelChip.kt diff --git a/android/README.md b/android/README.md index f7845240..39189cc4 100644 --- a/android/README.md +++ b/android/README.md @@ -4424,6 +4424,92 @@ and a selection navigating (the visual review owns the device, per the brief's device policy); the panel's pure logic is exercised by the unit tests and the compile only. +## Search type icons, a kind filter and sorting (17 Oct 2026) + +The omni-search results panel replaces each row's text type badge with a glyph and +gains the runs list's filter and sort controls. `android/` only; no new dependency +(the glyphs and the `FilterList`/`Sort` menu icons are from the already-declared +`material-icons-extended`), no Pipelines server/Go/installer/Docker file touched, +no run started from the app, and the operator's phone was never used. + +- **Type glyph per result.** `OmniSearchResults.searchResultIcon` maps a hit to a + glyph: pipeline → the app's pipeline icon (`AccountTree`), run → `History`, + version → `Commit`, step → `Segment`, field → `Subject` (text lines, distinct + from the gallery's `Description` document glyph), and an unknown kind → + `HelpOutline`. An artifact reuses the gallery's own + classification (`artifactKind`/`artifactIcon` in `ui/graph/ArtifactType.kt`) + rather than a second mapping, so a search artifact and a gallery tile never + disagree. The glyph replaces the `LabelChip` badge (the chip is removed); the + payload decides the branch exactly as `searchRow` does. +- **Kind in words.** The glyph's `contentDescription` is `searchResultKindLabel` + ("Pipeline", "Run", "Pipeline version", "Step", "Field", or " + artifact", e.g. "PDF artifact" via the new `artifactKindLabel`), so a screen + reader hears the type the icon alone cannot carry. The row and the filter use + the same kind vocabulary ("Fields"). +- **Kind filter, narrowing server-side.** `SearchKindFilter` lists the filter + options - All kinds, Pipelines, Runs, Steps, Fields, Artifacts, Versions - and + each carries the server's own `SearchRequest.kind` value, sent verbatim + (`PipelinesRepository.search(query, kind)`). There is deliberately no "Prompts" + option: the server's search kinds are pipeline/version/run/step/field/artifact + only (`internal/protocol/search.go`), so a prompts filter could never match and + would visibly do nothing. +- **Sort, honest about its reach.** `SearchSort` offers Relevance (the server's + own score/recency/tie-break order, left untouched), Newest first (by `recency`) + and Name (by the displayed title). The server's search command takes no sort, so + Newest and Name order the results already in hand; the sort menu carries a + "Sort results in hand" caption, the collapsed summary appends " (in hand)" for + those two orders, and the icon's description reads "Sort results in hand". A + server-side sort would need a `sort` field on `SearchRequest`/the search + command. +- **Shared controls, remembered choice.** The panel header uses the same + `FilterMenu` and `SortMenu` the runs list uses (no new pattern), plus a one-line + `searchControlsSummary` ("All kinds · Relevance") so the collapsed controls show + the active choice. The header row carries a top inset so the filter's count badge + stays inside the panel's rounded surface. The kind and order persist as `search_filter_kind`/ + `search_sort` in `SettingsRepository`, so they survive a query change, the + results streaming in, and a restart. +- **Tests.** `OmniSearchResultsTest` now covers the glyph per kind and per + artifact content type (checked against the gallery's + `artifactIcon(artifactKind(...))`), the kind-in-words label, the kind filter + narrowing a mixed list, the Relevance/Newest/Name ordering including a recency + tie and a title tie, the in-hand summary suffix, the filter-aware empty-state + line (`searchPanelEmptyMessage`, which replaced the panel's now-orphaned + `isEmptyResult` and names the active kind filter), and the stored-value + fallbacks; `ArtifactTypeTest` covers `artifactKindLabel`. + +Evidence (macOS, JDK 17 from Homebrew `openjdk@17`, +`ANDROID_HOME=/Users/alan/Library/Android/sdk`, Gradle 8.11.1 from the wrapper +cache, every command `--no-daemon --offline --console=plain`; this build includes +the visual-review fixes: the header's badge inset, the visible in-hand sort +caption/summary, and the consistent "Field" vocabulary with a distinct glyph): + +- `gradle :app:testDebugUnitTest --rerun` → `BUILD SUCCESSFUL`; the 47 result XMLs + aggregate to **433 tests, 0 failures, 0 errors, 0 skipped** + (`OmniSearchResultsTest` 28, `ArtifactTypeTest` 7). +- `gradle :app:assembleDebug` → `BUILD SUCCESSFUL`; + `app/build/outputs/apk/debug/app-debug.apk` is **18,715,466 bytes**, sha256 + `f4cee0d4949ac587601f01a96733b3d865431bd5376ac6d7d182222a40999bf5`. +- **APK publish.** Copied to + `~/.local/share/pipelines/data/artifacts/231/4/pipelines-debug-wip-f31f150.apk` + (`f31f150` = `git rev-parse --short HEAD`). The LAN URL + `http://10.0.0.75:8080/artifacts/231/4/pipelines-debug-wip-f31f150.apk` returned + `HTTP/1.1 200 OK`, `Content-Type: application/vnd.android.package-archive`, + `Content-Length: 18715466`, and the downloaded bytes' sha256 + `f4cee0d4949ac587601f01a96733b3d865431bd5376ac6d7d182222a40999bf5` matched the + local file. +- `gradle :app:lintDebug` fails on two pre-existing `NewApi` errors + (`res/values{,-night}/themes.xml`: `windowLightNavigationBar` requires API 27, + min is 26), unrelated to and not introduced by this change; the report names no + file touched by this change. +- No packaged template and no packaged authoring skill reference + (`internal/author/skill/references/*`, `internal/author/install.go`'s inventory) + documents the app's search panel - the only "omni search" reference describes + the TUI - so none needed updating. + +Not verified in this pass: device frames of the panel and the open controls (the +visual review owns the device, per the brief's device policy); the pure logic is +exercised by the unit tests and the compile only. + ## Chat destination and multiple conversations (16 Oct 2026) The first Chat slice: the destination, the server session list and several diff --git a/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt b/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt index a06126ef..6feff8ec 100644 --- a/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt +++ b/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt @@ -174,13 +174,13 @@ class PipelinesRepository( /** * Sends one omni-search query over the shared transport and returns the raw - * reply envelope. The server command is still landing, so the reply is - * classified by its envelope type: [Protocol.SEARCH_RESULTS] is the accepted - * search, and any other type is an unexpected reply the caller reports rather - * than parsing. The typed result payload is added with the results item. + * reply envelope. [kind] narrows the server-side scan to one SearchKind (see + * SearchKindFilter); a blank kind searches every kind. The reply is classified + * by its envelope type: [Protocol.SEARCH_RESULTS] is the accepted search, and + * any other type is an unexpected reply the caller reports rather than parsing. */ - suspend fun search(query: String): Message = - client.call(Message(type = Protocol.SEARCH, search = SearchRequest(query = query.trim()))) + suspend fun search(query: String, kind: String = ""): Message = + client.call(Message(type = Protocol.SEARCH, search = SearchRequest(query = query.trim(), kind = kind))) /** Fetches an artifact's bytes (image preview) over the shared HTTP client. */ suspend fun fetchArtifactBytes(url: String): ByteArray = client.fetchBytes(url) diff --git a/android/app/src/main/java/net/awan/pipelines/data/SettingsRepository.kt b/android/app/src/main/java/net/awan/pipelines/data/SettingsRepository.kt index 7daffe17..49164171 100644 --- a/android/app/src/main/java/net/awan/pipelines/data/SettingsRepository.kt +++ b/android/app/src/main/java/net/awan/pipelines/data/SettingsRepository.kt @@ -77,6 +77,13 @@ class SettingsRepository(context: Context) { private val _notificationPermissionAsked = MutableStateFlow(prefs.getBoolean(KEY_NOTIFICATION_PERMISSION_ASKED, false)) val notificationPermissionAsked: StateFlow = _notificationPermissionAsked.asStateFlow() + // The omni-search kind narrowing (a server kind, "" = every kind) and the + // search order, stored as their stable values and resolved by the UI. + private val _searchFilterKind = MutableStateFlow(prefs.getString(KEY_SEARCH_FILTER_KIND, "").orEmpty()) + val searchFilterKind: StateFlow = _searchFilterKind.asStateFlow() + + private val _searchSort = MutableStateFlow(prefs.getString(KEY_SEARCH_SORT, "").orEmpty()) + val searchSort: StateFlow = _searchSort.asStateFlow() fun setServerUrl(value: String) { val trimmed = value.trim() @@ -155,6 +162,16 @@ class SettingsRepository(context: Context) { prefs.edit().putBoolean(KEY_NOTIFICATION_PERMISSION_ASKED, asked).apply() } + fun setSearchFilterKind(value: String) { + _searchFilterKind.value = value + prefs.edit().putString(KEY_SEARCH_FILTER_KIND, value).apply() + } + + fun setSearchSort(value: String) { + _searchSort.value = value + prefs.edit().putString(KEY_SEARCH_SORT, value).apply() + } + /** True only when the user has explicitly supplied both required values. */ fun isConfigured(): Boolean = _serverUrl.value.isNotBlank() && _workspace.value.isNotBlank() @@ -173,5 +190,7 @@ class SettingsRepository(context: Context) { const val KEY_CHAT_SEEN = "chat_seen" const val KEY_ATTENTION = "attention" const val KEY_NOTIFICATION_PERMISSION_ASKED = "notification_permission_asked" + const val KEY_SEARCH_FILTER_KIND = "search_filter_kind" + const val KEY_SEARCH_SORT = "search_sort" } } diff --git a/android/app/src/main/java/net/awan/pipelines/ui/AppViewModel.kt b/android/app/src/main/java/net/awan/pipelines/ui/AppViewModel.kt index d338999a..dafe2157 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/AppViewModel.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/AppViewModel.kt @@ -83,6 +83,10 @@ class AppViewModel( val pipelineFilterRunStatuses: StateFlow = settings.pipelineFilterRunStatuses val pipelineFilterName: StateFlow = settings.pipelineFilterName + /** The stored omni-search kind narrowing (a server kind, "" = every kind) and order. */ + val searchKind: StateFlow = settings.searchFilterKind + val searchSort: StateFlow = settings.searchSort + private val _serverUrlDraft = MutableStateFlow(settings.serverUrl.value) val serverUrlDraft: StateFlow = _serverUrlDraft.asStateFlow() @@ -685,6 +689,19 @@ class AppViewModel( fun setPipelineFilterName(value: String) = settings.setPipelineFilterName(value) + /** + * Narrows the search to a server kind (see SearchKindFilter). The kind is a + * request parameter, so a narrowed search re-issues the live query at once + * rather than waiting for the next keystroke. + */ + fun setSearchKind(serverKind: String) { + settings.setSearchFilterKind(serverKind) + rerunSearchImmediately() + } + + /** Records the search order; it orders the results already in hand, so no refetch. */ + fun setSearchSort(storageKey: String) = settings.setSearchSort(storageKey) + private fun awaitConnected() { viewModelScope.launch { val connected = withTimeoutOrNull(CONNECT_TIMEOUT_MILLIS) { @@ -803,7 +820,13 @@ class AppViewModel( } /** Runs the current query immediately (the IME's search action), skipping the debounce. */ - fun searchNow() { + fun searchNow() = rerunSearchImmediately() + + /** + * Re-issues the live query at once, cancelling any pending debounce: the IME + * search action and a kind-filter change both want the newest request now. + */ + private fun rerunSearchImmediately() { val query = _search.value.query if (query.isBlank()) return val edit = searchSequencer.edit(query) @@ -821,7 +844,10 @@ class AppViewModel( private suspend fun runSearch(request: SentSearch) { _search.value = _search.value.copy(loading = true, error = null) try { - val reply = repository.search(request.query) + // The active kind filter is a request parameter; resolve it from the + // stored value (a blank/stale one falls back to every kind). + val kind = SearchKindFilter.fromStorage(settings.searchFilterKind.value).serverKind + val reply = repository.search(request.query, kind) // A reply for a superseded query must never land: the sequencer only // accepts the newest sent token. if (!searchSequencer.accepts(request.token)) return diff --git a/android/app/src/main/java/net/awan/pipelines/ui/OmniSearchResults.kt b/android/app/src/main/java/net/awan/pipelines/ui/OmniSearchResults.kt index 2533772c..2bbc9553 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/OmniSearchResults.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/OmniSearchResults.kt @@ -1,6 +1,15 @@ package net.awan.pipelines.ui +import androidx.compose.material.icons.Icons +import androidx.compose.material.icons.automirrored.filled.HelpOutline +import androidx.compose.material.icons.automirrored.filled.Segment +import androidx.compose.material.icons.automirrored.filled.Subject +import androidx.compose.material.icons.filled.AccountTree +import androidx.compose.material.icons.filled.Commit +import androidx.compose.material.icons.filled.History import androidx.compose.runtime.Immutable +import androidx.compose.ui.graphics.vector.ImageVector +import java.time.OffsetDateTime import net.awan.pipelines.data.protocol.Protocol import net.awan.pipelines.data.protocol.RunStep import net.awan.pipelines.data.protocol.SearchArtifact @@ -11,22 +20,50 @@ import net.awan.pipelines.data.protocol.SearchResult import net.awan.pipelines.data.protocol.SearchRun import net.awan.pipelines.data.protocol.SearchStep import net.awan.pipelines.data.protocol.SearchVersion +import net.awan.pipelines.ui.graph.artifactIcon +import net.awan.pipelines.ui.graph.artifactKind +import net.awan.pipelines.ui.graph.artifactKindLabel import net.awan.pipelines.ui.screens.runTimeline // --------------------------------------------------------------------------- -// Row model: the badge, title and secondary line of one result. Pure (no +// Row model: the glyph, title and secondary line of one result. Pure (no // Compose, no coroutines), so the mapping for every kind is unit-testable. // --------------------------------------------------------------------------- -/** The short mixed-list type badge for a result kind. */ -fun searchBadge(kind: String): String = when (kind) { - Protocol.SEARCH_KIND_PIPELINE, Protocol.SEARCH_KIND_VERSION -> "pipeline" - Protocol.SEARCH_KIND_RUN -> "run" - Protocol.SEARCH_KIND_STEP -> "step" - Protocol.SEARCH_KIND_ARTIFACT -> "artifact" - // A text ("field") match and an unknown kind both read as a generic match; - // the unknown one is additionally labelled read-only by [searchRow]. - else -> "match" +/** + * The glyph that names one result's type at a glance: the result's kind, and for + * an artifact the file type its content resolves to. The artifact mapping is the + * gallery's own ([artifactKind]/[artifactIcon]) rather than a second copy, so the + * two surfaces can never disagree about a file. The payload decides the branch, + * exactly as [searchRow] does, so a known payload with an unknown kind string + * still gets the right glyph and an unrecognised result falls back to a neutral + * mark instead of vanishing. + */ +fun searchResultIcon(hit: SearchResult): ImageVector = when { + hit.pipeline != null -> Icons.Filled.AccountTree + hit.version != null -> Icons.Filled.Commit + hit.run != null -> Icons.Filled.History + hit.step != null -> Icons.AutoMirrored.Filled.Segment + hit.field != null -> Icons.AutoMirrored.Filled.Subject + hit.artifact != null -> artifactIcon(artifactKind(hit.artifact.contentType, hit.artifact.name)) + else -> Icons.AutoMirrored.Filled.HelpOutline +} + +/** + * The kind in words for a row's accessible description, so a screen reader hears + * what the row is even though the glyph alone carries no text. An artifact is + * named by its own content type ("Image artifact", "JSON artifact"), from the + * same gallery classification [searchResultIcon] uses. + */ +fun searchResultKindLabel(hit: SearchResult): String = when { + hit.pipeline != null -> "Pipeline" + hit.version != null -> "Pipeline version" + hit.run != null -> "Run" + hit.step != null -> "Step" + hit.field != null -> "Field" + hit.artifact != null -> + "${artifactKindLabel(artifactKind(hit.artifact.contentType, hit.artifact.name))} artifact" + else -> "Unrecognised result" } /** @@ -38,13 +75,12 @@ fun searchBadge(kind: String): String = when (kind) { data class SnippetSpan(val text: String, val matched: Boolean) /** - * One rendered search row: its type badge, a title and a secondary line. [snippet] - * is non-null only for a text ("field") match and carries the snippet split so the - * matched span is distinguishable without colour. + * One rendered search row: its title and a secondary line. [snippet] is non-null + * only for a text ("field") match and carries the snippet split so the matched + * span is distinguishable without colour. */ @Immutable data class SearchRow( - val badge: String, val title: String, val secondary: String, val snippet: List? = null, @@ -56,7 +92,6 @@ data class SearchRow( * renders its stable target (or a placeholder) and a `read-only` note. */ fun searchRow(hit: SearchResult, query: String): SearchRow { - val badge = searchBadge(hit.kind) val pipeline: SearchPipeline? = hit.pipeline val version: SearchVersion? = hit.version val run: SearchRun? = hit.run @@ -65,12 +100,10 @@ fun searchRow(hit: SearchResult, query: String): SearchRow { val artifact: SearchArtifact? = hit.artifact return when { pipeline != null -> SearchRow( - badge, pipeline.name.ifBlank { "pipeline ${pipeline.id}" }, "pipeline ${pipeline.id} · v${pipeline.version} · ${stageCountText(pipeline.stages)}", ) version != null -> SearchRow( - badge, "pipeline ${version.pipelineId} · v${version.version}", listOfNotNull( version.contentHash.takeIf { it.isNotBlank() }?.let { "content $it" }, @@ -78,7 +111,6 @@ fun searchRow(hit: SearchResult, query: String): SearchRow { ).joinToString(" · "), ) run != null -> SearchRow( - badge, "run #${run.id}" + run.pipelineName.takeIf { it.isNotBlank() }?.let { " · $it" }.orEmpty(), listOfNotNull( run.status.takeIf { it.isNotBlank() }, @@ -87,18 +119,15 @@ fun searchRow(hit: SearchResult, query: String): SearchRow { ).joinToString(" · "), ) step != null -> SearchRow( - badge, "run #${step.runId} · ${step.stage.ifBlank { "step" }} visit ${step.visit}", stepSecondary(step), ) field != null -> SearchRow( - badge, "run #${field.runId} · step ${field.sequence} · ${field.field.ifBlank { "field" }}", field.snippet, snippetSpans(field.snippet, query), ) artifact != null -> SearchRow( - badge, artifact.name.ifBlank { "artifact" }, listOfNotNull( "run #${artifact.runId}", @@ -108,7 +137,6 @@ fun searchRow(hit: SearchResult, query: String): SearchRow { ).joinToString(" · "), ) else -> SearchRow( - badge, hit.target.ifBlank { "Unrecognised result" }, if (hit.kind.isBlank()) "read-only" else "kind \"${hit.kind}\" · read-only", ) @@ -145,6 +173,92 @@ fun snippetSpans(snippet: String, query: String): List { } } +// --------------------------------------------------------------------------- +// Narrowing and ordering: the filter/sort control's pure model. Pure (no +// Compose), so the kind narrowing and each order are unit-testable. +// --------------------------------------------------------------------------- + +/** + * The kind narrowing the search filter control offers. [serverKind] is exactly the + * server's SearchRequest kind vocabulary (internal/protocol/search.go), sent and + * stored verbatim; [All] is the empty kind. + * + * There is deliberately no "prompts" entry: the server has no such kind (its + * kinds are pipeline, version, run, step, field and artifact), so a filter that + * could only ever match nothing is not offered. + */ +enum class SearchKindFilter(val label: String, val serverKind: String) { + All("All kinds", ""), + Pipelines("Pipelines", Protocol.SEARCH_KIND_PIPELINE), + Runs("Runs", Protocol.SEARCH_KIND_RUN), + Steps("Steps", Protocol.SEARCH_KIND_STEP), + Fields("Fields", Protocol.SEARCH_KIND_FIELD), + Artifacts("Artifacts", Protocol.SEARCH_KIND_ARTIFACT), + Versions("Versions", Protocol.SEARCH_KIND_VERSION); + + companion object { + val Default = All + + /** Resolves a stored kind, tolerating a blank/stale value by returning [Default]. */ + fun fromStorage(value: String?): SearchKindFilter = + entries.firstOrNull { it.serverKind == value } ?: Default + } +} + +/** + * The orders the search sort control offers. [Relevance] keeps the server's own + * ranking (score, then recency, then a stable kind/target tie-break). [Newest] + * and [Name] cannot be asked of the server - its search command takes only a + * query, an optional kind and a limit - so they order the results already in + * hand, and the control says so. + */ +enum class SearchSort(val label: String, val storageKey: String) { + Relevance("Relevance", "relevance"), + Newest("Newest first", "newest"), + Name("Name", "name"); + + companion object { + val Default = Relevance + + /** Resolves a stored order, tolerating a blank/stale value by returning [Default]. */ + fun fromStorage(value: String?): SearchSort = + entries.firstOrNull { it.storageKey == value } ?: Default + } +} + +/** The one-line summary of the active filter and sort the collapsed control shows. */ +fun searchControlsSummary(kind: SearchKindFilter, sort: SearchSort): String { + // Only Relevance is the server's own ranking; the other orders run on the + // results in hand, so the summary says so even when the menu is closed. + val reach = if (sort == SearchSort.Relevance) "" else " (in hand)" + return "${kind.label} · ${sort.label}$reach" +} + +/** + * Narrows [results] to [filter]'s kind. The filter is also sent to the server + * (SearchRequest.kind), so this only re-narrows the results already in hand, + * keeping the panel honest while a narrowed request loads. + */ +fun filterSearchResults(results: List, filter: SearchKindFilter): List = + if (filter == SearchKindFilter.All) results else results.filter { it.kind == filter.serverKind } + +/** + * Orders [results] by [sort]. [Relevance] leaves the server's ranking untouched; + * [Newest] and [Name] sort the results in hand (the server has no sort). The + * sorts are stable, so two results that tie keep the server's order rather than + * swapping arbitrarily. + */ +fun sortSearchResults(results: List, sort: SearchSort): List = when (sort) { + SearchSort.Relevance -> results + SearchSort.Newest -> results.sortedWith( + compareByDescending { parseInstant(it.recency.orEmpty()) ?: OffsetDateTime.MIN }, + ) + SearchSort.Name -> results + .map { it to searchRow(it, "").title } + .sortedWith(compareBy(String.CASE_INSENSITIVE_ORDER) { it.second }) + .map { it.first } +} + // --------------------------------------------------------------------------- // Navigation: the destination a result resolves to. Pure, so the mapping for // every kind is unit-testable. @@ -284,6 +398,22 @@ fun SearchUiState.loaded(response: SearchResponse): SearchUiState = fun SearchUiState.failed(message: String?): SearchUiState = copy(loading = false, error = message, loaded = true) -/** Whether the panel shows the explicit, query-naming empty state. */ -fun SearchUiState.isEmptyResult(): Boolean = - error == null && !loading && loaded && results.isEmpty() && query.isNotBlank() +/** + * The empty-state line the panel shows when it has no rows to render for [query] + * under [kind], or null when it is showing rows, progress or nothing at all. + * [shown] is the filtered and sorted list actually displayed, so a filter that + * empties the list reports itself ("No runs match …") rather than the generic + * line. Pure, so the empty state is unit-testable without a device. + */ +fun searchPanelEmptyMessage( + state: SearchUiState, + shown: List, + kind: SearchKindFilter, +): String? = when { + state.error != null -> null + shown.isNotEmpty() -> null + state.loading -> null + state.query.isBlank() -> null + kind == SearchKindFilter.All -> "No matches for \"${state.query}\"." + else -> "No ${kind.label.lowercase()} match \"${state.query}\"." +} diff --git a/android/app/src/main/java/net/awan/pipelines/ui/PipelinesApp.kt b/android/app/src/main/java/net/awan/pipelines/ui/PipelinesApp.kt index ae1a60d1..da010126 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/PipelinesApp.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/PipelinesApp.kt @@ -179,6 +179,8 @@ fun PipelinesApp( // the chat list for the conversation. val conversationOpen by vm.conversationOpen.collectAsStateWithLifecycle() val pillVisible = destinationPillVisible(currentRoute, conversationOpen) + val searchKind by vm.searchKind.collectAsStateWithLifecycle() + val searchSort by vm.searchSort.collectAsStateWithLifecycle() /** Back/scrim/close and a selection all dismiss the morph and clear the panel. */ val dismissSearch: () -> Unit = { @@ -376,9 +378,13 @@ fun PipelinesApp( verticalArrangement = Arrangement.Bottom, horizontalAlignment = Alignment.End, ) { - if (searchState.open && searchState.query.isNotBlank()) { + if (searchState.open) { SearchResultsPanel( state = search, + kind = SearchKindFilter.fromStorage(searchKind), + sort = SearchSort.fromStorage(searchSort), + onKind = { vm.setSearchKind(it.serverKind) }, + onSort = { vm.setSearchSort(it.storageKey) }, onSelect = onSelectResult, modifier = Modifier .fillMaxWidth() diff --git a/android/app/src/main/java/net/awan/pipelines/ui/SearchResultsPanel.kt b/android/app/src/main/java/net/awan/pipelines/ui/SearchResultsPanel.kt index 4190d851..3e97dbef 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/SearchResultsPanel.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/SearchResultsPanel.kt @@ -12,6 +12,7 @@ import androidx.compose.foundation.lazy.items import androidx.compose.foundation.shape.RoundedCornerShape import androidx.compose.material3.CircularProgressIndicator import androidx.compose.material3.HorizontalDivider +import androidx.compose.material3.Icon import androidx.compose.material3.LinearProgressIndicator import androidx.compose.material3.MaterialTheme import androidx.compose.material3.Surface @@ -30,31 +31,47 @@ import androidx.compose.ui.text.style.TextOverflow import androidx.compose.ui.text.withStyle import androidx.compose.ui.unit.dp import net.awan.pipelines.data.protocol.SearchResult -import net.awan.pipelines.ui.components.LabelChip +import net.awan.pipelines.ui.components.FilterCheckItem +import net.awan.pipelines.ui.components.FilterMenu +import net.awan.pipelines.ui.components.SortMenu +import net.awan.pipelines.ui.theme.ICON_LIST_DP import net.awan.pipelines.ui.theme.SEARCH_PROGRESS_DP import net.awan.pipelines.ui.theme.SPACING_L import net.awan.pipelines.ui.theme.SPACING_M import net.awan.pipelines.ui.theme.SPACING_S -import net.awan.pipelines.ui.theme.SPACING_XXS import net.awan.pipelines.ui.theme.SPACING_XL +import net.awan.pipelines.ui.theme.SPACING_XS +import net.awan.pipelines.ui.theme.SPACING_XXS import net.awan.pipelines.ui.theme.pipelinesText /** * The omni-search results panel: one scrolling surface that sits above the search - * field. It renders the last accepted results, and while a newer query loads it - * keeps those results and adds a thin progress bar rather than blanking; a - * failure is reported without discarding what is already shown. Its height is - * bounded by the caller (the window's IME/navigation-bar insets), so it scrolls - * inside the remainder instead of running under the keyboard. + * field. It leads with the filter and sort controls (the same shared menu + * controls the runs list uses), then renders the last accepted results; while a + * newer query loads it keeps those results and adds a thin progress bar rather + * than blanking, and a failure is reported without discarding what is already + * shown. Its height is bounded by the caller (the window's IME/navigation-bar + * insets), so it scrolls inside the remainder instead of running under the + * keyboard. */ @Composable internal fun SearchResultsPanel( state: SearchUiState, + kind: SearchKindFilter, + sort: SearchSort, + onKind: (SearchKindFilter) -> Unit, + onSort: (SearchSort) -> Unit, onSelect: (SearchResult) -> Unit, modifier: Modifier = Modifier, ) { val scheme = MaterialTheme.colorScheme val error = state.error + // The filter and sort are applied to the results in hand as well as being sent + // to the server (the kind) or held client-side (the order), so the list always + // matches the active control, even for the moment a narrowed request loads. + val shown = remember(state.results, kind, sort) { + sortSearchResults(filterSearchResults(state.results, kind), sort) + } Surface( modifier = modifier, shape = RoundedCornerShape(SPACING_XL), @@ -63,6 +80,8 @@ internal fun SearchResultsPanel( shadowElevation = 6.dp, ) { Column(Modifier.fillMaxWidth()) { + SearchControls(kind = kind, sort = sort, onKind = onKind, onSort = onSort) + HorizontalDivider(color = scheme.outlineVariant) // A refresh of an already-populated panel shows progress without // replacing the results; the first load shows the searching row below. if (state.loading && state.results.isNotEmpty()) { @@ -70,14 +89,68 @@ internal fun SearchResultsPanel( } when { error != null -> PanelMessage(error, isError = true) - state.isEmptyResult() -> PanelMessage("No matches for \"${state.query}\".", isError = false) + shown.isNotEmpty() -> SearchResultList(shown, state.query, onSelect) state.loading && state.results.isEmpty() -> SearchingRow() - state.results.isNotEmpty() -> SearchResultList(state.results, state.query, onSelect) + else -> searchPanelEmptyMessage(state, shown, kind)?.let { PanelMessage(it, isError = false) } } } } } +/** + * The search surface's filter and sort control, the same shared [FilterMenu] and + * [SortMenu] the runs list uses rather than a new pattern, plus the one-line + * summary of the active choice so the collapsed controls are legible. The kind + * filter narrows server-side; the sort orders the results in hand. + */ +@Composable +private fun SearchControls( + kind: SearchKindFilter, + sort: SearchSort, + onKind: (SearchKindFilter) -> Unit, + onSort: (SearchSort) -> Unit, +) { + Row( + // The top inset leaves room for the filter badge, which is drawn above the + // icon button; without it the badge spills over the panel's rounded edge. + modifier = Modifier + .fillMaxWidth() + .padding(start = SPACING_S, end = SPACING_XS, top = SPACING_S, bottom = SPACING_XS), + verticalAlignment = Alignment.CenterVertically, + horizontalArrangement = Arrangement.spacedBy(SPACING_XS), + ) { + FilterMenu( + activeCount = if (kind == SearchKindFilter.All) 0 else 1, + contentDescription = "Filter results", + resetLabel = "Clear filter", + onReset = { onKind(SearchKindFilter.Default) }, + ) { dismiss -> + SearchKindFilter.entries.forEach { option -> + FilterCheckItem(option.label, option == kind) { + onKind(option) + dismiss() + } + } + } + SortMenu( + options = SearchSort.entries, + selected = sort, + label = { it.label }, + header = "Sort results in hand", + contentDescription = "Sort results in hand", + onSelect = onSort, + onReset = { onSort(SearchSort.Default) }, + ) + Text( + text = searchControlsSummary(kind, sort), + style = pipelinesText().meta, + maxLines = 1, + overflow = TextOverflow.Ellipsis, + modifier = Modifier.weight(1f).padding(start = SPACING_S), + ) + } +} + @Composable private fun PanelMessage(message: String, isError: Boolean) { Text( @@ -127,10 +200,12 @@ private fun SearchResultList( } /** - * One result row: its type badge, a title and a secondary line. A text match's - * secondary line is its snippet with the matched span rendered bold+underlined, - * so the match is distinguishable without relying on colour. A result with no - * navigation target (an unknown kind) is shown read-only and is not clickable. + * One result row: the type glyph (its kind, or an artifact's content type), a + * title and a secondary line. The glyph carries the kind in words as its + * content description, since the mark alone is not readable, and the matched span + * of a text match is rendered bold+underlined, so the match is distinguishable + * without relying on colour. A result with no navigation target (an unknown kind) + * is shown read-only and is not clickable. */ @Composable private fun SearchResultRow( @@ -151,9 +226,15 @@ private fun SearchResultRow( }, ) .padding(horizontal = SPACING_L, vertical = SPACING_M), + verticalAlignment = Alignment.CenterVertically, horizontalArrangement = Arrangement.spacedBy(SPACING_M), ) { - LabelChip(row.badge, SPACING_S, SPACING_XXS) + Icon( + imageVector = searchResultIcon(hit), + contentDescription = searchResultKindLabel(hit), + tint = MaterialTheme.colorScheme.onSurfaceVariant, + modifier = Modifier.size(ICON_LIST_DP), + ) Column( modifier = Modifier.weight(1f), verticalArrangement = Arrangement.spacedBy(SPACING_XXS), diff --git a/android/app/src/main/java/net/awan/pipelines/ui/components/FilterMenu.kt b/android/app/src/main/java/net/awan/pipelines/ui/components/FilterMenu.kt index e3d60ca4..ddf2e7a5 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/components/FilterMenu.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/components/FilterMenu.kt @@ -179,7 +179,7 @@ fun FilterCheckItem( ) } -/** A small section caption inside a filter menu (Status/Pipeline/Time range). */ +/** A small section caption inside a menu (a filter facet or a sort's reach). */ @Composable fun FilterSectionHeader(label: String) { Text( diff --git a/android/app/src/main/java/net/awan/pipelines/ui/components/LabelChip.kt b/android/app/src/main/java/net/awan/pipelines/ui/components/LabelChip.kt deleted file mode 100644 index 1652e6d2..00000000 --- a/android/app/src/main/java/net/awan/pipelines/ui/components/LabelChip.kt +++ /dev/null @@ -1,31 +0,0 @@ -package net.awan.pipelines.ui.components - -import androidx.compose.foundation.layout.padding -import androidx.compose.foundation.shape.RoundedCornerShape -import androidx.compose.material3.MaterialTheme -import androidx.compose.material3.Surface -import androidx.compose.material3.Text -import androidx.compose.runtime.Composable -import androidx.compose.ui.Modifier -import androidx.compose.ui.unit.Dp - -/** - * A small rounded tonal chip whose label carries its meaning, so it never relies - * on colour alone. One shape, colour and type across the app; a caller passes - * only the padding its context needs (the search row's type badge is tighter than - * the stage-type chip), so a second copy of the chip never appears. - */ -@Composable -internal fun LabelChip(label: String, horizontalPadding: Dp, verticalPadding: Dp) { - Surface( - shape = RoundedCornerShape(50), - color = MaterialTheme.colorScheme.secondaryContainer, - ) { - Text( - text = label, - style = MaterialTheme.typography.labelMedium, - color = MaterialTheme.colorScheme.onSecondaryContainer, - modifier = Modifier.padding(horizontal = horizontalPadding, vertical = verticalPadding), - ) - } -} diff --git a/android/app/src/main/java/net/awan/pipelines/ui/components/SortMenu.kt b/android/app/src/main/java/net/awan/pipelines/ui/components/SortMenu.kt index 9f3b5436..47f3ff2d 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/components/SortMenu.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/components/SortMenu.kt @@ -25,7 +25,9 @@ import androidx.compose.ui.Modifier * icon and works at both window widths (it is not width-dependent geometry). * * [selected] draws a leading check on its row, so the active choice is conveyed - * by a glyph as well as by text, never by colour alone. + * by a glyph as well as by text, never by colour alone. An optional [header] + * captions the menu, e.g. to say that an order applies to the results in hand + * rather than server-side. */ @Composable fun SortMenu( @@ -36,6 +38,7 @@ fun SortMenu( onSelect: (T) -> Unit, onReset: () -> Unit, modifier: Modifier = Modifier, + header: String? = null, ) { var expanded by remember { mutableStateOf(false) } Box(modifier) { @@ -43,6 +46,7 @@ fun SortMenu( Icon(Icons.AutoMirrored.Filled.Sort, contentDescription = contentDescription) } DropdownMenu(expanded = expanded, onDismissRequest = { expanded = false }) { + header?.let { FilterSectionHeader(it) } options.forEach { option -> DropdownMenuItem( text = { Text(label(option)) }, diff --git a/android/app/src/main/java/net/awan/pipelines/ui/graph/ArtifactType.kt b/android/app/src/main/java/net/awan/pipelines/ui/graph/ArtifactType.kt index 15037562..76b89093 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/graph/ArtifactType.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/graph/ArtifactType.kt @@ -82,6 +82,26 @@ internal fun artifactIcon(kind: ArtifactKind): ImageVector = when (kind) { ArtifactKind.Other -> Icons.AutoMirrored.Filled.InsertDriveFile } +/** + * The word that names [kind] where a surface shows the type glyph but must also + * say the type in prose (a screen reader cannot read an icon). It is the same + * classification [artifactIcon] draws from, so the glyph and the word never + * disagree. Pure, so the mapping is unit-tested. + */ +internal fun artifactKindLabel(kind: ArtifactKind): String = when (kind) { + ArtifactKind.Image -> "Image" + ArtifactKind.Video -> "Video" + ArtifactKind.Audio -> "Audio" + ArtifactKind.Pdf -> "PDF" + ArtifactKind.Json -> "JSON" + ArtifactKind.Archive -> "Archive" + ArtifactKind.Spreadsheet -> "Spreadsheet" + ArtifactKind.Log -> "Log" + ArtifactKind.Code -> "Code" + ArtifactKind.Document -> "Document" + ArtifactKind.Other -> "File" +} + private val ARCHIVE_EXTENSIONS = setOf("zip", "tar", "gz", "tgz", "bz2", "xz", "rar", "7z", "jar", "war") diff --git a/android/app/src/test/java/net/awan/pipelines/ui/OmniSearchResultsTest.kt b/android/app/src/test/java/net/awan/pipelines/ui/OmniSearchResultsTest.kt index ddb081c6..2bd8b23d 100644 --- a/android/app/src/test/java/net/awan/pipelines/ui/OmniSearchResultsTest.kt +++ b/android/app/src/test/java/net/awan/pipelines/ui/OmniSearchResultsTest.kt @@ -1,5 +1,19 @@ package net.awan.pipelines.ui +import androidx.compose.material.icons.Icons +import androidx.compose.material.icons.automirrored.filled.HelpOutline +import androidx.compose.material.icons.automirrored.filled.InsertDriveFile +import androidx.compose.material.icons.automirrored.filled.Segment +import androidx.compose.material.icons.automirrored.filled.Subject +import androidx.compose.material.icons.filled.AccountTree +import androidx.compose.material.icons.filled.Code +import androidx.compose.material.icons.filled.Commit +import androidx.compose.material.icons.filled.DataObject +import androidx.compose.material.icons.filled.Description +import androidx.compose.material.icons.filled.History +import androidx.compose.material.icons.filled.Image +import androidx.compose.material.icons.filled.PictureAsPdf +import androidx.compose.ui.graphics.vector.ImageVector import net.awan.pipelines.data.protocol.Protocol import net.awan.pipelines.data.protocol.RunStep import net.awan.pipelines.data.protocol.SearchArtifact @@ -10,6 +24,8 @@ import net.awan.pipelines.data.protocol.SearchResult import net.awan.pipelines.data.protocol.SearchRun import net.awan.pipelines.data.protocol.SearchStep import net.awan.pipelines.data.protocol.SearchVersion +import net.awan.pipelines.ui.graph.artifactIcon +import net.awan.pipelines.ui.graph.artifactKind import org.junit.Assert.assertEquals import org.junit.Assert.assertFalse import org.junit.Assert.assertNotNull @@ -19,26 +35,77 @@ import org.junit.Test class OmniSearchResultsTest { - // ---- Badges and rows --------------------------------------------------- + // ---- Type glyphs and rows ---------------------------------------------- @Test - fun everyKindMapsToItsBadge() { - assertEquals("pipeline", searchBadge(Protocol.SEARCH_KIND_PIPELINE)) - assertEquals("pipeline", searchBadge(Protocol.SEARCH_KIND_VERSION)) - assertEquals("run", searchBadge(Protocol.SEARCH_KIND_RUN)) - assertEquals("step", searchBadge(Protocol.SEARCH_KIND_STEP)) - assertEquals("artifact", searchBadge(Protocol.SEARCH_KIND_ARTIFACT)) - assertEquals("match", searchBadge(Protocol.SEARCH_KIND_FIELD)) - // A kind the client does not know still gets a badge and is shown. - assertEquals("match", searchBadge("future_kind")) - assertEquals("match", searchBadge("")) + fun everyKindMapsToItsOwnGlyph() { + assertEquals(Icons.Filled.AccountTree, searchResultIcon(hit(Protocol.SEARCH_KIND_PIPELINE))) + assertEquals(Icons.Filled.Commit, searchResultIcon(hit(Protocol.SEARCH_KIND_VERSION))) + assertEquals(Icons.Filled.History, searchResultIcon(hit(Protocol.SEARCH_KIND_RUN))) + assertEquals(Icons.AutoMirrored.Filled.Segment, searchResultIcon(hit(Protocol.SEARCH_KIND_STEP))) + assertEquals(Icons.AutoMirrored.Filled.Subject, searchResultIcon(hit(Protocol.SEARCH_KIND_FIELD))) + // An artifact shows its content type's glyph; an unknown kind gets a neutral + // mark rather than none, and no two kinds share a glyph. + assertEquals(Icons.Filled.Description, searchResultIcon(hit(Protocol.SEARCH_KIND_ARTIFACT))) + assertEquals(Icons.AutoMirrored.Filled.HelpOutline, searchResultIcon(hit("future_kind"))) + val glyphs = listOf( + Protocol.SEARCH_KIND_PIPELINE, + Protocol.SEARCH_KIND_VERSION, + Protocol.SEARCH_KIND_RUN, + Protocol.SEARCH_KIND_STEP, + Protocol.SEARCH_KIND_FIELD, + Protocol.SEARCH_KIND_ARTIFACT, + "future_kind", + ).map { searchResultIcon(hit(it)) } + assertEquals(glyphs.size, glyphs.toSet().size) } @Test - fun eachRowCarriesABadgeTitleAndSecondaryLine() { + fun anArtifactGlyphIsTheGallerysContentTypeMapping() { + // Every artifact reuses artifactIcon(artifactKind(...)) rather than a second + // mapping, so the search surface and the gallery can never disagree. + val cases = listOf( + "image/png" to "shot.png", + "application/pdf" to "report.pdf", + "application/json" to "run.json", + "text/markdown" to "notes.md", + "application/xml" to "graph.xml", + "text/plain" to "readme.txt", + "application/octet-stream" to "blob", + ) + cases.forEach { (contentType, name) -> + assertEquals( + "artifact $contentType", + artifactIcon(artifactKind(contentType, name)), + artifactGlyph(contentType, name), + ) + } + // Spot-check the concrete glyphs the brief names. + assertEquals(Icons.Filled.Image, artifactGlyph("image/png", "shot.png")) + assertEquals(Icons.Filled.PictureAsPdf, artifactGlyph("application/pdf", "report.pdf")) + assertEquals(Icons.Filled.DataObject, artifactGlyph("application/json", "run.json")) + assertEquals(Icons.Filled.Code, artifactGlyph("application/xml", "graph.xml")) + assertEquals(Icons.Filled.Description, artifactGlyph("text/plain", "readme.txt")) + assertEquals(Icons.AutoMirrored.Filled.InsertDriveFile, artifactGlyph("application/octet-stream", "blob")) + } + + @Test + fun everyKindCarriesItsKindInWords() { + assertEquals("Pipeline", searchResultKindLabel(hit(Protocol.SEARCH_KIND_PIPELINE))) + assertEquals("Pipeline version", searchResultKindLabel(hit(Protocol.SEARCH_KIND_VERSION))) + assertEquals("Run", searchResultKindLabel(hit(Protocol.SEARCH_KIND_RUN))) + assertEquals("Step", searchResultKindLabel(hit(Protocol.SEARCH_KIND_STEP))) + assertEquals("Field", searchResultKindLabel(hit(Protocol.SEARCH_KIND_FIELD))) + // The default artifact fixture is a markdown file; an image names itself. + assertEquals("Document artifact", searchResultKindLabel(hit(Protocol.SEARCH_KIND_ARTIFACT))) + assertEquals("Image artifact", searchResultKindLabel(artifactHit("image/png", "shot.png"))) + assertEquals("Unrecognised result", searchResultKindLabel(hit("future_kind"))) + } + + @Test + fun eachRowCarriesATitleAndSecondaryLine() { results().forEach { hit -> val row = searchRow(hit, "release") - assertTrue("badge for ${hit.kind}", row.badge.isNotBlank()) assertTrue("title for ${hit.kind}", row.title.isNotBlank()) assertTrue("secondary for ${hit.kind}", row.secondary.isNotBlank()) } @@ -62,6 +129,91 @@ class OmniSearchResultsTest { assertNull("an unknown kind is not navigable", searchTarget(unknown)) } + // ---- Kind filter ------------------------------------------------------- + + @Test + fun everyFilterCarriesTheServerKindAndResolvesFromStorage() { + assertEquals("", SearchKindFilter.All.serverKind) + assertEquals(Protocol.SEARCH_KIND_PIPELINE, SearchKindFilter.Pipelines.serverKind) + assertEquals(Protocol.SEARCH_KIND_VERSION, SearchKindFilter.Versions.serverKind) + assertEquals(SearchKindFilter.All, SearchKindFilter.fromStorage("")) + assertEquals(SearchKindFilter.Runs, SearchKindFilter.fromStorage("run")) + // A stale/unknown stored value falls back to every kind; "prompts" is not a + // server kind, so it is deliberately not an option. + assertEquals(SearchKindFilter.All, SearchKindFilter.fromStorage("prompts")) + } + + @Test + fun theKindFilterNarrowsTheListToThatKind() { + val mixed = listOf( + hit(Protocol.SEARCH_KIND_PIPELINE), + hit(Protocol.SEARCH_KIND_RUN), + hit(Protocol.SEARCH_KIND_STEP), + hit(Protocol.SEARCH_KIND_FIELD), + hit(Protocol.SEARCH_KIND_ARTIFACT), + hit(Protocol.SEARCH_KIND_VERSION), + ) + assertEquals(mixed, filterSearchResults(mixed, SearchKindFilter.All)) + assertEquals(listOf(hit(Protocol.SEARCH_KIND_RUN)), filterSearchResults(mixed, SearchKindFilter.Runs)) + assertEquals(listOf(hit(Protocol.SEARCH_KIND_ARTIFACT)), filterSearchResults(mixed, SearchKindFilter.Artifacts)) + assertEquals( + listOf(hit(Protocol.SEARCH_KIND_VERSION)), + filterSearchResults(mixed, SearchKindFilter.Versions), + ) + } + + // ---- Sort ordering ----------------------------------------------------- + + @Test + fun relevanceKeepsTheServersRanking() { + val ordered = listOf( + hitWithRecency(Protocol.SEARCH_KIND_RUN, "2026-01-01T00:00:00Z"), + hitWithRecency(Protocol.SEARCH_KIND_PIPELINE, "2026-03-01T00:00:00Z"), + ) + assertEquals(ordered, sortSearchResults(ordered, SearchSort.Relevance)) + } + + @Test + fun newestFirstOrdersByRecencyDescending() { + val older = hitWithRecency(Protocol.SEARCH_KIND_RUN, "2026-01-01T00:00:00Z") + val newer = hitWithRecency(Protocol.SEARCH_KIND_PIPELINE, "2026-03-01T00:00:00Z") + assertEquals(listOf(newer, older), sortSearchResults(listOf(older, newer), SearchSort.Newest)) + } + + @Test + fun aRecencyTieKeepsTheServersOrder() { + val first = hitWithRecency(Protocol.SEARCH_KIND_RUN, "2026-01-01T00:00:00Z") + val second = hitWithRecency(Protocol.SEARCH_KIND_PIPELINE, "2026-01-01T00:00:00Z") + assertEquals(listOf(first, second), sortSearchResults(listOf(first, second), SearchSort.Newest)) + } + + @Test + fun aMissingRecencySortsLast() { + val dated = hitWithRecency(Protocol.SEARCH_KIND_RUN, "2026-01-01T00:00:00Z") + val undated = SearchResult(kind = Protocol.SEARCH_KIND_RUN, recency = null) + assertEquals(listOf(dated, undated), sortSearchResults(listOf(undated, dated), SearchSort.Newest)) + } + + @Test + fun nameOrdersByTheDisplayedTitleAndATieKeepsItsOrder() { + val alpha1 = SearchResult(kind = Protocol.SEARCH_KIND_PIPELINE, pipeline = SearchPipeline(id = 1, name = "alpha")) + val beta = SearchResult(kind = Protocol.SEARCH_KIND_PIPELINE, pipeline = SearchPipeline(id = 2, name = "beta")) + val alpha2 = SearchResult(kind = Protocol.SEARCH_KIND_PIPELINE, pipeline = SearchPipeline(id = 3, name = "alpha")) + // The two "alpha" rows tie and keep their input order; "beta" moves last. + assertEquals(listOf(alpha1, alpha2, beta), sortSearchResults(listOf(beta, alpha1, alpha2), SearchSort.Name)) + } + + @Test + fun theStoredSortAndTheControlSummaryResolve() { + assertEquals(SearchSort.Relevance, SearchSort.fromStorage("")) + assertEquals(SearchSort.Name, SearchSort.fromStorage("name")) + assertEquals(SearchSort.Relevance, SearchSort.fromStorage("bogus")) + assertEquals("All kinds · Relevance", searchControlsSummary(SearchKindFilter.All, SearchSort.Relevance)) + // An order that runs on the fetched results says so in the collapsed summary. + assertEquals("Runs · Newest first (in hand)", searchControlsSummary(SearchKindFilter.Runs, SearchSort.Newest)) + assertEquals("Fields · Name (in hand)", searchControlsSummary(SearchKindFilter.Fields, SearchSort.Name)) + } + // ---- Snippet highlighting --------------------------------------------- @Test @@ -220,13 +372,25 @@ class OmniSearchResultsTest { } @Test - fun theEmptyStateNamesTheQueryAndOnlyAppearsWhenLoaded() { + fun theEmptyStateNamesTheQueryAndTheActiveFilter() { val empty = SearchUiState(query = "release").loaded(SearchResponse(results = emptyList())) - assertTrue(empty.isEmptyResult()) - // Still loading: not the empty state. - assertFalse(empty.editing("release2").isEmptyResult()) - // A failure is an error, not an empty result. - assertFalse(SearchUiState(query = "release").failed("boom").isEmptyResult()) + assertEquals( + "No matches for \"release\".", + searchPanelEmptyMessage(empty, emptyList(), SearchKindFilter.All), + ) + // A filter that empties the list names itself rather than the generic line. + val pipelineOnly = empty.copy(results = listOf(hit(Protocol.SEARCH_KIND_PIPELINE))) + assertEquals( + "No runs match \"release\".", + searchPanelEmptyMessage(pipelineOnly, emptyList(), SearchKindFilter.Runs), + ) + // Rows shown: no message. Still loading, blank query or an error: no message + // (the panel shows progress, nothing, or the error respectively). + val shown = listOf(hit(Protocol.SEARCH_KIND_RUN)) + assertNull(searchPanelEmptyMessage(empty.copy(results = shown), shown, SearchKindFilter.All)) + assertNull(searchPanelEmptyMessage(empty.editing("release2"), emptyList(), SearchKindFilter.All)) + assertNull(searchPanelEmptyMessage(SearchUiState(query = ""), emptyList(), SearchKindFilter.All)) + assertNull(searchPanelEmptyMessage(empty.failed("boom"), emptyList(), SearchKindFilter.All)) } // ---- Fixtures ---------------------------------------------------------- @@ -265,6 +429,17 @@ class OmniSearchResultsTest { else -> SearchResult(kind = kind, target = "") } + private fun hitWithRecency(kind: String, recency: String?): SearchResult = + hit(kind).copy(recency = recency) + + private fun artifactHit(contentType: String, name: String): SearchResult = SearchResult( + kind = Protocol.SEARCH_KIND_ARTIFACT, + artifact = SearchArtifact(name = name, contentType = contentType), + ) + + private fun artifactGlyph(contentType: String, name: String): ImageVector = + searchResultIcon(artifactHit(contentType, name)) + private fun results(): List = listOf( Protocol.SEARCH_KIND_PIPELINE, Protocol.SEARCH_KIND_VERSION, diff --git a/android/app/src/test/java/net/awan/pipelines/ui/graph/ArtifactTypeTest.kt b/android/app/src/test/java/net/awan/pipelines/ui/graph/ArtifactTypeTest.kt index 57060c12..a6274e23 100644 --- a/android/app/src/test/java/net/awan/pipelines/ui/graph/ArtifactTypeTest.kt +++ b/android/app/src/test/java/net/awan/pipelines/ui/graph/ArtifactTypeTest.kt @@ -74,4 +74,17 @@ class ArtifactTypeTest { val glyphs = ArtifactKind.entries.map { artifactIcon(it) } assertEquals(ArtifactKind.entries.size, glyphs.toSet().size) } + + @Test + fun everyKindHasAWordThatNamesIt() { + // The search surface names an artifact by this word for a screen reader; + // it must exist for every kind and be distinct. + assertEquals("Image", artifactKindLabel(ArtifactKind.Image)) + assertEquals("PDF", artifactKindLabel(ArtifactKind.Pdf)) + assertEquals("JSON", artifactKindLabel(ArtifactKind.Json)) + assertEquals("Document", artifactKindLabel(ArtifactKind.Document)) + assertEquals("File", artifactKindLabel(ArtifactKind.Other)) + val labels = ArtifactKind.entries.map { artifactKindLabel(it) } + assertEquals(ArtifactKind.entries.size, labels.toSet().size) + } } From 2c1dfe9a3561ca43f4d268c4196de36f14c60975 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 00:13:17 +0100 Subject: [PATCH 8/9] android: restore the shared LabelChip the search-icon replay deleted Replaying b808158 removed ui/components/LabelChip.kt: that commit predates e2147b0, which extracted one shared LabelChip for the chat panes, so the older diff carried the file's deletion. Restored from the commit before the replay; the build and the full unit suite pass again. A cherry-pick's deletions need the same scrutiny as its conflicts. --- .../awan/pipelines/ui/components/LabelChip.kt | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 android/app/src/main/java/net/awan/pipelines/ui/components/LabelChip.kt diff --git a/android/app/src/main/java/net/awan/pipelines/ui/components/LabelChip.kt b/android/app/src/main/java/net/awan/pipelines/ui/components/LabelChip.kt new file mode 100644 index 00000000..1652e6d2 --- /dev/null +++ b/android/app/src/main/java/net/awan/pipelines/ui/components/LabelChip.kt @@ -0,0 +1,31 @@ +package net.awan.pipelines.ui.components + +import androidx.compose.foundation.layout.padding +import androidx.compose.foundation.shape.RoundedCornerShape +import androidx.compose.material3.MaterialTheme +import androidx.compose.material3.Surface +import androidx.compose.material3.Text +import androidx.compose.runtime.Composable +import androidx.compose.ui.Modifier +import androidx.compose.ui.unit.Dp + +/** + * A small rounded tonal chip whose label carries its meaning, so it never relies + * on colour alone. One shape, colour and type across the app; a caller passes + * only the padding its context needs (the search row's type badge is tighter than + * the stage-type chip), so a second copy of the chip never appears. + */ +@Composable +internal fun LabelChip(label: String, horizontalPadding: Dp, verticalPadding: Dp) { + Surface( + shape = RoundedCornerShape(50), + color = MaterialTheme.colorScheme.secondaryContainer, + ) { + Text( + text = label, + style = MaterialTheme.typography.labelMedium, + color = MaterialTheme.colorScheme.onSecondaryContainer, + modifier = Modifier.padding(horizontal = horizontalPadding, vertical = verticalPadding), + ) + } +} From 971e555ceb770314b39df884bedcc3df8bca62ad Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Sun, 18 Oct 2026 00:10:47 +0100 Subject: [PATCH 9/9] chat: close and reopen an operator session on the server, keeping its history Add a server-side close for operator chats, so finishing with a chat takes it out of the active list for every client without deleting anything. The brokered protocol gains chat_close and chat_reopen; chat_close stops a running turn by reusing the existing broker interrupt (its result carries an interrupted flag, so a stream is never left running into nothing) and then sets closed_at on the session's operator_sessions row. The session, its transcript and its history survive, and because the closed state lives in the registry chat_sessions reports it to every client, not just the one that asked. An id that is not a recorded operator session, including a pipeline-owned run session, is refused before anything is written. chat_reopen clears the state again, and simply prompting a closed session also clears it (the store clears closed_at on touch). The registry gains closed_at for a fresh database and an idempotent migration for one created before it existed. The app renders closed sessions under a labelled Closed section with a Closed chip, offers a Close action with a confirmation that says it stops a running turn, marks the chat closed on every device and deletes nothing, and a Reopen action on each closed row. The device-local hide is renamed Hide on this device, with a snackbar saying the chat stays on the server, so it is never confused with the real close. No new dependency, the installer and Docker files are untouched, and no run is started from the app. Checked before committing: the packaged templates carry no chat surface and need no update, and internal/author/install.go's managed inventory needs none either (this adds no reference file). The packaged authoring skill reference internal/author/skill/references/operations.md and the shared docs/cli.md and android/README.md are stale because of this change, but an item no longer edits a shared document: what is stale and what should change there is recorded in docs/notes/chat-close.md for the docs-fold writer, which is committed here with the change. Checks: gofmt clean, go build ./... and go vet ./... clean, and go test ./internal/protocol/... ./internal/pipeline/... ./internal/server/... ./internal/author/... pass. The app side is verified with :app:assembleDebug and :app:testDebugUnitTest (--offline --no-daemon, BUILD SUCCESSFUL); the on-device close, second-client and reopen check is deferred to visual review. Not deployed; deploying is the operator's step. --- .../pipelines/data/PipelinesRepository.kt | 20 ++ .../net/awan/pipelines/data/protocol/Chat.kt | 38 +++ .../awan/pipelines/data/protocol/Message.kt | 8 + .../net/awan/pipelines/ui/AppViewModel.kt | 41 +++ .../net/awan/pipelines/ui/chat/ChatFormat.kt | 26 +- .../awan/pipelines/ui/chat/ChatListPane.kt | 118 ++++++- .../awan/pipelines/ui/chat/ChatOverrides.kt | 15 +- .../net/awan/pipelines/ui/chat/ChatStore.kt | 71 +++- .../data/protocol/ChatProtocolTest.kt | 52 +++ .../awan/pipelines/ui/chat/ChatCloseTest.kt | 107 ++++++ docs/notes/chat-close.md | 106 ++++++ internal/pipeline/operator_sessions.go | 85 ++++- .../pipeline/operator_sessions_close_test.go | 124 +++++++ internal/protocol/chat.go | 27 ++ internal/protocol/chat_test.go | 8 +- internal/protocol/message.go | 4 + internal/server/chat.go | 15 + internal/server/chat_claims.go | 11 + internal/server/chat_close.go | 143 ++++++++ internal/server/chat_close_test.go | 313 ++++++++++++++++++ internal/server/chat_sessions.go | 5 + 21 files changed, 1293 insertions(+), 44 deletions(-) create mode 100644 android/app/src/test/java/net/awan/pipelines/ui/chat/ChatCloseTest.kt create mode 100644 docs/notes/chat-close.md create mode 100644 internal/pipeline/operator_sessions_close_test.go create mode 100644 internal/server/chat_close.go create mode 100644 internal/server/chat_close_test.go diff --git a/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt b/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt index 284f038e..a565f4d6 100644 --- a/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt +++ b/android/app/src/main/java/net/awan/pipelines/data/PipelinesRepository.kt @@ -300,6 +300,26 @@ class PipelinesRepository( client.call(ChatProtocol.interruptRequest(sessionId)) } + /** + * Finishes a chat on the server: any running turn is stopped and the session + * is recorded closed, so every client sees it. Nothing is deleted. The + * server returns the closed session, which the caller folds into its list. + */ + suspend fun chatClose(sessionId: String): ChatSession { + if (sessionId.isBlank()) throw ProtocolException("Select a chat session first.") + val response = client.call(ChatProtocol.closeRequest(sessionId)) + return response.chatSession + ?: throw ProtocolException("The server did not return the closed chat session.") + } + + /** Clears a closed chat's state so it returns to the active list. */ + suspend fun chatReopen(sessionId: String): ChatSession { + if (sessionId.isBlank()) throw ProtocolException("Select a chat session first.") + val response = client.call(ChatProtocol.reopenRequest(sessionId)) + return response.chatSession + ?: throw ProtocolException("The server did not return the reopened chat session.") + } + suspend fun chatReply(sessionId: String, requestId: String, decision: String, message: String = "") { if (sessionId.isBlank() || requestId.isBlank()) { throw ProtocolException("A pending permission request is required.") diff --git a/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt b/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt index c3f8b35d..dcaa5b6a 100644 --- a/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt +++ b/android/app/src/main/java/net/awan/pipelines/data/protocol/Chat.kt @@ -33,6 +33,26 @@ data class ChatSession( // run: the phone shows it read-only instead of letting two clients write the // same conversation. val busy: Boolean = false, + // The operator finished with this session: the server recorded it as closed, + // so every client sees the same state. The session, its transcript and its + // history are kept and the closed chat stays in the list (grouped as history), + // where it can be reopened. [closedAt] is the epoch-millisecond close time, 0 + // while open. Additive/optional, so an older server simply never sets them. + val closed: Boolean = false, + @SerialName("closed_at") val closedAt: Long = 0, +) + +/** + * The outcome of a `chat_close`, mirroring `internal/protocol/chat.go` + * ChatCloseResult: the closed session's id, the epoch-millisecond close time and + * whether an in-flight turn was interrupted to stop it. It is the record that a + * running turn was stopped. + */ +@Serializable +data class ChatCloseResult( + @SerialName("session_id") val sessionId: String = "", + @SerialName("closed_at") val closedAt: Long = 0, + val interrupted: Boolean = false, ) @Serializable @@ -255,6 +275,24 @@ object ChatProtocol { fun interruptRequest(sessionId: String): Message = Message(type = Protocol.CHAT_INTERRUPT, chatQuery = ChatQuery(sessionId = sessionId)) + /** + * The `chat_close` frame that finishes [sessionId]: the server stops any + * running turn (through the same interrupt) and records the session closed on + * the server, sharing the state with every client. Nothing is deleted. Built + * here (not inline in the repository) so production and its unit test share + * the one wire shape. + */ + fun closeRequest(sessionId: String): Message = + Message(type = Protocol.CHAT_CLOSE, chatQuery = ChatQuery(sessionId = sessionId)) + + /** + * The `chat_reopen` frame that clears a closed session's state so it returns + * to the active list; the inverse of [closeRequest]. Built here so production + * and its unit test share the one wire shape. + */ + fun reopenRequest(sessionId: String): Message = + Message(type = Protocol.CHAT_REOPEN, chatQuery = ChatQuery(sessionId = sessionId)) + /** * The `chat_reply` frame that answers one permission request: [decision] is * one of [DECISION_ONCE]/[DECISION_ALWAYS]/[DECISION_REJECT]. Built here (not diff --git a/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt b/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt index 4817181b..8b738fcd 100644 --- a/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt +++ b/android/app/src/main/java/net/awan/pipelines/data/protocol/Message.kt @@ -68,6 +68,11 @@ object Protocol { const val CHAT_MESSAGES = "chat_messages" const val CHAT_INTERRUPT = "chat_interrupt" const val CHAT_REPLY = "chat_reply" + // Close/reopen an operator session on the server (its closed state is + // recorded so every client sees it). Both ride on chat_query like + // chat_interrupt; chat_close also carries a ChatCloseResult on the response. + const val CHAT_CLOSE = "chat_close" + const val CHAT_REOPEN = "chat_reopen" // The operator's directory choices for a new chat (home first, then the // directories of previous operator sessions, most recently used first). const val CHAT_DIRECTORIES = "chat_directories" @@ -680,5 +685,8 @@ data class Message( @SerialName("chat_event") val chatEvent: ChatEventFrame? = null, @SerialName("chat_permission") val chatPermission: ChatPermissionFrame? = null, @SerialName("chat_reply") val chatReply: ChatReplyRequest? = null, + // The outcome of a chat_close (session id, closed_at, interrupted); the + // close/reopen requests themselves ride on chat_query like chat_interrupt. + @SerialName("chat_close") val chatClose: ChatCloseResult? = null, @SerialName("chat_directories") val chatDirectories: List? = null, ) diff --git a/android/app/src/main/java/net/awan/pipelines/ui/AppViewModel.kt b/android/app/src/main/java/net/awan/pipelines/ui/AppViewModel.kt index 80f01734..e312f3de 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/AppViewModel.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/AppViewModel.kt @@ -1055,6 +1055,9 @@ class AppViewModel( viewModelScope.launch { try { repository.chatPrompt(sessionId, text, attachmentFiles(attachments)) + // Prompting a closed session reopens it on the server; clear the + // closed mark locally too so the list agrees without a re-fetch. + chatStore.sessionReopened(sessionId) } catch (t: Throwable) { if (t is CancellationException) throw t val message = ErrorMessages.describe(t) @@ -1099,6 +1102,44 @@ class AppViewModel( } } + /** + * Finishes a chat on the server: any running turn is stopped (the server + * reuses its interrupt) and the session is recorded closed, so every client + * sees the same state. Nothing is deleted — the session and its history stay — + * and the chat is kept in the list as closed history. Errors are reported on + * the list, which is where the action lives. + */ + fun closeChatSession(sessionId: String) { + if (sessionId.isBlank()) return + viewModelScope.launch { + try { + val closed = repository.chatClose(sessionId) + chatStore.sessionClosed(sessionId, closed.closedAt) + } catch (t: Throwable) { + if (t is CancellationException) throw t + chatStore.sessionsFailed(ErrorMessages.describe(t)) + } + } + } + + /** + * Reopens a closed chat so it returns to the active list. Sending another + * message also reopens it (the server clears the closed state on prompt), so + * this is the explicit path beside that one. + */ + fun reopenChatSession(sessionId: String) { + if (sessionId.isBlank()) return + viewModelScope.launch { + try { + repository.chatReopen(sessionId) + chatStore.sessionReopened(sessionId) + } catch (t: Throwable) { + if (t is CancellationException) throw t + chatStore.sessionsFailed(ErrorMessages.describe(t)) + } + } + } + private fun load(target: MutableStateFlow>, block: suspend () -> T) { viewModelScope.launch { target.value = target.value.copy(loading = true, error = null) diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt index d50c87cc..e4a8e196 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatFormat.kt @@ -134,10 +134,15 @@ private const val OPERATOR_TAG_LABEL = "Operator" * would imply. */ internal fun sessionStatusLabel(session: ChatSession, runningLocally: Boolean): String = - sessionStatusLabel(session.busy, runningLocally) + sessionStatusLabel(session.busy, runningLocally, session.closed) -/** The status of a conversation from its own model flags (see [sessionStatusLabel]). */ -internal fun sessionStatusLabel(busy: Boolean, runningLocally: Boolean): String = when { +/** + * The status of a conversation from its own model flags (see [sessionStatusLabel]). + * A closed session reads `Closed` first: it is finished, whatever the server's + * busy flag or a stale local running mark says. + */ +internal fun sessionStatusLabel(busy: Boolean, runningLocally: Boolean, closed: Boolean = false): String = when { + closed -> "Closed" runningLocally -> "Running" busy -> "Busy · read-only" else -> "Idle" @@ -183,7 +188,7 @@ internal data class ConversationHeader( internal fun conversationHeader(thread: ChatThread): ConversationHeader = ConversationHeader( title = sessionTitle(ChatSession(id = thread.sessionId, title = thread.title)), kind = sessionTagLabel(thread.tag), - activity = sessionStatusLabel(thread.busy, thread.running), + activity = sessionStatusLabel(thread.busy, thread.running, thread.closed), directory = thread.directory, model = thread.model, ) @@ -273,6 +278,19 @@ internal fun reasoningLabel(count: Int, streaming: Boolean): String = when { else -> REASONING_SETTLED_LABEL } +/** + * The close confirmation's body: it says exactly what closing does — stops a + * running turn, marks the chat closed on every device — and what it does not do: + * nothing is deleted, the chat and its history are kept and can be reopened. Kept + * pure so the confirmation wording and its unit test share one string instead of + * the copy drifting from the promise. + */ +internal fun closeChatConfirmation(title: String): String = + "Closes \"$title\" and marks it closed on every device. " + + "A turn that is running is stopped first. " + + "Nothing is deleted — the chat and its history are kept, " + + "and you can reopen it from the list." + /** * The elapsed time the server's own timing gives a settled turn: from the * earliest start to the latest completion across the parts that carry a timing diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatListPane.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatListPane.kt index e58ec9cf..4b9ab629 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatListPane.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatListPane.kt @@ -94,10 +94,12 @@ internal fun ChatListPane( // The server returns operator sessions only, with the operator's own local // renames and removals applied on top; the app never guesses which session // belongs to a run. The operator's search narrows that list without touching - // its order, and the survivors are grouped by directory when there is more - // than one so sessions in the same repository sit together. + // its order. Active sessions are grouped by directory when there is more than + // one; the closed ones the operator finished with sit below them as history. val sessions = state.filteredSessions - val groups = groupChatSessionsByDirectory(sessions) + val active = state.activeSessions + val closed = state.closedSessions + val groups = groupChatSessionsByDirectory(active) val query = state.sessionQuery // A removal is reported for what it is: a local, undoable change, never a @@ -115,6 +117,7 @@ internal fun ChatListPane( } } var renaming by remember { mutableStateOf(null) } + var closing by remember { mutableStateOf(null) } Scaffold( modifier = modifier, @@ -177,12 +180,21 @@ internal fun ChatListPane( groups.forEach { group -> item(key = "dir-" + group.directory) { DirectoryHeader(group.directory) } items(group.sessions, key = { it.id }) { session -> - SessionListItem(state, session, vm, onRename = { renaming = it }) + SessionListItem(state, session, vm, onRename = { renaming = it }, onClose = { closing = it }) } } } else { - items(sessions, key = { it.id }) { session -> - SessionListItem(state, session, vm, onRename = { renaming = it }) + items(active, key = { it.id }) { session -> + SessionListItem(state, session, vm, onRename = { renaming = it }, onClose = { closing = it }) + } + } + if (closed.isNotEmpty()) { + // Finished chats stay reachable as history: a clearly + // labelled section, in the same recency order, from which + // each one can be reopened. + item(key = "closed-header") { DirectoryHeader(CLOSED_SECTION_LABEL) } + items(closed, key = { it.id }) { session -> + SessionListItem(state, session, vm, onRename = { renaming = it }, onClose = { closing = it }) } } if (state.sessionsError != null) { @@ -211,6 +223,16 @@ internal fun ChatListPane( }, ) } + closing?.let { session -> + CloseChatDialog( + session = session, + onDismiss = { closing = null }, + onConfirm = { + vm.closeChatSession(session.id) + closing = null + }, + ) + } } /** @@ -251,17 +273,20 @@ private fun SessionListItem( session: ChatSession, vm: AppViewModel, onRename: (ChatSession) -> Unit, + onClose: (ChatSession) -> Unit, ) { val thread = state.thread(session.id) SessionRow( session = session, open = thread != null, running = thread?.running == true, - unseen = state.isUnseen(session), + unseen = !session.closed && state.isUnseen(session), active = state.activeId == session.id, onClick = { vm.openChatSession(session) }, onRename = { onRename(session) }, - onRemove = { vm.removeChat(session.id) }, + onClose = { onClose(session) }, + onReopen = { vm.reopenChatSession(session.id) }, + onHide = { vm.removeChat(session.id) }, ) } @@ -295,7 +320,9 @@ private fun SessionRow( active: Boolean, onClick: () -> Unit, onRename: () -> Unit, - onRemove: () -> Unit, + onClose: () -> Unit, + onReopen: () -> Unit, + onHide: () -> Unit, ) { val texts = pipelinesText() val activity = sessionActivity(running, unseen) @@ -315,10 +342,20 @@ private fun SessionRow( // The kind chip names the session kind the server reported, so an // operator chat is tellable from anything run-related at a glance. sessionTagLabel(session)?.let { LabelChip(it, SPACING_S, SPACING_XXS) } + // A closed chat is named as such on the row itself, so it is never + // confused with a hide (which only affects this device) or with a + // still-open chat. + if (session.closed) LabelChip(CLOSED_CHIP_LABEL, SPACING_S, SPACING_XXS) // The activity badge is the new-activity signal; the tag and the // directory below are unchanged beside it. SessionActivityBadge(activity, open) - SessionMenu(onRename = onRename, onRemove = onRemove) + SessionMenu( + closed = session.closed, + onRename = onRename, + onClose = onClose, + onReopen = onReopen, + onHide = onHide, + ) } val meta = buildList { add(sessionStatusLabel(session, running)) @@ -329,9 +366,19 @@ private fun SessionRow( } } -/** A session row's management actions: rename and remove from this device's list. */ +/** + * A session row's management actions. Closing is the real, server-side finish + * (shared by every device); hiding only affects this device and is named so the + * two cannot be confused. A closed chat offers Reopen instead of Close. + */ @Composable -private fun SessionMenu(onRename: () -> Unit, onRemove: () -> Unit) { +private fun SessionMenu( + closed: Boolean, + onRename: () -> Unit, + onClose: () -> Unit, + onReopen: () -> Unit, + onHide: () -> Unit, +) { var expanded by remember { mutableStateOf(false) } Box { IconButton(onClick = { expanded = true }, modifier = Modifier.size(ICON_BUTTON_SMALL_DP)) { @@ -349,17 +396,52 @@ private fun SessionMenu(onRename: () -> Unit, onRemove: () -> Unit) { onRename() }, ) + if (closed) { + DropdownMenuItem( + text = { Text("Reopen") }, + onClick = { + expanded = false + onReopen() + }, + ) + } else { + DropdownMenuItem( + text = { Text("Close chat…") }, + onClick = { + expanded = false + onClose() + }, + ) + } DropdownMenuItem( - text = { Text("Remove from list") }, + text = { Text("Hide on this device") }, onClick = { expanded = false - onRemove() + onHide() }, ) } } } +/** + * The close confirmation. It says exactly what closing does and does not do: + * stops any running turn, keeps the whole history, and marks the chat closed for + * every device — never a delete, and distinct from the local hide. + */ +@Composable +private fun CloseChatDialog(session: ChatSession, onDismiss: () -> Unit, onConfirm: () -> Unit) { + AlertDialog( + onDismissRequest = onDismiss, + title = { Text("Close chat?") }, + text = { + Text(closeChatConfirmation(sessionTitle(session))) + }, + confirmButton = { TextButton(onClick = onConfirm) { Text("Close chat") } }, + dismissButton = { TextButton(onClick = onDismiss) { Text("Cancel") } }, + ) +} + /** * The rename dialog. The brokered protocol has no rename for a chat session, so * the dialog says plainly that the name is kept on this device rather than @@ -395,7 +477,13 @@ private fun RenameChatDialog(session: ChatSession, onDismiss: () -> Unit, onConf } /** The removal report: what happened and how to undo it. */ -private const val CHAT_REMOVED_MESSAGE = "Removed from this list; the chat stays on the server." +private const val CHAT_REMOVED_MESSAGE = "Hidden on this device; the chat stays on the server." + +/** The row chip and section heading for a chat the operator finished with. */ +private const val CLOSED_CHIP_LABEL = "Closed" + +/** The heading of the section that keeps closed chats reachable as history. */ +private const val CLOSED_SECTION_LABEL = "Closed" /** A running/busy/open indicator: a coloured dot plus a word, never colour alone. */ @Composable diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatOverrides.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatOverrides.kt index 52ebdafa..54b65ce3 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatOverrides.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatOverrides.kt @@ -5,16 +5,17 @@ import net.awan.pipelines.data.protocol.PipelinesJson /** * The operator's own changes to the session list, which the server has no - * request for: a chat cannot be renamed or deleted through the brokered - * protocol (there is no chat_rename/chat_delete type, and the OpenCode session - * endpoint is not exposed), so both are kept here, on the device, and applied - * over whatever the server lists. + * request for: a chat cannot be renamed through the brokered protocol (there is + * no chat_rename type), so it is kept here, on the device, and applied over + * whatever the server lists. Closing a chat and reopening it are *not* here: they + * are server-side (`chat_close`/`chat_reopen`) so every device sees them. * * - [titles] are local renames, keyed by session id; a renamed chat shows its * local title and the server's title is left untouched. - * - [hidden] are sessions the operator removed from the list. Nothing is deleted - * on the server, so the removal is honest and reversible ([remove] can be - * undone with [restore]). + * - [hidden] are sessions the operator hid on this device. Nothing is deleted on + * the server, and no other device is affected, so the hide is honest and + * reversible ([remove] can be undone with [restore]). It is distinct from a + * server-side close, which marks the chat closed for every client. * * Kept as a serializable value so it survives a restart as one preference, * exactly like the app's other stored settings. diff --git a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt index a3d80f75..e81d3a38 100644 --- a/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt +++ b/android/app/src/main/java/net/awan/pipelines/ui/chat/ChatStore.kt @@ -57,6 +57,12 @@ data class ChatThread( val updatedAt: Long = 0, /** The server reports another client (or an active run) holds this session. */ val busy: Boolean = false, + /** + * The server reports this session closed: the operator finished with it. The + * conversation and its history are kept; the chat can be reopened, and sending + * another message reopens it too. + */ + val closed: Boolean = false, val messages: List = emptyList(), val loading: Boolean = false, val loaded: Boolean = false, @@ -225,6 +231,21 @@ data class ChatState( */ val filteredSessions: List get() = filterChatSessions(visibleSessions, sessionQuery) + + /** + * The sessions still in play: [filteredSessions] without the closed ones, in + * the same recency order. The list shows these as the active conversations. + */ + val activeSessions: List + get() = filteredSessions.filterNot { it.closed } + + /** + * The finished sessions: [filteredSessions] the server reports as closed, in + * the same order. They are shown as history — nothing was deleted — and can be + * reopened from the list. + */ + val closedSessions: List + get() = filteredSessions.filter { it.closed } } /** @@ -304,6 +325,7 @@ class ChatStore( agent = session.agent.ifBlank { thread.agent }, tag = session.tag.ifBlank { thread.tag }, busy = session.busy, + closed = session.closed, ) } // Fold the read state in: the active conversation is on screen, so its @@ -405,9 +427,11 @@ class ChatStore( } /** - * Removes a session from the device's list and closes its conversation, if - * open. Nothing is deleted on the server — the session still exists there — so - * the removal is honest and reversible through [undoRemove]. + * Hides a session on this device only and closes its conversation, if open. + * Nothing is deleted on the server — the session still exists there — and no + * other device is affected, so the hide is honest and reversible through + * [undoRemove]. It is deliberately not a "close": the server-side close (see + * [sessionClosed]) is shared by every client. */ fun remove(sessionId: String) { if (sessionId.isBlank()) return @@ -429,6 +453,44 @@ class ChatStore( ) } + // ---- Closing and reopening (server-side, shared by every client) --------- + + /** + * Records that the server closed [sessionId]: the row is marked closed with + * the server's [closedAt] and any in-flight turn is settled, because the + * server stopped it. The session is not removed from [ChatState.sessions] — + * closed chats stay listed as history. + */ + fun sessionClosed(sessionId: String, closedAt: Long) { + if (sessionId.isBlank()) return + val at = if (closedAt > 0) closedAt else now() + _state.value = _state.value.copy( + sessions = _state.value.sessions.map { + if (it.id == sessionId) it.copy(closed = true, closedAt = at) else it + }, + open = _state.value.open.map { + if (it.sessionId == sessionId) setRunning(it.copy(closed = true), false) else it + }, + ) + } + + /** + * Clears the closed state of [sessionId] — an explicit reopen, or a prompt + * that the server treated as reopening it — so the chat returns to the active + * list without a re-fetch. + */ + fun sessionReopened(sessionId: String) { + if (sessionId.isBlank()) return + _state.value = _state.value.copy( + sessions = _state.value.sessions.map { + if (it.id == sessionId) it.copy(closed = false, closedAt = 0) else it + }, + open = _state.value.open.map { + if (it.sessionId == sessionId) it.copy(closed = false) else it + }, + ) + } + // ---- Opening / switching ------------------------------------------------- /** @@ -454,6 +516,7 @@ class ChatStore( agent = session.agent, updatedAt = session.updatedAt, busy = session.busy, + closed = session.closed, ) _state.value = _state.value.copy(open = _state.value.open + thread, activeId = session.id, seen = seen) return true @@ -465,6 +528,7 @@ class ChatStore( agent = session.agent.ifBlank { existing.agent }, tag = session.tag.ifBlank { existing.tag }, busy = session.busy, + closed = session.closed, ) _state.value = _state.value.copy( open = _state.value.open.map { if (it.sessionId == session.id) merged else it }, @@ -733,6 +797,7 @@ class ChatStore( agent = session?.agent ?: "", tag = session?.tag ?: "", busy = session?.busy ?: false, + closed = session?.closed ?: false, ) _state.value = _state.value.copy(open = _state.value.open + placeholder) } diff --git a/android/app/src/test/java/net/awan/pipelines/data/protocol/ChatProtocolTest.kt b/android/app/src/test/java/net/awan/pipelines/data/protocol/ChatProtocolTest.kt index ef8d96f4..f6590287 100644 --- a/android/app/src/test/java/net/awan/pipelines/data/protocol/ChatProtocolTest.kt +++ b/android/app/src/test/java/net/awan/pipelines/data/protocol/ChatProtocolTest.kt @@ -311,6 +311,58 @@ class ChatProtocolTest { assertNull(message.chatEvent) assertNull(message.chatSessions) assertNull(message.chatPermission) + assertNull(message.chatClose) + } + + /** + * The session list carries the server's closed state: a closed session decodes + * with its flag and close time, and an open one stays open, so the app can + * group finished chats as history without a second request. + */ + @Test + fun chatSessionsParseTheClosedState() { + val json = """ + {"type":"chat_sessions","chat_sessions":[ + {"id":"ses_open","title":"Active"}, + {"id":"ses_done","title":"Finished","closed":true,"closed_at":1792112367999}]} + """.trimIndent() + val sessions = PipelinesJson.decodeFromString(Message.serializer(), json).chatSessions!! + assertEquals(false, sessions[0].closed) + assertEquals(0L, sessions[0].closedAt) + assertTrue(sessions[1].closed) + assertEquals(1792112367999L, sessions[1].closedAt) + } + + /** + * The close/reopen frames use the same builder the repository sends and carry + * only the session id; the close reply's result (closed_at, interrupted) + * round-trips, so the app can report that a turn was stopped. + */ + @Test + fun chatCloseAndReopenFramesRoundTrip() { + val close = ChatProtocol.closeRequest("ses_1") + assertEquals(Protocol.CHAT_CLOSE, close.type) + assertEquals("ses_1", close.chatQuery!!.sessionId) + val decodedClose = PipelinesJson.decodeFromString( + Message.serializer(), + PipelinesJson.encodeToString(Message.serializer(), close.copy(id = "android-1")), + ) + assertEquals(Protocol.CHAT_CLOSE, decodedClose.type) + + val reopen = ChatProtocol.reopenRequest("ses_1") + assertEquals(Protocol.CHAT_REOPEN, reopen.type) + assertEquals("ses_1", reopen.chatQuery!!.sessionId) + + val reply = """ + {"type":"chat_close","id":"android-1", + "chat_session":{"id":"ses_1","closed":true,"closed_at":1792112367999}, + "chat_close":{"session_id":"ses_1","closed_at":1792112367999,"interrupted":true}} + """.trimIndent() + val decodedReply = PipelinesJson.decodeFromString(Message.serializer(), reply) + assertEquals(true, decodedReply.chatSession!!.closed) + assertEquals(1792112367999L, decodedReply.chatSession!!.closedAt) + assertTrue(decodedReply.chatClose!!.interrupted) + assertEquals(1792112367999L, decodedReply.chatClose!!.closedAt) } private fun toolDuration(part: ChatPart): Long? { diff --git a/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatCloseTest.kt b/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatCloseTest.kt new file mode 100644 index 00000000..f673af4f --- /dev/null +++ b/android/app/src/test/java/net/awan/pipelines/ui/chat/ChatCloseTest.kt @@ -0,0 +1,107 @@ +package net.awan.pipelines.ui.chat + +import net.awan.pipelines.data.protocol.ChatProtocol +import net.awan.pipelines.data.protocol.ChatSession +import org.junit.Assert.assertEquals +import org.junit.Assert.assertFalse +import org.junit.Assert.assertTrue +import org.junit.Test + +/** + * Closing a chat: the server-side finish (shared by every client) marks the row + * closed, keeps it as history, settles a running turn, and can be reversed by a + * reopen or a prompt. Driven against [ChatStore] with no device or server. + */ +class ChatCloseTest { + + private fun session( + id: String, + title: String = id, + closed: Boolean = false, + closedAt: Long = 0, + ) = ChatSession( + id = id, + title = title, + tag = ChatProtocol.TAG_OPERATOR, + directory = "/home/op", + closed = closed, + closedAt = closedAt, + ) + + @Test + fun closingMarksTheRowClosedAndKeepsItAsHistory() { + val store = ChatStore() + store.sessionsLoaded(listOf(session("a"), session("b"))) + store.sessionClosed("a", 1_700_000_000_000) + + // Still in the server list (nothing deleted), but no longer active. + assertEquals(listOf("a", "b"), store.value.sessions.map { it.id }) + assertEquals(listOf("b"), store.value.activeSessions.map { it.id }) + val closed = store.value.closedSessions.single() + assertEquals("a", closed.id) + assertTrue(closed.closed) + assertEquals(1_700_000_000_000, closed.closedAt) + } + + @Test + fun reopeningReturnsTheChatToTheActiveList() { + val store = ChatStore() + store.sessionsLoaded(listOf(session("a"), session("b"))) + store.sessionClosed("a", 1_700_000_000_000) + store.sessionReopened("a") + + assertEquals(listOf("a", "b"), store.value.activeSessions.map { it.id }) + assertTrue(store.value.closedSessions.isEmpty()) + assertFalse(store.value.sessions.first { it.id == "a" }.closed) + assertEquals(0, store.value.sessions.first { it.id == "a" }.closedAt) + } + + @Test + fun closingSettlesARunningThreadAndMarksItClosed() { + val store = ChatStore() + store.sessionsLoaded(listOf(session("a"))) + store.open(session("a")) + store.running("a", true) + + store.sessionClosed("a", 1_700_000_000_000) + + val thread = store.value.thread("a")!! + assertFalse("the stopped turn must not still read as running", thread.running) + assertTrue(thread.closed) + // The conversation is kept: its history is not deleted. + assertTrue(store.value.thread("a") != null) + } + + @Test + fun aServerListRefreshCarriesTheClosedStateIntoTheStore() { + val store = ChatStore() + // The list arrives closed (the server is the source of truth). + store.sessionsLoaded(listOf(session("a", closed = true, closedAt = 5), session("b"))) + + assertEquals(listOf("b"), store.value.activeSessions.map { it.id }) + assertEquals(listOf("a"), store.value.closedSessions.map { it.id }) + } + + @Test + fun aRefreshMarksAnAlreadyOpenThreadClosed() { + val store = ChatStore() + store.sessionsLoaded(listOf(session("a"))) + store.open(session("a")) + assertFalse(store.value.thread("a")!!.closed) + + store.sessionsLoaded(listOf(session("a", closed = true, closedAt = 5))) + assertTrue(store.value.thread("a")!!.closed) + } + + @Test + fun theRowStatusReadsClosedAndTheConfirmationSaysWhatCloseDoes() { + assertEquals("Closed", sessionStatusLabel(session("a", closed = true), runningLocally = false)) + + val wording = closeChatConfirmation("Fix the parser") + assertTrue("names the stop of a running turn", wording.contains("running is stopped")) + assertTrue("says it affects every device", wording.contains("every device")) + assertTrue("says nothing is deleted", wording.contains("Nothing is deleted")) + assertTrue("says it can be reopened", wording.contains("reopen")) + assertTrue("names the chat", wording.contains("Fix the parser")) + } +} diff --git a/docs/notes/chat-close.md b/docs/notes/chat-close.md new file mode 100644 index 00000000..be8942de --- /dev/null +++ b/docs/notes/chat-close.md @@ -0,0 +1,106 @@ +# Finishing a chat: a server-side close that keeps the history + +## What this item changed + +The Pipelines server and `android/`. Before this, the only way to get a chat out +of the list was the app's device-local hide (`ChatOverrides.hidden`): the session +stayed open on the server, other clients still showed it, and nothing recorded +that the operator had finished with it. + +- `internal/protocol/chat.go` adds the `chat_close` and `chat_reopen` request + types, a `ChatCloseResult` (`session_id`, `closed_at`, `interrupted`) and + additive `closed`/`closed_at` fields on the chat session; `internal/protocol/message.go` + carries `ChatClose` on the outcome envelope (the requests themselves ride on + `chat_query`, like `chat_messages`/`chat_interrupt`). +- `internal/server/chat_close.go` (new) handles both: `chat_close` stops a turn + in flight by reusing the broker interrupt the session's room owns (recording in + the reply that a turn was stopped, so a stream is never left running into + nothing), then sets `closed_at`; `chat_reopen` clears it. Both take a + `chat_query` and echo the session plus its registry row. A session id that is + not a recorded operator session — including a pipeline-owned run session — is + refused before anything is written. Nothing is deleted. +- `internal/server/chat_sessions.go` marks a listed session `closed`/`closed_at` + from the registry, so every client sees the same state and a closed session + stays listed. +- `internal/server/chat_room.go` gains `turnInFlight`, so close only interrupts a + session that actually has a turn running. +- `internal/pipeline/operator_sessions.go` adds `closed_at` to + `operator_sessions` (for a fresh database and by an idempotent + `addColumnIfMissing` migration for an existing one), plus + `CloseOperatorSession`, `ReopenOperatorSession` and `OperatorSession`, and + clears the closed state on record and on touch, so simply prompting a closed + session reopens it. +- `android/`: `data/protocol/Chat.kt`/`Message.kt` (closed fields, the two + requests), `PipelinesRepository.chatClose`/`chatReopen`, `ChatStore` (closed + state, a `closedSessions` grouping, `setQueued`/`sessionReopened`), + `ChatFormat` (a closed status label), `ChatListPane` (a `Closed` chip and + section, Close/Reopen actions, a confirmation stating that close stops a + running turn, marks the chat closed on every device and deletes nothing), + `AppViewModel` (the close/reopen actions), and the rename of the local action + to **Hide on this device** with a snackbar saying the chat stays on the server. +- Tests: `internal/protocol/chat_test.go`, `internal/server/chat_close_test.go`, + `internal/pipeline/operator_sessions_close_test.go`, + `android/.../ChatCloseTest.kt` and the closed-state cases in + `android/.../ChatProtocolTest.kt`. + +No new dependency (only the already-declared material-icons-extended), the +installer and the Docker files are untouched, and no run is started from the app. +State: committed locally only, not deployed; the on-device close/second-client/ +reopen check is deferred to visual review. + +## Shared documents this change makes stale + +The note is written here rather than edited in place; the `docs-fold` writer +should update these when it next folds notes. + +- `docs/cli.md:306` — the `## Chat sessions` bullet for `chat_sessions` lists each + session's `directory`, `tag` and recency and ends "A session is never marked + `busy`". It should add that a closed session is still listed, marked + `closed: true` with its `closed_at`, so a client groups or filters it as + history rather than losing it. +- `docs/cli.md:342` — after the `chat_adopt` bullet, add two bullets: + `chat_close` takes a `chat_query` (`session_id`), stops any in-flight turn + through the same interrupt `chat_interrupt` uses (the `chat_close` result's + `interrupted` flag records that a turn was stopped), then sets `closed_at` in + the operator-session registry; it answers with the closed session as + `chat_session`, its registry row in `chat_sessions` and the `chat_close` + result; an id that is not a recorded operator session — including a + pipeline-owned run session — is refused before anything is written, and + nothing is ever deleted. And `chat_reopen` clears the state again (the inverse, + same `chat_query`); prompting a closed session also clears it. +- `android/README.md:6326` — append a dated section recording the behaviour: the + server-side close and reopen, the session and transcript surviving a close, + the `Closed` chip/section and the `Closed` status line, the Close action and + its confirmation wording, the Reopen action, the two ways a session reopens, + and the rename of the local action to **Hide on this device** (device-only, + with a snackbar saying the chat stays on the server) so the two are never + confused. Include the verification evidence and the not-verified-on-device + boundary (implementation verification is the build and the unit tests; visual + review owns the device). +- `internal/author/skill/references/operations.md:268` — the "Brokered OpenCode + chat" preamble lists the declared `chat_*` surface; add `chat_close` and + `chat_reopen`. +- `internal/author/skill/references/operations.md:307` — the `chat_sessions` + paragraph describes the `operator_sessions` shape (`session_id`, `directory`, + `title`, `tag`, `created_at`, `last_used_at`); add `closed_at` and say that a + closed session stays in the list marked `closed`/`closed_at`. Add a paragraph + documenting `chat_close`/`chat_reopen` (interrupt a running turn, record the + closed state, refuse a non-operator session, keep listing as history, reopen + explicitly or by prompting), and add a dated evidence bullet naming + `internal/server/chat_close_test.go`, + `internal/pipeline/operator_sessions_close_test.go`, + `internal/protocol/chat_test.go` and the app's `ChatCloseTest`, marking the + on-device check as not run. + +## Not stale + +- No packaged template names the chat surface, so `internal/author/`'s templates + need no change. +- `internal/author/install.go`'s managed file inventory needs no change: this + item adds no reference file. +- `internal/author/skill/references/SKILL.md` stays a task-directed index; the + close/reopen detail belongs in `operations.md`. +- `android/AGENTS.md` already lists `ui/chat/` and its files, and + `internal/server/AGENTS.md` already points at `internal/server/chat_*.go` and + `internal/pipeline/`'s operator-session registry, so neither area map needs a + new entry. diff --git a/internal/pipeline/operator_sessions.go b/internal/pipeline/operator_sessions.go index 52d99d39..c4cb2b7f 100644 --- a/internal/pipeline/operator_sessions.go +++ b/internal/pipeline/operator_sessions.go @@ -2,6 +2,8 @@ package pipeline import ( "context" + "database/sql" + "errors" "time" ) @@ -23,6 +25,11 @@ type OperatorSession struct { Tag string CreatedAt int64 UpdatedAt int64 + // ClosedAt is the epoch-millisecond time the operator finished with the + // session, or 0 while it is open. It records the closed state on the server + // so every client sees the same thing; the session and its history are never + // deleted, and reopening clears it back to 0. + ClosedAt int64 } // initOperatorSessions creates the operator-session registry. It is a table of @@ -30,44 +37,96 @@ type OperatorSession struct { // ownership (run_session_owners, SessionOwner) is untouched and the two // vocabularies cannot be confused. session_id is the primary key, so lookups and // the upsert use the index; operator_sessions_recent serves the recency order. +// closed_at is added here for a fresh database and by migrateOperatorSessions for +// one created before the closed state existed. func (s *Store) initOperatorSessions() error { _, err := s.db.Exec(`CREATE TABLE IF NOT EXISTS operator_sessions ( session_id TEXT PRIMARY KEY, directory TEXT NOT NULL, title TEXT NOT NULL DEFAULT '', -tag TEXT NOT NULL DEFAULT '', created_at INTEGER NOT NULL, last_used_at INTEGER NOT NULL); +tag TEXT NOT NULL DEFAULT '', created_at INTEGER NOT NULL, last_used_at INTEGER NOT NULL, +closed_at INTEGER NOT NULL DEFAULT 0); CREATE INDEX IF NOT EXISTS operator_sessions_recent ON operator_sessions(last_used_at DESC);`) - return err + if err != nil { + return err + } + return s.migrateOperatorSessions() +} + +// migrateOperatorSessions adds the closed_at column to a database created before +// the closed state existed. Adding a column with a default leaves every existing +// row valid and open (0), so an upgrade is idempotent across repeated Open calls +// and no session is silently reported as closed. +func (s *Store) migrateOperatorSessions() error { + return s.addColumnIfMissing("operator_sessions", "closed_at", "INTEGER NOT NULL DEFAULT 0") } // RecordOperatorSession upserts one operator chat session in a single statement: // a new id is inserted with its created_at and last_used_at set to now, and a // repeated id updates directory/title/tag and moves last_used_at to now while // preserving the original created_at. CreatedAt is therefore stable across -// re-records. +// re-records. Recording also clears any closed state: re-creating or adopting a +// session is use, so it is open again. func (s *Store) RecordOperatorSession(ctx context.Context, sessionID, directory, title, tag string) error { now := time.Now().UnixMilli() - _, err := s.db.ExecContext(ctx, `INSERT INTO operator_sessions(session_id,directory,title,tag,created_at,last_used_at) -VALUES(?,?,?,?,?,?) -ON CONFLICT(session_id) DO UPDATE SET directory=excluded.directory,title=excluded.title,tag=excluded.tag,last_used_at=excluded.last_used_at`, + _, err := s.db.ExecContext(ctx, `INSERT INTO operator_sessions(session_id,directory,title,tag,created_at,last_used_at,closed_at) +VALUES(?,?,?,?,?,?,0) +ON CONFLICT(session_id) DO UPDATE SET directory=excluded.directory,title=excluded.title,tag=excluded.tag,last_used_at=excluded.last_used_at,closed_at=0`, sessionID, directory, title, tag, now, now) return err } // TouchOperatorSession records that an operator session was just used, in one -// UPDATE. A session id that is not an operator session updates no row and is not -// an error: the statement is itself the presence check, so no second read is +// UPDATE. It also clears the closed state, so simply prompting a closed session +// reopens it. A session id that is not an operator session updates no row and is +// not an error: the statement is itself the presence check, so no second read is // needed. func (s *Store) TouchOperatorSession(ctx context.Context, sessionID string) error { - _, err := s.db.ExecContext(ctx, "UPDATE operator_sessions SET last_used_at=? WHERE session_id=?", time.Now().UnixMilli(), sessionID) + _, err := s.db.ExecContext(ctx, "UPDATE operator_sessions SET last_used_at=?, closed_at=0 WHERE session_id=?", time.Now().UnixMilli(), sessionID) return err } +// CloseOperatorSession records that the operator finished with an operator +// session, in one UPDATE that sets closed_at to now. Nothing is deleted: the row, +// its history and the OpenCode session itself are untouched. A session id that is +// not an operator session (for example a pipeline-owned run session) updates no +// row and is not an error, so run sessions are never affected. +func (s *Store) CloseOperatorSession(ctx context.Context, sessionID string) error { + _, err := s.db.ExecContext(ctx, "UPDATE operator_sessions SET closed_at=? WHERE session_id=?", time.Now().UnixMilli(), sessionID) + return err +} + +// ReopenOperatorSession clears the closed state of an operator session, in one +// UPDATE that sets closed_at back to 0. A session id that is not an operator +// session updates no row and is not an error. +func (s *Store) ReopenOperatorSession(ctx context.Context, sessionID string) error { + _, err := s.db.ExecContext(ctx, "UPDATE operator_sessions SET closed_at=0 WHERE session_id=?", sessionID) + return err +} + +// OperatorSession returns one operator session by id. found is false when the id +// is not a recorded operator session (so a pipeline-owned run session is never +// returned). It is one indexed lookup and never mutates the row. +func (s *Store) OperatorSession(ctx context.Context, sessionID string) (OperatorSession, bool, error) { + var session OperatorSession + row := s.db.QueryRowContext(ctx, `SELECT session_id,directory,title,tag,created_at,last_used_at,closed_at +FROM operator_sessions WHERE session_id=? AND tag <> ''`, sessionID) + if err := row.Scan(&session.ID, &session.Directory, &session.Title, &session.Tag, &session.CreatedAt, &session.UpdatedAt, &session.ClosedAt); err != nil { + if errors.Is(err, sql.ErrNoRows) { + return OperatorSession{}, false, nil + } + return OperatorSession{}, false, err + } + return session, true, nil +} + // OperatorSessions reports the operator's chat sessions, most-recently-used // first (ties broken by session id for a deterministic order), capped at // operatorSessionListLimit. Rows with no tag are omitted: a session with no -// recorded tag is not an operator session and must never be listed. It is one -// bounded statement; recency is never mutated here. +// recorded tag is not an operator session and must never be listed. Closed +// sessions are included: the app groups or filters them as history, so the +// operator can still see and reopen what they finished. It is one bounded +// statement; recency is never mutated here. func (s *Store) OperatorSessions(ctx context.Context) ([]OperatorSession, error) { - rows, err := s.db.QueryContext(ctx, `SELECT session_id,directory,title,tag,created_at,last_used_at + rows, err := s.db.QueryContext(ctx, `SELECT session_id,directory,title,tag,created_at,last_used_at,closed_at FROM operator_sessions WHERE tag <> '' ORDER BY last_used_at DESC, session_id LIMIT ?`, operatorSessionListLimit) if err != nil { return nil, err @@ -76,7 +135,7 @@ FROM operator_sessions WHERE tag <> '' ORDER BY last_used_at DESC, session_id LI sessions := []OperatorSession{} for rows.Next() { var session OperatorSession - if err := rows.Scan(&session.ID, &session.Directory, &session.Title, &session.Tag, &session.CreatedAt, &session.UpdatedAt); err != nil { + if err := rows.Scan(&session.ID, &session.Directory, &session.Title, &session.Tag, &session.CreatedAt, &session.UpdatedAt, &session.ClosedAt); err != nil { return nil, err } sessions = append(sessions, session) diff --git a/internal/pipeline/operator_sessions_close_test.go b/internal/pipeline/operator_sessions_close_test.go new file mode 100644 index 00000000..959b26b4 --- /dev/null +++ b/internal/pipeline/operator_sessions_close_test.go @@ -0,0 +1,124 @@ +package pipeline + +import ( + "context" + "path/filepath" + "testing" +) + +// TestOperatorSessionsCloseReopenAndTouch proves the closed-state contract: a +// close records closed_at and the session is still listed as history, an explicit +// reopen clears it, a prompt (touch) clears it, re-recording clears it, and the +// session, its history and its created_at are never deleted or rewritten. +func TestOperatorSessionsCloseReopenAndTouch(t *testing.T) { + ctx := context.Background() + store, err := Open(filepath.Join(t.TempDir(), "close.db")) + if err != nil { + t.Fatal(err) + } + defer store.Close() + if err := store.RecordOperatorSession(ctx, "ses_a", "/work/a", "A", "operator"); err != nil { + t.Fatal(err) + } + before, err := store.OperatorSessions(ctx) + if err != nil { + t.Fatal(err) + } + + if err := store.CloseOperatorSession(ctx, "ses_a"); err != nil { + t.Fatal(err) + } + closed, err := store.OperatorSessions(ctx) + if err != nil { + t.Fatal(err) + } + if len(closed) != 1 || closed[0].ClosedAt <= 0 { + t.Fatalf("close did not record closed_at: %+v", closed) + } + if closed[0].ID != before[0].ID || closed[0].Directory != before[0].Directory || + closed[0].Title != before[0].Title || closed[0].Tag != before[0].Tag || closed[0].CreatedAt != before[0].CreatedAt { + t.Fatalf("close changed the session beyond closed_at:\nbefore %+v\nafter %+v", before[0], closed[0]) + } + one, found, err := store.OperatorSession(ctx, "ses_a") + if err != nil || !found || one.ClosedAt <= 0 { + t.Fatalf("OperatorSession = %+v found=%v err=%v", one, found, err) + } + if _, found, err := store.OperatorSession(ctx, "ses_run"); err != nil || found { + t.Fatalf("a non-operator session was reported found=%v err=%v", found, err) + } + + if err := store.ReopenOperatorSession(ctx, "ses_a"); err != nil { + t.Fatal(err) + } + if rows, err := store.OperatorSessions(ctx); err != nil || len(rows) != 1 || rows[0].ClosedAt != 0 { + t.Fatalf("explicit reopen did not clear closed_at: %+v %v", rows, err) + } + + // Prompting (touch) reopens too. + if err := store.CloseOperatorSession(ctx, "ses_a"); err != nil { + t.Fatal(err) + } + if err := store.TouchOperatorSession(ctx, "ses_a"); err != nil { + t.Fatal(err) + } + if rows, err := store.OperatorSessions(ctx); err != nil || len(rows) != 1 || rows[0].ClosedAt != 0 { + t.Fatalf("touch did not clear closed_at: %+v %v", rows, err) + } + + // Re-recording (create/adopt) reopens too. + if err := store.CloseOperatorSession(ctx, "ses_a"); err != nil { + t.Fatal(err) + } + if err := store.RecordOperatorSession(ctx, "ses_a", "/work/a", "A", "operator"); err != nil { + t.Fatal(err) + } + if rows, err := store.OperatorSessions(ctx); err != nil || len(rows) != 1 || rows[0].ClosedAt != 0 { + t.Fatalf("re-record did not clear closed_at: %+v %v", rows, err) + } + + // Closing a session id that is not an operator session writes nothing. + if err := store.CloseOperatorSession(ctx, "ses_run"); err != nil { + t.Fatalf("closing a non-operator session errored: %v", err) + } +} + +// TestOperatorSessionsMigrationAddsClosedAt proves an existing database created +// before the closed state opens cleanly: the column is added with a default, so +// every existing session stays open and Close/Reopen work afterwards. +func TestOperatorSessionsMigrationAddsClosedAt(t *testing.T) { + ctx := context.Background() + path := filepath.Join(t.TempDir(), "migrate.db") + store, err := Open(path) + if err != nil { + t.Fatal(err) + } + if err := store.RecordOperatorSession(ctx, "ses_old", "/work/old", "Old", "operator"); err != nil { + t.Fatal(err) + } + // Simulate the pre-closed schema by dropping the column, then reopen. + if _, err := store.db.ExecContext(ctx, "ALTER TABLE operator_sessions DROP COLUMN closed_at"); err != nil { + t.Fatalf("drop closed_at: %v", err) + } + if err := store.Close(); err != nil { + t.Fatal(err) + } + + store, err = Open(path) + if err != nil { + t.Fatalf("Open after drop: %v", err) + } + defer store.Close() + rows, err := store.OperatorSessions(ctx) + if err != nil { + t.Fatal(err) + } + if len(rows) != 1 || rows[0].ID != "ses_old" || rows[0].ClosedAt != 0 { + t.Fatalf("migrated rows = %+v, want the old session open", rows) + } + if err := store.CloseOperatorSession(ctx, "ses_old"); err != nil { + t.Fatal(err) + } + if rows, err := store.OperatorSessions(ctx); err != nil || len(rows) != 1 || rows[0].ClosedAt <= 0 { + t.Fatalf("close after migration failed: %+v %v", rows, err) + } +} diff --git a/internal/protocol/chat.go b/internal/protocol/chat.go index bd39f8f0..282c0da0 100644 --- a/internal/protocol/chat.go +++ b/internal/protocol/chat.go @@ -26,6 +26,16 @@ const ( ChatMessages = "chat_messages" ChatInterrupt = "chat_interrupt" ChatReply = "chat_reply" + // ChatClose finishes an operator session and records it as closed on the + // server: any in-flight turn is interrupted through the existing interrupt, + // nothing is deleted (the session, its transcript and its history survive) and + // the closed state is shared by every client because it lives in the + // operator-session registry. ChatReopen clears the closed state again, so a + // finished chat can be resumed. Both take a ChatQuery (the session id) and + // echo the updated session like chat_create/chat_adopt. Neither ever touches + // the pipeline-owned run sessions. + ChatClose = "chat_close" + ChatReopen = "chat_reopen" // ChatDirectories is the request/response type for the operator's directory // choices: the home directory plus the directories of previous operator // sessions, most recently used first, deduplicated and bounded. It is a @@ -116,6 +126,23 @@ type ChatSession struct { // of letting two clients silently write the same conversation. It is // additive and optional: older peers ignore it. Busy bool `json:"busy,omitempty"` + // Closed records that the operator finished with this session: the server + // keeps the session, its transcript and its history, but the closed state is + // shared by every client (it lives in the operator-session registry, not on + // one device). ClosedAt is the epoch-millisecond close time, 0 while open. + // Additive/omitempty so older peers ignore them. + Closed bool `json:"closed,omitempty"` + ClosedAt int64 `json:"closed_at,omitempty"` +} + +// ChatCloseResult reports the outcome of a chat_close: the session id, the +// epoch-millisecond time the closed state was recorded, and whether an +// in-flight turn was interrupted to stop it. It is the record that a running +// turn was stopped, so a stream is never left running into nothing. +type ChatCloseResult struct { + SessionID string `json:"session_id"` + ClosedAt int64 `json:"closed_at"` + Interrupted bool `json:"interrupted,omitempty"` } // ChatCreateRequest is the chat_create request body: a title and an optional diff --git a/internal/protocol/chat_test.go b/internal/protocol/chat_test.go index 5c02e6cc..15f27d29 100644 --- a/internal/protocol/chat_test.go +++ b/internal/protocol/chat_test.go @@ -22,6 +22,8 @@ func chatSamples() []struct { Directory: "/work", ParentID: "ses_0", Tag: ChatSessionTagOperator, CreatedAt: 1792112366711, UpdatedAt: 1792112367999, }}, {"session_busy", ChatSession{ID: "ses_2", Title: "held", Busy: true}}, + {"session_closed", ChatSession{ID: "ses_3", Title: "done", Closed: true, ClosedAt: 1792112367999}}, + {"close_result", ChatCloseResult{SessionID: "ses_3", ClosedAt: 1792112367999, Interrupted: true}}, {"create", ChatCreateRequest{Title: "demo", Directory: "/work"}}, {"adopt", ChatAdoptRequest{SessionID: "ses_1"}}, {"query", ChatQuery{SessionID: "ses_1", Limit: 50}}, @@ -166,6 +168,7 @@ func TestChatEnvelopeRoundTrip(t *testing.T) { }, ChatReply: &ChatReplyRequest{SessionID: "ses_1", RequestID: "req_1", Decision: ChatDecisionReject}, ChatDirectories: []string{"/home/operator", "/work/project"}, + ChatClose: &ChatCloseResult{SessionID: "ses_1", ClosedAt: 1792112367999, Interrupted: true}, } encoded, err := json.Marshal(message) if err != nil { @@ -188,7 +191,8 @@ func TestChatEnvelopeRoundTrip(t *testing.T) { !reflect.DeepEqual(decoded.ChatEvent, message.ChatEvent) || !reflect.DeepEqual(decoded.ChatPermission, message.ChatPermission) || !reflect.DeepEqual(decoded.ChatReply, message.ChatReply) || - !reflect.DeepEqual(decoded.ChatDirectories, message.ChatDirectories) { + !reflect.DeepEqual(decoded.ChatDirectories, message.ChatDirectories) || + !reflect.DeepEqual(decoded.ChatClose, message.ChatClose) { t.Fatalf("chat payloads lost: %+v", decoded) } } @@ -198,7 +202,7 @@ func TestChatFieldsOmittedWhenUnused(t *testing.T) { if err != nil { t.Fatal(err) } - for _, absent := range []string{"chat_sessions", "chat_session", "chat_create", "chat_adopt", "chat_query", "chat_prompt", "chat_messages", "chat_event", "chat_permission", "chat_reply", "chat_directories"} { + for _, absent := range []string{"chat_sessions", "chat_session", "chat_create", "chat_adopt", "chat_query", "chat_prompt", "chat_messages", "chat_event", "chat_permission", "chat_reply", "chat_directories", "chat_close"} { if strings.Contains(string(minimal), absent) { t.Fatalf("absent %q must be omitted: %s", absent, minimal) } diff --git a/internal/protocol/message.go b/internal/protocol/message.go index 0ca03db2..c9165a19 100644 --- a/internal/protocol/message.go +++ b/internal/protocol/message.go @@ -166,6 +166,10 @@ type Message struct { ChatEvent *ChatEventFrame `json:"chat_event,omitempty"` ChatPermission *ChatPermissionFrame `json:"chat_permission,omitempty"` ChatReply *ChatReplyRequest `json:"chat_reply,omitempty"` + // ChatClose carries the outcome of a chat_close; the close and reopen + // requests themselves ride on ChatQuery (the session id), matching + // chat_messages/chat_interrupt. + ChatClose *ChatCloseResult `json:"chat_close,omitempty"` // ChatDirectories carries the operator's directory choices on a // chat_directories response (home first, then recent operator-session // directories, deduplicated and bounded). Additive/omitempty so older peers diff --git a/internal/server/chat.go b/internal/server/chat.go index 6112c876..f46082fb 100644 --- a/internal/server/chat.go +++ b/internal/server/chat.go @@ -44,6 +44,15 @@ type operatorRegistry interface { TouchOperatorSession(ctx context.Context, sessionID string) error OperatorSessions(ctx context.Context) ([]pipeline.OperatorSession, error) OperatorDirectories(ctx context.Context, limit int) ([]string, error) + // OperatorSession returns one recorded operator session by id (found false + // when the id is not an operator session), so chat_close/chat_reopen can echo + // the updated row and refuse a session that is not theirs. + OperatorSession(ctx context.Context, sessionID string) (pipeline.OperatorSession, bool, error) + // CloseOperatorSession records the closed state; ReopenOperatorSession clears + // it. Neither deletes anything, and neither touches a pipeline-owned run + // session (which has no operator_sessions row). + CloseOperatorSession(ctx context.Context, sessionID string) error + ReopenOperatorSession(ctx context.Context, sessionID string) error } // chatClientToken returns an unguessable per-connection identity. It attributes @@ -89,6 +98,12 @@ func handleChat(ctx context.Context, request protocol.Message, broker chatBroker case protocol.ChatDirectories: handleChatDirectories(ctx, request, registry, write) return true + case protocol.ChatClose: + handleChatClose(ctx, request, broker, hub, registry, write) + return true + case protocol.ChatReopen: + handleChatReopen(ctx, request, registry, write) + return true } return false } diff --git a/internal/server/chat_claims.go b/internal/server/chat_claims.go index ccc1792e..bd97b6ef 100644 --- a/internal/server/chat_claims.go +++ b/internal/server/chat_claims.go @@ -48,6 +48,17 @@ func (h *chatHub) busyForOther(sessionID, clientID string) bool { return ok && holder != clientID } +// active reports whether any client currently holds sessionID, so a turn may be +// running. chat_close uses it to decide whether to interrupt; the claim is +// released when the turn's stream drains, so it is never left set for a settled +// session. +func (h *chatHub) active(sessionID string) bool { + h.mu.Lock() + defer h.mu.Unlock() + _, ok := h.claims[sessionID] + return ok +} + // evictClaimsLocked drops the oldest claim when the cap is reached, keeping the // claim map bounded like the retained turns. Callers must hold h.mu. func (h *chatHub) evictClaimsLocked() { diff --git a/internal/server/chat_close.go b/internal/server/chat_close.go new file mode 100644 index 00000000..87a7933b --- /dev/null +++ b/internal/server/chat_close.go @@ -0,0 +1,143 @@ +package server + +import ( + "context" + "strings" + + "git.a-wan.net/alan/pipelines/internal/opencode" + "git.a-wan.net/alan/pipelines/internal/pipeline" + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// handleChatClose finishes an operator chat session and records it as closed on +// the server. It stops a turn that is running by reusing the existing interrupt +// (so a stream is never left running into nothing, and the result records that a +// turn was stopped), then sets the closed state in the operator-session +// registry. Nothing is deleted: the session, its transcript and its history +// survive, and every client sees the closed state because it lives in the +// registry, not on one device. A session id that is not a recorded operator +// session is refused before anything is written, so a pipeline-owned run session +// is never touched. +func handleChatClose(ctx context.Context, request protocol.Message, broker chatBroker, hub *chatHub, registry operatorRegistry, write func(protocol.Message) error) { + if broker == nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "chat is not configured on this server"}) + return + } + if registry == nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "operator session registry is not configured on this server"}) + return + } + query := request.ChatQuery + if query == nil || !opencode.ValidSessionID(query.SessionID) { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "a valid OpenCode session id is required"}) + return + } + sessionID := query.SessionID + if _, found, err := registry.OperatorSession(ctx, sessionID); err != nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) + return + } else if !found { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "session " + sessionID + " is not an operator chat session"}) + return + } + // Stop a running turn first. A failed interrupt is surfaced and the close is + // not recorded, so the operator is never told a live turn was stopped when it + // was not. + interrupted := hub.active(sessionID) + if interrupted { + if err := broker.Interrupt(ctx, sessionID); err != nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "session " + sessionID + " could not be stopped: " + err.Error()}) + return + } + } + if err := registry.CloseOperatorSession(ctx, sessionID); err != nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) + return + } + session, found, err := registry.OperatorSession(ctx, sessionID) + if err != nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) + return + } + if !found { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "session " + sessionID + " was closed but is no longer an operator session"}) + return + } + wire := chatSessionFromOperator(session) + response := protocol.Message{ + Type: protocol.ChatClose, + ID: request.ID, + ChatSession: &wire, + ChatClose: &protocol.ChatCloseResult{SessionID: sessionID, ClosedAt: session.ClosedAt, Interrupted: interrupted}, + } + // Echo the registry row on the list field so a client can splice it into + // chat_sessions without a re-list. + response.ChatSessions = []protocol.ChatSession{wire} + _ = write(response) +} + +// handleChatReopen clears the closed state of an operator chat session so it +// returns to the active list. Nothing is created or deleted; it is the inverse of +// chat_close. Prompting a closed session also reopens it (the store clears the +// closed state on touch), so both an explicit reopen and simply sending another +// message work. A session id that is not a recorded operator session is refused. +func handleChatReopen(ctx context.Context, request protocol.Message, registry operatorRegistry, write func(protocol.Message) error) { + if registry == nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "operator session registry is not configured on this server"}) + return + } + query := request.ChatQuery + if query == nil || !opencode.ValidSessionID(query.SessionID) { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "a valid OpenCode session id is required"}) + return + } + sessionID := query.SessionID + if _, found, err := registry.OperatorSession(ctx, sessionID); err != nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) + return + } else if !found { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "session " + sessionID + " is not an operator chat session"}) + return + } + if err := registry.ReopenOperatorSession(ctx, sessionID); err != nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) + return + } + session, found, err := registry.OperatorSession(ctx, sessionID) + if err != nil { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: err.Error()}) + return + } + if !found { + _ = write(protocol.Message{Type: protocol.Error, ID: request.ID, Error: "session " + sessionID + " is no longer an operator session"}) + return + } + wire := chatSessionFromOperator(session) + response := protocol.Message{ + Type: protocol.ChatReopen, + ID: request.ID, + ChatSession: &wire, + } + response.ChatSessions = []protocol.ChatSession{wire} + _ = write(response) +} + +// chatSessionFromOperator projects one registry row to the wire ChatSession the +// app lists, so close/reopen and chat_sessions agree on the closed fields. The +// id is always set; title/directory/tag are copied verbatim, and the closed +// state comes from closed_at. +func chatSessionFromOperator(session pipeline.OperatorSession) protocol.ChatSession { + out := protocol.ChatSession{ + ID: session.ID, + Title: strings.TrimSpace(session.Title), + Directory: session.Directory, + Tag: session.Tag, + CreatedAt: session.CreatedAt, + UpdatedAt: session.UpdatedAt, + } + if session.ClosedAt > 0 { + out.Closed = true + out.ClosedAt = session.ClosedAt + } + return out +} diff --git a/internal/server/chat_close_test.go b/internal/server/chat_close_test.go new file mode 100644 index 00000000..a88924af --- /dev/null +++ b/internal/server/chat_close_test.go @@ -0,0 +1,313 @@ +package server + +import ( + "strings" + "testing" + + "github.com/coder/websocket/wsjson" + + "git.a-wan.net/alan/pipelines/internal/protocol" +) + +// TestChatCloseRecordsClosedState is the close-records-state evidence: a +// chat_close on a recorded operator session answers with the closed session, sets +// closed_at in the registry and leaves the session listed (as closed) by +// chat_sessions, so every client sees the same state. +func TestChatCloseRecordsClosedState(t *testing.T) { + store := newOperatorStore(t) + broker := scriptedChat() + broker.sessions = []protocol.ChatSession{{ID: "ses_1", Title: "A", Directory: "/work/a"}} + ctx, _, conn := dialChatOptions(t, Options{Chat: broker, OperatorRegistry: store}) + if err := store.RecordOperatorSession(ctx, "ses_1", "/work/a", "A", protocol.ChatSessionTagOperator); err != nil { + t.Fatal(err) + } + if err := wsjson.Write(ctx, conn, protocol.Message{Type: protocol.ChatClose, ID: "cl1", ChatQuery: &protocol.ChatQuery{SessionID: "ses_1"}}); err != nil { + t.Fatal(err) + } + var response protocol.Message + if err := wsjson.Read(ctx, conn, &response); err != nil { + t.Fatal(err) + } + if response.Type != protocol.ChatClose || response.ID != "cl1" { + t.Fatalf("chat_close response = %+v", response) + } + if response.ChatSession == nil || !response.ChatSession.Closed || response.ChatSession.ClosedAt <= 0 { + t.Fatalf("closed session not reported: %+v", response.ChatSession) + } + if response.ChatClose == nil || response.ChatClose.SessionID != "ses_1" || response.ChatClose.ClosedAt <= 0 { + t.Fatalf("chat_close result = %+v", response.ChatClose) + } + if response.ChatClose.Interrupted { + t.Fatalf("idle session reported an interrupted turn: %+v", response.ChatClose) + } + if _, interrupts, _ := broker.counts(); interrupts != 0 { + t.Fatalf("idle close interrupted a turn: %d", interrupts) + } + rows, err := store.OperatorSessions(ctx) + if err != nil { + t.Fatal(err) + } + if len(rows) != 1 || rows[0].ClosedAt <= 0 { + t.Fatalf("registry did not record the closed state: %+v", rows) + } + + // The list still carries the session, marked closed, so it is reachable as + // history rather than disappearing. + if err := wsjson.Write(ctx, conn, protocol.Message{Type: protocol.ChatSessions, ID: "l1"}); err != nil { + t.Fatal(err) + } + if err := wsjson.Read(ctx, conn, &response); err != nil { + t.Fatal(err) + } + if response.Type != protocol.ChatSessions || len(response.ChatSessions) != 1 { + t.Fatalf("chat_sessions = %+v", response) + } + if !response.ChatSessions[0].Closed || response.ChatSessions[0].ClosedAt <= 0 { + t.Fatalf("closed session not listed as closed: %+v", response.ChatSessions[0]) + } +} + +// TestChatCloseStopsRunningTurn is the close-stops-a-running-turn evidence: a +// prompt holds the session (its stream is live), and chat_close from another +// connection interrupts it through the existing broker interrupt and reports that +// a turn was stopped. +func TestChatCloseStopsRunningTurn(t *testing.T) { + store := newOperatorStore(t) + broker := scriptedChat() + broker.block = true + broker.started = make(chan struct{}) + broker.done = make(chan struct{}) + ctx, _, conns := dialChatConns(t, Options{Chat: broker, OperatorRegistry: store}, 2) + if err := store.RecordOperatorSession(ctx, "ses_1", "/work/a", "A", protocol.ChatSessionTagOperator); err != nil { + t.Fatal(err) + } + // Start a long-running turn on the first connection. + if err := wsjson.Write(ctx, conns[0], protocol.Message{Type: protocol.ChatPrompt, ID: "r1", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "long running"}}); err != nil { + t.Fatal(err) + } + var ack protocol.Message + if err := wsjson.Read(ctx, conns[0], &ack); err != nil { + t.Fatal(err) + } + if ack.Type != protocol.ChatPrompt { + t.Fatalf("prompt ack = %+v", ack) + } + <-broker.started + + // Close from the second connection; it must interrupt the running turn. + if err := wsjson.Write(ctx, conns[1], protocol.Message{Type: protocol.ChatClose, ID: "cl1", ChatQuery: &protocol.ChatQuery{SessionID: "ses_1"}}); err != nil { + t.Fatal(err) + } + var response protocol.Message + if err := wsjson.Read(ctx, conns[1], &response); err != nil { + t.Fatal(err) + } + if response.Type != protocol.ChatClose || response.ID != "cl1" { + t.Fatalf("chat_close response = %+v", response) + } + if response.ChatClose == nil || !response.ChatClose.Interrupted { + t.Fatalf("close did not record a stopped turn: %+v", response.ChatClose) + } + if _, interrupts, _ := broker.counts(); interrupts != 1 { + t.Fatalf("interrupts = %d, want 1", interrupts) + } + rows, err := store.OperatorSessions(ctx) + if err != nil { + t.Fatal(err) + } + if len(rows) != 1 || rows[0].ClosedAt <= 0 { + t.Fatalf("registry did not record the closed state: %+v", rows) + } +} + +// TestChatCloseKeepsSessionAndMessages pins that closing deletes nothing: the +// registry row survives (only its closed_at changes) and the session's history is +// still readable afterwards. +func TestChatCloseKeepsSessionAndMessages(t *testing.T) { + store := newOperatorStore(t) + broker := scriptedChat() + broker.messages = []protocol.ChatMessage{{ID: "m1", SessionID: "ses_1", Role: protocol.ChatRoleUser}} + ctx, _, conn := dialChatOptions(t, Options{Chat: broker, OperatorRegistry: store}) + if err := store.RecordOperatorSession(ctx, "ses_1", "/work/a", "A", protocol.ChatSessionTagOperator); err != nil { + t.Fatal(err) + } + before, err := store.OperatorSessions(ctx) + if err != nil { + t.Fatal(err) + } + if err := wsjson.Write(ctx, conn, protocol.Message{Type: protocol.ChatClose, ID: "cl1", ChatQuery: &protocol.ChatQuery{SessionID: "ses_1"}}); err != nil { + t.Fatal(err) + } + var response protocol.Message + if err := wsjson.Read(ctx, conn, &response); err != nil { + t.Fatal(err) + } + if response.Type != protocol.ChatClose { + t.Fatalf("close failed: %+v", response) + } + after, err := store.OperatorSessions(ctx) + if err != nil { + t.Fatal(err) + } + if len(after) != 1 || after[0].ID != before[0].ID || after[0].Directory != before[0].Directory || + after[0].Title != before[0].Title || after[0].Tag != before[0].Tag || after[0].CreatedAt != before[0].CreatedAt { + t.Fatalf("close changed the session beyond closed_at:\nbefore %+v\nafter %+v", before[0], after[0]) + } + // The transcript is still readable. + if err := wsjson.Write(ctx, conn, protocol.Message{Type: protocol.ChatMessages, ID: "ms1", ChatQuery: &protocol.ChatQuery{SessionID: "ses_1"}}); err != nil { + t.Fatal(err) + } + if err := wsjson.Read(ctx, conn, &response); err != nil { + t.Fatal(err) + } + if response.Type != protocol.ChatMessages || len(response.ChatMessages) != 1 || response.ChatMessages[0].ID != "m1" { + t.Fatalf("history lost after close: %+v", response) + } + if calls, _, _ := broker.messageQuery(); calls != 1 { + t.Fatalf("message reads = %d, want 1", calls) + } +} + +// TestChatReopenClearsClosedState pins that chat_reopen is the inverse of +// chat_close: the closed state is cleared and the session is listed as active +// again. +func TestChatReopenClearsClosedState(t *testing.T) { + store := newOperatorStore(t) + broker := scriptedChat() + ctx, _, conn := dialChatOptions(t, Options{Chat: broker, OperatorRegistry: store}) + if err := store.RecordOperatorSession(ctx, "ses_1", "/work/a", "A", protocol.ChatSessionTagOperator); err != nil { + t.Fatal(err) + } + if err := store.CloseOperatorSession(ctx, "ses_1"); err != nil { + t.Fatal(err) + } + if err := wsjson.Write(ctx, conn, protocol.Message{Type: protocol.ChatReopen, ID: "op1", ChatQuery: &protocol.ChatQuery{SessionID: "ses_1"}}); err != nil { + t.Fatal(err) + } + var response protocol.Message + if err := wsjson.Read(ctx, conn, &response); err != nil { + t.Fatal(err) + } + if response.Type != protocol.ChatReopen || response.ID != "op1" || response.ChatSession == nil { + t.Fatalf("chat_reopen response = %+v", response) + } + if response.ChatSession.Closed || response.ChatSession.ClosedAt != 0 { + t.Fatalf("reopened session still closed: %+v", response.ChatSession) + } + rows, err := store.OperatorSessions(ctx) + if err != nil { + t.Fatal(err) + } + if len(rows) != 1 || rows[0].ClosedAt != 0 { + t.Fatalf("registry still closed after reopen: %+v", rows) + } +} + +// TestChatPromptReopensClosedSession pins the second reopen path: simply +// prompting a closed session clears its closed state, so the operator never has +// to make an explicit reopen request. +func TestChatPromptReopensClosedSession(t *testing.T) { + store := newOperatorStore(t) + broker := scriptedChat() + ctx, _, conn := dialChatOptions(t, Options{Chat: broker, OperatorRegistry: store}) + if err := store.RecordOperatorSession(ctx, "ses_1", "/work/a", "A", protocol.ChatSessionTagOperator); err != nil { + t.Fatal(err) + } + if err := store.CloseOperatorSession(ctx, "ses_1"); err != nil { + t.Fatal(err) + } + if err := wsjson.Write(ctx, conn, protocol.Message{Type: protocol.ChatPrompt, ID: "r1", ChatPrompt: &protocol.ChatPromptRequest{SessionID: "ses_1", Text: "resume"}}); err != nil { + t.Fatal(err) + } + var ack protocol.Message + if err := wsjson.Read(ctx, conn, &ack); err != nil { + t.Fatal(err) + } + if ack.Type != protocol.ChatPrompt { + t.Fatalf("prompt ack = %+v", ack) + } + _ = readChatTurn(t, ctx, conn) + rows, err := store.OperatorSessions(ctx) + if err != nil { + t.Fatal(err) + } + if len(rows) != 1 || rows[0].ClosedAt != 0 { + t.Fatalf("prompting did not clear the closed state: %+v", rows) + } +} + +// TestChatCloseRefusesNonOperatorSession pins that a pipeline-owned run session +// (which has no operator_sessions row) is refused and nothing is written, so the +// close never touches the sessions the pipelines own. +func TestChatCloseRefusesNonOperatorSession(t *testing.T) { + store := newOperatorStore(t) + broker := scriptedChat() + ctx, _, conn := dialChatOptions(t, Options{Chat: broker, OperatorRegistry: store}) + if err := wsjson.Write(ctx, conn, protocol.Message{Type: protocol.ChatClose, ID: "cl1", ChatQuery: &protocol.ChatQuery{SessionID: "ses_run"}}); err != nil { + t.Fatal(err) + } + var response protocol.Message + if err := wsjson.Read(ctx, conn, &response); err != nil { + t.Fatal(err) + } + if response.Type != protocol.Error || !strings.Contains(response.Error, "not an operator") { + t.Fatalf("non-operator session not refused: %+v", response) + } + if _, interrupts, _ := broker.counts(); interrupts != 0 { + t.Fatalf("refused close still interrupted: %d", interrupts) + } + rows, err := store.OperatorSessions(ctx) + if err != nil { + t.Fatal(err) + } + if len(rows) != 0 { + t.Fatalf("refused close wrote a registry row: %+v", rows) + } +} + +// TestChatCloseRejectsInvalidInput pins that a missing/invalid session id and an +// unconfigured broker/registry are answered with an error before any write. +func TestChatCloseRejectsInvalidInput(t *testing.T) { + store := newOperatorStore(t) + broker := scriptedChat() + ctx, _, conn := dialChatOptions(t, Options{Chat: broker, OperatorRegistry: store}) + for _, query := range []*protocol.ChatQuery{nil, {}, {SessionID: "not-a-session"}} { + if err := wsjson.Write(ctx, conn, protocol.Message{Type: protocol.ChatClose, ID: "bad", ChatQuery: query}); err != nil { + t.Fatal(err) + } + var response protocol.Message + if err := wsjson.Read(ctx, conn, &response); err != nil { + t.Fatal(err) + } + if response.Type != protocol.Error || response.ID != "bad" { + t.Fatalf("query %+v not rejected: %+v", query, response) + } + } + + // No registry configured: refuse rather than close nothing. + noRegCtx, cancelNoReg, noRegConn := dialChatOptions(t, Options{Chat: broker}) + defer cancelNoReg() + if err := wsjson.Write(noRegCtx, noRegConn, protocol.Message{Type: protocol.ChatClose, ID: "nr", ChatQuery: &protocol.ChatQuery{SessionID: "ses_1"}}); err != nil { + t.Fatal(err) + } + var response protocol.Message + if err := wsjson.Read(noRegCtx, noRegConn, &response); err != nil { + t.Fatal(err) + } + if response.Type != protocol.Error || !strings.Contains(response.Error, "registry") { + t.Fatalf("close without registry = %+v", response) + } + + // No broker configured: the existing "not configured" error. + noBrokerCtx, cancelNoBroker, noBrokerConn := dialChatOptions(t, Options{OperatorRegistry: store}) + defer cancelNoBroker() + if err := wsjson.Write(noBrokerCtx, noBrokerConn, protocol.Message{Type: protocol.ChatClose, ID: "nb", ChatQuery: &protocol.ChatQuery{SessionID: "ses_1"}}); err != nil { + t.Fatal(err) + } + if err := wsjson.Read(noBrokerCtx, noBrokerConn, &response); err != nil { + t.Fatal(err) + } + if response.Type != protocol.Error || !strings.Contains(response.Error, "not configured") { + t.Fatalf("close without broker = %+v", response) + } +} diff --git a/internal/server/chat_sessions.go b/internal/server/chat_sessions.go index 4a0d034c..17efafbf 100644 --- a/internal/server/chat_sessions.go +++ b/internal/server/chat_sessions.go @@ -74,6 +74,11 @@ func handleChatSessions(ctx context.Context, request protocol.Message, broker ch session.Tag = operator.Tag session.CreatedAt = operator.CreatedAt session.UpdatedAt = operator.UpdatedAt + // The closed state comes from the registry, so every client sees the same + // thing; a closed session stays in the list (the app groups it as history) + // rather than disappearing. + session.Closed = operator.ClosedAt > 0 + session.ClosedAt = operator.ClosedAt session.Busy = hub.busyForOther(operator.ID, clientID) response.ChatSessions = append(response.ChatSessions, session) }