Skip to content

Add the app→agent queue (operations, tasks, events) to blueprint-pocketbase-react #22

Description

@ahmad-ajmal

Summary

blueprint-pocketbase-react is the only runnable blueprint without the app→agent direction. Its PocketBase hooks adapter (pb/pb_hooks/_a2app.pb.js + _a2app_impl.js) serves identity, describe, and the record create/update/delete guards. It has no:

  • operations endpoint: there is no /api/ops/{name} route, so operations declared in operations.json (the starter's archive-done, for one) are listed by describe but cannot be invoked.
  • task queue: no /api/_a2app/tasks routes, so nothing can be queued for an agent and agent-app <dir> bridge has nothing to deliver.
  • events: no /api/_a2app/events.

reference/blueprint.md currently tells authors to record this as a known limitation, or pick another blueprint. Every other runtime blueprint (react-node, go-react, rust-react, rails-vue, python-fastapi) carries the queue.

Proposal

  1. Operations:
    • Endpoint: POST /api/ops/{name}.
    • App-owned code: a seam where the app's own operation code lives, with trigger available beside the store.
    • Access: same-origin View calls allowed on single-user apps, the agent token required otherwise.
    • Approval: destructive operations need approval (428 + approval key), matching the other adapters.
  2. Task queue and events, matching the other adapters' wire format:
    • Endpoints: GET /api/_a2app/tasks[?status=], GET /tasks/{id}, and POST …/claim | progress | complete | cancel.
    • Events: GET /api/_a2app/events.
    • Lifecycle: trigger(type, payload, capability) refuses undeclared event types. The same occurrence dedupes to one task. A claim lapses without a heartbeat and the task is redelivered, failing as redelivery_exhausted after the delivery limit.
    • Storage: tasks and events persist across restarts in the app's data directory.
    • Discovery: identity advertises the queue so agent-app <dir> bridge finds it.
  3. Runtime constraints: hooks run in PocketBase's Goja runtime, not Node. Handlers can't close over file scope (each one require()s the impl), and storage goes through $app/$os. The pure rules (dedup key, lifecycle transitions, sweep) go in _a2app_rules.js, so node … --selftest in the gate covers them.
  4. Starter and View:
  5. Docs: replace the "no app→agent queue in v0.1" section of reference/blueprint.md with how to declare events, fire trigger, and show the work.

Acceptance

  • Bidirectional conformance: a pocketbase-react app passes the Class C (bidi) conformance suite: task poll, claim, claim contention (409 task_not_claimable), progress, completion.
  • Real run: clicking "Ask an agent" in the starter queues a task that agent-app <dir> bridge start delivers to a real harness. The View shows it waiting, working and done (or failed, with "Ask again") without a reload.
  • Gate: the blueprint's gate self-test covers the new rules, and a fresh scaffold passes validate's "agent work shown in the View" step.
  • Version: verified against PocketBase v0.26.6, the only version the adapter supports.

Activity

  1. self-assigned this
    on Oct 5, 2026
  2. linked a pull request that will close this issuefix: pocketbase kit #25on Oct 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions