fix(websocket,files,ui): fix ws tenant scope, missing skills path 404, and empty chat bubbles

.drone.yml

@@ -0,0 +1,22 @@
+kind: pipeline
+type: docker
+name: clawith-ci
+
+steps:
+  - name: backend-lint-and-tests
+    image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+    environment:
+      PYTHONPATH: .
+    commands:
+      - cd backend
+      - uv sync
+      - uv run ruff check app/ alembic/
+      - bash ../scripts/arch-guard.sh
+      - uv run pytest tests/ -q
+
+  - name: frontend-type-check
+    image: node:20-alpine
+    commands:
+      - cd frontend
+      - npm ci || npm install
+      - npx tsc --noEmit

.env.example

@@ -10,10 +10,17 @@ CLAWITH_DOCKER_NETWORK=clawith_network
 # Database (auto-configured by setup.sh; override for custom setups)
 # For local dev, ssl=disable is required to prevent asyncpg SSL negotiation hang
 # DATABASE_URL=postgresql+asyncpg://clawith:clawith@localhost:5432/clawith?ssl=disable
+# DB_POOL_SIZE=20
+# DB_MAX_OVERFLOW=10
 
 # Redis
 # REDIS_URL=redis://localhost:6379/0
 
+# API concurrency tuning
+# APP_WORKERS=1
+# BCRYPT_WORKERS=4
+# LOGIN_SLOW_LOG_THRESHOLD_MS=1000
+
 # LangGraph Runtime and native multi-Agent model configuration.
 # Both multi-Agent model IDs must reference enabled platform models
 # (llm_models.tenant_id IS NULL); they never fall back to a business Agent model.

.gitignore

@@ -35,12 +35,13 @@ _agent/
 _agents/
 
 # Internal docs
-docs/
 /RELEASE_NOTES.md
 /.coaligneignore
 .agents/rules/deploy.md
 backend/tests/test_agent_api_live.py
 .omx/
+.coaligne/
+.clawith-local-designs/
 
 # Local Toolathlon benchmark harness (never commit or deploy)
 backend/app/scripts/toolathlon_benchmark.py

AGENTS.md

@@ -1,31 +1,72 @@
-# Clawith Project Instructions
+# AGENTS.md — Clawith Agent Governance & Architecture Guidelines
 
-This file is the project-level entry point for agent instructions.
+---
 
-## Primary Source of Project Rules
+## 1. Project Identity
 
