@imagile-dev/toil-ui 0.0.0-stage → 0.1.0-alpha.2
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/LICENSE +202 -0
- package/NOTICE +230 -0
- package/README.md +728 -2
- package/dist/app/assets/Graph-CeJeskZg.css +1 -0
- package/dist/app/assets/Graph-X3vfaDBI.js +7 -0
- 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/crop-grown-HG5zb5pJ.svg +74 -0
- package/dist/app/assets/crop-harvested-Q-ua5_kg.svg +79 -0
- package/dist/app/assets/eb-garamond-cyrillic-400-normal-C0kVTdou.woff +0 -0
- package/dist/app/assets/eb-garamond-cyrillic-400-normal-DDLP67lu.woff2 +0 -0
- package/dist/app/assets/eb-garamond-cyrillic-600-normal-CHfC3jm-.woff2 +0 -0
- package/dist/app/assets/eb-garamond-cyrillic-600-normal-koFutDBv.woff +0 -0
- package/dist/app/assets/eb-garamond-cyrillic-ext-400-normal-DG8lny6_.woff +0 -0
- package/dist/app/assets/eb-garamond-cyrillic-ext-400-normal-o8fRvAFQ.woff2 +0 -0
- package/dist/app/assets/eb-garamond-cyrillic-ext-600-normal-b6vuEf1e.woff +0 -0
- package/dist/app/assets/eb-garamond-cyrillic-ext-600-normal-cjIjEMm6.woff2 +0 -0
- package/dist/app/assets/eb-garamond-greek-400-normal-CVAbzS9p.woff2 +0 -0
- package/dist/app/assets/eb-garamond-greek-400-normal-d4JlP2QH.woff +0 -0
- package/dist/app/assets/eb-garamond-greek-600-normal--vWuDlyL.woff2 +0 -0
- package/dist/app/assets/eb-garamond-greek-600-normal-JScKXZBq.woff +0 -0
- package/dist/app/assets/eb-garamond-greek-ext-400-normal-BaZl8BIK.woff +0 -0
- package/dist/app/assets/eb-garamond-greek-ext-400-normal-K8pwR3tn.woff2 +0 -0
- package/dist/app/assets/eb-garamond-greek-ext-600-normal-B6KG6Acg.woff2 +0 -0
- package/dist/app/assets/eb-garamond-greek-ext-600-normal-DzPSPp8W.woff +0 -0
- package/dist/app/assets/eb-garamond-latin-400-normal-BCNrxLz_.woff2 +0 -0
- package/dist/app/assets/eb-garamond-latin-400-normal-maQnHeKB.woff +0 -0
- package/dist/app/assets/eb-garamond-latin-600-normal-DHwxsLHv.woff2 +0 -0
- package/dist/app/assets/eb-garamond-latin-600-normal-xCe6GkOx.woff +0 -0
- package/dist/app/assets/eb-garamond-latin-ext-400-normal-B4EmgUmt.woff +0 -0
- package/dist/app/assets/eb-garamond-latin-ext-400-normal-o4A__6QZ.woff2 +0 -0
- package/dist/app/assets/eb-garamond-latin-ext-600-normal-CoWPx8v4.woff +0 -0
- package/dist/app/assets/eb-garamond-latin-ext-600-normal-CrweTMKz.woff2 +0 -0
- package/dist/app/assets/eb-garamond-vietnamese-400-normal-CLvJdMEL.woff2 +0 -0
- package/dist/app/assets/eb-garamond-vietnamese-400-normal-ifvNSiWx.woff +0 -0
- package/dist/app/assets/eb-garamond-vietnamese-600-normal-DgZMCD0h.woff +0 -0
- package/dist/app/assets/eb-garamond-vietnamese-600-normal-Dmi8L14S.woff2 +0 -0
- package/dist/app/assets/empty-field-BN05R29i.svg +151 -0
- package/dist/app/assets/empty-sector-amtiZ3_V.webp +0 -0
- package/dist/app/assets/exo-2-cyrillic-400-normal-DkhFZ3TL.woff2 +0 -0
- package/dist/app/assets/exo-2-cyrillic-400-normal-h9Yg8YHF.woff +0 -0
- package/dist/app/assets/exo-2-cyrillic-600-normal-CENMUrsM.woff2 +0 -0
- package/dist/app/assets/exo-2-cyrillic-600-normal-DUkGHFVI.woff +0 -0
- package/dist/app/assets/exo-2-cyrillic-ext-400-normal-CkIweJqd.woff2 +0 -0
- package/dist/app/assets/exo-2-cyrillic-ext-400-normal-iCCHmvbS.woff +0 -0
- package/dist/app/assets/exo-2-cyrillic-ext-600-normal-Bva7FavC.woff +0 -0
- package/dist/app/assets/exo-2-cyrillic-ext-600-normal-c2lTakb1.woff2 +0 -0
- package/dist/app/assets/exo-2-latin-400-normal-D8MC3_dU.woff2 +0 -0
- package/dist/app/assets/exo-2-latin-400-normal-_vYD6UCb.woff +0 -0
- package/dist/app/assets/exo-2-latin-600-normal-DOMk466V.woff2 +0 -0
- package/dist/app/assets/exo-2-latin-600-normal-DZPWd1Z-.woff +0 -0
- package/dist/app/assets/exo-2-latin-ext-400-normal-BiLgrt0k.woff2 +0 -0
- package/dist/app/assets/exo-2-latin-ext-400-normal-eOOluZza.woff +0 -0
- package/dist/app/assets/exo-2-latin-ext-600-normal-70qtqWxx.woff2 +0 -0
- package/dist/app/assets/exo-2-latin-ext-600-normal-DMfc7h1y.woff +0 -0
- package/dist/app/assets/exo-2-vietnamese-400-normal-BgZK7AGH.woff2 +0 -0
- package/dist/app/assets/exo-2-vietnamese-400-normal-C-HDQfeq.woff +0 -0
- package/dist/app/assets/exo-2-vietnamese-600-normal-D_uNeL95.woff2 +0 -0
- package/dist/app/assets/exo-2-vietnamese-600-normal-H3VyuMj8.woff +0 -0
- package/dist/app/assets/favicon-D8c5IAlv.svg +16 -0
- package/dist/app/assets/fields-BxauQmw0.webp +0 -0
- package/dist/app/assets/fira-code-cyrillic-400-normal-UC0NFL4U.woff2 +0 -0
- package/dist/app/assets/fira-code-cyrillic-400-normal-dc1q3VD7.woff +0 -0
- package/dist/app/assets/fira-code-cyrillic-ext-400-normal-Buh61xzB.woff +0 -0
- package/dist/app/assets/fira-code-cyrillic-ext-400-normal-txZ9Fk_1.woff2 +0 -0
- package/dist/app/assets/fira-code-greek-400-normal-B2Gh_Y8s.woff2 +0 -0
- package/dist/app/assets/fira-code-greek-400-normal-DobhaxvF.woff +0 -0
- package/dist/app/assets/fira-code-greek-ext-400-normal-DR7mBgIM.woff2 +0 -0
- package/dist/app/assets/fira-code-greek-ext-400-normal-DSPUheWg.woff +0 -0
- package/dist/app/assets/fira-code-latin-400-normal-C-QZfXAs.woff +0 -0
- package/dist/app/assets/fira-code-latin-400-normal-DGosTW8U.woff2 +0 -0
- package/dist/app/assets/fira-code-latin-ext-400-normal-DG73JjOf.woff +0 -0
- package/dist/app/assets/fira-code-latin-ext-400-normal-KSMg0QLl.woff2 +0 -0
- package/dist/app/assets/fira-code-symbols2-400-normal-9X26I2LK.woff2 +0 -0
- package/dist/app/assets/fira-code-symbols2-400-normal-_QEZCEwe.woff +0 -0
- package/dist/app/assets/fredoka-latin-600-normal-C4zohCW5.woff2 +0 -0
- package/dist/app/assets/fredoka-latin-600-normal-CcrEjrB4.woff +0 -0
- package/dist/app/assets/grenze-gotisch-latin-600-normal-C3H1tCTC.woff2 +0 -0
- package/dist/app/assets/grenze-gotisch-latin-600-normal-DwyVc51H.woff +0 -0
- package/dist/app/assets/grenze-gotisch-latin-800-normal-BIIxJnpI.woff2 +0 -0
- package/dist/app/assets/grenze-gotisch-latin-800-normal-DByO6Q7M.woff +0 -0
- package/dist/app/assets/ibm-plex-sans-cyrillic-400-normal-BTotfTJu.woff +0 -0
- package/dist/app/assets/ibm-plex-sans-cyrillic-400-normal-DZqxrq2p.woff2 +0 -0
- package/dist/app/assets/ibm-plex-sans-cyrillic-600-normal-71GNu3SW.woff2 +0 -0
- package/dist/app/assets/ibm-plex-sans-cyrillic-600-normal-BGq0mW3O.woff +0 -0
- package/dist/app/assets/ibm-plex-sans-cyrillic-ext-400-normal-Dsrv2Tcn.woff +0 -0
- package/dist/app/assets/ibm-plex-sans-cyrillic-ext-400-normal-g30qAdWV.woff2 +0 -0
- package/dist/app/assets/ibm-plex-sans-cyrillic-ext-600-normal-Bz0x94Yp.woff +0 -0
- package/dist/app/assets/ibm-plex-sans-cyrillic-ext-600-normal-DUMzJB7m.woff2 +0 -0
- package/dist/app/assets/ibm-plex-sans-greek-400-normal-D9ESIMu3.woff +0 -0
- package/dist/app/assets/ibm-plex-sans-greek-400-normal-_efipK4i.woff2 +0 -0
- package/dist/app/assets/ibm-plex-sans-greek-600-normal-D-CqTdkO.woff +0 -0
- package/dist/app/assets/ibm-plex-sans-greek-600-normal-DzTrcv_p.woff2 +0 -0
- package/dist/app/assets/ibm-plex-sans-latin-400-normal-CDDApCn2.woff2 +0 -0
- package/dist/app/assets/ibm-plex-sans-latin-400-normal-CYLoc0-x.woff +0 -0
- package/dist/app/assets/ibm-plex-sans-latin-600-normal-Cu4Hd6ag.woff +0 -0
- package/dist/app/assets/ibm-plex-sans-latin-600-normal-CuJfVYMP.woff2 +0 -0
- package/dist/app/assets/ibm-plex-sans-latin-ext-400-normal-C5H60-Va.woff2 +0 -0
- package/dist/app/assets/ibm-plex-sans-latin-ext-400-normal-RBey6euL.woff +0 -0
- package/dist/app/assets/ibm-plex-sans-latin-ext-600-normal-DIrixKbi.woff +0 -0
- package/dist/app/assets/ibm-plex-sans-latin-ext-600-normal-DOrvGEcy.woff2 +0 -0
- package/dist/app/assets/ibm-plex-sans-vietnamese-400-normal-DG4YqDda.woff2 +0 -0
- package/dist/app/assets/ibm-plex-sans-vietnamese-400-normal-fK1oJ5dG.woff +0 -0
- package/dist/app/assets/ibm-plex-sans-vietnamese-600-normal-DgdngZtN.woff +0 -0
- package/dist/app/assets/ibm-plex-sans-vietnamese-600-normal-DpPYBSTl.woff2 +0 -0
- package/dist/app/assets/index-CVbMaY02.js +51 -0
- package/dist/app/assets/index-DjyOI2P3.css +1 -0
- package/dist/app/assets/lightspeed-LxKj3vD3.svg +68 -0
- package/dist/app/assets/mark-bSC__Aar.svg +188 -0
- package/dist/app/assets/nebula-t0QcaA3K.webp +0 -0
- package/dist/app/assets/orbitron-latin-600-normal-75H6acHo.woff +0 -0
- package/dist/app/assets/orbitron-latin-600-normal-mazHmDYu.woff2 +0 -0
- package/dist/app/assets/orbitron-latin-700-normal-4jsRXGGJ.woff2 +0 -0
- package/dist/app/assets/orbitron-latin-700-normal-DmYOh-W9.woff +0 -0
- package/dist/app/assets/pallets-rO-RsztZ.webp +0 -0
- package/dist/app/assets/pixelify-sans-cyrillic-400-normal-Ckz2YJkH.woff2 +0 -0
- package/dist/app/assets/pixelify-sans-cyrillic-400-normal-DfOZNMlW.woff +0 -0
- package/dist/app/assets/pixelify-sans-cyrillic-600-normal-B3EuUOZG.woff +0 -0
- package/dist/app/assets/pixelify-sans-cyrillic-600-normal-BhqNJYOZ.woff2 +0 -0
- package/dist/app/assets/pixelify-sans-latin-400-normal-DLrIX9QE.woff2 +0 -0
- package/dist/app/assets/pixelify-sans-latin-400-normal-JapMNN6Z.woff +0 -0
- package/dist/app/assets/pixelify-sans-latin-600-normal-BNlgYbDL.woff +0 -0
- package/dist/app/assets/pixelify-sans-latin-600-normal-Dd_Dy7u5.woff2 +0 -0
- package/dist/app/assets/pixelify-sans-latin-ext-400-normal-BkfTUL4s.woff +0 -0
- package/dist/app/assets/pixelify-sans-latin-ext-400-normal-DdH6zlBQ.woff2 +0 -0
- package/dist/app/assets/pixelify-sans-latin-ext-600-normal-CDaIumwU.woff +0 -0
- package/dist/app/assets/pixelify-sans-latin-ext-600-normal-Dha6RiOG.woff2 +0 -0
- package/dist/app/assets/racking-BI-9puyv.webp +0 -0
- package/dist/app/assets/source-serif-4-cyrillic-600-normal-BDP5YDHD.woff2 +0 -0
- package/dist/app/assets/source-serif-4-cyrillic-600-normal-DFnC3vAY.woff +0 -0
- package/dist/app/assets/source-serif-4-cyrillic-ext-600-normal-D_E8FDgP.woff2 +0 -0
- package/dist/app/assets/source-serif-4-cyrillic-ext-600-normal-DiT2IGQm.woff +0 -0
- package/dist/app/assets/source-serif-4-greek-600-normal-DdRkKr-1.woff2 +0 -0
- package/dist/app/assets/source-serif-4-greek-600-normal-DhXQw1Kl.woff +0 -0
- package/dist/app/assets/source-serif-4-latin-600-normal-DMD1h6_f.woff +0 -0
- package/dist/app/assets/source-serif-4-latin-600-normal-DouSKlru.woff2 +0 -0
- package/dist/app/assets/source-serif-4-latin-ext-600-normal-0sIUyHMO.woff2 +0 -0
- package/dist/app/assets/source-serif-4-latin-ext-600-normal-C6NNqpJh.woff +0 -0
- package/dist/app/assets/source-serif-4-vietnamese-600-normal-B0WJbuqT.woff +0 -0
- package/dist/app/assets/source-serif-4-vietnamese-600-normal-CznyfUKR.woff2 +0 -0
- package/dist/app/assets/star-chart-Chk7Xt5X.svg +91 -0
- package/dist/app/assets/starfield-BM71b4P5.svg +112 -0
- package/dist/app/assets/theme-94QYOO7U.css +1 -0
- package/dist/app/assets/theme-DNLvgU8q.css +1 -0
- package/dist/app/assets/theme-ofha-KFg.css +1 -0
- package/dist/app/assets/vellum-DlU0Uxzz.webp +0 -0
- package/dist/app/assets/war-map-_sup_aJg.webp +0 -0
- package/dist/app/assets/wood-panel-CFA5lKLa.svg +211 -0
- package/dist/app/index.html +16 -0
- package/dist/server/toil-ui.js +17929 -0
- package/package.json +96 -4
package/README.md
CHANGED
|
@@ -1,3 +1,729 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Toil UI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A local web app for seeing work across Jira, Azure DevOps and GitHub, read through
|
|
4
|
+
[toil](https://www.npmjs.com/package/@imagile-dev/toil): one dashboard per dossier,
|
|
5
|
+
with its stories, pull requests, builds and deployments side by side, a pull
|
|
6
|
+
requests view for what is waiting on review, and a daily worklog of what happened.
|
|
7
|
+
|
|
8
|
+
**Status: alpha, local only.** It runs on your own machine, binds loopback, and
|
|
9
|
+
reads through toil with your own connections and dossiers, read-only. Its
|
|
10
|
+
settings pages are the one place it changes anything of toil's, and only toil's own
|
|
11
|
+
connections and dossiers. The worklog keeps its pages and the notes you add in its own
|
|
12
|
+
data folder, and writes anywhere else only when you export a page. Its Feedback dialog sends a report to Imagile through
|
|
13
|
+
`toil feedback`, only when you approve it. It is a separate package from toil: installing toil
|
|
14
|
+
never installs it.
|
|
15
|
+
|
|
16
|
+
## Start it
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npx @imagile-dev/toil-ui
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
It needs Node 24.14 or later and installs one dependency, `@imagile-dev/toil`, at
|
|
23
|
+
the exact version it was built with. Until a version shows on
|
|
24
|
+
[npm](https://www.npmjs.com/package/@imagile-dev/toil-ui), run it from a clone of
|
|
25
|
+
the repository:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm ci --ignore-scripts
|
|
29
|
+
npm run build -w ui
|
|
30
|
+
node ui/dist/server/toil-ui.js
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
It prints one URL and keeps running until you press Ctrl+C:
|
|
34
|
+
|
|
35
|
+
```text
|
|
36
|
+
Toil UI 0.1.0-alpha.1 (alpha, local only), on toil 0.1.0-alpha.3
|
|
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
|
+
The cache is /home/you/.toil-ui/cache/toil-ui.db, kept 30 days after each sync; toil-ui wipe deletes it.
|
|
39
|
+
|
|
40
|
+
Open this URL in your browser. It carries this launch's token, so keep it to yourself:
|
|
41
|
+
http://127.0.0.1:53117/?token=<token>
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Open that URL. The page trades the token for a session it keeps in memory, and the
|
|
45
|
+
token leaves the address bar. A reloaded page forgets its session, so open the URL
|
|
46
|
+
again to get back in. Each start prints a new token. Toil UI opens no browser
|
|
47
|
+
itself.
|
|
48
|
+
|
|
49
|
+
`toil-ui --sample` serves the sample dossiers and the scripted agent the site's
|
|
50
|
+
preview uses, with nothing connected to a tracker.
|
|
51
|
+
|
|
52
|
+
## What it reads
|
|
53
|
+
|
|
54
|
+
Each dashboard reads its dossier the way `toil dossiers show` describes it: the
|
|
55
|
+
Jira project, the Azure DevOps project and pipelines, the GitHub repository and
|
|
56
|
+
project board, and the OpenShift namespace of each environment. A GitHub section
|
|
57
|
+
with no `projects` reads the repository's own issues, open and closed, as its work
|
|
58
|
+
items, with the history of every open one and the 50 most recently closed. Pull
|
|
59
|
+
requests are read from every code host the dossier names (GitHub, Bitbucket Data
|
|
60
|
+
Center and Cloud, Azure DevOps Server and Services) with `pr list`, then `pr get
|
|
61
|
+
--include reviews,checks,commits,files` for every open one and the 20 newest closed or
|
|
62
|
+
merged ones, and mapped to OWI 0.2 changes; a GitHub repository's CODEOWNERS is read
|
|
63
|
+
with `github repo file` when an open pull request has no reviewer. Every call runs
|
|
64
|
+
in-process through `@imagile-dev/toil/api`, read-only, and toil's audit log
|
|
65
|
+
records it with `via: "api"` and `caller: "toil-ui"`. A call that fails shows on
|
|
66
|
+
its own panel with toil's message and fix.
|
|
67
|
+
|
|
68
|
+
## Pull requests
|
|
69
|
+
|
|
70
|
+
Each dossier has a **Pull requests** view (`#/dossier/<name>/prs`, linked from its
|
|
71
|
+
dashboard and the header), built from OWI 0.2 changes:
|
|
72
|
+
|
|
73
|
+
- **Waiting now:** the open pull requests, longest wait first, each with what it
|
|
74
|
+
waits on (review, changes, checks, merge, or a draft its author holds), since when
|
|
75
|
+
in working days and why, who wrote it (a person, an agent or a bot, with the signal
|
|
76
|
+
that said so), the work items it names, and its size, XS to XL by changed lines.
|
|
77
|
+
- **Flags:** no first review in 2 working days, checks failing for over a day, a merge
|
|
78
|
+
conflict, no linked work item, a work item done while its pull request is open, and
|
|
79
|
+
a merged pull request whose item isn't done, each with what it rests on.
|
|
80
|
+
- **Flow:** pickup (opened to first review), review (first review to approval) and
|
|
81
|
+
merge (approval to merge) times, review rounds, sizes and merges per week, over six
|
|
82
|
+
weeks, each split by people, agents and bots and each with its sample size and what
|
|
83
|
+
couldn't be measured.
|
|
84
|
+
- **Suggested reviewers:** for an open pull request with nobody asked, the CODEOWNERS
|
|
85
|
+
of its paths and the earlier reviewers of the same files and folders, each as a
|
|
86
|
+
proposal with the `toil … --allow-write` line to ask them.
|
|
87
|
+
|
|
88
|
+
The dossier's work item keys are matched in each pull request's title, branch and
|
|
89
|
+
description (a Jira project's `PAY-101`, Azure Boards' `AB#2302`, a GitHub
|
|
90
|
+
repository's `owner/repo#41`). A code host's section may set author kinds by hand,
|
|
91
|
+
`"authorKinds": { "release-bot": "BOT" }`, which win over every other signal.
|
|
92
|
+
|
|
93
|
+
## People
|
|
94
|
+
|
|
95
|
+
Each dossier has a **People** view (`#/dossier/<name>/people`, in the header), built
|
|
96
|
+
from the same OWI work items and changes as the dashboard and the pull requests view,
|
|
97
|
+
and from the dossier's `people` section, which says who each person is in every
|
|
98
|
+
system (`toil dossiers person`, or **Settings, Dossiers**):
|
|
99
|
+
|
|
100
|
+
- **A card per person**, agents included, in name order: their work in progress by
|
|
101
|
+
status with how long each item has sat in it, their open pull requests and what
|
|
102
|
+
each waits on, the reviews waiting on them (oldest first), their blocked items and
|
|
103
|
+
what blocks each, and what they did in the last 14 days. A link opens their items
|
|
104
|
+
on the dashboard's board, filtered to them.
|
|
105
|
+
- **A team strip:** work in progress against the dossier's `wipLimit` and who is over
|
|
106
|
+
it, the review queue, and the current sprint's unassigned items.
|
|
107
|
+
- **Agents:** a person with `kind: "agent"`, matched by the same signals as a pull
|
|
108
|
+
request's author kind (its account, a Co-Authored-By trailer, a branch prefix) where
|
|
109
|
+
the signal names it. A person's own pull request written with an agent says so.
|
|
110
|
+
- **Accounts the dossier doesn't map** get cards of their own, so no work goes
|
|
111
|
+
missing. One that shares an email with a person, or with an account in another
|
|
112
|
+
system, is suggested as a match with the `toil dossiers person` line that applies
|
|
113
|
+
it; it is applied only when someone presses the button, and an email that fits more
|
|
114
|
+
than one candidate suggests nothing and says why. Accounts that only wrote bots'
|
|
115
|
+
pull requests are left out and counted.
|
|
116
|
+
|
|
117
|
+
It shows what is on each plate and never scores anyone: no ranking, no productivity
|
|
118
|
+
figure, no person-to-person comparison and no line or commit counts. Flow metrics
|
|
119
|
+
stay team-level, in the pull requests view.
|
|
120
|
+
|
|
121
|
+
## Readiness and the Command Center
|
|
122
|
+
|
|
123
|
+
Before a work item goes to an agent, Toil UI checks whether it is ready for one. The
|
|
124
|
+
check uses no model and no premium request: only the item's cached OWI record, the
|
|
125
|
+
dossier's other items, and at most one live read, made when you press for it
|
|
126
|
+
(`ui/src/model/readiness.ts`). Its verdict is **ready**, **thin** or **blocked**, with
|
|
127
|
+
one row per check:
|
|
128
|
+
|
|
129
|
+
| Check | Passes when | Otherwise |
|
|
130
|
+
|---|---|---|
|
|
131
|
+
| Acceptance criteria | The field the dossier names has them, or the description has an "Acceptance criteria", "Definition of done" or "Done when" heading with text under it, or a checklist | thin |
|
|
132
|
+
| Description | At least `minWords` words (25 by default) of real text, not counting the dossier's template lines, placeholder lines (TBD, N/A, lorem ipsum) or unfilled `<slots>` | thin |
|
|
133
|
+
| Done state | It isn't done, and a way to Done is known: a GitHub issue closes from any state; otherwise an item of the same type in the dossier reached Done, or the live read finds a Done state (Azure DevOps) or a move into Done (Jira) | blocked when it's already done, or the workflow has no Done state; thin when it isn't known |
|
|
134
|
+
| Blockers | No open item blocks it | blocked by an open item; thin for a blocker the dossier doesn't hold |
|
|
135
|
+
| Scope | It comes from one of the dossier's sources, and the dossier names a repository | blocked from outside the dossier; thin with no repository |
|
|
136
|
+
|
|
137
|
+
The verdict is blocked when any row is, thin when any row is, and ready only when every
|
|
138
|
+
row passes. Each area's section in the dossier sets it up:
|
|
139
|
+
|
|
140
|
+
```json
|
|
141
|
+
"jira": {
|
|
142
|
+
"project": "PAY",
|
|
143
|
+
"fields": { "acceptanceCriteria": "customfield_10500" },
|
|
144
|
+
"readiness": { "minWords": 20, "templates": ["## What\n## Why\n## Acceptance criteria"] }
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
`fields.acceptanceCriteria` is also the area's `--field` alias. An Azure DevOps section
|
|
149
|
+
that names none uses `Microsoft.VSTS.Common.AcceptanceCriteria`.
|
|
150
|
+
|
|
151
|
+
- **On each item's page**, a **Ready for an agent?** panel shows the verdict and its
|
|
152
|
+
rows, each with where its answer came from. **Check the workflow live** makes the one
|
|
153
|
+
live read, read-only: `jira issue transitions` for a Jira issue, `ado work-item
|
|
154
|
+
states` for an Azure DevOps type. A GitHub issue needs none.
|
|
155
|
+
- **The Command Center** (`#/dossier/<name>/command-center`, in the header) lists every
|
|
156
|
+
work item with its verdict and, for each one that isn't ready, the rows that say why.
|
|
157
|
+
It filters by verdict, status, type, assignee and source, and makes no live read.
|
|
158
|
+
It is strict: only ready items are slated, in the dossier's order, under a plan id
|
|
159
|
+
that changes when anything in the plan does.
|
|
160
|
+
- **Starting the plan comes with assign-to-agent (#293).** Until then the start button
|
|
161
|
+
is disabled and says so; the plan it would start is shown above it.
|
|
162
|
+
- **The agent** gets `readiness_list` and `readiness_get` and a starter, "Which items
|
|
163
|
+
are ready for an agent?" (The agent, below).
|
|
164
|
+
## Worklog
|
|
165
|
+
|
|
166
|
+
Each dossier has a **Worklog** (`#/dossier/<name>/worklog`, linked from the header):
|
|
167
|
+
one page a day, folded by code from what the cache holds, facts only. No model writes
|
|
168
|
+
a line of it. A calendar shows the days that have a page, with how many lines each
|
|
169
|
+
has; a day opens as `#/dossier/<name>/worklog/<yyyy-mm-dd>`. Days and times are UTC,
|
|
170
|
+
as everywhere else in Toil UI.
|
|
171
|
+
|
|
172
|
+
A page has:
|
|
173
|
+
|
|
174
|
+
- **Work items** that changed status (from, to, who and when), were added to or
|
|
175
|
+
dropped from a sprint, or got a new blocker.
|
|
176
|
+
- **Pull requests** opened, reviewed (approved, changes requested, commented), merged
|
|
177
|
+
or declined.
|
|
178
|
+
- **Builds and deployments** that failed or recovered (deployments from OpenShift,
|
|
179
|
+
whose state a sync can see change): a build is recovered when a
|
|
180
|
+
passing run follows a failing one of the same pull request or pipeline.
|
|
181
|
+
- **Agent runs:** each question an agent adapter answers in the Ask pane, when it
|
|
182
|
+
started and ended,
|
|
183
|
+
whether it finished, failed, was stopped or was stopped at a usage cap, what it
|
|
184
|
+
cited, and its proposals, each
|
|
185
|
+
with whether toil's audit log (`toil audit list`) shows a person ran that write on
|
|
186
|
+
the same item afterwards. Each run's transcript is kept beside the pages and shown
|
|
187
|
+
under the run, labelled as the agent's.
|
|
188
|
+
- **Notes** a person added that day, on today's page.
|
|
189
|
+
- **Sources:** each source's syncs that day.
|
|
190
|
+
|
|
191
|
+
Every line links to its item, pull request, build or transcript, where the source has a
|
|
192
|
+
page for it. Two kinds of fact
|
|
193
|
+
come in differently. Status and sprint changes, pull requests, reviews and builds
|
|
194
|
+
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 and a deployment that failed or came back have
|
|
196
|
+
no time in the trackers, so a sync sees them by comparing what it read with the last
|
|
197
|
+
sync, and the line says which sync first saw it and when the one before ran.
|
|
198
|
+
|
|
199
|
+
**What a page can't vouch for is said at the top:** a day before the earliest sync the
|
|
200
|
+
cache holds, a day no sync of a source ran on, a sync that failed, a source whose latest
|
|
201
|
+
sync failed, today so far, and a day older than the retention period.
|
|
202
|
+
|
|
203
|
+
**How it's kept.** Each sync records its facts in the cache, one row per fact by a key
|
|
204
|
+
that never changes, so the same fact synced twice is one row. After each sync every
|
|
205
|
+
page is folded again from the cache and written where its text changed, as Markdown
|
|
206
|
+
in the data folder:
|
|
207
|
+
|
|
208
|
+
```text
|
|
209
|
+
<data folder>/cache/worklog/<dossier>/<yyyy-mm>/<yyyy-mm-dd>.md
|
|
210
|
+
<data folder>/cache/worklog/<dossier>/runs/<run id>.md
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
The pages live under the cache's retention: a day whose rows are gone loses its page,
|
|
214
|
+
and a wipe deletes them all. **Rebuild this day** folds the day again and says whether
|
|
215
|
+
it came out the same as the page kept; the same cache always gives the same page.
|
|
216
|
+
|
|
217
|
+
**Export** writes the day's or the month's Markdown into a folder you name, through
|
|
218
|
+
toil's own file service: `toil util encode base64 --decode --out <file>`, run with that
|
|
219
|
+
folder as its workspace, which writes a new file only and never into toil's own
|
|
220
|
+
config. Publishing an exported page is a proposal: `toil confluence page create
|
|
221
|
+
--body-file <file> --markdown` in the dossier's Confluence space, or `toil github issue
|
|
222
|
+
create --body-file <file>` in its repository, for you to run through toil's write gate.
|
|
223
|
+
Toil UI posts nothing. With sample data, notes and export are off.
|
|
224
|
+
|
|
225
|
+
## Toil's configuration
|
|
226
|
+
|
|
227
|
+
The Settings pages manage what `toil connections` and `toil dossiers` manage, by
|
|
228
|
+
running those commands through `@imagile-dev/toil/api`, never by editing a file:
|
|
229
|
+
|
|
230
|
+
- **Connections:** list, add, test, set the default, turn writes on or off,
|
|
231
|
+
replace a secret (`toil connections login`) and remove. A secret goes from a
|
|
232
|
+
password field to toil, which keeps it in the OS credential store; the page
|
|
233
|
+
clears the field, and it is never logged, stored by Toil UI, or sent back.
|
|
234
|
+
Turning writes on asks you to type the connection's name, as the CLI does. A
|
|
235
|
+
connection made by `TOIL_*` env vars alone is shown read-only, with where it
|
|
236
|
+
came from.
|
|
237
|
+
- **Dossiers:** create one, add a repository, link an area, name a field, and
|
|
238
|
+
show and check any of them. A link to a connection with writes on is refused
|
|
239
|
+
here, as over MCP: make it on the CLI.
|
|
240
|
+
- **Bounds and time limit:** toil has no command for these, so they are shown
|
|
241
|
+
read-only, with the file or env var that sets them.
|
|
242
|
+
- **Usage:** how toil is used on this machine, from `toil audit stats`, which
|
|
243
|
+
reads only toil's local audit log: calls per day, the split between Toil UI, the
|
|
244
|
+
CLI and MCP, the commands used most, the ones that fail most with their top
|
|
245
|
+
error code and its usual fix (and, on request, their recent failures from
|
|
246
|
+
`toil audit list`), and the commands nothing called. It needs a toil with
|
|
247
|
+
`audit stats`, newer than 0.1.0-alpha.3; with an older one the page shows toil's
|
|
248
|
+
error.
|
|
249
|
+
|
|
250
|
+
Every change is an explicit action, runs the command's own checks, and is in
|
|
251
|
+
toil's audit log as `caller: "toil-ui"`. The page can run no other command on this
|
|
252
|
+
path, and never a tracker write. Adding or changing connections needs a toil
|
|
253
|
+
newer than 0.1.0-alpha.2; with that one, use the CLI.
|
|
254
|
+
|
|
255
|
+
## Feedback
|
|
256
|
+
|
|
257
|
+
The **Feedback** button in the header opens a dialog for a bug report or a feature
|
|
258
|
+
request: the kind, a title, the details and your email. It sends through
|
|
259
|
+
`toil feedback` (toil's `skills/toil/core.md`, **Feedback**), never on its own:
|
|
260
|
+
|
|
261
|
+
- **A live preview.** As you type, the page asks toil for the report it would send,
|
|
262
|
+
read-only, and shows it exactly, with the endpoint. Nothing is sent to show it.
|
|
263
|
+
- **toil's disclaimer, and a checkbox.** The report goes to Imagile LLC, which files
|
|
264
|
+
it as a public GitHub issue; your email stays private; you remove company data
|
|
265
|
+
first. Send works only while the box is ticked, and any edit clears it, so you
|
|
266
|
+
agree to the report on screen and no other.
|
|
267
|
+
- **Only what you typed.** toil adds its version and commit, nothing else: no
|
|
268
|
+
dossier, connection, host or cached data.
|
|
269
|
+
- **The same lock as Settings.** `api/feedback` needs the session, the page's
|
|
270
|
+
Origin and the CSRF token, takes the four fields and nothing else, and runs
|
|
271
|
+
`toil feedback` and no other command. Your tick becomes the yes to the command's
|
|
272
|
+
own consent question. With sample data it sends nothing. With a toil that has no
|
|
273
|
+
`feedback` command (0.1.0-alpha.2), the dialog says so and points at the site's
|
|
274
|
+
form.
|
|
275
|
+
|
|
276
|
+
## Sync and the cache
|
|
277
|
+
|
|
278
|
+
The dashboards read from a local cache, which a sync fills. Press **Sync now** in
|
|
279
|
+
the Sync panel at the foot of the page. The sync makes the same toil calls the
|
|
280
|
+
dashboards make, for every dossier, and stores the answers. The work items go
|
|
281
|
+
through toil's Open Work Item mapping, with their status changes and the pull
|
|
282
|
+
requests, builds and deployments that name them.
|
|
283
|
+
|
|
284
|
+
- **Incremental.** After the first sync, Jira and Azure DevOps searches, and a
|
|
285
|
+
GitHub repository's issues, ask only for what changed since the last good sync (`updatedSince`, five minutes early in
|
|
286
|
+
case the clocks disagree), and the GitHub board marks the issues whose
|
|
287
|
+
`updatedAt` moved. Only those items and their histories are fetched again.
|
|
288
|
+
Pull requests, builds, deployments and iterations have no "changed since" in
|
|
289
|
+
toil, so they're read again each time, bounded as the dashboards bound them.
|
|
290
|
+
- **Every page.** Each call follows `meta.page.nextCursor` to the end, up to 200
|
|
291
|
+
pages, and fails that source, saying so, rather than keep part of a listing.
|
|
292
|
+
- **Each source on its own.** Each area a dossier reads (Jira, Bitbucket, Jenkins,
|
|
293
|
+
OpenShift and so on) is a source with its own state. A source that fails shows
|
|
294
|
+
toil's message and fix in the Sync panel, and keeps its last good data, marked
|
|
295
|
+
stale. The other sources and dossiers aren't touched. The next sync asks it
|
|
296
|
+
for everything since its last good sync, so nothing is missed.
|
|
297
|
+
- **When.** The line under the header says when the data was synced. The panel
|
|
298
|
+
says when each dossier was synced, and shows a running sync's progress
|
|
299
|
+
(requests, pages and retries, from toil's own progress events).
|
|
300
|
+
- **Where.** The cache is one SQLite file, `cache/toil-ui.db` in the data folder,
|
|
301
|
+
through Node's built-in `node:sqlite`, so there's no native module. While Toil
|
|
302
|
+
UI runs, its write-ahead log (`toil-ui.db-wal` and `toil-ui.db-shm`) sits beside
|
|
303
|
+
it, and closing folds the log back into the file. It holds
|
|
304
|
+
ticket content, so it stays on this machine and is readable by your account
|
|
305
|
+
only.
|
|
306
|
+
- **For how long.** Anything not synced again within the retention period (30
|
|
307
|
+
days by default) is deleted, at start and after each sync.
|
|
308
|
+
- **Wiping it.** **Wipe the cache** in the Sync panel deletes it after asking
|
|
309
|
+
first. `toil-ui wipe` does the same from a terminal, once `toil-ui` has
|
|
310
|
+
stopped: a running Toil UI holds `toil-ui.lock` in the data folder, and the
|
|
311
|
+
command refuses while it does. Your trackers are never touched. The next sync fetches everything again.
|
|
312
|
+
- **Deleted tickets.** An item deleted in its tracker stays in the cache until
|
|
313
|
+
the retention period ends or you wipe it, since an incremental search only
|
|
314
|
+
returns items that still exist.
|
|
315
|
+
|
|
316
|
+
The page can run only the reads the dashboards make: `dossiers list` and `dossiers
|
|
317
|
+
show`, and each area's search, history, pull request, build and deployment reads.
|
|
318
|
+
Any other command is refused before it reaches toil, and a change to a tracker is
|
|
319
|
+
never made from the page. The worklog's own calls are made by the server, never named
|
|
320
|
+
by the page: `toil audit list`, read-only, to see whether a proposal was applied, and
|
|
321
|
+
`toil util encode` for an export you asked for.
|
|
322
|
+
|
|
323
|
+
## The agent
|
|
324
|
+
|
|
325
|
+
The docked chat answers with the agent your organization already approved, on the
|
|
326
|
+
subscription you already have. Toil UI has three adapters, each an optional peer
|
|
327
|
+
dependency that is loaded only when you choose it:
|
|
328
|
+
|
|
329
|
+
| Adapter | Package | Starts | Signs in with |
|
|
330
|
+
|---|---|---|---|
|
|
331
|
+
| Claude | `@anthropic-ai/claude-agent-sdk` (and its peer `zod`) | `claude` (Claude Code) | Claude Code's own login, or Bedrock, Foundry or Vertex through Claude Code's environment switches |
|
|
332
|
+
| GitHub Copilot | `@github/copilot-sdk` | `copilot` (the Copilot CLI) | your Copilot seat, through the CLI |
|
|
333
|
+
| Codex | `@openai/codex-sdk` | `codex` (the Codex CLI) | the CLI's ChatGPT sign-in or its own API key setup |
|
|
334
|
+
|
|
335
|
+
```bash
|
|
336
|
+
npm install -g @anthropic-ai/claude-agent-sdk zod # beside a global toil-ui
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
Then choose it under **Settings, Agent**: the adapter, the model (empty for the CLI's
|
|
340
|
+
default), the CLI's path (empty to use the one on `PATH`) and, for Claude, the
|
|
341
|
+
endpoint. The choice is kept in `<data folder>/agent.json`, never in toil's config,
|
|
342
|
+
and has no field for a key: each SDK signs in the way its CLI does. Install the SDK
|
|
343
|
+
with `--omit=optional` if you don't want its bundled copy of the CLI on disk; Toil UI
|
|
344
|
+
never starts that copy anyway.
|
|
345
|
+
|
|
346
|
+
- **Only the CLI already on this machine.** Toil UI finds it on `PATH` (skipping
|
|
347
|
+
relative entries and the working directory) or at the path you set, which must
|
|
348
|
+
name that CLI, hands that path to the SDK, and never downloads one.
|
|
349
|
+
- **An environment of its own.** The CLI gets only what it needs to run (paths, home
|
|
350
|
+
and temp folders, proxy and CA settings) and its own sign-in variables. toil's
|
|
351
|
+
`TOIL_*` variables, `GITHUB_TOKEN` and CI tokens never reach it. Not found is a plain
|
|
352
|
+
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`.
|
|
354
|
+
- **Read-only tools, one dossier.** The agent gets `owi_query`, `owi_get`,
|
|
355
|
+
`owi_similar` (likely duplicates, scored as `toil util owi similar` scores them)
|
|
356
|
+
and `owi_history` over the cache, `pr_query`, `pr_get` and `pr_metrics` over its
|
|
357
|
+
pull requests (what each waits on, its flags, and flow figures by author kind with
|
|
358
|
+
their sample sizes), `people_list` and `person_get` (each person's plate as the
|
|
359
|
+
People view works it out, with the dossier read live through `dossiers show`, and
|
|
360
|
+
told it describes load, never performance), `readiness_list` and
|
|
361
|
+
`readiness_get` (each item's readiness verdict and its rows, as the Command Center
|
|
362
|
+
works them out), `proposal_fields` (a write command's input fields,
|
|
363
|
+
told it describes load, never performance), `worklog_day` (one day's worklog page,
|
|
364
|
+
with what it can't vouch for), `proposal_fields` (a write command's input fields,
|
|
365
|
+
from toil's registry), and `toil mcp`'s read tools for live lookups, called through
|
|
366
|
+
toil's `execute()` with `readOnly: true`. The dossier is fixed to the one on screen.
|
|
367
|
+
There is no write tool, and each SDK's own tools (shell, files, web, plugins, other
|
|
368
|
+
MCP servers) are switched off.
|
|
369
|
+
- **Citations are checked.** Every answer cites the work items and pull requests it
|
|
370
|
+
used as links.
|
|
371
|
+
The server holds each id it names to what its tools returned, and flags any other
|
|
372
|
+
as unverified above the answer.
|
|
373
|
+
- **Writes are proposals.** A change the agent suggests comes back as a card with the
|
|
374
|
+
`toil … --allow-write` command line for you to run through toil's write gate. The
|
|
375
|
+
agent can't run it.
|
|
376
|
+
- **Codex takes tools only from an MCP server**, so for the length of one question
|
|
377
|
+
Toil UI serves them at `api/agent/mcp` on its own loopback port, behind a token made
|
|
378
|
+
for that question. The token reaches Codex in its environment, never on its command
|
|
379
|
+
line, and the endpoint refuses any request carrying a browser's `Origin`.
|
|
380
|
+
- **Codex runs in a Codex home of Toil UI's own**, `<data folder>/cache/codex`, not
|
|
381
|
+
yours. Codex adds whatever its home's config names (MCP servers, profiles, plugins,
|
|
382
|
+
hooks, skills) to what it's given, so with your own home your servers would start
|
|
383
|
+
beside Toil UI's. Toil UI's home holds a `config.toml` it rewrites before every
|
|
384
|
+
question, so `codex mcp list` there shows only `toil_ui`, and `auth.json`, a hard
|
|
385
|
+
link to the one in your Codex home (`$CODEX_HOME`, else `~/.codex`). A hard link is
|
|
386
|
+
the same file under a second name, not a copy: a token Codex refreshes is refreshed
|
|
387
|
+
for both, and once you sign out of Codex the next question removes the link and says
|
|
388
|
+
so. With no `auth.json` (a sign-in kept in the OS keyring, or none), `CODEX_API_KEY`
|
|
389
|
+
in Toil UI's environment signs in instead. Your data folder and your Codex home must
|
|
390
|
+
be on the same drive. `toil-ui wipe` deletes this home with the cache, along with
|
|
391
|
+
Codex's record of Toil UI's questions, and leaves your own `auth.json` alone.
|
|
392
|
+
|
|
393
|
+
- **Your own instructions.** Under **Settings, Agent**, general instructions (for
|
|
394
|
+
example "answer in British English") and a custom voice, each up to 4,000
|
|
395
|
+
characters, kept in `agent.json` beside the adapter. They come after the rules in
|
|
396
|
+
the prompt, and the rules win: they can't change the citations, the figures, the
|
|
397
|
+
proposals or what the tools can do. **Show the full prompt** shows exactly what
|
|
398
|
+
the agent is sent.
|
|
399
|
+
|
|
400
|
+
With no adapter chosen, the chat says so and names the three. `toil-ui --sample`
|
|
401
|
+
keeps the scripted agent, which answers its starter questions from the sample data.
|
|
402
|
+
|
|
403
|
+
### What the agent's models used
|
|
404
|
+
|
|
405
|
+
Each SDK reports what a question used, and Toil UI keeps that report, one record per
|
|
406
|
+
model call or running total, read only from the SDK's own events (no billing API is
|
|
407
|
+
called):
|
|
408
|
+
|
|
409
|
+
| Adapter | What the SDK reports | What Toil UI shows |
|
|
410
|
+
|---|---|---|
|
|
411
|
+
| 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
|
+
| 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 |
|
|
414
|
+
|
|
415
|
+
- **Under each answer**, one line per model: `2.1k in · 380 out · 14k cached · cache
|
|
416
|
+
write not reported · ~$0.012 (SDK estimate)`. A figure the SDK didn't report reads
|
|
417
|
+
"not reported", never 0.
|
|
418
|
+
- **In the chat's heading**, the chat's running total, split by model, and how full
|
|
419
|
+
the last answer's context got, where the SDK says (Claude and Copilot; Codex's SDK
|
|
420
|
+
doesn't).
|
|
421
|
+
- **Settings, Agent usage** (beside Usage, which counts toil's own commands): the last
|
|
422
|
+
30 days by day, adapter, model and dossier, the chats that used the most, and an
|
|
423
|
+
**Export as CSV** download made in the page.
|
|
424
|
+
- **One adding-up rule**, `addUp` in `src/model-usage.ts`, read by the server's caps,
|
|
425
|
+
the footer, the heading and Settings: reports with one id are one report, merged to
|
|
426
|
+
the highest of each figure (a running total), and different ids are summed.
|
|
427
|
+
- **The ledger** is the cache's `usage` table, apart from everything a sync writes: a
|
|
428
|
+
sync's cleanup or a dossier leaving never lowers a total. It follows the cache's
|
|
429
|
+
retention, `toil-ui wipe` clears it, and it is never sent anywhere.
|
|
430
|
+
|
|
431
|
+
**Caps** are optional and off until you turn one on, under Settings, Agent usage: a
|
|
432
|
+
per-chat and a per-day (UTC) cap for each adapter, in tokens, dollars (Claude's SDK
|
|
433
|
+
estimate, or Codex from your rates) or Copilot premium requests. At 80% the answer
|
|
434
|
+
says so; at 100% the question stops, naming the cap and how to raise it. Claude and
|
|
435
|
+
Copilot report each call as it happens, so their caps stop a run partway; Codex
|
|
436
|
+
reports when an answer ends, so its cap refuses the next question. They live in
|
|
437
|
+
`<data folder>/usage.json`, with the Codex rates. A value that doesn't parse is
|
|
438
|
+
refused, naming the setting, and while the file can't be read the agent answers
|
|
439
|
+
nothing, so a typo can never turn a cap off. A cap counts only what the SDK reports:
|
|
440
|
+
the vendor's own bill is the authority.
|
|
441
|
+
|
|
442
|
+
## Assigning work to an agent
|
|
443
|
+
|
|
444
|
+
From an item's page, or **Assign** on its card on the board, a work item can be
|
|
445
|
+
assigned to Claude, GitHub Copilot or Codex in one of three modes. The agent works on
|
|
446
|
+
the subscription you already have, and nothing it proposes leaves this machine until
|
|
447
|
+
you apply it.
|
|
448
|
+
|
|
449
|
+
| Mode | What the agent does | What it can change |
|
|
450
|
+
|---|---|---|
|
|
451
|
+
| **Refine** | Checks for duplicates, drafts acceptance criteria, suggests an estimate, splits the item into children where it is too big, and asks its open questions | Nothing: every change is a proposal |
|
|
452
|
+
| **Investigate** | Reads the item, its parent, children, links, likely duplicates, pull requests and toil's live reads, and writes a report that cites each source | Nothing: the report is kept with the assignment, and posting it as a comment is a proposal |
|
|
453
|
+
| **Implement** | Works in a copy of the dossier repository's git folder that Toil UI makes in a folder of its own, fills it from the last commit, makes the branch `agent/<key>`, changes and tests the code, and stages the change | Only that clone, with no network. Committing, pushing and opening a pull request are proposals |
|
|
454
|
+
|
|
455
|
+
- **Refine and investigate** get the same read-only tools as the chat (`owi_*`, `pr_*`,
|
|
456
|
+
`proposal_fields` and toil's live reads), with no shell and no file writes.
|
|
457
|
+
- **Implement runs on Codex only, for now.** Codex's own sandbox, `workspace-write`,
|
|
458
|
+
holds the agent's commands and writes to the clone, with no network and none of the
|
|
459
|
+
temp folders Codex adds by default, on Windows (its `unelevated` restricted-token sandbox), macOS and Linux. The clone is
|
|
460
|
+
`<data folder>/cache/work/<assignment>/repo`, so `toil-ui wipe` deletes it; before any git runs there outside the sandbox, Toil UI rewrites its git config and removes its hooks. The dossier's
|
|
461
|
+
repository needs a local path (`toil dossiers add-repo <dossier> <folder>`). The agent stages its change and never commits, pushes or fetches; the
|
|
462
|
+
staged diff is shown through toil's own `git status` and `git diff`, and the commit
|
|
463
|
+
and push are a proposal of the exact git lines to run, since toil has no command
|
|
464
|
+
that pushes.
|
|
465
|
+
- **States**: `queued` (waiting for a free slot, or for a person to press Start),
|
|
466
|
+
`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** lane on the
|
|
468
|
+
dashboard shows each assignment's state, mode, adapter, run time and what it used,
|
|
469
|
+
and the People view shows each agent's assignments.
|
|
470
|
+
- **From the Command Center**, "Start every ready item" assigns each slated item in
|
|
471
|
+
implement mode, in order, on Codex (or the adapter chosen in Settings, when it can
|
|
472
|
+
implement), in the dossier's one repository with a local path, and says what it
|
|
473
|
+
queued or why it started nothing.
|
|
474
|
+
- **The tracker only queues.** An item labelled `agent:refine`, `agent:investigate` or
|
|
475
|
+
`agent:implement`, or assigned to one of the dossier's agents (its `people` with
|
|
476
|
+
`kind: agent`, which queues a refine), appears in the **Agent inbox** on the next
|
|
477
|
+
read. It runs only when a person presses Start.
|
|
478
|
+
- **Applying a proposal** runs its toil command, the one the server stored when the
|
|
479
|
+
run ended, through toil's write gate: the connection needs `writes: true`, and your
|
|
480
|
+
press of Apply is the call's `--allow-write`. Each call toil makes for an assignment
|
|
481
|
+
is in toil's audit log with `caller: "toil-ui"` and `actor: "assignment-<id>"`.
|
|
482
|
+
- **Tracker text is untrusted.** The item is fenced off in the prompt as data, and an
|
|
483
|
+
item that tells the agent to do anything else stops the run, marked `needs you`.
|
|
484
|
+
- **Limits.** One assignment runs at a time and each has 20 minutes, both changeable
|
|
485
|
+
in the lane's **Limits** (1 to 3 at once, 1 to 240 minutes), kept in
|
|
486
|
+
`<data folder>/assignments.json`. An assignment is one chat to the usage caps under
|
|
487
|
+
**Settings, Agent usage**, so a per-chat cap is a per-assignment cap. Either limit
|
|
488
|
+
stops a run cleanly, saying which.
|
|
489
|
+
- **The transcript** keeps the prompts, every tool call, the agent's text, the
|
|
490
|
+
commands and file changes Codex reports, and each proposal and what came of it.
|
|
491
|
+
Each assignment also records what it started on: the toil and Toil UI versions, the
|
|
492
|
+
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
|
|
494
|
+
`<data folder>/cache/assignments/`, so a wipe deletes them.
|
|
495
|
+
- **For programs on the same server**, `api/assignments` lists, assigns, starts,
|
|
496
|
+
stops, applies and dismisses, and `api/assignments/events?since=<n>` streams every
|
|
497
|
+
change of state as NDJSON.
|
|
498
|
+
|
|
499
|
+
## Themes
|
|
500
|
+
|
|
501
|
+
Five built-in themes: Plain, Crate (the default), Harvest, Starship and Realm. Pick
|
|
502
|
+
one from the header, or under **Settings, General**, where two checkboxes say how far
|
|
503
|
+
it goes, both on by default:
|
|
504
|
+
|
|
505
|
+
- **Themed wording:** the theme's own lede, eyebrows, dashboard notes, empty
|
|
506
|
+
states and loading lines, and its names for a sprint, a board or an epic beside
|
|
507
|
+
the real ones ("Campaign (Epic)"). Buttons, links, figures, ids, commands and errors
|
|
508
|
+
read the same in every theme.
|
|
509
|
+
- **Themed agent voice:** the agent answers in the theme's register, a terse
|
|
510
|
+
dockworker in Crate, a patient farmhand in Harvest, a ship's log in Starship, a
|
|
511
|
+
house's steward in Realm. It changes phrasing only.
|
|
512
|
+
|
|
513
|
+
Plain has neither, so both are off while it's chosen. The choice is kept in this
|
|
514
|
+
browser. Toil UI doesn't install themes from anywhere else: to ask for one, send a
|
|
515
|
+
feature request from **Feedback** or with `toil feedback feature`. A `themes/` folder
|
|
516
|
+
left in the data folder by an earlier alpha is not read, and Toil UI says so when it
|
|
517
|
+
starts. [Themes](https://imagile-dev.github.io/toil/docs/themes/) has the whole
|
|
518
|
+
story, the composed prompt included.
|
|
519
|
+
|
|
520
|
+
## The lock on the door
|
|
521
|
+
|
|
522
|
+
Any program on the machine, or a web page using DNS rebinding, can reach a local
|
|
523
|
+
port, so the server lets in only the browser holding this launch's token:
|
|
524
|
+
|
|
525
|
+
- **The token.** A random token per start, in the URL it prints. The page trades it
|
|
526
|
+
for a session id, which it keeps in memory and sends as a header on every API
|
|
527
|
+
call. Nothing is kept in a cookie: a browser would send one to any other server
|
|
528
|
+
on `127.0.0.1`, whatever its port.
|
|
529
|
+
- **The Host header.** Only the exact `127.0.0.1:<port>` it printed is answered.
|
|
530
|
+
- **No CORS.** No `Access-Control-*` header is ever sent. Every POST also needs the
|
|
531
|
+
page's own `Origin`, a JSON body, and the session's CSRF token.
|
|
532
|
+
- **No network but toil's.** It talks to the hosts in your toil connections, and
|
|
533
|
+
nothing else, apart from a feedback report you send, which toil sends to Imagile. The agent CLI you choose talks to its own model endpoint.
|
|
534
|
+
|
|
535
|
+
## Run against a real repository
|
|
536
|
+
|
|
537
|
+
From a clone, one command starts Toil UI on a real GitHub repository, in a home
|
|
538
|
+
folder of its own (`.scratch/home` in the clone, ignored by git), so your own
|
|
539
|
+
`~/.toil` and `~/.toil-ui` are never read or written:
|
|
540
|
+
|
|
541
|
+
```bash
|
|
542
|
+
npm ci --ignore-scripts
|
|
543
|
+
npm run build -w ui
|
|
544
|
+
node ui/scripts/dev-real.mjs
|
|
545
|
+
```
|
|
546
|
+
|
|
547
|
+
It works the same in PowerShell, Git Bash and a macOS or Linux shell. It needs the
|
|
548
|
+
GitHub CLI signed in (`gh auth login`), or `TOIL_GITHUB_TOKEN` set in the shell.
|
|
549
|
+
|
|
550
|
+
- **toil's config**, written once: one connection, `github`, to
|
|
551
|
+
`https://api.github.com`, with writes off and no token in the file.
|
|
552
|
+
- **The token** comes from `gh auth token` each time it starts and goes only into
|
|
553
|
+
Toil UI's environment, as `TOIL_GITHUB_TOKEN`. It's never written to a file or
|
|
554
|
+
printed. `GITHUB_TOKEN` and other `TOIL_*` variables in your shell are left out.
|
|
555
|
+
- **The dossiers**, made with `toil dossiers init` and `link` and checked with
|
|
556
|
+
`toil dossiers check`: one for `--repo`, and `toil-self` for the public
|
|
557
|
+
`imagile-dev/toil` unless `--no-self`. `--repo` defaults to
|
|
558
|
+
`imagile-dev/toil-sandbox` (as `sandbox`), which is private to Imagile's
|
|
559
|
+
maintainers; anyone else passes their own repository, or seeds a sandbox of their
|
|
560
|
+
own (below).
|
|
561
|
+
- **toil from this checkout.** Each start builds toil from the clone into
|
|
562
|
+
`.scratch/toil` (`npm run build` with `TOIL_BUILD_DIR`, a few seconds), and both the
|
|
563
|
+
dossier setup and Toil UI run on that build, not on the published toil
|
|
564
|
+
`ui/package.json` pins. Toil UI is started with `node --import
|
|
565
|
+
ui/scripts/local-toil-hook.mjs`, which resolves `@imagile-dev/toil/api` to
|
|
566
|
+
`.scratch/toil/api.js` and says so on stderr. So a command `ui/` calls before its
|
|
567
|
+
release works here. The committed `dist/` and `node_modules` are left alone, and a
|
|
568
|
+
plain `node ui/dist/server/toil-ui.js` still runs on the pinned toil.
|
|
569
|
+
- **Then** it starts `ui/dist/server/toil-ui.js` on loopback and prints its URL.
|
|
570
|
+
Press **Sync now**, then open a dossier. `--port <n>` fixes the port, and
|
|
571
|
+
`--home <dir>` uses another folder.
|
|
572
|
+
- **Ask with Codex.** Install the SDK in the clone without saving it
|
|
573
|
+
(`npm install --no-save --ignore-scripts @openai/codex-sdk@0.160.0`), then choose
|
|
574
|
+
Codex under **Settings, Agent**. The script points `CODEX_HOME` at your real
|
|
575
|
+
`~/.codex`, which is where Toil UI finds the `auth.json` it links into its own
|
|
576
|
+
Codex home.
|
|
577
|
+
|
|
578
|
+
## Verify before you open a PR: `npm run verify:ui`
|
|
579
|
+
|
|
580
|
+
One command checks Toil UI the way a reviewer would, and writes what it found to
|
|
581
|
+
`ui/.verify/report.md` with screenshots beside it (git ignores the folder). Run it
|
|
582
|
+
from the root or from `ui/`, and paste the report's table into the PR.
|
|
583
|
+
|
|
584
|
+
```bash
|
|
585
|
+
npm run verify:ui # build, sample data, real data
|
|
586
|
+
npm run verify:ui -- --ask # and one Codex question
|
|
587
|
+
npm run verify:ui -- --no-build --starter standup
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
- **It builds Toil UI and toil**, unless `--no-build`: toil from this checkout into
|
|
591
|
+
`.scratch/toil`, which Toil UI runs on, as `dev-real.mjs` does (above). The report's
|
|
592
|
+
header and its **Toil** row name that toil: its version, the commit it was built
|
|
593
|
+
at, and whether `src/` had uncommitted changes. The run fails if Toil UI didn't
|
|
594
|
+
resolve `@imagile-dev/toil/api` to it. It also confirms that the toil `npm ci`
|
|
595
|
+
installs is the one `ui/package.json` pins (`npm run check:lockfile -w ui`), which
|
|
596
|
+
is what the published package runs on.
|
|
597
|
+
- **Sample data:** `toil-ui --sample` in a throwaway home, every view through the
|
|
598
|
+
layout check (`scripts/layout-check.mjs`) in every theme and scheme at 375, 768 and
|
|
599
|
+
1440px. It needs only a browser, so it runs anywhere, CI included.
|
|
600
|
+
- **Real data:** the home `dev-real.mjs` sets up, made fresh at
|
|
601
|
+
`.scratch/verify/home`, on `imagile-dev/toil-sandbox` with the token from `gh auth
|
|
602
|
+
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.
|
|
604
|
+
Without a GitHub sign-in it skips this part and says so; nothing else depends on it.
|
|
605
|
+
- **`--ask`** asks Codex one starter question (`hygiene` unless `--starter <id>`) and
|
|
606
|
+
checks that an answer arrived, that the server verified every `[[id]]` it cites,
|
|
607
|
+
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`. It
|
|
609
|
+
needs the Codex CLI signed in and the SDK installed in the clone (above).
|
|
610
|
+
- **What fails it:** any layout problem in any theme, and any axe violation at WCAG
|
|
611
|
+
2.2 AA in Plain and Crate. Axe findings in the other themes are listed in the report
|
|
612
|
+
and never fail it. Screenshots are of Plain and Crate.
|
|
613
|
+
- **It stops** every server and browser it started, and exits 1 on any problem.
|
|
614
|
+
|
|
615
|
+
`--source ado` runs the real-data part against an Azure DevOps Services board
|
|
616
|
+
instead (the `ado-board` dossier, as `dev-real.mjs --source ado` makes it below),
|
|
617
|
+
with `TOIL_ADO_CLOUD_BASE_URL`, `TOIL_ADO_CLOUD_PAT` and `--project <name>` (else
|
|
618
|
+
`TOIL_ADO_CLOUD_PROJECT`); without them it skips that part and says why. Each source is
|
|
619
|
+
one entry in `SOURCES` in `scripts/verify.mjs`. Set `CHROME_PATH` if the browser it finds doesn't draw headless; Playwright's
|
|
620
|
+
Chromium works where an installed Chrome doesn't.
|
|
621
|
+
|
|
622
|
+
### The sandbox repository
|
|
623
|
+
|
|
624
|
+
`imagile-dev/toil-sandbox` is a private repository of made-up work for trying
|
|
625
|
+
this, and the seed below makes the same in a repository of yours: labels for type, priority, points and blocked; three milestones as sprints
|
|
626
|
+
(41 closed, 42 current, 43 next); 25 issues, open and closed, some assigned, some
|
|
627
|
+
blocked by others, a few unestimated, one with a very long title; a workflow that
|
|
628
|
+
only echoes, with one branch that fails on purpose; four pull requests that
|
|
629
|
+
close issues (merged, open, draft, and one with a failing build); and comment
|
|
630
|
+
reviews on two of them. GitHub won't let a pull request's author approve it or be
|
|
631
|
+
asked to review it, so review requests are seeded only when the repository has a
|
|
632
|
+
second collaborator to ask; with one, the seed says it skipped them.
|
|
633
|
+
|
|
634
|
+
```bash
|
|
635
|
+
gh repo create <owner>/toil-sandbox --private --add-readme
|
|
636
|
+
node ui/scripts/seed-sandbox.mjs --owner <owner> --repo toil-sandbox
|
|
637
|
+
```
|
|
638
|
+
|
|
639
|
+
The seed writes through the GitHub CLI's own login, never through toil, and is
|
|
640
|
+
safe to run again: what exists is found by name or title and left alone. To start
|
|
641
|
+
over, delete the repository (`gh repo delete <owner>/toil-sandbox`, which needs the
|
|
642
|
+
`delete_repo` scope), create it again and re-run the seed. It adds no Projects
|
|
643
|
+
board, which needs the `project` scope on the token, and no deployments, which
|
|
644
|
+
toil's `github` area doesn't read.
|
|
645
|
+
|
|
646
|
+
### An Azure DevOps Services board
|
|
647
|
+
|
|
648
|
+
`--source ado` runs the same way against an Azure DevOps Services project, through
|
|
649
|
+
toil's `ado-cloud` area, with a dossier named `ado-board`:
|
|
650
|
+
|
|
651
|
+
```bash
|
|
652
|
+
node ui/scripts/dev-real.mjs --source ado --project "<project>"
|
|
653
|
+
```
|
|
654
|
+
|
|
655
|
+
It needs `TOIL_ADO_CLOUD_BASE_URL` (`https://dev.azure.com/<organization>`) and
|
|
656
|
+
`TOIL_ADO_CLOUD_PAT` (an organization-scoped token with Work Items, Read) in the
|
|
657
|
+
shell. They go into Toil UI's environment only: toil makes its `ado-cloud`
|
|
658
|
+
connection from them, with writes off, and nothing about the organization is
|
|
659
|
+
written to the config file. `--project`, or `TOIL_ADO_CLOUD_PROJECT`, names the
|
|
660
|
+
project; the dossier in the scratch home holds it. The dossier names no repository,
|
|
661
|
+
so no pull requests are read; add `repo` to its `ado-cloud` section for them.
|
|
662
|
+
|
|
663
|
+
To fill a board with made-up work, `ui/scripts/ado-seed/` seeds one from Open Work
|
|
664
|
+
Items. `items.owi.json` holds 45 of them across the three sample products
|
|
665
|
+
(`card-payments`, `settlement`, `checkout-web`): Scrum epics, features, backlog
|
|
666
|
+
items, tasks and bugs, in a mix of states, in Sprints 1 to 3 and the backlog, with
|
|
667
|
+
efforts (some missing), acceptance criteria (some missing), parents, dependencies,
|
|
668
|
+
related pairs, long titles and two stale items. It's written by a seeded generator,
|
|
669
|
+
so the same seed always gives the same file:
|
|
670
|
+
|
|
671
|
+
```bash
|
|
672
|
+
node ui/scripts/ado-seed/generate.mjs # writes items.owi.json, checked against docs/owi/schema.json
|
|
673
|
+
node ui/scripts/ado-seed/apply.mjs --project "<project>" --dry-run # what it would create; sends no write
|
|
674
|
+
node ui/scripts/ado-seed/apply.mjs --project "<project>" # creates what's missing
|
|
675
|
+
node ui/scripts/ado-seed/cleanup.mjs --project "<project>" # lists the seeded items, deletes nothing
|
|
676
|
+
node ui/scripts/ado-seed/cleanup.mjs --project "<project>" --confirm <code> # sends exactly that list to the recycle bin
|
|
677
|
+
```
|
|
678
|
+
|
|
679
|
+
The scripts read the same two variables, create and change work items only, in
|
|
680
|
+
sprints that already exist (a missing sprint stops the run; none is ever created),
|
|
681
|
+
and touch only items tagged `toil-seed` with one `seed:<key>` tag. Every item gets
|
|
682
|
+
both. Running `apply.mjs` again creates only what's missing. Each item's history is
|
|
683
|
+
backdated to its timeline when the token's identity may bypass rules, and seeded with
|
|
684
|
+
ordinary transitions dated today when not, which the run says. `cleanup.mjs` deletes
|
|
685
|
+
only after a dry run has listed the items: the code it prints is made from their ids,
|
|
686
|
+
and `--confirm` refuses a code for any other list. Deleted items can be restored from
|
|
687
|
+
the project's recycle bin. To start over, clean up and apply again.
|
|
688
|
+
|
|
689
|
+
To check what toil reads back, map the board's output and compare it with the file:
|
|
690
|
+
`compare.mjs` matches each item to its record by its `seed:` tag and prints every
|
|
691
|
+
difference, leaving out what the server assigns.
|
|
692
|
+
|
|
693
|
+
```bash
|
|
694
|
+
toil ado-cloud work-item iterations --project "<project>" > board.jsonl
|
|
695
|
+
toil ado-cloud work-item get-many <ids…> >> board.jsonl
|
|
696
|
+
toil ado-cloud work-item history <id> >> board.jsonl # once for each id
|
|
697
|
+
toil util owi map board.jsonl > mapped.json
|
|
698
|
+
node ui/scripts/ado-seed/compare.mjs mapped.json --project "<project>" --backdated
|
|
699
|
+
```
|
|
700
|
+
|
|
701
|
+
## Settings
|
|
702
|
+
|
|
703
|
+
| Setting | Flag | Env var | Default |
|
|
704
|
+
|---|---|---|---|
|
|
705
|
+
| Bind address | `--host` | `TOIL_UI_HOST` | `127.0.0.1` (`::1` is the other choice) |
|
|
706
|
+
| Port | `--port` | `TOIL_UI_PORT` | `0`: the OS picks a free one |
|
|
707
|
+
| Base path | `--base-path` | `TOIL_UI_BASE_PATH` | `/` |
|
|
708
|
+
| Data folder | `--data-dir` | `TOIL_UI_DATA_DIR` | `~/.toil-ui` |
|
|
709
|
+
| Retention | `--retention-days` | `TOIL_UI_RETENTION_DAYS` | `30` (1 to 3650) |
|
|
710
|
+
|
|
711
|
+
A flag beats its env var. Any bind address other than loopback is refused in this
|
|
712
|
+
release. The data folder is Toil UI's own, apart from toil's `~/.toil/`, and holds
|
|
713
|
+
the cache, `agent.json` and `usage.json`. A `~` at the start of `TOIL_UI_DATA_DIR` means your home folder, on
|
|
714
|
+
Windows too.
|
|
715
|
+
|
|
716
|
+
## Not in this alpha
|
|
717
|
+
|
|
718
|
+
- **Serving other machines.** It is local only.
|
|
719
|
+
- **Implement mode on Claude or Copilot**, and **answering an agent's questions in the assignment** itself: answer on the item and assign it again.
|
|
720
|
+
|
|
721
|
+
## The package
|
|
722
|
+
|
|
723
|
+
`@imagile-dev/toil-ui` ships the server (`dist/server/toil-ui.js`) and the built app
|
|
724
|
+
(`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
|
|
726
|
+
front end's framework is built in rather than installed. The agent SDKs are
|
|
727
|
+
optional peer dependencies: none is installed with it.
|
|
728
|
+
|
|
729
|
+
Apache-2.0. See `NOTICE` for what the app bundles.
|