Kaede AkinoandClaude Opus 5
99be1d6885
Editing a config on a host cost two full copies of it in tokens. `sftp_read` returns the file inline, and `sftp_write` takes the replacement back as a `content` string the model has to re-emit in full — so the ordinary "pull it, change three lines, push it back" job paid for the whole file twice, and anything over the 128 KB inline cap, or anything that was not UTF-8, was out of reach entirely. There was also nowhere to keep a draft between turns: a script the agent was composing lived only in the transcript, which the context pipeline trims head-and-tail as the run grows. `AgentScratchWorkspace` is a per-conversation staging directory under Application Support, inside the sandbox container, deleted with the conversation that owns it. Application Support rather than Caches because the system may evict a Caches directory mid-run, and a staging area that can vanish between two tool calls is worse than none. Paths are relative; `..` is refused rather than resolved, which is the inverse of `normalizeRemotePath` and the right inversion — a relative path with `..` in it is never something the agent needed. Symlinks are refused even when they point back inside, because an alias within the workspace makes two paths the same file and quietly breaks both the quota arithmetic and the atomicity `apply(_:to:)` claims. Every resolved path is then proven to still be under the scope. Writes are bounded per file, per conversation, and by entry count, and hidden files are counted — a quota you can evade by naming a file `.big` is not a quota. It is an actor, and that is load-bearing rather than incidental. Pi serializes file mutations through an explicit per-path queue; here the actor already serializes every operation against every other, so a read-modify-write is atomic for free. That is what lets every local scratch tool stay `.parallel`: a batch containing one does not have to drag its whole turn serial to be safe. `scratch_edit` follows Pi's `edit` and is what makes the rest pay off. Every `old_text` is matched against the file as it was before the call, not against the result of the preceding edit, so the model never simulates its own changes to write the second one. Matches must be unique and non-overlapping; anything ambiguous fails the whole call rather than applying part of it, because a half-applied edit is the one outcome nobody can reason about. Matching is exact first, then one line-aligned retry that ignores smart quotes, unicode dashes and trailing whitespace — without it an edit fails whenever the model retypes a block with tidied punctuation, which is often. And it returns a unified diff rather than the new file, which is the entire point: an 8 MB file can now be changed for the price of the lines that changed. `scratch_pull` and `scratch_push` move the bytes, and are separate tools rather than options on `sftp_read` / `sftp_write`. A tool that means two different things depending on which optional argument is present is harder for a model to choose correctly and harder to audit, and it would have put two safety levels inside one descriptor. The SFTP tools are untouched. `Safety` gains `locallyContained`. The existing two cases state *why* a call may skip the gate, and "read-only" is the wrong reason for a scratch write — it changes something, it just cannot change anything outside storage the app owns. It is auto-allowed in every mode including Ask for approval, because a staging area you must approve into is not a staging area, and six dialogs for one edit loop teach the reader to click through the seventh, which is the one that reaches a host. `isAutoAllowed` is a property of the case rather than an `== .requiresAuthorization` at the call site, so a fourth case has to make a decision here instead of defaulting to allowed. Nothing switches exhaustively over `Safety` and it is not persisted, so there is no migration. `scratch_push` is the only gated tool here, and it has a problem the SFTP tools do not: the approval card would show a filename where it used to show the bytes, leaving the reviewer — human or model — agreeing to something neither had seen. Its preflight therefore reads the staged file and puts the size, digest and a redacted twenty-line head into `localReasons`, which both the card and Security Review's `Local signals:` line already render. It also carries the digest in `executionMetadata` and rechecks it at execute time: approval suspends the turn, and what comes back from the workspace afterwards is only the same file if nothing rewrote it in between. The schema helpers move to an `AgentToolSchemaBuilding` protocol with defaults rather than a namespace enum, so a conforming type still calls `descriptor(…)` and `string(max:)` unqualified and a second tool file costs a conformance instead of a copy of forty lines. `UnifiedDiff` is a formatter over `CollectionDifference` — Swift's `difference(from:)` is already a Myers diff, so no dependency. It trims the common prefix and suffix before running, because Myers is fast on similar inputs and quadratic on unrelated ones, and refuses anything past a line limit in what is left. Its output was checked against the real tool before any expectation was written down: for eight cases it is byte-identical to GNU `diff -u`, and `patch -p1` applies each one and reproduces the target file. That found three bugs reading the code had not. `firstChangedLine` was nil for every replacement, because the first changed row of one is the removal and a removal has no line number on the new side. A trailing-newline-only difference produced an empty diff with `identical: false` — true and useless. And `LineEnding.detected` reported `.lf` for every CRLF file, because Swift treats "\r\n" as a single Character and `firstIndex(of: "\n")` finds nothing in a Windows file; editing one line would have rewritten every line ending in it. A fourth came from the BOM test: `String(data:encoding:.utf8)` strips a UTF-8 BOM while decoding, so checking the decoded String never fired and writing it back dropped those three bytes. It now reads the raw Data, and the test asserts on bytes for the same reason — decoding would have reported a pass either way. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
8.9 KiB
Termind architecture
Termind intentionally remains one application target and one unit-test target. Directories describe dependency boundaries even though Swift does not enforce them as separate modules.
Dependency direction
Domaincontains platform-independent values and rules.Applicationcontains repositories, feature state, use cases, events, and service protocols.Infrastructureimplements persistence, security, SSH, SFTP, and LLM clients.Featurescontains SwiftUI presentation and sends intents to Application.Platform/macOScontains AppKit adapters.Appconstructs dependencies and owns application/window lifetimes.
Domain must not import SwiftUI, SwiftData, AppKit, Ghostty, CSSH2, or OpenSSL. Views must not construct network clients, access SwiftData/Keychain directly, or coordinate cross-domain cleanup. Runtime side effects belong to application services and durable outbox handlers.
State lifetimes
- Repository snapshots are application-wide and shared by every window.
- A window owns one top-level shell, quick-open, and context-panel state.
- The shell always starts with two pinned routes:
Vault, thenAssistant. Dynamic tabs after them are SSH/SFTP Workspaces only. - Vault owns its navigation column, including quick-connect Recents, and routes for Hosts, Keychain, Snippets, Welcome, and Host Editor. These routes never enter the Workspace deck.
- Known Hosts management belongs to the Host Editor draft for both new and existing Hosts. Context-panel Host details are read-only.
- Assistant owns its conversation list through
AssistantLibraryModel; conversations are not panes and do not participate in Workspace drag, split, close, or reconnect lifecycles. - A workspace owns only SSH/SFTP panes plus its session-scoped assistant conversation. Workspace content is full width and has no left sidebar.
- Session models own live SSH/SFTP resources and terminal/file-browser state.
- Settings is a native singleton macOS
Settingsscene, outside window routing.
Repository data is persistent truth. Runtime connection state is kept in a connection registry and is never persisted onto domain records.
Agent runtime and security
AgentRuntime is an actor holding a run's state — transcript snapshot, tool
registry, steering queue, secret broker — and the loop over it. Each phase of
the loop is a separate value it drives:
AgentContextPipelinerewrites what is sent at the model boundary: tool results reordered to match the calls they answer, orphaned results dropped, older results trimmed head-and-tail, session context inserted in front of the turn it describes. It shapes only the request. Run snapshots and stored history keep everything.AgentTurnDriverstreams one assistant turn and assembles its tool calls.AgentToolSchedulerplans and runs the turn's batch.AgentToolExecutortakes one call through schema validation, preflight, the card, hooks, authorization, and execution, in that order.AgentEventChannelis the single ordered path for events, fanning out to the UI and to a serial durable recorder.
OpenAI Responses, OpenAI Chat Completions, Anthropic Messages, and Gemini are adapters at the LLM boundary. Models without tool capability receive no tools. Stop cancels the active stream and actions that have not started; steering messages are consumed at the next turn boundary.
A turn's tool calls run concurrently only when every call in it is marked
parallel; one sequential call makes the whole turn serial rather than being
fenced into its own segment. Concurrency is declared per tool and may be
overridden per call by preflight — ssh_exec is parallel exactly when
CommandRiskClassifier proves the command safe, the same evidence that decides
its safety. MCP tools are parallel by default; a server's destructive hint or
Ask First makes them sequential, so remote metadata can only tighten
concurrency, never grant it. Whatever the order of execution, results reach the
transcript in the order the model asked for them, and every call is answered
even when the turn is cancelled or refused — an assistant turn with unanswered
tool calls is rejected outright on the next request.
Approvals and agent questions are queued and presented one at a time. Run state is derived from what is outstanding rather than asserted by whichever call moved last.
Extension points, all additive: AgentToolProviding for tool sources,
AgentLoopHook for willExecute / didExecute / shouldStop,
AgentContextTransforming for the model boundary, AgentModelStreaming for
providers. Authorization is deliberately not among them — AgentApprovalHandling
is a structural stage of the executor that no configuration can remove, and
hooks run on either side of it.
Tools never receive a reference to the interactive PTY. Server commands use a
dedicated SSH exec channel and file operations use run-scoped SFTP clients.
Vault secrets are resolved behind AgentHostResolver. User-entered secrets are
single-use handles bound to run, tool, host, and purpose; plaintext is passed
directly to the executor and is excluded from model input, reviews, events,
logs, and SwiftData. Fetch treats public HTTP(S) reads as locally read-only and
routes private or otherwise non-public unicast targets through the active
permission policy. DNS is revalidated on every redirect; a redirect that first
enters a restricted origin pauses for another authorization decision. Explicit
request headers follow every redirect, including cross-origin redirects, to
match curl -H -L; sensitive values are redacted from review, UI, and durable
history. MCP discovery retains schemas and annotations, but remote annotations
are risk hints rather than proof of safety.
AgentScratchWorkspace is a per-conversation staging directory under Application
Support, inside the sandbox container, deleted with the conversation that owns it.
Paths are relative, .. is refused rather than resolved, symlinks are refused even
when they point back inside, and every resolved path is proven to still be under the
scope; writes are bounded per file, per conversation, and by entry count. It is an
actor, so it is also the per-path mutation queue — a read and a write of the same
file in one batch serialize there rather than by taking the whole turn serial, which
is why every scratch tool is parallel. scratch_pull and scratch_push move bytes
between a host and the workspace without the bytes entering the transcript, so a
remote file can be pulled, edited and pushed back without a copy of it crossing the
model boundary in either direction; scratch_edit returns a unified diff rather than
the new file for the same reason. The SFTP tools are unchanged and know nothing about
the workspace. Because a push is approved by filename rather than by content, its
preflight puts the size, digest and a redacted head into the approval reasons, and
binds the approval to that digest through execution-only metadata so a file rewritten
while the user was deciding is refused rather than written.
The permission modes share structural validation but differ at the action gate.
Safety is a property of the call, established locally: locallyReadOnly for calls
proven to change nothing, locallyContained for calls that change only storage the
app owns, and requiresAuthorization for everything else. The first two are allowed
in every mode — a staging area that has to be approved into is not a staging area,
and dialogs nobody can act on teach the reader to click through the one that matters.
- Ask for approval executes locally proven read-only and contained calls and presents every other action to the user.
- Approve for me sends those same non-read-only actions to Security Review. Missing credentials, timeout, transport errors, or malformed review JSON fail closed and are persisted as review failures.
- Full access skips action approval and Security Review while retaining host-key, secret, schema, host/path, fetch protocol/header/address-classification, sandbox, and tool-capability boundaries.
Agent conversations, runs, visible messages, tool calls/results, and reviews are
stored in SwiftData after truncation and redaction. Launch marks unfinished runs
interrupted; history is restored but remote actions are never resumed or
replayed.
A process that dies mid-batch — force quit, crash, the OS reclaiming the app —
leaves tool calls that nothing answered, which the next request would be
rejected for. Restore closes that in two steps. Results are recorded as each
tool finishes but their transcript rows wait for the run's next snapshot save,
so loadConversations first materializes any recorded result whose transcript
row was never written. Whatever is still unanswered is answered at the model
boundary by AgentUnansweredToolCallRepair, which says the outcome is unknown
rather than that the tool did not run: the process died after the command was
dispatched, and a model told otherwise would repeat it.