1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
|
# Feature: Agent Context API
**Status:** [COMPLETED]
**Created:** 2026-01-27
**Updated:** 2026-03-23
**Author:** Architect
---
## Overview
Expose a JSON API that allows external chat agents (e.g., Claude Code, Gemini CLI) to query dashboard context and manipulate items. Authentication uses a notification-based approval flow with agent identity binding.
---
## User Stories
1. [x] **As a user**, I can approve/deny agent access requests from the dashboard UI
2. [x] **As a user**, I can see which agents have been granted access and revoke them
3. [x] **As an agent**, I can request access by providing my name and unique ID
4. [x] **As an agent**, once approved, I can query the 7-day context (tasks, meals, timeline)
5. [x] **As an agent**, I can complete/uncomplete tasks, update due dates, modify details, and create items
---
## Implementation Status
### Phase 1: Auth Flow + Read Context (Complete)
- [x] Agent authentication handshake (Request -> Approve -> Token)
- [x] `/agent/context` endpoint returning timeline + today items
- [x] WebSocket notification for approval requests
- [x] Browser-only agent support (`/agent/web/context`)
### Phase 2: Write Operations (Complete)
- [x] `POST /agent/tasks/{id}/complete`
- [x] `POST /agent/tasks/{id}/uncomplete`
- [x] `PATCH /agent/tasks/{id}/due`
- [x] `PATCH /agent/tasks/{id}` (generic update)
### Phase 3: Create + Management (Complete)
- [x] `POST /agent/tasks` (Quick add)
- [x] `POST /agent/shopping` (Add shopping item)
- [x] Trusted Agent management UI in Settings (list, revoke)
---
## API Endpoints
### Authentication (no auth required)
| Method | Path | Purpose |
|--------|------|---------|
| POST | `/agent/auth/request` | Request access (returns request_token) |
| GET | `/agent/auth/poll?token=X` | Poll for approval status |
### Authentication (browser session required)
| Method | Path | Purpose |
|--------|------|---------|
| POST | `/agent/auth/approve` | User approves request |
| POST | `/agent/auth/deny` | User denies request |
### Context & Operations (agent session required)
| Method | Path | Purpose |
|--------|------|---------|
| GET | `/agent/context` | Full 7-day context |
| POST | `/agent/tasks` | Create task |
| POST | `/agent/tasks/{id}/complete` | Complete task |
| POST | `/agent/tasks/{id}/uncomplete` | Reopen task |
| PATCH | `/agent/tasks/{id}/due` | Update due date |
| PATCH | `/agent/tasks/{id}` | Update details (title, desc) |
| POST | `/agent/shopping` | Add shopping item |
### Management (browser session required)
| Method | Path | Purpose |
|--------|------|---------|
| DELETE | `/settings/agents/{id}` | Revoke agent access |
---
## Files Reference
| Purpose | File |
|---------|------|
| Migration | `migrations/010_agent_tables.sql` |
| Store methods | `internal/store/sqlite.go` |
| Agent handlers | `internal/handlers/agent.go` |
| WebSocket hub | `internal/handlers/websocket.go` |
| Route registration | `cmd/dashboard/main.go` |
| Settings handler | `internal/handlers/settings.go` |
| Settings template | `web/templates/settings.html` |
| Tests | `internal/handlers/agent_test.go` |
|
