Learning to build an agent from Markwork

The journey: from answering to finishing the work

Each bar is one commit that changed the agent. The colors tell three kinds of tools apart: read (browsing files and Git history), proposal (producing changes that wait for approval), and control (the plan and verification, which do not touch files). Hover over a bar to see the number of tests and lines of code at that point.

1. f6a4cc7Chapters 1, 2 · The DeepSeek Assistant panel: context within a token budget, a stable prefix for the cache, BM25, an agent loop with 4 read-only tools.
2. 2d0150fChapter 3 · Conversation history is saved as Markdown in .markwork/chats and can be resumed.
3. 49021f3Chapter 3 · The prompt and identity are aligned with the personal workbench vision, no longer specific to book manuscripts.
4. 3f387e6Chapter 3 · search_manuscript → search_documents; the tool descriptions are neutralized.
5. 5a64789Chapter 4 · The first write tools (create_file, edit_file), which only produce proposals and wait for Apply/Reject.
6. c6f71daChapter 4 · Proposals are reviewed in the same diff window as Git history.
7. 8db7c55Chapter 4 · Fix for the panel being cut off after a long answer (scrolling through an idle).
8. deb8aa5Chapter 4 · edit_kanban and multi-hunk diffs.
9. 6c47266Chapters 5, 6 · The plan (set_work), batches (propose_batch), verification, the action journal, retry, and the history summary.
10. 1c90735Chapter 7 · The Agent log window for monitoring rounds, reasoning, tools, and their results.
11. 90c28bbChapter 8 · Insert, delete, move, replace all, partial approval, Undo, Git history tools, and structure verification.
12. b1ab712Chapter 9 · The harness orchestrator: @pi cards are worked on by pi in another project folder, a queue per folder, the pi log, cards move to In Progress/Review.
13. 0db63d2Chapter 9d · pi through RPC mode: a ⏸ waiting status when pi asks or an extension requests permission, answered from Markwork; steering while working and replies that continue the session.
14. 8d0cdecChapter 9f · A [[note]] on a card becomes pi prompt context: the note contents from the work folder are copied into the prompt, limited per note and in total.
15. b31556dChapter 5d · The set_work plan is shown as a checklist (WorkList): progress, a spinner on the step being worked on, turn duration; tidied to GNOME idioms in 4a35bc8 (Adw.Spinner, accessible labels).
16. a8dd69aChapter 5d · The Assistant message box: the send button inside the message frame (6037ab4), the context summary appears immediately when the panel is open from the start.
17. 9d6ea05Chapter 8d · The Git tools always answer: a watchdog in runGit ends a run whose result the runtime lost, or a git that hangs, as a failure the model can read.
18. 2dbf902Four rules · The conversation life cycle (send, stop, folder-change guards, saving and reopening history, undo) moves from the panel into agent/chatcontroller.ts; the panel only draws through ChatView. The workspace files now come from WorkspaceRepository (e4e3d91), with an explicit freshness per read.
19. 84dccddFour rules · The Assistant panel is split into its parts: settings, history, the context popover, and the proposal cards with their review window and Undo (ui/proposalcard.ts). Earlier commits split ChatSession.ask into a TurnRun with one method per tool (76acf0d), and planChange/planKanban into handlers per tool and action (1caf08a); every function is now at most complexity 15.
20. 1bac3b8Chapter 10 · The assistant writes the commit message: one request without tools from the checked files' diffs within a 30,000-character budget, streamed into the commit box, which the user still reviews and commits.

Four rules kept in every commit

The agent's capabilities quadrupled, but its basic shape stayed the same. Every new feature has to satisfy these four rules. That is why each chapter below can also be read as a way of satisfying them.

The direction of calls is never reversed. agent/ knows nothing about the editor or widgets. The window only gives it a way to read files (ChatHost) and a way to ask for the user's decision (onProposal, onBatchProposal). Since 2dbf902 the turn itself (sending, stopping, refusing proposals after a folder change, saving, undo) is run by ChatController, and the panel only draws what ChatView tells it, so these paths are tested without a window.

