Skip to content

04 — Features Roadmap (everything to implement)

Legend: [ ] todo, [~] stubbed in scaffold, [x] done. Build P0 top-to-bottom.

P0 — Usable single agent (v0.1)

  • Project scaffold (monorepo, TS package, docs, CI)
  • Agent ReAct loop with maxSteps
  • Tool + defineTool + ToolRegistry (zod validation)
  • Memory interface + InMemoryMemory (windowed)
  • ModelProvider interface + MockModelProvider
  • runWithBudget (AbortSignal + timeout) + AgentError codes
  • AgentEvents hooks + consoleEvents (dep-free ANSI colors, NO_COLOR/TTY aware) + logError
  • Streaming: stream: true SSE in provider (delta.content → onToken, delta.reasoning_content → onThinking), wired through the agent loop
  • Structured errors: UNKNOWN_TOOL, TOOL_ARG_INVALID, TOOL_EXECUTION (tool bugs wrapped, AgentError passes through), MODEL_ERROR (retryable on 429/5xx/network), TIMEOUT, ABORTED (no DOMException leaks), BUDGET_EXCEEDED (via maxToolCalls), MODEL_CAPABILITY (images on text-only models), WORKFLOW_* / ROUTER_NO_MATCH / ORCHESTRATION_EMPTY — unit test per code
  • Content-block messages: text/reasoning/image/audio/file/tool_call/non_standard, ids, factories, zod-validated serialization round-trip
  • Tool artifacts: toResult() splits model-visible content from downstream-only artifact
  • outputVersion v0/v1: v1 preserves thinking as reasoning blocks in history
  • prompts/ — definePrompt + file loading + A/B variants
  • skills/ — SKILL.md frontmatter parse + SkillRegistry + FS discovery + TF-IDF routing
  • OpenAI-compatible provider (fetch-based, no SDK lock-in) — live-verified on TogetherAI (E2E_MODEL=1), mock tests offline-green
  • .env + dotenv loadConfig() (TogetherAI preferred, OpenAI fallback; never commit keys)
  • Examples: all run green (01,02,03,04,06,08,09,10,11,12,13,14,15,16 — including sessions, swarm/a2a, providers, HITL resume)
  • Coverage gate >= 80% (test:coverage enforces lines/functions/branches/statements)

P0-sem — Semantic grounding, read path (v0.1-sem, with P0)

  • semantic/ — GraphStore + InMemoryGraphStore: RDFS + OWL (transitive/symmetric/inverse/functional-conflict) to fixpoint, SHACL-subset shapes, versioned CONSTRUCT rules, why() proofs, dedup, export/import
  • ontology_lookup + sparql_select (read-only) + graph_add (autonomous validated writes) + claim_check (grounded/unknown/contradicted) tools over the closure
  • Provenance rule enforced: agent writes without dct:source rejected
  • Example: 06-semantic-graph.ts (seed Turtle → query closure → cite proof)

P1 — Teams + reliability (v0.2)

  • Orchestration: sequential (output→input chaining), parallel (concurrency cap, ordered results), router (model-picked specialist, ROUTER_NO_MATCH on invalid) — Agent.description feeds the router menu
  • Workflows: DAG with topological levels, concurrent siblings, per-node retry (backoff), WORKFLOW_* errors (duplicate/unknown-dep/self-dep/cycle)
  • Swarm: autonomous handoff_to_agent coordination, shared context (task/history/knowledge/roster), multimodal task input, maxHandoffs/maxIterations + execution/node timeouts + ping-pong detection, typed stream events, COMPLETED/FAILED results
  • A2A: A2AClient (card + send) + a2aAsTool + A2AServer (card/message/send/SSE /stream, per-context isolation, LRU cap, durable HITL threads, CORS, /ok health)
  • State: AgentState (validated JSON KV) + ToolContext + per-run invocationState (shared by ref, returned on result); agent.messages + initialMessages; pause()/resume(); editMessage + branch() with version timeline; shared across orchestration/workflows via run opts
  • Conversation managers: Null / SlidingWindow (window/pinFirst/perTurn, pair-safe trim) / Summarizing (ratio/preserve/model-or-fn)
  • Sessions: InMemoryStorage/LocalFileStorage + SessionManager (latest + immutable checkpoints, delete) + takeSnapshot (preset/include/exclude/appData) / loadSnapshot + auto restore-on-first-run + save-after-run
  • MCP: McpHttpClient (Streamable HTTP, JSON+SSE) + McpStdioClient + mcpToolsToFramework (JSON-Schema→zod bridge, collision namespacing) — live-tested against a fake server
  • Skills discovery: discoverSkills (SKILL.md scan) + loadSkillsInto + matchSkills ($mention + overlap routing)
  • Middleware: hooks (beforeModel/wrapModel/afterModel/beforeTool/aroundTool/afterTool: before_ in order, after_ reversed, wrap_* nested) + createMiddleware + middleware-contributed tools
  • Prebuilt middleware: full toolRetry/modelRetry (backoff+jitter/filter/onFailure) + modelFallback, modelCallLimit, toolCallLimit, humanInTheLoop (approve/edit/reject), pii (redact/mask/hash/block + custom detectors), summarization, contextEditing (ClearToolUses), todoList (write_todos), llmToolSelector, toolEmulator, filesystem (ls/read/write/edit, root-jailed), subagents (task tool)
  • stampRetryable/getRetryable verdicts; initChatModel("provider:model") (together/openai/anthropic/ollama/custom)
  • Structured output: toolStrategy/providerStrategy (responseFormat), structuredResponse on result, in-loop repair
  • Event streaming: agent.stream() typed events + collectStream
  • Compaction: CompactedMemory + model summarizer + semantic (keep-triples) variant + fidelity tests
  • Budgets: maxTokens, maxCostUsd (+prices), maxToolCalls, deadlineMs enforced per model call
  • Retries: exponential backoff with jitter for retryable errors (verdicts honored); per-tool/model retry middleware
  • Persistent memory: FileMemory (atomic JSON, validated reload); Redis/Postgres stay adapters
  • Tokenizer: dependency-free word/CJK/punctuation estimate (documented approximation) + truncation in memory
  • Evals harness: eval/ JSONL datasets + scorer + pass-rate reporter (pnpm eval, EVAL_LIVE=1 for live); 4 seed evals green

