Uh oh!
There was an error while loading. Please reload this page.
fix(skill): document bundle postings and topic ID resolution - #157
fix(skill): document bundle postings and topic ID resolution#157joshRpowell wants to merge 2 commits into
Conversation
There was a problem hiding this comment.
Pull request overview
This PR corrects the bundled agent guidance in skills/hey/SKILL.md so that AI agents no longer treat an Imbox posting id as a topic ID when calling hey threads or hey reply. As described in issue #156, hey box --json does not guarantee a topic_id, and passing a posting ID to hey threads requests /topics/<posting-id>/entries, which returns 404. The updated skill distinguishes posting IDs from topic IDs and instructs the agent to fall back to the topic ID in app_url when present, or direct the user to HEY otherwise.
Changes:
- Updated the box response-format note to clarify that
topic_idis not currently guaranteed in posting output. - Rewrote the "ID note" so agents extract the topic ID from
app_url(/topics/<id>) and avoid substituting the posting ID when no topic route exists.
Tip
If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The previous revision told agents to give up whenever a posting's app_url
was not topic-shaped. That discards the bundles that wrap a single message,
which carry their topic in app_bundle_url and read fine — 70 of 238 bundles
(29%) in a 500-posting sample.
Document the two posting kinds instead. A kind=topic posting always has a
/topics/ app_url; a kind=bundle posting has a contact-shaped app_url and is
resolvable via app_bundle_url only when it wraps one message. A bundle of
several messages names a contact rather than a thread, so no topic ID exists
for it and there is no CLI command to list its contents.
Also correct the documented envelope ({ok, data:{...}} rather than
{box, postings}), note that a bundle's name concatenates several subjects,
and state plainly that no posting carries a topic_id rather than that one is
not "guaranteed".
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>A bundle posting's app_url names its sender's contact page, so the topic_id resolved out of it was always zero and hey box view --json served bundle rows with no way to read the thread they open. haystack's bundle_posting route points app_bundle_url at a topic exactly when the bundle holds one unseen thread — the thread the row opens in the web app. mail.TopicIDOf now tries app_url and falls back to app_bundle_url, so those rows carry a usable topic_id in the CLI's listings and the TUI alike. A bundle with several unseen threads (or none) still answers zero, and the skill now says what a bundle row is, that topic_id can be absent on one, and to reach the bundled mail through hey contacts unbundle rather than passing the box item id to hey threads. Surfaced by #157, which documented the workaround; resolving it in the CLI keeps the skill's contract (every posting names its thread where one exists) true instead.
robzolkos
commented
Aug 24, 2026
Closing as superseded. The core complaint — the skill documenting a |
The embedded skill documented a
topic_idon everyhey boxposting. No live posting carries that field, so the documentedbox→threadsworkflow fails.This corrects the guidance to describe what postings actually carry. Agents resolve a topic ID from the first
/topics/<id>URL a posting offers —app_urlon akind: "topic"posting, orapp_bundle_urlon akind: "bundle"posting wrapping a single message. A bundle wrapping several messages names a contact rather than a thread, so no topic ID exists for it; agents are told to direct the user to HEY rather than substituting the posting ID, which 404s as/topics/<posting-id>/entries.Measured on a 500-posting Imbox: 262 topic postings, 70 single-entry bundles resolvable via
app_bundle_url, 168 multi-message bundles unresolvable. Readingapp_urlalone would give up on all 238 bundles.Also corrects the documented response envelope (
{ok, data:{...}}, not{box, postings}) and notes that a bundle'snameconcatenates several subjects.This is a docs-only change to bundled agent guidance; it does not make unreachable bodies readable. Bundle expansion is tracked in #156.
Validation:
GOCACHE=/private/tmp/hey-cli-go-build make testPost-Deploy Monitoring & Validation
No additional operational monitoring required; this only corrects bundled agent guidance and has no runtime service behavior.
Summary by cubic
Clarifies ID handling in the HEY skill so
hey threads/hey replyalways use a topic ID and never a posting ID. Updateshey box --jsondocs with the correct{"ok": true, "data": {...}}envelope, defineskind: "topic"andkind: "bundle", states postings don’t includetopic_id, and explains resolving topic IDs fromapp_urlorapp_bundle_url(single-message bundles); multi-message bundles have no topic ID and should be opened in HEY.Written for commit 90be0bb. Summary will update on new commits.