@imagile-dev/toil-ui 0.1.0-beta.3 → 0.1.0-beta.5
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/README.md +451 -266
- package/dist/app/assets/400-3Dshv1o0.css +1 -0
- package/dist/app/assets/400-BlzPh-5d.css +1 -0
- package/dist/app/assets/400-CPrO1MiG.css +1 -0
- package/dist/app/assets/400-CbHxiUkt.css +1 -0
- package/dist/app/assets/400-D153RTnK.css +1 -0
- package/dist/app/assets/600-B0bH0tPL.css +1 -0
- package/dist/app/assets/600-BC2hxnnO.css +1 -0
- package/dist/app/assets/600-BR9-_eiK.css +1 -0
- package/dist/app/assets/600-BsKsKkx5.css +1 -0
- package/dist/app/assets/600-CjaIhKfW.css +1 -0
- package/dist/app/assets/600-Czj0FyAy.css +1 -0
- package/dist/app/assets/600-D452fNA9.css +1 -0
- package/dist/app/assets/600-DBby7xF7.css +1 -0
- package/dist/app/assets/700-DlBBsyxq.css +1 -0
- package/dist/app/assets/700-Dr8Emwbw.css +1 -0
- package/dist/app/assets/Graph-d-CslDZy.js +7 -0
- package/dist/app/assets/{PowershellMan-BMVCrjjz.js → PowershellMan-C7mR66E-.js} +1 -1
- package/dist/app/assets/index-fUsawfsS.css +1 -0
- package/dist/app/assets/index-qD5xYplp.js +507 -0
- package/dist/app/assets/latin-400-BVAlDo0s.css +1 -0
- package/dist/app/assets/latin-400-CjeLe9eM.css +1 -0
- package/dist/app/assets/latin-400-_vizA_-6.css +1 -0
- package/dist/app/assets/latin-600-BcF9gTYO.css +1 -0
- package/dist/app/assets/latin-600-Cv5fXBpv.css +1 -0
- package/dist/app/assets/latin-600-yBvtfTSt.css +1 -0
- package/dist/app/assets/latin-800-DN-4L033.css +1 -0
- package/dist/app/assets/theme--CDBXtCV.css +1 -0
- package/dist/app/assets/theme-Bd9rCh2b.css +1 -0
- package/dist/app/assets/theme-C7Mxc3ZD.css +1 -0
- package/dist/app/assets/{theme-mWrwQOT7.css → theme-elgfmZWW.css} +1 -1
- package/dist/app/assets/theme-hbyLw_lf.css +1 -0
- package/dist/app/index.html +2 -2
- package/dist/server/toil-ui.js +3524 -1765
- package/package.json +2 -2
- package/dist/app/assets/Graph-CFuW4gKS.js +0 -7
- package/dist/app/assets/index-BcEh-0qQ.css +0 -1
- package/dist/app/assets/index-D9EQ864e.js +0 -74
- package/dist/app/assets/theme-BJbhJDgp.css +0 -1
- package/dist/app/assets/theme-CC5mVuDH.css +0 -1
- package/dist/app/assets/theme-gYmLCU0M.css +0 -1
- package/dist/app/assets/theme-paULUSRX.css +0 -1
package/README.md
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
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
|
|
4
|
+
[toil](https://www.npmjs.com/package/@imagile-dev/toil): one dashboard per Toil project,
|
|
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
8
|
**Status: beta, local only.** It runs on your own machine, binds loopback, and
|
|
9
|
-
reads through toil with your own connections and
|
|
10
|
-
settings pages, and a
|
|
11
|
-
places it changes anything of toil's, and only toil's own connections and
|
|
9
|
+
reads through toil with your own connections and Toil projects, read-only. Its
|
|
10
|
+
settings pages, and a Toil project'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 Toil projects. 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
14
|
never installs it. toil's beta commitment to stable commands, flags and output doesn't
|
|
@@ -36,57 +36,93 @@ It prints one URL and keeps running until you press Ctrl+C:
|
|
|
36
36
|
|
|
37
37
|
```text
|
|
38
38
|
Toil UI <version> (beta, local only), on toil <version>
|
|
39
|
-
Syncing through toil, read-only, with your own connections and
|
|
39
|
+
Syncing through toil, read-only, with your own connections and Toil projects. Only its Settings pages, and a Toil project's name and description edited in place, change anything: toil's own connections and toilProjects, 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.
|
|
40
40
|
The cache is /home/you/.toil-ui/cache/toil-ui.db, kept 30 days after each sync; toil-ui wipe deletes it.
|
|
41
41
|
|
|
42
|
-
Open this URL in your browser. It
|
|
43
|
-
http://127.0.0.1:53117
|
|
42
|
+
Open this URL in your browser. It holds no secret: your browser is let in by a cookie signed with the key in the data folder, and anything running as you on this machine can reach Toil UI too:
|
|
43
|
+
http://127.0.0.1:53117/
|
|
44
44
|
```
|
|
45
45
|
|
|
46
|
-
Open that URL.
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
restores, can carry the session while the same `toil-ui` is still running. Toil UI opens no browser itself.
|
|
46
|
+
Open that URL. There is nothing to paste and nothing stored by the page: the first
|
|
47
|
+
time your browser opens the page, the server sets a cookie, and the browser sends it
|
|
48
|
+
back with every call. Reload, bookmark, open a new tab or restart `toil-ui`, and it
|
|
49
|
+
still works. Toil UI opens no browser itself.
|
|
51
50
|
|
|
52
|
-
Why
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
cookie to every port on `127.0.0.1`, so any other local server would receive the
|
|
56
|
-
session. `sessionStorage` belongs to this exact origin (port included) and is never
|
|
57
|
-
sent anywhere. `localStorage` would outlive the tab, so it isn't used.
|
|
51
|
+
Why this and not a token in the URL: the maintainer chose a local-only tool with no
|
|
52
|
+
step for the person and nothing in `sessionStorage` (#561). What does the work
|
|
53
|
+
instead is in **The checks on the door**, below, with what they don't protect against.
|
|
58
54
|
|
|
59
|
-
`toil-ui --sample` serves the sample
|
|
55
|
+
`toil-ui --sample` serves the sample Toil projects and the scripted agent that
|
|
60
56
|
[the site's Toil UI page](https://imagile-dev.github.io/toil/ui/) runs on, with
|
|
61
57
|
nothing connected to a tracker.
|
|
62
58
|
|
|
63
59
|
## First run
|
|
64
60
|
|
|
65
|
-
Until you have a
|
|
61
|
+
Until you have a Toil project and it has synced once, the Toil projects view shows a short
|
|
66
62
|
checklist in place of the empty page:
|
|
67
63
|
|
|
68
64
|
1. **Connect a tracker** opens Settings, Connections at the add form. If an agent following the toil skill's `setup.md` already created the connection, you only enter its secret here, on its row.
|
|
69
|
-
2. **Create a
|
|
65
|
+
2. **Create a Toil project** opens the New Toil project wizard (`#/new-project`, below).
|
|
70
66
|
3. **Sync** starts the first sync, as the Sync panel's Sync now does.
|
|
71
67
|
|
|
72
68
|
Each step ticks itself off from toil's own state: `toil connections list` for a
|
|
73
69
|
connection to Jira, Azure DevOps or GitHub (one made by env vars counts), `toil
|
|
74
|
-
|
|
75
|
-
**Try the sample data** shows `npx @imagile-dev/toil-ui --sample` with a Copy
|
|
76
|
-
button, to restart Toil UI on the sample dossiers. The checklist goes once the first
|
|
70
|
+
projects list` for a Toil project, and the Sync panel for the sync. Beside the steps, **Set it up step by step** opens the setup wizard (`#/setup`, below). The checklist goes once the first
|
|
77
71
|
sync finishes. Each step's (i) explains it and links to these docs.
|
|
78
72
|
|
|
73
|
+
## The setup wizard
|
|
74
|
+
|
|
75
|
+
For someone new to AI, toil and Toil UI, `#/setup` walks through setup one question a screen, with Back and one Next button, which stays disabled until the page is done (an optional page has a "Not now" choice), and a "Step 3 of 7" line. It opens from **Set it up step by step** on the first run, from **Set up toil, step by step** in the command palette, from the link under Settings' heading, and by its own address.
|
|
76
|
+
|
|
77
|
+
1. **Welcome** says what toil and Toil UI are, and that nothing in your tools changes without you.
|
|
78
|
+
2. **An AI agent (optional)** comes first, so it can explain the rest. It is the AI agent page's own Install dialog and Save, explained for someone who has never used one: what it is, that it only reads and suggests, that it uses the subscription you already have so Toil UI stores no key, and that it never sees your login. Choose "Not now" and every later step is what it always was, with one small line, "Set up an AI agent to get explanations here", that brings you back here and then returns you to where you were.
|
|
79
|
+
3. **Which tools do you use?** lists the areas toil can connect to, from the server's own registry: GitHub, Jira, Azure DevOps, Bitbucket, Confluence and SonarQube first, the rest under **More tools**. A tool you already have a connection to says so.
|
|
80
|
+
4. **Link your tools** takes each ticked tool in turn with the same form as Settings, Connections: the settings in text boxes, and the login in a masked box that goes to toil's own `connections login` path and the OS credential store, as it does in Settings. The wizard never keeps it, and no AI agent, guide or suggestion ever sees it. The new connection starts with changes off (writes off in toil's words), and the screen says so. **Test the link** runs `toil connections test`.
|
|
81
|
+
5. **Your Toil project** creates one (`projects init`, an optional repository with `projects add-repo`, then `projects link` for each tool set up) or links the tools to one you already have.
|
|
82
|
+
6. **Let toil learn your Jira fields (optional)** is Settings' Find the fields.
|
|
83
|
+
7. **All set** says what was set up and offers **Sync now**.
|
|
84
|
+
|
|
85
|
+
### The guide
|
|
86
|
+
|
|
87
|
+
Once an AI agent is ready (installed, its program found, and chosen here or in Settings), the Tools, Link, Toil project and Jira fields steps show a guide beside the step: two columns from 1000px wide, and below the step behind **Ask the guide**, closed, on a phone or tablet. Each step offers starter questions ("Which scopes does my token need?", "Where do I find my Jira site name?", "Cloud or Data Center?", "What is a Toil project?", "What does Sprint mean here?") and a question box labelled **Ask a question (never paste a token here)**. The chat is kept as you move between steps.
|
|
88
|
+
|
|
89
|
+
It is a guide, not an operator. The server gives it its own prompt (`ui/server/agents/guide.ts`) and three read tools: `docs_list` and `docs_read`, which read toil's own skill pages for the tools you chose (the pages the MCP server serves as resources, embedded in the server), and `connection_scopes`, which says what a tool's token needs. Once a Toil project exists it also gets toil's live reads for it; it needs no sync and no Toil project before then. What it is told is built on the server from three places and no others: the wizard's whitelisted state (the step, the tools ticked, the one being linked, a Cloud or Data Center choice and the address the form composed, with no login or query in it, and the Toil project's name), `connections list` run read-only (name, tool, address, writes, and the same "token: saved, from an environment variable or missing" badge Settings shows, never a value), and the docs. A change it suggests comes back as a card with the command it would type and **Run this**, which runs it through the same config call the wizard's own buttons use, after the page checks it again; only `connections add` (with plain `--set` settings, no login), `projects init`, `projects add-repo` and `projects link` are offered a button. Its answers are not in the worklog, which is about work.
|
|
90
|
+
|
|
91
|
+
**No secret reaches it.** The connection form reports only what it would send as settings (a form's `submission`, which holds no secret by construction), and the wizard whitelists `deployment` and the address from them. A message is checked before it is sent, three times over, by the same function (`looksLikeSecret`, `ui/src/guide.ts`: toil's own `checkSecret()` paste check on the message, each word and each pair, the usual credential prefixes such as `ghp_`, `github_pat_`, `ATATT`, `glpat-`, `xox` and `AKIA`, a `Bearer` header, a JWT or private key, an address with a login in it, `password:` and `token=` with a value, and one long key-shaped word): in the panel, in the page's client, and at the server's route, which refuses it before it reads another field, and again in the host before the connection list, the agent, the usage ledger or the worklog is touched. A refused message is cleared, never kept, logged, audited or echoed, and the notice says: "That looks like a token. Type it in the masked box in the step instead; the guide never needs it." Nothing is stored in the browser: closing the tab ends the chat.
|
|
92
|
+
|
|
93
|
+
The wizard keeps its progress in the page only; it adds no config key. Connections it saved stay saved if you close the tab. Every change is one of the commands in the allowlist Settings uses, so each is in toil's audit log as `toil-ui`.
|
|
94
|
+
|
|
95
|
+
## The New Toil project wizard
|
|
96
|
+
|
|
97
|
+
`#/new-project` is a separate, short wizard for the one job of making a Toil project, so nobody who already has their tools set up lands on "Step 5 of 7" of the first run. It looks and behaves like the setup wizard (a "Step 2 of 4" line, Back, one primary button that stays disabled with a plain reason until the page is done, and a **Not now** on each optional page) and has no AI agent guide. The **New Toil project** buttons (the Toil projects page, Settings, the first-run checklist), the command palette's **Create a Toil project**, and the old addresses `#/setup/project` and `#/settings/projects/+new` (which are rewritten to it) all open it.
|
|
98
|
+
|
|
99
|
+
1. **Name it**: a name (lowercase letters, digits and single hyphens, not already taken) and an optional description.
|
|
100
|
+
2. **Where does it live? (optional)**: folders or repository addresses, or **Not now**.
|
|
101
|
+
3. **Which tools does it use?**: your existing tool links, each tool's main one ticked, one per tool, or **Not now**.
|
|
102
|
+
4. **Create it**: a summary and one **Create `<name>`** button, which runs `projects init`, `projects add-repo` for each folder, then `projects link` for each tool, never with `--shared`, and says what it is doing as it goes. A folder that fails does not undo the Toil project: it is listed with a **Retry**. Then **Open `<name>`**, and **Name your Jira fields** when Jira was linked. With changes turned off the button stays disabled and says so. The wizard keeps its place in the page only, as the setup wizard does.
|
|
103
|
+
|
|
79
104
|
## What it reads
|
|
80
105
|
|
|
81
|
-
Each dashboard reads its
|
|
82
|
-
Jira project, the Azure DevOps project and pipelines, the GitHub
|
|
83
|
-
project board, and the OpenShift namespace of each environment. A GitHub
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
106
|
+
Each dashboard reads its Toil project the way `toil projects show` describes it: the
|
|
107
|
+
Jira project, the Azure DevOps project and pipelines, the GitHub repositories and
|
|
108
|
+
project board, and the OpenShift namespace of each environment. A Toil project's GitHub
|
|
109
|
+
repositories are the `github` section's `owner` and `repo` (one value, or one per repo
|
|
110
|
+
name), plus its `repos` remotes on github.com or on the host of a repository the section names, and each is read on its own
|
|
111
|
+
with `owner` and `repo` passed explicitly (`src/github-repos.ts`); a repository that
|
|
112
|
+
couldn't be read gets one muted line where its gap shows: "pull requests not read" on the Pull requests view (linking to the failed call), "work items not read" on the Board tab. The same goes for the other
|
|
113
|
+
areas' per-repo values: a Jira `project`, a Bitbucket `project`, `workspace` or `repo`,
|
|
114
|
+
and an Azure DevOps `collection`, `project` or `repo` given as an object of repo name to
|
|
115
|
+
value are each read once per target (one Jira search per project, work items per Azure
|
|
116
|
+
DevOps project, pull requests per repo) with those inputs passed explicitly
|
|
117
|
+
(`src/targets.ts`; a pipeline is tried in each Azure DevOps project in turn, and a repo name the section leaves half-named is shown as not read), because Toil UI has no repo folder for toil to pick one from; a section
|
|
118
|
+
with plain values sends the calls it always did. Only GitHub's remotes are read for more
|
|
119
|
+
targets. A GitHub section with no `projects`
|
|
120
|
+
reads each repository's own issues, open and closed, as its work items, with the
|
|
121
|
+
history of every open one and the 50 most recently closed in each. Pull
|
|
122
|
+
requests are read from every code host the Toil project names (GitHub, Bitbucket Data
|
|
87
123
|
Center and Cloud, Azure DevOps Server and Services) with `pr list`, then `pr get
|
|
88
124
|
--include reviews,checks,commits,files` for every open one and the 20 newest closed or
|
|
89
|
-
merged ones, and mapped to OWI 0.2 changes; a GitHub repository's CODEOWNERS is read
|
|
125
|
+
merged ones (of each GitHub repository), and mapped to OWI 0.2 changes; a GitHub repository's CODEOWNERS is read
|
|
90
126
|
with `github repo file` when an open pull request has no reviewer. Every call runs
|
|
91
127
|
in-process through `@imagile-dev/toil/api`, read-only, and toil's audit log
|
|
92
128
|
records it with `via: "api"` and `caller: "toil-ui"`. A call that fails shows on
|
|
@@ -97,73 +133,115 @@ the read window: the retention period, but at least 6 weeks (42 days), so the
|
|
|
97
133
|
longest view stays whole. A closed item older than that isn't read, and so isn't
|
|
98
134
|
in any view.
|
|
99
135
|
|
|
100
|
-
##
|
|
136
|
+
## Plain words
|
|
137
|
+
|
|
138
|
+
Screens always read in everyday words: a pull request is a **code review**, an agent an **AI agent**, with toil's own term in the hover. There is no switch. Anything a person reads to act (a menu item, tab, button, label, heading, an error and its fix) is plain English and identical in every theme; a theme speaks only in ledes and explanations, loading text, empty-state sentences and its moments (**Words** in `docs/themes.md`). Facts, numbers, commands and errors read the same everywhere. Themed wording is on by default and themed agent voice is off until chosen.
|
|
139
|
+
|
|
140
|
+
The tabs read **Summary**, **Board**, **What blocks what** (Dependencies), **Code reviews**, **People**, **What happened** (Worklog) and **Past briefings** (Analyses); Analyze is **Get a briefing**. A panel's source reads "From Jira and GitHub", with each tool and how many reads it took one step in. **Settings → Appearance** has a **Font** control: the theme's own type first, then pairings made only of fonts already bundled (`docs/themes.md`, **Fonts**). Quoted titles, the tracker's words and a briefing's own sentences are never reworded.
|
|
141
|
+
|
|
142
|
+
## Plain copy: no terminal in the words
|
|
143
|
+
|
|
144
|
+
- **Toil UI never shows a terminal command, an environment variable name or a file path as copy** (the maintainer's decision, 2026-11-09). Its readers are product owners and managers, not developers. So no "Runs `toil …`" line, no `TOIL_*` name, no config-file location, no `--flag`, no "Saves: area github, baseUrl …" summary; a login says **Saved on this computer** or **Set outside Toil UI, so it can't be changed here**. Errors and their fixes stay honest (principle 4) but are worded in plain English, and an error toil itself worded is kept as toil said it. Where a thing can only be done in a terminal, the screen says Toil UI can't do it yet, rather than quoting the command.
|
|
145
|
+
- **The one exception is an approval card:** a proposed change shown before a person presses Run ("Proposed change, not applied", the Board's proposals, the AI agent's setup suggestions, an install awaiting its press) shows what will run, because that is what the person is approving.
|
|
101
146
|
|
|
102
|
-
|
|
147
|
+
## The Toil projects view
|
|
148
|
+
|
|
149
|
+
Toil UI opens on its Toil projects, one card each, read from the same data the dashboards
|
|
103
150
|
read, so it asks no tracker anything: in the local app that is the cache a sync
|
|
104
|
-
filled, plus `
|
|
151
|
+
filled, plus `projects list` and `projects show` for the Toil projects themselves.
|
|
105
152
|
|
|
106
153
|
- **What each card shows:** the current sprint with its working days left, points
|
|
107
154
|
done and a small burn-up; how many items are in progress and blocked, and how many
|
|
108
155
|
pull requests wait on a review; the people with work in it, as avatars; its sources
|
|
109
156
|
as badges; when it was last synced; and how many work items and pull requests
|
|
110
157
|
changed since this browser last opened its dashboard.
|
|
111
|
-
- **
|
|
158
|
+
- **Unknown is not zero (principle 12):** a Toil project that has never synced has
|
|
159
|
+
read nothing, so its counts show a dash (`–`, spoken as "not read yet") instead of
|
|
160
|
+
`0`, and the sprint and "since you last looked" lines stay off until a sync has
|
|
161
|
+
read something. Once it has synced, a `0` is a real count.
|
|
162
|
+
- **Card order:** the Toil project opened most recently in this browser, or, before
|
|
112
163
|
any was opened, the one with the most in motion (in progress, blocked and waiting on
|
|
113
|
-
review together),
|
|
164
|
+
review together), comes first unless the person set an order with a card's **Move earlier** /
|
|
165
|
+
**Move later** (kept in this browser). Every card is the same size. On a wide screen the grid goes
|
|
114
166
|
wider than the dashboards and fits more cards across; at 375px it is one column.
|
|
115
167
|
- **What this browser remembers:** when each dashboard was last opened, in
|
|
116
168
|
`localStorage`, never sent anywhere. Without it (a private window) the cards just
|
|
117
169
|
say nothing about "since".
|
|
118
|
-
- **A
|
|
119
|
-
sources as badges, and the sprint's day (The
|
|
170
|
+
- **A Toil project's top row** uses the same parts: the description beside the name, the
|
|
171
|
+
sources as badges, and the sprint's day (The Toil project page, below).
|
|
172
|
+
|
|
173
|
+
### Archiving a Toil project (#561)
|
|
120
174
|
|
|
121
|
-
|
|
175
|
+
A card's quiet "more" menu holds Archive, and so does the command palette (type
|
|
176
|
+
"archive") and each of your own Toil projects under Settings, Toil projects. It runs
|
|
177
|
+
`toil projects archive <toilProject>` on the settings pages' path, so the file is
|
|
178
|
+
changed by toil and nothing is deleted. One line under the header says what happened
|
|
179
|
+
and has an Undo. The archived ones leave the list, the switcher and the sync figures,
|
|
180
|
+
and wait under a closed "Archived (n)" at the bottom of the page, each with Unarchive
|
|
181
|
+
(`toil projects unarchive`), which the palette offers too. The list reads them with
|
|
182
|
+
`toil projects list --archived`; if that fails the disclosure is not drawn, because
|
|
183
|
+
unknown is not none. The preview changes nothing, so it shows the sample's archived
|
|
184
|
+
project and no controls.
|
|
185
|
+
|
|
186
|
+
### Renaming and describing a Toil project
|
|
122
187
|
|
|
123
188
|
The name and the description have a pencil beside them, on the card and in the
|
|
124
|
-
|
|
125
|
-
`toil
|
|
189
|
+
Toil project's top row. It opens an inline field: Enter saves through
|
|
190
|
+
`toil projects describe <toilProject> --name <new name>` or `--description <text>`, run
|
|
126
191
|
on the settings pages' path (below), so toil's own checks apply and the change is in
|
|
127
192
|
its audit log as `caller: "toil-ui"`. Escape cancels, and a refusal shows toil's
|
|
128
|
-
message and fix under the field. Only a
|
|
129
|
-
described; a checked-in one is refused with the `toil
|
|
193
|
+
message and fix under the field. Only a Toil project in your own folder can be renamed or
|
|
194
|
+
described; a checked-in one is refused with the `toil projects import` fix.
|
|
195
|
+
|
|
196
|
+
A card's menu has **Edit**, which opens a **Name** and **Description** form with one **Save**: it makes one `toil projects describe` call carrying only what changed. The top row keeps the pencil and the inline field.
|
|
130
197
|
|
|
131
|
-
|
|
198
|
+
### Editing a Toil project
|
|
199
|
+
|
|
200
|
+
Each of your own Toil projects has an edit page at `#/settings/projects/<name>/<section>`, reached from the card menu's **Edit** or **Edit sources**, from Settings, Toil projects, the command palette, or by its address. Its sections are grouped: **Sources** (repositories and the tools linked), **Field names** (with **Find the fields**, which reads a Jira project's custom fields), **People**, **Work in progress limit** and **How Analyze briefs**. Each saves through toil's own `projects` commands on the settings pages' path, so the write gate and the audit log apply as they do anywhere else, and a link to a connection with writes on is refused here as it is over MCP.
|
|
201
|
+
|
|
202
|
+
A rename keeps everything Toil UI holds for the Toil project: the server moves its cache
|
|
132
203
|
(responses, items, history, sources, sync runs, notes and agent runs), its assignments
|
|
133
204
|
and its worklog pages to the new name once toil has renamed the file, so its
|
|
134
205
|
dashboard opens straight away with no new sync. A rename waits, refused with a
|
|
135
|
-
message, while a sync or an assignment of that
|
|
206
|
+
message, while a sync or an assignment of that Toil project is running, since both read it
|
|
136
207
|
by name as they go. What can't be moved is said beside toil's result, and the next
|
|
137
|
-
sync reads the
|
|
208
|
+
sync reads the Toil project afresh under its new name.
|
|
209
|
+
|
|
210
|
+
## Switching Toil projects
|
|
138
211
|
|
|
139
|
-
|
|
212
|
+
The app's header carries a project picker right after the brand, before the views, on every page and in every theme. Its button names the Toil project you are in (**All Toil projects** on a page that belongs to none); its menu lists **All Toil projects** and each Toil project, with the current one checked. Picking one keeps the tab you are on (Code reviews stays Code reviews), and a page that is not a tab lands on the project's Summary. It is the header's way to the Toil projects page (the header has no "Toil projects" link of its own, only Settings), so it is drawn whenever there is at least one Toil project; with none, the brand goes home. On a phone the same list is the first thing in the header's Menu.
|
|
140
213
|
|
|
141
|
-
|
|
214
|
+
## The Toil project page
|
|
142
215
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
**
|
|
147
|
-
|
|
216
|
+
A Toil project opens on its **Overview**, the briefing, in a frame all of its pages share:
|
|
217
|
+
|
|
218
|
+
- **The top row:** on the Overview, a **Diagram** link (`#/project/<name>/job/diagram`) draws the Toil project's repositories as a C4 diagram in Mermaid; the steps that need a folder on disk (`util size`, `git log`, `deps scan`) are reported unchecked. Its name; the sprint and its day; its description, cut to one
|
|
219
|
+
line with the whole of it in its tooltip, its sources and a quiet **Edit** link at the end of that line (on a phone, a **Details** button beside the name opens them, the link with them); and the Ask bar, with the
|
|
220
|
+
**AI agents** button beside it (The agent, below). Moving to another Toil project is the picker in the app's header, right after the brand, on every page (see below).
|
|
221
|
+
- **The tabs**, one address each: **Overview** (`#/project/<name>`), **Board**
|
|
148
222
|
(`/board`, with how many of its cards need attention), **Dependencies**
|
|
149
223
|
(`/dependencies`), **Pull requests** (`/prs`), **People** (`/people`), **Worklog**
|
|
150
224
|
(`/worklog`) and **Analyses** (`/analyses`). The Command Center (`/command-center`)
|
|
151
225
|
is the Board tab's **Readiness** view, the stand-up is the Worklog's, and an item's
|
|
152
226
|
page sits under Board, so every address from before the tabs still opens. On a
|
|
153
|
-
narrow screen the tabs scroll sideways
|
|
154
|
-
|
|
155
|
-
|
|
227
|
+
narrow screen the tabs scroll sideways; the Agents button sits beside the Ask bar at
|
|
228
|
+
every width (a compact **AI** with its count on a phone, still named "AI agents"), so the tabs get the whole row.
|
|
229
|
+
- **The Agents panel**, closed by default at every width: one **Agents** button (**AI agents** in plain words)
|
|
230
|
+
beside the Ask bar, counting what waits on you (the tracker's inbox, proposals to approve and
|
|
231
|
+
questions to answer, and any assignment or proposal that failed, since a closed panel must not hide a failure). From 1200px wide it opens the panel beside every tab, and remembers
|
|
232
|
+
whether you left it open (in `localStorage`); below that it opens a drawer. The palette's
|
|
233
|
+
**Open the Agents panel** does the same. It holds: the tracker's inbox, then the Toil project's assignments
|
|
156
234
|
in three groups (those that need you, those working, and those gone stale), with the
|
|
157
235
|
finished ones under **Earlier**; then **Renew all stale**, the **Limits**, and this
|
|
158
|
-
|
|
236
|
+
Toil project's three newest analyses, each linking to it (Assigning work to an agent, below). Each card's title is its link; how many run at once, for how long, and what the inbox is are in the heading's (i), and the tracker's raw label (`agent:refine`) is in the Start dialog.
|
|
159
237
|
While an item's drawer is open (`?item=<id>`, The briefing, below), it takes the
|
|
160
238
|
sidebar's column from 1200px wide, and covers the view from the right below that.
|
|
161
|
-
- **Analyses** lists every Analyze kept for the
|
|
239
|
+
- **Analyses** lists every Analyze kept for the Toil project, newest first: when it was made,
|
|
162
240
|
the adapter and model that wrote it, its one-line recommendation, and what changed
|
|
163
241
|
since the one before (items newly blocked or blocked by something new, blockers
|
|
164
242
|
cleared, points moved on an item or in the sprint, items newly cited or no longer
|
|
165
243
|
cited, a new recommendation). What changed is worked out by code, from a snapshot of
|
|
166
|
-
the
|
|
244
|
+
the Toil project's items each analysis keeps, never by asking the agent. **Open** reads one
|
|
167
245
|
again at its own address (`/analyses/<id>`), top-down like the chat, with its
|
|
168
246
|
suggested changes and what it used. The server keeps them in the cache (Sync and the
|
|
169
247
|
cache, below), so they outlast a reload and a restart; with `--sample`,
|
|
@@ -171,23 +249,42 @@ A dossier opens on its **Overview**, the briefing, in a frame all of its pages s
|
|
|
171
249
|
|
|
172
250
|
### The briefing
|
|
173
251
|
|
|
174
|
-
A
|
|
175
|
-
further in, and each step one you choose (#494).
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
252
|
+
A Toil project opens on its briefing: one column to read top to bottom, each part a step
|
|
253
|
+
further in, and each step one you choose (#494). The tab's top is the answer (#552):
|
|
254
|
+
|
|
255
|
+
- **The status sentence**, the biggest text on the tab: a word with a shape (On
|
|
256
|
+
track, At risk, Behind, No sprint, or No estimates when no story in the sprint has points) and the rest of the sentence ("Behind: 18 of
|
|
257
|
+
21 points are left, and 3 working days remain."), with an (i). That it is an estimate is the first line of the fold; "Too early in the sprint to judge a pace" stays on the page. One rule
|
|
258
|
+
picks the word (`ui/src/model/status.ts`): On track when the points left fit at
|
|
259
|
+
the pace so far, At risk when at least 75% of them would land or a red reason holds
|
|
260
|
+
work up, Behind below 75%; the fold says 75% is the app's own rule of thumb. Today isn't counted in the working days left, as on the
|
|
261
|
+
Toil project cards.
|
|
262
|
+
- **One line on why**, from the briefing on screen, naming items by their titles (quoted as they are, never reworded by plain words), and
|
|
263
|
+
**How was this worked out?** one step in, with the sums and the rule.
|
|
264
|
+
- **Needs attention**, at most three cards, the same for everyone: the biggest risk,
|
|
265
|
+
stories that can't start, the oldest code review waiting past the pickup limit;
|
|
266
|
+
stories not ready to start take the place of an empty one, and an all-clear card
|
|
267
|
+
says so when nothing needs anyone; if a read failed, that card says which reads could not be read instead of an all-clear. A card's title is its one link, opening the item in
|
|
268
|
+
its drawer (or its page, as Customize says), with the ticket key in small print.
|
|
269
|
+
- **Outside the fold, too:** one compact line for each red reason no card already tells (it opens the reason in the fold), and the "Couldn't check" line for a panel that could not be read.
|
|
270
|
+
- **Show the full briefing**, closed until you open it, and remembered in this
|
|
271
|
+
browser: everything below, with Customize. The source and sprint line, any problem
|
|
272
|
+
with the briefing, and **Go to** stay in view outside it.
|
|
273
|
+
|
|
274
|
+
1. **The recommendation:** the one thing to do first, as a sentence. The sprint and
|
|
275
|
+
its day, and who wrote the briefing, stay under the answer, outside the fold: the latest Analyze, when it is
|
|
179
276
|
current (made since the data was read, or the same UTC day) and answered with a
|
|
180
277
|
briefing, with who wrote it, when, and a link to it; otherwise toil's briefing by
|
|
181
|
-
code (`toil
|
|
278
|
+
code (`toil projects brief`, `src/core/brief/`), with no agent call, which says so,
|
|
182
279
|
and why when an older Analyze exists.
|
|
183
280
|
2. **Why:** the reasons, one line each, the first open and the rest folded: Failing
|
|
184
281
|
checks, Blocked, Waiting on review, Sprint at risk, Stale, Over the WIP limit, and
|
|
185
|
-
Ticket and pull request disagree, in the
|
|
282
|
+
Ticket and pull request disagree, in the Toil project's order. Each item is under one
|
|
186
283
|
reason only, as a row with its key, title and assignee. Then **On track**, counted
|
|
187
284
|
rather than listed.
|
|
188
|
-
3. **One step in:** anything the
|
|
285
|
+
3. **One step in:** anything the Toil project's focus left out, with why, and anything the
|
|
189
286
|
code flagged that Analyze didn't mention, so nothing drops off the page unsaid. An
|
|
190
|
-
id Analyze named that isn't the
|
|
287
|
+
id Analyze named that isn't the Toil project's is shown in red.
|
|
191
288
|
4. **The numbers**, folded: burn-up, throughput, cycle time, aging work in progress
|
|
192
289
|
and pull request wait, each opening its full chart.
|
|
193
290
|
5. **Go to:** every other view, as well as its tab.
|
|
@@ -202,15 +299,15 @@ to the view behind it.
|
|
|
202
299
|
|
|
203
300
|
#### Tuning Analyze
|
|
204
301
|
|
|
205
|
-
Each
|
|
206
|
-
Analyze briefs** (`#/settings/
|
|
302
|
+
Each Toil project tunes how Analyze briefs it, under **Settings → Toil projects**, **How
|
|
303
|
+
Analyze briefs** (`#/settings/projects/<name>/analyze`): its goal, who it's written
|
|
207
304
|
for, its lenses in order with their thresholds, and what else to watch for or leave
|
|
208
305
|
out, the lenses folded until you open them. **The prompt Analyze will send**, under
|
|
209
306
|
the form, shows it as you type, composed by toil's own code, and **Save** runs
|
|
210
|
-
`toil
|
|
211
|
-
the form. The settings live in the
|
|
212
|
-
shares them; whenever a
|
|
213
|
-
whether it's your own, and a focus from a
|
|
307
|
+
`toil projects analyze set` with only what you changed, the line it runs shown under
|
|
308
|
+
the form. The settings live in the Toil project file, so a team that shares the Toil project
|
|
309
|
+
shares them; whenever a Toil project tunes Analyze, the briefing names the file and
|
|
310
|
+
whether it's your own, and a focus from a Toil project you haven't adopted still applies.
|
|
214
311
|
Clearing a setting is a delete, made in a terminal. Toil UI composes the preview with
|
|
215
312
|
the toil code it's built with, and Analyze asks the toil it runs on, so the two match
|
|
216
313
|
when Toil UI and toil are released together.
|
|
@@ -248,7 +345,7 @@ blocks another or is blocked, on the current sprint's dates, then the dependency
|
|
|
248
345
|
toil reads dates a link, so a block is drawn from when both items existed. An item
|
|
249
346
|
whose history records no move into In progress (GitHub records only open and closed)
|
|
250
347
|
is drawn in progress from when it was created. Nothing is fetched for the chart: it
|
|
251
|
-
reads the links, transitions, pull requests, builds and checks the
|
|
348
|
+
reads the links, transitions, pull requests, builds and checks the Toil project already
|
|
252
349
|
synced, and the readiness gate's verdict for work not started.
|
|
253
350
|
- **The table under the chart lists every bar and every arrow**, with links: each
|
|
254
351
|
item's status and points, its time in progress, blocked (and by what) and with
|
|
@@ -265,7 +362,7 @@ The Board tab flags each card that needs attention, with a flag beside its statu
|
|
|
265
362
|
an edge in the warning colour: anything that needs action now or a look (Insights,
|
|
266
363
|
below), but not what is only worth knowing. **Needs attention only** narrows the board
|
|
267
364
|
to those cards, and the tab carries how many there are. Drag a card to another column,
|
|
268
|
-
or press M on it for its menu, to propose the move: nothing changes until you apply
|
|
365
|
+
or press M on it for its menu, to propose the move (a card that can't be moved can't be dragged, and shows the reason: a GitHub issue that isn't on a project board this Toil project reads, or an area with no status command; a GitHub move proposes `toil github project status --item <id> --to <status>`): nothing changes until you apply
|
|
269
366
|
the command the proposal shows, and the card stays where its tracker says. Under the board are its
|
|
270
367
|
stories with their pull requests, builds and deployments, then the builds and
|
|
271
368
|
deployments themselves.
|
|
@@ -275,31 +372,50 @@ deployments themselves.
|
|
|
275
372
|
The board's cards and its **Needs attention** flag and the flow charts mark
|
|
276
373
|
each open work item with its insights, weightiest first, each naming the data it
|
|
277
374
|
rests on (`ui/src/model/insights.ts`). One the data can't support isn't raised at
|
|
278
|
-
all, rather than raised on a guess.
|
|
375
|
+
all, rather than raised on a guess. A card shows one chip per kind of insight,
|
|
376
|
+
with a count when there are several ("Blocking 2"); its tooltip lists each one,
|
|
377
|
+
and the item view lists them all.
|
|
279
378
|
|
|
280
379
|
| Insight | Means | Weight |
|
|
281
380
|
|---|---|---|
|
|
282
381
|
| Blocked | Another item that isn't done blocks it (its links) | needs action now |
|
|
283
382
|
| Build failing | Its pull request's latest build failed | needs action now |
|
|
284
|
-
| Aging | In progress longer than 85% of the
|
|
383
|
+
| Aging | In progress longer than 85% of the Toil project's finished items took; needs at least three cycle times to compare with | needs action now |
|
|
285
384
|
| Deployed, still open | An environment runs it, but it isn't done | needs a look |
|
|
286
385
|
| Carried over | It was in the previous sprint too | needs a look |
|
|
287
386
|
| PR with no build | A pull request for it is open with no build | needs a look |
|
|
288
387
|
| Stale | No update for more than 5 days | needs a look |
|
|
289
388
|
| Blocking | It blocks another item | needs a look |
|
|
290
|
-
| Merged, not deployed | Its pull requests are merged, but no environment runs them yet; only for a
|
|
389
|
+
| Merged, not deployed | Its pull requests are merged, but no environment runs them yet; only for a Toil project that names environments | worth knowing |
|
|
291
390
|
| No estimate | It has no estimate | worth knowing |
|
|
292
391
|
| Added mid-sprint | It joined the sprint after it started | worth knowing |
|
|
293
392
|
|
|
393
|
+
## Tables and rows
|
|
394
|
+
|
|
395
|
+
The pattern every table follows (`DataTable` in `src/components/layout.tsx`; the Waiting now table is the model):
|
|
396
|
+
|
|
397
|
+
- **Actions get their own column,** the narrow last one (`actions: true` on the column): a quiet icon button that opens a menu, named for its row (`aria-label="Actions for …"`). Never a bordered text button under each row's title.
|
|
398
|
+
- **One idea a cell.** A name and one badge, a state and one figure. Figures are compact (`32.6 d`, `326 · 8 files`); the sentence behind one is a `<details className="cell-more">` one press in. Nothing is dropped, only layered (principle 11); errors, source and verification stay on screen.
|
|
399
|
+
- **Numbers as small visuals where they have a shape:** a diff-style bar of five squares for additions and deletions, never colour alone (a stripe pattern and the numbers beside it), as one `role="img"` whose `aria-label` carries every figure. An unknown figure is a dash, not zero (principle 12).
|
|
400
|
+
- **Gutters:** every cell has room on its right (`1.5rem` in the queue), the actions column none, and stacked rows (under about 28rem) drop to label and value pairs. Check at 375, 768 and 1440px in Plain, Crate and Harvest.
|
|
401
|
+
|
|
402
|
+
## Forms and rows of controls
|
|
403
|
+
|
|
404
|
+
A label with its control is one row, and rows stacked in a card line up (the Settings, Theme card is the model, `.panel > .choice` in `src/views.css`):
|
|
405
|
+
|
|
406
|
+
- **One label column, one control width.** Stacked rows share a label column wide enough for the longest label and give their controls the same width, so the controls start at the same left edge and end at the same right one. Never let each row size itself to its own label.
|
|
407
|
+
- **A control that is a link is still a button.** A link that looks like one takes `btn`, which gives it the frame a `<button>` gets (`.btn:where(a)`); don't style a bare anchor and hope.
|
|
408
|
+
- **Narrow:** under about 30rem a row is the label above its control, full width.
|
|
409
|
+
- **Look at it, don't reason about it.** Screenshot every new or changed form at 375 and 1440px in Plain, Crate and Harvest; ragged edges, text with no frame and controls that don't line up don't show up in tests.
|
|
410
|
+
|
|
294
411
|
## Pull requests
|
|
295
412
|
|
|
296
|
-
Each
|
|
413
|
+
Each Toil project has a **Pull requests** tab (`#/project/<name>/prs`), built from OWI 0.2
|
|
297
414
|
changes:
|
|
298
415
|
|
|
299
416
|
- **Waiting now:** the open pull requests, longest wait first, each with what it
|
|
300
417
|
waits on (review, changes, checks, merge, or a draft its author holds), since when
|
|
301
|
-
in working days
|
|
302
|
-
that said so), the work items it names, and its size, XS to XL by changed lines.
|
|
418
|
+
in working days (`32.6 d`, the sentence behind it one press in), who wrote it (the name, and an Agent or Bot badge that opens the signal that said so), the work items it names, and its size, XS to XL by changed lines.
|
|
303
419
|
- **Flags:** no first review in 2 working days, checks failing for over a day, a merge
|
|
304
420
|
conflict, no linked work item, a work item done while its pull request is open, and
|
|
305
421
|
a merged pull request whose item isn't done, each with what it rests on.
|
|
@@ -307,38 +423,49 @@ changes:
|
|
|
307
423
|
merge (approval to merge) times, review rounds, sizes and merges per week, over six
|
|
308
424
|
weeks, each split by people, agents and bots and each with its sample size and what
|
|
309
425
|
couldn't be measured.
|
|
426
|
+
- **Actions:** each open pull request has one **Actions** menu, a quiet `…` icon button in its own narrow last column (named `Actions for <repo> #<n>`; stacked rows put it at the row's top corner), with **Review** (reads the pull request, its diff and checks, and drafts findings as comments you can post) and **Ship** (on a pull request a person wrote: drafts replies to its review; editing, the gate and pushing stay in your terminal). Each opens its own page, `#/project/<name>/job/review?target=<change id>` or `/job/ship?…`, which says what the job does and needs and has **Run**. The run goes through the Ask bar, so every write is a proposal card and the run is kept in the worklog. A job missing its code host's connection stays in the menu, dimmed, naming the connection to add. Ship stops after 3 finished rounds on one pull request; the next run is refused and says it needs a person (`needs-human`). The steps come from toil's workflow pages (`skills/toil/workflows/`).
|
|
310
427
|
- **Suggested reviewers:** for an open pull request with nobody asked, the CODEOWNERS
|
|
311
428
|
of its paths and the earlier reviewers of the same files and folders, each as a
|
|
312
429
|
proposal with the `toil … --allow-write` line to ask them.
|
|
313
430
|
|
|
314
|
-
The
|
|
431
|
+
The Toil project's work item keys are matched in each pull request's title, branch and
|
|
315
432
|
description (a Jira project's `PAY-101`, Azure Boards' `AB#2302`, a GitHub
|
|
316
433
|
repository's `owner/repo#41`). A code host's section may set author kinds by hand,
|
|
317
434
|
`"authorKinds": { "release-bot": "BOT" }`, which win over every other signal.
|
|
318
435
|
|
|
319
436
|
## People
|
|
320
437
|
|
|
321
|
-
Each
|
|
438
|
+
Each Toil project has a **People** tab (`#/project/<name>/people`), built
|
|
322
439
|
from the same OWI work items and changes as the dashboard and the pull requests view,
|
|
323
|
-
and from the
|
|
324
|
-
system (`toil
|
|
440
|
+
and from the Toil project's `people` section, which says who each person is in every
|
|
441
|
+
system (`toil projects person`, or **Settings, Toil projects**):
|
|
325
442
|
|
|
326
443
|
- **A card per person**, agents included, in name order: their work in progress by
|
|
327
444
|
status with how long each item has sat in it, their open pull requests and what
|
|
328
445
|
each waits on, the reviews waiting on them (oldest first), their blocked items and
|
|
329
446
|
what blocks each, and what they did in the last 14 days. A link opens their items
|
|
330
447
|
on the Board tab, filtered to them.
|
|
331
|
-
- **A team strip:** work in progress against the
|
|
448
|
+
- **A team strip:** work in progress against the Toil project's `wipLimit` and who is over
|
|
332
449
|
it, the review queue, and the current sprint's unassigned items.
|
|
333
450
|
- **Agents:** a person with `kind: "agent"`, matched by the same signals as a pull
|
|
334
451
|
request's author kind (its account, a Co-Authored-By trailer, a branch prefix) where
|
|
335
452
|
the signal names it. A person's own pull request written with an agent says so.
|
|
336
|
-
- **Accounts the
|
|
453
|
+
- **Accounts the Toil project doesn't map** get cards of their own, so no work goes
|
|
337
454
|
missing. One that shares an email with a person, or with an account in another
|
|
338
|
-
system, is suggested as a match with the `toil
|
|
455
|
+
system, is suggested as a match with the `toil projects person` line that applies
|
|
339
456
|
it; it is applied only when someone presses the button, and an email that fits more
|
|
340
457
|
than one candidate suggests nothing and says why. Accounts that only wrote bots'
|
|
341
458
|
pull requests are left out and counted.
|
|
459
|
+
- **Map** (#561) is on each such card: it opens a form in place to choose an existing
|
|
460
|
+
person or add a new one (a person or an agent), with a field for the identity in each
|
|
461
|
+
source the Toil project uses (GitHub, Jira, Azure DevOps, Bitbucket), the account's own
|
|
462
|
+
prefilled and a likely person from toil's matcher (`src/core/people-match.ts`) as the
|
|
463
|
+
starting choice. Save runs `toil projects person` through the same config path as
|
|
464
|
+
Settings; nothing is applied until it is pressed. **Save to this repository** (beside
|
|
465
|
+
the people, in the Map form once it has saved, and in Settings) runs `toil projects
|
|
466
|
+
people save`, which writes the people into the repository's `.toil/projects/<name>.json`
|
|
467
|
+
for any host (GitHub, Azure DevOps, Bitbucket); the page says which file changes, and
|
|
468
|
+
nothing is staged or committed.
|
|
342
469
|
|
|
343
470
|
It shows what is on each plate and never scores anyone: no ranking, no productivity
|
|
344
471
|
figure, no person-to-person comparison and no line or commit counts. Flow metrics
|
|
@@ -348,20 +475,20 @@ stay team-level, in the pull requests view.
|
|
|
348
475
|
|
|
349
476
|
Before a work item goes to an agent, Toil UI checks whether it is ready for one. The
|
|
350
477
|
check uses no model and no premium request: only the item's cached OWI record, the
|
|
351
|
-
|
|
478
|
+
Toil project's other items, and at most one live read, made when you press for it
|
|
352
479
|
(`ui/src/model/readiness.ts`). Its verdict is **ready**, **thin** or **blocked**, with
|
|
353
480
|
one row per check:
|
|
354
481
|
|
|
355
482
|
| Check | Passes when | Otherwise |
|
|
356
483
|
|---|---|---|
|
|
357
|
-
| Acceptance criteria | The field the
|
|
358
|
-
| Description | At least `minWords` words (25 by default) of real text, not counting the
|
|
359
|
-
| 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
|
|
360
|
-
| Blockers | No open item blocks it | blocked by an open item; thin for a blocker the
|
|
361
|
-
| Scope | It comes from one of the
|
|
484
|
+
| Acceptance criteria | The field the Toil project 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 |
|
|
485
|
+
| Description | At least `minWords` words (25 by default) of real text, not counting the Toil project's template lines, placeholder lines (TBD, N/A, lorem ipsum) or unfilled `<slots>` | thin |
|
|
486
|
+
| 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 Toil project 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 |
|
|
487
|
+
| Blockers | No open item blocks it | blocked by an open item; thin for a blocker the Toil project doesn't hold |
|
|
488
|
+
| Scope | It comes from one of the Toil project's sources, and the Toil project names a repository | blocked from outside the Toil project; thin with no repository |
|
|
362
489
|
|
|
363
490
|
The verdict is blocked when any row is, thin when any row is, and ready only when every
|
|
364
|
-
row passes. Each area's section in the
|
|
491
|
+
row passes. Each area's section in the Toil project sets it up:
|
|
365
492
|
|
|
366
493
|
```json
|
|
367
494
|
"jira": {
|
|
@@ -378,10 +505,10 @@ that names none uses `Microsoft.VSTS.Common.AcceptanceCriteria`.
|
|
|
378
505
|
rows, each with where its answer came from. **Check the workflow live** makes the one
|
|
379
506
|
live read, read-only: `jira issue transitions` for a Jira issue, `ado work-item
|
|
380
507
|
states` for an Azure DevOps type. A GitHub issue needs none.
|
|
381
|
-
- **The Command Center** (`#/
|
|
508
|
+
- **The Command Center** (`#/project/<name>/command-center`, the Board tab's Readiness view) lists every
|
|
382
509
|
work item with its verdict and, for each one that isn't ready, the rows that say why.
|
|
383
510
|
It filters by verdict, status, type, assignee and source, and makes no live read.
|
|
384
|
-
It is strict: only ready items are slated, in the
|
|
511
|
+
It is strict: only ready items are slated, in the Toil project's order, under a plan id
|
|
385
512
|
that changes when anything in the plan does.
|
|
386
513
|
- **Starting the plan comes with assign-to-agent (#293).** Until then the start button
|
|
387
514
|
is disabled and says so; the plan it would start is shown above it.
|
|
@@ -389,10 +516,10 @@ that names none uses `Microsoft.VSTS.Common.AcceptanceCriteria`.
|
|
|
389
516
|
are ready for an agent?" (The agent, below).
|
|
390
517
|
## Worklog
|
|
391
518
|
|
|
392
|
-
Each
|
|
519
|
+
Each Toil project has a **Worklog** tab (`#/project/<name>/worklog`):
|
|
393
520
|
one page a day, folded by code from what the cache holds, facts only. No model writes
|
|
394
521
|
a line of it. A calendar shows the days that have a page, with how many lines each
|
|
395
|
-
has; a day opens as `#/
|
|
522
|
+
has; a day opens as `#/project/<name>/worklog/<yyyy-mm-dd>`. Days and times are UTC,
|
|
396
523
|
as everywhere else in Toil UI.
|
|
397
524
|
|
|
398
525
|
A page has:
|
|
@@ -435,8 +562,8 @@ page is folded again from the cache and written where its text changed, as Markd
|
|
|
435
562
|
in the data folder:
|
|
436
563
|
|
|
437
564
|
```text
|
|
438
|
-
<data folder>/cache/worklog/<
|
|
439
|
-
<data folder>/cache/worklog/<
|
|
565
|
+
<data folder>/cache/worklog/<toilProject>/<yyyy-mm>/<yyyy-mm-dd>.md
|
|
566
|
+
<data folder>/cache/worklog/<toilProject>/runs/<run id>.md
|
|
440
567
|
```
|
|
441
568
|
|
|
442
569
|
The pages live under the cache's retention: a day whose rows are gone loses its page,
|
|
@@ -447,16 +574,20 @@ it came out the same as the page kept; the same cache always gives the same page
|
|
|
447
574
|
toil's own file service: `toil util encode base64 --decode --out <file>`, run with that
|
|
448
575
|
folder as its workspace, which writes a new file only and never into toil's own
|
|
449
576
|
config. Publishing an exported page is a proposal: `toil confluence page create
|
|
450
|
-
--body-file <file> --markdown` in the
|
|
577
|
+
--body-file <file> --markdown` in the Toil project's Confluence space, or `toil github issue
|
|
451
578
|
create --body-file <file>` in its repository, for you to run through toil's write gate.
|
|
452
579
|
Toil UI posts nothing. With sample data, notes and export are off.
|
|
453
580
|
|
|
454
581
|
### Stand-up
|
|
455
582
|
|
|
456
|
-
**Stand-up since the last working day
|
|
457
|
-
|
|
583
|
+
**Stand-up since the last working day** leads the Summary too: a compact **Stand-up** card right under the
|
|
584
|
+
headline answer and what needs attention shows the same report for the default range ("Yesterday" or "Since
|
|
585
|
+
Friday"), five lines with **Show more** in place, and **Open the full stand-up**. With no sync behind it the card
|
|
586
|
+
shows `–` and "Not read yet" with **Sync now**, never "nothing happened". The Summary's **Go to** row and the
|
|
587
|
+
command palette (**Open the stand-up**) open it as well. The page, on the Worklog
|
|
588
|
+
(`#/project/<name>/worklog/standup`), reshapes the worklog for a meeting: since the last
|
|
458
589
|
working day through today (Friday through Monday on a Monday), or any range of up to 31
|
|
459
|
-
days you pick (`#/
|
|
590
|
+
days you pick (`#/project/<name>/worklog/standup/<from>/<to>`, or `/<day>` for one), and each day's page has a
|
|
460
591
|
**Stand-up for this day**. It is a fold of those days' pages by code, with no model, so the
|
|
461
592
|
same days always give the same report.
|
|
462
593
|
|
|
@@ -468,9 +599,9 @@ same days always give the same report.
|
|
|
468
599
|
failed build of their pull request, a pull request of theirs waiting on review for 2
|
|
469
600
|
working days or more) and **Next** (current-sprint items assigned to them and not
|
|
470
601
|
started). A line belongs to whoever the fact names: who moved the item, who wrote or
|
|
471
|
-
reviewed the pull request. A pull request a
|
|
472
|
-
- **People** come from the
|
|
473
|
-
GitHub accounts land under one name. An account the
|
|
602
|
+
reviewed the pull request. A pull request a Toil project agent wrote goes under the agent.
|
|
603
|
+
- **People** come from the Toil project's `people`, so one person's Jira, Azure DevOps and
|
|
604
|
+
GitHub accounts land under one name. An account the Toil project doesn't map gets its own
|
|
474
605
|
card, named with its area and id; the People view suggests where it belongs.
|
|
475
606
|
- **What the worklog can't vouch for** in the range is said at the top. Review waits, the
|
|
476
607
|
sprint and Next aren't on any worklog page, so they are as of the latest sync, and the
|
|
@@ -479,7 +610,7 @@ same days always give the same report.
|
|
|
479
610
|
|
|
480
611
|
It copies as **Markdown** (for Slack, Teams or a wiki) or **plain text**, line for line as
|
|
481
612
|
shown. **Export** writes the Markdown through toil's file service, as a page's export does,
|
|
482
|
-
to `standup-<
|
|
613
|
+
to `standup-<toilProject>-<from>-to-<to>.md`, and publishing it to Confluence or GitHub is a
|
|
483
614
|
proposal for you to run.
|
|
484
615
|
|
|
485
616
|
**Write it up** is optional: it asks the agent for a short narrative of the same report,
|
|
@@ -490,7 +621,7 @@ usage counts like any chat's.
|
|
|
490
621
|
|
|
491
622
|
## Toil's configuration
|
|
492
623
|
|
|
493
|
-
The Settings pages manage what `toil connections` and `toil
|
|
624
|
+
The Settings pages manage what `toil connections` and `toil projects` manage, by
|
|
494
625
|
running those commands through `@imagile-dev/toil/api`, never by editing a file:
|
|
495
626
|
|
|
496
627
|
- **Connections:** list, add, test, set the default, turn writes on or off,
|
|
@@ -505,14 +636,14 @@ running those commands through `@imagile-dev/toil/api`, never by editing a file:
|
|
|
505
636
|
Turning writes on asks you to type the connection's name, as the CLI does. A
|
|
506
637
|
connection made by `TOIL_*` env vars alone is shown read-only, with where it
|
|
507
638
|
came from.
|
|
508
|
-
- **
|
|
509
|
-
show and check any of them. A
|
|
510
|
-
on its card and dashboard, through `toil
|
|
639
|
+
- **Toil projects:** create one, add a repository, link an area, name a field, and
|
|
640
|
+
show and check any of them. A Toil project's name and description are edited in place
|
|
641
|
+
on its card and dashboard, through `toil projects describe`. The list has **New Toil project** (`#/new-project`) and an edit page for each (`#/settings/projects/<name>/<section>`: Sources, Field names, People, Work in progress limit, How Analyze briefs). A link to a connection with writes on is refused
|
|
511
642
|
here, as over MCP: make it on the CLI.
|
|
512
|
-
- **Bounds and time limit:** toil has no command for these, so they are
|
|
513
|
-
|
|
643
|
+
- **Bounds and time limit:** toil has no command for these, so they are under
|
|
644
|
+
Settings, General, **Advanced**, shown read-only.
|
|
514
645
|
- **Usage:** how toil is used on this machine, from `toil audit stats`, which
|
|
515
|
-
reads only toil's local audit log
|
|
646
|
+
reads only toil's local audit log. It opens on a one-line summary of calls, failures and changes, without Toil UI's own background calls; behind **More detail** are calls per day, the split between Toil UI, the
|
|
516
647
|
CLI and MCP, the commands used most, the ones that fail most with their top
|
|
517
648
|
error code and its usual fix (and, on request, their recent failures from
|
|
518
649
|
`toil audit list`), and the commands nothing called. It needs a toil with
|
|
@@ -529,18 +660,18 @@ newer than 0.1.0-alpha.2; with that one, use the CLI.
|
|
|
529
660
|
An **(i)** beside a term explains it in a sentence or two when you hover or focus
|
|
530
661
|
it, and pressing it opens the same words with a **Read more** link to the section
|
|
531
662
|
of these docs that says the rest. A **pencil** beside a configurable value (a
|
|
532
|
-
connection, a
|
|
663
|
+
connection, a Toil project's sources, people, field names or work-in-progress limit,
|
|
533
664
|
the agent, a usage cap) opens the settings page where it's set, at that value; it
|
|
534
665
|
only navigates. **Help** in the header is a menu with the docs for the view you're on
|
|
535
666
|
and **What's new** (below).
|
|
536
667
|
|
|
537
|
-
Where a screen uses an AI term (tokens and the context window under
|
|
538
|
-
model, harness and MCP under
|
|
668
|
+
Where a screen uses an AI term (tokens and the context window under Usage,
|
|
669
|
+
model, harness and MCP under AI agent, sandbox and permission mode in the Assign
|
|
539
670
|
dialog's modes, session and system prompt in Renew all stale, hallucination in the
|
|
540
671
|
chat's **About these answers**), its (i) popover also gives each term's first
|
|
541
672
|
sentence from Context Overflow's glossary, with **Read more on Context Overflow**.
|
|
542
673
|
Help's menu then has **Learn**: four of Context Overflow's modules, by task.
|
|
543
|
-
|
|
674
|
+
**Links to learning content**, under
|
|
544
675
|
**Settings, General** and kept in this browser, is on by default; off, every link to
|
|
545
676
|
Context Overflow and every glossary line is gone, and Help keeps the view's docs and
|
|
546
677
|
What's new.
|
|
@@ -554,12 +685,12 @@ views follow.
|
|
|
554
685
|
|
|
555
686
|
Every empty panel offers the one action that fills it, under one short line, with any
|
|
556
687
|
explanation in its (i): **Link a pipeline** and **Add an environment** (pencils to
|
|
557
|
-
|
|
688
|
+
Toil project setup at the Toil project's sources) on the Board tab's builds and deployments, **Add
|
|
558
689
|
a repository** for pull requests, **Add a person** on the People tab, **Analyze now**
|
|
559
690
|
for an empty Analyses tab, **Show every item** for a Command Center filter that hides
|
|
560
691
|
everything, and **Sync now** in the local app wherever only a newer read of the tracker
|
|
561
692
|
fills the panel (the sprint, the burn-up, links between items). The site preview can't
|
|
562
|
-
sync, so it offers
|
|
693
|
+
sync, so it offers Toil project setup there instead. A test fails on any empty panel with
|
|
563
694
|
neither an action nor a link.
|
|
564
695
|
|
|
565
696
|
### What's new
|
|
@@ -580,23 +711,23 @@ screen it's **Search and commands** in the header's Menu. Type to narrow it down
|
|
|
580
711
|
use the arrow keys to move, **Enter** to open and **Escape** to close. It's hidden
|
|
581
712
|
until you call it up.
|
|
582
713
|
|
|
583
|
-
- **Jump** to a
|
|
714
|
+
- **Jump** to a Toil project, any of a Toil project's tabs (Overview, Board, Dependencies,
|
|
584
715
|
Pull requests, People, Worklog, Analyses), a saved analysis, a settings page, or a
|
|
585
716
|
theme.
|
|
586
|
-
- **Run** Sync now (where Toil UI keeps a cache), and on a
|
|
587
|
-
focuses the Ask bar), Analyze, the agent that answers this chat, and Assign the
|
|
717
|
+
- **Run** Sync now (where Toil UI keeps a cache), and on a Toil project's page Ask (it
|
|
718
|
+
focuses the Ask bar), Analyze, **Review a pull request**, **Ship: answer a review** and **Diagram <Toil project>** (each opens its job's page), **Open the Agents panel** (**Open the AI agents panel** in plain words), the agent that answers this chat, and Assign the
|
|
588
719
|
item you were on to an agent: the board card that had focus, or the item whose
|
|
589
720
|
page is open.
|
|
590
721
|
- Matching is fuzzy and ignores case: `pay12` finds `PAY-12`, and each word you
|
|
591
722
|
type has to appear, in order. Results are grouped by kind, and the group with the
|
|
592
723
|
best match comes first.
|
|
593
724
|
|
|
594
|
-
### Search across
|
|
725
|
+
### Search across Toil projects
|
|
595
726
|
|
|
596
|
-
With something typed, the palette searches the items of every
|
|
597
|
-
title. Each result shows its
|
|
598
|
-
what the last sync stored, never the tracker: opening it reads each
|
|
599
|
-
the cache the way its dashboard does. A result from a
|
|
727
|
+
With something typed, the palette searches the items of every Toil project, by key and
|
|
728
|
+
title. Each result shows its Toil project and status and opens the item. It reads only
|
|
729
|
+
what the last sync stored, never the tracker: opening it reads each Toil project from
|
|
730
|
+
the cache the way its dashboard does. A result from a Toil project last synced more than
|
|
600
731
|
a day ago, or whose last sync failed, says how old its copy is.
|
|
601
732
|
|
|
602
733
|
### Keyboard shortcuts
|
|
@@ -621,9 +752,9 @@ request: the kind, a title, the details and your email. It sends through
|
|
|
621
752
|
first. Send works only while the box is ticked, and any edit clears it, so you
|
|
622
753
|
agree to the report on screen and no other.
|
|
623
754
|
- **Only what you typed.** toil adds its version and commit, nothing else: no
|
|
624
|
-
|
|
625
|
-
- **The same
|
|
626
|
-
Origin and
|
|
755
|
+
Toil project, connection, host or cached data.
|
|
756
|
+
- **The same checks as Settings.** `api/feedback` needs the cookie, the page's own
|
|
757
|
+
Host and Origin and a JSON body, takes the four fields and nothing else, and runs
|
|
627
758
|
`toil feedback` and no other command. Your tick becomes the yes to the command's
|
|
628
759
|
own consent question. With sample data it sends nothing. With a toil that has no
|
|
629
760
|
`feedback` command (0.1.0-alpha.2), the dialog says so and points at the site's
|
|
@@ -633,10 +764,11 @@ request: the kind, a title, the details and your email. It sends through
|
|
|
633
764
|
|
|
634
765
|
The dashboards read from a local cache, which a sync fills. Press **Sync now** in
|
|
635
766
|
the Sync panel at the foot of the page. The sync makes the same toil calls the
|
|
636
|
-
dashboards make, for every
|
|
767
|
+
dashboards make, for every Toil project, and stores the answers. The work items go
|
|
637
768
|
through toil's Open Work Item mapping, with their status changes and the pull
|
|
638
769
|
requests, builds and deployments that name them.
|
|
639
770
|
|
|
771
|
+
- **Nothing moves while it runs.** A running sync shows as a small card over the lower corner of the window (along the bottom edge on a phone), with the theme's loader inside it, never in the page itself, so the page you are reading stays where it is.
|
|
640
772
|
- **Incremental.** After the first sync, Jira and Azure DevOps searches, and a
|
|
641
773
|
GitHub repository's issues, ask only for what changed since the last good sync (`updatedSince`, five minutes early in
|
|
642
774
|
case the clocks disagree), and the GitHub board marks the issues whose
|
|
@@ -646,27 +778,27 @@ requests, builds and deployments that name them.
|
|
|
646
778
|
Once a day, the Jira and Azure DevOps searches are also sent whole (ids only
|
|
647
779
|
where toil can), and an item they no longer list is dropped; if that listing
|
|
648
780
|
fails, the changes are kept and the next sync tries it again. Per-item calls
|
|
649
|
-
(histories, pull request gets) run 4 at a time across a
|
|
781
|
+
(histories, pull request gets) run 4 at a time across a Toil project.
|
|
650
782
|
Azure DevOps histories come from the project's revisions feed, read from the
|
|
651
783
|
watermark; an item is read on its own when the feed doesn't hold all of it.
|
|
652
784
|
- **Every page.** Each call follows `meta.page.nextCursor` to the end, up to 200
|
|
653
785
|
pages, and fails that source, saying so, rather than keep part of a listing.
|
|
654
|
-
- **Each source on its own.** Each area a
|
|
786
|
+
- **Each source on its own.** Each area a Toil project reads (Jira, Bitbucket, Jenkins,
|
|
655
787
|
OpenShift and so on) is a source with its own state. A source that fails shows
|
|
656
788
|
toil's message and fix in the Sync panel, and keeps its last good data, marked
|
|
657
|
-
stale. The other sources and
|
|
789
|
+
stale. The other sources and Toil projects aren't touched. The next sync asks it
|
|
658
790
|
for everything since its last good sync, so nothing is missed.
|
|
659
791
|
- **When.** The line under the header says when the data was synced. The panel
|
|
660
|
-
says when each
|
|
792
|
+
says when each Toil project was synced, and shows a running sync's progress
|
|
661
793
|
(requests, pages and retries, from toil's own progress events).
|
|
662
794
|
- **Where.** The cache is one SQLite file, `cache/toil-ui.db` in the data folder,
|
|
663
795
|
through Node's built-in `node:sqlite`, so there's no native module. While Toil
|
|
664
796
|
UI runs, its write-ahead log (`toil-ui.db-wal` and `toil-ui.db-shm`) sits beside
|
|
665
797
|
it, and closing folds the log back into the file. It holds
|
|
666
798
|
ticket content, so it stays on this machine and is readable by your account
|
|
667
|
-
only. The analyses (#395) are kept in the same file, the newest 100 per
|
|
799
|
+
only. The analyses (#395) are kept in the same file, the newest 100 per Toil project,
|
|
668
800
|
and a sync never rewrites them.
|
|
669
|
-
- **For how long.** A
|
|
801
|
+
- **For how long.** A Toil project's synced data (responses, items,
|
|
670
802
|
transitions, change refs, worklog facts and each source's state) expires together, once the
|
|
671
803
|
last sync that saved data for it is older than the retention period (30 days by default),
|
|
672
804
|
at start and after each sync. A sync that fails doesn't keep old data alive. Worklog facts that no
|
|
@@ -674,9 +806,9 @@ requests, builds and deployments that name them.
|
|
|
674
806
|
goes when it is that old itself. The retention period
|
|
675
807
|
also sets how far back closed Jira and Azure DevOps items are read, with a
|
|
676
808
|
floor of 6 weeks (see What it reads). An analysis goes once
|
|
677
|
-
it is older than the retention period, and with its
|
|
809
|
+
it is older than the retention period, and with its Toil project when toil no longer
|
|
678
810
|
has it.
|
|
679
|
-
- **Wiping it.** **Wipe the cache
|
|
811
|
+
- **Wiping it.** **Wipe the cache**, under Settings, General, **Advanced**, deletes it after asking
|
|
680
812
|
first. `toil-ui wipe` does the same from a terminal, once `toil-ui` has
|
|
681
813
|
stopped: a running Toil UI holds `toil-ui.lock` in the data folder, and the
|
|
682
814
|
command refuses while it does. Your trackers are never touched. The next sync fetches everything again.
|
|
@@ -686,7 +818,7 @@ requests, builds and deployments that name them.
|
|
|
686
818
|
exist. So is an item closed longer ago than the read window. A GitHub issue
|
|
687
819
|
stays until the retention period ends or you wipe the cache.
|
|
688
820
|
|
|
689
|
-
The page can run only the reads the dashboards make: `
|
|
821
|
+
The page can run only the reads the dashboards make: `projects list` and `Toil projects
|
|
690
822
|
show`, and each area's search, history, pull request, build and deployment reads.
|
|
691
823
|
Any other command is refused before it reaches toil, and a change to a tracker is
|
|
692
824
|
never made from the page. The worklog's own calls are made by the server, never named
|
|
@@ -695,39 +827,61 @@ by the page: `toil audit list`, read-only, to see whether a proposal was applied
|
|
|
695
827
|
|
|
696
828
|
## The agent
|
|
697
829
|
|
|
698
|
-
Every
|
|
699
|
-
|
|
700
|
-
screen and the page steps back, with a slim strip that keeps the dossier, its sprint
|
|
830
|
+
Every Toil project page has an **Ask bar** in its top row: one line. Pressing into it opens the **focused view**: the conversation takes the
|
|
831
|
+
screen and the page steps back, with a slim strip that keeps the Toil project, its sprint
|
|
701
832
|
and the agent answering in sight. **Escape** or **Close** puts it away; the
|
|
702
|
-
conversation stays, for the rest of the
|
|
703
|
-
|
|
704
|
-
- **
|
|
705
|
-
|
|
833
|
+
conversation stays, for the rest of the Toil project's pages, until you reload.
|
|
834
|
+
|
|
835
|
+
- **The guided start** (#552) is what the chat shows before the first question:
|
|
836
|
+
"What would you like to know about {name}?", then nine plain questions in four groups
|
|
837
|
+
(How are we doing? What's in the way? Backlog. For others), beside **Before you ask**. What each is good for is its hover; the one line on the page is that "Who might need help?" never ranks anyone. The dialog's title is the project's name. You can still type your own, except with no AI agent set up, when the questions are off and the notice links to **Settings → AI agent**. Pressing a question asks its text
|
|
838
|
+
through the same path as typing it; after the first answer the same questions are the
|
|
839
|
+
**Suggestions** menu. The questions are `src/guided-questions.ts`, not the server's
|
|
840
|
+
starters, which still back `api/agent/starters`.
|
|
841
|
+
- **Before you ask** is on the page, never in a popover, as the same one line at every width,
|
|
842
|
+
"It reads what your connections can read, saved and live. It changes nothing.", with a
|
|
843
|
+
**What AI can see** button that opens the rest: what the AI can see (this Toil project's saved
|
|
844
|
+
copy, counted as items, code reviews, builds and deployments, and live reads through toil when
|
|
845
|
+
the copy is not enough, read-only) and what it can't do (change anything in the systems named,
|
|
846
|
+
see email or chat, read anything your connections can't already read). Who answers is the
|
|
847
|
+
header's to say, and what it costs is the usage line's.
|
|
848
|
+
- **How sure is this?** is under every finished answer, worked out by code
|
|
849
|
+
(`src/model/confidence.ts`) and never by the model, with an (i). **High**: every saved read worked, the data
|
|
850
|
+
is under 24 hours old, and at most 1 in 10 of the items the question needs a field of
|
|
851
|
+
lacks it. **Medium**: one of those slipped, or the answer names one item its tools never returned. **Low**: a read failed, the data is over 3 days
|
|
852
|
+
old, there are fewer than 3 items to go on (code reviews, for the question about reviews), or the answer names more than one item its tools never returned, or half of those it cites. A question from the guided start is checked against
|
|
853
|
+
the panels it needs; a typed question and Analyze against every read. Under the word and its reason is one folded line, "What it looked at · 3 s · about $0.04 of usage (estimate)", which opens to the items the answer cited as links (a cited id the project doesn't hold as the bare
|
|
854
|
+
id) and the usage breakdown. "Suggestions only. Nothing was changed." is said under the first answer of a conversation, not every one; "Answered by" appears under an answer only when it differs from the header's. The answer's own heading is not drawn (it repeats the question), though a screen reader still has it. The existing proposal
|
|
855
|
+
cards still show the command to run, with no approve button.
|
|
706
856
|
- **Answers stream in** as the agent writes them, under a **status line** that says
|
|
707
857
|
what it is doing: reading the cache with `owi_query`, reading live through toil with
|
|
708
858
|
`github issue list`, writing, and at the end how long it took. **Stop** cancels the
|
|
709
859
|
question on the server and keeps what had arrived. Claude and Copilot stream as they
|
|
710
860
|
write; Codex's SDK hands over its text a message at a time, so with Codex the status
|
|
711
861
|
line is what moves between messages.
|
|
712
|
-
- **The wording follows the theme**: the bar's
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
- **Analyze** briefs the
|
|
716
|
-
|
|
717
|
-
|
|
862
|
+
- **The wording follows the theme only where nothing depends on it**: with themed wording on, the bar's welcome and note are in each game
|
|
863
|
+
theme's voice and Plain stays neutral. The placeholder and the status line's source words read the same plain text in every theme, and so
|
|
864
|
+
do the starter questions.
|
|
865
|
+
- **Analyze** briefs the Toil project in one press (#494). It is the guided start's first
|
|
866
|
+
question, "Give me the full briefing", and still the command palette's Get a briefing and the
|
|
867
|
+
Analyses tab's button; the Ask bar has no button of its own for it. Its question comes from toil,
|
|
868
|
+
`toil projects analyze prompt <toilProject> --host toil-ui`: the standard method with
|
|
869
|
+
the Toil project's own lenses and focus (Tuning Analyze, above). It answers with a
|
|
718
870
|
briefing block, which the server lifts out of the answer and checks, every id in it
|
|
719
871
|
against what the agent's tools read: a recommendation, then the reasons, each item
|
|
720
872
|
with why it's there and the next step, then what changed, and anything the
|
|
721
|
-
|
|
873
|
+
Toil project's focus left out. The briefing, the item drawer, the chat and the analysis
|
|
722
874
|
page all lay it out, with the rest of the answer as **Evidence**, folded until you
|
|
723
875
|
open it. An answer with no briefing block is shown as it came, and says so. With a
|
|
724
|
-
toil that has no `
|
|
876
|
+
toil that has no `projects analyze prompt`, Analyze asks Toil UI's own question
|
|
725
877
|
instead, and the answer warns that it did. Each whole Analyze is kept in the
|
|
726
|
-
|
|
727
|
-
- **Citations are
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
878
|
+
Toil project's **Analyses** tab, and the answer links to it.
|
|
879
|
+
- **Citations are links in the text**: in every answer, each `[[id]]` is an ordinary link
|
|
880
|
+
(a short source name such as ADO or GH, the item's key and a cut title) to its page (a
|
|
881
|
+
pull request to its host). Hovering or focusing one shows the whole title, its source and
|
|
882
|
+
status, type, assignee, estimate, sprint and last update; the status is also in the
|
|
883
|
+
link's name for a screen reader. An id the
|
|
884
|
+
Toil project doesn't hold stays the bare id, marked, and the server's check above the
|
|
731
885
|
answer still names any id its tools never returned.
|
|
732
886
|
- **Each question carries the chat so far**: its last 8 questions and answers, each
|
|
733
887
|
answer cut to 1,500 characters. An item an earlier answer named is still checked
|
|
@@ -737,16 +891,17 @@ conversation stays, for the rest of the dossier's pages, until you reload.
|
|
|
737
891
|
from its next question, which carries the conversation so far; the default stays in
|
|
738
892
|
Settings. An adapter that can't answer is listed with the reason and **Install** or
|
|
739
893
|
**Fix**, never left out. Each answer names the adapter and model that wrote it.
|
|
740
|
-
- **
|
|
741
|
-
agent it was asked of, in `<data folder>/
|
|
742
|
-
|
|
743
|
-
opens on that
|
|
744
|
-
default from Settings,
|
|
745
|
-
the server trying the default and saying why it
|
|
746
|
-
by** say which: "last used on this
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
894
|
+
- **The chat remembers its agent for each Toil project** (#494). A whole answer, Analyze or an
|
|
895
|
+
ordinary question, records the agent it was asked of, in `<data folder>/toil-project-agents.json` (an adapter name per
|
|
896
|
+
Toil project name, Toil UI's own state, never in the Toil project file). The next time the chat
|
|
897
|
+
opens on that Toil project it starts on that agent if it can still answer, else on the
|
|
898
|
+
default from Settings, AI agent (Claude, GitHub Copilot or Codex), else the first agent
|
|
899
|
+
that is ready, else as before, with the server trying the default and saying why it
|
|
900
|
+
can't. A few words beside **Answered by** say which: "last used on this Toil project",
|
|
901
|
+
"your default", "your default can't run", "the first one ready" or
|
|
902
|
+
"picked for this chat". Picking another agent and asking updates the memory; a question that names no
|
|
903
|
+
agent, or an answer that fails, is stopped or comes back empty, doesn't. Renaming a Toil project moves its
|
|
904
|
+
memory, and a Toil project toil no longer has is forgotten on the next full sync. The sample
|
|
750
905
|
remembers nothing.
|
|
751
906
|
|
|
752
907
|
The chat answers with the agent your organization already approved, on the
|
|
@@ -759,16 +914,19 @@ dependency that is loaded only when it answers:
|
|
|
759
914
|
| GitHub Copilot | `@github/copilot-sdk` | `copilot` (the Copilot CLI) | your Copilot seat, through the CLI |
|
|
760
915
|
| Codex | `@openai/codex-sdk` | `codex` (the Codex CLI) | the CLI's ChatGPT sign-in or its own API key setup |
|
|
761
916
|
|
|
762
|
-
Choose the default under **Settings,
|
|
917
|
+
Choose the default under **Settings, AI agent**: the adapter, each adapter's model
|
|
763
918
|
(empty for its CLI's default), the CLI's path (empty to use the one on `PATH`) and,
|
|
764
919
|
for Claude, the endpoint. The choice is kept in `<data folder>/agent.json`, never in
|
|
765
920
|
toil's config, and has no field for a key: each SDK signs in the way its CLI does.
|
|
766
921
|
|
|
767
922
|
### Installing an adapter's SDK
|
|
768
923
|
|
|
769
|
-
**Settings,
|
|
770
|
-
|
|
771
|
-
|
|
924
|
+
**Settings, AI agent** opens on the steps to get going and each
|
|
925
|
+
AI agent with its state (Ready, Not set up yet in a calm tone, or Needs one more step with the
|
|
926
|
+
reason shown), and an **Install** button on each AI agent that isn't installed. Whether its SDK
|
|
927
|
+
is installed and at which version against the one Toil UI was tested with, which CLI it would
|
|
928
|
+
start, and anything worth knowing, are one step in under **Details for whoever sets it up**;
|
|
929
|
+
models, the CLI path and the endpoint are behind **Advanced**. A missing SDK has an **Install** button, which shows the one
|
|
772
930
|
command it will run, word for word, before anything runs:
|
|
773
931
|
|
|
774
932
|
```bash
|
|
@@ -776,7 +934,7 @@ npm install --global --prefix <the prefix Toil UI is installed in> --ignore-scri
|
|
|
776
934
|
```
|
|
777
935
|
|
|
778
936
|
Pressing **Install** runs it through the npm that came with your Node, with no shell and
|
|
779
|
-
your own npm config, so your organization's registry and proxy apply. npm's output
|
|
937
|
+
your own npm config, so your organization's registry and proxy apply. If the install fails, Toil UI offers a registry helper: on a press, it writes one `registry=<url>` line to the user npmrc (`ui/server/agents/npmrc.ts`) and you try again. The Copilot CLI's package installs along with its SDK (`docs/decisions/561-ai-helper-installs.md`). npm's output
|
|
780
938
|
streams into the dialog, and Toil UI then loads the SDK to prove it installed; a
|
|
781
939
|
failure shows npm's own message and the fix. **Copy command** is beside it, for a
|
|
782
940
|
machine where you'd rather run it yourself. This is the one thing Toil UI runs npm
|
|
@@ -816,12 +974,12 @@ for (docs/decisions/343-ask-up-front.md).
|
|
|
816
974
|
`TOIL_*` variables, `GITHUB_TOKEN` and CI tokens never reach it. Not found is a plain
|
|
817
975
|
error naming the CLI and the fix. On Windows a `.cmd` shim can't be started by the
|
|
818
976
|
SDKs, so point at the `.exe` (Copilot's npm shim is the exception, above).
|
|
819
|
-
- **Read-only tools, one
|
|
977
|
+
- **Read-only tools, one Toil project.** The agent gets `owi_query`, `owi_get`,
|
|
820
978
|
`owi_similar` (likely duplicates, scored as `toil util owi similar` scores them)
|
|
821
979
|
and `owi_history` over the cache, `pr_query`, `pr_get` and `pr_metrics` over its
|
|
822
980
|
pull requests (what each waits on, its flags, and flow figures by author kind with
|
|
823
981
|
their sample sizes), `people_list` and `person_get` (each person's plate as the
|
|
824
|
-
People view works it out, with the
|
|
982
|
+
People view works it out, with the Toil project read live through `projects show`, and
|
|
825
983
|
told it describes load, never performance), `readiness_list` and
|
|
826
984
|
`readiness_get` (each item's readiness verdict and its rows, as the Command Center
|
|
827
985
|
works them out), `proposal_fields` (a write command's input fields,
|
|
@@ -829,7 +987,7 @@ for (docs/decisions/343-ask-up-front.md).
|
|
|
829
987
|
with what it can't vouch for), `standup_report` (a range of days as the Stand-up folds
|
|
830
988
|
them, each line numbered), `proposal_fields` (a write command's input fields,
|
|
831
989
|
from toil's registry), and `toil mcp`'s read tools for live lookups, called through
|
|
832
|
-
toil's `execute()` with `readOnly: true`. The
|
|
990
|
+
toil's `execute()` with `readOnly: true`. The Toil project is fixed to the one on screen.
|
|
833
991
|
There is no write tool, and each SDK's own tools (shell, files, web, plugins, other
|
|
834
992
|
MCP servers) are switched off.
|
|
835
993
|
- **Citations are checked.** Every answer cites the work items and pull requests it
|
|
@@ -856,28 +1014,21 @@ for (docs/decisions/343-ask-up-front.md).
|
|
|
856
1014
|
be on the same drive. `toil-ui wipe` deletes this home with the cache, along with
|
|
857
1015
|
Codex's record of Toil UI's questions, and leaves your own `auth.json` alone.
|
|
858
1016
|
|
|
859
|
-
- **Your own instructions.** Under **Settings,
|
|
1017
|
+
- **Your own instructions.** Under **Settings, AI agent**, general instructions (for
|
|
860
1018
|
example "answer in British English") and a custom voice, each up to 4,000
|
|
861
1019
|
characters, kept in `agent.json` beside the adapter. They come after the rules in
|
|
862
1020
|
the prompt, and the rules win: they can't change the citations, the figures, the
|
|
863
1021
|
proposals or what the tools can do. **Show the full prompt** shows exactly what
|
|
864
1022
|
the agent is sent.
|
|
865
1023
|
|
|
866
|
-
With no adapter chosen, the chat says
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
dossier's open items likeliest to cover it, scored as `toil util owi similar` scores
|
|
875
|
-
them, each with why. Attach the work to one by naming its key in your branch and
|
|
876
|
-
commits, which writes nothing, or press **Ticket this** for proposals: a sub-task
|
|
877
|
-
under each match, and a new ticket on the dossier's tracker. They are proposal cards
|
|
878
|
-
like the chat's others, with the command line to run through toil's write gate, and
|
|
879
|
-
nothing is created until you run one. With no match, it says there is no likely
|
|
880
|
-
ticket and offers only a new one. It asks once per chat, and **Not now** hides it.
|
|
1024
|
+
With no adapter chosen, the chat says in plain words that no AI agent is set up and where
|
|
1025
|
+
an engineer sets one up (Settings, AI agent), with the three adapters and their packages one
|
|
1026
|
+
step in, behind **Details for whoever sets it up**; its switcher can still
|
|
1027
|
+
choose an installed one for that chat. The notice goes as soon as an AI agent can answer: the chat
|
|
1028
|
+
reads the AI agents again whenever the page moves, so installing on the Settings page needs no
|
|
1029
|
+
reload. An AI agent that is installed but can't start yet says so instead, with the reason one step
|
|
1030
|
+
in. `toil-ui --sample` keeps the scripted agent,
|
|
1031
|
+
which answers its starter questions, Analyze and the workflow jobs from the sample data (a job's answer says nothing was read and lists every check as unchecked).
|
|
881
1032
|
|
|
882
1033
|
### What the agent's models used
|
|
883
1034
|
|
|
@@ -891,23 +1042,23 @@ called):
|
|
|
891
1042
|
| 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 |
|
|
892
1043
|
| 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 |
|
|
893
1044
|
|
|
894
|
-
- **Under each answer**, one line per model: `2.1k in · 380 out · 14k cached · cache
|
|
1045
|
+
- **Under each answer**, one line in its folded line, "about $0.04 of usage (estimate)", or "(not billed on your plan)" on a Claude plan. The fold opens to one line per model: `2.1k in · 380 out · 14k cached · cache
|
|
895
1046
|
write not reported · ~$0.012 (SDK estimate)`. A figure the SDK didn't report reads
|
|
896
|
-
"not reported", never 0.
|
|
897
|
-
- **In the chat's
|
|
1047
|
+
"not reported", never 0. A cap notice stays in the open.
|
|
1048
|
+
- **In the chat's footer**, from the second answer (one answer's usage is the chat's), the chat's running total, split by model, and how full
|
|
898
1049
|
the last answer's context got, where the SDK says (Claude and Copilot; Codex's SDK
|
|
899
|
-
doesn't).
|
|
900
|
-
- **Settings,
|
|
901
|
-
30 days by day, adapter, model and
|
|
1050
|
+
doesn't). On a phone the chat's header is one line, "Answered by … · Change".
|
|
1051
|
+
- **Settings, Usage**, under its **More detail** (beside the count of toil's own commands): the last
|
|
1052
|
+
30 days by day, adapter, model and Toil project, the chats that used the most, and an
|
|
902
1053
|
**Export as CSV** download made in the page.
|
|
903
1054
|
- **One adding-up rule**, `addUp` in `src/model-usage.ts`, read by the server's caps,
|
|
904
1055
|
the footer, the heading and Settings: reports with one id are one report, merged to
|
|
905
1056
|
the highest of each figure (a running total), and different ids are summed.
|
|
906
1057
|
- **The ledger** is the cache's `usage` table, apart from everything a sync writes: a
|
|
907
|
-
sync's cleanup or a
|
|
1058
|
+
sync's cleanup or a Toil project leaving never lowers a total. It follows the cache's
|
|
908
1059
|
retention, `toil-ui wipe` clears it, and it is never sent anywhere.
|
|
909
1060
|
|
|
910
|
-
**Caps** are optional and off until you turn one on, under Settings,
|
|
1061
|
+
**Caps** are optional and off until you turn one on, under Settings, Usage: a
|
|
911
1062
|
per-chat and a per-day (UTC) cap for each adapter, in tokens, dollars (Claude's SDK
|
|
912
1063
|
estimate, or Codex from your rates) or Copilot premium requests. At 80% the answer
|
|
913
1064
|
says so; at 100% the question stops, naming the cap and how to raise it. Claude and
|
|
@@ -930,29 +1081,29 @@ you apply it.
|
|
|
930
1081
|
|---|---|---|
|
|
931
1082
|
| **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 |
|
|
932
1083
|
| **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 |
|
|
933
|
-
| **Implement** | Works in a copy of the
|
|
1084
|
+
| **Implement** | Works in a copy of the Toil project 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 |
|
|
934
1085
|
|
|
935
1086
|
- **Refine and investigate** get the same read-only tools as the chat (`owi_*`, `pr_*`,
|
|
936
1087
|
`proposal_fields` and toil's live reads), with no shell and no file writes.
|
|
937
1088
|
- **Implement runs on Codex only, for now.** Codex's own sandbox, `workspace-write`,
|
|
938
1089
|
holds the agent's commands and writes to the clone, with no network and none of the
|
|
939
1090
|
temp folders Codex adds by default, on Windows (its `unelevated` restricted-token sandbox), macOS and Linux. The clone is
|
|
940
|
-
`<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
|
|
941
|
-
repository needs a local path (`toil
|
|
1091
|
+
`<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 Toil project's
|
|
1092
|
+
repository needs a local path (`toil projects add-repo <toilProject> <folder>`). The agent stages its change and never commits, pushes or fetches; the
|
|
942
1093
|
staged diff is shown through toil's own `git status` and `git diff`, and the commit
|
|
943
1094
|
and push are a proposal of the exact git lines to run, since toil has no command
|
|
944
1095
|
that pushes.
|
|
945
1096
|
- **States**: `queued` (waiting for a free slot, or for a person to press Start),
|
|
946
1097
|
`working`, `needs you` (proposals or questions to review, or an item the agent
|
|
947
1098
|
thought was trying to instruct it), `done` and `failed`. The **Agents** sidebar beside
|
|
948
|
-
every
|
|
1099
|
+
every Toil project tab shows each assignment's state, mode, adapter, run time and what it
|
|
949
1100
|
used, and the People view shows each agent's assignments.
|
|
950
1101
|
- **From the Command Center**, "Start every ready item" assigns each slated item in
|
|
951
1102
|
implement mode, in order, on Codex (or the adapter chosen in Settings, when it can
|
|
952
|
-
implement), in the
|
|
1103
|
+
implement), in the Toil project's one repository with a local path, and says what it
|
|
953
1104
|
queued or why it started nothing.
|
|
954
1105
|
- **The tracker only queues.** An item labelled `agent:refine`, `agent:investigate` or
|
|
955
|
-
`agent:implement`, or assigned to one of the
|
|
1106
|
+
`agent:implement`, or assigned to one of the Toil project's agents (its `people` with
|
|
956
1107
|
`kind: agent`, which queues a refine), appears in the **Agent inbox** on the next
|
|
957
1108
|
read. It runs only when a person presses Start.
|
|
958
1109
|
- **Applying a proposal** runs its toil command, the one the server stored when the
|
|
@@ -964,12 +1115,12 @@ you apply it.
|
|
|
964
1115
|
- **Limits.** One assignment runs at a time and each has 20 minutes, both changeable
|
|
965
1116
|
in the sidebar's **Limits** (1 to 3 at once, 1 to 240 minutes), kept in
|
|
966
1117
|
`<data folder>/assignments.json`. An assignment is one chat to the usage caps under
|
|
967
|
-
**Settings,
|
|
1118
|
+
**Settings, Usage**, so a per-chat cap is a per-assignment cap. Either limit
|
|
968
1119
|
stops a run cleanly, saying which.
|
|
969
1120
|
- **The transcript** keeps the prompts, every tool call, the agent's text, the
|
|
970
1121
|
commands and file changes Codex reports, and each proposal and what came of it.
|
|
971
1122
|
Each assignment also records what it started on: the toil and Toil UI versions, the
|
|
972
|
-
adapter and model, the tools, and SHA-256 fingerprints of the
|
|
1123
|
+
adapter and model, the tools, and SHA-256 fingerprints of the Toil project, the item and
|
|
973
1124
|
the prompt, and the install fingerprint a later look holds it to (Stale sessions, below). Assignments are kept under the cache, in
|
|
974
1125
|
`<data folder>/cache/assignments/`, so a wipe deletes them.
|
|
975
1126
|
- **For programs on the same server**, `api/assignments` lists, assigns, starts,
|
|
@@ -979,7 +1130,7 @@ you apply it.
|
|
|
979
1130
|
## Stale sessions
|
|
980
1131
|
|
|
981
1132
|
An agent works from the instructions it got when it started. Upgrade toil, edit the
|
|
982
|
-
|
|
1133
|
+
Toil project or change your instructions under **Settings, AI agent**, and the chats and
|
|
983
1134
|
assignments already going are still on the old ones. Toil UI records what each one
|
|
984
1135
|
started on, says which have gone stale and why, and renews them on request.
|
|
985
1136
|
|
|
@@ -987,7 +1138,7 @@ started on, says which have gone stale and why, and renews them on request.
|
|
|
987
1138
|
run starts, keeps an install fingerprint: toil's and Toil UI's version and commit,
|
|
988
1139
|
one SHA-256 per toil area of the tools the agent was handed (Toil UI loads no skill
|
|
989
1140
|
page, so those tools are the toil instructions its agent reads), SHA-256 of the
|
|
990
|
-
|
|
1141
|
+
Toil project as `toil projects show` reads it, and SHA-256 of the prompts (the system
|
|
991
1142
|
prompt, the starters or the mode's task, and your own instructions and voice). The
|
|
992
1143
|
theme on screen isn't part of it. An assignment recorded before this has none, and
|
|
993
1144
|
is never called stale.
|
|
@@ -995,7 +1146,7 @@ started on, says which have gone stale and why, and renews them on request.
|
|
|
995
1146
|
assignment page compares what the session started on with the current fingerprint,
|
|
996
1147
|
whose builds are the ones on disk, read again only when their files change. The
|
|
997
1148
|
reason names what moved: "started on toil 0.1.0-alpha.3 · now alpha.4 · skills
|
|
998
|
-
changed: github ·
|
|
1149
|
+
changed: github · Toil project changed". A session's earlier turns aren't marked; only
|
|
999
1150
|
the instructions it started on are.
|
|
1000
1151
|
- **Where it shows.** A **Stale** badge with the reason on the chat (in the Ask bar and
|
|
1001
1152
|
the focused view), on each assignment in the Agents sidebar and on its page, and on the
|
|
@@ -1008,7 +1159,7 @@ started on, says which have gone stale and why, and renews them on request.
|
|
|
1008
1159
|
stays readable, marked as renewed. Renew never interrupts a turn: a chat that is
|
|
1009
1160
|
answering and a working assignment wait, and an assignment that needs you is
|
|
1010
1161
|
skipped until you've reviewed it.
|
|
1011
|
-
- **Renew all stale**, in the Agents sidebar, lists every stale session of the
|
|
1162
|
+
- **Renew all stale**, in the Agents sidebar, lists every stale session of the Toil project
|
|
1012
1163
|
first, the chat included, each saying whether it renews or why it's skipped, and
|
|
1013
1164
|
renews the rest with one press.
|
|
1014
1165
|
- **The server itself.** When toil or Toil UI on disk is newer than the running
|
|
@@ -1039,18 +1190,18 @@ call, its progress, or a state that didn't change never notifies.
|
|
|
1039
1190
|
assignments assigned, started or renewed here), and quiet hours, which hold every
|
|
1040
1191
|
notice while the title still counts.
|
|
1041
1192
|
- **Plain words.** Notices read the same in every theme: the theme's wording stays in
|
|
1042
|
-
the views.
|
|
1193
|
+
the views' flavour text.
|
|
1043
1194
|
- **Where it listens.** The server's `api/assignments/events?since=latest` stream,
|
|
1044
1195
|
which carries what a notice says with each event, and a minute's read of the
|
|
1045
|
-
|
|
1196
|
+
Toil project on screen for sessions gone stale.
|
|
1046
1197
|
|
|
1047
1198
|
### Notification history
|
|
1048
1199
|
|
|
1049
1200
|
The **bell** in the header (beside **Menu** on a narrow screen) counts the unread and
|
|
1050
1201
|
opens the last 50 things worth telling you, newest first: each change a notice carried
|
|
1051
1202
|
(needs you, done, failed, stopped at a usage cap, gone stale), each sync's result, from
|
|
1052
|
-
the Sync panel, with the
|
|
1053
|
-
to what it's about: the assignment, the
|
|
1203
|
+
the Sync panel, with the Toil project that failed, and when each happened. Every entry links
|
|
1204
|
+
to what it's about: the assignment, the Toil project, or the Toil projects view. **Mark all read**
|
|
1054
1205
|
clears the count and keeps the entries. The bell keeps a change that quiet hours held
|
|
1055
1206
|
back, and one whose notice you dismissed; which changes reach it is the notification
|
|
1056
1207
|
settings' choice. It's kept in this browser's `localStorage`, shared by its tabs (with one
|
|
@@ -1061,8 +1212,8 @@ the worklog's facts, never from the bell.
|
|
|
1061
1212
|
|
|
1062
1213
|
Eight built-in themes: Plain, Crate (the default), Harvest, Starship, Realm, Sprawl,
|
|
1063
1214
|
Frontier and Overworld. Pick
|
|
1064
|
-
one from the header, or under **Settings,
|
|
1065
|
-
it goes,
|
|
1215
|
+
one from the header, or under **Settings, Appearance**, where two checkboxes say how far
|
|
1216
|
+
it goes, wording on and the agent voice off by default (#552, #561):
|
|
1066
1217
|
|
|
1067
1218
|
- **Themed wording:** the theme's own lede, eyebrows, dashboard notes, empty
|
|
1068
1219
|
states and loading lines, and its names for a sprint, a board or an epic beside
|
|
@@ -1073,19 +1224,16 @@ it goes, both on by default:
|
|
|
1073
1224
|
dungeon master in Realm, a laconic netrunner in Sprawl, a dry telegraph operator
|
|
1074
1225
|
in Frontier, an old sage in a cave in Overworld. It changes phrasing only.
|
|
1075
1226
|
|
|
1076
|
-
Every theme has a light and a dark scheme. **
|
|
1227
|
+
Every theme has a light and a dark scheme. **Light or dark**, in Settings, Appearance or the
|
|
1077
1228
|
command palette, picks one; System, the default, follows your operating system.
|
|
1078
1229
|
|
|
1079
|
-
|
|
1080
|
-
theme on its own: off, that theme's particles are gone entirely, while its other
|
|
1081
|
-
motion keeps following **Reduce motion and effects** (and the operating system's
|
|
1082
|
-
reduced-motion setting, which stops everything).
|
|
1230
|
+
**Motion**, one select under Settings, Appearance, is Full, Subtle or Off: Off is what reduced motion was, and Subtle also turns the theme's particles off. The operating system's reduced-motion setting stops everything.
|
|
1083
1231
|
|
|
1084
1232
|
Crate, Harvest, Starship, Realm, Sprawl, Frontier and Overworld also have **theme moments**: a launch splash while the first read
|
|
1085
1233
|
runs, their own loading screens with the real progress and a rotating line of their own,
|
|
1086
|
-
an entrance as a
|
|
1234
|
+
an entrance as a Toil project opens, a transition between its tabs, and a short moment when a
|
|
1087
1235
|
sync brings an item done, a build passed or failed, a blocker cleared, a pull request
|
|
1088
|
-
merged, or a sprint's end. **
|
|
1236
|
+
merged, or a sprint's end. **Motion**, under Settings, Appearance, plays them in full,
|
|
1089
1237
|
subtly or not at all, and is off whenever reduced motion is asked for. Every loading
|
|
1090
1238
|
screen also carries a **toil tip**, one line with a Read more link, which **Toil tips on
|
|
1091
1239
|
loading screens** turns off. Waits under 300 ms show no loading screen at all.
|
|
@@ -1101,19 +1249,47 @@ left in the data folder by an earlier alpha is not read, and Toil UI says so whe
|
|
|
1101
1249
|
starts. [Themes](https://imagile-dev.github.io/toil/docs/themes/) has the whole
|
|
1102
1250
|
story, the composed prompt included.
|
|
1103
1251
|
|
|
1104
|
-
## The
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
|
|
1108
|
-
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
|
|
1113
|
-
|
|
1114
|
-
|
|
1115
|
-
|
|
1116
|
-
-
|
|
1252
|
+
## The checks on the door
|
|
1253
|
+
|
|
1254
|
+
The server binds loopback only (`127.0.0.1` or `::1`; any other `--host` is refused).
|
|
1255
|
+
A web page open in your browser can still send requests to a port on `127.0.0.1`, by
|
|
1256
|
+
posting a form or by rebinding its own domain to loopback, so every request passes
|
|
1257
|
+
these checks, before a route runs:
|
|
1258
|
+
|
|
1259
|
+
- **A cookie.** The first time `toil-ui` runs it makes 32 random bytes in
|
|
1260
|
+
`machine-secret` in its data folder (`~/.toil-ui/`), mode 0600 on macOS and Linux, and
|
|
1261
|
+
reads the same file on every later start. It never leaves the machine and is never
|
|
1262
|
+
printed, logged or sent. When a browser navigates to the page itself
|
|
1263
|
+
(`Sec-Fetch-Dest: document`, `Sec-Fetch-Site` none or same-origin), the server sets
|
|
1264
|
+
the `toil-ui` cookie: a random id, the time, and an HMAC-SHA256 of both with the
|
|
1265
|
+
secret; `HttpOnly` (no script can read it), `SameSite=Strict`, 30 days. It can't be
|
|
1266
|
+
`Secure`, which a browser won't keep over plain `http`. Every API call needs a valid
|
|
1267
|
+
one, compared in constant time. A page on another site can't have it sent with a
|
|
1268
|
+
request, and a cross-site navigation is refused the cookie.
|
|
1269
|
+
- **The peer and the Host header.** The connection must come from loopback, and the
|
|
1270
|
+
`Host` must be `127.0.0.1:<port>`, `localhost:<port>` or `[::1]:<port>`.
|
|
1271
|
+
- **Origin and Fetch Metadata.** An API call whose `Origin` isn't this server's own, or
|
|
1272
|
+
whose `Sec-Fetch-Site` isn't `same-origin`, is refused, and a POST must be
|
|
1273
|
+
`application/json`, which a plain cross-site form cannot send. With the cookie's
|
|
1274
|
+
`SameSite=Strict`, that is why there is no CSRF header.
|
|
1275
|
+
- **No CORS.** No `Access-Control-*` header is ever sent and `OPTIONS` is refused.
|
|
1276
|
+
|
|
1277
|
+
A program that isn't a browser gets the cookie the way a browser does: `GET /` from
|
|
1278
|
+
this machine with `Sec-Fetch-Dest: document` and `Sec-Fetch-Site: none`, then send the
|
|
1279
|
+
`toil-ui=…` value from `Set-Cookie` back in `Cookie` (`ui/scripts/smoke.mjs` does).
|
|
1280
|
+
|
|
1281
|
+
What this does not do: **any program running on this machine as you can read
|
|
1282
|
+
`machine-secret`, or ask for the page as a browser would and get a cookie.** On a
|
|
1283
|
+
shared machine, another account can reach the port too, unless the operating system
|
|
1284
|
+
restricts loopback between users; the secret file itself stays yours. Cookies are not
|
|
1285
|
+
scoped to a port, so another local web server on `127.0.0.1` is sent this cookie
|
|
1286
|
+
too. On Windows the file takes the permissions of your profile folder (restricting it
|
|
1287
|
+
would need `icacls`, a program toil doesn't add). The server runs toil with your own
|
|
1288
|
+
connections, so run `toil-ui` only where you would run a database client. Writes still
|
|
1289
|
+
need the connection's `writes` setting and the Settings page's own confirmations, and
|
|
1290
|
+
secrets are still entered only in Settings, going to the OS credential store.
|
|
1291
|
+
|
|
1292
|
+
**No network but toil's.** It talks to the hosts in your toil connections, and
|
|
1117
1293
|
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.
|
|
1118
1294
|
|
|
1119
1295
|
## Run against a real repository
|
|
@@ -1136,40 +1312,40 @@ GitHub CLI signed in (`gh auth login`), or `TOIL_GITHUB_TOKEN` set in the shell.
|
|
|
1136
1312
|
- **The token** comes from `gh auth token` each time it starts and goes only into
|
|
1137
1313
|
Toil UI's environment, as `TOIL_GITHUB_TOKEN`. It's never written to a file or
|
|
1138
1314
|
printed. `GITHUB_TOKEN` and other `TOIL_*` variables in your shell are left out.
|
|
1139
|
-
- **The
|
|
1140
|
-
`toil
|
|
1315
|
+
- **The Toil projects**, made with `toil projects init` and `link` and checked with
|
|
1316
|
+
`toil projects check`: one for `--repo`, and `toil-self` for the public
|
|
1141
1317
|
`imagile-dev/toil` unless `--no-self`. `--repo` defaults to
|
|
1142
1318
|
`imagile-dev/toil-sandbox` (as `sandbox`), which is private to Imagile's
|
|
1143
1319
|
maintainers; anyone else passes their own repository, or seeds a sandbox of their
|
|
1144
1320
|
own (below).
|
|
1145
1321
|
- **toil from this checkout.** Each start builds toil from the clone into
|
|
1146
1322
|
`.scratch/toil` (`npm run build` with `TOIL_BUILD_DIR`, a few seconds), and both the
|
|
1147
|
-
|
|
1323
|
+
Toil project setup and Toil UI run on that build, not on the published toil
|
|
1148
1324
|
`ui/package.json` pins. Toil UI is started with `node --import
|
|
1149
1325
|
ui/scripts/local-toil-hook.mjs`, which resolves `@imagile-dev/toil/api` to
|
|
1150
1326
|
`.scratch/toil/api.js` and says so on stderr. So a command `ui/` calls before its
|
|
1151
1327
|
release works here. The committed `dist/` and `node_modules` are left alone, and a
|
|
1152
1328
|
plain `node ui/dist/server/toil-ui.js` still runs on the pinned toil.
|
|
1153
1329
|
- **Then** it starts `ui/dist/server/toil-ui.js` on loopback and prints its URL.
|
|
1154
|
-
Press **Sync now**, then open a
|
|
1330
|
+
Press **Sync now**, then open a Toil project. `--port <n>` fixes the port, and
|
|
1155
1331
|
`--home <dir>` uses another folder.
|
|
1156
1332
|
- **Ask with Codex.** Install the SDK in the clone without saving it
|
|
1157
1333
|
(`npm install --no-save --ignore-scripts @openai/codex-sdk@0.160.0`), then choose
|
|
1158
|
-
Codex under **Settings,
|
|
1334
|
+
Codex under **Settings, AI agent**. The script points `CODEX_HOME` at your real
|
|
1159
1335
|
`~/.codex`, which is where Toil UI finds the `auth.json` it links into its own
|
|
1160
1336
|
Codex home.
|
|
1161
1337
|
- **Ask with GitHub Copilot, on a cheap model.** Install `@github/copilot-sdk@1.0.16`
|
|
1162
|
-
the same way (or press **Install** under **Settings,
|
|
1338
|
+
the same way (or press **Install** under **Settings, AI agent**). The Copilot CLI found
|
|
1163
1339
|
its own sign-in from the scratch home in our runs; if it says it isn't signed in, run
|
|
1164
1340
|
`copilot` once on its own. Then pick the model: Copilot lists the models your
|
|
1165
1341
|
account can use, each with its premium-request multiplier (`/model` in the CLI, or
|
|
1166
1342
|
the SDK's `listModels()`). Choose the lowest, ideally one at 0×; otherwise the
|
|
1167
1343
|
cheapest multiplier, such as `mai-code-1.1-flash` at 0.25×, never a premium model.
|
|
1168
|
-
Type its id as Copilot's model under **Settings,
|
|
1344
|
+
Type its id as Copilot's model under **Settings, AI agent**, and check the model each
|
|
1169
1345
|
answer names and the premium requests under it.
|
|
1170
1346
|
- **Ask with Claude, on Haiku.** Install `@anthropic-ai/claude-agent-sdk@0.3.289` and
|
|
1171
1347
|
`zod@4.6.5` the same way, and type `haiku` (or `claude-haiku-5-5`) as Claude's
|
|
1172
|
-
model under **Settings,
|
|
1348
|
+
model under **Settings, AI agent**; empty would be Claude Code's own default, which
|
|
1173
1349
|
may be Opus. Claude Code keeps its sign-in in `~/.claude`, which the scratch home
|
|
1174
1350
|
hides, and refreshing it from there would rewrite your credentials file, so the
|
|
1175
1351
|
script only reads it: a `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` in the
|
|
@@ -1179,6 +1355,12 @@ GitHub CLI signed in (`gh auth login`), or `TOIL_GITHUB_TOKEN` set in the shell.
|
|
|
1179
1355
|
script says so: run `claude` once in a terminal, which refreshes its own sign-in,
|
|
1180
1356
|
or set a token from `claude setup-token`, and start the script again.
|
|
1181
1357
|
|
|
1358
|
+
To run the same build against your own `~/.toil` instead (your connections and
|
|
1359
|
+
Toil projects as they are, changed only by what you save in Settings, with Toil UI's own
|
|
1360
|
+
data in `.scratch/toil-ui`), run `node ui/scripts/dev-mine.mjs`.
|
|
1361
|
+
That's the way to try unreleased changes on real work (`skills/toil/install.md`,
|
|
1362
|
+
Trying unreleased changes).
|
|
1363
|
+
|
|
1182
1364
|
## Verify before you open a PR: `npm run verify:ui`
|
|
1183
1365
|
|
|
1184
1366
|
One command checks Toil UI the way a reviewer would, and writes what it found to
|
|
@@ -1196,24 +1378,27 @@ npm run verify:ui -- --no-build --starter standup
|
|
|
1196
1378
|
`.scratch/toil`, which Toil UI runs on, as `dev-real.mjs` does (above). The report's
|
|
1197
1379
|
header and its **Toil** row name that toil: its version, the commit it was built
|
|
1198
1380
|
at, and whether `src/` had uncommitted changes. The run fails if Toil UI didn't
|
|
1199
|
-
resolve `@imagile-dev/toil/api` to it. It also
|
|
1381
|
+
resolve `@imagile-dev/toil/api` to it. It also checks that the toil `npm ci`
|
|
1200
1382
|
installs is the one `ui/package.json` pins (`npm run check:lockfile -w ui`), which
|
|
1201
|
-
is what the published package runs on.
|
|
1383
|
+
is what the published package runs on. Right after a release, until its lockfile PR
|
|
1384
|
+
merges, that check passes with a warning naming the previous toil, and the
|
|
1385
|
+
**Pinned toil** row carries it.
|
|
1202
1386
|
- **Sample data:** `toil-ui --sample` in a throwaway home, every view through the
|
|
1203
1387
|
layout check (`scripts/layout-check.mjs`) in every theme and scheme at 375, 768 and
|
|
1204
|
-
1440px. On each
|
|
1388
|
+
1440px. On each Toil project's dashboard it also drags a board card to the next column
|
|
1205
1389
|
with real input, a mouse and at 375px a finger, and fails when the card doesn't
|
|
1206
1390
|
follow the pointer or the dropped move doesn't show in the target column. It needs
|
|
1207
1391
|
only a browser, so it runs anywhere, CI included.
|
|
1208
|
-
- **First run:** `toil-ui` on an empty home, with no connections, no
|
|
1209
|
-
`TOIL_*` variable from your shell, through the same check: its
|
|
1392
|
+
- **First run:** `toil-ui` on an empty home, with no connections, no Toil projects and no
|
|
1393
|
+
`TOIL_*` variable from your shell, through the same check: its Toil projects view must
|
|
1210
1394
|
show the three-step checklist, and the palette and the shortcuts sheet open over it.
|
|
1211
1395
|
- **Real data:** the home `dev-real.mjs` sets up, made fresh at
|
|
1212
1396
|
`.scratch/verify/home`, on `imagile-dev/toil-sandbox` with the token from `gh auth
|
|
1213
|
-
token` in Toil UI's environment only. It syncs the `sandbox`
|
|
1214
|
-
same check over the home page, the
|
|
1215
|
-
except that its header may fold into the Menu at 1440px, since a real
|
|
1216
|
-
and links can genuinely fill the row
|
|
1397
|
+
token` in Toil UI's environment only. It syncs the `sandbox` Toil project and runs the
|
|
1398
|
+
same check over the home page, the Toil project and its Board and Dependencies tabs, its worklog and stand-up, one of its items and the settings pages,
|
|
1399
|
+
except that its header may fold into the Menu at 1440px, since a real Toil project's name
|
|
1400
|
+
and links can genuinely fill the row, and its Usage page's failed-command lines are
|
|
1401
|
+
opened on the sample only, since real data may have none.
|
|
1217
1402
|
Without a GitHub sign-in it skips this part and says so; nothing else depends on it.
|
|
1218
1403
|
- **`--ask`** asks Codex one starter question (`hygiene` unless `--starter <id>`) and
|
|
1219
1404
|
checks that an answer arrived, that the server verified every `[[id]]` it cites,
|
|
@@ -1221,7 +1406,7 @@ npm run verify:ui -- --no-build --starter standup
|
|
|
1221
1406
|
run), and that `codex mcp list` in Toil UI's Codex home shows only `toil_ui`. Then it
|
|
1222
1407
|
asks Analyze as the chat's second question, and checks the history of analyses
|
|
1223
1408
|
(#395): that Analyze was kept with its briefing (a recommendation, and its first
|
|
1224
|
-
three reasons as the history's issues); then it changes the
|
|
1409
|
+
three reasons as the history's issues); then it changes the Toil project's WIP limit in the scratch home (`toil projects
|
|
1225
1410
|
wip-limit --replace`), asks Analyze again, checks the history lists both, newest
|
|
1226
1411
|
first, the second compared with the first, and puts the Overview, the Analyses tab
|
|
1227
1412
|
and the second analysis opened through the layout check, shot. It needs the Codex CLI signed in and the
|
|
@@ -1236,7 +1421,7 @@ npm run verify:ui -- --no-build --starter standup
|
|
|
1236
1421
|
- **It stops** every server and browser it started, and exits 1 on any problem.
|
|
1237
1422
|
|
|
1238
1423
|
`--source ado` runs the real-data part against an Azure DevOps Services board
|
|
1239
|
-
instead (the `ado-board`
|
|
1424
|
+
instead (the `ado-board` Toil project, as `dev-real.mjs --source ado` makes it below),
|
|
1240
1425
|
with `TOIL_ADO_BASE_URL`, `TOIL_ADO_PAT` and `--project <name>` (else
|
|
1241
1426
|
`TOIL_ADO_PROJECT`); without them it skips that part and says why. Each source is
|
|
1242
1427
|
one entry in `SOURCES` in `scripts/verify.mjs`. Set `CHROME_PATH` if the browser it finds doesn't draw headless; Playwright's
|
|
@@ -1269,7 +1454,7 @@ toil's `github` area doesn't read.
|
|
|
1269
1454
|
### An Azure DevOps Services board
|
|
1270
1455
|
|
|
1271
1456
|
`--source ado` runs the same way against an Azure DevOps Services project, through
|
|
1272
|
-
toil's `ado` area on a Services connection, with a
|
|
1457
|
+
toil's `ado` area on a Services connection, with a Toil project named `ado-board`:
|
|
1273
1458
|
|
|
1274
1459
|
```bash
|
|
1275
1460
|
node ui/scripts/dev-real.mjs --source ado --project "<project>"
|
|
@@ -1280,7 +1465,7 @@ It needs `TOIL_ADO_BASE_URL` (`https://dev.azure.com/<organization>`) and
|
|
|
1280
1465
|
shell. They go into Toil UI's environment only: toil makes its `ado` (deployment cloud)
|
|
1281
1466
|
connection from them, with writes off, and nothing about the organization is
|
|
1282
1467
|
written to the config file. `--project`, or `TOIL_ADO_PROJECT`, names the
|
|
1283
|
-
project; the
|
|
1468
|
+
project; the Toil project in the scratch home holds it. The Toil project names no repository,
|
|
1284
1469
|
so no pull requests are read; add `repo` to its `ado` section for them.
|
|
1285
1470
|
|
|
1286
1471
|
To fill a board with made-up work, `ui/scripts/ado-seed/` seeds one from Open Work
|
|
@@ -1353,7 +1538,7 @@ npm run screens:sheet -w ui -- --theme realm --width 768 --motion full
|
|
|
1353
1538
|
`ui/.moments/sheets/<theme>-<width>-<motion>.png`, ready to attach to the PR, with its
|
|
1354
1539
|
frames and an HTML copy in a folder beside it. A sheet shows the splash arriving, held and
|
|
1355
1540
|
handing over; the loading screen as its loops turn; each event moment the theme declares
|
|
1356
|
-
coming in, held and going out, cropped to the card; the
|
|
1541
|
+
coming in, held and going out, cropped to the card; the Toil project entrance; and a change of
|
|
1357
1542
|
tab. Every frame is a still: the engine's animations are caught paused as they start and
|
|
1358
1543
|
stepped by hand, so a sheet is the same on every run. `--width` and `--motion` repeat, and
|
|
1359
1544
|
replace the defaults.
|