๐๏ธ ๐๏ธ System Architecture
This document provides a detailed overview of Wegent's system architecture, component design, and technology stack.
๐๏ธ ๐ป Development Setup
This document provides detailed instructions on setting up a local development environment for Wegent.
๐๏ธ Dynamic Context (Injecting Request-Scoped Context)
Background
๐๏ธ Test Framework Documentation
This document describes the unit testing framework setup for the Wegent project.
๐๏ธ ๐ CRD Architecture
This document provides a detailed technical reference for Wegent's CRD (Custom Resource Definition) architecture, designed for developers who need to understand the internal structure and implementation details.
๐๏ธ Skill Development Guide
This document provides technical implementation details for the Skill system, including architecture, Provider development, and API reference.
๐๏ธ Collaboration Models Development Guide
This document provides detailed configuration examples, real-world cases, and technical implementation details for collaboration models.
๐๏ธ MCP Tool Refactoring Guide
English | ็ฎไฝไธญๆ
๐๏ธ External Knowledge MCP
English | ็ฎไฝไธญๆ
๐๏ธ Skill Runtime Flow
This document explains how Wegent selects, resolves, propagates, and consumes skills across execution scenarios. The focus is on why skill resolution must stay centralized in backend, and why sandbox / local-device startup cannot rely on skill names alone.
๐๏ธ External Knowledge Sources
English | ็ฎไฝไธญๆ
๐๏ธ Knowledge Indexing Protection
Background
๐๏ธ Entity Permission Extension
This document describes Wegent's unified resource sharing permission architecture, covering the current authorization mechanism, permission processing logic, extension architecture design, and how to integrate internal customized authorization systems via IExternalEntityResolver.
๐๏ธ Web Scraper Service
Scope
๐๏ธ Exposing Capabilities Guide
This document describes the standard way to expose functional capabilities in the Wegent project, using the Knowledge Base MCP implementation as an example to show how to make your features available to AI Agents.
๐๏ธ Local Device Architecture
This document describes the technical architecture of local device support, including communication protocols, heartbeat mechanisms, and security design.
๐๏ธ Pre-Execute Hooks
Pre-execute hooks allow you to run custom scripts before task execution in the Executor. This is useful for custom initialization, security checks, environment setup, or integration with external systems.
๐๏ธ Runtime Local Work
Wework runtime local work surfaces Codex and Claude Code work that already exists on a user's device. It does not import that work into central TaskResource or Subtask rows, and it no longer depends on the Backend projects table to build the sidebar list. The list comes from runtime threads returned by online device executors and is shown in two groups:
๐๏ธ Issue unread state
Issue unread state belongs to the current user and persists in existing Issue metadata. Reading does not change the Issue version or update timestamp and requires no schema migration.
๐๏ธ Runtime Cleanup
Runtime cleanup manually removes execution environments that have not been updated for a configured period. It only deletes runtime Pods or containers. It does not delete Backend Task records or message history.
๐๏ธ Local Device Command RPC
Local device command RPC lets the Backend send a preconfigured shell command to a specific online local executor device and wait for the completed result. It is intended for operational checks, workspace diagnostics, and backend-initiated probes. It does not participate in the Task/Subtask lifecycle and does not create chat messages.
๐๏ธ Wework AI Branch Name Generation
The Wework branch selector can generate a Git branch name from the current composer input or task title. It reuses the model configured for friendly task titles and falls back to the current task model when no title model is configured or the configured model is temporarily unavailable.
๐๏ธ Connector Apps Architecture and Deployment
Connector Apps let Wework connect to internal systems without changing Codex source code or requiring a ChatGPT login. The upstream may be either an MCP server or an ordinary HTTP API. Responsibilities are separated: Wegent Admin manages definitions, visibility, and fixed provider headers, Wegent Backend reads ConnectorApp resources from kinds and adapts upstream protocols, and Executor exposes one local MCP endpoint to Codex. Wework has no Connector settings page; it only synchronizes available capabilities after connecting to Wegent Cloud.
๐๏ธ Global Capability Sync
Global capability sync lets Backend deliver user-enabled Skills, Plugins, and MCP servers to online local executor devices. Project tasks can reuse these local capabilities, while non-Project tasks continue to use task-scoped .claude config directories for isolation.
๐๏ธ Interactive Form Defer Flow
This document describes the standard render and resume flow for the interactiveformquestion MCP tool. The flow lets an Agent show a structured form while running, then continue from a later user message after the user submits the form.
๐๏ธ Sandbox Workspace Archive
Sandbox workspace archive preserves file state before a Sandbox runtime is deleted by the 24-hour idle cleanup, then restores those files when the same Task creates a new Sandbox runtime during a later conversation. The feature reuses the existing executor Pod workspace archive pipeline. Executor and sandbox archives both use home/ and workspace/ roots, with runtime_type selecting the runtime-specific home path.
๐๏ธ Wework Message Scroll Verification
Full-history DOM occurrence and ordering checks must establish that their fixture fits the viewport and wait for and read text from the same active pane. Goal recovery retains empty cancelled turns, so the virtual row count can exceed the number of nonempty texts. Later text being mounted near the bottom does not prove the first message is mounted. Reuse the short-conversation viewport preparation and size restoration while keeping every occurrence and ordering assertion; long-conversation scrolling keeps its overflowing fixtures.
๐๏ธ External OAuth 2.0 Integration
English | ็ฎไฝไธญๆ
๐๏ธ Task Runtime State Machine
Background
๐๏ธ Chat Shell Graceful Shutdown
Chat Shell's /v1/responses endpoint is a long-lived streaming API. When Kubernetes terminates a Pod, the service must stop accepting new traffic before waiting for existing streams to finish. Otherwise users can see interrupted SSE responses.
๐๏ธ Chat Shell dispatch connections and diagnostics
In HTTP mode, the Backend calls Chat Shell's /v1/responses using the OpenAI
๐๏ธ Rust MySQL database migrations
The Rust Backend prepares MySQL before starting background consumers and HTTP handlers. Development startup retains ENVIRONMENT=development and DBAUTOMIGRATE=true. Production checks the version and reports pending migrations without applying them.
๐๏ธ User Runtime Config
English | ็ฎไฝไธญๆ
๐๏ธ Wework Telemetry and Product Analytics
Wework separates product analytics, desktop error diagnostics, and service observability:
๐๏ธ Rust Authentication Compatibility
Rust-owned APIs use their corresponding Python authentication dependencies as the compatibility
๐๏ธ Plugin and Smart App telemetry
This document defines plugin and Smart App event coverage, success boundaries and verification requirements.
๐๏ธ QuickCard Input Presets
Overview
๐๏ธ Wework stand-in telemetry
Stand-ins share the Wework telemetry client, receiver, field policy and consent. Account identity is excluded by default. See telemetry configuration.
๐๏ธ Cross-origin iframes and region capture in Wework Smart Apps
This document defines the generic architecture for embedding a cross-origin page in a Wework
๐๏ธ Chat Shell Context Governance
Overview
๐๏ธ Shared Skill Directory
Wework provides a Skills settings page that unifies local Claude and Codex personal skill directories under ~/.agents/skills. The feature targets online Claude Code local devices and runs through local device command RPC; the browser does not access the filesystem directly.
๐๏ธ Chat Shell Attachment Context (Preview & On-Demand Read)
If you want the broader three-stage rollout, design trade-offs, and maintenance
๐๏ธ Cloud project collaboration architecture
The current V4 UI source of truth is /Users/hongyu9/Downloads/wework-delivery-v4-TODO.pen. Implement the interaction from that design instead of deriving page layout from this document.
๐๏ธ Cloud Collaboration Domain Model
This document defines the cloud collaboration concepts shared by Wework and
๐๏ธ Collaboration Workspace Storage Model
This document defines how collaboration workspaces are persisted without
๐๏ธ Wework local projects and agent execution
Wework stores and drives local projects independently of Wegent Backend. Projects,
๐๏ธ Wework collaboration execution and authorization
Project Agent bindings, Agent resource owners, Issue assigners, and runner owners are distinct identities.
๐๏ธ Wework execution state and history investigation, 2026-09-17
The investigation below records the state before the frontend fix: rolled-back product code, read-only runtime inspection and isolated A/B tests. It did not restore user data, replace executors or restart user processes. The subsequent frontend implementation is documented at the end.
๐๏ธ Collaboration permission architecture and invariants
Spaces define the administrative boundary. Projects inherit space membership by default. Resources participate through explicit use grants and project bindings. Lists and mutations share one server-side authorization policy. This document is a human-approved product contract, protected by tests.
๐๏ธ Collaboration templates
Wework exposes discovery under Collaboration โ Templates. Wegent exposes the same
๐๏ธ Project member settings
The member page uses a compact neutral settings layout with four cells per row: identity, responsibilities, role and source, and actions. Inherited-source information stays inside the role cell so it cannot displace the role control or action button.
๐๏ธ Device artifact instructions: withdrawn migration and revision compatibility
The automatic prompt update for the public Ghost/default/wegent-wework is withdrawn. Artifact delivery does not require rewriting production Ghost configuration or restoring administrator settings through a migration.
๐๏ธ Wework Stand-in
After connecting to an enterprise Backend, first-use primary setup and personal/cloud-project role creation default to an available cloud or remote device, preferring its default flag, or to the local device when neither is usable. The form allows explicitly selecting local or another device; changes reuse the unsaved-edit confirmation. Existing configured local profiles remain selected on first open; an unsaved placeholder role does not count as configuration. Explicit cloud-device choices are remembered per enterprise Backend and account without moving existing profiles when a device goes offline. Inventory changes never silently move an editor already opened. Saving and conversations use the selected Executorโs existing Runtime channels. Standalone usage and local projects retain their execution flow. No plugin, provider configuration or host provisioning is added.
๐๏ธ Rust libraries and build boundaries
Backend and Executor compile, test, and release independently, each with its own Cargo lockfile. They reuse source libraries through local path dependencies, without depending on the other application's binary or creating a repository-wide Cargo workspace.
๐๏ธ Progressive capability loading in Wework
Wework defaults to native Codex Code Mode. Built-in and MCP tools retain native registration, execution, permissions and result handling. Discover relevant entries through ALL_TOOLS; matching descriptions provide their calling signatures. The model-facing exec declaration contains execution and discovery guidance rather than the complete nested catalog. Explicit custom-model direct settings remain supported.
๐๏ธ Wework long-history responsiveness
Task control, task discovery, and transcript bodies have separate responsibilities.
๐๏ธ Wework DSH connection extension point
Connections are capabilities of outer Wework Core DSH plugins. The Codex plugin protocol remains unchanged. A connection plugin can depend on an existing Codex plugin or implement its own external access. Collection, pagination and normalization use deterministic code; models organize and process work within each role.
๐๏ธ Runtime conversation consistency
The shared conversation Store owns Wework transcripts. Execution lifecycle, Goal continuation, and composer drafts are separate state. A pane must not keep another writable transcript or infer missing history from the presence of rendered messages.
๐๏ธ ๐ ๏ธ Developer Guide
English | ็ฎไฝไธญๆ
๐๏ธ Database Migrations Guide
This guide covers database migration management using Alembic for the Wegent Backend application.
๐๏ธ OpenTelemetry Setup Guide
This guide explains how to set up and configure OpenTelemetry for distributed tracing and metrics in Wegent.
๐๏ธ Responsive Development Guide
Overview