P1-sem — Semantic writes + rules (v0.2-sem, with P1)

  • OWL property axioms: transitive / symmetric / inverse / functional (functional conflict = violation, not second fact)
  • SHACL-subset engine: class shapes (min/max/datatype/nodeKind/hasValue), violations → repair feedback → model self-repair loop
  • Versioned CONSTRUCT-style rules to fixpoint; every inferred quad keeps prov:wasDerivedFrom + rule id
  • GraphMemory implements Memory: load() injects relevant closure slice, save() delegates, exportState/importState for session LTS

P2 — Ecosystem (v0.3)

  • Providers: Anthropic native API (text/thinking/tool_use/SSE, MODEL_ERROR mapping) + local Ollama (ollama(), no key) + initChatModel prefixes (together/openai/anthropic/ollama/custom)
  • framework.json + framework-serve CLI (dev/serve|up/validate, --port/--host/-c): agent files + overrides, framework/agent envFile + inline env{}, checkpointer dir, CORS, /ok health
  • Frontend: AgentClient (send + SSE stream) + handleAgentRoute (Next.js/TanStack Start bridge) + framework-agents-react useAgent (turns/thinking/activity/status/send/cancel/reset)
  • Checkpointed HITL resume (local-first): FileCheckpointer + withFileLock (stale reclaim) + HitlInterrupt/hitlKey + agent.resume(); S3 backends and distributed locks explicitly deferred (third-party)
  • Local skill routing: dependency-free TF-IDF cosine (scoreSkills seam for future embedders)
  • Provider fallback chain via modelFallbackMiddleware(...providers) (any backends)
  • RAG interface: Retriever { search(query, k) } + retrievalTool() + TF-IDF + SPARQL adapters (no bundled vector DB)
  • Human-in-the-loop: approve/edit/reject/suspend + checkpointed resume (agent.resume, hitlKey)
  • Guardrails: PII middleware, output schema enforcement (responseFormat), tool sandboxing via emulator
  • Sandbox: run_javascript (vm, timeout) + createSandboxBackend (execute shell w/ scrubbed env, ls/read/write/edit/glob/grep, spill-to-file)
  • Prompt management: markdown files + render(vars) + A/B variants with tests
  • Python parity: framework_agents (packages/python) — full TS module map ported with pydantic + httpx + aio stdlib; the FIXED semantics are encoded from day one (see packages/python/README.md pinned-semantics table); 195 offline tests + live Together parity (same e2e scenarios as TS) + executable cross-language conformance (Python A2A client ↔ TS A2A server on the real wire)

P2-sem — Linked data at scale

  • Remote SPARQL adapter (SELECT/UPDATE over HTTP, auth, prefixes) — RemoteSparqlAdapter + remoteSparqlTool (SELECT always; UPDATE opt-in)
  • Entity linking tool (mention → IRI via sameAs index) + JSON-LD expand/compact I/O — EntityLinker/linkEntityTool, autonomous-by-default MappingProposals (review = autonomy: false), quadsToJsonLd/jsonldToQuads with named-graph round-trip
  • Ontology evolution: TBox v3→v4 migration + conformance battery — migrateTBox (rebuild; v3 untouched) + runConformance; each version's TBox lands in its own named graph (urn:framework:ontology:<to>)

P3 — Production hardening (v0.4+)

  • Observability exporters: OTel-shaped spans (console/JSONL/memory sinks) behind AgentEvents; vendor HTTP adapters stay out
  • Tool/skill registry service: namespaced packages, semver, signed manifests
  • Distributed runtime: queue-backed runs, idempotency keys, resume-from-checkpoint
  • Guardrails: policyFilterMiddleware (allow/deny, continue/error) + PII + schemas + emulator
  • Benchmarks: bench/ token/latency harness + --baseline regression gate (pnpm bench)

Out of scope (explicitly not building yet)

  • Hosted UI / playground, hosted API, billing — library first.
  • Fine-tuning pipelines, model training.
  • External internet search (web_search provider + fetch/extract) — deferred, out of scaffold for now.