Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.md only 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.md Stable 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 share OpenAIProvider via create_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 in docs/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::tokenizer ships TokenCounter trait + TiktokenCounter (cl100k_base, o200k_base, p50k_base, r50k_base via tiktoken-rs) + HeuristicCounter fallback + counter_for_model(model_id) factory. FU1 added the bridge from yanshi-llm to yanshi-memory: Message::*_with_counter constructors + a token_counter_adapter in yanshi-agents that routes ReActAgent / PlanExecuteAgent message construction through the BPE counter. apply_memory_prompt_budget compacts 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.). A cargo xtask refresh-live-models would ping each provider’s models-list endpoint + rotate the workflow env block. Tracked also under P10.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.2 closed). Landed AgeEncryptedPreferenceStore — single-user X25519 envelope encryption over any PreferenceStore. 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.3 closed as RFC). Design 1-pager at docs/RFC_CROSS_SESSION_MEMORY_LINKING.md frames 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.1 landed BM25 + dense + hybrid). Future: external retrievers (Qdrant production, Elasticsearch, custom domain-specific). Easy via the Retriever trait — 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/runs body could carry retention_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 in yanshi-server deliverables, not the UI — consistent with the P10.17.1 positioning.)
  • Real backup/restore implementation (P10.15.1). Today: docs + yanshi doctor --backup-check probes; production uses pg_dump + filesystem snapshot. An yanshi backup --output <path> orchestrator would close the loop.
  • Read-replica support (P10.15.2, closed). Database carries an optional read_pool; every get_* / list_* repo method routes to it when configured, writes always hit the primary. yanshi serve --database-read-url <URL> (env YANSHI_DATABASE_READ_URL) opts in. See docs/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-viz deleted (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}/graph was 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 is yanshi harness replay --speed 2x per-event text timeline.

Explicitly NOT v2:

  • Cost / billing aggregation, retry-rate trends, worker utilization, policy-decision summary tabs. The WEB_UI.md in/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 via WorkerAdmissionPolicy.jwt_workers, configurable JwtPolicy (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. See docs/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 (WorkerCapabilities advertises which node_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 static max_workers + max_concurrent_tasks_per_worker caps remain in place; the hints are additive on top.
  • Worker-executable node payload expansion — P2.8 expanded to template/file; future iterations should add llm, http, mcp, agent so 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 harness config 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 at docs/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. The PluginRuntime::Wasm manifest enum variant stays as a forward-compatible reservation.
  • Avoid native dlopen — unless a concrete ABI strategy emerges. The Non-Goals stance from RoadMap.md carries 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 against bench-gate baseline 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-gate covers criterion; extending to cargo test --workspace wall-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 to quality.yml release-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-changelog enforces it locally; CI promotion is the natural follow-up.
  • Centralised release notes — docs/RELEASE_NOTES_*.md per version (pattern set by v1.0.0-rc.1.md DRAFT).
  • 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_failed as 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:

  1. Open a TODO entry under a P11.x (or beyond) segment in TODOs.md with explicit acceptance criteria.
  2. Cross-reference back to the relevant theme letter in this file so the audit trail stays.
  3. 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.