@imagile-dev/toil-ui 0.1.0-alpha.2 → 0.1.0-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/NOTICE +12 -5
- package/README.md +657 -55
- package/dist/app/assets/Graph-BG4Q-CNd.js +7 -0
- package/dist/app/assets/PowershellMan-24GyLAoI.js +1 -0
- package/dist/app/assets/PowershellMan-Ic3-jSrq.css +1 -0
- package/dist/app/assets/basket-Cj-ZPWsU.svg +73 -0
- package/dist/app/assets/bitter-latin-400-normal-B_gsCfHZ.woff +0 -0
- package/dist/app/assets/bitter-latin-400-normal-Cl9vToDR.woff2 +0 -0
- package/dist/app/assets/bitter-latin-600-normal-B6efaj8C.woff2 +0 -0
- package/dist/app/assets/bitter-latin-600-normal-Bm9hnW4x.woff +0 -0
- package/dist/app/assets/boot-sheet-C9B_iXU-.webp +0 -0
- package/dist/app/assets/chakra-petch-latin-600-normal-DQKfcdKo.woff +0 -0
- package/dist/app/assets/chakra-petch-latin-600-normal-DVQm9bgb.woff2 +0 -0
- package/dist/app/assets/chakra-petch-latin-700-normal-CnDBPjkL.woff2 +0 -0
- package/dist/app/assets/chakra-petch-latin-700-normal-D1s_c2du.woff +0 -0
- package/dist/app/assets/chakra-petch-latin-ext-600-normal-CdGvbdDU.woff2 +0 -0
- package/dist/app/assets/chakra-petch-latin-ext-600-normal-nL80L4xU.woff +0 -0
- package/dist/app/assets/chakra-petch-latin-ext-700-normal-BeviJPUl.woff +0 -0
- package/dist/app/assets/chakra-petch-latin-ext-700-normal-DAkvJhej.woff2 +0 -0
- package/dist/app/assets/chakra-petch-thai-600-normal-BiM5MXH8.woff +0 -0
- package/dist/app/assets/chakra-petch-thai-600-normal-C620THcd.woff2 +0 -0
- package/dist/app/assets/chakra-petch-thai-700-normal-B7WL5pBr.woff2 +0 -0
- package/dist/app/assets/chakra-petch-thai-700-normal-vZLZ_5L8.woff +0 -0
- package/dist/app/assets/chakra-petch-vietnamese-600-normal-Pvj4qcw_.woff +0 -0
- package/dist/app/assets/chakra-petch-vietnamese-600-normal-YQPWIhHU.woff2 +0 -0
- package/dist/app/assets/chakra-petch-vietnamese-700-normal-ZDCXY9IA.woff2 +0 -0
- package/dist/app/assets/chakra-petch-vietnamese-700-normal-gQuUA8Wu.woff +0 -0
- package/dist/app/assets/crate-loading-B9H4D652.webp +0 -0
- package/dist/app/assets/crate-lost-Dk5CaIuV.webp +0 -0
- package/dist/app/assets/dead-drop-BHoO7uon.webp +0 -0
- package/dist/app/assets/depot-BjEccEGj.webp +0 -0
- package/dist/app/assets/door-open-CL1v6qnp.svg +4 -0
- package/dist/app/assets/dungeon-map-Beqcufkh.webp +0 -0
- package/dist/app/assets/dungeon-map-T2FZ-7n0.webp +0 -0
- package/dist/app/assets/empty-room-BvPyqrlb.webp +0 -0
- package/dist/app/assets/{favicon-D8c5IAlv.svg → favicon-pNvr4nr7.svg} +5 -11
- package/dist/app/assets/fira-code-cyrillic-600-normal-BD56RyRT.woff +0 -0
- package/dist/app/assets/fira-code-cyrillic-600-normal-CPRdbepc.woff2 +0 -0
- package/dist/app/assets/fira-code-cyrillic-ext-600-normal-B9wE0zmr.woff2 +0 -0
- package/dist/app/assets/fira-code-cyrillic-ext-600-normal-DldcyWhZ.woff +0 -0
- package/dist/app/assets/fira-code-greek-600-normal-D_h3X2X5.woff +0 -0
- package/dist/app/assets/fira-code-greek-600-normal-Dxp52_By.woff2 +0 -0
- package/dist/app/assets/fira-code-greek-ext-600-normal-C-cQDoOk.woff +0 -0
- package/dist/app/assets/fira-code-greek-ext-600-normal-DtBpFRLc.woff2 +0 -0
- package/dist/app/assets/fira-code-latin-600-normal-BmSSHshu.woff +0 -0
- package/dist/app/assets/fira-code-latin-600-normal-CvYZpPHg.woff2 +0 -0
- package/dist/app/assets/fira-code-latin-ext-600-normal-0PFQL1eg.woff +0 -0
- package/dist/app/assets/fira-code-latin-ext-600-normal-Cb7jxoAi.woff2 +0 -0
- package/dist/app/assets/fira-code-symbols2-600-normal-Bu3RnO39.woff2 +0 -0
- package/dist/app/assets/fira-code-symbols2-600-normal-Dvq6IQE5.woff +0 -0
- package/dist/app/assets/fredoka-latin-ext-600-normal-BExgZzUO.woff +0 -0
- package/dist/app/assets/fredoka-latin-ext-600-normal-GoyidTAB.woff2 +0 -0
- package/dist/app/assets/gate-DgvMBPi9.svg +109 -0
- package/dist/app/assets/gauge-sheet-ZMjQ7TPd.svg +1 -0
- package/dist/app/assets/index-BZCjoilm.js +66 -0
- package/dist/app/assets/index-DNYTmC1J.css +1 -0
- package/dist/app/assets/jack-in-Cs60f1qu.webp +0 -0
- package/dist/app/assets/locked-door-CdXyTY3n.svg +4 -0
- package/dist/app/assets/locomotive-CPPtBzL2.webp +0 -0
- package/dist/app/assets/overworld-W3adxmKX.webp +0 -0
- package/dist/app/assets/press-start-2p-latin-400-normal-KLytu4cr.woff +0 -0
- package/dist/app/assets/press-start-2p-latin-400-normal-_wFEWmAB.woff2 +0 -0
- package/dist/app/assets/rye-latin-400-normal-CPBiwIfN.woff +0 -0
- package/dist/app/assets/rye-latin-400-normal-CnIDrDaJ.woff2 +0 -0
- package/dist/app/assets/sage-cave-Bu8KEIPH.webp +0 -0
- package/dist/app/assets/sensor-sheet-Dn-dKnev.svg +1 -0
- package/dist/app/assets/shard-sheet-NpLu-BuT.svg +101 -0
- package/dist/app/assets/skyline-CZ4WZ55S.webp +0 -0
- package/dist/app/assets/splash-Dgll39Db.webp +0 -0
- package/dist/app/assets/splash-hOSg5Qrh.webp +0 -0
- package/dist/app/assets/sprites-BUKsxG6N.webp +0 -0
- package/dist/app/assets/sprout-sheet-BLjjvTMl.svg +143 -0
- package/dist/app/assets/stone-wall-DRNYiEy2.svg +4 -0
- package/dist/app/assets/story-CS6l92Yr.webp +0 -0
- package/dist/app/assets/sun-Cyqqe255.svg +72 -0
- package/dist/app/assets/survey-map-BI4XT_wf.webp +0 -0
- package/dist/app/assets/theme-63MlXwuO.css +1 -0
- package/dist/app/assets/theme-BJDDePbd.css +1 -0
- package/dist/app/assets/theme-BVugNGOi.css +1 -0
- package/dist/app/assets/theme-C_ukluUB.css +1 -0
- package/dist/app/assets/{theme-ofha-KFg.css → theme-D3_AOEgB.css} +1 -1
- package/dist/app/assets/theme-DMjUjC0D.css +1 -0
- package/dist/app/assets/title-1MphWZoQ.webp +0 -0
- package/dist/app/assets/tray-BHNdSAiO.webp +0 -0
- package/dist/app/assets/wanted-poster-BnjUajnc.webp +0 -0
- package/dist/app/assets/warp-BNB4TdQ4.webp +0 -0
- package/dist/app/assets/wood-CrrZEj6Y.webp +0 -0
- package/dist/app/index.html +3 -3
- package/dist/server/toil-ui.js +5629 -1751
- package/package.json +11 -5
- package/dist/app/assets/Graph-X3vfaDBI.js +0 -7
- package/dist/app/assets/candle-ledger-LHVvMHKk.webp +0 -0
- package/dist/app/assets/crate-loading-Dw5rbPVs.webp +0 -0
- package/dist/app/assets/crate-lost-CaqeM6QF.webp +0 -0
- package/dist/app/assets/index-CVbMaY02.js +0 -51
- package/dist/app/assets/index-DjyOI2P3.css +0 -1
- package/dist/app/assets/pallets-rO-RsztZ.webp +0 -0
- package/dist/app/assets/racking-BI-9puyv.webp +0 -0
- package/dist/app/assets/theme-94QYOO7U.css +0 -1
- package/dist/app/assets/theme-DNLvgU8q.css +0 -1
package/README.md
CHANGED
|
@@ -5,13 +5,15 @@ A local web app for seeing work across Jira, Azure DevOps and GitHub, read throu
|
|
|
5
5
|
with its stories, pull requests, builds and deployments side by side, a pull
|
|
6
6
|
requests view for what is waiting on review, and a daily worklog of what happened.
|
|
7
7
|
|
|
8
|
-
**Status:
|
|
8
|
+
**Status: beta, local only.** It runs on your own machine, binds loopback, and
|
|
9
9
|
reads through toil with your own connections and dossiers, read-only. Its
|
|
10
|
-
settings pages
|
|
11
|
-
connections and dossiers. The worklog keeps its pages and the notes you add in its own
|
|
10
|
+
settings pages, and a dossier's name and description edited in place, are the only
|
|
11
|
+
places it changes anything of toil's, and only toil's own connections and dossiers. The worklog keeps its pages and the notes you add in its own
|
|
12
12
|
data folder, and writes anywhere else only when you export a page. Its Feedback dialog sends a report to Imagile through
|
|
13
13
|
`toil feedback`, only when you approve it. It is a separate package from toil: installing toil
|
|
14
|
-
never installs it.
|
|
14
|
+
never installs it. toil's beta commitment to stable commands, flags and output doesn't
|
|
15
|
+
cover Toil UI: its screens, and its server's HTTP API, which is internal to the
|
|
16
|
+
package, can change from one beta to the next.
|
|
15
17
|
|
|
16
18
|
## Start it
|
|
17
19
|
|
|
@@ -19,7 +21,7 @@ never installs it.
|
|
|
19
21
|
npx @imagile-dev/toil-ui
|
|
20
22
|
```
|
|
21
23
|
|
|
22
|
-
It needs Node 24.
|
|
24
|
+
It needs Node 24.22.1 or later on 24.x, or 26.12.1 or later, as toil does, and installs one dependency, `@imagile-dev/toil`, at
|
|
23
25
|
the exact version it was built with. Until a version shows on
|
|
24
26
|
[npm](https://www.npmjs.com/package/@imagile-dev/toil-ui), run it from a clone of
|
|
25
27
|
the repository:
|
|
@@ -33,8 +35,8 @@ node ui/dist/server/toil-ui.js
|
|
|
33
35
|
It prints one URL and keeps running until you press Ctrl+C:
|
|
34
36
|
|
|
35
37
|
```text
|
|
36
|
-
Toil UI 0.1.0-
|
|
37
|
-
Syncing through toil, read-only, with your own connections and dossiers. Only its Settings pages change anything: toil's own connections and dossiers, when you ask. The worklog keeps its pages and your notes in its data folder, and writes anywhere else only when you export one. Feedback goes to Imagile only when you send it.
|
|
38
|
+
Toil UI 0.1.0-beta.1 (beta, local only), on toil 0.1.0-beta.1
|
|
39
|
+
Syncing through toil, read-only, with your own connections and dossiers. Only its Settings pages, and a dossier's name and description edited in place, change anything: toil's own connections and dossiers, when you ask. The worklog keeps its pages and your notes in its data folder, and writes anywhere else only when you export one. Feedback goes to Imagile only when you send it.
|
|
38
40
|
The cache is /home/you/.toil-ui/cache/toil-ui.db, kept 30 days after each sync; toil-ui wipe deletes it.
|
|
39
41
|
|
|
40
42
|
Open this URL in your browser. It carries this launch's token, so keep it to yourself:
|
|
@@ -46,8 +48,25 @@ token leaves the address bar. A reloaded page forgets its session, so open the U
|
|
|
46
48
|
again to get back in. Each start prints a new token. Toil UI opens no browser
|
|
47
49
|
itself.
|
|
48
50
|
|
|
49
|
-
`toil-ui --sample` serves the sample dossiers and the scripted agent
|
|
50
|
-
|
|
51
|
+
`toil-ui --sample` serves the sample dossiers and the scripted agent that
|
|
52
|
+
[the site's Toil UI page](https://imagile-dev.github.io/toil/ui/) runs on, with
|
|
53
|
+
nothing connected to a tracker.
|
|
54
|
+
|
|
55
|
+
## First run
|
|
56
|
+
|
|
57
|
+
Until you have a dossier and it has synced once, the Dossiers view shows a short
|
|
58
|
+
checklist in place of the empty page:
|
|
59
|
+
|
|
60
|
+
1. **Connect a tracker** opens Settings, Connections at the add form.
|
|
61
|
+
2. **Create a dossier** opens Settings, Dossiers at Create a dossier.
|
|
62
|
+
3. **Sync** starts the first sync, as the Sync panel's Sync now does.
|
|
63
|
+
|
|
64
|
+
Each step ticks itself off from toil's own state: `toil connections list` for a
|
|
65
|
+
connection to Jira, Azure DevOps or GitHub (one made by env vars counts), `toil
|
|
66
|
+
dossiers list` for a dossier, and the Sync panel for the sync. Beside the steps,
|
|
67
|
+
**Try the sample data** shows `npx @imagile-dev/toil-ui --sample` with a Copy
|
|
68
|
+
button, to restart Toil UI on the sample dossiers. The checklist goes once the first
|
|
69
|
+
sync finishes. Each step's (i) explains it and links to these docs.
|
|
51
70
|
|
|
52
71
|
## What it reads
|
|
53
72
|
|
|
@@ -65,10 +84,183 @@ in-process through `@imagile-dev/toil/api`, read-only, and toil's audit log
|
|
|
65
84
|
records it with `via: "api"` and `caller: "toil-ui"`. A call that fails shows on
|
|
66
85
|
its own panel with toil's message and fix.
|
|
67
86
|
|
|
87
|
+
## The Dossiers view
|
|
88
|
+
|
|
89
|
+
Toil UI opens on its dossiers, one card each, read from the same data the dashboards
|
|
90
|
+
read, so it asks no tracker anything: in the local app that is the cache a sync
|
|
91
|
+
filled, plus `dossiers list` and `dossiers show` for the dossiers themselves.
|
|
92
|
+
|
|
93
|
+
- **What each card shows:** the current sprint with its working days left, points
|
|
94
|
+
done and a small burn-up; how many items are in progress and blocked, and how many
|
|
95
|
+
pull requests wait on a review; the people with work in it, as avatars; its sources
|
|
96
|
+
as badges; when it was last synced; and how many work items and pull requests
|
|
97
|
+
changed since this browser last opened its dashboard.
|
|
98
|
+
- **Which card leads:** the dossier opened most recently in this browser, or, before
|
|
99
|
+
any was opened, the one with the most in motion (in progress, blocked and waiting on
|
|
100
|
+
review together), takes two columns where they fit. On a wide screen the grid goes
|
|
101
|
+
wider than the dashboards and fits more cards across; at 375px it is one column.
|
|
102
|
+
- **What this browser remembers:** when each dashboard was last opened, in
|
|
103
|
+
`localStorage`, never sent anywhere. Without it (a private window) the cards just
|
|
104
|
+
say nothing about "since".
|
|
105
|
+
- **A dossier's top row** uses the same parts: the description beside the name, the
|
|
106
|
+
sources as badges, and the sprint's day (The dossier page, below).
|
|
107
|
+
|
|
108
|
+
### Renaming and describing a dossier
|
|
109
|
+
|
|
110
|
+
The name and the description have a pencil beside them, on the card and in the
|
|
111
|
+
dossier's top row. It opens an inline field: Enter saves through
|
|
112
|
+
`toil dossiers describe <dossier> --name <new name>` or `--description <text>`, run
|
|
113
|
+
on the settings pages' path (below), so toil's own checks apply and the change is in
|
|
114
|
+
its audit log as `caller: "toil-ui"`. Escape cancels, and a refusal shows toil's
|
|
115
|
+
message and fix under the field. Only a dossier in your own folder can be renamed or
|
|
116
|
+
described; a checked-in one is refused with the `toil dossiers import` fix.
|
|
117
|
+
|
|
118
|
+
A rename keeps everything Toil UI holds for the dossier: the server moves its cache
|
|
119
|
+
(responses, items, history, sources, sync runs, notes and agent runs), its assignments
|
|
120
|
+
and its worklog pages to the new name once toil has renamed the file, so its
|
|
121
|
+
dashboard opens straight away with no new sync. A rename waits, refused with a
|
|
122
|
+
message, while a sync or an assignment of that dossier is running, since both read it
|
|
123
|
+
by name as they go. What can't be moved is said beside toil's result, and the next
|
|
124
|
+
sync reads the dossier afresh under its new name.
|
|
125
|
+
|
|
126
|
+
## The dossier page
|
|
127
|
+
|
|
128
|
+
A dossier opens on its **Overview**, in a frame all of its pages share:
|
|
129
|
+
|
|
130
|
+
- **The top row:** its name, with the pencil that renames it; **Switch**, for another
|
|
131
|
+
dossier or the Dossiers view; the sprint and its day; its description, cut to one
|
|
132
|
+
line with the whole of it in its tooltip, and its sources; and the Ask bar with
|
|
133
|
+
**Analyze** (The agent, below).
|
|
134
|
+
- **The tabs**, one address each: **Overview** (`#/dossier/<name>`), **Board**
|
|
135
|
+
(`/board`, with how many of its cards need attention), **Dependencies**
|
|
136
|
+
(`/dependencies`), **Pull requests** (`/prs`), **People** (`/people`), **Worklog**
|
|
137
|
+
(`/worklog`) and **Analyses** (`/analyses`). The Command Center (`/command-center`)
|
|
138
|
+
is the Board tab's **Readiness** view, the stand-up is the Worklog's, and an item's
|
|
139
|
+
page sits under Board, so every address from before the tabs still opens. On a
|
|
140
|
+
narrow screen the tabs scroll sideways.
|
|
141
|
+
- **The Agents sidebar**, beside every tab from 1200px wide, and a drawer behind the
|
|
142
|
+
**Agents** button below that: the tracker's inbox, then the dossier's assignments
|
|
143
|
+
in three groups (those that need you, those working, and those gone stale), with the
|
|
144
|
+
finished ones under **Earlier**; then **Renew all stale**, the **Limits**, and this
|
|
145
|
+
dossier's three newest analyses, each linking to it (Assigning work to an agent, below).
|
|
146
|
+
- **Analyses** lists every Analyze kept for the dossier, newest first: when it was made,
|
|
147
|
+
the adapter and model that wrote it, its one-line recommendation, and what changed
|
|
148
|
+
since the one before (items newly blocked or blocked by something new, blockers
|
|
149
|
+
cleared, points moved on an item or in the sprint, items newly cited or no longer
|
|
150
|
+
cited, a new recommendation). What changed is worked out by code, from a snapshot of
|
|
151
|
+
the dossier's items each analysis keeps, never by asking the agent. **Open** reads one
|
|
152
|
+
again at its own address (`/analyses/<id>`), top-down like the chat, with its
|
|
153
|
+
suggested changes and what it used. The server keeps them in the cache (Sync and the
|
|
154
|
+
cache, below), so they outlast a reload and a restart; with `--sample`,
|
|
155
|
+
card-payments starts with two, kept in memory for the run.
|
|
156
|
+
|
|
157
|
+
### The Overview
|
|
158
|
+
|
|
159
|
+
The Overview puts the answer first, then the reasons, then the evidence, and fits a
|
|
160
|
+
1440 by 900 screen without scrolling:
|
|
161
|
+
|
|
162
|
+
1. **The recommendation:** the one thing to do first. When the dossier has a
|
|
163
|
+
current analysis (made since the data was read, or the same UTC day), it is the
|
|
164
|
+
latest Analyze's recommendation, with when it was made, who wrote it and a link to
|
|
165
|
+
it. Without one (none yet, the latest had no Recommendation line, or it is older
|
|
166
|
+
than the data, which the card links to), it is worked out by code from what the dossier already holds, with no agent
|
|
167
|
+
call (`ui/src/model/recommend.ts`), and says what it read. The card says which of
|
|
168
|
+
the two it is. The key issues under it are always the code's.
|
|
169
|
+
2. **Three key issues**, each with its tickets as chips, every one showing its key,
|
|
170
|
+
title and status, and a link to the tab that has the rest.
|
|
171
|
+
3. **The metrics as sparklines:** burn-up, throughput, cycle time, aging work in
|
|
172
|
+
progress and pull request wait, each with its figure. Pressing one opens its full
|
|
173
|
+
chart, with its figures in a table and what it couldn't compute.
|
|
174
|
+
4. **The blockers in brief:** the critical chain as a compact Gantt on the sprint's
|
|
175
|
+
timeline, with its points and a link to the Dependencies tab, which has every
|
|
176
|
+
blocker (The Dependencies tab, below).
|
|
177
|
+
|
|
178
|
+
The key issues come from six checks, each with a fixed weight, so blockers always come
|
|
179
|
+
first and work not yet started comes last. Within a kind, more tickets outrank fewer.
|
|
180
|
+
|
|
181
|
+
| Issue | Raised when | Its tab |
|
|
182
|
+
|---|---|---|
|
|
183
|
+
| Blocked | An open item is blocked by another open one. The blocker holding the most, counting chains, is the one to clear first | Dependencies |
|
|
184
|
+
| Builds failing | An open item's latest build failed | Board |
|
|
185
|
+
| Points left | The sprint's pace so far (points done per working day) won't finish the points left in the days left | Board |
|
|
186
|
+
| Pull requests waiting | An open pull request has waited on review 2 working days or more, or its checks have failed for over a day | Pull requests |
|
|
187
|
+
| Aging | An item has been in progress longer than 85% of finished items took, or has had no update for more than 5 days | Board |
|
|
188
|
+
| Not ready | Work not started in the sprint fails the readiness gate (Readiness and the Command Center, below) | Board |
|
|
189
|
+
|
|
190
|
+
The recommendation is the heaviest issue's action. With none raised, it says to keep
|
|
191
|
+
going, and why.
|
|
192
|
+
|
|
193
|
+
### The Dependencies tab
|
|
194
|
+
|
|
195
|
+
The Dependencies tab opens on the **blocker timeline**, a Gantt chart of every item that
|
|
196
|
+
blocks another or is blocked, on the current sprint's dates, then the dependency graph.
|
|
197
|
+
|
|
198
|
+
- **Each item is a bar.** A solid segment is its time in progress, from its
|
|
199
|
+
transitions. A hatched, outlined segment is its time blocked, from its `blocks`
|
|
200
|
+
links until the blocker finished. A thin strip under the bar is its failing checks,
|
|
201
|
+
from the first of its open pull requests' latest run of failed builds, or the pull
|
|
202
|
+
request's own failing checks. A tick after the bar means it is done, and a blocker
|
|
203
|
+
not started yet says so in place of a bar. Each mark
|
|
204
|
+
differs by its shape as well as its colour, and the key above the chart draws each
|
|
205
|
+
one.
|
|
206
|
+
- **Arrows join each blocker to what waits on it**, pointing at the item that waits.
|
|
207
|
+
A dashed arrow is a wait that is over: the blocker is done. A dotted line marks today.
|
|
208
|
+
- **The critical chain** is the chain of open blockers holding the most points (the
|
|
209
|
+
longest chain when nothing on any chain has points). Its rows carry a diamond and
|
|
210
|
+
its arrows are drawn heavy, and it is named above the chart. The Overview shows it
|
|
211
|
+
alone, in brief.
|
|
212
|
+
- **What is estimated is said, in the chart's note and on each table cell.** No tracker
|
|
213
|
+
toil reads dates a link, so a block is drawn from when both items existed. An item
|
|
214
|
+
whose history records no move into In progress (GitHub records only open and closed)
|
|
215
|
+
is drawn in progress from when it was created. Nothing is fetched for the chart: it
|
|
216
|
+
reads the links, transitions, pull requests, builds and checks the dossier already
|
|
217
|
+
synced, and the readiness gate's verdict for work not started.
|
|
218
|
+
- **The table under the chart lists every bar and every arrow**, with links: each
|
|
219
|
+
item's status and points, its time in progress, blocked (and by what) and with
|
|
220
|
+
checks failing, what it waits on, whether it is on the critical chain, and whether
|
|
221
|
+
it is ready to start. The chart is an image with a summary for a screen reader; the
|
|
222
|
+
table is its accessible equivalent, so the bars themselves aren't focusable.
|
|
223
|
+
- **On a narrow screen** the chart keeps its smallest width and scrolls sideways in its
|
|
224
|
+
own scroller, which can be focused and scrolled with the keyboard, with a line above
|
|
225
|
+
it saying so; the page itself never scrolls sideways.
|
|
226
|
+
|
|
227
|
+
### The board
|
|
228
|
+
|
|
229
|
+
The Board tab flags each card that needs attention, with a flag beside its status and
|
|
230
|
+
an edge in the warning colour: anything that needs action now or a look (Insights,
|
|
231
|
+
below), but not what is only worth knowing. **Needs attention only** narrows the board
|
|
232
|
+
to those cards, and the tab carries how many there are. Drag a card to another column,
|
|
233
|
+
or press M on it for its menu, to propose the move: nothing changes until you apply
|
|
234
|
+
the command the proposal shows, and the card stays where its tracker says. Under the board are its
|
|
235
|
+
stories with their pull requests, builds and deployments, then the builds and
|
|
236
|
+
deployments themselves.
|
|
237
|
+
|
|
238
|
+
## Insights
|
|
239
|
+
|
|
240
|
+
The board's cards and its **Needs attention** flag, the flow charts and the Overview's
|
|
241
|
+
key issues mark
|
|
242
|
+
each open work item with its insights, weightiest first, each naming the data it
|
|
243
|
+
rests on (`ui/src/model/insights.ts`). One the data can't support isn't raised at
|
|
244
|
+
all, rather than raised on a guess.
|
|
245
|
+
|
|
246
|
+
| Insight | Means | Weight |
|
|
247
|
+
|---|---|---|
|
|
248
|
+
| Blocked | Another item that isn't done blocks it (its links) | needs action now |
|
|
249
|
+
| Build failing | Its pull request's latest build failed | needs action now |
|
|
250
|
+
| Aging | In progress longer than 85% of the dossier's finished items took; needs at least three cycle times to compare with | needs action now |
|
|
251
|
+
| Deployed, still open | An environment runs it, but it isn't done | needs a look |
|
|
252
|
+
| Carried over | It was in the previous sprint too | needs a look |
|
|
253
|
+
| PR with no build | A pull request for it is open with no build | needs a look |
|
|
254
|
+
| Stale | No update for more than 5 days | needs a look |
|
|
255
|
+
| Blocking | It blocks another item | needs a look |
|
|
256
|
+
| Merged, not deployed | Its pull requests are merged, but no environment runs them yet; only for a dossier that names environments | worth knowing |
|
|
257
|
+
| No estimate | It has no estimate | worth knowing |
|
|
258
|
+
| Added mid-sprint | It joined the sprint after it started | worth knowing |
|
|
259
|
+
|
|
68
260
|
## Pull requests
|
|
69
261
|
|
|
70
|
-
Each dossier has a **Pull requests**
|
|
71
|
-
|
|
262
|
+
Each dossier has a **Pull requests** tab (`#/dossier/<name>/prs`), built from OWI 0.2
|
|
263
|
+
changes:
|
|
72
264
|
|
|
73
265
|
- **Waiting now:** the open pull requests, longest wait first, each with what it
|
|
74
266
|
waits on (review, changes, checks, merge, or a draft its author holds), since when
|
|
@@ -92,7 +284,7 @@ repository's `owner/repo#41`). A code host's section may set author kinds by han
|
|
|
92
284
|
|
|
93
285
|
## People
|
|
94
286
|
|
|
95
|
-
Each dossier has a **People**
|
|
287
|
+
Each dossier has a **People** tab (`#/dossier/<name>/people`), built
|
|
96
288
|
from the same OWI work items and changes as the dashboard and the pull requests view,
|
|
97
289
|
and from the dossier's `people` section, which says who each person is in every
|
|
98
290
|
system (`toil dossiers person`, or **Settings, Dossiers**):
|
|
@@ -101,7 +293,7 @@ system (`toil dossiers person`, or **Settings, Dossiers**):
|
|
|
101
293
|
status with how long each item has sat in it, their open pull requests and what
|
|
102
294
|
each waits on, the reviews waiting on them (oldest first), their blocked items and
|
|
103
295
|
what blocks each, and what they did in the last 14 days. A link opens their items
|
|
104
|
-
on the
|
|
296
|
+
on the Board tab, filtered to them.
|
|
105
297
|
- **A team strip:** work in progress against the dossier's `wipLimit` and who is over
|
|
106
298
|
it, the review queue, and the current sprint's unassigned items.
|
|
107
299
|
- **Agents:** a person with `kind: "agent"`, matched by the same signals as a pull
|
|
@@ -152,7 +344,7 @@ that names none uses `Microsoft.VSTS.Common.AcceptanceCriteria`.
|
|
|
152
344
|
rows, each with where its answer came from. **Check the workflow live** makes the one
|
|
153
345
|
live read, read-only: `jira issue transitions` for a Jira issue, `ado work-item
|
|
154
346
|
states` for an Azure DevOps type. A GitHub issue needs none.
|
|
155
|
-
- **The Command Center** (`#/dossier/<name>/command-center`,
|
|
347
|
+
- **The Command Center** (`#/dossier/<name>/command-center`, the Board tab's Readiness view) lists every
|
|
156
348
|
work item with its verdict and, for each one that isn't ready, the rows that say why.
|
|
157
349
|
It filters by verdict, status, type, assignee and source, and makes no live read.
|
|
158
350
|
It is strict: only ready items are slated, in the dossier's order, under a plan id
|
|
@@ -163,7 +355,7 @@ that names none uses `Microsoft.VSTS.Common.AcceptanceCriteria`.
|
|
|
163
355
|
are ready for an agent?" (The agent, below).
|
|
164
356
|
## Worklog
|
|
165
357
|
|
|
166
|
-
Each dossier has a **Worklog** (`#/dossier/<name>/worklog
|
|
358
|
+
Each dossier has a **Worklog** tab (`#/dossier/<name>/worklog`):
|
|
167
359
|
one page a day, folded by code from what the cache holds, facts only. No model writes
|
|
168
360
|
a line of it. A calendar shows the days that have a page, with how many lines each
|
|
169
361
|
has; a day opens as `#/dossier/<name>/worklog/<yyyy-mm-dd>`. Days and times are UTC,
|
|
@@ -172,13 +364,14 @@ as everywhere else in Toil UI.
|
|
|
172
364
|
A page has:
|
|
173
365
|
|
|
174
366
|
- **Work items** that changed status (from, to, who and when), were added to or
|
|
175
|
-
dropped from a sprint,
|
|
367
|
+
dropped from a sprint, got a new blocker or had one cleared, and each sprint that
|
|
368
|
+
ended, with how many of its items and points were done.
|
|
176
369
|
- **Pull requests** opened, reviewed (approved, changes requested, commented), merged
|
|
177
370
|
or declined.
|
|
178
371
|
- **Builds and deployments** that failed or recovered (deployments from OpenShift,
|
|
179
372
|
whose state a sync can see change): a build is recovered when a
|
|
180
373
|
passing run follows a failing one of the same pull request or pipeline.
|
|
181
|
-
- **Agent runs:** each question an agent adapter answers in the
|
|
374
|
+
- **Agent runs:** each question an agent adapter answers in the chat, when it
|
|
182
375
|
started and ended,
|
|
183
376
|
whether it finished, failed, was stopped or was stopped at a usage cap, what it
|
|
184
377
|
cited, and its proposals, each
|
|
@@ -192,9 +385,11 @@ Every line links to its item, pull request, build or transcript, where the sourc
|
|
|
192
385
|
page for it. Two kinds of fact
|
|
193
386
|
come in differently. Status and sprint changes, pull requests, reviews and builds
|
|
194
387
|
carry their own times in the sources' history, so a page can be built for any past
|
|
195
|
-
day the cache covers. A new blocker
|
|
196
|
-
no time in the trackers, so a sync sees them by comparing
|
|
197
|
-
sync, and the line says which sync first saw it and when the
|
|
388
|
+
day the cache covers. A new blocker, a cleared one, a sprint's end and a deployment
|
|
389
|
+
that failed or came back have no time in the trackers, so a sync sees them by comparing
|
|
390
|
+
what it read with the last sync, and the line says which sync first saw it and when the
|
|
391
|
+
one before ran. The facts a sync records for the first time are also what play a theme's
|
|
392
|
+
event moments (Themes, below).
|
|
198
393
|
|
|
199
394
|
**What a page can't vouch for is said at the top:** a day before the earliest sync the
|
|
200
395
|
cache holds, a day no sync of a source ran on, a sync that failed, a source whose latest
|
|
@@ -222,6 +417,43 @@ config. Publishing an exported page is a proposal: `toil confluence page create
|
|
|
222
417
|
create --body-file <file>` in its repository, for you to run through toil's write gate.
|
|
223
418
|
Toil UI posts nothing. With sample data, notes and export are off.
|
|
224
419
|
|
|
420
|
+
### Stand-up
|
|
421
|
+
|
|
422
|
+
**Stand-up since the last working day**, on the Worklog
|
|
423
|
+
(`#/dossier/<name>/worklog/standup`), reshapes the worklog for a meeting: since the last
|
|
424
|
+
working day through today (Friday through Monday on a Monday), or any range of up to 31
|
|
425
|
+
days you pick (`#/dossier/<name>/worklog/standup/<from>/<to>`, or `/<day>` for one), and each day's page has a
|
|
426
|
+
**Stand-up for this day**. It is a fold of those days' pages by code, with no model, so the
|
|
427
|
+
same days always give the same report.
|
|
428
|
+
|
|
429
|
+
- **Team lines first:** the sprint's working days left, items added to or dropped from a
|
|
430
|
+
sprint, and builds and deployments that broke or recovered.
|
|
431
|
+
- **Then each person, agents included,** in four lists: **Done** (items moved into a done
|
|
432
|
+
status, pull requests merged or closed), **In progress** (every other status change,
|
|
433
|
+
pull requests opened or reviewed), **Blocked** (a new blocker on an item they hold, a
|
|
434
|
+
failed build of their pull request, a pull request of theirs waiting on review for 2
|
|
435
|
+
working days or more) and **Next** (current-sprint items assigned to them and not
|
|
436
|
+
started). A line belongs to whoever the fact names: who moved the item, who wrote or
|
|
437
|
+
reviewed the pull request. A pull request a dossier agent wrote goes under the agent.
|
|
438
|
+
- **People** come from the dossier's `people`, so one person's Jira, Azure DevOps and
|
|
439
|
+
GitHub accounts land under one name. An account the dossier doesn't map gets its own
|
|
440
|
+
card, named with its area and id; the People view suggests where it belongs.
|
|
441
|
+
- **What the worklog can't vouch for** in the range is said at the top. Review waits, the
|
|
442
|
+
sprint and Next aren't on any worklog page, so they are as of the latest sync, and the
|
|
443
|
+
report says which.
|
|
444
|
+
- **Every line links** to its item, pull request or build, and is numbered (F1, F2, ...).
|
|
445
|
+
|
|
446
|
+
It copies as **Markdown** (for Slack, Teams or a wiki) or **plain text**, line for line as
|
|
447
|
+
shown. **Export** writes the Markdown through toil's file service, as a page's export does,
|
|
448
|
+
to `standup-<dossier>-<from>-to-<to>.md`, and publishing it to Confluence or GitHub is a
|
|
449
|
+
proposal for you to run.
|
|
450
|
+
|
|
451
|
+
**Write it up** is optional: it asks the agent for a short narrative of the same report,
|
|
452
|
+
in the theme's voice when that is on. The agent reads the report through its
|
|
453
|
+
`standup_report` tool and ends each sentence with the fact numbers it rests on; the
|
|
454
|
+
write-up is labelled as the agent's, the lines it names are marked in the report, and its
|
|
455
|
+
usage counts like any chat's.
|
|
456
|
+
|
|
225
457
|
## Toil's configuration
|
|
226
458
|
|
|
227
459
|
The Settings pages manage what `toil connections` and `toil dossiers` manage, by
|
|
@@ -231,11 +463,17 @@ running those commands through `@imagile-dev/toil/api`, never by editing a file:
|
|
|
231
463
|
replace a secret (`toil connections login`) and remove. A secret goes from a
|
|
232
464
|
password field to toil, which keeps it in the OS credential store; the page
|
|
233
465
|
clears the field, and it is never logged, stored by Toil UI, or sent back.
|
|
466
|
+
A note under the field says how many characters it holds and what trimming
|
|
467
|
+
removes, never the value. The same paste checks as the CLI's run, in the
|
|
468
|
+
CLI's words: a line break (or, for a token, a space) in the middle is
|
|
469
|
+
refused, and quotes or a `Bearer ` / `token ` prefix ask Remove it or Keep
|
|
470
|
+
it before anything is saved.
|
|
234
471
|
Turning writes on asks you to type the connection's name, as the CLI does. A
|
|
235
472
|
connection made by `TOIL_*` env vars alone is shown read-only, with where it
|
|
236
473
|
came from.
|
|
237
474
|
- **Dossiers:** create one, add a repository, link an area, name a field, and
|
|
238
|
-
show and check any of them. A
|
|
475
|
+
show and check any of them. A dossier's name and description are edited in place
|
|
476
|
+
on its card and dashboard, through `toil dossiers describe`. A link to a connection with writes on is refused
|
|
239
477
|
here, as over MCP: make it on the CLI.
|
|
240
478
|
- **Bounds and time limit:** toil has no command for these, so they are shown
|
|
241
479
|
read-only, with the file or env var that sets them.
|
|
@@ -252,6 +490,90 @@ toil's audit log as `caller: "toil-ui"`. The page can run no other command on th
|
|
|
252
490
|
path, and never a tracker write. Adding or changing connections needs a toil
|
|
253
491
|
newer than 0.1.0-alpha.2; with that one, use the CLI.
|
|
254
492
|
|
|
493
|
+
## Help and edit links
|
|
494
|
+
|
|
495
|
+
An **(i)** beside a term explains it in a sentence or two when you hover or focus
|
|
496
|
+
it, and pressing it opens the same words with a **Read more** link to the section
|
|
497
|
+
of these docs that says the rest. A **pencil** beside a configurable value (a
|
|
498
|
+
connection, a dossier's sources, people, field names or work-in-progress limit,
|
|
499
|
+
the agent, a usage cap) opens the settings page where it's set, at that value; it
|
|
500
|
+
only navigates. **Help** in the header is a menu with the docs for the view you're on
|
|
501
|
+
and **What's new** (below).
|
|
502
|
+
|
|
503
|
+
Where a screen uses an AI term (tokens and the context window under Agent usage,
|
|
504
|
+
model, harness and MCP under Agent, sandbox and permission mode in the Assign
|
|
505
|
+
dialog's modes, session and system prompt in Renew all stale, hallucination in the
|
|
506
|
+
chat's **About these answers**), its (i) popover also gives each term's first
|
|
507
|
+
sentence from Context Overflow's glossary, with **Read more on Context Overflow**.
|
|
508
|
+
Help's menu then has **Learn**: four of Context Overflow's modules, by task.
|
|
509
|
+
The agent's empty chat has the same **Learn**. **Links to learning content**, under
|
|
510
|
+
**Settings, General** and kept in this browser, is on by default; off, every link to
|
|
511
|
+
Context Overflow and every glossary line is gone, and Help keeps the view's docs and
|
|
512
|
+
What's new.
|
|
513
|
+
|
|
514
|
+
Read more, Help, Learn and What's new's changelog links open in a new tab, and are the
|
|
515
|
+
only places the app links out to: nothing is fetched until you follow one.
|
|
516
|
+
[Help and edit links](https://imagile-dev.github.io/toil/docs/ui-help/) has the rule
|
|
517
|
+
views follow.
|
|
518
|
+
|
|
519
|
+
### Empty panels
|
|
520
|
+
|
|
521
|
+
Every empty panel offers the one action that fills it, under one short line, with any
|
|
522
|
+
explanation in its (i): **Link a pipeline** and **Add an environment** (pencils to
|
|
523
|
+
Dossier setup at the dossier's sources) on the Board tab's builds and deployments, **Add
|
|
524
|
+
a repository** for pull requests, **Add a person** on the People tab, **Analyze now**
|
|
525
|
+
for an empty Analyses tab, **Show every item** for a Command Center filter that hides
|
|
526
|
+
everything, and **Sync now** in the local app wherever only a newer read of the tracker
|
|
527
|
+
fills the panel (the sprint, the burn-up, links between items). The site preview can't
|
|
528
|
+
sync, so it offers Dossier setup there instead. A test fails on any empty panel with
|
|
529
|
+
neither an action nor a link.
|
|
530
|
+
|
|
531
|
+
### What's new
|
|
532
|
+
|
|
533
|
+
After an upgrade, **Help** in the header carries a dot (and so does **Menu** on a narrow
|
|
534
|
+
screen, which holds Help), and Help's **What's new** lists what changed in toil and Toil
|
|
535
|
+
UI since this browser last saw them: three to five lines a version, features first, from
|
|
536
|
+
each package's release notes, with a link to its full changelog. The lines are read from
|
|
537
|
+
`CHANGELOG.md` and `ui/CHANGELOG.md` when Toil UI is built and bundled with it, so
|
|
538
|
+
nothing is fetched to show them. The versions this browser last saw are kept in
|
|
539
|
+
`localStorage`; a first visit records them and shows no dot, and opening the list takes
|
|
540
|
+
the dot away. Nothing pops up over the page.
|
|
541
|
+
|
|
542
|
+
## The command palette
|
|
543
|
+
|
|
544
|
+
**Ctrl+K** (**⌘K** on a Mac) opens the command palette from any page; on a narrow
|
|
545
|
+
screen it's **Search and commands** in the header's Menu. Type to narrow it down,
|
|
546
|
+
use the arrow keys to move, **Enter** to open and **Escape** to close. It's hidden
|
|
547
|
+
until you call it up.
|
|
548
|
+
|
|
549
|
+
- **Jump** to a dossier, any of a dossier's tabs (Overview, Board, Dependencies,
|
|
550
|
+
Pull requests, People, Worklog, Analyses), a saved analysis, a settings page, or a
|
|
551
|
+
theme.
|
|
552
|
+
- **Run** Sync now (where Toil UI keeps a cache), and on a dossier's page Ask (it
|
|
553
|
+
focuses the Ask bar), Analyze, the agent that answers this chat, and Assign the
|
|
554
|
+
item you were on to an agent: the board card that had focus, or the item whose
|
|
555
|
+
page is open.
|
|
556
|
+
- Matching is fuzzy and ignores case: `pay12` finds `PAY-12`, and each word you
|
|
557
|
+
type has to appear, in order. Results are grouped by kind, and the group with the
|
|
558
|
+
best match comes first.
|
|
559
|
+
|
|
560
|
+
### Search across dossiers
|
|
561
|
+
|
|
562
|
+
With something typed, the palette searches the items of every dossier, by key and
|
|
563
|
+
title. Each result shows its dossier and status and opens the item. It reads only
|
|
564
|
+
what the last sync stored, never the tracker: opening it reads each dossier from
|
|
565
|
+
the cache the way its dashboard does. A result from a dossier last synced more than
|
|
566
|
+
a day ago, or whose last sync failed, says how old its copy is.
|
|
567
|
+
|
|
568
|
+
### Keyboard shortcuts
|
|
569
|
+
|
|
570
|
+
**?** opens a sheet listing every shortcut in Toil UI, anywhere but a text field;
|
|
571
|
+
it's also **Keyboard shortcuts** in the palette and the header's Menu. The sheet,
|
|
572
|
+
the palette and the views all read one table (`src/shortcuts.ts`), and a test fails
|
|
573
|
+
on a key a view checks any other way, so the sheet can't fall behind. On a board
|
|
574
|
+
card, **M** or the Menu key opens its menu, and **Space** picks it up to move with
|
|
575
|
+
the arrow keys.
|
|
576
|
+
|
|
255
577
|
## Feedback
|
|
256
578
|
|
|
257
579
|
The **Feedback** button in the header opens a dialog for a bug report or a feature
|
|
@@ -302,9 +624,12 @@ requests, builds and deployments that name them.
|
|
|
302
624
|
UI runs, its write-ahead log (`toil-ui.db-wal` and `toil-ui.db-shm`) sits beside
|
|
303
625
|
it, and closing folds the log back into the file. It holds
|
|
304
626
|
ticket content, so it stays on this machine and is readable by your account
|
|
305
|
-
only.
|
|
627
|
+
only. The analyses (#395) are kept in the same file, the newest 100 per dossier,
|
|
628
|
+
and a sync never rewrites them.
|
|
306
629
|
- **For how long.** Anything not synced again within the retention period (30
|
|
307
|
-
days by default) is deleted, at start and after each sync.
|
|
630
|
+
days by default) is deleted, at start and after each sync. An analysis goes once
|
|
631
|
+
it is older than the retention period, and with its dossier when toil no longer
|
|
632
|
+
has it.
|
|
308
633
|
- **Wiping it.** **Wipe the cache** in the Sync panel deletes it after asking
|
|
309
634
|
first. `toil-ui wipe` does the same from a terminal, once `toil-ui` has
|
|
310
635
|
stopped: a running Toil UI holds `toil-ui.lock` in the data folder, and the
|
|
@@ -322,9 +647,49 @@ by the page: `toil audit list`, read-only, to see whether a proposal was applied
|
|
|
322
647
|
|
|
323
648
|
## The agent
|
|
324
649
|
|
|
325
|
-
|
|
650
|
+
Every dossier page has an **Ask bar** in its top row: one line, with **Analyze**
|
|
651
|
+
beside it. Pressing into it opens the **focused view**: the conversation takes the
|
|
652
|
+
screen and the page steps back, with a slim strip that keeps the dossier, its sprint
|
|
653
|
+
and the agent answering in sight. **Escape** or **Close** puts it away; the
|
|
654
|
+
conversation stays, for the rest of the dossier's pages, until you reload.
|
|
655
|
+
|
|
656
|
+
- **Starter questions** are a row of chips before the first question, then a
|
|
657
|
+
**Suggestions** menu.
|
|
658
|
+
- **Answers stream in** as the agent writes them, under a **status line** that says
|
|
659
|
+
what it is doing: reading the cache with `owi_query`, reading live through toil with
|
|
660
|
+
`github issue list`, writing, and at the end how long it took. **Stop** cancels the
|
|
661
|
+
question on the server and keeps what had arrived. Claude and Copilot stream as they
|
|
662
|
+
write; Codex's SDK hands over its text a message at a time, so with Codex the status
|
|
663
|
+
line is what moves between messages.
|
|
664
|
+
- **The wording follows the theme**: the bar's placeholder, the welcome and the status
|
|
665
|
+
words are in each game theme's voice, and Plain stays neutral. The starter questions
|
|
666
|
+
read the same in every theme.
|
|
667
|
+
- **Analyze** asks for a pulse check in one press: what changed since the last Analyze
|
|
668
|
+
(from the worklog), who is on what, what is blocked or stuck in review, the sprint's
|
|
669
|
+
health and risks, and anything that looks off, such as a ticket marked done while its
|
|
670
|
+
pull request is open. Every line cites its items, and follow-up questions continue
|
|
671
|
+
from it. It answers top-down: a **Recommendation** line first, then the **Issues**
|
|
672
|
+
behind it (three at most), then the **Evidence**, which stays folded until you open
|
|
673
|
+
it. An answer that doesn't start with a Recommendation line is shown as it came, and
|
|
674
|
+
says so. Each whole Analyze is kept in the dossier's **Analyses** tab, and the
|
|
675
|
+
answer links to it.
|
|
676
|
+
- **Citations are chips**: in every answer, each `[[id]]` is a chip with the item's
|
|
677
|
+
key, title and status, linking to its page (a pull request to its host). Hovering or
|
|
678
|
+
focusing one shows its type, assignee, estimate, sprint and last update. An id the
|
|
679
|
+
dossier doesn't hold stays the bare id, marked, and the server's check above the
|
|
680
|
+
answer still names any id its tools never returned.
|
|
681
|
+
- **Each question carries the chat so far**: its last 8 questions and answers, each
|
|
682
|
+
answer cut to 1,500 characters. An item an earlier answer named is still checked
|
|
683
|
+
against what the tools return for the new question.
|
|
684
|
+
- **Switch agent from the chat.** The strip's switcher lists Claude, GitHub Copilot and
|
|
685
|
+
Codex, each with its model and whether it can answer. A choice holds for this chat
|
|
686
|
+
from its next question, which carries the conversation so far; the default stays in
|
|
687
|
+
Settings. An adapter that can't answer is listed with the reason and **Install** or
|
|
688
|
+
**Fix**, never left out. Each answer names the adapter and model that wrote it.
|
|
689
|
+
|
|
690
|
+
The chat answers with the agent your organization already approved, on the
|
|
326
691
|
subscription you already have. Toil UI has three adapters, each an optional peer
|
|
327
|
-
dependency that is loaded only when
|
|
692
|
+
dependency that is loaded only when it answers:
|
|
328
693
|
|
|
329
694
|
| Adapter | Package | Starts | Signs in with |
|
|
330
695
|
|---|---|---|---|
|
|
@@ -332,16 +697,54 @@ dependency that is loaded only when you choose it:
|
|
|
332
697
|
| GitHub Copilot | `@github/copilot-sdk` | `copilot` (the Copilot CLI) | your Copilot seat, through the CLI |
|
|
333
698
|
| Codex | `@openai/codex-sdk` | `codex` (the Codex CLI) | the CLI's ChatGPT sign-in or its own API key setup |
|
|
334
699
|
|
|
700
|
+
Choose the default under **Settings, Agent**: the adapter, each adapter's model
|
|
701
|
+
(empty for its CLI's default), the CLI's path (empty to use the one on `PATH`) and,
|
|
702
|
+
for Claude, the endpoint. The choice is kept in `<data folder>/agent.json`, never in
|
|
703
|
+
toil's config, and has no field for a key: each SDK signs in the way its CLI does.
|
|
704
|
+
|
|
705
|
+
### Installing an adapter's SDK
|
|
706
|
+
|
|
707
|
+
**Settings, Agent** lists each adapter: whether its SDK is installed and at which
|
|
708
|
+
version against the one Toil UI was tested with, which CLI it would start, and
|
|
709
|
+
anything worth knowing. A missing SDK has an **Install** button, which shows the one
|
|
710
|
+
command it will run, word for word, before anything runs:
|
|
711
|
+
|
|
335
712
|
```bash
|
|
336
|
-
npm install
|
|
713
|
+
npm install --global --prefix <the prefix Toil UI is installed in> --ignore-scripts --before=<14 days ago> --no-audit --no-fund --omit=optional @openai/codex-sdk@0.160.0
|
|
337
714
|
```
|
|
338
715
|
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
716
|
+
Pressing **Install** runs it through the npm that came with your Node, with no shell and
|
|
717
|
+
your own npm config, so your organization's registry and proxy apply. npm's output
|
|
718
|
+
streams into the dialog, and Toil UI then loads the SDK to prove it installed; a
|
|
719
|
+
failure shows npm's own message and the fix. **Copy command** is beside it, for a
|
|
720
|
+
machine where you'd rather run it yourself. This is the one thing Toil UI runs npm
|
|
721
|
+
for (docs/decisions/343-ask-up-front.md).
|
|
722
|
+
|
|
723
|
+
- **Only the tested versions**: `@anthropic-ai/claude-agent-sdk@0.3.289` with
|
|
724
|
+
`zod@4.6.5`, `@github/copilot-sdk@1.0.16` and `@openai/codex-sdk@0.160.0`, exactly
|
|
725
|
+
(`ui/server/agents/tested.ts`). Nothing else is ever named, and `--before` holds
|
|
726
|
+
everything npm resolves, the SDK's own dependencies included, to releases at least
|
|
727
|
+
14 days old.
|
|
728
|
+
- **Where it goes depends on how Toil UI is installed.** Installed globally, the SDK
|
|
729
|
+
is installed globally into the same prefix, read from where Toil UI is rather than
|
|
730
|
+
from npm's config, so a global install under another prefix still lands beside it.
|
|
731
|
+
Its optional dependencies, each SDK's own copy of its CLI, are left out: Toil UI
|
|
732
|
+
never starts them. In a project's `node_modules`, it installs into the project with
|
|
733
|
+
`--save-exact`. In a clone of this repository, it installs at the root with
|
|
734
|
+
`--no-save`, naming the agent SDKs already there again, since an unsaved install
|
|
735
|
+
removes the ones it doesn't name.
|
|
736
|
+
- **Run with `npx`, it can't install**: npx runs Toil UI from its cache, which npm
|
|
737
|
+
clears when it likes, so there is no folder to install beside. The dialog says so;
|
|
738
|
+
install Toil UI with `npm install -g @imagile-dev/toil-ui` and start it as `toil-ui`.
|
|
739
|
+
- **Not into Toil UI's own folder.** Its `package.json` lists the SDKs as optional
|
|
740
|
+
peers, so npm reports them up to date there and installs nothing.
|
|
741
|
+
- **Claude's bundled CLI.** `@anthropic-ai/claude-agent-sdk`'s platform package is an
|
|
742
|
+
optional dependency that npm sometimes skips. Toil UI doesn't need it, since it
|
|
743
|
+
starts the `claude` it finds, and the status says so rather than fail.
|
|
744
|
+
- **Copilot on Windows.** npm installs the Copilot CLI as `copilot.cmd`, a shim no SDK
|
|
745
|
+
can start without a shell. Copilot's SDK starts a `.js` CLI with Node itself, so
|
|
746
|
+
Toil UI starts the script the shim runs (`node_modules\@github\copilot\npm-loader.js`
|
|
747
|
+
beside it) and says so in the status. Claude Code and Codex install as `.exe` files.
|
|
345
748
|
|
|
346
749
|
- **Only the CLI already on this machine.** Toil UI finds it on `PATH` (skipping
|
|
347
750
|
relative entries and the working directory) or at the path you set, which must
|
|
@@ -350,7 +753,7 @@ never starts that copy anyway.
|
|
|
350
753
|
and temp folders, proxy and CA settings) and its own sign-in variables. toil's
|
|
351
754
|
`TOIL_*` variables, `GITHUB_TOKEN` and CI tokens never reach it. Not found is a plain
|
|
352
755
|
error naming the CLI and the fix. On Windows a `.cmd` shim can't be started by the
|
|
353
|
-
SDKs, so point at the `.exe
|
|
756
|
+
SDKs, so point at the `.exe` (Copilot's npm shim is the exception, above).
|
|
354
757
|
- **Read-only tools, one dossier.** The agent gets `owi_query`, `owi_get`,
|
|
355
758
|
`owi_similar` (likely duplicates, scored as `toil util owi similar` scores them)
|
|
356
759
|
and `owi_history` over the cache, `pr_query`, `pr_get` and `pr_metrics` over its
|
|
@@ -361,7 +764,8 @@ never starts that copy anyway.
|
|
|
361
764
|
`readiness_get` (each item's readiness verdict and its rows, as the Command Center
|
|
362
765
|
works them out), `proposal_fields` (a write command's input fields,
|
|
363
766
|
told it describes load, never performance), `worklog_day` (one day's worklog page,
|
|
364
|
-
with what it can't vouch for), `
|
|
767
|
+
with what it can't vouch for), `standup_report` (a range of days as the Stand-up folds
|
|
768
|
+
them, each line numbered), `proposal_fields` (a write command's input fields,
|
|
365
769
|
from toil's registry), and `toil mcp`'s read tools for live lookups, called through
|
|
366
770
|
toil's `execute()` with `readOnly: true`. The dossier is fixed to the one on screen.
|
|
367
771
|
There is no write tool, and each SDK's own tools (shell, files, web, plugins, other
|
|
@@ -397,8 +801,21 @@ never starts that copy anyway.
|
|
|
397
801
|
proposals or what the tools can do. **Show the full prompt** shows exactly what
|
|
398
802
|
the agent is sent.
|
|
399
803
|
|
|
400
|
-
With no adapter chosen, the chat says so and names the three
|
|
401
|
-
|
|
804
|
+
With no adapter chosen, the chat says so and names the three; its switcher can still
|
|
805
|
+
choose an installed one for that chat. `toil-ui --sample` keeps the scripted agent,
|
|
806
|
+
which answers its starter questions and Analyze from the sample data.
|
|
807
|
+
|
|
808
|
+
### Not ticketed yet
|
|
809
|
+
|
|
810
|
+
When you ask the chat for work that names no ticket (not a question, which ends in `?` or
|
|
811
|
+
opens with what, why, how and the like, and no key such as `PAY-12` or `#42`), a **Not ticketed yet** banner lists up to three of the
|
|
812
|
+
dossier's open items likeliest to cover it, scored as `toil util owi similar` scores
|
|
813
|
+
them, each with why. Attach the work to one by naming its key in your branch and
|
|
814
|
+
commits, which writes nothing, or press **Ticket this** for proposals: a sub-task
|
|
815
|
+
under each match, and a new ticket on the dossier's tracker. They are proposal cards
|
|
816
|
+
like the chat's others, with the command line to run through toil's write gate, and
|
|
817
|
+
nothing is created until you run one. With no match, it says there is no likely
|
|
818
|
+
ticket and offers only a new one. It asks once per chat, and **Not now** hides it.
|
|
402
819
|
|
|
403
820
|
### What the agent's models used
|
|
404
821
|
|
|
@@ -410,7 +827,7 @@ called):
|
|
|
410
827
|
|---|---|---|
|
|
411
828
|
| Claude | each step's `usage` by message id, then the result's `modelUsage` per model and its `costUSD` | tokens (in, out, cache read, cache write) per model, and the dollar figure as the SDK's estimate; on a Claude plan (no API key, Anthropic's own API) it says "API-equivalent", since the plan isn't billed per token |
|
|
412
829
|
| Codex | `turn.completed`'s `usage`: input (which holds the cached input), cached input, cache writes, output | tokens; a dollar figure only from rates you enter, labelled "computed from your rates". The SDK names no model, so a Codex record names the model you chose, or says it wasn't named |
|
|
413
|
-
| GitHub Copilot | one `assistant.usage` event per model call, with `cost` as the premium-request multiplier, and `session.usage_info` for the context | tokens and premium requests, never dollars; premium requests left from the SDK's experimental `account.getQuota`, marked experimental |
|
|
830
|
+
| GitHub Copilot | one `assistant.usage` event per model call, with `cost` as the premium-request multiplier, and `session.usage_info` for the context. Copilot bills the multiplier once per prompt: only the call the prompt started (`initiator` `user`) counts it, and the agent's follow-up calls in the tool loop count 0 | tokens and premium requests, never dollars; premium requests left from the SDK's experimental `account.getQuota`, marked experimental |
|
|
414
831
|
|
|
415
832
|
- **Under each answer**, one line per model: `2.1k in · 380 out · 14k cached · cache
|
|
416
833
|
write not reported · ~$0.012 (SDK estimate)`. A figure the SDK didn't report reads
|
|
@@ -441,7 +858,8 @@ the vendor's own bill is the authority.
|
|
|
441
858
|
|
|
442
859
|
## Assigning work to an agent
|
|
443
860
|
|
|
444
|
-
From an item's page, or **Assign
|
|
861
|
+
From an item's page, or **Assign to an agent…** in its card's menu on the board
|
|
862
|
+
(right-click the card, long-press it, or press M while it has focus), a work item can be
|
|
445
863
|
assigned to Claude, GitHub Copilot or Codex in one of three modes. The agent works on
|
|
446
864
|
the subscription you already have, and nothing it proposes leaves this machine until
|
|
447
865
|
you apply it.
|
|
@@ -464,9 +882,9 @@ you apply it.
|
|
|
464
882
|
that pushes.
|
|
465
883
|
- **States**: `queued` (waiting for a free slot, or for a person to press Start),
|
|
466
884
|
`working`, `needs you` (proposals or questions to review, or an item the agent
|
|
467
|
-
thought was trying to instruct it), `done` and `failed`. The **Agents**
|
|
468
|
-
|
|
469
|
-
and the People view shows each agent's assignments.
|
|
885
|
+
thought was trying to instruct it), `done` and `failed`. The **Agents** sidebar beside
|
|
886
|
+
every dossier tab shows each assignment's state, mode, adapter, run time and what it
|
|
887
|
+
used, and the People view shows each agent's assignments.
|
|
470
888
|
- **From the Command Center**, "Start every ready item" assigns each slated item in
|
|
471
889
|
implement mode, in order, on Codex (or the adapter chosen in Settings, when it can
|
|
472
890
|
implement), in the dossier's one repository with a local path, and says what it
|
|
@@ -482,7 +900,7 @@ you apply it.
|
|
|
482
900
|
- **Tracker text is untrusted.** The item is fenced off in the prompt as data, and an
|
|
483
901
|
item that tells the agent to do anything else stops the run, marked `needs you`.
|
|
484
902
|
- **Limits.** One assignment runs at a time and each has 20 minutes, both changeable
|
|
485
|
-
in the
|
|
903
|
+
in the sidebar's **Limits** (1 to 3 at once, 1 to 240 minutes), kept in
|
|
486
904
|
`<data folder>/assignments.json`. An assignment is one chat to the usage caps under
|
|
487
905
|
**Settings, Agent usage**, so a per-chat cap is a per-assignment cap. Either limit
|
|
488
906
|
stops a run cleanly, saying which.
|
|
@@ -490,15 +908,97 @@ you apply it.
|
|
|
490
908
|
commands and file changes Codex reports, and each proposal and what came of it.
|
|
491
909
|
Each assignment also records what it started on: the toil and Toil UI versions, the
|
|
492
910
|
adapter and model, the tools, and SHA-256 fingerprints of the dossier, the item and
|
|
493
|
-
the prompt. Assignments are kept under the cache, in
|
|
911
|
+
the prompt, and the install fingerprint a later look holds it to (Stale sessions, below). Assignments are kept under the cache, in
|
|
494
912
|
`<data folder>/cache/assignments/`, so a wipe deletes them.
|
|
495
913
|
- **For programs on the same server**, `api/assignments` lists, assigns, starts,
|
|
496
|
-
stops, applies and
|
|
914
|
+
stops, applies, dismisses and renews, and `api/assignments/events?since=<n>` streams every
|
|
497
915
|
change of state as NDJSON.
|
|
498
916
|
|
|
917
|
+
## Stale sessions
|
|
918
|
+
|
|
919
|
+
An agent works from the instructions it got when it started. Upgrade toil, edit the
|
|
920
|
+
dossier or change your instructions under **Settings, Agent**, and the chats and
|
|
921
|
+
assignments already going are still on the old ones. Toil UI records what each one
|
|
922
|
+
started on, says which have gone stale and why, and renews them on request.
|
|
923
|
+
|
|
924
|
+
- **What it records.** Each chat at its first question, and each assignment when its
|
|
925
|
+
run starts, keeps an install fingerprint: toil's and Toil UI's version and commit,
|
|
926
|
+
one SHA-256 per toil area of the tools the agent was handed (Toil UI loads no skill
|
|
927
|
+
page, so those tools are the toil instructions its agent reads), SHA-256 of the
|
|
928
|
+
dossier as `toil dossiers show` reads it, and SHA-256 of the prompts (the system
|
|
929
|
+
prompt, the starters or the mode's task, and your own instructions and voice). The
|
|
930
|
+
theme on screen isn't part of it. An assignment recorded before this has none, and
|
|
931
|
+
is never called stale.
|
|
932
|
+
- **When it's stale.** Every answer, every read of the Agents sidebar and every
|
|
933
|
+
assignment page compares what the session started on with the current fingerprint,
|
|
934
|
+
whose builds are the ones on disk, read again only when their files change. The
|
|
935
|
+
reason names what moved: "started on toil 0.1.0-alpha.3 · now alpha.4 · skills
|
|
936
|
+
changed: github · dossier changed". A session's earlier turns aren't marked; only
|
|
937
|
+
the instructions it started on are.
|
|
938
|
+
- **Where it shows.** A **Stale** badge with the reason on the chat (in the Ask bar and
|
|
939
|
+
the focused view), on each assignment in the Agents sidebar and on its page, and on the
|
|
940
|
+
agent's card in the People view. A done assignment is closed and isn't marked.
|
|
941
|
+
- **Renew.** On the chat, **Renew** in the focused view records what it starts on now;
|
|
942
|
+
the conversation stays, and the next question carries it as every question does. The
|
|
943
|
+
chat's usage total carries on, so renewing never resets a cap. On a stale assignment
|
|
944
|
+
that has failed, **Renew** queues a fresh one on the same item, mode, adapter and
|
|
945
|
+
repository, whose prompt carries what the old run left, fenced as data; the old one
|
|
946
|
+
stays readable, marked as renewed. Renew never interrupts a turn: a chat that is
|
|
947
|
+
answering and a working assignment wait, and an assignment that needs you is
|
|
948
|
+
skipped until you've reviewed it.
|
|
949
|
+
- **Renew all stale**, in the Agents sidebar, lists every stale session of the dossier
|
|
950
|
+
first, the chat included, each saying whether it renews or why it's skipped, and
|
|
951
|
+
renews the rest with one press.
|
|
952
|
+
- **The server itself.** When toil or Toil UI on disk is newer than the running
|
|
953
|
+
server, the header says so, with the command that starts it again. A session renewed
|
|
954
|
+
then would start on the old build and be stale at once, so until it restarts, Renew
|
|
955
|
+
is refused (and Renew all stale skips every session), saying so with that command.
|
|
956
|
+
|
|
957
|
+
## Notifications
|
|
958
|
+
|
|
959
|
+
Toil UI tells you when an agent's state changes, and stays quiet otherwise. A tool
|
|
960
|
+
call, its progress, or a state that didn't change never notifies.
|
|
961
|
+
|
|
962
|
+
- **What notifies:** an assignment reaching **needs you** (with why: "asked a
|
|
963
|
+
question", "3 proposals to review"), **done** or **failed**, one stopped at its
|
|
964
|
+
**usage cap**, and a chat or assignment gone **stale** (Stale sessions, above). A
|
|
965
|
+
run going from queued to working says nothing, and neither does your own Stop.
|
|
966
|
+
- **Once, together.** Changes within four seconds become one notice: "2 agents need
|
|
967
|
+
you", each line linking to its assignment. A change undone inside those seconds,
|
|
968
|
+
such as a question answered elsewhere, sends nothing.
|
|
969
|
+
- **Where.** A notice under the header, with Dismiss. While the tab is hidden its
|
|
970
|
+
title counts them, `(2) Toil UI`, until you come back. With **Browser
|
|
971
|
+
notifications** on, the browser's own notification shows them too, drawn on this
|
|
972
|
+
computer: nothing leaves the machine. The browser is asked for permission only when
|
|
973
|
+
you turn that on, never before.
|
|
974
|
+
- **Settings**, under **Settings, General**, kept in this browser: a switch for each
|
|
975
|
+
kind (**needs you**, **failed** and the usage cap on, **done** off, **stale** on, by
|
|
976
|
+
default), **only for agents I started** (the chats in this browser and the
|
|
977
|
+
assignments assigned, started or renewed here), and quiet hours, which hold every
|
|
978
|
+
notice while the title still counts.
|
|
979
|
+
- **Plain words.** Notices read the same in every theme: the theme's wording stays in
|
|
980
|
+
the views.
|
|
981
|
+
- **Where it listens.** The server's `api/assignments/events?since=latest` stream,
|
|
982
|
+
which carries what a notice says with each event, and a minute's read of the
|
|
983
|
+
dossier on screen for sessions gone stale.
|
|
984
|
+
|
|
985
|
+
### Notification history
|
|
986
|
+
|
|
987
|
+
The **bell** in the header (beside **Menu** on a narrow screen) counts the unread and
|
|
988
|
+
opens the last 50 things worth telling you, newest first: each change a notice carried
|
|
989
|
+
(needs you, done, failed, stopped at a usage cap, gone stale), each sync's result, from
|
|
990
|
+
the Sync panel, with the dossier that failed, and when each happened. Every entry links
|
|
991
|
+
to what it's about: the assignment, the dossier, or the Dossiers view. **Mark all read**
|
|
992
|
+
clears the count and keeps the entries. The bell keeps a change that quiet hours held
|
|
993
|
+
back, and one whose notice you dismissed; which changes reach it is the notification
|
|
994
|
+
settings' choice. It's kept in this browser's `localStorage`, shared by its tabs (with one
|
|
995
|
+
entry for each event, however many tabs saw it), and sent nowhere. Notices follow the rules above unchanged, and a theme's moments play from
|
|
996
|
+
the worklog's facts, never from the bell.
|
|
997
|
+
|
|
499
998
|
## Themes
|
|
500
999
|
|
|
501
|
-
|
|
1000
|
+
Eight built-in themes: Plain, Crate (the default), Harvest, Starship, Realm, Sprawl,
|
|
1001
|
+
Frontier and Overworld. Pick
|
|
502
1002
|
one from the header, or under **Settings, General**, where two checkboxes say how far
|
|
503
1003
|
it goes, both on by default:
|
|
504
1004
|
|
|
@@ -508,10 +1008,29 @@ it goes, both on by default:
|
|
|
508
1008
|
read the same in every theme.
|
|
509
1009
|
- **Themed agent voice:** the agent answers in the theme's register, a terse
|
|
510
1010
|
dockworker in Crate, a patient farmhand in Harvest, a ship's log in Starship, a
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
1011
|
+
dungeon master in Realm, a laconic netrunner in Sprawl, a dry telegraph operator
|
|
1012
|
+
in Frontier, an old sage in a cave in Overworld. It changes phrasing only.
|
|
1013
|
+
|
|
1014
|
+
A theme with particles also gets **Particles and ambient effects**, kept for each
|
|
1015
|
+
theme on its own: off, that theme's particles are gone entirely, while its other
|
|
1016
|
+
motion keeps following **Reduce motion and effects** (and the operating system's
|
|
1017
|
+
reduced-motion setting, which stops everything).
|
|
1018
|
+
|
|
1019
|
+
Crate, Harvest, Starship, Realm, Sprawl, Frontier and Overworld also have **theme moments**: a launch splash while the first read
|
|
1020
|
+
runs, their own loading screens with the real progress and a rotating line of their own,
|
|
1021
|
+
an entrance as a dossier opens, a transition between its tabs, and a short moment when a
|
|
1022
|
+
sync brings an item done, a build passed or failed, a blocker cleared, a pull request
|
|
1023
|
+
merged, or a sprint's end. **Theme motion**, under Settings, General, plays them in full,
|
|
1024
|
+
subtly or not at all, and is off whenever reduced motion is asked for. Every loading
|
|
1025
|
+
screen also carries a **toil tip**, one line with a Read more link, which **Toil tips on
|
|
1026
|
+
loading screens** turns off. Waits under 300 ms show no loading screen at all.
|
|
1027
|
+
|
|
1028
|
+
Plain has neither wording nor voice, so both are off while it's chosen. It sets
|
|
1029
|
+
headings and figures in Fredoka, toil's wordmark face, on IBM Plex Sans. The theme
|
|
1030
|
+
is toil's own setting too (`toil theme set`, `TOIL_THEME` over it), which the welcome
|
|
1031
|
+
menu follows: a pick here writes it, and Toil UI opens in it, except in a browser that
|
|
1032
|
+
had a theme saved before the setting, which keeps it until the next pick. The other
|
|
1033
|
+
choices are kept in this browser. Toil UI doesn't install themes from anywhere else: to ask for one, send a
|
|
515
1034
|
feature request from **Feedback** or with `toil feedback feature`. A `themes/` folder
|
|
516
1035
|
left in the data folder by an earlier alpha is not read, and Toil UI says so when it
|
|
517
1036
|
starts. [Themes](https://imagile-dev.github.io/toil/docs/themes/) has the whole
|
|
@@ -574,6 +1093,26 @@ GitHub CLI signed in (`gh auth login`), or `TOIL_GITHUB_TOKEN` set in the shell.
|
|
|
574
1093
|
Codex under **Settings, Agent**. The script points `CODEX_HOME` at your real
|
|
575
1094
|
`~/.codex`, which is where Toil UI finds the `auth.json` it links into its own
|
|
576
1095
|
Codex home.
|
|
1096
|
+
- **Ask with GitHub Copilot, on a cheap model.** Install `@github/copilot-sdk@1.0.16`
|
|
1097
|
+
the same way (or press **Install** under **Settings, Agent**). The Copilot CLI found
|
|
1098
|
+
its own sign-in from the scratch home in our runs; if it says it isn't signed in, run
|
|
1099
|
+
`copilot` once on its own. Then pick the model: Copilot lists the models your
|
|
1100
|
+
account can use, each with its premium-request multiplier (`/model` in the CLI, or
|
|
1101
|
+
the SDK's `listModels()`). Choose the lowest, ideally one at 0×; otherwise the
|
|
1102
|
+
cheapest multiplier, such as `mai-code-1.1-flash` at 0.25×, never a premium model.
|
|
1103
|
+
Type its id as Copilot's model under **Settings, Agent**, and check the model each
|
|
1104
|
+
answer names and the premium requests under it.
|
|
1105
|
+
- **Ask with Claude, on Haiku.** Install `@anthropic-ai/claude-agent-sdk@0.3.289` and
|
|
1106
|
+
`zod@4.6.5` the same way, and type `haiku` (or `claude-haiku-5-5`) as Claude's
|
|
1107
|
+
model under **Settings, Agent**; empty would be Claude Code's own default, which
|
|
1108
|
+
may be Opus. Claude Code keeps its sign-in in `~/.claude`, which the scratch home
|
|
1109
|
+
hides, and refreshing it from there would rewrite your credentials file, so the
|
|
1110
|
+
script only reads it: a `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` in the
|
|
1111
|
+
shell goes through as it is, and otherwise the access token in
|
|
1112
|
+
`~/.claude/.credentials.json` goes into Toil UI's environment as
|
|
1113
|
+
`CLAUDE_CODE_OAUTH_TOKEN` while it has ten minutes left. When it has expired the
|
|
1114
|
+
script says so: run `claude` once in a terminal, which refreshes its own sign-in,
|
|
1115
|
+
or set a token from `claude setup-token`, and start the script again.
|
|
577
1116
|
|
|
578
1117
|
## Verify before you open a PR: `npm run verify:ui`
|
|
579
1118
|
|
|
@@ -584,6 +1123,7 @@ from the root or from `ui/`, and paste the report's table into the PR.
|
|
|
584
1123
|
```bash
|
|
585
1124
|
npm run verify:ui # build, sample data, real data
|
|
586
1125
|
npm run verify:ui -- --ask # and one Codex question
|
|
1126
|
+
npm run verify:ui -- --ask --adapter copilot --model mai-code-1.1-flash # or --adapter claude --model haiku
|
|
587
1127
|
npm run verify:ui -- --no-build --starter standup
|
|
588
1128
|
```
|
|
589
1129
|
|
|
@@ -596,17 +1136,35 @@ npm run verify:ui -- --no-build --starter standup
|
|
|
596
1136
|
is what the published package runs on.
|
|
597
1137
|
- **Sample data:** `toil-ui --sample` in a throwaway home, every view through the
|
|
598
1138
|
layout check (`scripts/layout-check.mjs`) in every theme and scheme at 375, 768 and
|
|
599
|
-
1440px.
|
|
1139
|
+
1440px. On each dossier's dashboard it also drags a board card to the next column
|
|
1140
|
+
with real input, a mouse and at 375px a finger, and fails when the card doesn't
|
|
1141
|
+
follow the pointer or the dropped move doesn't show in the target column. It needs
|
|
1142
|
+
only a browser, so it runs anywhere, CI included.
|
|
1143
|
+
- **First run:** `toil-ui` on an empty home, with no connections, no dossiers and no
|
|
1144
|
+
`TOIL_*` variable from your shell, through the same check: its Dossiers view must
|
|
1145
|
+
show the three-step checklist, and the palette and the shortcuts sheet open over it.
|
|
600
1146
|
- **Real data:** the home `dev-real.mjs` sets up, made fresh at
|
|
601
1147
|
`.scratch/verify/home`, on `imagile-dev/toil-sandbox` with the token from `gh auth
|
|
602
1148
|
token` in Toil UI's environment only. It syncs the `sandbox` dossier and runs the
|
|
603
|
-
same check over the home page, the dossier, one of its items and the settings pages
|
|
1149
|
+
same check over the home page, the dossier and its Board and Dependencies tabs, its worklog and stand-up, one of its items and the settings pages,
|
|
1150
|
+
except that its header may fold into the Menu at 1440px, since a real dossier's name
|
|
1151
|
+
and links can genuinely fill the row.
|
|
604
1152
|
Without a GitHub sign-in it skips this part and says so; nothing else depends on it.
|
|
605
1153
|
- **`--ask`** asks Codex one starter question (`hygiene` unless `--starter <id>`) and
|
|
606
1154
|
checks that an answer arrived, that the server verified every `[[id]]` it cites,
|
|
607
1155
|
that its proposals parsed, that nothing ran (no write in toil's audit log for the
|
|
608
|
-
run), and that `codex mcp list` in Toil UI's Codex home shows only `toil_ui`.
|
|
609
|
-
|
|
1156
|
+
run), and that `codex mcp list` in Toil UI's Codex home shows only `toil_ui`. Then it
|
|
1157
|
+
asks Analyze as the chat's second question, and checks the history of analyses
|
|
1158
|
+
(#395): that Analyze was kept, top-down (a Recommendation line, three issues at
|
|
1159
|
+
most); then it changes the dossier's WIP limit in the scratch home (`toil dossiers
|
|
1160
|
+
wip-limit --replace`), asks Analyze again, checks the history lists both, newest
|
|
1161
|
+
first, the second compared with the first, and puts the Overview, the Analyses tab
|
|
1162
|
+
and the second analysis opened through the layout check, shot. It needs the Codex CLI signed in and the
|
|
1163
|
+
SDK installed in the clone (above). `--adapter copilot` or `--adapter claude` asks that
|
|
1164
|
+
adapter instead, held to the same checks (Codex is the reference; its MCP check is
|
|
1165
|
+
skipped), and `--model <id>` sets its model and fails the run when an answer or a
|
|
1166
|
+
usage record names another one, so a cheap-model run can't quietly use a dear one. Each adapter's full live run, every agent feature on the sandbox, is
|
|
1167
|
+
recorded in `ui/docs/live-runs/`.
|
|
610
1168
|
- **What fails it:** any layout problem in any theme, and any axe violation at WCAG
|
|
611
1169
|
2.2 AA in Plain and Crate. Axe findings in the other themes are listed in the report
|
|
612
1170
|
and never fail it. Screenshots are of Plain and Crate.
|
|
@@ -698,6 +1256,50 @@ toil util owi map board.jsonl > mapped.json
|
|
|
698
1256
|
node ui/scripts/ado-seed/compare.mjs mapped.json --project "<project>" --backdated
|
|
699
1257
|
```
|
|
700
1258
|
|
|
1259
|
+
## Measuring theme moments
|
|
1260
|
+
|
|
1261
|
+
Two more commands are for a PR that changes a theme's moments ([Theme
|
|
1262
|
+
moments](https://imagile-dev.github.io/toil/docs/themes/#theme-moments)) or the engine that
|
|
1263
|
+
plays them. Both build Toil UI first (`--no-build` skips it), run `toil-ui --sample` in a
|
|
1264
|
+
throwaway home, drive headless Chrome (the one the layout check finds; `CHROME_PATH` picks
|
|
1265
|
+
another), and write to `ui/.moments/`, which git ignores.
|
|
1266
|
+
|
|
1267
|
+
```bash
|
|
1268
|
+
npm run moments:measure -w ui # every theme with moments, 3 runs each
|
|
1269
|
+
npm run moments:measure -w ui -- --theme realm --cold
|
|
1270
|
+
npm run screens:sheet -w ui # every theme, 375 and 1440px, full, subtle and off
|
|
1271
|
+
npm run screens:sheet -w ui -- --theme realm --width 768 --motion full
|
|
1272
|
+
```
|
|
1273
|
+
|
|
1274
|
+
- **`moments:measure`** times each theme's launch splash, loading screen and sprint recap at
|
|
1275
|
+
1440px with GPU compositing on. A `requestAnimationFrame` recorder gives the frame times
|
|
1276
|
+
(Sprawl's rain and Realm's embers draw at 30 fps by design, which raw presented-frame gaps
|
|
1277
|
+
would misread), and Chrome's frame reporter the frames it dropped. Each run opens a fresh
|
|
1278
|
+
browser per theme and plays it twice: the first pass is Chrome compiling its GPU shaders,
|
|
1279
|
+
which a person sees at most once per browser version, and the second is the figure. It
|
|
1280
|
+
prints a table, each cell the median frame, the worst frame, the frames over 20 ms and the
|
|
1281
|
+
frames Chrome dropped over every run, and writes it to `ui/.moments/measure.md` with the
|
|
1282
|
+
raw results in `measure.json` beside it. It exits 1 when any frame is over 20 ms or a phase
|
|
1283
|
+
didn't play. `--report-only` prints the same and exits 0; `--cold` adds the first pass's
|
|
1284
|
+
worst frames; `--runs <n>` (default 3), `--motion subtle`, `--throttle <rate>` (a slower
|
|
1285
|
+
CPU) and `--no-gpu` (software rendering) change the run. It takes about two minutes a
|
|
1286
|
+
theme.
|
|
1287
|
+
- **`screens:sheet`** makes one contact sheet for each theme, width and Theme motion level,
|
|
1288
|
+
`ui/.moments/sheets/<theme>-<width>-<motion>.png`, ready to attach to the PR, with its
|
|
1289
|
+
frames and an HTML copy in a folder beside it. A sheet shows the splash arriving, held and
|
|
1290
|
+
handing over; the loading screen as its loops turn; each event moment the theme declares
|
|
1291
|
+
coming in, held and going out, cropped to the card; the dossier entrance; and a change of
|
|
1292
|
+
tab. Every frame is a still: the engine's animations are caught paused as they start and
|
|
1293
|
+
stepped by hand, so a sheet is the same on every run. `--width` and `--motion` repeat, and
|
|
1294
|
+
replace the defaults.
|
|
1295
|
+
|
|
1296
|
+
**Run them on a quiet machine, with nothing else running**: no build, no other test run, no
|
|
1297
|
+
video call. A frame time measures the machine as much as the page, so a busy machine's slow
|
|
1298
|
+
frames aren't the theme's. `moments:measure` reads the CPU before it starts, says so when the
|
|
1299
|
+
machine is already more than 15% busy, and puts both readings, before and during, at the top of
|
|
1300
|
+
its table. For the same reason neither command runs in CI, and neither is part of
|
|
1301
|
+
`npm run verify:ui`. Put the table and the sheets in the PR, with the load the run saw.
|
|
1302
|
+
|
|
701
1303
|
## Settings
|
|
702
1304
|
|
|
703
1305
|
| Setting | Flag | Env var | Default |
|
|
@@ -713,7 +1315,7 @@ release. The data folder is Toil UI's own, apart from toil's `~/.toil/`, and hol
|
|
|
713
1315
|
the cache, `agent.json` and `usage.json`. A `~` at the start of `TOIL_UI_DATA_DIR` means your home folder, on
|
|
714
1316
|
Windows too.
|
|
715
1317
|
|
|
716
|
-
## Not in this
|
|
1318
|
+
## Not in this beta
|
|
717
1319
|
|
|
718
1320
|
- **Serving other machines.** It is local only.
|
|
719
1321
|
- **Implement mode on Claude or Copilot**, and **answering an agent's questions in the assignment** itself: answer on the item and assign it again.
|
|
@@ -722,7 +1324,7 @@ Windows too.
|
|
|
722
1324
|
|
|
723
1325
|
`@imagile-dev/toil-ui` ships the server (`dist/server/toil-ui.js`) and the built app
|
|
724
1326
|
(`dist/app/`), and nothing else. It has no install scripts and no native addons,
|
|
725
|
-
spawns no program of its own (an agent SDK you install starts its CLI), and its
|
|
1327
|
+
spawns no program of its own but npm, for Install alone (an agent SDK you install starts its CLI), and its
|
|
726
1328
|
front end's framework is built in rather than installed. The agent SDKs are
|
|
727
1329
|
optional peer dependencies: none is installed with it.
|
|
728
1330
|
|