SDK Architecture

Deep architectural reference for the @namzu/sdk source tree, runtime pipeline, state model, and extension surfaces.

This section documents @namzu/sdk as an implementation architecture, not just as a package API. It maps the public package surface back to the real packages/sdk/src folder structure so the documentation stays useful both for integrators and for contributors navigating the codebase.

1. Architectural Shape

At a high level, the SDK is organized around a small set of repeated patterns:

Pattern	What it owns
Types and contracts	Stable cross-module shapes in `types/` and `contracts/`
Registries	Static definitions and catalogs in `registry/`
Managers	Lifecycle and orchestration in `manager/`
Stores	Mutable state and persistence in `store/`
Runtime	Query assembly, iteration flow, and final result shaping in `runtime/`
Compaction	Context reduction strategies and verified summarization in `compaction/`
Bridges	Protocol and subsystem translation in `bridge/`
Extensions	Providers, connectors, plugins, personas, skills, and RAG

The result is a layered package where runtime orchestration stays inside the SDK while vendor- or environment-specific implementations stay outside or behind explicit interfaces.

2. Reading Order

If you are new to the SDK internals, read these pages in order:

Pattern Language for the core structural rules.
Source Tree for the top-level module map.
Folder Reference for the "why does this folder exist?" overview.
Foundation Folders for types/, contracts/, constants/, config/, utils/, and version.ts.
Execution Folders for agents/, runtime/, compaction/, manager/, registry/, and routing.
Session and Store Folders for session/, store/, and gateway/.
Integration Folders for provider/, connector/, bridge/, tools/, plugin/, persona/, skills/, rag/, and advisory/.
Runtime Pipeline for the execution path of a run.
State and Persistence for sessions, stores, checkpoints, and disk layout.
Extensions and Integrations for extension surfaces in runtime context.
Safety and Operations for sandboxing, verification, bus coordination, and operational guardrails.

3. Top-Level Dependency View

The SDK's internal folders are easiest to read in this dependency-oriented grouping:

Foundation
  config/ constants/ contracts/ types/ utils/ version.ts

Execution Core
  agents/ runtime/ compaction/ run/ execution/ manager/ registry/

State and Durability
  session/ store/ gateway/

Extension Surfaces
  provider/ connector/ bridge/ plugin/ persona/ skills/ rag/ advisory/ tools/

Safety and Operations
  sandbox/ verification/ bus/ telemetry/ vault/

4. What This Section Optimizes For

These pages are written to answer questions such as:

Which folder should own a new runtime concern?
Where does a static definition stop and a lifecycle manager start?
How does a request move from ReactiveAgent.run() into the iteration loop?
Why does compaction/ exist as its own subsystem instead of being hidden in runtime/?
Which modules are public-facing contracts versus internal adapters?
Where do persistence, safety, and extension mechanisms connect?

1. Architectural Shape

2. Reading Order

3. Top-Level Dependency View

4. What This Section Optimizes For

Related

On this page