The model only knows what is sent: building context within a budget

The problem. The model cannot see the editor. If the work folder holds hundreds of KB of notes, it is impossible to send everything, and sending too much is also expensive and slow. So the quality of the answers is largely determined by a single function: buildContext().

The design. The context is split into two parts with different properties, and then ordered so that the part that rarely changes comes first:

DEFAULT_BUDGET = 48_000            // tokens
estimateTokens = s => ceil(s.length / 3)
// deliberately wasteful for Indonesian text
// order: selection → active document → @mention
//        → project map → BM25 excerpts

splitChunks(file, text)   // per heading,
  // sections >1,800 characters are split at blank lines
rankChunks(chunks, query) // BM25, k1 = 1.5, b = 0.75
  // headings count twice
buildQuery: question ×1, selection ×0.5,
            last 2 questions ×0.4

Earlier questions also go into the query with a small weight. That way, a follow-up question such as "then who handles it?" still finds the right excerpts. Suffixes are stripped roughly (the Indonesian -nya, -kan, -an, …) so that "rapatnya" matches "rapat".

Why the order matters: the prefix cache

Providers such as DeepSeek keep a cache for a message prefix that is exactly the same as in the previous request. A single different character at the start is enough to break the cache for the whole message after it. That is why the cursor position and the selection (which change with every question) must not be placed in system.

A bounded agent loop: the model asks, the code runs

A turn starts by calling the model. If the model asks for a tool, that tool is run, the result is sent back, and then the model is called again. The loop stops when the model gives an answer. The first version had only 4 read tools: list_files, search_manuscript (BM25), search_text (exact text), and read_file.

for (round = 0; round < MAX_ROUNDS; round++) {   // 10
  useTools = round < MAX_ROUNDS - 1
  result = await provider.chat({ messages,
             tools: useTools ? TOOLS : undefined })
  if (!result.toolCalls.length) break  // the answer
  for (call of result.toolCalls) {
    out = runTool(call.name, call.arguments, files)
    if (cost(out) > toolBudget) out = 'Budget exhausted…'
    messages.push({ role: 'tool', content: out })
  }
}

There are several small decisions that matter. Tools never throw: broken JSON arguments become an error message the model can read, so the model can fix it by itself. The result of read_file is given the same line numbers as the context, so "file:line" references are consistent. Tools are only offered if the user allows other files to be read (the project context switch). In addition, unsaved editor contents replace the version on disk.

Memory a human can read, and names that do not mislead

3a. A conversation as a Markdown file

Each conversation is saved as one file in <folder>/.markwork/chats/, with frontmatter (title, model, created) and then ## You / ## Assistant sections. The format is deliberately readable and editable by humans, not a hidden database.

3b. Tool names are part of the prompt

Markwork was originally designed for writing books, so its prompt and tools talked about the "manuscript". After the vision was widened into a personal workbench (notes, meetings, research, plans), the name search_manuscript was changed to search_documents and all the tool descriptions were neutralized. The model picks tools by their names and descriptions. A name that is too narrow makes the model hesitate to use the tool for meeting minutes.

From answering to proposing: changes as data

The need. Users want the agent not just to say "replace line 12", but to do it, without losing control over their files. The design. A write tool writes nothing. It only validates the arguments, and then computes the result as a value:

interface Change {
  kind: 'create' | 'edit' | 'delete' | 'move'
  file: string     // relative path in the work folder
  before: string   // contents at the time of the proposal
  after: string    // contents if applied
  reason: string   // the reason, shown in the review window
  to?: string      // move only
}

TOOLS          // read-only, run directly
CHANGE_TOOLS   // only produce a Change
// session:
change = planChange(name, args, files)
answer = await handlers.onProposal(change)
// ↑ a Promise that waits for the review window
if (answer.applied) applyToFiles(files, change)

