Skip to content

docs

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

docs

README.md

Documentation

Design and reference documents for Interchange. Code is the source of truth; these documents explain the why behind it and the shape of the system at a higher level than any single package.

For development setup see DEV.md. For code conventions see CONVENTIONS.md. For the package taxonomy see LAYOUT.md.

Orientation

  • PRODUCT.md — product brief. What Interchange is for and who it is aimed at. Read first.
  • ARCHITECTURE.md — system architecture. Agent composition, the hub/sidecar/harness split, how the pieces talk to each other.

Subsystem design

  • AUTH.md — authentication and authorization. Unified principal model, tenant-scoped grants, capability evaluation.
  • CREDENTIALS.md — credential storage and rotation, harness delivery, background refresh.
  • HARNESS_DESIGN.md — agent harness implementation. How the sidecar manages harnesses on behalf of the hub.
  • unified-execution-host-design.md — design of record for the workflow-process execution host: how the sidecar runs each agent as a supervised workflow-process child. Its forward-looking sections are marked not-yet-built.
  • INFERENCE.md — inference layer. Provider adapters, streaming, tool execution, context management, token accounting.
  • MESSAGE.md — message transport. Mail as the first-class communication primitive, raw MIME storage, JMAP-style client views.

HTTP API

  • ROUTES.md — routing conventions and the why behind the route structure.
  • API.md — generated route reference. Regenerated by make docs from the OpenAPI spec at GET /openapi.json and ArkType introspection over @intx/types. Do not edit by hand.
  • GIT_ACCESS.md — operator-facing walkthrough for the hub's smart-HTTP git endpoints. Minting tokens, configuring stock git, and the URL and refPattern grammars for the assets and agent-state repo families.

Implementation notes

  • IMPLEMENTATION.md — implementation notes. Currently covers the SMTP/IMAP message bus.
  • ANTHROPIC_DISCOVERY.md — observed vs documented wire behaviour of Anthropic's /v1/messages and /v1/files surfaces. Narrative companion to the discovery fixtures and the SUPPORT_MATRIX.
  • OPENCODE_DISCOVERY.md — observed vs documented wire behaviour of the OpenCode Zen relay. Narrative companion to the discovery fixtures and the SUPPORT_MATRIX.