dsh-artel 0.1.0 → 0.2.0

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/CHANGELOG.md CHANGED
@@ -4,6 +4,57 @@ All notable changes to this project are documented here. The format follows
4
4
  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses
5
5
  [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
6
 
7
+ ## [0.2.0] — 2026-11-19
8
+
9
+ ### Added
10
+
11
+ - In-chat launcher: an **Artel** button in the chat composer tool row (next to **+**) opens a panel over
12
+ the current conversation. The chat stays mounted underneath, and a dot on the button marks a run in
13
+ progress.
14
+ - Panel with a **Sessions** rail: every Artel run of the chat session, grouped by project, with a status
15
+ dot, the mode/counts/phase meta line, the active run highlighted, **+ New Artel** and session
16
+ counters.
17
+ - New-run form in the panel: project and mode in the heading, a task field, the Solo/Swarm selector with
18
+ hints, the **Go →** primary button (Ctrl+Enter) and a note that the run works in an isolated copy.
19
+ - Run page in the panel: task, mode tag, status pill and phase line, a two-step **Stop** confirmation,
20
+ and a feed of full agent replies (avatar, name, role, time, markdown), grouped tool calls, and
21
+ status, plan, user, peer, collision and error rows.
22
+ - Message composer on the run page: "Write to the agents…", a recipient picker (**Everyone** or a
23
+ specific agent) and Ctrl+Enter; a message also wakes a waiting or stopped run.
24
+ - **Changes** card on the run page: the run's file list with added/removed line counts, lazy diffs,
25
+ all-files **Apply** and **Discard** with inline confirmations, and applied/discarded/skipped states.
26
+ - The panel works on a blank chat session too: the profile's default working directory is used, so a
27
+ run can be started before the first message.
28
+
29
+ ### Changed
30
+
31
+ - Agents run unattended: Artel sets their approval policy to `never` and inherits the sandbox mode of
32
+ the parent chat session, so a run no longer stalls on an approval prompt.
33
+ - **Apply** writes every changed file; the per-file tick list and the "Apply N files" button are gone.
34
+ A conflict with a file changed in the project still rejects the whole apply.
35
+ - The run's diff count and status are visible in its header and in the rail while and after the agents
36
+ work.
37
+ - After **Apply** the isolated copy is deleted right away, like **Discard** already did; a run whose
38
+ copy is gone reports no changed files.
39
+ - The user guide and README now describe the in-chat launcher and the panel instead of the sidebar tab,
40
+ and ship screenshots of the new UI.
41
+
42
+ ### Removed
43
+
44
+ - The right-sidebar Artel tab and its standalone page. The client half now registers a single launcher
45
+ in the chat composer tool row and renders the panel as an overlay over the conversation.
46
+ - Per-file selection in the changes review, the "Open conversation" action and the session-header
47
+ status list.
48
+
49
+ ### Fixed
50
+
51
+ - `changeCount` is recalculated when a run is interrupted or fails, so the review card and the rail show
52
+ the real number of changed files instead of zero.
53
+ - The review card loads the run's changes when the run enters review, so the card no longer depends on
54
+ the Host-reported count to become visible.
55
+ - A Swarm planning turn no longer stalls when an agent calls `wait_agent`; the planning prompt tells
56
+ agents to announce their files and end the turn instead.
57
+
7
58
  ## [0.1.0] — 2026-11-17
8
59
 
9
60
  First public release.
@@ -37,4 +88,5 @@ First public release.
37
88
  - No build step: the host half is plain ESM and the client half is hand-written
38
89
  `React.createElement`.
39
90
 
91
+ [0.2.0]: https://github.com/ksolodev/dsh-artel/compare/v0.1.0...v0.2.0
40
92
  [0.1.0]: https://github.com/ksolodev/dsh-artel/releases/tag/v0.1.0
package/README.md CHANGED
@@ -9,8 +9,12 @@
9
9
  Run a development task in an isolated copy of your project, watch the work as it happens, review the
10
10
  diff line by line, then apply it yourself.
11
11
 
12
- Artel is a DeepSeek Harness plugin. It adds an **Artel** tab to the right sidebar of a chat session.
13
- The chat session's working directory is the project; Artel never touches it until you press Apply.
12
+ Artel is a DeepSeek Harness plugin. It adds an **Artel** icon button to the chat composer tool row, next
13
+ to **+**. The button covers the current chat with a panel: the session rail of Artel runs on the left,
14
+ and either the new-run form or the live run on the right. The chat session's working directory is the
15
+ project; Artel never touches it until you apply.
16
+
17
+ ![Artel opens over the chat](docs/artel-in-chat/screens/hero.png)
14
18
 
15
19
  ## Install
16
20
 
@@ -22,11 +26,11 @@ Artel is a DSH bundle: it installs with the standard plugin CLI and needs no bui
22
26
  dsh plugin --profile <profile> add dsh-artel
23
27
  ```
24
28
 
25
- **From the release tarball** — download `dsh-artel-0.1.0.tgz` from the
26
- [v0.1.0 release](https://github.com/ksolodev/dsh-artel/releases/tag/v0.1.0), then:
29
+ **From the release tarball** — download `dsh-artel.tgz` from the
30
+ [latest release](https://github.com/ksolodev/dsh-artel/releases/latest), then:
27
31
 
28
32
  ```sh
29
- dsh plugin --profile <profile> add C:/path/to/dsh-artel-0.1.0.tgz
33
+ dsh plugin --profile <profile> add C:/path/to/dsh-artel.tgz
30
34
  ```
31
35
 
32
36
  **From a checkout** — point the plugin CLI at the directory:
@@ -40,9 +44,9 @@ host reload. In the desktop app you can also use **Settings → Plugins → Inst
40
44
  the `.tgz` or the checkout folder.
41
45
 
42
46
  After installing, restart DeepSeek Harness (or reload the page, which recomposes the client boot
43
- graph), open a chat session that has a project directory, and click **Artel** in the session header.
44
- The plugin's page is served over a loopback-only HTTP API, so the plugin and the host must run on the
45
- same machine.
47
+ graph), open a chat session that has a project directory, and click **Artel** in the composer tool row.
48
+ The plugin's host half talks to the client over a loopback-only HTTP API, so the plugin and the host
49
+ must run on the same machine.
46
50
 
47
51
  ## How it works
48
52
 
@@ -51,12 +55,15 @@ same machine.
51
55
  touched.
52
56
  2. **Agents** — one agent works in the copy in **Solo**; three agents share one copy and one agent
53
57
  tree in **Swarm**, so they can message each other with `send_message`/`list_agents`. The first
54
- Swarm turn is planning only: the agents divide the files and announce who owns what.
55
- 3. **Diff** — when every agent goes idle, Artel stops the run and shows every changed file with added
56
- and removed line counts and a line-by-line diff.
57
- 4. **Apply** — you tick the files you want and press **Apply**. Before writing, Artel checks each file
58
- against the state it had when the run started; a file you edited during the run is reported and
59
- never overwritten. **Discard** deletes the copy and changes nothing.
58
+ Swarm turn is planning only: the agents divide the files and announce who owns what. The agents run
59
+ unattended: Artel gives them the approval policy `never` and inherits the sandbox mode of the chat
60
+ session, so a run never stalls on an approval prompt.
61
+ 3. **Diff** — when every agent goes idle, Artel stops the run and fills the **Changes** card on the run
62
+ page: every changed file with added and removed line counts and a line-by-line diff.
63
+ 4. **Apply** — you press **Apply** and confirm. It writes every changed file into the project. Before
64
+ writing, Artel checks each file against the state it had when the run started; a file you edited
65
+ during the run is reported and the whole apply is refused, so nothing is half-written. **Discard**
66
+ deletes the copy and changes nothing.
60
67
 
61
68
  ## Two ways to run a task
62
69
 
@@ -79,28 +86,37 @@ Use Swarm when the work splits into pieces that do not meet in the same files.
79
86
 
80
87
  ## Review and apply
81
88
 
82
- While a run is active, the Artel tab shows the live feed of every agent. You can write to an agent at
83
- any time without waiting for it to finish; in Swarm you can also address one agent only.
89
+ While a run is active, the run page shows the live feed of every agent: full replies with the avatar,
90
+ name, role and time, grouped tool calls, and separate rows for status, plans, your messages,
91
+ agent-to-agent messages, edit collisions and errors. You can write to the agents at any time without
92
+ waiting for them to finish (Ctrl+Enter sends); address everyone or one specific agent.
93
+
94
+ ![The run page](docs/artel-in-chat/screens/run.png)
84
95
 
85
96
  When every agent is idle, Artel stops and waits for you:
86
97
 
87
98
  - **Changes** lists every changed file with added and removed line counts. Open a file to see the diff.
88
- - Untick the files you do not want.
89
- - **Apply N files** copies the selected files into your project. A file that you edited during the run
90
- is never overwritten: Artel reports it and leaves it alone.
91
- - **Discard** deletes the copy. Nothing was applied.
99
+ - **Apply** asks for confirmation and writes every changed file into your project. A file that you
100
+ edited during the run is never overwritten: Artel reports it and refuses the whole apply, so you can
101
+ discard and run again.
102
+ - **Discard** asks for confirmation, deletes the copy and changes nothing.
92
103
 
93
- The copy lives outside the project, under your DSH home directory, and is removed when the run is
94
- discarded or when it gets older than `keepCopiesHours`.
104
+ ![The Changes card](docs/artel-in-chat/screens/changes.png)
105
+
106
+ The copy lives outside the project, under your DSH home directory. It is deleted as soon as you apply
107
+ or discard the run, so reviewed copies do not pile up on disk.
95
108
 
96
109
  ## Open it
97
110
 
98
111
  1. Open a chat session that has a project directory.
99
- 2. Click the **Artel** button in the session header, or open it from the right sidebar guide.
100
- 3. Pick Solo or Swarm, write the task, press Start.
101
-
102
- Each agent works in the copy as its working directory. The first agent of a Swarm run is an ordinary
103
- DSH session, so you can open its full conversation from the Agents section of the Artel tab; the other
112
+ 2. Click the **Artel** button in the chat composer tool row (next to **+**). While a run in the session
113
+ is active, the button shows a dot.
114
+ 3. Pick Solo or Swarm, write the task, press **Go →** (or Ctrl+Enter). **← Chat** or Esc returns to the
115
+ chat; the chat itself is not replaced.
116
+
117
+ The panel belongs to the chat session: the **Sessions** rail lists every run of the session, grouped by
118
+ project, with the active one highlighted, and **+ New Artel** returns to the form. Each agent works in
119
+ the copy as its working directory. The first agent of a Swarm run is an ordinary DSH session, the other
104
120
  two are that session's subagents, live in the same agent tree, and are not listed in the sidebar as
105
121
  separate chats. Solo agents are ordinary sessions as well, titled `Artel · <agent> — <task>`; archive
106
122
  or delete those sessions when you no longer need them.
@@ -110,8 +126,8 @@ or delete those sessions when you no longer need them.
110
126
  The plugin was renamed to Artel (the npm name `dsh-forge` belongs to an unrelated placeholder package).
111
127
  On its first start the Host moves the previous data root from `<DSH home>/forge/<profile>` to
112
128
  `<DSH home>/artel/<profile>`, so existing run records, feeds and copies stay available. The plugin id
113
- changed with the name, so an already open Forge tab does not restore — open the **Artel** tab once after
114
- the restart.
129
+ changed with the name: an open Forge page does not restore Artel, so restart DeepSeek Harness and open
130
+ Artel once from the chat composer.
115
131
 
116
132
  ## Requirements
117
133
 
@@ -126,8 +142,8 @@ All values are optional; set them in the bundle's plugin configuration.
126
142
  | Key | Default | Meaning |
127
143
  | --- | --- | --- |
128
144
  | `swarmAgentCount` | `3` | Agents per Swarm run (2–8). |
129
- | `maxRunsPerSession` | `10` | Runs kept per session. Older runs are dropped. |
130
- | `keepCopiesHours` | `72` | Copies older than this are deleted on startup. `0` disables the sweep. |
145
+ | `maxRunsPerSession` | `10` | Finished runs kept per session; the oldest are dropped with their copies. Runs waiting for you stay. |
146
+ | `keepCopiesHours` | `72` | Retention window for run copies, in hours (0 disables). The current startup sweep removes copies of applied and discarded runs regardless of age. |
131
147
  | `diffContext` | `3` | Context lines around each diff hunk (0–12). |
132
148
  | `idleGraceMs` | `1200` | How long Artel waits for a possible agent-to-agent message before it calls the run idle (0–10000). |
133
149
  | `excludeGlobs` | `[]` | Extra paths never copied, diffed, or applied. |
@@ -138,13 +154,16 @@ All values are optional; set them in the bundle's plugin configuration.
138
154
 
139
155
  - The project is copied as files, not through Git. Git metadata is not copied, and Artel does not
140
156
  require Git to be installed.
141
- - A copy holds up to 20,000 files, 32 MB per file and 512 MB in total. Larger projects are refused
142
- with an error instead of a partial copy.
157
+ - A copy is limited to 512 MB in total and 32 MB per file. A project above the total limit is
158
+ refused with an error instead of a partial copy; files above the per-file limit are left out of
159
+ the copy.
143
160
  - `node_modules` is linked into the copy instead of copied, so agents can run project checks.
144
161
  - Artel watches the copy, not your project: it cannot know about edits you make during the run until
145
162
  you apply, and then it refuses to overwrite those files.
146
163
  - Only files are applied. Deleted files are deleted on Apply; renames arrive as one deletion and one
147
164
  addition.
165
+ - Apply is all-or-nothing for the run: either every changed file is written or, if a file conflicts,
166
+ none is. The changes card has no per-file selection.
148
167
  - Swarm agents live in one agent tree: the first agent is the session at the root of that tree and the
149
168
  other two are its subagents. That is what lets them message each other, and it means the root session
150
169
  must exist for their messages to be delivered. Closing that session (or restarting the Host) ends the
@@ -161,8 +180,9 @@ All values are optional; set them in the bundle's plugin configuration.
161
180
  ## Data and privacy
162
181
 
163
182
  Run records and feeds are plain JSON and JSONL files under `stateDir`. Agent conversations are
164
- ordinary DSH sessions and stay in your session store. The plugin serves its page over a loopback-only
165
- HTTP API; every request is checked for a local socket, a local Host header and a same-origin origin.
183
+ ordinary DSH sessions and stay in your session store. The plugin's host half talks to the client over
184
+ a loopback-only HTTP API; every request is checked for a local socket, a local Host header and a
185
+ same-origin origin.
166
186
 
167
187
  ## Development
168
188
 
package/docs/guide.md CHANGED
@@ -1,136 +1,218 @@
1
1
  # Artel
2
2
 
3
- Artel runs a development task in an isolated copy of the project open in your chat session, shows the
4
- work while it happens, and applies the result to your project only when you say so.
3
+ Artel runs a development task in an isolated copy of the project that the current chat session works
4
+ in: it shows the work as it happens and moves the result into your project only when you ask.
5
5
 
6
- Open the **Artel** tab from the session header (**Artel** button) or from the right sidebar guide. The
7
- tab belongs to the current chat session, and that session's working directory is the project.
6
+ Artel opens from the chat itself. The **Artel** icon button sits in the composer tool row, next to
7
+ "+". It lays a panel (overlay) over the current chat; the chat stays underneath and is not changed.
8
+ The panel belongs to this session, and the session's working directory is the project.
8
9
 
9
- ## Start a run
10
+ ![The Artel panel: the session rail and the new-run form](artel-in-chat/screens/hero.png)
10
11
 
11
- 1. Choose a mode: **Solo** or **Swarm**.
12
- 2. Describe the task in your own words: what should come out, and where in the project it lives. You do
13
- not have to prepare files — the agents find and read them.
14
- 3. Press **Start** (or Ctrl+Enter).
12
+ ## Open Artel
13
+
14
+ 1. Open a chat whose working directory contains the project.
15
+ 2. Click **Artel** in the tool row under the chat composer (next to **+**). While a run in this
16
+ session is active, the button shows a dot.
17
+ 3. The panel covers the chat area. To get back to the chat, use **← Chat** in the panel header or
18
+ press Esc. Closing the panel does not stop the run: the agents keep working, and the next time
19
+ you open the panel it returns to the last selected run.
20
+
21
+ The header holds **← Chat**, the title **Artel**, the status of the selected run, and **Refresh** (it
22
+ re-reads the run list and the open run; the feed itself updates while the panel is open).
23
+
24
+ The left side is the **Sessions** rail: every Artel run of the current session, grouped by project.
25
+ A row shows a state dot, the task and a short `Solo · 1/3 · phase` line — the mode, how many agents
26
+ have finished a turn out of the total, and the current phase (the last status or plan message). The
27
+ active run is highlighted; clicking a row opens its page. **+ New Artel** returns to the new-run
28
+ form, and the rail footer shows `{n} runs` and `{n} files`. While there are no runs the rail says
29
+ "No Artel runs yet." and "Describe a task on the right — the agents work in an isolated copy.".
30
+
31
+ ## New Artel
32
+
33
+ The form takes the right side of the panel. Its heading names the project and the mode: "New Artel
34
+ in <project> · via <mode>". If the project is not known yet the heading is shorter: "New Artel ·
35
+ via <mode>".
36
+
37
+ 1. Describe the task in "What should the agents do? Describe the task…": what should come out and
38
+ where it lives in the project. You do not need to prepare any files — the agents find and read
39
+ them.
40
+ 2. Pick a mode: **Solo** ("One agent, one copy") or **Swarm** ("Three agents divide the files").
41
+ 3. Press **Go →** (or Ctrl+Enter). While the request is in flight the button reads "Starting…".
42
+
43
+ Below the form: "Artel works in an isolated copy of the project. Your files stay untouched until you
44
+ apply the changes." If a run does not start, a banner titled "Could not start Artel" with the error
45
+ text appears under the button.
46
+
47
+ ## Starting a run
15
48
 
16
49
  Artel then:
17
50
 
18
- 1. copies the project into a fresh directory outside it;
19
- 2. starts one agent (Solo) or three agents (Swarm) whose working directory is the copy;
20
- 3. sends them the task and a short set of rules: own the copy, never touch the real project, run the
21
- checks that fit the change, and explain what they did at the end.
51
+ 1. copies the project into a separate directory outside it;
52
+ 2. starts one agent (Solo) or three (Swarm) with the copy as their working directory;
53
+ 3. hands them the task and a few rules: edit only the copy, never touch the real project, run the
54
+ appropriate checks and finish by explaining what was done.
22
55
 
23
- The copy is created once per run and shared by every agent in it. The project itself is not modified.
56
+ The copy is made once per run and all agents work in it. The project itself never changes.
57
+
58
+ The agents run unattended: Artel gives them the approval policy `never` and inherits the sandbox
59
+ mode of the parent chat session. Tools that are unavailable in that sandbox return a refusal to the
60
+ agent instead of leaving the run waiting for an approval.
24
61
 
25
62
  ## Solo
26
63
 
27
- One agent carries the task from start to finish. Its messages, tool calls and file edits appear in the
28
- feed as they happen. Write to it at any time; the message joins the conversation without stopping it.
64
+ One agent carries the task from start to finish. Its messages, tool calls and edits appear in the
65
+ feed right away. You can write to it at any time — the message joins the conversation without
66
+ stopping the work.
29
67
 
30
68
  ## Swarm
31
69
 
32
- Three agents work in one copy and read each other's edits on disk as they appear. They also talk to
33
- each other: the team shares one conversation tree, so `send_message({ agent: "<name>", message: "..." })`
34
- reaches a teammate as a real turn, and `list_agents()` shows the whole team. Messages the agents send
35
- each other appear in the feed with both names (`Orion → Vega`), so you can follow the negotiation
36
- without opening their conversations.
70
+ Three agents work in the same copy and see each other's edits: each one reads the files the others
71
+ have already changed and adapts to them. They also talk to each other: the whole team lives in one
72
+ conversation tree, so `send_message({ agent: "<name>", message: "..." })` reaches a neighbour as a
73
+ real turn, and `list_agents()` lists the whole team. Their exchanges appear in the feed as separate
74
+ rows: the sender's name, an arrow and the message text.
37
75
 
38
- **First turn — planning.** The agents are told not to edit anything. They read the project, decide who
39
- takes which files, talk it over when a boundary is unclear, and end their turn with one line:
76
+ **The first turn is planning.** The agents may not edit anything. They read the project, agree who
77
+ owns which files (if a boundary is unclear, they message the neighbour) and end the turn with a
78
+ single line:
40
79
 
41
80
  ```
42
81
  OWNERSHIP: src/app/settings/**
43
82
  ```
44
83
 
45
- Artel collects those claims, keeps the first claim on a contested path, and shows the divided map in
46
- the feed. If two agents claim the same files, the feed names both agents and the winner.
84
+ Artel collects the claims, leaves a contested area to the first claimant and shows the split as a
85
+ **Plan** card in the feed. If two agents claim the same files, the feed names both and the winner.
86
+
87
+ **Then parallel work.** Artel sends each agent its area and starts them all at once. Each one reads
88
+ the files the others have already changed and adapts to them; if a change outside the area is
89
+ needed, the agent messages the owner instead of editing someone else's file and mentions it in the
90
+ final report. A message that arrives while an agent is idle wakes it for a new turn; Artel waits
91
+ briefly before declaring the run waiting so a short exchange between two agents does not look like
92
+ finished work.
47
93
 
48
- **Then — parallel work.** Artel sends each agent its final area and starts them together. Each agent
49
- reads the files the others already changed on disk and adapts to them; an agent that needs something
50
- outside its area messages the owner instead of editing the owner's files, and says so in its final
51
- summary. A message that arrives while an agent is idle wakes it for another turn; Artel waits a moment
52
- before calling the run waiting, so a short exchange between two agents does not look like a finished run.
94
+ While the run is active Artel watches the edits. When a second agent touches a file another agent
95
+ has already touched, an **Edit collision** row appears in the feed with both names and the path.
96
+ Ownership is declared, not enforced: the overlap is visible, the edit is not blocked.
53
97
 
54
- While the run is active, Artel watches every edit tool call. When a second agent touches a path that
55
- another agent already touched, the feed shows a collision line with both names. Ownership is
56
- announced, not enforced: the collision is visible, but the edit is not blocked.
98
+ An agent that claimed nothing receives the unclaimed files with a "nobody claimed it" note in the
99
+ plan, so it does not sit idle; if there are no unclaimed files, it becomes a reviewer of the shared
100
+ copy and says so in its report.
57
101
 
58
- An agent that ends up with no claimed files is handed unclaimed files that sit next to the claimed work,
59
- marked "nobody claimed it" in the plan. If the task is small enough for one agent, the other two simply
60
- change nothing, verify the copy and say so in their summaries.
102
+ If nobody claims an area during the planning turn, Artel asks again. If the second attempt is empty
103
+ too, Artel splits the top level of the project between the agents so the run does not stall, and
104
+ says so in the feed.
61
105
 
62
- If no agent announces ownership in the planning turn, Artel asks once more. If the second attempt also
63
- comes back empty, Artel splits the top level of the project between the agents so the run can still
64
- proceed, and says so in the feed.
106
+ ## The run page
65
107
 
66
- ## While the run is active
108
+ The selected run's page opens on the right: the task at the top, the mode tag (**Solo** or
109
+ **Swarm**), the status, a tag with the number of changed files (once there are any) and a phase line
110
+ — the same short stage description as in the rail.
67
111
 
68
- The header shows the run status: preparing, dividing work, working, waiting for you, applied,
69
- discarded, failed, interrupted.
112
+ Run statuses: **Preparing**, **Planning**, **Working**, **Waiting for you**, **Finished**,
113
+ **Stopped**, **Failed**, **Applied**, **Discarded**.
70
114
 
71
- - **Feed** — every message, tool call, status change, plan and collision, in order.
72
- - **Agents** — one row per agent with its state and claimed files. **Open conversation** opens the
73
- agent's full DSH conversation in a new chat; those chats also appear in the sidebar titled
74
- `Artel · <agent> — <task>` and can be archived like any other chat. In Swarm only the lead agent has
75
- its own chat: the other two are its subagents and live inside that conversation tree, which is exactly
76
- what lets all three message each other. Their traffic is in the feed instead.
77
- - **Write to the agents** — the composer at the bottom of the run. In Solo it goes to the agent; in
78
- Swarm you choose one agent or **All agents** (broadcast). A message turns a waiting run back into a
79
- working run.
80
- - **Stop** interrupts every agent. The work already done in the copy stays available for review.
115
+ ![The run page: agent replies and grouped tool calls](artel-in-chat/screens/run.png)
81
116
 
82
- When every agent goes idle, Artel stops the run, computes the diff against the copy and marks the run
83
- as **Waiting for you**.
117
+ While a run is active the header has a **Stop** button. It asks for confirmation: "Stop this Artel
118
+ run?" with **Stop run** and **Keep working** (and "Stopping…" while the request is in flight). A
119
+ stopped run becomes **Stopped**; the copy and the diff stay available, and messaging the agents puts
120
+ it back to work.
84
121
 
85
- ## Review, apply, discard
122
+ ### The feed
86
123
 
87
- The **Changes** list shows every file that differs from your project: `A` added, `M` modified,
88
- `D` deleted, `B` binary (binary files can be applied but not previewed as text). Added and removed line
89
- counts are shown per file; open a file to read its hunks.
124
+ - Full agent replies: an avatar with the initial, the name, the role and the time; the text is
125
+ rendered as markdown.
126
+ - Tool calls are grouped into compact rows: the tool name and the file path or command.
127
+ - Status rows with a timestamp and a **Plan** card with the split of work.
128
+ - Your messages: a bubble labelled "You → Everyone" or "You → <agent>".
129
+ - Agents talking to each other: the sender's name, an arrow and the message text.
130
+ - **Edit collision** when two agents touched one path; **Error** when an agent's turn failed. Both
131
+ name the path underneath when it is known.
90
132
 
91
- - Untick files you do not want to apply. **Select all** and **Select none** are shortcuts.
92
- - **Apply N files** copies the selected files into your project.
93
- - **Discard** throws the copy away. Nothing reaches your project.
94
- - **New task** starts a fresh run; the previous run stays in the list.
133
+ While the feed is empty it says "The agents are getting ready — their messages will appear here.";
134
+ while it loads, "Loading the feed…".
95
135
 
96
- Before writing anything, Artel re-reads your project. For every selected file it checks whether the
97
- file still matches the state it had when the run started:
136
+ ### Messaging the agents
137
+
138
+ The field at the bottom is "Write to the agents…", with a **Send** button. The footer has **To**:
139
+ **Everyone** by default, and a specific agent can also be chosen. Next to it: "Ctrl+Enter — send".
140
+ The message appears in the feed as "You → …" and puts a waiting or stopped run back to work while the
141
+ copy is still neither applied nor discarded.
142
+
143
+ ## Changes: apply or discard
144
+
145
+ When the agents go idle, Artel stops, computes the difference against your project and moves the run
146
+ to **Waiting for you**. The **Changes** card at the bottom of the page lists the files that differ
147
+ from your project: the heading "Changes · N files" and total `+N/−M` counts. Each row has a status —
148
+ **added**, **modified**, **deleted** or **binary** — and its own `+N/−M`. Click a file to open its
149
+ diff (**Show the diff**); click again to close it (**Hide the diff**). Binary files cannot be
150
+ expanded. The card header has **Refresh changes** and a collapse toggle (**Show changes** / **Hide
151
+ changes**).
152
+
153
+ ![The Changes card with a file diff open](artel-in-chat/screens/changes.png)
154
+
155
+ - **Apply** first asks for confirmation: "Apply these changes?" and "The changes will be written to
156
+ <project>. The isolated copy will be deleted.", with **Apply** and **Cancel**. It writes every
157
+ file in the card; there is no per-file selection.
158
+ - **Discard** asks "Discard these changes?" and "The isolated copy will be deleted; <project> will
159
+ stay untouched.", with **Discard** and **Cancel**.
160
+
161
+ After the decision a plate replaces the buttons: **Applied** with "The changes are written to
162
+ <project>." or **Discarded** with "The copy was deleted; the project is unchanged." If some files
163
+ could not be written, the card adds "Skipped: N".
164
+
165
+ Before writing, Artel re-reads your project. For each file it checks whether the file still matches
166
+ the state it had when the run started:
98
167
 
99
168
  - If it does, the file is applied.
100
- - If you changed it during the run, Artel refuses that file and says `changed in your project during
101
- the run`; the rest of the selection is not applied either — the whole Apply is rejected so that you
102
- can decide again.
103
- - A file that appeared in your project during the run is refused the same way.
169
+ - If you edited it during the run, Artel refuses: "Nothing was applied. <file>: changed in your
170
+ project during the run" — and writes nothing, so you can decide again.
171
+ - A file that appeared in the project during the run is rejected the same way.
104
172
 
105
- Applying a run is final: the run becomes **Applied** and its copy stays on disk for later inspection
106
- until the sweep removes it.
173
+ An apply is final: the run becomes **Applied**, its changes are in the project, and the isolated copy is
174
+ deleted right away. The diff stays in the run feed, so you can still read what changed.
107
175
 
108
176
  ## Where the data lives
109
177
 
110
- - Copies: `<DSH home>/artel/<profile>/copies/<run id>` — deleted on Discard, and on startup when older
111
- than `keepCopiesHours`.
112
- - Run index and feeds: `<DSH home>/artel/<profile>/state/runs` — JSON index plus one JSONL feed per
113
- run, capped per run.
178
+ - Copies: `<DSH home>/artel/<profile>/copies/<run id>` — deleted when the run is applied or discarded; a
179
+ copy left behind by a crash is removed at the next start.
180
+ - Run index and feeds: `<DSH home>/artel/<profile>/state/runs` — a JSON index and one JSONL file per
181
+ run, with a size limit.
114
182
  - Agent conversations: ordinary DSH sessions in your session store.
115
183
 
116
- Artel keeps at most `maxRunsPerSession` runs per session; the oldest are dropped from the list.
184
+ Artel keeps at most `maxRunsPerSession` runs per session: the oldest finished runs (applied,
185
+ discarded, stopped, failed) are dropped from the list together with their copies. Runs still waiting
186
+ for your decision are never dropped.
117
187
 
118
188
  ## Troubleshooting
119
189
 
120
- **"Artel cannot see the web server"** — the profile does not expose a Host web server, so the page
121
- cannot be served. This plugin needs the desktop/web profile.
190
+ **"The Artel host half is unavailable. Check that the plugin is enabled."** — the client half loaded
191
+ but the host half does not answer: the plugin is disabled or the host half failed to load. Enable
192
+ the plugin and reload the page.
193
+
194
+ **"The Artel host is restarting — retry in a moment."** — the host is updating or restarting. Wait
195
+ and press **Retry** in the banner.
196
+
197
+ **"This chat session has no project directory yet, so there is nothing to copy"** — the session has
198
+ no working directory, so there is nothing to copy. Open a workspace or start the session in a
199
+ directory. If the project directory exists but was deleted or moved, the host answers
200
+ "The project directory does not exist".
122
201
 
123
- **"This chat session has no project directory yet"** — the session has no working directory. Open a
124
- workspace or start the session in a directory first.
202
+ **"Could not copy the project: project is larger than 536870912 bytes; excluded folders or a smaller
203
+ project are required"** — the project exceeds the 512 MB copy limit. Artel does not make a partial
204
+ copy: the run is refused. Exclude heavy directories with `excludeGlobs` or use a smaller project.
205
+ Files larger than 32 MB are left out of the copy.
125
206
 
126
- **"The project is too large to copy"** — the copy limits are 20,000 files, 32 MB per file, 512 MB in
127
- total. Exclude heavy directories with `excludeGlobs`.
207
+ **"Another run is already in progress in this session"** — one active run per session. Finish it or
208
+ stop it.
128
209
 
129
- **"Another run is already in progress in this session"** — one active run per session. Stop or finish
130
- it before starting another.
210
+ **No changes** — the agents may have finished without edits; the card says "No file changes in this
211
+ run.". Read the feed; if the task needs a nudge, write to the agents.
131
212
 
132
- **No changes are shown** — the agents may have finished without editing files. Read the feed; if the
133
- task needs a nudge, write to the agents.
213
+ **The apply was rejected** — the card's banner lists the files that changed in the project during
214
+ the run. Discard the run, wait until the file is free and start again: applying only the remaining
215
+ files is not possible, because the card has no per-file selection.
134
216
 
135
- **Apply is refused** — the message names the files that changed in your project during the run.
136
- Discard the run, or re-run after the file is quiet, or apply the remaining files by starting a new run.
217
+ **The run was interrupted by a restart** — if the plugin or the host restarted, active runs become
218
+ **Stopped**. The copy and the diff stay: you can apply or discard them.