-For this repository, the canonical project instructions live under:
+**Clawith** — Multi-tenant Enterprise Agent Application Platform.
+Repository architecture and invariants defined in [`ARCHITECTURE_SPEC_EN.md`](file:///Users/alex/Documents/Code/dataelem/Clawith/ARCHITECTURE_SPEC_EN.md).
 
-- `.agents/rules/`
-- `.agents/workflows/`
+### Core Stack & Layout
+| Path | Component | Stack | Responsibilities |
+|---|---|---|---|
+| `backend/` | Product API & Runtime | Python 3.11+, FastAPI, SQLModel (PostgreSQL), LangGraph, Celery/Worker | API adapters, tenant isolation, durable execution state, message delivery |
+| `frontend/` | Web Interface | React 18, TypeScript, Vite, Tailwind CSS, shadcn/ui | End-user agent interaction, workspace, chat, session management |
 
-When working in this project, read and follow those files first. If this file and a file under `.agents/` ever conflict, prefer the more specific file under `.agents/`.
+### Separation of Four Kinds of Facts (Separation Principle)
+1. **Product Records**: Owner = Clawith product tables (Tenant, User, Agent, Session, Group, Permissions).
+2. **Accepted Command Inbox**: Owner = `agent_run_commands` table (Accepted start, resume, cancel inputs).
+3. **Execution Lifecycle**: Owner = LangGraph Checkpoint (PostgreSQL durable checkpoint).
+4. **User Delivery**: Owner = Product-side idempotent reconciliation and delivery.
 
-## Required Read Order
+> **CRITICAL INVARIANT (C1)**: Product projections must **NEVER** become a second Agent execution state machine. API endpoints and product services must not mutate checkpoint lifecycle fields directly or implement private execution control loops.
 
-At the start of work on Clawith, use this order:
+---
 
-1. `.agents/workflows/read_architecture.md`
-2. Relevant files under `.agents/rules/`
+## 2. P0 Architectural Constitution Rules
 
-In practice:
+The single source of truth for architectural laws is [`docs/constitution.md`](file:///Users/alex/Documents/Code/dataelem/Clawith/docs/constitution.md) (enforced by `scripts/arch-guard.sh`). Do not copy these laws here — link to them:
 
-- For general design, implementation, or feature questions, read `.agents/rules/design_and_dev.md`
-- For deployment and environment updates, read `.agents/rules/deploy.md`
-- For GitHub-related work, read `.agents/rules/github.md`
-- For versioning and release work, read `.agents/rules/release.md`
+- **C1: Runtime Boundary Isolation** → [`docs/constitution.md#C1`](file:///Users/alex/Documents/Code/dataelem/Clawith/docs/constitution.md#c1-runtime-boundary-isolation-fact-separation)
+- **C2: Strict Multi-Tenant Data Scope** → [`docs/constitution.md#C2`](file:///Users/alex/Documents/Code/dataelem/Clawith/docs/constitution.md#c2-strict-multi-tenant-data-scope--auto-injected--explicit-filters)
+- **C3: Idempotent Side Effects & Reconciliation** → [`docs/constitution.md#C3`](file:///Users/alex/Documents/Code/dataelem/Clawith/docs/constitution.md#c3-idempotent-side-effects--reconciliation)
+- **C4: Client & Gateway Wrapper Enforcement** → [`docs/constitution.md#C4`](file:///Users/alex/Documents/Code/dataelem/Clawith/docs/constitution.md#c4-client--gateway-wrapper-enforcement)
+- **C5: Database & Performance Standards** → [`docs/constitution.md#C5`](file:///Users/alex/Documents/Code/dataelem/Clawith/docs/constitution.md#c5-database--performance-standards-no-foreign-keys--n1-prevention)
+- **C6: Code Modularity & Reusability** → [`docs/constitution.md#C6`](file:///Users/alex/Documents/Code/dataelem/Clawith/docs/constitution.md#c6-code-modularity--reusability-recommended-size-thresholds--helper-layer)
 
-## Notes
+---
 
-- The architecture document currently present in this repository is `ARCHITECTURE_SPEC_EN.md`
-- Do not invent alternative instruction filenames when the real rules already exist under `.agents/`
+## 3. Quick Command Reference
+
+Dev and test commands live in sub-project instruction files:
+- Backend: `backend/AGENTS.md` (Server start, Alembic migrations, Pytest, Ruff)
+- Frontend: `frontend/AGENTS.md` (Vite dev server, type-check, lint, build)
+
+---
+
+## 4. SDD Workflow (Specification-Driven Development)
+
+For non-trivial features or architecture refactoring, follow this workflow:
+
+```text
+1. Spec Discovery                          → ★ User Confirms
+2. spec.md   → /sdd-review <dir> spec       → ★ User Confirms
+3. design.md → /sdd-review <dir> design     → ★ User Confirms (Constitution Check)
+4. tasks.md  → /sdd-review <dir> tasks
+5. Branch feat/{NNN}-{name}
+6. Implement Wave-by-Wave & Run unit tests → /task-review
+7. Run scripts/arch-guard.sh & test suite
+8. /code-review --base main
+```
+*Note: ★ indicates mandatory user confirmation gates.*
+
+---
+
+## 5. Instruction File Mapping (AGENTS.md Hierarchy)
+
+- **Root `AGENTS.md`** (This file): Single source of truth for global constitution, architecture topology, SDD workflow, and P0 rules.
+- **[`backend/AGENTS.md`](file:///Users/alex/Documents/Code/dataelem/Clawith/backend/AGENTS.md)**: Backend-specific coding standards, Python import rules, database access guidelines.
+- **[`backend/alembic/AGENTS.md`](file:///Users/alex/Documents/Code/dataelem/Clawith/backend/alembic/AGENTS.md)**: Database migration standards, timestamp conventions, lock safety.
+- **[`frontend/AGENTS.md`](file:///Users/alex/Documents/Code/dataelem/Clawith/frontend/AGENTS.md)**: Frontend-specific coding standards, React/TS guidelines, HTTP wrapper usage.
+
+> **RULE**: Sub-directory `AGENTS.md` files extend root guidelines. Never duplicate root rules in sub-files. If a rule spans multiple components, put it here.

CLAUDE.md

@@ -1,158 +1 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Clawith is an open-source multi-agent collaboration platform — a "digital employee" system where AI agents have persistent identity (`soul.md`), long-term memory (`memory.md`), autonomous awareness (cron/interval/webhook triggers), and can communicate with each other (A2A) and with humans via omni-channel integrations (Feishu, DingTalk, WeCom, Slack, Discord).
-
-## Agent Instructions
-
-Per `AGENTS.md`, canonical project rules live under `.agents/`. Read in this order at the start of work:
-
-1. `.agents/workflows/read_architecture.md` (architecture overview)
-2. `.agents/rules/design_and_dev.md` — for feature/implementation work
-3. `.agents/rules/deploy.md` — for deployment/environment changes
-4. `.agents/rules/github.md` — for GitHub-related work
-5. `.agents/rules/release.md` — for versioning/release work
-
-The architecture reference document is `ARCHITECTURE_SPEC_EN.md`.
-
-## Commands
-
-### Backend (Python / FastAPI)
-
-```bash
-cd backend
-
-# Install dependencies
-pip install -e ".[dev]"
-
-# Run dev server
-uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
-
-# Run all tests
-pytest
-
-# Run a single test file
-pytest tests/test_auth.py -v
-
-# Run a single test
-pytest tests/test_auth.py::test_login -v
-
-# Lint
-ruff check .
-ruff format .
-
-# Database migrations
-alembic upgrade head
-alembic revision --autogenerate -m "description"
-```
-
-### Frontend (React / TypeScript / Vite)
-
-```bash
-cd frontend
-
-# Install dependencies
-npm install
-
-# Dev server (http://localhost:5173)
-npm run dev
-
-# Type-check + build
-npm run build
-
-# Preview production build
-npm run preview
-```
-
-### Full Stack (Docker Compose)
-
-```bash
-# One-command setup (creates .env, PostgreSQL, installs deps)
-bash setup.sh
-
-# Start all services → http://localhost:3008
-bash restart.sh
-
-# Deploy to dev server (192.168.106.163, port 3009)
-# See .agents/workflows/deploy-dev.md for full steps
-```
-
-## Architecture
-
-### Monorepo Layout
-
-- `backend/` — Python 3.11+ FastAPI app
-- `frontend/` — React 19 TypeScript app (Vite)
-- `helm/` — Kubernetes Helm charts
-- `.agents/` — Agent workflow and rule files
-
-### Backend Structure (`backend/app/`)
-
-| Directory | Purpose |
-|-----------|---------|
-| `api/` | 36 FastAPI route modules (one per domain) |
-| `services/` | Business logic (78 modules) |
-| `models/` | SQLAlchemy 2.0 async ORM entities |
-| `schemas/` | Pydantic request/response schemas |
-| `core/` | Auth, events, middleware, logging |
-| `alembic/` | Database migrations |
-
-**Critical files:**
-- `api/websocket.py` — Tool-calling loop (up to 50 iterations: LLM → Tool → Context reassembly), LLM streaming
-- `api/gateway.py` — OpenClaw edge node protocol (poll/report/send for local agents)
-- `services/agent_tools.py` — All file-based tools (`read_file`, `write_file`, `send_message_to_agent`, etc.)
-- `services/agent_context.py` — Assembles LLM context from `soul.md`, system prompts, `memory.md`
-- `services/trigger_daemon.py` — Background scheduler for the Aware Engine (cron/interval/poll/on_message triggers)
-
-### Frontend Structure (`frontend/src/`)
-
-| Directory | Purpose |
-|-----------|---------|
-| `pages/` | 19 page components |
-| `components/` | Reusable UI components |
-| `stores/` | Zustand global state (auth, permissions, i18n) |
-| `services/` | Axios API client |
-| `hooks/` | Custom React hooks |
-| `i18n/` | Internationalization |
-
-**Critical files:**
-- `pages/AgentDetail.tsx` — Agent chat UI, settings, triggers, relationships (~427KB)
-- `pages/EnterpriseSettings.tsx` — Enterprise config, channels, auth providers (~256KB)
-- `App.tsx` — Main router with protected routes
-
-### Key Data Models
-
-- `Agent` — Digital employee entity (native or OpenClaw edge node)
-- `Participant` — Multi-party communication routing anchor (determines left/right bubble rendering)
-- `ChatSession` / `ChatMessage` — Full audit trail including tool_call snapshots
-- `AgentTrigger` — Aware Engine scheduling (cron, interval, poll, webhook, on_message)
-- `AgentAgentRelationship` — Strict A2A access control (agents must have explicit relationship to communicate)
-- `Tenant` / `OrgDepartment` / `OrgMember` — Multi-tenant isolation (all entities carry `tenant_id`)
-
-### Multi-Tenant Pattern
-
-Every database entity includes `tenant_id`. All queries must filter by tenant. The `OrgMember` table maps external channel users (Feishu/DingTalk/WeCom) to internal users.
-
-### WebSocket Tool-Calling Loop
-
-The core LLM execution in `api/websocket.py` runs up to 50 iterations. Each iteration: call LLM → parse tool calls → execute tools → reassemble context → repeat. Resource warnings fire at 80% of the round limit. High-risk tools (`write_file`, `delete_file`) have hard parameter validation.
-
-### Agent Workspace
-
-Each agent has a private file workspace under `agent_template/`. The files `soul.md` (personality) and `memory.md` (long-term memory) are injected into every LLM context via `services/agent_context.py`.
-
-## Tech Stack
-
-- **Backend**: Python 3.11+, FastAPI, SQLAlchemy 2.0 (async), PostgreSQL 15+ / SQLite (dev), Redis 7+
-- **Frontend**: React 19, TypeScript, Vite 6, Zustand 5, TanStack Query 5, React Router 7, i18next
-- **LLM**: Unified abstraction in `services/llm/` supporting OpenAI, Anthropic Claude, DeepSeek, and others
-- **Integrations**: Feishu/Lark, DingTalk, WeCom, Slack, Discord, Jira/Confluence, Microsoft Teams
-- **Linting**: Ruff (Python, line-length 120, target py311), TypeScript strict mode
-- **Testing**: pytest + pytest-asyncio (asyncio_mode = "auto")
-
-## Code Guidelines
-
-- **Python Imports**: Python imports should be placed at the top of the file (file header) as much as possible. Avoid inline imports within functions or methods unless strictly necessary (e.g., to prevent circular import dependencies).
+AGENTS.md

backend/AGENTS.md

@@ -0,0 +1,75 @@
+# Backend AGENTS.md — Clawith Backend Guidelines
+
+---
+
+## 1. Subsystem Overview
+
+**Stack**: Python 3.11+, FastAPI, SQLModel (SQLAlchemy 2.0+), Alembic, LangGraph, Celery / Worker processes, Pytest.
+**Root Spec**: Extended from root [`AGENTS.md`](file:///Users/alex/Documents/Code/dataelem/Clawith/AGENTS.md).
+
+---
+
+## 2. Common Commands
+
+From `backend/` directory:
+
+| Action | Command |
+|---|---|
+| Run Dev Server | `uv run uvicorn app.main:app --reload --port 8000` |
+| Run Unit Tests | `uv run pytest` |
+| Run Specific Test File | `uv run pytest tests/test_agent_runtime.py` |
+| Run Linter / Format Check | `uv run ruff check .` |
+| Run Auto-Fix Linter | `uv run ruff check --fix .` |
+| Generate DB Migration | `uv run alembic revision --autogenerate -m "description"` |
+| Apply DB Migrations | `uv run alembic upgrade head` |
+
+---
+
+## 3. Python Coding Standards
+
+### 3.1 Import Placement
+- **File Header Placement**: All Python imports MUST be placed at the top of the file (file header).
+- **No Inline Imports**: Avoid inline/local imports within functions or methods unless strictly necessary (e.g., to break circular import dependencies).
+
+### 3.2 Multi-Tenant Scope (P0 - C2)
+- **Mandatory Tenant Filter**: Every database query (`select(...)`), update, or delete MUST explicitly include `tenant_id` scoping to guarantee data isolation.
+- **Worker & Context Var**: Ensure background tasks propagate tenant context correctly.
+
+### 3.3 Code Formatting & Type Safety
+- **Ruff Compliance**: Code must adhere to Ruff rules (max line length: 120, target-version: `py311`).
+- **Type Annotations**: All public functions and endpoint handlers must include explicit type hints for parameters and return values.
+
+### 3.4 Code Splitting Guidelines (C6)
+- **Function Length Recommendation**: Recommended ~**100 lines** per function. Treat functions exceeding this size as candidates for refactoring into sub-functions or helper modules (flexible guideline).
+- **File Length Recommendation**: Backend Python files recommended ~**1000 lines**. Split oversized files into modular sub-files when reasonable.
+
+### 3.5 Anti-Reinvention & Helper Layer (C6)
+- **Search Before Coding**: Check `app/core/`, `app/utils/`, and `app/helpers/` before writing custom helper/utility functions.
+- **Extract Common Logic**: Promote reusable operations (formatting, ID generation, string manipulation) into shared `utils/helpers` modules.
+
+### 3.6 Database & Query Performance (C5)
+- **No Physical Foreign Keys**: Do not define physical `FOREIGN KEY` constraints at the DB layer. Keep relationship checks at the SQLModel / application layer.
+- **Minimize DB JOINs & N+1 Prevention**: Avoid multi-table complex JOINs. Use batch query interfaces (`where(Model.id.in_(ids))` / batch APIs) and `selectinload` to prevent N+1 loop queries.
+
+---
+
+## 4. Subsystem Layout & Architectural Invariants
+
+- `app/api/`: FastAPI endpoints & HTTP/WS adapters.
+  - **Rule**: Must NOT invoke LangGraph node executors directly. Must submit commands through `RuntimeCommandIntake`. Must NOT write raw ORM queries; delegate to `app/dao/`.
+- `app/dao/`: Data Access Objects (Detailed guidelines → [`app/dao/AGENTS.md`](file:///Users/alex/Documents/Code/dataelem/Clawith/backend/app/dao/AGENTS.md)).
+  - **Rule**: Exclusive owner of database queries and persistence. Must enforce `tenant_id` scope.
+- `app/services/agent_runtime/`: Core execution boundary.
+  - `command_worker.py`: Claims durable commands and executes graph turns.
+  - `graph.py`: LangGraph graph topology definition.
+- `app/models/`: SQLModel data models.
+- `app/services/`: Product domain logic services.
+
+---
+
+## 5. Testing Conventions
+
+- Place unit and integration tests under `tests/`.
+- Name test files with `test_` prefix (e.g., `tests/test_runtime_intake.py`).
+- Use `@pytest.mark.asyncio` for async test functions.
+