Workspace Architecture

The repository is organized around the agent runtime, city control plane, shared city infrastructure, and deployable surfaces.

Primary workspaces

• packages/agent/: local agent kernel, session execution, plugin runtime, HTTP/RPC host, SDK
• cli/city/: control plane, CLI, project orchestration, model pool, console-facing gateway
• packages/city/: City runtime for services, actions, auth, env, studio-scoped access, and routing
• packages/services/: public services such as accounts, balance, usage, payment, and Stripe flows
• packages/gate/: user and admin SDK for service calls
• packages/ui/: reusable UI primitives and app-facing components
• cities/: deployable City compositions that assemble city runtime and services for Node or edge runtimes
• products/console/: browser control surface
• products/chrome-extension/: extension that sends live page context into agents
• homepage/: marketing site, user docs, devdocs, SDK docs, and plugin docs

Boundary rules

• /docs is user-facing only
• /devdocs is contributor-facing only
• packages/agent owns single-agent execution
• cli/city owns control-plane and multi-project coordination
• packages/city owns reusable service runtime infrastructure
• packages/services owns public service capabilities
• packages/gate owns service access over HTTP
• product surfaces should consume runtime APIs instead of duplicating runtime logic

Current architecture philosophy

• console owns global governance
• agent host owns one project runtime
• session owns execution
• plugin owns capability exposure and augmentation
• durable traces stay close to the workspace

Build relationships

packages/agent build -> SDK and runtime package
packages/city build -> infrastructure runtime package
packages/services build -> public services package
packages/gate build -> service SDK package
cli/city build -> CLI and control-plane package
cities/node typecheck -> Node service block
cities/edge typecheck -> edge service block
products/console build -> browser control surface
products/chrome-extension build -> extension bundle
homepage build -> docs and marketing site