small gleam coding and persistent agent daemon with a detachable cli and a canvas ui forked from okami.mom/albedo
albedo robot-docs workspaces.md
11 kB · 203 lines
Markdown

Workspaces #

A session workspace identifies the directory where its work runs. The daemon represents it as a local path or an SSH location. Worktrees are separate checkouts that can supply a workspace.

Locations #

location.parse accepts local strings beginning with / or ~, and remote locations of the form [user@]host:/absolute/path. Bracketed IPv6 addresses are supported. Remote paths are normalized lexically. This does not resolve filesystem links. User and host names must begin with a letter or digit.

location.workspace validates an existing local directory when a session is created or moved. It resolves remote ~ through SSH, but accepts an absolute remote path without checking its existence at that point. A later operation can fail when the host or directory is unavailable.

location.exists observes a local or remote folder without opening it. An unreachable host returns an error, not a missing-folder result. The remote probe and gather retain their separate time bounds.

Path completion #

GET /sessions/{session_id}/file-paths?query=<text>&limit=8 (capability file_path_completion: 1) returns {items: [paths], truncated}. daemon/file_paths.gleam owns matching and ranking; http_resources resolves the stored session workspace. Bare queries search that workspace and return relative paths. Starting ~ or ~/ anchors at the session host's home, ./ at the workspace, and / at that host's filesystem root. The directory through the last slash is a literal scan root; only the remaining tail fuzzy-matches descendant relative paths. Results retain that directory prefix (~ becomes ~/). No ~user expansion is performed. A missing directory fails without broadening the search. Explicit ./../ is allowed: completion is not a workspace sandbox. Local enumeration belongs to daemon/file_paths.gleam; remote enumeration uses the existing SSH gather route file-paths, including home expansion on that host, never a local fallback.

Enumeration uses ripgrep (rg --files --hidden --no-require-git), respecting ignore files, excluding .git and .jj, and not following directory symlinks. Ripgrep must be installed on the workspace's machine; otherwise the request fails 503 workspace_unavailable. Commands stop after two seconds or 2 MiB of path output, retaining at most 20,000 candidates. Only complete UTF-8 paths of at most 4096 bytes are kept. The output/candidate cap sets truncated; the bounded subset need not contain the globally best match when the tree exceeds a cap. Ranking within that subset is deterministic. A timeout fails rather than pretending there are no matches. Anchored scans that encounter filesystem errors after emitting paths return that partial subset as truncated; errors without paths still fail. Bare workspace queries retain their strict error behavior. Bare / and ~/ may hit the same caps or timeout; supplying a directory narrows enumeration before it starts. There is no retained index or session-turn work.

Queries are case-insensitive subsequences, ranked by matched positions and remaining length, then lexicographically. Empty queries list shortest paths first. limit is 1–50; queries accept at most 256 UTF-8 bytes and no NUL. The endpoint never reads file contents. CLI and web replace an @ token with a plain path (JSON double-quoted when it contains whitespace), preserving the rest of the draft; submission and attachments are unchanged.

The terminal and web clients expose this as composer suggestions.

Linked workspaces #

links stores workspace group membership. Linked workspaces retain their own data while group readers can include the other members. Linking and unlinking are separate from creating a worktree.

The links extension owns membership changes and session notifications. See its service and ledger. Group reads also include managed worktrees of each origin, as links.members shows. The ledger declares workspace_links with its revision tables, because the extension's initialiser creates it through links.apply and its ledger writes it.

Moving a session #

session_workspace records workspace changes and tracks their application to family members. A session configuration change and its application are distinct outcomes. The session configuration owner and session workspace owner govern the persisted state.

Moving a session between daemons is a separate transfer. transfers owns export and import, and http_transfers defines the HTTP routes. transfer/codec owns the segment format and streams rows through SQLite statements prepared on the caller's connection. Its module comment defines the cell encoding. Keep segments byte-identical across changes. The golden case in transfer_codec_test.erl pins the bytes and digest of a known export. Transfer adapters declare which extension data travels. See carry rows when a session moves for an adapter's tables, shifts, and activation. A transfer is not ongoing synchronization between the daemons. After a move, extensions reach the session's new daemon through host.Context.ask_moved, and refuse arrivals for it through extension.Daemon.tell_refused and hook_gone. These callbacks keep relay and refusal behavior with moves.

Each owner keeps its stored states as a type with one codec for the stored and HTTP spelling. transfers owns TransferState and TransferRole, and moves owns MoveState and the binding status. A move reads the target's import state through transfers.parse_state. Build SQL state literals from the codec, and do not match a state's name in text.

Moves between versions #

Moves between daemons of different builds are supported in one direction only, from an older daemon to a newer one. Both must speak the same transfer.protocol. The source checks the target's protocol before it exports.

A move to an older daemon is unsupported when the carried schema differs. The export lists every carried table and every column in the manifest, including empty tables. An older target does not know a table or column added since its build. It refuses the manifest at staging, in transfers.known, when a segment:

  • names an extension the target lacks (transfer_unsupported), or one built in there that failed to load (transfer_extension_unavailable; older targets answer transfer_unsupported)
  • names a table that extension does not carry there (transfer_unsupported)
  • has a different table version (transfer_version)
  • has a column the target's table lacks (transfer_version, as owner/table here lacks column)

The source keeps the target's detail, which names the first thing it lacks, and reports transfer_version as transfer_target_older (relays.staged). It keeps transfer_unsupported, because a target from before transfer_extension_unavailable gives it both for an older build and for an extension that failed to load. The move then fails before anything goes live on the target, and before the target writes a receipt or staging directory. The source keeps the session, its bindings stay armed, and it still takes input.

The preflight asks the target before a move starts, through POST /transfers/check (transfers.check). The source sends transfers.shape: every table the export would list, with its version and this daemon's columns, without rows. It also sends one file entry for each owner that carries files and no tables, such as memory, when that owner has files to send. The target runs the same known checks and nothing else. It reads table columns, and writes no receipt or directory, runs no expiry, and checks no space. The check knows which extensions are quarantined, so the source reads a missing extension or table from it as transfer_target_older (relays.checked), and transfer_extension_unavailable stays as it is. Either makes the preflight unavailable with that code and the target's detail. A target from before the route answers 404 or 405. The preflight then offers the move, and staging refuses what that target lacks.

Clients read these codes for a person and keep the target's detail as secondary text. transfer_target_older asks to update albedo on the target. transfer_extension_unavailable says the extension failed to load there, with no update advice. transfer_unsupported names both causes. See the terminal client and the web client.

The daemon has no ordered version to compare. /server reports a build label and digest, which tell two builds apart but not which is older. The schema checks are what decide.

Keep older-to-newer moves working:

  • Keep adapter names stable. The target finds a segment's adapter by its owner name, so a renamed or removed adapter refuses segments from older daemons.
  • Keep the segment format byte-identical, as the codec requires.
  • Do not bump a carried table's version. The target accepts only its own version, so segments from older daemons would be refused.
  • Settle rows imported from an older daemon in the adapter's activate, as webhooks does.

move_versions_test.py moves a session from a pinned older build to this checkout, and checks that the reverse move is refused cleanly. move_test.py checks that the preflight refuses a target of this build that lacks a column, and writes and expires nothing there. transfer_check_test.gleam covers each refusal code, including a quarantined extension. See mixed-version moves.

Starting an older daemon on a whole home that a newer one upgraded is a different case. See downgrades.

Browsing #

folders.directory returns a directory listing for the folder picker. The same module owns file reads and existence checks. Remote locations use the location and SSH handling in that module, so an unavailable host is a distinct failure from a missing local directory.