oc
725d17d3eb
A follow-up question on a task produced no event at all, so an unattended conversation stalled silently. --comments polls the account's assigned tasks (including done ones, where follow-ups land) and fires for comments written by anyone else. Guards: comments by the account itself never fire, so a replying agent cannot wake itself; on first sight of a task the newest comment id is adopted without firing, so enabling this does not replay history; the comment id is recorded before the command runs, so a wedged harness is not relaunched every poll.
158 lines
6.1 KiB
Markdown
158 lines
6.1 KiB
Markdown
# vikunja-agents
|
|
|
|
git clone https://git.dominat.us/oc/vikunja-agents.git
|
|
|
|
Public read, push restricted to the owner. On `reptar` the working copy is
|
|
`/srv/pods/vikunja-agents/`, which is also where the quadlets and the Claude Code
|
|
MCP registration point.
|
|
|
|
|
|
Harness-agnostic glue between Vikunja and agent harnesses. Standard library
|
|
Python only — no virtualenv on any device.
|
|
|
|
This file is the how-to. For why the design is shaped this way — the MAS SSO
|
|
constraints, the API-token limits, why polling instead of webhooks, and the
|
|
known gaps — see [`/srv/pods/docs/agent-collaboration.md`](../docs/agent-collaboration.md).
|
|
|
|
| File | What it is |
|
|
|---|---|
|
|
| `vkclient.py` | Shared API client. |
|
|
| `vk` | CLI. Any harness that can shell out is integrated. |
|
|
| `vikunja_mcp.py` | MCP server (stdio). Any harness that speaks MCP is integrated. |
|
|
| `vk-watch@.service` | systemd template for the per-device task watcher. |
|
|
|
|
## The model
|
|
|
|
- **Task** = unit of work. **Assignee** = which agent owns it. **Comments** =
|
|
the thread. **Labels** = routing and state.
|
|
- **Outbound** (agent → Vikunja): `vk` or the MCP tools, authenticated as that
|
|
bot, so its actions are attributed to it in the UI.
|
|
- **Inbound** (Vikunja → agent): `vk watch` polls the bot's own assigned queue
|
|
and runs a command per new task.
|
|
|
|
### Why polling rather than webhooks
|
|
|
|
Harnesses live on several machines. A webhook receiver would need an inbound
|
|
port on each device (or SSH fan-out from one host), and Vikunja's WebSocket is
|
|
not an alternative: it authenticates with a JWT only (API tokens are rejected by
|
|
`auth.GetUserIDFromToken`) and its subscribable events are notifications and
|
|
timers — there are no task events to subscribe to. Polling needs only outbound
|
|
HTTPS, so a device behind NAT or on another subnet works with no extra config.
|
|
|
|
## Onboarding an agent
|
|
|
|
Hand [`AGENT-ONBOARDING.md`](AGENT-ONBOARDING.md) to the agent as a task prompt —
|
|
it covers token bootstrap, MCP registration per harness, verification, and the
|
|
constraints that otherwise get rediscovered the hard way.
|
|
|
|
## One-time setup per bot
|
|
|
|
Agents run as Vikunja **bot users**: local accounts owned by a human, with no
|
|
password of their own. Create one in the UI (Settings → Bot Users); the `bot-`
|
|
prefix is reserved for them and `vikunja user create` will refuse it.
|
|
|
|
A bot cannot mint its own token — `tokens` is not a token-grantable route group,
|
|
and there is no password to log in with. The owner issues it instead, with
|
|
`owner_id` set to the bot's user id (UI, or `PUT /api/v1/tokens`), and the agent
|
|
stores it:
|
|
|
|
```sh
|
|
vk profile bot-nullclaw --username bot-nullclaw < token.txt # reads stdin, verifies, 0600
|
|
```
|
|
|
|
`vk bootstrap` remains for legacy password accounts only.
|
|
|
|
This mints a scoped token and writes `~/.config/vikunja-agents/config.json`
|
|
(mode 0600). The username is stored alongside the token because `/user` is
|
|
unreachable with an API token, so `vk whoami` and `--mine` read it from there.
|
|
|
|
Default grants: tasks (read/create/update), comments, assignees, labels,
|
|
projects (read + `projectusers` for username lookup). Override with
|
|
`--permissions`; `vk bootstrap` intersects your map against the live `/routes`
|
|
and reports what it dropped rather than failing at creation.
|
|
|
|
## Deploying a watcher to a device
|
|
|
|
Applies equally to this host, the Spark, and any other server.
|
|
|
|
```sh
|
|
# 1. Copy the tools and put `vk` on PATH
|
|
mkdir -p ~/.local/bin ~/opt/vikunja-agents
|
|
scp vk vkclient.py vikunja_mcp.py <device>:~/opt/vikunja-agents/
|
|
ln -sf ~/opt/vikunja-agents/vk ~/.local/bin/vk
|
|
|
|
# 2. Bootstrap that bot's token on that device
|
|
vk bootstrap --username bot-nullclaw
|
|
|
|
# 3. Confirm it sees its queue before wiring systemd
|
|
vk watch --once --dry-run -- nullclaw --task '{task_id}'
|
|
|
|
# 4. Configure and start
|
|
cat > ~/.config/vikunja-agents/watch-bot-nullclaw.env <<'EOF'
|
|
VK_WATCH_ARGS=--interval 30 -- nullclaw --task {task_id} --url {url}
|
|
EOF
|
|
cp vk-watch@.service ~/.config/systemd/user/
|
|
systemctl --user daemon-reload
|
|
systemctl --user enable --now vk-watch@bot-nullclaw
|
|
```
|
|
|
|
**On the Spark, enable linger first** — user services are killed on logout
|
|
otherwise, and the watcher will quietly stop:
|
|
|
|
```sh
|
|
loginctl enable-linger $USER
|
|
```
|
|
|
|
### Placeholders
|
|
|
|
Available in the command: `{task_id}` `{title}` `{project_id}` `{priority}`
|
|
`{labels}` `{url}`. The same values are also exported as `VIKUNJA_TASK_ID`,
|
|
`VIKUNJA_TASK_TITLE`, `VIKUNJA_TASK_URL`.
|
|
|
|
### Replying to comments
|
|
|
|
Add `--comments` and the watcher also fires when **someone else** comments on one
|
|
of your tasks:
|
|
|
|
```sh
|
|
vk watch --comments --interval 30 -- nullclaw --task {task_id}
|
|
```
|
|
|
|
- Scans your assigned tasks **including done ones** — a follow-up question almost
|
|
always lands on a task that was just closed.
|
|
- Your own comments never fire it, so an agent replying cannot wake itself.
|
|
- On first sight of a task the newest comment id is adopted **without firing**, so
|
|
turning this on does not replay the whole history. The flip side: a comment
|
|
already sitting there when you enable it will not fire either. To pick it up,
|
|
delete that task's entry from the `comments` map in the state file.
|
|
- The command gets `VIKUNJA_TRIGGER=comment` plus `VIKUNJA_COMMENT`,
|
|
`VIKUNJA_COMMENT_AUTHOR`, `VIKUNJA_COMMENT_ID` alongside the usual task vars.
|
|
Task triggers set `VIKUNJA_TRIGGER=task`.
|
|
|
|
### Trigger semantics
|
|
|
|
A task fires once, when it first appears as assigned-to-me and not-done.
|
|
Handled IDs are recorded in `~/.local/state/vikunja-agents/watch-<profile>.json`
|
|
**before** the command runs — at-most-once, so a harness that wedges the machine
|
|
is not relaunched on every poll. Entries expire after 30 days. To replay a task,
|
|
delete its ID from that file. Poll failures log and back off to 10 minutes;
|
|
the watcher never exits on an API error.
|
|
|
|
## MCP
|
|
|
|
```sh
|
|
claude mcp add vikunja -- ~/opt/vikunja-agents/vikunja_mcp.py
|
|
```
|
|
|
|
Auth comes from the same config file / `VIKUNJA_PROFILE`. Seven tools:
|
|
list/get/create/update/assign tasks, comment, list projects.
|
|
|
|
## Routing work to a specific agent
|
|
|
|
Assignment is the dispatch mechanism — assign a task to `bot-picoclaw` and only
|
|
picoclaw's watcher picks it up. For finer control, give each watcher a filter:
|
|
|
|
```sh
|
|
vk watch --project 7 --filter "priority >= 3" -- picoclaw --task {task_id}
|
|
```
|