small gleam coding and (not yet) persistent agent daemon with a detachable cli forked from okami.mom/albedo
albedo robot-docs README.md
5.1 kB · 101 lines
Markdown
at main

Robot documentation #

Implementation references for models and engineers working on Albedo. The pages link related topics and the code that owns each contract.

Change Albedo collects the project rules for ownership, runtime helpers, lifecycle, storage, providers, and testing. Topic pages add guidance specific to their interfaces.

For documentation changes, follow the wiki authoring instructions and the repository agent instructions.

API and operator guides #

Runtime and sessions #

  • Runtime: startup, preparation, tool calls, and kernel ownership.
  • Sessions: input, live output, cancellation, and history.
  • Operations: durable admission, receipts, and recovery.
  • Inbox: every input a session will read, in order, and the queue.
  • Agents: child sessions, mail, and verification.
  • Workspaces: locations, linked workspaces, and session moves.
  • Worktrees: checkout providers and session attachments.
  • Settings: configuration, preferences, and persistence.

Kernel and tools #

  • Kernel: Python execution, jobs, and kernel lifecycle.
  • Kernel state: saved variables and restoration.
  • Context: request inspection and accounting.
  • Compaction: projections, strategies, and retained history.
  • Files: reading, editing, and searching files.
  • Artifacts: versioned content, previews, and client communication.
  • Image generation: drivers, references, output, and recovery.
  • Command shims: Nix and Cargo wrappers on job PATH.
  • Direnv: workspace environment updates.

Extensions and commands #

  • Extensions: the harness base, installation, selection, and composition.
  • Write an extension: the checklist extension as a worked example of tables, a Python binding, a command, a hook, a transfer adapter, cleanup, registration, and daemon scenarios.
  • Extension API reference: function documentation, signatures, types, and SDK navigation.
  • Plugins: extension contribution contracts.
  • Commands: command catalogs, invocation, and clients.
  • Hooks: model and Python call hooks, verdicts, and command helpers.
  • Skills: discovery, activation, and resource reads.
  • MCP: configured servers, editor servers, and Python calls.
  • Web search: search bindings and provider selection.
  • Paperclips: model reports and user review.

Providers and usage #

  • Authentication: provider credentials and sign-in.
  • Models: catalogs, model selection, and limits.
  • Provider requests: transport, recorded attempts, and usage.
  • Outbound proxies: direct or proxied outbound routes per service.
  • Proxy: the OpenAI-compatible endpoint and request translation.
  • Quota: account readings and polling.
  • Usage feed: the usage-core driver and consumers.
  • Cache TTL: policy data, precedence, and refresh.
  • Cache warming: background requests and stop conditions.

Clients and integrations #

  • TUI: terminal client state, views, and rendering.
  • Change a terminal screen: shared components, keys, confirmations, and asynchronous requests.
  • Web client: browser state and the local web server.
  • ACP: editor attachment, prompts, output, and MCP overlays.
  • Webhooks: signed intake and session delivery.
  • Discord: bot configuration, messages, and delivery.
  • Computer use: the CUA binding and driver lifecycle.
  • Colab: runtime management and remote connections.

Development and release #

  • Testing: concurrency, fixtures, and cleanup.
  • Gleam checks: lint rules and review profiles.
  • Workspace packages: reusable Gleam packages under packages/, their dependency direction, and how to add one.
  • Migrations: storage changes, startup order, and the downgrade refusal.
  • Performance: measurement commands, metrics, and gates.
  • Release: builds, packages, and smoke tests.