edit_file asks for an old_text that appears exactly once. If it does not match, the model gets a message telling it to read the file first or to add surrounding lines. This approach is stronger than line numbers, because models often miscount lines. edit_kanban (deb8aa5) does not edit text directly. It uses the same board model as the kanban UI (parseBoard → operation → serializeBoard), so the result is always a valid board.

Preflight: the file contents must still be what they were at the proposal

There is a gap between the moment a proposal is made and the moment the user presses Apply. During that gap the user may well edit the file. That is why, before writing, the window calls preflight(). A proposal is rejected if before is no longer the same as the actual contents, instead of overwriting the user's edit.

function preflight(c, read) {
  const at = read(c.file)                  // null = does not exist
  if (c.kind === 'create') return at === null ? null : `${c.file} already exists`
  if (at === null)        return `${c.file} no longer exists`
  if (at !== c.before)    return `${c.file} changed since it was proposed; ask for a new proposal`
  if (c.kind === 'move' && read(c.to) !== null) return `${c.to} already exists`
  return null
}

Plan, batch, and verification: "done" must be checkable

The symptom. For multi-step work, such as moving a schedule across three documents and a task board, the model proposed changes one by one, sometimes forgot a file, and then declared "all done". The user had to approve five separate windows without seeing the whole picture.

5a. A plan that is stored: set_work

interface WorkState {
  goal: string
  status: 'running' | 'paused' | 'failed' | 'complete'
  steps: { text: string; status: 'pending' | 'done' | 'blocked' }[]   // 1–20
  note: string
  actionStart?: number          // journal index when this work started
  verification?: Verification   // the latest check result
}

One important rule: the model cannot set complete itself. That status can only be reached if verify_work passes and all the steps have the status done. Every change applied afterwards clears the verification result, so the check has to be repeated. If, in the next turn, the file contents turn out no longer to match the changes that were applied, the complete status drops back to paused.

5b. Batches: many actions, one review

planBatch(args, files) {
  virtual = copy(files)          // a trial world
  for (item of actions) {        // ≤ 20
    c = planChange(item.tool, item.arguments, virtual)
    // delete/move lock the file
    merge per file: first before, last after
    applyToFiles(virtual, c)     // the next action
  }                              // sees this result
}

applyBatch(changes, host) {
  // 1. preflight ALL first; one failure = cancel everything
  // 2. write in order
  // 3. if a write fails: roll back what was written,
  //    return the error + any rollback failures
}
// an in-process transaction, no atomic guarantee
// against power loss

The actions in a batch are planned on a virtual copy, so a second action on the same file sees the result of the first. The final results are merged into one Change per file. This decision later makes the partial approval in Chapter 8 possible.

5c. Deterministic verification

verify_work does not ask another model for an opinion. The model states its criteria, and then code checks them against the actual contents: present / absent (exact text), kanban (a card is in a given list with a given status), and since Chapter 8 also structure. The session also adds checks of its own: every file that was changed but is not mentioned in the criteria automatically produces "Changed files not yet checked: FAILED". That way, the model cannot get through just by checking the easy files.

5d. A visible plan: one WorkState, two readers · commits b31556d, 4a35bc8 · ui/worklist.ts

The symptom. The plan had been stored since 6c47266, but the panel showed it as the workText() text as it was: - [x] Read the meeting decisions, exactly as sent to the model. While the agent worked, the user could not see at a glance which step was in progress, and the same plan appeared twice because the tool step line "Work plan → …" printed it as well.

// before: one text for the model and for humans
answer.work.set_text(workText(work))
// - [x] Read the meeting decisions
// - [ ] Check the plan and the task cards

// after: the model still receives workText(),
// the panel draws from the same data
answer.work.update(work, running, seconds)
current = running && work.status === 'running'
  ? steps.findIndex(s => s.status === 'pending') : -1

