Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 95 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -431,6 +431,30 @@ released 0.27.25 and 0.27.10 binaries as processes:
mod's bridge stops, and Ask AI offers only its providers.
- A CLI before 0.19.24 writes no ready file: commands wait their full 45 s /
15 s and say "Starting…", and decisions still arrive at exit.
- The tool's `list` and `close` (contract v2): a CLI without
`/api/host/status` lists its reviews with `unsent: unknown`. `close` counts as
closed ONLY a JSON answer with a numeric `unsentAnnotations`
(`classifyHostCloseAnswer` in `controller.ts`): 0.24–0.28.3 answer a JSON
`404` and 0.19.24–0.23.x (before the `/api/*` 404 guard, #748) their app page
with `200 text/html`, and both read as "an older Plannotator", never as
closed. A CURRENT CLI with host control turned off (remote mode) answers
`404 { code: "host_control_disabled" }` instead, which the mod never TERMs:
the close reports that the review runs in remote mode and should be closed
from the tab. Only for an older CLI does the mod TERM the process
(`STOP_SCRIPT`), and only if the launch's `result.json` / `exit` is still
absent and the pid still names a `plannotator` process (`ps -o args=`);
nothing answering on the port (a stale or reused pid after a reboot) is never
signalled, and where `ps` cannot verify a pid (missing, as on Debian slim
without procps, or without `-p`, as BusyBox's) the script signals nothing
and the close says the review was left running. In every such case the close
reports failure. After a TERM close, a decision record without `closedBy` (or an
older CLI's exit 0) is the reviewer's and is delivered as usual. **Remaining
window:** these CLIs publish a decision only after a 1.5 s post-decision
sleep and nothing on their HTTP surface says a decision is pending, so a
decision the reviewer makes in the ~1.5 s before the TERM is lost (and those
CLIs had already deleted the draft on submit; the feedback archive record
survives where it is on). A CLI with the endpoint has no such window: its
close is refused with `409` once the reviewer decided.

**Commands.** `/plannotator-review`, `/plannotator-annotate` and
`/plannotator-last` keep their names (spec open question 7, conservative): when
Expand Down Expand Up @@ -518,6 +542,45 @@ only its name until it searches; with the updated skill it searched and called
the tool for "open notes.md in plannotator", while a profile still holding the
older installed skill text loaded that skill and ran the CLI instead.

**Contract v2: session ids, `list` and `close` (agent sessions, 0.29).** Every
review the mod opens has a session id, `pn-` + the six hex digits that end its
launch id (`sessionIdOf` in `controller.ts`; unique among the session's open
launches). The tool result's first line is `Session: pn-3f2a9c`, and every
decision turn's first line names it (`plannotatorDecisionHeading`:
`Plannotator: notes.md (pn-3f2a9c) — Feedback · 3 comments.`); slash-command
output is unchanged. `action: "list"` reports the reviews opened in THIS Claude
session, by the tool or by the user's `/plannotator-*` commands (the launch
store is already per session id; the global `sessions/` registry is never
read): id, kind, subject, url, age, state and `unsent: N` from the server's
`GET /api/host/status` (`unknown` for an older CLI). `unsent` counts only the
reviewer's own draft comments (`countUnsentDraftComments`: entries without a
`source`, so review-agent, WebMCP and linter findings are not counted, plus
code review's PR description and PR comment notes).
`action: "close"` takes `session: "pn-…"` or `"all"` and calls
`POST /api/host/close` (see "Host session control" under Server API): the
reviewer's Close, marked `closedBy: "agent"`, with the draft KEPT and the open
tab told over the external-annotation SSE (`session-closed`, which the editor
and review app show as "Closed by the Agent" with the unsent count). The result
reports how many unsent comments stay saved as a draft. The copy promises no
restore beyond each surface's own draft key (`agentClosedSubtitle`: annotate
drafts come back for the same unchanged document, code review drafts for the
same changes; path-keyed annotate drafts are #1710). Nothing is delivered for
that review afterwards (the launch is marked `closedByAgent` and settles with
one log line), except a decision record WITHOUT `closedBy`, which is the
reviewer's and is delivered. Plan reviews are listed but never closed (`close
all` skips them, a plan id is refused). An id this session did not open is "not
found". Against an older CLI the mod falls back to `TERM` under the checks
described in "Version skew" above (`stopArgv`), which ends the server without a
decision and never deletes a draft. The contract also
accepts `target` as a list for annotate (validated, duplicates dropped, a
one-item list is the plain call) and reserves `action: "reply"` (`session`,
`comment`, `text`, `resolve`) for live comments; until bundles and live
comments ship the mod answers a list of several files with
`PLANNOTATOR_TOOL_BUNDLE_UNAVAILABLE_TEXT` and `reply` with
`PLANNOTATOR_TOOL_REPLY_UNAVAILABLE_TEXT`, launching nothing. The tool
description does not advertise lists or `reply` yet. Design:
`.product/drafts/agent-sessions-0.29/DESIGN.md`.

**Agent-run CLI commands are taken over (Bash).** Because the tool is deferred
and the skill also documents the CLI, Claude sometimes runs
`plannotator annotate x.html --gate --json` in Bash anyway; that blocked the
Expand Down Expand Up @@ -1303,6 +1366,7 @@ During normal plan review, an Archive sidebar tab provides the same browsing via
| `/api/external-annotations` | POST | Add external annotations (single or batch `{ annotations: [...] }`) |
| `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`). The body is allowlisted and field-validated by `validateAnnotationPatch` (`@plannotator/core/external-annotation`, both runtimes) with the SAME validators POST applies — `diagramAnchor` / `htmlAnchor` / `elementContext` / the target arrays through their own fail-closed parsers, `inReplyTo` through `validateReplyTarget`, the scalars by type and cap. A bad value is `400`, unknown keys are dropped, `id` and `source` stay immutable, and `null` clears an optional field but is refused on an anchor or a structural one |
| `/api/external-annotations` | DELETE | Remove by `?id=`, `?source=`, or clear all |
| `/api/host/status` | GET | Host-only (see "Host session control" below): `{ kind: "plan", documents: [], unsentAnnotations, decided }`. A plan review has no host close (`POST /api/host/close` answers `409 { code: "not_closable" }`). |

### Review Server (`packages/server/review.ts`)

Expand Down Expand Up @@ -1339,6 +1403,8 @@ During normal plan review, an Archive sidebar tab provides the same browsing via
| `/api/external-annotations` | POST | Add external annotations (single or batch `{ annotations: [...] }`) |
| `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`). The body is allowlisted and field-validated by `validateAnnotationPatch` (`@plannotator/core/external-annotation`, both runtimes) with the SAME validators POST applies — `diagramAnchor` / `htmlAnchor` / `elementContext` / the target arrays through their own fail-closed parsers, `inReplyTo` through `validateReplyTarget`, the scalars by type and cap. A bad value is `400`, unknown keys are dropped, `id` and `source` stay immutable, and `null` clears an optional field but is refused on an anchor or a structural one |
| `/api/external-annotations` | DELETE | Remove by `?id=`, `?source=`, or clear all |
| `/api/host/status` | GET | Host-only (see "Host session control" below): `{ kind, documents, unsentAnnotations, decided }`; counts only, never comment text |
| `/api/host/close` | POST | Host-only: the reviewer's Close marked `closedBy: "agent"`, KEEPING the draft; tells open tabs over the external-annotation SSE (`session-closed`) and answers `{ unsentAnnotations }`; `409 { code: "already_decided" }` once decided |
| `/api/agents/capabilities` | GET | Check available agent providers (claude, codex, tour, guide, cursor, opencode, pi, copilot) |
| `/api/agents/review-profiles` | GET | List launchable review profiles (enabled skills + builtin default) |
| `/api/agents/skills` | GET | List all discovered skills for the add-a-review picker (each flagged `enabled`) |
Expand Down Expand Up @@ -1401,9 +1467,38 @@ During normal plan review, an Archive sidebar tab provides the same browsing via
| `/api/external-annotations` | POST | Add external annotations (single or batch `{ annotations: [...] }`) |
| `/api/external-annotations` | PATCH | Update fields on a single annotation (`?id=`). The body is allowlisted and field-validated by `validateAnnotationPatch` (`@plannotator/core/external-annotation`, both runtimes) with the SAME validators POST applies — `diagramAnchor` / `htmlAnchor` / `elementContext` / the target arrays through their own fail-closed parsers, `inReplyTo` through `validateReplyTarget`, the scalars by type and cap. A bad value is `400`, unknown keys are dropped, `id` and `source` stay immutable, and `null` clears an optional field but is refused on an anchor or a structural one |
| `/api/external-annotations` | DELETE | Remove by `?id=`, `?source=`, or clear all |
| `/api/host/status` | GET | Host-only (see "Host session control" below): `{ kind, documents, unsentAnnotations, decided }`; counts only, never comment text |
| `/api/host/close` | POST | Host-only: the reviewer's Close marked `closedBy: "agent"`, KEEPING the draft; tells open tabs over the external-annotation SSE (`session-closed`) and answers `{ unsentAnnotations }`; `409 { code: "already_decided" }` once decided |

All servers use random ports locally or fixed port (`19432`) in remote mode.

### Host session control

`GET /api/host/status` and `POST /api/host/close` (`packages/shared/host-control.ts`,
vendored to Pi; Bun adapter `packages/server/host-control.ts`, Pi adapter
`apps/pi-extension/server/host-control.ts`) let the agent session that launched a
review ask what it holds and close it. Guarded exactly like the pull bridge: a
loopback Host naming the server's port (`403`), no `Origin` (`403`), and
`Authorization: Bearer <token>` (`401`), the launch's `PLANNOTATOR_SESSION_BRIDGE_TOKEN`
(Bun default; servers also take `hostControlToken`). Without a token the paths answer
`404 { error: "Not found", code: "host_control_disabled" }` (`HOST_CONTROL_DISABLED_CODE`),
which a host reads as "turned off" rather than "an older Plannotator" (an uncoded `404`);
they are off in remote mode, and
`--tailscale` discards the env token. Unlike the pull bridge they still answer under
`PLANNOTATOR_AI=disabled` (closing a review is not an AI feature). Once a session is
decided (a host close included), the review servers refuse a late `/api/feedback` or
`/api/exit` with `409` (both runtimes, like annotate), so a tab still open after the
close neither deletes the kept draft nor gets an ok for feedback nobody receives.
Close settles the decision as `exit` with
`closedBy: "agent"` and `unsentAnnotations` (no draft delete, no feedback-archive
record: the reviewer decided nothing), broadcasts `{ type: "session-closed", by:
"agent", unsentAnnotations }` on the external-annotation stream (`broadcast` on both
runtimes' handlers; `useExternalAnnotations`'s `onSessionClosed`), and the CLI's
host result record carries the same `closedBy` / `unsentAnnotations` on its
`dismissed` record. Every server result also exposes `hostControl` (`status()`,
`close?()`) for hosts that run the server in-process (Pi, the OpenCode 2 embedded
plan server). Plan servers implement status only.

### Paste Service (`apps/paste-service/`)

| Endpoint | Method | Purpose |
Expand Down
Loading
Loading