Sam Rolfe
81f9722eee
The runbook now holds the recorded result, not only the steps. - Key source: PAPERCLIP_API_KEY in environment.d/10-secrets.conf. - Job: AUD-55 (d58891ce-9934-4710-9bba-d37974251ed9), closed done. - Result: "The Hub round trip works." - Announce: POST http://192.168.20.13:8501/announce, HTTP 200. Co-Authored-By: Paperclip <noreply@paperclip.ing>
98 lines
3.6 KiB
Markdown
98 lines
3.6 KiB
Markdown
# Central AI Hub — AI Agent Runbook
|
|
|
|
> **Writing Style**: ASD-STE100 Simplified Technical English (`ste-writing`).
|
|
|
|
## Phase 1 — Prove the Paperclip Round Trip
|
|
|
|
This phase has no Hub code. It proves the missing link: a job that leaves and a
|
|
result that returns.
|
|
|
|
### Steps
|
|
|
|
1. Create a Paperclip agent API key for this project. **DONE.**
|
|
- Paperclip board: `http://192.168.20.13:3100`.
|
|
- Agent: `Hub`, id `108c6220-c9e1-4b62-9e0a-6a763e0d28fd`.
|
|
- Key name: `hub-service`.
|
|
- The key is stored in `/home/sam/.config/environment.d/10-secrets.conf` as
|
|
`PAPERCLIP_API_KEY`. Never commit it.
|
|
- Verification: `GET /api/agents/me` with the key returns `200` and the name
|
|
`Hub`.
|
|
- Note: `POST /api/agents/{id}/keys` is **board-only**. A run JWT gets
|
|
`403 Board access required`. Mint keys with the local board key.
|
|
2. File one job with the round-trip script. The script uses the issue-create
|
|
endpoint: `POST /api/companies/{companyId}/issues`.
|
|
- The old `POST /api/issues` route does not exist. It returns `404`.
|
|
- Company id: `d4921013-e5da-4d88-8016-57d5746e2d03`.
|
|
- Script: `scripts/paperclip-roundtrip.sh`.
|
|
3. Confirm the job appears in the Paperclip board. **DONE.**
|
|
- The first job is `AUD-55`, id `d58891ce-9934-4710-9bba-d37974251ed9`.
|
|
4. Wait for the agent to close the job. **DONE.**
|
|
- `AUD-55` closed as `done` at `2026-10-10T06:21:03Z`.
|
|
- The agent comment on `AUD-55`: "The Hub round trip works."
|
|
5. Send the result to Jervis `POST /announce` so the house speaks it. **DONE.**
|
|
- See the announce call and the response below.
|
|
6. Record the result in this file. **DONE.**
|
|
|
|
### Commands
|
|
|
|
```bash
|
|
# File one job with the script. It reads PAPERCLIP_API_KEY from the
|
|
# environment, then from ~/.config/environment.d/10-secrets.conf.
|
|
scripts/paperclip-roundtrip.sh \
|
|
--title "Hub round-trip job: confirm the return path" \
|
|
--description "Prove the outbound Paperclip path." \
|
|
--assignee 403de1f7-645c-4d35-bc7e-19b01d77bacc \
|
|
--priority high \
|
|
--project 7ae791bb-8d9a-462f-99bf-013421d20623
|
|
|
|
# Speak the result.
|
|
curl -sS -X POST http://192.168.20.13:8501/announce \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"text":"The Hub round trip works."}'
|
|
```
|
|
|
|
### Recorded Result — 2026-10-10
|
|
|
|
The round trip works. This table holds the proof.
|
|
|
|
| Item | Value |
|
|
|---|---|
|
|
| Key source | `PAPERCLIP_API_KEY` in `/home/sam/.config/environment.d/10-secrets.conf` |
|
|
| Key name | `hub-service` |
|
|
| Agent | `Hub`, id `108c6220-c9e1-4b62-9e0a-6a763e0d28fd` |
|
|
| Job identifier | `AUD-55`, id `d58891ce-9934-4710-9bba-d37974251ed9` |
|
|
| Job result | "The Hub round trip works." |
|
|
| Job final status | `done`, at `2026-10-10T06:21:03Z` |
|
|
| Announce call | `POST http://192.168.20.13:8501/announce` |
|
|
| Announce response | HTTP 200, text "The Hub round trip works." |
|
|
|
|
The script wrote this line to `.state/paperclip-roundtrip-issues.log`:
|
|
|
|
```text
|
|
2026-10-10T06:20:48Z d58891ce-9934-4710-9bba-d37974251ed9 AUD-55
|
|
```
|
|
|
|
Note: Jervis has no playback-telemetry endpoint. Thus the HTTP 200 code and
|
|
the spoken reply are the strongest available proof of the announce. The
|
|
announce ran one time.
|
|
|
|
### Definition of Done
|
|
|
|
- The job appears in Paperclip. **DONE.**
|
|
- The job closes. **DONE.**
|
|
- The house speaks the result. **DONE.**
|
|
- This file records the result. **DONE.**
|
|
|
|
## After Phase 1
|
|
|
|
Follow the build order in `AGENTS.md`. Do not start a destination before the
|
|
round trip works.
|
|
|
|
## Health Checks
|
|
|
|
```bash
|
|
curl -s http://192.168.20.13:3100/health # Paperclip
|
|
curl -s http://192.168.20.13:8501/health # Jervis
|
|
curl -s -o /dev/null -w '%{http_code}\n' http://192.168.20.30:8123/ # HA
|
|
```
|