There is no new status. WorkList only reads the existing WorkState, so a turn that is running and a conversation reopened from .markwork/chats look the same. The only piece of information that does not come from the model is the step in progress: the first pending step, only while the turn is running. As soon as the turn finishes, the spinner disappears and the status goes back to the saved status (paused, failed, or done and verified), so the display never claims progress that was not recorded. The "Work plan" line in the tool step list is hidden when the plan is valid; a plan rejected by parseWork still appears as an error line.

The display follows GNOME idioms (see AGENT.md, "The UI must follow GNOME standards"): symbolic icons, the @success_bg_color/@success_fg_color color pair, Adw.Spinner when libadwaita ≥ 1.6 with a Gtk.Spinner fallback, and every row has the list item role with an accessible label "text — status", so that the status is not conveyed through color alone.

The journal and recovery: interrupted work must not be repeated blindly

The symptom. The app can be closed, the connection can drop, or the user can open an old conversation tomorrow morning. Without a record, the agent might propose again a change that has already been applied, or conversely think a change that actually failed has succeeded.

interface ActionEvent {
  id, question, tool, time: string
  status: 'proposed' | 'applied' | 'rejected' | 'failed'
        | 'interrupted' | 'read' | 'reverted'
  changes: Change[]       // before/after snapshots → the diff can be reopened
  summary: string
}

Every tool call is recorded. A proposal is recorded as proposed before the review window opens, and its status is updated after the decision. If the process dies between the two points, the journal still holds proposed. On the next turn, reconcileEvents() compares it with the actual contents:

The journal and the work status are inserted as a message labeled "data, not instructions", together with an order not to repeat actions that have been applied or rejected. When loaded from disk, parseEvents() only accepts entries with a valid shape (a clean path, a known kind). That metadata can be edited by the user, so its contents are only restored as data and never executed.

A retry that does not duplicate text

// recovery.ts: retry only if no output has been shown yet
if (!(e instanceof TemporaryProviderError) || emitted || attempt >= 2) throw e
await wait(attempt === 0 ? 300 : 900)

Temporary errors (429, 5xx, a failed connection, or a cut-off stream) are retried at most twice, but only if not a single piece of text or reasoning has been shown yet. Retrying after part of an answer has streamed in would duplicate text on the user's screen.

A history summary that does not make things up

When the history exceeds 25% of the budget, the oldest turns are cut off in pairs. The cut-off part is replaced by an extractive excerpt (≤400 characters per turn, ≤4,000 in total), not a model-written summary. Excerpts add no new facts and need no extra API call. The full history stays on disk.

The Agent log: seeing what the agent actually did

The need. When the agent answers strangely, the question is almost always the same: what was sent, which tools were called with which arguments, and what came back? The step cards in the panel only show a one-line summary.

class AgentTrace {
  events: TraceEvent[]        // ≤ 2,000, the oldest dropped
  begin(kind, key, title)     // status 'running'
  append(kind, round, delta)  // text/reasoning streaming in
  finish(kind, key, status, detail)  // + duration (ms)
}
TraceKind = 'turn' | 'round' | 'reasoning' | 'text'
          | 'tool' | 'usage' | 'note' | 'error'

Broader actions, with limits just as tight

With the foundation of Change, preflight, the journal, and verification, new capabilities can be added without opening a shortcut. Every new tool uses the same approval path.

8a. Partial approval: why one Change per file matters

The batch review window now has a checkbox per file. Partial approval is only safe if each Change stands on its own. That is why planBatch (Chapter 5) already merged actions per file, and why files that are deleted or moved are locked so that no other action in the same batch may touch them. When the user applies only part of a batch, the journal records two events: one applied and one rejected. The model is told that the rejected part must not be repeated without asking. The Note for the agent box is passed along with the decision (≤2,000 characters), so a rejection can come with a reason.

8b. Undo = the inverse, passing through the same preflight

