Roadmap v2 — Post-v1.0 GA Direction
This document is the single source of truth for “what’s after
v1.0 GA”. Before P10.19.3 the same signals lived in three
places: RoadMap.md “Later Tracks”, docs/archive/ PROJECT_EVALUATION_2026-05-19.md §7.3, and the v1.x entries
in TODOs.md. Consolidating them here makes the post-v1 picture
auditable in one read.
Status
- Not binding. Items here are directional. They graduate to
TODOs.mdonly when they become concrete (clear acceptance criteria + owner). This doc is the staging ground. - Not exhaustive. New ideas land here when they’re worth remembering but not worth executing today.
- Living document. Edit freely. Remove items that landed, rename items as the shape sharpens, add items as they surface.
v1 → v2 inflection
v1.0 GA closes when the P10.0.x release-engineering checklist
runs clean (production deployment dress-rehearsal, cargo publish --dry-run, tag, image push, fresh-VM doctor smoke).
After GA the maintenance bar tightens:
- Wire shapes pinned by fixture tests don’t change. Anything
in
docs/STABILITY.mdStable or Beta tier is now load-bearing for downstream users; bumping requires a major version or an explicit migration window. - Operator UX > new capability surface. The v1 → v2 work emphasises hardening, observability, and ergonomics rather than new product surfaces.
- “Operator dashboard” stays out. Per P10.17.1, the Web UI
is a debugger / run console. Operator-dashboard features
(cost / retry-rate / worker utilization / policy summaries)
are explicitly out of scope; Prometheus + Grafana + BI tools
cover those better. See
docs/WEB_UI.md§ Product positioning.
Themes
Each theme below collects related items. Item-level references
point at the canonical source so the inventory is auditable
(TODOs.md::P10.X for tracked items, RoadMap.md for the
“Later Tracks” prose, etc.).
A. LLM provider & model layer
Motivation: the 9-provider live nightly is green (N9) and the modality dispatcher is unified (P-LLM). The remaining work is hardening + finer-grained vendor compatibility.
- Promote DashScope / DeepSeek / MiniMax to dedicated provider
modules (
P10.3.2, closed). Today they shareOpenAIProviderviacreate_provider. Per-vendor promotion triggers (tool-call shape divergence, multimodal-shape divergence, streaming-protocol divergence, auth/endpoint topology divergence, vendor-specific feature with no upstream OpenAI mapping, operator-side request) pinned indocs/LLM_PROVIDER_MODULE_PROMOTION.md. None has fired as of 2026-05-20. Estimate when needed: ~300-500 LoC per vendor. - Provider-specific tokenizers (
P10.3.3+P10.3.3-FU1, both closed).yanshi_llm::tokenizershipsTokenCountertrait +TiktokenCounter(cl100k_base, o200k_base, p50k_base, r50k_base viatiktoken-rs) +HeuristicCounterfallback +counter_for_model(model_id)factory. FU1 added the bridge from yanshi-llm to yanshi-memory:Message::*_with_counterconstructors + atoken_counter_adapterin yanshi-agents that routesReActAgent/PlanExecuteAgentmessage construction through the BPE counter.apply_memory_prompt_budgetcompacts against precise counts for the OpenAI family + cl100k_base-compatible vendors. Anthropic / Google fall back to the documented heuristic; provider responses still ship exact counts for post-call accounting. - Auto-rotate live nightly default models on 404 (
P10.3.4). Vendor deprecations cause periodic CI churn (claude-3-5-haiku → claude-haiku-4-5; gemini-1.5-flash → 2.5-flash, etc.). Acargo xtask refresh-live-modelswould ping each provider’s models-list endpoint + rotate the workflow env block. Tracked also underP10.18.1.
B. Memory & RAG layer
Motivation: P4 landed the 4-layer memory design + RAG eval harness. Production-grade encryption + cross-session linking + richer eval baselines are next.
- Encryption-at-rest (
P10.7.2closed). LandedAgeEncryptedPreferenceStore— single-user X25519 envelope encryption over anyPreferenceStore. Cloud KMS / multi-user / envelope re-keying remain v2 follow-ups; promote a new P11.x line item when concrete demand (SaaS multi-tenant hosting, regulated-environment deployment) surfaces. - Cross-session memory linking (
P10.7.3closed as RFC). Design 1-pager atdocs/RFC_CROSS_SESSION_MEMORY_LINKING.mdframes the design space (Option A index-only / Option B embedded graph store / Option C vector-graph hybrid) and pins explicit promotion criteria. Doesn’t pre-decide the implementation — three of the four memory layers already cross sessions automatically, so the headline feature (knowledge-graph traversal) is parked until concrete UC3-shaped demand surfaces. - Pluggable retriever expansion (
P10.6.1landed BM25 + dense + hybrid). Future: external retrievers (Qdrant production, Elasticsearch, custom domain-specific). Easy via theRetrievertrait — trigger when a real use case surfaces. - Retrieval hardening beyond the BM25+dense baseline —
AST-aware / fine-grained chunking, rerank + retrieval
post-processing chain, query rewrite / decomposition,
citation-consistency checking. Promoted to
TODOs.md§L4 (2026-07-23 curriculum-gap review). - Project-level memory layer — codebase-scoped facts
(build / test commands, module boundaries, past fixes) as a
first-class memory scope alongside the existing four layers.
Promoted to
TODOs.md§L3 (2026-07-23). - Knowledge-asset governance (“LLM Wiki”) — knowledge-base versioning, source/citation lineage, per-audience access scoping, staleness cleanup. Product-layer; stays staged until a real multi-user knowledge deployment demands it.
C. Server / platform productization
Motivation: P2 + P5 landed the server skeleton + worker control plane. v1.x hardening focuses on per-tenant operations.
- Per-run retention override (
P10.14.1). Today retention is per-tenant + per-profile. P2.2 left per-run override as deferred.POST /v1/runsbody could carryretention_overrides: { events_days, artifacts_days }for keeping critical runs longer than the global sweep. - Grafana dashboard templates (
P10.14.2). Server emits Prometheus metrics; checked-in Grafana JSON would let operators import in 1 click. (NB: this is operator-dashboard territory but lives inyanshi-serverdeliverables, not the UI — consistent with the P10.17.1 positioning.) - Real backup/restore implementation (
P10.15.1). Today: docs +yanshi doctor --backup-checkprobes; production usespg_dump+ filesystem snapshot. Anyanshi backup --output <path>orchestrator would close the loop. - Read-replica support (
P10.15.2, closed).Databasecarries an optionalread_pool; everyget_*/list_*repo method routes to it when configured, writes always hit the primary.yanshi serve --database-read-url <URL>(envYANSHI_DATABASE_READ_URL) opts in. Seedocs/DEPLOYMENT.md“Read-replica routing (P10.15.2)” for the operator playbook and the documented replication-lag caveat.
D. Web UI
Motivation: positioning is now firmly debugger / run console. v1.x work stays inside that boundary. Operator dashboard is explicitly NOT v2 scope.
In scope (each is a small additive feature inside the debugger boundary):
- Harness session replay UI — visual analogue of
yanshi harness replay --speed 2x(P10.10.2 landed the CLI). Stretch. - Trace compare polish — better diffs, more event-type coverage.
- Preference UI wiring follow-through — extend P10.17.2’s
proof-of-pattern (run-console tenant) to the other 6
syncable keys; the 3-line replication pattern lives in
yanshi-ui/src/main.tsx::RunConsole.
Architectural decisions already landed:
yanshi-vizdeleted (P10.13.1, closed). Honest audit revealed the “DAG visualisation” was a button grid of node status badges + the raw Mermaid markdown text in a<pre>block — no SVG, no spatial layout, no edges. The data plumbing through/v1/runs/{id}/graphwas disproportionate to the rendering value. Crate + endpoint + UI consumer all removed. Workflow DAG visualisation could be done well (e.g. mount mermaid.js in the UI to render the text as SVG) but is deferred to a future RFC. Agent-native execution visualisation (ReAct loop / multi-agent topology / Harness session tree) is its own design problem — today’s surface isyanshi harness replay --speed 2xper-event text timeline.
Explicitly NOT v2:
- Cost / billing aggregation, retry-rate trends, worker
utilization, policy-decision summary tabs. The
WEB_UI.mdin/out table is the canonical list.
E. Distributed execution & worker hardening
Motivation: yanshi-worker exists with gRPC WorkerProtocol
- admission policy + PSK auth. v1.x adds identity + scheduling intelligence.
- Signed-JWT identity (
P10.16.1, closed). HS256 + RS256 JWT verification landed alongside the existing PSK path: per- worker opt-in viaWorkerAdmissionPolicy.jwt_workers, configurableJwtPolicy(issuer / audience / key pool / leeway), strict claim validation (iss/aud/sub/exp/nbf), key-pool rotation. PSK takes precedence over JWT when a worker is misconfigured into both sets so there’s no silent downgrade. Seedocs/DISTRIBUTED.md“JWT identity flow” for the operator playbook. gRPC-metadata propagation of admission tokens is still deferred. - Worker pool admission heuristics (
P10.16.2, foundation closed). Capability-aware dispatch (WorkerCapabilitiesadvertises whichnode_types a worker accepts) + locality preference (warm-run bias on next claim) land for the in-memory protocol. gRPC wire-extension stays as a tracked follow-up (P10.16.2-FU1). The staticmax_workers+max_concurrent_tasks_per_workercaps remain in place; the hints are additive on top. - Worker-executable node payload expansion —
P2.8expanded totemplate/file; future iterations should addllm,http,mcp,agentso worker mode is useful for real workloads. - Distributed scheduling validation — large DAG scheduling with mixed local + worker-executed nodes; failure-domain tests.
F. Harness Agent Mode (H6 items)
Motivation: H0–H5 closed. H6 is the open-ended track of
“advanced compatibility” features — promoted individually only
when concrete demand surfaces. Per-item promotion triggers are
pinned in docs/H6_PROMOTION_CRITERIA.md (P10.10.1, closed).
Candidate items (each needs its own RFC before promotion;
two are explicit non-goals in RoadMap.md and would need that
decision re-opened first):
- Slash-command ecosystem expansion — beyond the current closed command set.
- TUI product shell (non-goal in
RoadMap.md) — separate from CLI run; an opinionated long-lived agent UI. - OpenHarness-style config import — interop with the
external
harnessconfig conventions. - Plugin compatibility adapters — bridges for existing third-party agent frameworks.
- Provider subscription bridge (non-goal in
RoadMap.md) — bring-your-own-subscription flows.
Don’t pull en bloc. Each is its own design conversation. See
docs/H6_PROMOTION_CRITERIA.md for the per-item demand signals
that would tip the scale.
Already-closed Harness session replay CLI is P10.10.2 (landed).
G. Plugin runtime expansion
Motivation: subprocess JSON-RPC is the stable v1 runtime. v2’s question is what supplements it.
- WASM plugin runtime (closed:
P10.19.1). Evaluation landed atdocs/WASM_PLUGIN_EVALUATION.md. Decision: push to v2.0. Runtime choice if/when we cross the threshold: wasmtime + WIT + WASI 0.2. Re-evaluation triggers documented in the 1-pager — until at least one fires, WASM is “better story for hypothetical users,” not a fix for current friction. ThePluginRuntime::Wasmmanifest enum variant stays as a forward-compatible reservation. - Avoid native
dlopen— unless a concrete ABI strategy emerges. The Non-Goals stance fromRoadMap.mdcarries forward.
H. Performance & regression detection
Motivation: P7 + bench-gate xtask exist; baseline workspace
coverage is uneven.
- Hot-path benchmark suite (
P10.1.1). Criterion benches exist (benches/scheduler.rs); compare againstbench-gatebaseline and watch for 1.10× regressions. - Per-node latency benches (
P10.2.1). Today only scheduler mechanics are benched. Per-node hot-path benches would catch e.g. template-render regressions. - Workspace-wide perf regression detection (
P10.19.2).bench-gatecovers criterion; extending tocargo test --workspacewall-clock per crate would catch test-suite bloat early. Gate on 1.5× regressions.
I. Ops & developer tooling
cargo xtask refresh-live-models(P10.18.1). See Theme A above. Reduces manual chore toil after vendor deprecations.cargo xtask check-changelog(P10.18.2, landed) — now available as a manual gate; promotion toquality.ymlrelease-gate is the next step once the heuristic has run against real PRs.- Operational deployment profiles — local dev, single-node
server, distributed worker cluster (from
RoadMap.md:: Operations). - E2E smoke tests covering CLI + server + worker + tracing +
Web UI paths (from
RoadMap.md::Operations). The UI e2e slice (P10.17.4) is the wedge.
J. Documentation & contributor experience
- CHANGELOG hygiene — the new
cargo xtask check-changelogenforces it locally; CI promotion is the natural follow-up. - Centralised release notes —
docs/RELEASE_NOTES_*.mdper version (pattern set byv1.0.0-rc.1.mdDRAFT). - Stretch json-envelope migrations — periodic audit per the P10.11.3 pattern; today’s audit landed exactly one holdout fix. Recheck after every new CLI subcommand added.
K. Long-horizon agent reliability
Motivation: the 2026-07-23 curriculum-gap review (external
AI-agent training syllabus vs this codebase) confirmed the
long-horizon story currently stops at budgets + checkpoints —
no replanning, no loop detection, no narrative recovery, no
structured delegation. Four items were concrete enough to skip
the staging ground and land directly in TODOs.md:
- Dynamic-workflow replan loop (failure-driven re-planning,
completed-node reuse) — promoted to
TODOs.md§L1.1. - Loop-signature detection (repeated tool+args spinning caught before budget exhaustion) — promoted to §L1.2.
- Task-summary recovery after context truncation — promoted to §L2.
- Subagent delegation contracts + result arbitration — promoted to §L5.
Still staging here (promote when demand sharpens):
- Task-level state machine surface —
waiting_tool/waiting_approval/tool_failedas first-class queryable run states on the server API (today they’re derivable from the event stream but not materialized). - Model routing / fallback chains in
yanshi-llm— automatic fallback across providers, strong/weak model tiering, token-budget-aware routing. Today provider choice is static per model id. - Cross-cutting cache layer — prompt / RAG-retrieval / tool-result caches with invalidation policy. Tool idempotency flags exist; an actual cache does not.
Non-goals for v2
These stay out unless a strong concrete signal lands. The
v1-era non-goals (RoadMap.md::Non-Goals For V1) carry
forward; v2 adds explicitly:
- Web UI as operator dashboard — out per P10.17.1. Use Prometheus + Grafana + BI tools instead.
- UI as headless-operation requirement — the CLI + trace replay remain the canonical headless surfaces.
- Native dynamic-library plugins (
dlopen-style) — covered in the v1 non-goals; no change. - Unbounded marketplace remote-code-execution defaults — signature + checksum + capability gates stay mandatory.
- Provider-specific agent behaviour bypassing Tool/Trace/Policy contracts — every new provider integrates through the existing surfaces.
How to promote an item
When a v2 idea sharpens into something actionable:
- Open a TODO entry under a
P11.x(or beyond) segment inTODOs.mdwith explicit acceptance criteria. - Cross-reference back to the relevant theme letter in this file so the audit trail stays.
- Delete the corresponding bullet here OR (preferred) leave a
stub like
_promoted to P11.x — see TODOs.md_so the history of the idea is preserved.
Related
RoadMap.md— v1 direction + Later Tracks prose (Later Tracksitems mirror the themes here).TODOs.md(maintainer-local, gitignored) — active execution queue. The current P10 segment is the v1.0-rc.1 → v1.0 hardening arc; P11+ slots are reserved for promoted v2 items.docs/STABILITY.md— wire-shape promises this roadmap inherits.docs/WEB_UI.md§ Product positioning — the canonical debugger-only commitment that scopes Theme D.docs/archive/PROJECT_EVALUATION_2026-05-19.md§7 — the most recent eval that seeded the original v1.x bullets.