Architecture and implementation stack

AgenZync separates product identity, runtime execution, collaboration, storage, and external capabilities. The separation is used to keep authorization and recovery rules independent from the model provider.

Layer boundaries

Layer	Primary responsibilities
Product	Projects, Chats, Jobs, module policy, lifecycle, launch intents, and owner-scoped APIs.
Orchestration	Mission state, continuation, completion gates, budgets, loop decisions, and recovery coordination.
Agent runtime	Model turns, tool routing, agent attempts, interaction state, approvals, context budgets, and event emission.
Collaboration	Parent-child control, Team state, workspaces, Write Intents, ChangeSets, integration claims, and reconciliation.
Persistence	Project catalog, per-run SQLite state, append-only event streams, artifacts, filesystem generations, and leases.
Adapters	Model providers, MCP, guarded shell and source access, repository execution, and optional analytics sinks.

Frameworks and libraries

The current source tree pins its runtime and frontend dependencies. Versions below describe the development branch and are not a long-term compatibility promise.

Runtime

Python 3.11

Core services, persistence, orchestration, tool routing, provider adapters, and the local WebUI host.

Model integration

LangChain 1.3.14

Used with langchain-openai 1.4.0 behind AgenZync-owned runtime and policy boundaries.

Contracts

Pydantic 2.13.4

Typed runtime and product validation. YAML skill metadata uses PyYAML 6.0.3.

Product UI

React 19.2.8

React Router 8.3, TanStack Query 5.101, and Zod 4.4 provide routing, server-state handling, and response validation.

Build and tests

Vite 8.1.5

TypeScript 7, Vitest 4.1, Testing Library, MSW, axe-core, and browser acceptance scripts.

Specialized I/O

Playwright and document tools

Playwright 1.61, Pillow 12.3, pypdf 6.14, and optional user-installed integrations are routed through bounded capabilities.

Local process model

Browser / CLI / local automation
              │
              ▼
      Python product host
  Projects · Chats · Jobs · Modules
              │
              ▼
       Controlled runtime
 Turns · Agents · Tools · Missions
       │              │
       ▼              ▼
 Durable local     External boundaries
 state + files     Providers · MCP · sources

The browser uses owner-scoped product routes. CLI and local automation can enter through supported command and protocol surfaces. All paths converge on the same runtime and persistence contracts rather than creating a separate browser-only agent engine.

Data authority

Question	Authoritative source
Which Project, Chat, Job, or module exists?	Project catalog and its schema-versioned product records.
What happened during execution?	Per-run state, redacted append-only events, messages, attempts, and artifacts.
Is a process currently owned?	Process claims and fenced runtime ownership—not catalog lifecycle labels.
What changed in a repository?	Repository identity, Git base revision, observed worktree state, and submitted ChangeSet hunks.
What may an agent do?	The immutable dispatch snapshot of modules, tools, profiles, skills, provider state, and approvals.

Trust boundaries

User-owned repositories and external Project workspaces remain outside the product catalog.
Provider responses and peer-agent messages are untrusted input until verified.
Job Definitions are declarative data; they cannot create runtime authority by naming a tool or adapter.
Repository writes, shell execution, external fetches, MCP calls, and custom tools are checked against path, capability, and approval policy.
Secrets are redacted from retained events and public projections, but prompts and commands should still avoid carrying secret values.