invertChange(c):  create → delete    delete → create (from the before snapshot)
                  edit   → edit with before/after swapped
                  move   → move from c.to back to c.file
// applied as a reversed batch: [...changes].reverse().map(invertChange)

Because the inverse is also a Change, Undo automatically fails safely if the file has been edited again. You already tried it in Simulation 4. The journal marks it reverted so that the agent does not think the change is still in effect.

8c. Structure verification: only new problems cause a failure

The structure check (markdown/lint.ts) looks for tables whose cell counts do not match, unclosed code blocks, empty headings or ones that skip a level, and links to Markdown files that do not exist. Real documents often already have such problems, so the check is compared with the contents before the work (the baseline, taken from the before of the first change per file). Every problem has a key without a line number, so an old problem that only shifted lines is not counted as new. Only problems that appear because of the agent's change make it fail. The criterion file: "*" checks the whole folder, for example to make sure an old date remains nowhere.

8d. A tool must always answer: the Git result that never came

The agent loop waits for every tool call before the next round. A read tool that never returns does not fail; it freezes the whole turn, with the spinner still turning. That is what an occasional timeout of the test agentGit in a real repository turned out to be. The log of a failing run showed:

Gjs-CRITICAL: Attempting to run a JS callback during garbage collection … it has been blocked.
The offending callback was AsyncReadyCallback().

runGit() (git.ts) starts git with Gio.Subprocess and waits for communicate_utf8_async(). Git had exited (GLib had already reaped it) and timers still ran, but GJS 1.80 blocked the completion callback because it arrived during a garbage collection, so the Promise behind git_log never settled. This is the same runtime guard described in bench/GC-DIAGNOSIS.md; it is rare (about a third of the test runs with every CPU core busy, and now and then without load) and cannot be fixed from the app.

runGit(cwd, args):  start git, wait for communicate_utf8_async()
  watchdog every 500 ms:
    git has exited and no result after 5 s   → failure "git finished but its result was lost; try again"
    git still running after 120 s             → stop git, failure "git did not finish within 120 seconds"
  the first of (callback, watchdog) settles the run; the other is ignored

Both endings are ordinary failures: formatGit() turns them into a message the model reads, and it can call the tool again. The run is not repeated automatically, because the same runGit() also commits for the History tab, and a commit whose result was lost may already have happened. The second limit covers a git that waits for input that will never come, such as a signing passphrase. The test replaces Gio.Subprocess.prototype.communicate_utf8_async with a function that never calls back, exactly what the runtime does, and also runs a git alias that sleeps longer than the limit; with the watchdog disabled, the test times out.

Markwork as an orchestrator: another agent works, Markwork holds the board

The need. Project code (for example ~/web-ecommerce) does not live in Markwork's work folder, and the work needs an agent that can run commands, edit code, and run tests. That is not a job for the Markwork agent, which deliberately never writes by itself. The answer: let another agent (pi) do the work, and make the Markwork kanban board the control plane. The card states the task, @pi states who does it, and the list states its status.

## Plan
- [ ] Checkout with QRIS @pi #feature
  Use the official SDK.
- [ ] Test the cart @pi #project/shop-admin

// board frontmatter: project: web-ecommerce
// settings.json: projects = {
//   "web-ecommerce": "/home/eka/web-ecommerce",
//   "shop-admin":    "/home/eka/shop-admin" }

interface Run {
  board, card        // board + card text (the identifier)
  agent: 'pi'
  project, folder    // name → folder from the settings
  prompt
  status: 'queued' | 'working' | 'done'
        | 'failed' | 'stopped'
  trace: AgentTrace  // the pi log
  result: HarnessResult | null
}

9a. The trust boundary moves to the folder

Up to Chapter 8, every write went through Change and the review window. An external harness cannot be treated like that: pi writes directly, runs bash, and uses its own permission rules. So the boundary is no longer per change, but per folder:

9b. Delegation through a process contract, not a tool call

