AkurAI-Framework / BATCHES.md

Latest change 631417472adebacf9be16c712af89ca5d8a25c28 - Add RustAgent agent OS UI contract by Ólafur Búi Ólafsson

# Feature batches — remaining roadmap

The canonical ledger for finishing the framework's roadmap. Each batch = up to 3
features built as **parallel worktree agents on DISJOINT file sets** (rule: AT
MOST ONE cli-touching feature per batch; the others are a NEW crate or
frontend-JS-only), then the orchestrator merges, gates, wires nav/docs/changelog,
verifies, and runs `./deploy.sh minor`.

Status: ✅ done · 🔄 in progress · ⬜ queued

Anything `std` genuinely cannot do (TLS clients, from-scratch image codecs) is
descoped honestly and documented rather than faked.

---

## Batch 5 — Data engine core ✅ (shipped v0.2.0, live)  → v0.2.0
- `crates/toml` — pure-std TOML parser (unblocks `collections.toml`). [new crate]
- `crates/collections` — collection schema + auto-CRUD records over `akurai-storage`. [new crate]
- `crates/vector` — embedding client (plain-HTTP OpenAI-compatible) + cosine/top-k. [new crate]
- **Integration (orchestrator):** wire `backend/collections.toml` → auto REST API
  (`/api/collections/<name>/records` CRUD) + `?search` (vector ranking, substring
  fallback when no `AKURAI_EMBED_URL`); merge collections into `/api/_meta`;
  scaffold a default `collections.toml`. **Ships: auto-generated REST API + semantic search.**

## Batch 6 — Build pipeline + SQL writes + Admin ✅ (shipped v0.3.0)  → v0.3.0
- (A) **Build-pipeline wiring** [cli]: emit `utilities.css` from `crates/css` on
  `serve`/`dev` (+ watch), and run `crates/assets` (fingerprint + minify, immutable
  cache headers) over static assets. Closes the two "lib, not wired" crates.
- (B) **SQL UPDATE/DELETE** [`crates/sqlexec`]: execute the already-parsed
  `UPDATE`/`DELETE` statements over the B+tree.
- (C) **Admin UI** [frontend-only]: an `/admin` page (native ESM) that reads
  `/api/_meta` and does collection CRUD via the auto-API.

## Batch 7 — Relations, blobs, typed client ✅ (shipping v0.4.0)  → v0.4.0
- (A) **Relations** [`crates/collections`]: a `relation` field referencing another
  collection by id, with `?expand=` on read.
- (B) **File uploads / blobs** [cli + storage]: `multipart/form-data` parsing in
  `akurai-http` + blob storage; a `file` field type.
- (C) **Typed client SDK** [frontend-only]: generate `akurai-client.js` (typed
  collection CRUD) from `/api/_meta`.

## Batch 8 — Frontend platform I ✅ (shipping v0.5.0)  → v0.5.0
- (A) **SSG + ISR** [cli]: pre-render configured routes to static HTML cached in
  storage, with revalidation.
- (B) **i18n** [`crates/i18n` (new) + frontend]: locale message catalogs, a
  `{{ t "key" }}` template helper, and `Accept-Language` negotiation.
- (C) **Error/loading boundaries** [frontend-only]: declarative error + loading UI
  for SPA navigation and data loaders.

## Batch 9 — Frontend platform II + SQL depth 🔄  → v0.6.0
- (A) **Lazy routes / code splitting** [frontend + small cli manifest]: per-route
  JS via native `import()` + a route manifest.
- (B) **SQL indexes + joins** [`crates/sqlexec`]: secondary indexes + inner joins.
- (C) **Performance budgets** [`bench/` + `deploy.sh`]: `cargo bench` budgets
  enforced as a release gate.

## Batch 10 — Streaming, planner, images ⬜  → v0.7.0
- (A) **Streaming SSR** [`crates/http` + cli]: chunked transfer-encoding streaming
  of large templates.
- (B) **SQL planner + transactions** [`crates/sqlexec`]: a cost-aware planner +
  multi-statement transactions.
- (C) **Image optimisation** [frontend + cli]: responsive image hints + native
  lazy-loading (from-scratch raster codecs are out of pure-std scope — documented).

---

# AI Components track — `assistant-ui` + `tool-ui` 1:1 port

