small gleam coding and persistent agent daemon with a detachable cli and a canvas ui forked from okami.mom/albedo
7.0 kB · 134 lines
Markdown

Terminal client #

The Go terminal client lives in cli/internal/tui. It uses Bubble Tea models and the daemon client. The web client is another client of the daemon.

Application and screens #

AppModel owns navigation between chat, session selection, and other screens. Update routes messages to the relevant model and handles transitions such as opening the model picker, webhooks, and Discord pages. listFrame renders shared list-screen framing. pageStatus tracks loading and request generations for pages.

Follow Add or change a terminal screen for shared components, keyboard conventions, confirmation behavior, and stale-request handling.

Chat and events #

ChatModel.Init starts the stream subscription and status requests. The subscription delivers daemon events as Bubble Tea messages. Cancellation and stream termination are handled in the subscription code. Chat transcript state and rendering live in transcript_state.go and transcript.go.

chat_shell.go parses shell input, submits commands through the daemon client, and updates their output in chat. Shell output is external content, not an instruction to the model.

File path completion #

In the chat composer, @ at the start of a whitespace-delimited token opens fuzzy workspace file suggestions. The daemon searches the session workspace by default; @./… explicitly keeps that base, @~/… searches from home, and @/… from the filesystem root, all on the session’s machine. An explicit prefix uses the directory through the last slash literally and fuzzy-matches the remainder. The CLI never scans or reads files. Email addresses, escaped \@, quoted tokens and ! shell inputs do not open it. Queries are capped at 256 UTF-8 bytes.

Up/down chooses among matches; Tab or Enter replaces the whole @token, including any token suffix after the caret, with the chosen path, keeping an explicit ~/, ./ or / prefix. Paths containing whitespace, quotes or backslashes, or starting with a composer dispatch prefix (!, /), use JSON double quotes. Selecting text hides and invalidates completion. Surrounding draft text stays intact. Completion inserts text only: it neither attaches contents nor submits a prompt. Escape dismisses the picker (including a pending search) until the token changes. Pending, empty and failed searches leave normal typing and sending available.

chat_paths.go owns token parsing, picker keys and effects. Requests debounce for 120 ms, cancel when superseded and carry session, generation, workspace and token identities so late replies cannot reopen or overwrite a newer picker. At most eight results are retained; four rows plus the keyboard hint are visible. shot_paths_test.go registers the ready, selected, pending, empty, error and dismissed composer states.

See workspace path completion for the daemon contract.

Reasoning controls #

Chat headers and the model picker prefer the catalog's display name. The session's API ID remains unchanged. The chat loads names through the session-bound model catalog when it opens or its model or provider changes. Late replies must match the chat generation, session, provider, and model before changing the displayed name. Missing names or failed reads fall back to the ID. The same read retains model and profile reasoning defaults so inherited chat headers show the effective level. Unknown levels display Provider default. Unsupported profile levels remain visible in the selectors with an unsupported warning and a model-default bypass.

The model picker separates the effective reasoning level from its source in the details pane. Left and Right choose a level, with the actual default annotated. Ctrl+X resets the staged choice to the profile/model default. When the profile has an override, Ctrl+T switches the staged choice between the profile and model default. Enter applies the choice only to this session. Escape cancels it. Ctrl+S separately asks to apply and save the selected model and reasoning for the named profile. Confirming changes that profile without changing the starting profile.

The chat selector, opened with /effort, uses a vertical list. The actual default level is annotated instead of appearing as a separate row. Up and Down preview levels, Ctrl+X resets to default, and Ctrl+T switches the default source when a profile override exists. Previewing does not save the choice. Enter applies it and Escape restores the composer. The list keeps the highlight visible in short terminals. Models owns the saved choice and provider resolution contract.

Moving a session #

/cd to another host's folder opens the question box. It asks the daemon's preflight, and cd_move.go starts and follows the move when the user chooses yes. An unavailable preflight shows its reason under yes and offers only no.

A target that can't take this daemon's data refuses in the preflight or when a move reaches staging. cdRefusal reads three codes for a person:

  • transfer_target_older: "The target daemon is older than this one and can't accept this session. Update albedo on host."
  • transfer_extension_unavailable: an extension this session uses failed to load there. It gives no update advice.
  • transfer_unsupported: the target may be older, or one of its extensions failed to load there. An older target can't say which.

The target's own words, which name what it lacks, stay below in faint text for debugging. Other refusals show their reason as it came. The shot gallery's cd screen covers these states. The rules behind the codes are in moves between versions.

Screens and tests #

Screen-specific models and rendering live beside the application model. For example, webhooks_page.go and discord_page.go implement their respective pages. Screenshot fixtures and tests live in the same package, including shot_chat_test.go.

The Go client boundary owns typed daemon operations and transport recovery. Follow Change the HTTP API when a screen needs a new public operation.