pi is not called as a model tool. It is a separate process with a clear contract: arguments in, JSONL out, an exit code at the end. PiReader reads the events tool_execution_start/end, message_update, message_end (with stopReason and usage.cost), and agent_settled, and maps them to the same AgentTrace as in Chapter 7. The Agent log window is reused without any change. Lines that are not JSON are recorded as they are and do not make the reading fail.

One GJS trap: the pipe from Gio.Subprocess.get_stdout_pipe() is wrapped as a Gio.UnixInputStream after Gtk is loaded, and GJS prints a Gjs-WARNING. That is why the pipe is read through GLib.IOChannel, split only at LF according to pi's JSONL framing.

9c. The board as the source of truth, the card looked up again

The board has no card ids, so a card is recognized by its text. Every time the status changes, locateCard() looks for it on the current board (the user may have moved it) and refuses if it is missing or not unique. A board that is open is changed through its editor (one undo step); a closed one is written straight to disk.

9d. Waiting for an answer: from a one-way stream to a two-way conversation

The symptom. The first version used pi --mode json with stdin closed right away. If pi asked ("Do you want SDK A or B?"), the card still went into Review and the question was simply left behind in the note. If a pi extension asked for permission (for example before rm -rf), the dialog had no recipient: the permission-gate shipped with pi's examples actually blocks the command when there is no UI.

The design. pi is started with --mode rpc. Its process stays alive for the run, receives commands through stdin, and sends the same events as the JSON mode, plus two new things:

// stdout → Markwork
{"type":"extension_ui_request","id":"u1",
 "method":"confirm","title":"Allow the bash command?",
 "message":"rm -rf build"}
{"type":"agent_settled"}    // the turn is finished

// Markwork → stdin
{"type":"extension_ui_response","id":"u1","confirmed":true}
{"id":"markwork-2","type":"prompt","message":"Use SDK A"}
{"id":"markwork-steer","type":"steer","message":"…"}

PiSignal = { type: 'ask', ask: HarnessAsk }
         | { type: 'settled' }
         | { type: 'rejected', error }

HarnessAsk {
  kind: 'select' | 'confirm' | 'input'
      | 'editor' | 'question'
  id     // null for a question
  title, message, options, prefill
  timeout  // pi answers by itself after it
}

There are two kinds of "waiting" with different answer channels. An extension dialog has an id and is answered with extension_ui_response. A model question has no special protocol: pi just stops with some text. Markwork treats it as a question if the last answer ends with ?, and the reply is sent as the next prompt to the same process. The reader discards the old turn state through restart() so that an error or answer from before is not carried over. This heuristic can miss, so every finished run can still be replied to through Reply to pi…, which runs pi again with --session <id> and the same log.

9f. Notes as context: the contents are sent, the access is not

The need. Design decisions, specifications, and meeting minutes live in Markwork's work folder, while pi works in the project repo. The boundary in 9a deliberately makes pi unable to read the work folder. As a result, the card "Checkout with QRIS" only carries a single title line. Users had to copy the specification into the card note by hand, and that copy went stale quickly.