A faithful port (in spirit, not code) of [assistant-ui](https://github.com/assistant-ui/assistant-ui)
(composable chat primitives) and [assistant-ui/tool-ui](https://github.com/assistant-ui/tool-ui)
(tool-payload → UI, 30+ components) into the framework's **no-build native-ESM**
frontend — NO React/Tailwind/Zod. Where the framework lacks backend support a chat UI
needs, **add it** in the pure-`std` spirit (Óli: "add the features missing in the
framework if they call for it"). Docs: `site/content/docs/ai-components.md`. Same
worktree recipe (3 disjoint agents/batch, model-tiered) + orchestrator integration +
`./deploy.sh minor`. **This track is the current execution priority** (ahead of
roadmap Batches 9–10, which remain queued).

## Batch AB1 — Assistant runtime + chat core ✅
- (A) **LLM client + streaming assistant endpoint** [`crates/llm` (new) + cli] — a
  plain-HTTP OpenAI-compatible `/v1/chat/completions` client with SSE token streaming
  (mirrors `akurai-vector`); `POST /api/assistant` proxies a conversation to
  `AKURAI_LLM_URL` and streams tokens; graceful when unconfigured. **opus.**
- (B) **Chat primitives** [frontend] — Thread + Message + Composer + ActionBar as
  native-ESM on `signals.js` + `akurai-markdown`, consuming the SSE stream;
  auto-scroll, retries, keyboard shortcuts, a11y. A `/chat` demo. **sonnet.**
- (C) **Code highlighting + Markdown polish** [frontend or `crates/markdown`] —
  syntax-highlighted code blocks + copy button for assistant messages. **haiku.**

## Batch AB2 — Generative UI runtime + tool mapping ✅
- (A) **Payload schema validator** [`crates/schema` (new)] — lightweight JSON-shape
  validation (no Zod), server + client-exposed, for matching tool payloads to
  components. **sonnet.**
- (B) **Tool-call runtime + generative UI** [frontend + cli] — the client registry
  (payload → component, fail-safe JSON fallback, "receipts" back to assistant),
  inline human approvals, safe frontend actions; assistant endpoint relays tool
  calls/results. **opus.**
- (C) **ThreadList + branch picker + reasoning/suggestions** [frontend] — multi-thread
  switching, alternate-branch navigation, collapsible reasoning, suggestion chips. **sonnet.**

## Batch AB3 — tool-ui components I (Display + Artifacts) ✅
3 frontend agents over disjoint component files (each ships its `/docs/<component>` +
preset example data; native SVG/`<canvas>` for charts/maps, no bundled libs):
- (A) **Display** — Citation, Link Preview, Stats Display, Terminal, Weather Widget. **sonnet.**
- (B) **Artifacts — data** — Chart (canvas/SVG), Data Table, Code Block, Code Diff. **sonnet.**
- (C) **Artifacts — content + carousel/map** — Message Draft, X/LinkedIn/Instagram post
  cards, Item Carousel, Geo Map. **sonnet.**

## Batch AB4 — tool-ui components II (Input + Progress + Confirmation + Media) ✅
3 frontend agents, disjoint component files:
- (A) **Input** — Option List, Parameter Slider, Preferences Panel, Question Flow. **sonnet.**
- (B) **Progress + Confirmation** — Plan, Progress Tracker; Approval Card, Order Summary. **sonnet.**
- (C) **Media** — Audio, Image, Image Gallery, Video. **haiku.**

## Batch AB5 — AkurAI-RustAgent agent OS parity ⬜
Hermes-style agent UI parity for the AkurAI-RustAgent web surface. This is the
missing layer between "chat with the agent" and a personalized agent operating
system: preserve channels, show all agent asks, and send typed receipts back.
- (A) **RustAgent/Hermes event adapter contract** [frontend-docs + fixtures] —
  normalize `analysis`/`commentary`/`final`, `message.*`, `reasoning.*`,
  `tool.start`/`tool.progress`/`tool.complete`, `approval.request`,
  `clarify.request`, `sudo.request`, `secret.request`, `terminal.read.request`,
  `background.complete`, `subagent.*`, edits, artifacts, errors, and
  sequence/run metadata into the framework tool-ui event model. **gpt-5.5.**
- (B) **Agent workspace shell** [frontend-only] — compose ThreadList, reasoning,
  branch picker, suggestions, tool cards, artifact panes, context/sidebar state,
  and kanban/cron/curator entry points into a tenant-scoped operating surface.
  **gpt-5.5.**
- (C) **Receipt bridge** [frontend + gateway contract] — route approval, option,
  question-flow, slider, preferences, and edit-preview receipts back to RustAgent
  using the pending `toolCallId`/`request_id` and the matching
  `*.respond` method instead of flattening them into chat text. **gpt-5.5.**

## Batch AB6 — AkurAI-RustAgent durable workspace panes ⬜
The unique RustAgent product features become first-class UI objects.
- (A) **Memory + notes panes** [frontend + collections] — browse/search/pin memory
  and notes scoped by tenant, thread, project, and run. **gpt-5.4-mini.**
- (B) **Passvault actions** [frontend + approval policy] — display secret-related
  requests as approval cards with least-revealing metadata and typed receipts.
  **gpt-5.5.**
- (C) **Cron/kanban/curator board** [frontend-only first] — render schedules,
  blocked asks, active jobs, completed runs, and curator decisions using progress,
  plan, and data-table components. **gpt-5.4-mini.**

---

*After Batch 10 the roadmap's headline gaps vs Next/Vue/Svelte and PocketBase are
closed; the AI Components track (AB1–AB6) then makes AkurAI-Framework a first-class
substrate for AI chat apps and AkurAI-RustAgent's personalized agent operating
system. Update `site/content/docs/roadmap.md` as each batch ships.*