Skip to content

feat(backends): add Beads (bd) storage backend - #53

Open
RooseveltAdvisors wants to merge 27 commits into
kunchenguid:mainfrom
RooseveltAdvisors:fm/tasks-axi-beads-backend
Open

feat(backends): add Beads (bd) storage backend#53
RooseveltAdvisors wants to merge 27 commits into
kunchenguid:mainfrom
RooseveltAdvisors:fm/tasks-axi-beads-backend

Conversation

@RooseveltAdvisors

Copy link
Copy Markdown

What

Implements the existing pluggable Store seam (src/store.ts) for the Beads issue tracker: a second backend alongside markdown, selected via .tasks.toml backend = "beads".

Why

We run agent fleets where the dispatch pipeline (fm-spawn, session-start, backlog handoff) calls tasks-axi, while task truth lives in a Beads graph (Dolt-backed, dependency edges, bd ready). The adapter removes double bookkeeping: one CLI surface (tasks-axi), pluggable storage (markdown or beads). Our fleet has been running it in production across ~25 agent homes for the last day.

Design notes

  • ID preservation: tasks-axi slug ids map 1:1 to bd issue ids via bd create --id (bd rejects ids outside its prefix; we validate before invoking). No sidecar mapping needed.
  • Post-call verification: transitions/deps verify the requested result against bd's actual response, not mere task existence - a silently no-oped update surfaces as an AxiError.
  • Holds: map to a tasks-axi-held label; hold.until mirrors native --defer; clearing uses bd's documented clear operation.
  • Dependency reasons: bd has no native edge-note field, so reasons persist in a versioned base64url metadata header (tasks-axi:beads/v1) in the issue description; same header carries kind/repo and archived-body bookkeeping.
  • Timestamps: native bd created/closed timestamps are used (no preservation encoding - deliberate ponytail cut).
  • Capabilities: deps=true, fullTextSearch=true, comments=true, customStates=true, serverMintsIds=true, publicFollowups=false, prune=false.
  • markdown backend untouched: deriveLinks was extracted to shared src/links.ts (net negative lines); markdown behavior and tests unchanged.

Testing

353 lines of fixture-mocked tests: CRUD round-trip, transitions with post-call verification, dependency add/remove with reason encoding, prefix rejection, bd's structured missing-issue shapes, hold persistence and dated-hold clearing, config resolution. Full suite green.

Config

backend = "beads"

[beads]
path = ".beads"        # .beads directory (or its parent)
binary = "bd"          # bd on PATH
prefix = "bd"          # expected id prefix for slug validation

@LeonidShamis

Copy link
Copy Markdown

Please check PR #52 - it looks like we worked on the same feature

@RooseveltAdvisors

Copy link
Copy Markdown
Author

I checked PR #52. It is a second, overlapping Beads backend implementation (with a different config shape plus mirror, prune, and real-bd conformance work), not an unrelated change. Both PRs cannot be applied independently without overlap. Since #52 is still open and there is no explicit supersession or rejection signal, I’m leaving #53 open pending your direction on which implementation to keep.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants