docs(specs): Agent Inbox API v1.1 — adopt the designed UI contract (HT-25)

[zaridan]

Why

The Agent Inbox UI (Claude Design project "Helpthread Agent Inbox Design") was designed against a v1 surface that extends the shipped API in eight ways, each marked CONTRACT ADDITION in its mock-api.js. Decision (maintainer, 2026-07-11): build to the designed contract for v1. HT-25.

What

Amends specs/api/agent-inbox-v1.md in place to v1.1, with a changelog section. Spec only — no code changes. Each addition lands under its own ticket:

• HT-26 — status model active | pending | closed | spam; list filter keeps three folders (open = active + pending, closed, spam); PATCH accepts all four; reply-reopen covers closed AND spam → active
• HT-27 — preview (derived latest-text excerpt) + number (per-deployment sequential, display-only) on summaries
• HT-28 — internal notes: direction: 'note' + POST …/notes; never emailed, never reopens; send-path boundary test required
• HT-29 — tags: tags[] + PUT …/tags (replace-set; trim/lowercase/dedupe; 1–40 chars)
• HT-30 — DELETE …/{id} soft delete; indistinguishable-from-nonexistent everywhere after
• HT-31 — single-Agent assignee 'me' | null + PUT …/assignee (deliberately not identity)
• HT-32 — open tracking customerViewedAt: config-gated, default OFF (privacy stance in the spec); pixel endpoint contract (always 200 + gif, first-view-only, no cookies); byte-identical mail when off, fixture-proven per charter invariant HT-8: mail threading behavioral spec #5

Also on record in the changelog: the prototype's mock simplifies the §4a replay model — HT-16's shipped lease/replay/409 semantics govern, and the UI must handle the 409.

Review focus

• §2 status semantics + migration note (open → active) — HT-26 is the foundational increment
• §4c notes boundary language (mail semantics adjacency)
• §4g open-tracking stance — default OFF is a deliberate product position, worth an explicit yes/no

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Updated the Agent Inbox API specification to introduce v1.1 conversation status semantics, including revised inbox folder filtering.
  • Documented expanded conversation summaries and thread details, including internal agent-only notes and untrusted HTML handling expectations.
  • Clarified read/write behaviors for replying, status updates, tagging, assignment, and v1.1 soft deletion.
  • Added guidance for open-tracking, including config gating, pixel behavior, idempotent view timestamps, and privacy/no-leak expectations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 02d3eeaf-e5dc-4ccf-9693-57804f3202ee

📥 Commits

Reviewing files that changed from the base of the PR and between 3575bd8 and 8b7c730.

📒 Files selected for processing (1)

• specs/api/agent-inbox-v1.md

🚧 Files skipped from review as they are similar to previous changes (1)

• specs/api/agent-inbox-v1.md

---

📝 Walkthrough

Walkthrough

The Agent Inbox API specification is updated to v1.1 with expanded conversation and thread models, revised status filtering, new write endpoints, soft deletion, tagging, assignment, and configuration-gated open tracking.

Changes

Agent Inbox API v1.1

Layer / File(s)	Summary
Conversation and thread read contract specs/api/agent-inbox-v1.md	Defines expanded conversation statuses, assignee and summary fields, ThreadView metadata, open-tracking authentication exceptions, v1.1 inbox folder filters, and deleted-resource read behavior.
Conversation write lifecycle specs/api/agent-inbox-v1.md	Documents reply reopening for closed or spam conversations, status updates, agent-only notes, and soft deletion behavior.
Agent controls and open tracking specs/api/agent-inbox-v1.md	Adds tag replacement, single-agent assignment, configuration-gated tracking pixels, idempotent view timestamps, and updated security and changelog details.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• Helpthread/helpthread#14: Defines the earlier Agent Inbox API v1 contract revised by this v1.1 specification.
• Helpthread/helpthread#16: Updates related Agent Inbox API documentation under the /api/v1 surface.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the spec-only update to the Agent Inbox API v1.1 contract.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/ht-25-agent-inbox-v1-1-spec

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@specs/api/agent-inbox-v1.md`:
- Around line 316-320: Update the pixel endpoint contract in the section
describing its unauthenticated behavior to explicitly exempt it from the global
application/json response requirement. Specify Content-Type: image/gif, the
required cache policy, and the exact 1×1 GIF body, while preserving the existing
200 response, token-blindness, and first-view timestamp semantics.
- Around line 27-28: Update the deployment guidance near the HT-26 status
changes in the agent inbox specification to separate the status migration from
the additive-field partial-deployment note. Mark the active/pending/spam status
and filter changes as requiring coordinated rollout or an explicit compatibility
plan, while retaining the per-field degradation guidance only for nullable or
additive fields.
- Around line 313-318: Update the pixel tracking contract in §4a and the pixel
endpoint description to specify the exact HT-32 route, request shape, and token
format. Define the credential as an unguessable, signed token bound to the
outbound thread rather than exposing or accepting a bare thread UUID, while
preserving the unauthenticated endpoint’s constant 200/1×1 GIF response and
no-leak behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 49cbeee8-1ce3-4d42-a5eb-aa89643d4959

📥 Commits

Reviewing files that changed from the base of the PR and between 5a23c33 and 3575bd8.

📒 Files selected for processing (1)

• specs/api/agent-inbox-v1.md