Architecture map
Compositor separates execution, extension contracts and rendering. Start with the package map to locate implementations, then use this page to follow the active product path.
Application assembly
packages/app/src/main.ts selects terminal, plain or headless mode.
buildApp in packages/app/src/build.ts resolves configuration and storage,
composes model profiles and policy, loads explicitly enabled extensions and
creates the active AgentCore.
Configuration + scoped selections + provider profiles
|
buildApp
|
AgentCore + services + extensions
/ \
Headless AppUI
|
Versioned JSONL protocol
|
Ink / OpenTUI renderer
packages/core contains the active multi-turn engine. packages/agent is a
historical reference loop and pane demo. packages/plugins is a compatibility
facade over the shared packages/loader implementation.
An agent turn
A submitted prompt flows through prompt.submit, input preparation, effective
tool selection and instruction composition. service.agent.run selects the
turn strategy. The default strategy streams the model, executes tool batches
through policy, manages context pressure and checks whether the task can finish.
Tools use tool.call, tool.check and service contracts. Model transport, tool
scheduling, context preparation, compaction and journal writes have replacement
services. Core customization documents selection and
the capabilities a replacement strategy receives.
Events and extensions
The Zod event catalog defines inputs, response forms, aliases and versions.
The runtime dispatches onion handler chains ordered by tier and priority. Hooks
can pass through, await a downstream result, transform an event, answer it or
deny an operation. Runtime budgets and lifecycle signals bound cooperative
asynchronous work. User management actions in the TUI travel through ui.press
and ui.change, independently of the model prompt queue and tool turn. The
built-in managers use replaceable service.extension.control and
service.marketplace.control chains for explicit user operations, keeping model
history and foreground cancellation intact. Plugin file changes requested while
busy are staged until explicit application at idle; plugin reload remains a
composition boundary.
Immediate manifest commands use the separate command.invoke path in both the
TUI and headless core. Only the loaded owner handles an explicit user command;
it can notify, call guarded tools or open a view. Command operations have their
own lifetime, cancellation and auxiliary usage accounting. Their start/settlement
events do not rewrite the running model's task or insert a queued prompt. See
the command contract.
The $ API exposes host services through these contracts. Private controller
requests carry editor and dialog state only to the selected implementation.
They are not broadcast as ordinary event payloads.
The loader validates metadata before importing active code. Filesystem packages remain inactive until explicit user or project selection. A composite package owns all of its hooks, tools, skills, UI and MCP declarations through reload, disable and removal. See the plugin standard.
UI and tiling
The tiling manager owns the window tree, resolved geometry, workspace membership, focus routing and drag/resize. Decorations and contents can be replaced within those rectangles. Editor, approval, question, form, placement and history controllers have selected implementations with input, rendering, state and teardown contracts.
The configured OpenTUI layout adapter supplies optional read-only split-target metadata from the same projected/canonical split selection as keyboard changes. Its copied geometry comes from the readable layout used for pointer hit testing; saved proportions remain separate. The renderer uses it for an Arrange cue and receives no mutable tree or persistence authority. Hidden targets carry a reason without a fabricated divider. This metadata crosses the native presentation protocol as data; the host retains the mutable tree and persistence authority. The adapter uses the same readable projection at every width: a split retains both children when each can receive at least 24 columns and 6 rows. Insufficient areas collapse to their focused branch without mutating the canonical tree or saved ratios. Rendering, split cues and pointer hit testing share that geometry; compact metadata describes an actual single-frame size fallback, not a width threshold or explicit zoom.
Arrange-only Ctrl+arrows select a live directional neighbor from logical geometry and reuse canonical edge-drop retiling. Shift+direction keeps center swap semantics. Unmeasured or missing neighbors leave the tree unchanged; successful retiling retains source focus and clears zoom like a pointer drop.
Configured Main windows separate compositor pane identity, logical conversation identity and Core binding generation. Restored session views use guarded per-pane ports to the same Core/inbox/editor. The renderer keeps one native conversation input/request/editor subtree keyed by logical identity, outside the keyed window tiles, and changes its rectangle when another copy takes focus. Inactive copies render transcript-only views. Public native scroll state is handed off per pane after layout, with cancellation and Core-epoch fencing; no SDK private scroll state is used. Core replacement revokes old ports even when it resumes the same journal ID. It resets transcript scroll while keeping the resident draft/undo and validated editor checkpoint.
The layout admits validated persisted session/Tools/Help descriptors and keeps closed identities available without placing them. Host-owned Tools/Help sources are separate from plugin surfaces and their operation/placement ownership, so plugin reload and Core replacement cannot forget their saved tree positions. Creating a view atomically allocates its bounded ID, descriptor and tree; failures leave the saved layout unchanged. Only window metadata is persisted.
Window-navigation intent is transient and separate from layout revisions or Finder filtering revisions. Explicit navigation invalidates an older operation's permission to autofocus; publication, viewport measurement and persistence do not create new user intent. The host applies that decision before placement or opening can change focus. Trusted service provenance separates retained passive publication from a live user operation, while a current signal-bound Finder attempt can still receive its requested retained destination. This policy does not change plugin lifetimes, command cancellation or the saved tiling tree. An admitted native action consumes its mouse-down before invoking the callback. Opening or moving a window cannot reinterpret that same click against the new layout. Unhandled body, title and separator clicks still reach window selection and gestures normally.
OpenTUI input callbacks are bound to a specific Core generation and captured capability origin. Each UI operation has one private request FIFO; retained background input gets an independent bounded owner. Shared native components render approvals, questions, questionnaires and forms while the host admits responses against the current source generation and request ID. Trusted service scope carries actual plugin-instance lifetime and effective signal outside plugin-writable payloads. Unscoped input keeps Main's FIFO; stale scoped input cannot fall through to Main. Private inbox binding does not replace the Core's global form router. Lifecycle reload emissions explicitly leave expired service scope before constructing fresh plugin capabilities.
Core human callbacks carry a private, immutable producer context generated by the actual Core: instance and root lifetime, originating host, inert agent/parent labels and host-generated tool invocation identity. Provider call IDs are descriptive only. Captured delegated UI authority is separate from this lineage; explicit background/detached work cannot borrow a later ambient UI operation. The context never enters catalog payloads, controller factory data or public render props. Direct immediate-command spawning resolves the normal effective tool composition before constructing the child; already-resolved empty tool compositions remain empty.
OpenTUI gives each delegated or managed human request its own transient private
surface and binds it to the producing host's controller registry. These pending
windows do not occupy the four effectful UI operation slots. Main-generation
replacement revokes Main's descendant requests, while independent managed roots
retain their own Core lifetimes and pending surfaces. BuiltApp.bindHumanRequests
commits the current UI channels for managed agents; preparing another Core cannot
replace that registration. Managed shutdown closes the actual Core before waiting
for a run blocked on input. Ink forwards the same private source context and
inherits its current Core form handler while retaining its existing dialog queue.
Agent management acquires its UI capability through the actual service hook
chain and retains it in an asynchronous caller scope. Concurrent actions cannot
replace each other's owner. Only passive worker repaint may fall back to the
live session-lifetime API after an action finishes; expired foreground focus
authority is never renewed that way. Archive removes the actual current panes
instead of reporting success after skipping stale UI cleanup.
Selected OpenTUI approval/question/form requests reuse the same registry leases and private FIFOs. The host keeps factory data, results, validators and lifetime signals; the renderer receives a distinct validated frame without native request defaults or capabilities. Its guarded input and viewport ports address one request and Core generation. Input admission captures continuation intent before the lease's serialized asynchronous handler runs. Settlement checks the same live lease, without granting fresh focus after an await. Failure denies an approval, rejects a question or cancels a form with a constant diagnostic; controller exception text cannot leak private input into notices or journals. Across the wire, relative key/text input may advance to the current revision of the exact same lease; a field change also requires the current field identity. Mouse coordinates and declared actions still require the exact painted revision. Future revisions, old ports, retired leases and unfocused input remain rejected. The resident Main editor parks while a selected request owns input. Selected editor leases use a separate host adapter because command/file discovery carries callable capabilities. The renderer receives only the validated editor view, availability and input/admission/scroll receipts. Private UTF-16 checkpoints are captured before disposal; serialized input waits for Core ownership rather than model completion. Rejected ownership restores the visible draft before later queued input; an accepted turn failure never restores it. Lifetime-guarded capabilities and captured input-time navigation intent survive neither a Core replacement nor a revoked lease.
Selected history uses the per-Core session contribution's app-private presenter;
it does not serialize a lease, callable data or private frame into the catalog.
HooksHost.withPrivateUiInput(owner, signal, run) admits a loaded trusted owner
with fresh foreground capabilities and actual invocation origin, outside any
retained service scope. There is no catalog hook to continue. Input-local async
storage keeps overlapping old/new APIs distinct, and normal session control
services and the selected repository remain authoritative. Canonical browse
commands use the existing UI command route instead of borrowing a model turn.
Placement has a separate capability-bearing adapter over current plugin windows and anchors. Both private window adapters serialize inputs, wait abortably for the preceding same-window operation and one of four UI slots, and release the slot after each input. Hidden windows keep their leases. Host cancellation, unload and Core replacement revoke pending work. Actual render bounds and completed input receipts protect resident native fields during async updates. Resume captures input-time navigation intent; placement checks target/neighbor identity again after persistence before applying geometry or requesting focus. Session preparation rechecks Core identity, lifetime, caller operation and readiness before committing. A cancelled prepared Core is closed without replacing the current session; a failed private resume retains its history view. Semantic plugin windows whose owner exists in the new Core are detached and rebound to fresh content sources, preserving the workspace's canonical tree, closed identities and split ratios. Transient requests/controllers are disposed.
Each admitted editor input marks fresh user intent before its asynchronous handler runs. Two UI commands therefore cannot share an old continuation's focus priority; a slow first result remains passive after a newer command or edit. Invalid, stale, hidden or unfocused inputs and viewport updates do not renew it.
Portable plugin views may include a catalog 0.27 semantic table: labeled columns, stable rows, ordinary actions and expandable details. Producers own expansion and filter state and republish when data changes. AppUI chooses aligned or stacked rows for the viewport; the core retains a labeled text fallback. The contract does not depend on Ink or grant a plugin permission to execute frontend code. Catalog 0.28 adds semantic tabs with producer-owned selection and ordinary action IDs. AppUI resolves wrapped tab geometry, cell hit ranges and keyboard navigation; plugins do not need to manufacture padded strings or terminal coordinates.
AppUI sends protocol frames to renderer-ink; input returns through that same
protocol. The renderer draws and translates input. It does not own agent state
or execute extension modules. UI controller contracts and
appearance hooks describe the two extension mechanisms.
The opt-in --renderer opentui frontend binds the actual application through
the negotiated native presentation profile of protocol 0.7. A host-only broker
serializes conversation snapshots and semantic plugin sources; renderer-local
adapters reconstruct observable data sources and send identified inputs through
the same protocol. No host callback, Core object or private lease crosses it. The host
retains provider/session/permission ownership and the same tiling engine; the
renderer receives views and revision-checked actions. Explicit UI operations
own separate abort signals and private form windows, so they can coexist with a
pending model question. An optional host-owned window-navigation source exposes
stable Arrange actions and a private, revision-checked window inventory. Native
input capture commits focus before subsequent keys/paste, while resident editors
remain mounted. Opening a declared UI route retains navigation ownership until
its current surface or form is ready; changing selection cancels that opening.
The deterministic preview omits this capability and keeps its development keys.
Native input waits only for a protocol admission receipt. Queued keys and paste
then reach the resident widget selected by the acknowledged host state; Core
generation changes revoke queued old input. Controller completion remains a
separate frame acknowledgment and model work does not block navigation.
The legacy grid OpenTUI client and Ink reuse the same pure protocol grid reducer
while retaining separate toolkit views. Same-log tests compare the actual painted
frames, including unflushed diffs. Native replay additionally needs terminal
input because local draft/undo is not a host snapshot. Wider platform and
terminal evidence remains part of the migration gates; Ink remains the default.
Ink and OpenTUI share validated per-plugin appearance contribution semantics. Valid publications replace one owner and move it to latest field precedence; null/unload removes only that owner. OpenTUI receives an immutable, revisioned merged partial appearance snapshot and applies its own defaults through React context. No plugin function, Core object or private request crosses that source. Theme updates retain resident input/controller identities. Publication-sensitive Tools visibility stays in the host so ordinary decoration updates cannot replay layout intent. Main tool details use exact live call occurrences admitted in the current noninteractive Main turn, excluding UI operations and unknown historical groups; reused provider IDs cannot promote private historical arguments.
OpenTUI's public render adapter owns stable per-pane sources, including separate Main/Tools/Help copies and status. It builds explicit public defaults and calls the normal read-only hook chain, then validates the final portable tree. Numeric drawable measurements and explicit user scroll receipts enter a bounded cache; only current source/viewport/generation results and displayed actions survive. The hook's SDK authority is cancelled as soon as its public input becomes obsolete, while its cache slot follows the host-owned dispatch lifetime. A superseded hook cannot continue the chain or perform SDK effects, and cannot admit another painter by returning an early caller-cancellation receipt. Producer defaults never come from the previous override. Status defaults are host-owned public data; private controller/editor/Finder objects are excluded. Tools' local diagnostic aggregate is not a public render input: only positively admitted Main tool records enter that projection. Native default-scroll memory survives override clamping, while private input owners stay resident.
Streaming text updates are composed on a 16 ms timer instead of rebuilding the
Markdown transcript for every provider delta. The catalog's assistant.text
precursor is still available to plugins; the UI consumes the subsequent rewritten
text notification. Input and lifecycle changes draw immediately and flush pending
text, including turn completion. The Ink renderer enables incremental output.
Native composer images reserve their cell rectangle without also decoding a
portable text-art copy or serializing the RGBA payload into an unused input-view
cache key. The portable image path remains available to its other consumers.
The interactive alternate screen disables terminal autowrap to keep glyph-width
differences from scrolling the entire layout. Autowrap is restored for external
editors and terminal cleanup. Unicode shaping remains terminal-dependent.
Resize clearing is included in synchronized output before Ink clears its previous
frame, avoiding a blank intermediate paint on terminals supporting DEC 2026.
See the performance bench for
observed input/hover latency, output volume and terminal-state comparisons.
Persistence and independent work
The default store journals conversations in project-scoped private storage. Configured journal failures stop further execution and are surfaced live; a terminal success requires a write acknowledgement. Replay closes unfinished tool exchanges with explicit unknown-outcome results without repeating effects. The session repository contract replaces history, journaling, search and resume together. Settings and window metadata have separate storage services.
Headless process signals close the application before its final result. Core and application close calls join the same teardown, including managed agents, foreground shells and retained SDK processes. Caller cancellation can end a long lifecycle hook; a journal failure separately revokes further effects. Terminal outcome observation has a bounded grace with revoked caller authority, while its original journal/UI record remains host-owned. See cancellation and cleanup contracts.
Task children and independent agents have separate execution contexts. Independent agents can also use Git worktrees. Their Saved activity views read explicit snapshots from each child app's session repository router, so custom backends and worktree scopes match execution. Filtering, paging and expandable records stay in the host UI; inspecting journal data does not mutate model context or invoke a provider. Closing a view invalidates pending reads. Workflow stages coordinate bounded workers through a persistent dependency graph. Multiple views of one conversation do not create additional agents.
Background shells are owned by their originating core. The host reports process completion and provides a bounded follow-up queue; the optional background-jobs plugin chooses wake or notification delivery. Waiting does not keep a model stream open. Commands and output retain normal shell permissions, and closing the core drains its workers.
Boundaries to preserve
- Standard host-mediated tool calls retain policy, workspace checks and accounting.
- Explicitly selected missing implementations report errors rather than silently changing providers.
- Reload disposes owned callbacks, processes and controllers and restores supported state.
- Trusted JavaScript runs in-process. Runtime guards and Monty Python execution are not OS isolation for arbitrary shell or native plugin code.
- Generated references describe the current sources; historical design proposals remain labeled as history.
Journal writes use detached JSON snapshots before dispatching
service.session.append. Live execution payloads remain available to hooks,
while local and custom repositories receive the same serializable record shape.
Serialization failures stop effect admission just like storage failures.