# halkyon_learn_agent

Halkyon Learn's agent (Halkyon's ADR 0044, D6, D7, D10, D49 to D52): an account of its own on an
instance, made in a person's Profile (Agents) and invited as a Viewer to the studysets they share
with it. It reads their cards and notes and **suggests**: changes, new cards and notes, reports of
what should go, replies. It never writes into a studyset; its Owner and Editors accept or decline
in the app (a studyset's Suggestions). Claude Code, or another MCP client, reaches it over stdio.

## Using it

On the machine it runs on, as a user of its own (D7; halkyon.li's host at home):

1. Build and copy it there from a laptop with Dart, `tool/install.sh <ssh target>` (D52). It builds
   for the laptop's architecture (`dart build cli`, libsodium and SQLite bundled; the host needs
   no Dart) into `~/.local/lib/halkyon-agent/<commit>`, `~/.local/bin/halkyon-agent` pointing to
   it, the build before kept.
2. Sign in once with the token its owner copied from their Profile, on stdin, never as an
   argument others on the machine could see:

   ```
   $ halkyon-agent --instance https://halkyon.li sign-in < token.txt
   ```

   It keeps the token, makes its key pair and sets the public halves on the register, syncs and
   says how many studysets are shared with it.
3. Let Claude Code start it:

   ```
   $ claude mcp add halkyon -- ~/.local/bin/halkyon-agent --instance https://halkyon.li mcp
   ```

`halkyon-agent --instance … sync` syncs once, e.g. to see that it still can.

## Its tools

`list_studysets`, `read_studyset` (title, description, topics, cards and notes as plain text),
`search_cards`, `suggest_card_change`, `suggest_new_card` (front and back, or a vocabulary
card's word, reading and meanings), `suggest_note_change`, `suggest_new_note`, `report`,
`list_suggestions` (with replies and what was decided) and `reply`. Only studysets shared with it
count. Each call syncs first and a suggestion syncs again at once; a sync that fails leaves what
it holds to read, and the result says so. A refusal (a studyset not shared with it, a card it
can't find) is the tool's error, which the model reads.

## What it keeps

`$XDG_CONFIG_HOME/halkyon-agent/<host>[_<port>]/` (else `~/.config/…`), the folder 0700 and its
files 0600, refused when others may read or change them (D50): `token`, `keys.json` (its key
pair, unsealed: its user's boundary protects it), `keys_set`, `sync.sqlite` (the shared
studysets, opened as the app opens them), `key_pins.json` (the members' public keys as first
seen), `privacy.json` and `files/`. An instance is reached over HTTPS, or plain HTTP on the same
machine alone. Its session is kept in memory, a sign-in with the token at every start.

## Code

- `lib/src/open_agent.dart` signs in and opens its data as the app's `_openPersonData` does, on
  `halkyon_learn_core` (its gateways and repositories) and `halkyon_content` (keys, shared
  spaces, files).
- `lib/src/agent_library.dart` reads and suggests, `lib/src/agent_server.dart` makes tools of it
  (`dart_mcp`), `lib/src/agent_sync.dart` syncs on demand, `lib/src/agent_home.dart` keeps its
  files; `bin/halkyon_agent.dart` is the CLI. Tests run on the core's fakes, without a server.

Licensed under the AGPL-3.0.