## twin

twin watches tangled for mentions of a bot, and gives each
one to an agent in a session in tarp daemon.

twin tails jetstream for `sh.tangled.*` records from the
accounts you choose. it starts an agent in a new tarp
terminal when a record mentions or replies to the bot.

if a session already exists in that context, twin types the
new message into that terminal.

## build

```
nix build
```

or, in the dev shell:

```
nix develop
go build
```

## usage

configure the service using `TWIN_*` variables. `twin
config` shows all of them with their defaults. nixos module
is provided.

```
export TWIN_DIDS=did:plc:qfpnj4og54vl56wngdriaxug        # oppi.li
export TWIN_MENTION_DIDS=did:plc:omwbu2wmkfxrsevklxbxujfx # bot.oppi.li
export TWIN_MENTION_HANDLES=bot.oppi.li
twin
```

| variable | default | |
|---|---|---|
| `TWIN_DIDS` | | accounts to watch. twin ignores all others. |
| `TWIN_MENTION_DIDS` | | the bot, in a record's `mentions` list. |
| `TWIN_MENTION_HANDLES` | | the bot, as `@handle` in a record's text. |
| `TWIN_COLLECTIONS` | `sh.tangled.*` | collections to read. |
| `TWIN_OPERATIONS` | `create` | add `update` to act on edits too. |
| `TWIN_JETSTREAM_HOSTS` | `jetstream.us-east.bsky.network,jetstream.us-west.bsky.network` | the first host, then failovers. |
| `TWIN_TARP_ADDR` | `127.0.0.1:39423` | the tarp daemon. |
| `TWIN_AGENT_COMMAND` | `exec opencode --auto --prompt "$TWIN_PROMPT"` | runs with `sh -c` in the new terminal. |
| `TWIN_JOIN` | `true` | send a mention to the terminal of its thread, if one runs. |
| `TWIN_PROMPT_TEMPLATE` | | a go `text/template` file to replace the built in prompt. |
| `TWIN_STATE_DIR` | `$XDG_STATE_HOME/twin` | the jetstream cursor and the prompts. |
| `TWIN_WORK_DIR` | `$TWIN_STATE_DIR/work` | one directory for each thread. the agent starts there. |
| `TWIN_DRY_RUN` | `false` | log the prompt, start nothing. |

to test the agent on a single record, you can manually
dispatch:

```
twin dispatch at://did:plc:qfpnj4og54vl56wngdriaxug/sh.tangled.feed.comment/3mxs4g5tc5kqs
```

the agent starts in `workDir`, as the tarp user, so let
`user` be the user of the tarp daemon. `environmentFile` adds
more variables. `nix/module.nix` has all the options.

## the agent

the agent gets the task in `$TWIN_PROMPT`, and in a file at
`$TWIN_PROMPT_FILE`. these variables tell it where the
mention is:

- `TWIN_URI`, `TWIN_CID`: the record that mentions the bot.
- `TWIN_THREAD`: the issue or pull of the record.
- `TWIN_KIND`: `issue` or `pull`.
- `TWIN_REPO`: the repository did, if twin found it.
- `TWIN_AUTHOR`: the did of the author.

the tarp terminal also has the environment of the tarp
daemon. put the bot credentials there, for example a goat
login as the bot.