Abort 並不足夠：ToolKnit Desktop 的 Tauri 工具箱生命週期與輸出契約

A user starts a conversion, switches tools, and starts another operation. The first promise resolves last. Which screen is allowed to display its result?

That question looks like a small UI bug. In a desktop toolbox, it connects several architectural decisions: who owns asynchronous work, whether an imported module is still wanted, and when a file operation is actually complete.

This is a source-based walkthrough of those boundaries in ToolKnit Desktop, a project I maintain. The examples below are simplified teaching examples, not copied production implementations. The references point to one fixed revision so the discussion remains reproducible as the code changes.

Scope and disclosure: AI generated this draft from a review of the linked source and documentation. This is not a benchmark or an independent security audit. The repository is source-available: its current licensing includes PolyForm Noncommercial and a separate restriction for the PDF-to-Word engine. Public source access should not be confused with unrestricted open-source licensing.

1. Three different lifetimes hide behind one tool button

A toolbox can have at least three useful lifetimes:

These lifetimes do not necessarily end together. Hiding a tool does not unload an ES module. A registry can cache an initialized tool for reuse while the tool cancels its current operation.

This distinction matters because two opposite mistakes are easy to make:

• Keep every resource alive because the tool instance is cached.
• Destroy all reusable state whenever a tool becomes invisible.

The useful question for each resource is: which lifetime owns it? A global Escape listener and a conversion-specific progress callback should not have identical ownership.

The project's lifecycle utilities group cleanup callbacks into a scope. The scope provides event and timer helpers, an abort controller, revision tokens, and idempotent disposal. Disposal invalidates outstanding tokens and runs cleanup callbacks in reverse registration order. One cleanup error does not prevent the other cleanups from running.

That is a mechanism for managing resources, not proof that every feature uses it correctly. Feature implementations still have to register what they allocate.

2. Cancellation and permission to update the UI are different things

An AbortController asks cooperative work to stop. It does not automatically make every result from that work irrelevant.

Consider this sequence:

1. Operation A starts.
2. The user starts operation B.
3. A is asked to abort.
4. A's already-completed result reaches a continuation.
5. A overwrites B's progress or result.

Not every dependency accepts an abort signal. Even when it does, a completion may already be queued. A result needs an identity check as well as a cancellation mechanism.

Here is an intentionally small, original example:

let generation = 0;
let activeController;
let closed = false;

async function run(input) {
  if (closed) return;

  const mine = ++generation;
  activeController?.abort();
  const controller = new AbortController();
  activeController = controller;

  const isCurrent = () => !closed && mine === generation;

  setBusy(true);
  try {
    const result = await convert(input, {
      signal: controller.signal,
    });
    if (!isCurrent()) return;
    render(result);
  } catch (error) {
    if (isCurrent() && error.name !== "AbortError") {
      showError(error);
    }
  } finally {
    if (isCurrent()) setBusy(false);
  }
}

function dispose() {
  closed = true;
  generation++;
  activeController?.abort();
}

Notice the guard in finally. Guarding only render() still lets an older request clear the busy indicator for a newer one. Error notifications need the same treatment.

The example also has a limit: if convert() allocates a resource and returns it after becoming stale, returning early is not sufficient cleanup. A real implementation must release that result, or give the operation scope ownership of it. Ignoring a stale object URL does not revoke it.

In the actual lifecycle utility, invalidate(), token(), and isCurrent() provide the revision mechanism, while disposal makes all earlier tokens invalid. Cancellation manages work; a revision check manages authority to affect the current interface.

3. Lazy loading introduces a second race

Lazy loading is often presented as a bundle-size technique. It also changes navigation semantics.

User requests tool A → A's module starts loading
User requests tool B → B's module starts loading
B finishes → display B
A finishes → should A replace B?

The answer should normally follow the latest user request, not the slowest import.

The lazy registry handles two separate concerns:

1. It caches pending loads by instance key, so concurrent requests for one tool share initialization work.
2. It maintains a request revision and checks it across asynchronous navigation steps, so an older request cannot simply reclaim the active view after loading.

De-duplicating a promise does not solve stale navigation. Conversely, preventing stale activation does not prevent duplicate initialization. Both are needed.

There is another nuance: the currently active tool can reject a close by returning false. A navigation system must respect that decision rather than treating a successful import as permission to discard the current workflow.

A cached module may remain available after its original navigation request becomes stale. The important distinction is between having loaded a tool and being authorized to activate it now.

4. Platform boundaries should be explicit, not magically universal

The frontend uses vanilla JavaScript modules with Vite, while Tauri supplies the desktop boundary. The platform adapter centralizes core Tauri imports and exposes dynamic imports for selected APIs, including dialogs and webviews.

That is a specific boundary, not a claim that every native API is loaded lazily or that desktop code can be dropped unchanged into a browser.

For a reusable feature, the design question is which capability it needs: file selection, native processing, opening a window, or a browser API. Making those dependencies visible is more useful than giving every feature unrestricted access to every environment.

This also helps explain why a graphical app and a command-line interface should not be coupled through simulated clicks. A CLI should invoke a processing contract, not depend on which overlay happens to be open.

5. A successful command does not necessarily mean a new file exists

The project's CLI documentation describes direct file operations rather than GUI automation. Its documented output rules include explicit destinations, rejecting symbolic links, refusing to overwrite inputs, and requiring an explicit overwrite option for existing outputs. Writing operations stage temporary output in the destination directory before publishing it on success.

These rules give callers something more useful than a button label: a file-system contract.

They do not eliminate every operational failure. Disk exhaustion, process interruption, unsupported formats, and missing engines still need handling. Staging an output also should not be described as a universal power-loss durability guarantee.

Compression provides an especially useful lesson. A request can be handled without publishing a new output: the input might already satisfy the target, the requested target might not be reached, or the operation might achieve no reduction. The documented statuses distinguish these cases from a newly published compressed file.

An automation client that only checks “exit code equals zero” can therefore make the wrong next move. It should inspect the operation's structured status and documented output fields before trying to attach or upload a result.

This is a general API design principle: report what happened to the artifact, not just what happened to the process.

6. MCP needs the same contracts, plus protocol discipline

Exposing tools to an agent does not make their file operations less consequential. It makes explicit inputs, outputs, and cancellation more important.

The documented MCP interface uses newline-delimited JSON-RPC over standard input and output. Standard output must remain protocol-only: a friendly startup banner in that stream can break a client. Human-readable diagnostics need a separate channel.

The documentation also specifies bounded input and concurrency rather than unlimited parallel execution. Those are useful resource controls, but they should not be mistaken for a sandbox or authorization policy.

An agent caller still needs to inspect a tool's schema, identify the intended input files, choose a destination, and interpret the returned status. Permission to inspect one document is not automatically permission to replace a folder of documents.

7. Test the transitions, not only the happy path

The following is a proposed test matrix for this architecture, not a claim that these scenarios were executed for this article:

Deferred promises make the frontend races deterministic: resolve them in the wrong order deliberately instead of hoping a slow machine reproduces the bug. File-writing tests should use temporary fixtures and inspect both content and directory state after failure.

The common thread is ownership. A result needs an owner that is still current. A resource needs an owner that will release it. An output file needs a contract that tells the next caller whether it exists and whether it is complete.

Those boundaries are worth defining before a toolbox becomes large. They remain useful whether the application has five tools or fifty.

Source references

The source review used revision 0f088b0ee25ac3a1d362c740fed7267ab4b36b36. Code examples above are explanatory; the linked implementation is the authority for its exact behavior.