62 lines
3.2 KiB
Markdown
62 lines
3.2 KiB
Markdown
|
# 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.
|