# 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` |