wooo/awoooi
1
1
Fork 0
Code Issues 2 Pull Requests 1 Actions 3 Packages Projects Releases Wiki Activity
Files
2a2cb16c135fd7e5b159d94de9b5ff04f6cf31f5
awoooi/docs/awooop/IMPLEMENTATION-ROADMAP.md
Your Name 8629ac709b
Some checks failed
run-migration / migrate (push) Failing after 59s
Details
Code Review / ai-code-review (push) Successful in 1m8s
Details
Type Sync Check / check-type-sync (push) Successful in 2m27s
Details
feat(awooop): Phase 1-8 完整實作 — AwoooP Agent Platform 六平面架構 
## 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>
2026-05-04 19:31:53 +08:00

11 KiB
Raw Blame History

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:

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:

/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:

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
Reference in New Issue View Git Blame Copy Permalink