Skip to content

phases.md

Latest commit

 

History

History
64 lines (48 loc) · 4 KB

phases.md

File metadata and controls

64 lines (48 loc) · 4 KB

Focused Roadmap (Phases)

Phase 0 — Completed Foundations

  • Zod models and parsing utilities: src/models/schemas.ts; normalization helpers: src/models/normalize.ts.
  • LLM abstraction for OpenAI + Anthropic via Vercel AI SDK: src/llms/index.ts with text/object gen, streaming, embeddings.
  • Memory system with adapters: in‑memory, filesystem, localStorage; state adapters: src/memory/index.ts.
  • State machine and flows with entry/exit validation and flow tracking: src/core/state-machine.ts.
  • Decision engine with structured gen, embeddings‑guided examples, validation/retry: src/core/session.ts.
  • Agent/session APIs aligned with Python; optional event emitter: src/core/agent.ts, src/core/session.ts, src/core/events.ts.
  • Config loading and Mermaid visualization: src/config/loader.ts, src/utils/mermaid.ts.
  • Working examples including streaming and HTTP server demos: see examples/*.

Phase 1 — Tools Hardening & Registry

  • Error taxonomy and richer results: InvalidArgumentsError, FallbackError; extend ToolResult with code, status, metadata (src/tools/index.ts).
  • Namespaced ToolRegistry with serialize/restore APIs; list/get/has across namespaces.
  • Argument validation guidance: missing‑arg retry in Session.ensureValidDecision with clearer messages.
  • Acceptance: typed errors; registry list/serialize/restore; guided retries enumerate missing keys clearly.

Phase 2 — Nomos Agent Server + Client SDK

  • Server core in src/server: lightweight HTTP abstractions.
    • createAgentServer(agent, opts?) with POST /next and POST /stream (NDJSON).
    • Adapters: Node http and express.
    • Standardized request/response contracts aligned with Session.next/streamNext.
  • Client: AgentClient in src/client with next and stream (NDJSON parsing).
  • Subpath exports for server/client in package.json; examples updated in README.
  • Acceptance: One‑line boot; client works from Node/browser; streaming end‑to‑end.

Phase 2B — Sessions API (Server/Client)

  • SessionsManager with pluggable SessionStore interface.
    • In‑memory InMemorySessionStore implementation.
    • SQL adapters (Postgres/SQL) via example interface and hooks; provide contract so developers can plug in any store.
  • Server support: accept sessionId and persist flags; auto‑load state when not provided and auto‑save after responses.
  • Client support: pass sessionId/persist in next/stream opts.
  • Docs: short guide on wiring custom stores and lifecycle hooks.

Phase 3 — Packaging & Environment Guards

  • Conditional exports for Node/Edge/Browser via exports["."] mapping to index.node.js, index.browser.js, and index.edge.js.
  • Keep Node APIs out of browser paths; fs persistence behind adapters.
  • ESM-first with smaller export surface; subpath exports server and client added.
  • Main entry no longer re-exports server/client; use subpaths.
  • Mark package as side-effect free for tree-shaking (sideEffects: false).
  • Acceptance: Build/test pass; examples updated to use subpaths; tree‑shaking enabled.

Phase 4 — Deferred/MCP Tools (Stretch)

  • Deferred tools interface with polling and resume path.
  • MCP bridge interfaces and Node‑only adapter stub.
  • Acceptance: at least one deferred example; MCP stub lists tools.

Phase 5 — Docs, Telemetry, and Polish

  • Docs: README and docs updated; server/client quickstarts; architecture and API surface aligned.
  • Telemetry: optional OpenTelemetry hooks and structured logging toggles.
  • Examples and tests: examples runnable; core tests present. Add more coverage for server handlers and client streaming parser.
  • Acceptance: OTEL hooks guarded; broadened test coverage for server/client paths.

Notes

  • This roadmap reflects current status and priorities after server/client and packaging work. Remaining focus: tool taxonomy/registry, multi‑target packaging, deferred/MCP, and telemetry.