Skip to content

README.md

Latest commit

 

History

History
38 lines (31 loc) · 3.66 KB

README.md

File metadata and controls

38 lines (31 loc) · 3.66 KB
Raw

hypha Documentation

This directory contains public documentation for using hypha APIs, specs, runtime conventions, and extension points. It intentionally describes stable contracts rather than internal planning notes.

Start Here

  • Architecture Reference: package responsibilities, harness semantics, runtime boundaries, and extension rules.
  • Runtime Model: DomainPack, Session, Run, Event, durable orchestration, FSM, replay, audit, regression, and concurrency conventions.
  • FSM Anomaly Recovery: cross-module supervision, evidence-based convergence, bounded recovery states, cache knowledge, and module failure matrix.
  • Storage Reference: document, messaging, relational, vector, and artifact storage conventions plus memory extension points.
  • Local Data Layout: ignored data/ tree for local runtime records, indexes, artifacts, and logs.
  • Framework API: TypeScript package contracts and field-level spec references.
  • HTTP API: REST endpoints, authentication, request bodies, response shapes, and SSE behavior.
  • Architecture Notes: subsystem-level architecture notes.
  • Serving Cache: exact LLM response cache middleware, key fields, policies, stores, and trace events.
  • WorkCache: event-derived typed runtime cache, recovery knowledge, tree alignments, policies, stores, and audit events.
  • Tool/MCP Architecture: governed execution, Invocation lifecycle, MCP trust, drift, and Run snapshots.
  • Execution Contracts: provider-neutral Workspace, Sandbox, Command, Store, Event, and cache-fingerprint boundaries.
  • Governed Memory: scoped records, atomic persistence and index outbox, deterministic retrieval, bounded context, external adapters, and replay/cache bindings.
  • Execution Threat Model: trust boundaries, audited runtime surfaces, required controls, and residual limitations.
  • Execution Provider Matrix: provider guarantees and fail-closed capability negotiation.
  • ADRs: accepted architecture decisions.

Guides

  • Domain Packs: how to declare workflows, task schemas, tools, MCP profiles, memory profiles, policies, evaluations, regressions, and output contracts.
  • Local Development: setup, environment, commands, storage adapters, and verification checks.
  • Tool/MCP Security: trust boundaries, secrets, side effects, approval, and recovery.
  • Tool Adapter Guide: implement and register Local, HTTP, Plugin, Mock, and MCP adapters.
  • Common Utility Tools: governed JSON, text, and SHA-256 tools with limits and examples.
  • Tool/MCP Migration: move legacy handlers and MCP calls to the governed runtime.
  • Governance Examples: local Tool execution and MCP catalog/snapshot examples.
  • Capability Matrix: public surfaces and runtime guarantees.
  • Known Limitations: deliberate constraints and operational caveats.

Documentation Rules

Public docs should describe API behavior, fields, runtime conventions, package boundaries, and examples that remain valid for users of the framework. Local planning notes belong outside tracked docs.