Private UI controllers and session repositories
The assembled terminal host can select implementations for the editor, approvals,
questions, local forms, placement settings and history. These are behavior
replacements: rendering, input, state and teardown belong to the controller.
The compositor retains window geometry, focus routing, workspaces and drag/resize.
Existing ui.render and appearance hooks continue to customize portable views
and decoration.
Selection and modules
A trusted native plugin exports a named controllers factory map from its main
module. It can export controllers without exporting hooks. Selection is explicit:
{
"enabledPlugins": ["workspace-ui", "conversation-store", "session-manager"],
"ui": {
"controllers": {
"editor": "workspace-ui",
"approval": "workspace-ui",
"question": "workspace-ui",
"form": "workspace-ui",
"placement": "workspace-ui",
"history": "workspace-ui"
}
},
"sessionProvider": "conversation-store"
}
Omitted entries use the standard implementation through the same controller
registry. A missing or failed explicit selection does not silently select the
standard behavior. An unavailable editor shows an error; unavailable approvals
deny, forms cancel and questions reject. The selected plugin must be enabled.
The standard /history, /sessions, /resume, rename, archive and fork command
entry points belong to session-manager; a composition may omit that contribution
and supply its own commands instead.
The configured OpenTUI frontend
supports selected editors in Main and selected approval, question and private-form
controllers in Main and independent request windows. Selected history and
placement implementations have their own independent windows. Only their validated views/cells reach the renderer;
the original private request is not attached as hidden native fallback data.
Unavailable selections fail closed when opened, without a native replacement.
Portable appearance now updates native semantic colors/chrome without replacing
selected owners; explicit controller-cell colors remain literal. Public render
overrides apply only to public presentation slots, including the Main transcript;
they cannot replace private request/editor frames or acquire their inputs.
Full wire adaptation remains a migration gate. The host can
inspect selection through core.host.controllers.selectedOwner(kind), which
returns metadata without creating a controller or receiving private input.
Controller selection is partial. For example, with an enabled workspace-ui
plugin, "ui": {"controllers": {"form": "workspace-ui"}} replaces only local
forms; every omitted kind keeps its host implementation. Unknown kinds and
empty provider names remain configuration errors.
UiControllerFactory, UiController, UiControllerInput, UiEditorState and
UiEditorIntent are exported by @agent-compositor/hooks.
AppUiControllerData, UiApprovalResult and UiHistoryIntent from
@agent-compositor/app describe this host's private requests and results.
export const controllers = {
editor: ({ state }, { signal, invalidate }) => {
let text = state?.text ?? "";
return {
snapshot: () => ({ text, cursor: text.length }),
preferredRows: () => 3,
render: () => ({
hint: "F2 sends",
lines: [{ text: "Workspace input", bold: true }, { text }],
}),
handle(input) {
signal.throwIfAborted();
if (input.kind === "text") text += input.text;
if (input.kind === "key" && input.key === "f2") {
const submitted = text;
text = "";
return { type: "submit", text: submitted };
}
},
dispose() { text = ""; },
};
},
};
A factory receives {kind, data, state?} and {signal, invalidate()}. Creation
and render({columns, rows}) are synchronous. Views use UiTextView; direct
terminal controllers can additionally provide validated protocol cells per line.
preferredRows(columns, maxRows) requests bounded space. pointer(row, col)
returns a local default, pointer or text hint. Rendering and measurement
are pure: mutation services, state writes and recursive invalidation are rejected.
The renderer executes no plugin code and receives only protocol frames/cells.
handle(input) may return a promise. Extension inputs are serialized, rejected
on disposal, and late results cannot submit or settle another request. Controllers
must cooperate with the supplied signal for work they start; synchronous JS
cannot be preempted, and already-started effects are not undone. The private
controller channel has no automatic hook timeout; the selected implementation
owns its input algorithm. Unload, replacement, UI close and session transitions
clean up leases. A valid editor snapshot is retained before disposal so a reload
can pass the draft to the next instance, even when disposal erases local state.
Configuration selection follows existing restart behavior; /reload reloads
implementations under the current configuration.
Approval and question controllers occupy the input dock rather than locking other windows. Their keyboard input is routed when the dock has focus; mouse input outside the dock can focus and operate other panes and the toolbar. A settings form may coexist in the main area. The agent remains suspended until the dock receives an answer, denial or cancellation.
Requests and results
| Kind | Private data | Result from handle |
|---|---|---|
editor | Session ID, command discovery, optional file discovery; state is {text,cursor} | `{type:'submit' |
approval | Tool identity, descriptor and reason | `{allow:boolean,scope?:'once' |
question | Question/options or questionnaire with stable question IDs | {answer: UserQuestionAnswer} or 'cancel' |
form | Validated UiForm declaration | UiFormResult or 'cancel' |
placement | windows(), anchors(), async apply(id,placement,save?) | 'close'; placement changes use apply |
history | Session ID/query, async control(action,args), local form(request) | 'close' or {type:'resume',id,name?} |
No result means the interaction continues. Editor and dialog text/key input is routed to the active controller; mouse coordinates are local to its content. Placement retains the panel's full frame coordinate convention. Fixed tiling shortcuts remain routed by the host. Raw terminal function keys F1–F12, including modifiers, pass through the reference renderer instead of being discarded by Ink's text-input adapter.
In OpenTUI Main, selected private requests start in Draft mode. Alt+I or the Answer/Draft button switches between their input and the resident message draft, preserving the draft and its cursor. A separate request window gives input to its selected controller when that window is focused. Closing a window only hides the live lease; Windows reopens it with controller-owned state. The host reserves Alt+W Arrange, Alt+0 Main, spatial/workspace shortcuts and Ctrl+C cancellation before controller input. F2 reaches a selected editor only while its available Draft owns focused Main in normal mode. In Answer mode, another window, Finder, Arrange or an unavailable editor, F2 Windows remains a host control. Alt+W, then W, and the Windows button always remain available. Other unreserved function keys reach the selected controller only while it owns input. Selected request controllers retain host F2 precedence. A selected local form in Main does not block a new ordinary message from Draft mode while the agent is idle. The form remains pending during that model turn. Selected questions and approvals still require their own answer or decision.
Delegated and managed request windows bind factories to the actual producing Core's registry, rather than Main's registry. Their safe host title identifies the request and agent without adding private prompts, tool arguments or form values. Same-name siblings have separate request identities and controller leases. Hide/reopen retains a pending lease; settlement, source cancellation or unload revokes it. Main resume revokes Main descendants, while independent managed agents' pending requests retain their own lifetime. The Ink frontend also uses the producing registry, with its existing shared dialog queue. Reload changes the reloaded Core's registry. An already-running child's selected lease belongs to that child's original registry; disabling and reloading its provider only in Main does not unregister that child provider. Actual source unload or source Core closure revokes the child lease. New children use the parent's current composition.
OpenTUI keeps the selected editor's factory, command/file discovery capabilities
and {text,cursor} checkpoint inside the host. The cursor is a UTF-16 offset;
it is not a native textarea's display-cell offset. Only its rendered view and
bounded input/admission receipts reach the frontend. The native composer stays
parked, and an unavailable selected editor shows a constant error instead of
accepting native input. Window navigation remains usable.
Editor input is serialized through handling, admission and recovery. Busy submit and steer intents retain Core's queue semantics without answering a pending question. The host shows Accepted or Queued once ownership is taken. A genuine pre-admission rejection restores the visible pre-input draft and cursor before later admitted editor inputs run. An accepted prompt hook, command or model failure does not restore the cleared draft or resubmit it. See Core input admission for the separate admission and completion receipts. Reload and interactive session resume retain a validated checkpoint before disposal. Old-generation handles and asynchronous capabilities cannot submit into the replacement Core. Unsent drafts do not survive process exit. Editor scroll intents scroll the transcript without changing window focus.
Controller lines occupy individual clipped terminal rows; optional validated cells preserve their colors and text attributes, including wide characters. The controller receives actual content viewport dimensions; its hint occupies a separate host row. Portable action rows, tabs and table rows send declared action IDs; a declared input uses the semantic change channel. Raw key, text and bracketed-paste input otherwise goes directly to editor, request and placement leases. Placement mouse input retains the reference panel's full-frame origin: the first content cell is row 2, column 1. Other raw controller mouse input uses local content coordinates. Selected lines retain the foreground/background selection pair, including validated rich cells. Optional controller pointer-shape hints are not yet projected by this frontend; native window-navigation pointers remain host-owned. The host checks request identity and the displayed revision before admitting a mouse/action input. Already admitted asynchronous inputs remain serialized when the controller invalidates its own view. A later navigation action can suppress continuation autofocus without discarding the admitted answer.
History uses semantic {kind:'action',action} and
{kind:'change',id,value} inputs from portable view actions and input fields.
It receives open after creation. control supports list (search and archived
filter), rename, fork, archive and unarchive. Resume is an explicit returned
intent so the host can close the old pane before changing the UI subscription.
The history controller owns selection, filtering, paging and presentation.
In OpenTUI, named history keys become semantic actions (enter, escape,
up, down, pageup, pagedown); a native query input keeps the factory's
declared field ID. History does not gain a separate raw text/mouse contract.
Canonical /history, /sessions and /resume browse routes run outside the
model prompt queue, including while Main waits for an answer. Browsing does not
create an empty conversation journal. Explicit extension commands with the same
name retain their existing owner. Session mutations and resume still use the
ordinary controls-ready and canonical service/repository checks.
History and placement factories, leases and callable capabilities remain inside
the application. Each admitted input waits for its window's preceding operation
and an available UI slot, then receives a fresh foreground operation; an idle
view holds no slot. A history input receives a fresh trusted instance-bound API
without broadcasting its raw input or frame through ui.press, ui.change or
ui.render. Deliberate control calls retain the ordinary session service chain
and its necessary search/name payload; this does not hide those values from an
explicit service provider/interceptor. Local form results remain private.
Closing a window through Arrange hides its live state. Ctrl+C closes its selected history/placement controller and cancels the pending input; plugin Escape/close actions follow the controller's own serialized input logic. Reload, provider unload and Core replacement revoke old capabilities and queued input. A private history resume keeps its view until the host commits the new Core. Rejection keeps that same view with a constant notice. Cancellation while preparing the replacement closes the prepared Core and leaves the current one in place. A successful transition still expires old capabilities and respects newer navigation. Registered semantic plugin windows retain their saved tiling identities, closed state and ratios when the same owner exists in the new Core; their old content/input sources are replaced. Placement validates the target, neighbor and declaration before saving, then rechecks the same window identity and operation before applying geometry. A write already started may persist after cancellation; that does not authorize a stale in-memory move or focus transfer.
Requests, drafts and local form results travel directly to the selected factory;
they are not broadcast catalog payloads. Editor and form rendering bypasses
unrelated ui.render hooks. The wire necessarily contains the visible editor
text; a password controller must render a mask. The host validates form field
IDs/types, required values, select values and HTTP(S) URL fields before resolving
the requester. An advertised cancel action discards field values without
requiring completed fields and resolves $.ui.form as null. Approval results require a boolean decision and a recognized
scope; malformed results deny. Question results still pass through the normal
questionnaire validation in core. Existing permission policy remains binding.
Custom host form handlers can reuse
validateUiFormResult(request, value) from @agent-compositor/events. It returns
only declared fields after validating the action, field types, required values,
select membership and HTTP(S) URLs. For cancel, it returns an empty values
object before the hook API normalizes the result to null. Validation errors contain no submitted values.
The OpenTUI private adapter gives the selected factory a detached request copy;
its result validation retains the originally admitted declaration and question
choices, even if the factory or requester later mutates its own copy.
core.host.setFormHandler(handler) returns a disposer that clears the handler
only while that binding is still current. Disposing a superseded binding does
not clear or later revive another owner's handler.
Core-based hosts should use core.setHumanFormHandler(handler) when delegated
children need the same private form channel and authentic producing-Core context.
The lower-level host setter configures only that single HooksHost. See
host human channels for callback and lifetime semantics.
Native form views treat a declared action with ID cancel as cancellation:
it returns null without collecting or validating fields. Escape and the host's
Cancel control have the same result. Other actions require a valid form result.
Trusted plugins can also call
$.ui.controller(kind, data, fallback, invalidate, state?) to select a private
controller for their own workflow. Those leases are revoked with both the
requesting plugin and the selected provider. This API and $.ui.form are private
host capabilities rather than events. Trusted JavaScript runs in-process;
these privacy boundaries are API routing guarantees, not an OS sandbox.
Complete session storage replacement
A trusted native module can export:
export async function sessionRepository({
cwd, sessionsRoot, stateRoot, signal, config,
}) {
// Open the chosen backend and return the complete SessionRepository interface.
return repository;
}
SessionRepository, SessionRepositoryContext and SessionRepositoryFactory
are public exports of @agent-compositor/session. The interface is structural:
no inheritance from SessionStore, filesystem directory or JSONL file is needed.
It requires create, append, load, list, search, findByPrefix, fork,
rename, archive, unarchive and remove. Optional dispose releases resources;
optional root supports callers that explicitly need a local path. A backend
without root works in the assembled application. Preserve session metadata,
ordered replay events, project scoping and supplied search cancellation.
sessionProvider selects one plugin's factory before startup resumption. The
same stable repository router serves journaling, the history services, interactive
resume, headless --resume and independent-agent restoration. The normal local
store is the default. Backend failures propagate instead of reading unrelated
local history. The existing service.session.append seam can independently
replace journal behavior; a composition selecting it must keep its writes and
chosen repository consistent.
Reload gates new storage calls, drains in-flight operations, opens the candidate
backend, validates/replaces the core contribution and commits the backend.
Initialization/validation failures retain the current repository. Retired
backends are disposed; cleanup errors are recorded in the router's
cleanupErrors without reverting an already committed backend. Application close
drains writes and disposes once. Changing provider does not migrate records:
remote concurrency, transactions, credentials and migrations belong to that
backend. General plugin settings and agent-window bookkeeping still use the
separate configuration/storage services.
Verification
packages/app/test/controllers.test.ts loads the external test-only module in
tools/visual/controller-plugin, replaces behavior and storage, checks private
input, unload cancellation, reload draft preservation and startup/interactive
resume. Hooks and session package tests cover routing, pure rendering, async
cancellation, in-flight write draining and failed replacement.
npm run visual:controllers drives the actual PTY with F2/F3/F4/F5, checks
approvals/questions, masked forms, placement settings, custom history search and
resumption after process restart at 60 columns. VISUAL_EXECUTABLE selects a
built distribution. It uses fake credentials and a scripted/loopback model.
The fixture repository is test evidence, not a production storage implementation.
Standard placement/settings/question/history scenarios remain regression checks.