Roadmap: harden the core to production quality (depth over breadth)

[ayman3000]

Prioritized roadmap from a full review of the stack (LLMProviderKit → SwiftAgentKit → SwiftAgentKitUI → Demo). Strategy: depth over breadth — get the core loop + providers + tools to production quality and label everything else experimental until it's tested.

Current releases: LLMProviderKit 0.1.0-alpha.6, SwiftAgentKit 0.3.0-alpha.8, SwiftAgentKitUI 0.3.0-alpha.3.

Guiding principle

The architecture (clean layering, actor-based concurrency, minimal provider protocol) is the right bet. The gap is advertised ≠ wired-and-tested. Close that gap before adding features.

---

P0 — correctness & trust (shipped in alpha.8; keep as regression baseline)

• Anthropic anthropic-version header fix; Gemini tool-result role fix (LLMProviderKit alpha.6)
• Tool confirmation gating actually enforced (AgentCallbacks.onToolConfirmation, fail-closed)
• Context-window trimming preserves tool_call/tool_result pairing (avoids provider HTTP 400)
• Plan progress advances for target-less LLM-generated plans
• MCP request timeouts + handshake-failure process cleanup + readResource per-server fallback
• File stores: serialized memory-store writes; atomic session/goal writes
• StructuredOutput: robust object/array extraction (fences, backticks, root arrays)
• @Tool macro emits diagnostics instead of uncompilable code for unsupported inputs

P1 — close the advertised-vs-working gap

• CI on every repo: swift build + swift test on macOS + iOS on each PR. Highest-leverage item — this review was a manual substitute for it.
• Integration test suite exercising a live model end-to-end (agent loop + tools + memory + MCP). Use Ollama glm-5.2:cloud locally / gated in CI.
• Streaming + tools: today the final answer is yielded as one chunk after the loop. Either implement true streaming of the final turn, or document the limitation prominently in runStreaming.
• Token estimation (Conversation, 4 chars/token): replace with a per-provider tokenizer hook or a configurable, better-calibrated estimate — trimming correctness depends on it.
• Review SwiftAgentKitUI properly (only build-verified so far, not code-reviewed).

P2 — subsystem hardening (label experimental until done)

• @tool macro: real support for optionals and arrays (currently diagnosed-and-rejected), or descope. It's the weakest link — don't feature it until it's robust.
• Planning: substring target-matching is fragile; make plan-step ↔ tool-call correlation explicit rather than heuristic.
• AgentMemoryStore id/slug inconsistency: delete(id:) slugifies the arg but fact files are title-slugged, so delete-by-UUID never matches. Reconcile the addressing model.
• MCP: reap terminated server processes without blocking the actor (zombie cleanup) — deferred to avoid a hang on servers that ignore SIGTERM.
• Text-marker ToolCallParser: nested-JSON args break the \{[^}]*\} regex (fallback path for non-native-tool models only).

P3 — positioning

• Consider promoting LLMProviderKit as the flagship (most complete, zero-dep, independently useful) and marking the agent kit's advanced subsystems (planning/skills/macro) as experimental in the README.

---

Filed from a code-review session; P0 items reference fixes already merged and tagged.