8629ac709b
## Phase 1-3: Control Plane + Contract System - awooop_phase1_control_plane_2026-05-04.sql: 12 張核心表 + RLS - awooop_phase1_batch1_rls_2026-05-04.sql: 全部 FORCE RLS + GRANT - packages/awooop-contracts/: 六合約 JSON Schema + golden fixtures - src/models/awooop_contracts.py: Pydantic v2 contract models（extra=forbid） - src/repositories/contract_repository.py: contract lifecycle（draft→published→active） - src/services/contract_service.py: HMAC publish sig + Redis multi-sig activate - src/services/schema_validator.py: LLM output validator（retry×3, E-SCHEMA-001） ## Phase 2: Tenant Isolation - awooop_phase2_budget_ledger_2026-05-04.sql: budget_ledger + RLS - src/services/budget_service.py: Token Budget Hard Kill 三層防線 - src/core/context.py: PROJECT_ID ContextVar（31 background loop 自動繼承） - src/db/base.py + models.py: project_id 欄位 + RLS set_config 注入 - src/hermes/nl_gateway.py: project_id Redis key 前綴（Phase A 雙寫） - src/services/anomaly_counter.py: per-project 改造（Phase A fallback） ## Phase 4: Platform Shell in Shadow Mode - awooop_phase4_run_state_2026-05-04.sql: run_state + step_journal + idempotency - src/services/run_state_machine.py: 8-state FSM + SKIP LOCKED + stale reaper - src/services/platform_runtime.py: UUID v7 + W3C trace_id + shadow_execute - src/services/audit_sink.py: PII/secret redaction 9 patterns - src/api/v1/platform/runs.py: POST/GET /v1/platform/runs（Router→Service 架構） - src/workers/platform_worker.py: SKIP LOCKED worker + heartbeat + reaper loop - src/main.py: platform router + lifespan worker start/stop ## Phase 5: MCP Gateway 五閘門 - awooop_phase5_mcp_gateway_2026-05-04.sql: 4 表 + RLS - src/plugins/mcp/gateway.py: McpGateway（Gate 1~5, E-MCP-GATE-001~009） - src/plugins/mcp/redaction_middleware.py: 雙層 redaction + 16K 截斷 - src/plugins/mcp/registry.py: __provider name mangling（ADR-116） - src/plugins/mcp/credential_resolver.py: k8s secret ref 解析 - tests/test_mcp_credential_isolation.py: 10 個迴歸測試（secret leak 防再現） ## Phase 6-8: EwoooC + Channel Hub + Approval Token - awooop_phase6_ewoooc_onboarding_2026-05-04.sql: ewoooc tenant + 4 read-only MCP tools - awooop_phase7_channel_hub_2026-05-04.sql: conversation_event + outbound_message - src/services/provider_proxy.py: ProviderProxy + PlatformEnvelope（ADR-115） - src/services/channel_hub.py: Telegram inbound mirror + Progressive Feedback（30s） - src/services/awooop_approval_token.py: HS256 + jti NX replay 防護 + suggest mode Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
324 lines
11 KiB
Markdown
324 lines
11 KiB
Markdown
# AwoooP Implementation Roadmap
|
|
|
|
**Status**: Planning baseline
|
|
**Date**: 2026-05-01
|
|
**Owner**: AWOOOI / AwoooP platform workstream
|
|
**Primary ADRs**: ADR-106, ADR-107
|
|
|
|
## Purpose
|
|
|
|
This document is the implementation handoff for AwoooP, the AWOOOI Agent
|
|
Platform.
|
|
|
|
ADRs record architectural decisions. This roadmap translates those decisions
|
|
into execution phases, work items, acceptance gates, and Codex workflow
|
|
guidance.
|
|
|
|
## Executive Summary
|
|
|
|
AwoooP is the multi-tenant Agent Platform extracted from the AI capabilities
|
|
that first emerged inside AWOOOI.
|
|
|
|
AWOOOI is the first tenant and first runtime host. It is not the platform
|
|
boundary.
|
|
|
|
AwoooP must let current and future products share AI agents and communication
|
|
capabilities without copying project-specific code:
|
|
|
|
- AWOOOI: AIOps, SRE automation, K8s/MCP/Telegram workflows
|
|
- EwoooC / MOMO PRO: ecommerce and business analysis, market intelligence, LINE
|
|
and Telegram workflows
|
|
- Tsenyang: existing Telegram webhook surface
|
|
- Bitan and future products: repeatable onboarding to shared AI capabilities
|
|
|
|
The approved direction is not a pure HTTP hub, not only an SDK, and not only a
|
|
shared config table. The approved direction is:
|
|
|
|
```text
|
|
AwoooP = Control Plane + Agent Runtime + MCP Gateway + Context Firewall
|
|
+ Communication Hub + Observability / Audit
|
|
```
|
|
|
|
## Core Decisions
|
|
|
|
### Product and Layout
|
|
|
|
- Product name: `AwoooP`
|
|
- Repository/package slug: `awooop`
|
|
- Existing AWOOOI tenant id remains `awoooi`
|
|
- Do not create empty runtime or package directories before implementation owns
|
|
real code.
|
|
- `docs/awooop/` is allowed now because it contains concrete implementation
|
|
planning artifacts.
|
|
|
|
Future code layout should be created only when each path owns real artifacts:
|
|
|
|
| Path | Create when | Owns |
|
|
|---|---|---|
|
|
| `packages/awooop-contracts/` | Contract schemas are ready to validate | JSON Schema / Pydantic / TS types |
|
|
| `packages/awooop-client/` | First downstream client integration begins | Python/TS SDK |
|
|
| `apps/awooop-runtime/` | Runtime shell separates from `apps/api` | Platform API and run orchestration |
|
|
| `apps/awooop-worker/` | Async workers are needed | Run state execution workers |
|
|
| `docs/awooop/` | Planning and implementation docs exist | Roadmaps, schema notes, runbooks |
|
|
|
|
### Storage
|
|
|
|
AwoooP v1 is PostgreSQL-first.
|
|
|
|
- PostgreSQL is source of truth for contracts, active revisions, tenant records,
|
|
policy, MCP grants, budget, ACL, run state, approval, channel event, and audit.
|
|
- Redis is cache/watch/counter/coordination only.
|
|
- Prompt, JSON Schema, eval, and replay artifacts are stored by ref + SHA-256
|
|
hash.
|
|
- Kubernetes CRDs are future runtime projection only, not the v1 control-plane
|
|
source of truth.
|
|
|
|
### Six Contracts
|
|
|
|
| Contract | Purpose |
|
|
|---|---|
|
|
| Project / Tenant | Tenant identity, data boundary, budget, ACL, channels, approval gates |
|
|
| Agent | Versioned capability module, I/O schema, context domain, safety ceiling |
|
|
| MCP Gateway | Tool authorization, credential resolution, approval, result sanitization |
|
|
| Policy / Routing | Effective model/provider route, fallback, privacy and budget gates |
|
|
| Runtime / Run State | Durable async run lifecycle, shadow/canary/active, checkpoint/resume |
|
|
| Communication / Channel Event | Telegram/LINE/Slack/Email/API receive, verify, normalize, send |
|
|
|
|
## Migration Strategy
|
|
|
|
AwoooP must migrate by strangler fig, not big-bang replacement:
|
|
|
|
1. `shadow`: mirror events, write audit/trace only, no user response, no side
|
|
effects.
|
|
2. `canary`: selected low-risk user-visible responses, no side effects by
|
|
default.
|
|
3. `read_only`: read-only queries and business chat move first.
|
|
4. `suggest`: analysis and recommendations move next; approval still external.
|
|
5. `auto_remediate`: write/execute tools move only after Gateway, approval,
|
|
replay, audit, and rollback evidence are green.
|
|
|
|
## Implementation Phases
|
|
|
|
### Phase 0 - Documentation Freeze
|
|
|
|
Goal: make future implementation unambiguous.
|
|
|
|
Status: in progress / mostly complete.
|
|
|
|
Work items:
|
|
|
|
- ADR-106: AwoooP architecture and migration strategy.
|
|
- ADR-107: AwoooP control-plane storage strategy.
|
|
- This roadmap.
|
|
- LOGBOOK entries for ADR-106/107 and roadmap.
|
|
- Task-routing lookup in `docs/12-agent-game-rules.md`.
|
|
|
|
Acceptance:
|
|
|
|
- `git diff --check` passes.
|
|
- No runtime code changes.
|
|
- No empty code directories.
|
|
|
|
### Phase 1 - Control Plane Schema Foundation
|
|
|
|
Goal: create the minimum PostgreSQL foundation for contract materialization.
|
|
|
|
Suggested work items:
|
|
|
|
- Add `awooop_contract_revisions`.
|
|
- Add active revision pointer tables.
|
|
- Add `awooop_projects` / tenant records.
|
|
- Add `awooop_artifact_refs`.
|
|
- Add `awooop_project_migration_state`.
|
|
- Add `project_id` strategy for existing AWOOOI records.
|
|
- Add tests for immutable published revisions and draft isolation.
|
|
|
|
Acceptance:
|
|
|
|
- Published contract revision is append-only.
|
|
- Runtime-facing reads cannot see mutable drafts.
|
|
- Every active revision has `revision_id` and `body_hash`.
|
|
- AWOOOI can be represented as `project_id=awoooi` without behavior changes.
|
|
|
|
### Phase 2 - Isolation and Namespace Hardening
|
|
|
|
Goal: make AWOOOI tenant-safe before sharing anything downstream.
|
|
|
|
Suggested work items:
|
|
|
|
- Prefix Redis sessions, budget, rate, and Telegram/Hermes keys with
|
|
`project_id`.
|
|
- Add `project_id` columns where required for logs, audit, sessions, and
|
|
approval records.
|
|
- Define `platform_resource` exceptions separately from tenant resources.
|
|
- Convert global resources such as Ollama failover state into explicit platform
|
|
resources.
|
|
- Add regression tests for cross-project read/write rejection.
|
|
|
|
Acceptance:
|
|
|
|
- Tenant-scoped data cannot be read without matching `project_id`.
|
|
- Platform resources are explicitly allowed and audited.
|
|
- No prompt text is trusted as the data isolation boundary.
|
|
|
|
### Phase 3 - Contract Packages and Validators
|
|
|
|
Goal: make the six contracts executable rather than prose-only.
|
|
|
|
Suggested work items:
|
|
|
|
- Create `packages/awooop-contracts/` only when validators are implemented.
|
|
- Define JSON Schema/Pydantic models for the six contracts.
|
|
- Define envelope schemas for platform invocation, MCP tool call, run state, and
|
|
channel events.
|
|
- Add output schema validator middleware design.
|
|
- Add golden fixtures for valid and invalid contracts.
|
|
|
|
Acceptance:
|
|
|
|
- Contract validation fails closed.
|
|
- LLM output that fails schema validation cannot reach channel adapters.
|
|
- Prompt/schema refs require SHA-256 hashes.
|
|
|
|
### Phase 4 - Platform Shell in Shadow Mode
|
|
|
|
Goal: build the first runtime shell without replacing legacy behavior.
|
|
|
|
Suggested work items:
|
|
|
|
- Add `/v1/platform/runs` shell around existing AWOOOI logic.
|
|
- Generate `run_id` and `trace_id`.
|
|
- Resolve project and agent contract revisions.
|
|
- Resolve `EffectivePolicy` without changing provider behavior.
|
|
- Write run state transitions and audit.
|
|
- Mirror selected AWOOOI events into AwoooP shadow mode.
|
|
|
|
Acceptance:
|
|
|
|
- Shadow runs produce audit and trace.
|
|
- Shadow runs never send user-visible responses.
|
|
- Shadow runs never call write/execute/destructive tools.
|
|
- Legacy AWOOOI behavior remains unchanged.
|
|
|
|
### Phase 5 - MCP Gateway First Slice
|
|
|
|
Goal: move tool authorization behind a real Gateway.
|
|
|
|
Suggested work items:
|
|
|
|
- Define MCP Gateway tables for tool registry, grants, credentials refs, and
|
|
audit.
|
|
- Wrap current read-only MCP tools behind Gateway checks.
|
|
- Enforce `Project AND Agent AND Tool AND Environment AND Approval`.
|
|
- Sanitize tool results before model context.
|
|
- Record tool call `trace_id`, `run_id`, credential ref, latency, result status.
|
|
|
|
Acceptance:
|
|
|
|
- Agents never see raw credentials.
|
|
- Read-only tools are auditable by `trace_id`.
|
|
- Write/execute tools stay blocked until later phases.
|
|
|
|
### Phase 6 - EwoooC Read-Only Tenant Onboarding
|
|
|
|
Goal: validate AwoooP with a real downstream tenant without high-risk actions.
|
|
|
|
Suggested work items:
|
|
|
|
- Create `project_id=ewoooc`.
|
|
- Register `openclaw-biz` as a specialized agent contract.
|
|
- Register market-intelligence tools as read-only MCP Gateway tools.
|
|
- Add a read-only platform client path.
|
|
- Mirror EwoooC bot/business-analysis events into shadow/canary.
|
|
|
|
Acceptance:
|
|
|
|
- EwoooC can run read-only AwoooP shadow/canary without touching AWOOOI data.
|
|
- Business-agent context cannot access infra-only AWOOOI context.
|
|
- Budget and audit are project-scoped.
|
|
|
|
### Phase 7 - Communication Hub Increment
|
|
|
|
Goal: standardize channels without breaking existing bots.
|
|
|
|
Suggested work items:
|
|
|
|
- Define `ConversationEvent` and `OutboundMessage` tables.
|
|
- Mirror Telegram inbound events first.
|
|
- Add progressive status feedback policy for async runs.
|
|
- Keep existing bot handlers authoritative until canary passes.
|
|
- Add adapter-level escaping, redaction, idempotency, and delivery audit.
|
|
|
|
Acceptance:
|
|
|
|
- Channel adapters do not call LLM or MCP.
|
|
- Async runs can produce progress updates.
|
|
- Duplicate channel retries do not create duplicate runs.
|
|
|
|
### Phase 8 - Suggest and Controlled Write Paths
|
|
|
|
Goal: graduate from read-only to proposal and then controlled execution.
|
|
|
|
Suggested work items:
|
|
|
|
- Enable `suggest` mode for selected AWOOI SRE flows.
|
|
- Add approval resume for `WAITING_APPROVAL`.
|
|
- Add dry-run and rollback evidence gates.
|
|
- Move low-risk write paths only after Gateway and audit evidence are stable.
|
|
|
|
Acceptance:
|
|
|
|
- `WAITING_APPROVAL` resumes without replaying the whole task.
|
|
- Rejected or expired approvals fail with structured failure codes.
|
|
- Write/execute paths are blocked by default and feature-flagged.
|
|
|
|
## Codex Workflow Recommendation
|
|
|
|
Use a new Codex conversation for implementation, but keep the working directory
|
|
at the monorepo root:
|
|
|
|
```text
|
|
/Users/ogt/awoooi
|
|
```
|
|
|
|
Do not start from a new project directory until `apps/awooop-runtime` or
|
|
`packages/awooop-*` actually exists and owns code.
|
|
|
|
Recommended implementation kickoff prompt:
|
|
|
|
```text
|
|
Read AGENTS.md, docs/12-agent-game-rules.md, docs/LOGBOOK.md newest entry,
|
|
docs/adr/ADR-106-agent-platform-architecture.md,
|
|
docs/adr/ADR-107-awooop-control-plane-storage.md, and
|
|
docs/awooop/IMPLEMENTATION-ROADMAP.md.
|
|
|
|
Start Phase 1 only: design and implement the minimum PostgreSQL control-plane
|
|
schema foundation for AwoooP contract revisions. Do not create runtime APIs,
|
|
do not change provider behavior, do not move Telegram/LINE webhooks, and do not
|
|
create empty AwoooP code directories.
|
|
```
|
|
|
|
If the current worktree is dirty, prefer a clean branch or clean worktree before
|
|
runtime implementation. Documentation-only planning can remain in this thread.
|
|
|
|
## First Implementation Slice
|
|
|
|
The first code slice should be deliberately boring:
|
|
|
|
1. DB migration for contract revisions and active pointers.
|
|
2. Pydantic/SQLAlchemy models for contract revisions.
|
|
3. Repository/service methods for draft, publish, activate, and read active.
|
|
4. Tests for immutability and draft isolation.
|
|
5. LOGBOOK update.
|
|
|
|
Do not start with MCP Gateway, Telegram Hub, or model routing. Those are more
|
|
visible, but they depend on the contract source of truth.
|
|
|
|
## References
|
|
|
|
- `docs/adr/ADR-106-agent-platform-architecture.md`
|
|
- `docs/adr/ADR-107-awooop-control-plane-storage.md`
|
|
- `docs/adr/ADR-105-mcp-agent-loop-governance.md`
|
|
- `docs/12-agent-game-rules.md`
|
|
- `docs/LOGBOOK.md`
|