The design. A card links notes with the syntax already used in the editor, [[Specification#Payment]]. On Work on it with pi, Markwork resolves the link and copies its contents into the prompt. Pi still gets no path to the work folder, and the boundary in 9a does not change.

// pure: agent/harness.ts + markdown/wikilink.ts
cardWikiLinks(card)        // title + note, ≤ 10,
                           // no duplicates, code skipped
LinkedNote {
  link: WikiLink           // target, heading, alias
  file: string | null      // null = not found
  text: string | null      // null = #section is missing
}
buildPrompt(card, project, board, notes)

// host (window.ts), same rules as Ctrl+click
linkedNotes(boardFile, links):
  root  = work folder (or the board's folder)
  files = workspace.names(root)    // no dot folders,
                                   // no symlinks
  file  = resolveWikiLink(target, files, board)
  text  = open editor ?? disk
  text  = heading ? noteSection(text, heading) : text

9e. Testing: a real process, a fake harness

The GUI tests run a shell script that pretends to be pi, through the same process path. These tests check the cwd and the prompt, a card moving to In Progress and then Review with a note, a queue that is truly in order (the script records start/end), Stop on a process stuck for 30 seconds, a failure with a message from stderr, a project folder that is asked for once and then remembered, and a closed board that is updated on disk. For RPC mode, the fake script reads get_state and prompt from stdin, sends a permission request or a question, and then records the answer it received. The tests check the exact answer that arrives ({"type":"extension_ui_response","id":"ui-1","confirmed":true}), Later still waiting, End without replying, steering that arrives as steer, and a reply that runs with --session test-session in the same log. The unit tests cover @name assignment (not an email or @{date}), the project, folder rejection, the prompt, PiReader, the result note, and the queue. There are 23 tests, all without a real pi or API.

The smallest model call: one line for the commit box

The need. The History tab can commit several files at once, but the message is still typed by hand, and a writer's commits easily turn into "update plan.md". The model can see what changed, so it can suggest a better line. This needs no conversation, no tools, and no proposal. It is one request whose answer goes into a box the user already reviews.

// agent/commitmessage.ts: no GTK; git and the key come in as CommitSources
writeCommitMessage(sources, files, onText, cancellable)
  key   = sources.keyStore.get()            → none: { ok: false, reason: 'no-key' }
  diffs = files.map(sources.diff)           → one unreadable diff is named, not fatal
  fit   = fitDiffs(diffs, 30_000 chars)     → small diffs whole, the largest cut to whole lines
  chat({ messages: commitPrompt(fit, subjects), thinking: false, onText })
  return { ok: true, message: cleanMessage(answer), shortened, cancelled }

The budget. A diff can be as long as a book. fitDiffs() shares a fixed budget out fairly: going from the smallest diff up, each gets at most an equal share of what is left, so small diffs are sent whole and only the largest ones are cut. The cut ends on a whole line and says how many lines were left out, and the prompt tells the model that some diffs were shortened. The status line under the box tells the user the same thing.

The boundary. The button reads only what the user is about to commit, which is the same set the user already chose with the checkboxes. While it writes, MessageWriter locks the box, the checkboxes, and Commit, so the files and the message cannot change under it. The button becomes Stop, and Stop keeps the text written so far. A missing key, a network error, or an empty answer puts the previous text back and says why in the status line. Without a key, the status line links to the Assistant settings. The window gives the button its writer (connectWriter) using the Assistant's key store, provider, and model, so tests swap in a fake writer without touching the network.

One GTK detail. Gtk.TextBuffer.set_text() is not recorded in the box's undo history, so GTK's own Ctrl+Z cannot step back to the user's draft. MessageWriter keeps that one step itself: a capture-phase key handler restores the previous text while the box still holds exactly the written message, and forgets it as soon as the user edits.

What does that safety cost?

Snapshots, verification, and the journal are not free. The following measurements run locally without calling a model: 10 repetitions after 3 warm-ups, a batch of 20 files, at sizes of 30,000 and 480,000 characters per file. The fixture replaces the entire contents of a file, so it is deliberately heavier than ordinary work.

Optimizing the new code in the same piece of work (90c28bb)

The first version of the structure check walked every document three times (frontmatter/code, tables, links) and trimmed whitespace on every line. The "*" check split all files into lines even if the text being looked for was not in that file. Now the three are merged into a single pass with a character filter before the regex, and "*" only splits files that actually contain the text (file.text.includes() first).

Patterns that carry over to other agents

Sources: README.md (the "How the assistant works" section), AGENTIC.md, src/agent/, and the git commit history from f6a4cc7 to 90c28bb, plus the harness orchestrator (Chapter 9). See also learning performance from the Markwork editor.