# Robot Agent - Implementation TODO

> Based on DESIGN.md and TECHNICAL.md
> Test environment: `source yao/env.local.sh`
> Test assistants: `yao-dev-app/assistants/robot/`

---

## Workflow: Human-AI Collaboration

**Important:** Follow this workflow strictly for each sub-task.

```
┌─────────────────────────────────────────────────────────────────┐
│                     Implementation Workflow                      │
├─────────────────────────────────────────────────────────────────┤
│  1. AI: Implement code for current sub-task                     │
│  2. AI: Present code for review (DO NOT write tests yet)        │
│  3. Human: Review code, provide feedback                        │
│  4. AI: Iterate based on feedback                               │
│  5. Human: Confirm "LGTM" or "Approved"                         │
│  6. AI: Write tests for the approved code                       │
│  7. Human: Review tests                                         │
│  8. AI: Run tests, fix if needed                                │
│  9. Human: Confirm sub-task complete, move to next              │
└─────────────────────────────────────────────────────────────────┘
```

**Rules:**

| Rule                     | Description                                |
| ------------------------ | ------------------------------------------ |
| One sub-task at a time   | Focus only on current sub-task             |
| No tests before approval | Wait for human "LGTM" before writing tests |
| No jumping ahead         | Do not implement future phases             |
| Ask if unclear           | When in doubt, ask before proceeding       |

---

## Core Principle

- Phase 1-2: Types + Skeleton (code compiles)
- Phase 3: Complete scheduling system (Cache + Pool + Trigger + Dedup + Job), executor is stub
- Phase 4-9: Implement executor phases one by one (P0 → P5)
- Phase 10: API completion, end-to-end tests
- Monitoring: Provided by Job system, no separate implementation

---

## Phase 1: Types & Interfaces ✅

**Goal:** Define all types, enums, interfaces. No logic, no external deps.

**Status:** Complete - 88.4% test coverage, all tests passing

### 1.1 Enums (`types/enums.go`)

- [x] `Phase` - execution phases (inspiration, goals, tasks, run, delivery, learning)
- [x] `ClockMode` - clock trigger modes (times, interval, daemon)
- [x] `TriggerType` - trigger sources (clock, human, event)
- [x] `ExecStatus` - execution status (pending, running, completed, failed, cancelled)
- [x] `RobotStatus` - robot status (idle, working, paused, error, maintenance)
- [x] `InterventionAction` - human actions (task.add, goal.adjust, etc.)
- [x] `Priority` - priority levels (high, normal, low)
- [x] `DeliveryType` - delivery types (email, webhook, process, notify)
- [x] `DedupResult` - dedup results (skip, merge, proceed)
- [x] `EventSource` - event sources (webhook, database)
- [x] `LearningType` - learning types (execution, feedback, insight)
- [x] `TaskSource` - task sources (auto, human, event)
- [x] `ExecutorType` - executor types (assistant, mcp, process)
- [x] `TaskStatus` - task status (pending, running, completed, failed, skipped, cancelled)
- [x] `InsertPosition` - insert positions (first, last, next, at)

### 1.2 Context (`types/context.go`)

- [x] `Context` struct - robot execution context
- [x] `NewContext()` - constructor
- [x] `UserID()`, `TeamID()` - helper methods

### 1.3 Config Types (`types/config.go`)

- [x] `Config` - main config struct
- [x] `Triggers`, `TriggerSwitch` - trigger enable/disable
- [x] `Clock` - clock config with validation
- [x] `Identity` - role, duties, rules
- [x] `Quota` - concurrency limits with defaults
- [x] `KB`, `DB` - knowledge base and database config
- [x] `Learn` - learning config
- [x] `Resources`, `MCPConfig` - available agents and tools
- [x] `Delivery` - output delivery config
- [x] `Event` - event trigger config

### 1.4 Core Types (`types/robot.go`)

- [x] `Robot` struct - runtime robot representation
- [x] `Robot` methods - `CanRun()`, `RunningCount()`, `AddExecution()`, `RemoveExecution()`, `GetExecution()`, `GetExecutions()`
- [x] `Execution` struct - single execution instance
- [x] `TriggerInput` - stored trigger input
- [x] `CurrentState` - current executing state
- [x] `Goals` - P1 output (markdown)
- [x] `Task` - planned task (structured)
- [x] `TaskResult` - task execution result
- [x] `DeliveryResult` - delivery output
- [x] `LearningEntry` - knowledge to save

### 1.5 Clock Context (`types/clock.go`)

- [x] `ClockContext` struct - time context for P0
- [x] `NewClockContext()` - constructor

### 1.6 Inspiration (`types/inspiration.go`)

- [x] `InspirationReport` struct - P0 output

### 1.7 Request/Response (`types/request.go`)

- [x] `InterveneRequest` - human intervention request
- [x] `EventRequest` - event trigger request
- [x] `ExecutionResult` - trigger result
- [x] `RobotState` - robot status query result

### 1.8 Interfaces (`types/interfaces.go`)

- [x] `Manager` interface
- [x] `Executor` interface
- [x] `Pool` interface
- [x] `Cache` interface
- [x] `Dedup` interface
- [x] `Store` interface

### 1.9 Errors (`types/errors.go`)

- [x] Config errors
- [x] Runtime errors
- [x] Phase errors

### 1.10 Tests

- [x] `types/enums_test.go` - enum validation
- [x] `types/config_test.go` - config validation
- [x] `types/clock_test.go` - clock context creation
- [x] `types/robot_test.go` - robot methods

---

## Phase 2: Skeleton Implementation ✅

**Goal:** Create all packages with empty/stub implementations. Code compiles.

**Status:** Complete - All packages compile successfully, no circular dependencies

### 2.1 Utils (`utils/`) ✅

- [x] `utils/convert.go` - JSON, map, struct conversions (implement)
- [x] `utils/time.go` - time parsing, formatting, timezone (implement)
- [x] `utils/id.go` - ID generation (nanoid) (implement)
- [x] `utils/validate.go` - validation helpers (implement)
- [x] Test: `utils/utils_test.go`

### 2.2 Package Skeletons ✅ (stubs only, implemented in Phase 3)

Create empty structs and stub methods that return nil/empty/success:

- [x] `cache/cache.go` - Cache struct, stub methods
- [x] `dedup/dedup.go` - Dedup struct, stub methods
- [x] `store/store.go` - Store struct, stub methods
- [x] `pool/pool.go` - Pool struct, stub methods
- [x] `plan/plan.go` - Plan struct, stub methods
- [x] `trigger/trigger.go` - trigger dispatcher stub
- [x] `executor/executor.go` - Executor struct, stub `Execute()`
- [x] `manager/manager.go` - Manager struct, stub methods

### 2.3 API Skeletons ✅

- [x] `api/api.go` - Go API facade (all function signatures, return errors)
- [x] `api/process.go` - Yao Process registration (all processes, return errors)
- [x] `api/jsapi.go` - JSAPI registration (all methods, return errors)

### 2.4 Root ✅

- [x] `robot.go` - package entry
  - [x] `Init()` - placeholder
  - [x] `Shutdown()` - placeholder

### 2.5 Compile Test ✅

- [x] All packages compile without errors
- [x] All imports resolve correctly
- [x] No circular dependencies

---

## Phase 3: Complete Scheduling System ✅

**Goal:** Implement complete scheduling system. Executor is stub (simulates success).

**Status:** Complete - All 7 sub-tasks done, 80+ integration tests passing

This phase delivers a fully working scheduling pipeline:

```
Trigger → Manager → Cache → Dedup → Pool → Worker → Executor(stub) → Job
```

### ✅ 3.1 Cache Implementation (COMPLETE)

- [x] `cache/cache.go` - Cache struct with thread-safe map
- [x] `cache/load.go` - load robots from `__yao.member` where `member_type='robot'` and `autonomous_mode=true`
  - [x] Implemented pagination (100 robots per page)
  - [x] Configurable model name via `SetMemberModel()`
- [x] `cache/refresh.go` - refresh single robot, periodic full refresh (every hour)
- [x] Test: load/refresh with real DB
  - [x] Created comprehensive integration tests with real database
  - [x] Tests cover Load, LoadByID, Refresh, ListByTeam, GetByStatus
  - [x] All tests passing with proper cleanup

### ✅ 3.2 Pool Implementation (COMPLETE)

- [x] `pool/pool.go` - worker pool with configurable size (global limit)
  - [x] Default config: 10 workers, 100 queue size
  - [x] Configurable via `pool.NewWithConfig()`
- [x] `pool/queue.go` - priority queue (sorted by: robot priority, trigger type, wait time)
  - [x] Two-level limit: global queue + per-robot queue
  - [x] Priority: Robot Priority × 1000 + Trigger Priority × 100
- [x] `pool/worker.go` - worker goroutines, dispatch to executor
  - [x] Non-blocking quota check with re-enqueue
  - [x] Graceful shutdown support
- [x] Test: submit jobs, verify execution order, verify concurrency limits
  - [x] 15 test cases covering all edge cases
  - [x] All tests passing

### ✅ 3.3 Manager Implementation (COMPLETE)

> **Note:** Manager is the scheduling core, depends on completed Cache and Pool.

- [x] `manager/manager.go` - Manager struct
  - [x] `Start()` - load cache, start pool, start ticker goroutine
  - [x] `Stop()` - graceful shutdown (wait for running, drain queue)
  - [x] `Tick()` - main loop:
    1. Get all cached robots
    2. For each robot with clock trigger enabled
    3. Check if should execute (times/interval/daemon modes)
    4. Submit to pool
  - [x] `TriggerManual()` - manual trigger for testing/API
  - [x] Clock modes: times, interval, daemon
  - [x] Day matching for times mode
  - [x] Timezone handling
  - [x] Skip paused/error/maintenance robots
- [x] Test: manager start/stop, tick cycle, manual trigger, clock modes, goroutine leak

### ✅ 3.4 Trigger Implementation (COMPLETE)

- [x] `trigger/trigger.go` - validation and helper functions
  - [x] `ValidateIntervention()` - validate human intervention requests
  - [x] `ValidateEvent()` - validate event trigger requests
  - [x] `BuildEventInput()` - build TriggerInput from event request
  - [x] `GetActionCategory()` / `GetActionDescription()` - action helpers
- [x] `trigger/clock.go` - ClockMatcher for clock trigger matching
  - [x] `times` mode: match specific times (09:00, 14:00)
  - [x] `interval` mode: run every X duration (30m, 1h)
  - [x] `daemon` mode: restart immediately after completion
  - [x] Timezone handling
  - [x] Day-of-week filtering
- [x] `trigger/control.go` - ExecutionController for pause/resume/stop
  - [x] Track/Untrack executions
  - [x] Pause/Resume execution
  - [x] Stop execution (cancel context)
  - [x] WaitIfPaused() for executor integration
- [x] `manager/manager.go` - integrated trigger handling
  - [x] `Intervene()` - human intervention handler
  - [x] `HandleEvent()` - event trigger handler
  - [x] `PauseExecution()` / `ResumeExecution()` / `StopExecution()`
  - [x] `ListExecutions()` / `ListExecutionsByMember()`
- [x] Tests: `trigger/trigger_test.go`, `trigger/clock_test.go`, `trigger/control_test.go`
  - [x] Validation tests for intervention and event requests
  - [x] Clock matching tests for all modes
  - [x] ExecutionController lifecycle tests
  - [x] Manager integration tests for Intervene/HandleEvent

### ✅ 3.5 Execution Storage (COMPLETE)

- [x] ExecutionStore - execution record persistence
  - [x] Execution data stored in `__yao.agent_execution` table
  - [x] All phase outputs (Inspiration, Goals, Tasks, Results, Delivery, Learning)
  - [x] Status and phase tracking
  - [x] Logging via `kun/log` package
  - [x] Localization support (en-US, zh-CN)
- [x] Test: execution storage, status tracking
  - [x] `store/execution_test.go` - execution store tests
  - [x] All tests passing with real database

### ✅ 3.6 Executor Architecture (COMPLETE)

Pluggable executor architecture with multiple execution modes:

```
executor/
├── types/
│   ├── types.go      # Executor interface, Config types
│   └── helpers.go    # Shared helper functions
├── standard/
│   ├── executor.go   # Real Agent execution (production)
│   ├── agent.go      # AgentCaller for LLM calls
│   ├── input.go      # InputFormatter for prompts
│   ├── inspiration.go # P0: Inspiration phase
│   ├── goals.go      # P1: Goals phase
│   ├── tasks.go      # P2: Tasks phase
│   ├── run.go        # P3: Run phase
│   ├── delivery.go   # P4: Delivery phase
│   └── learning.go   # P5: Learning phase
├── dryrun/
│   └── executor.go   # Simulated execution (testing/demo)
├── sandbox/
│   └── executor.go   # Container-isolated (NOT IMPLEMENTED)
└── executor.go       # Factory functions
```

**Execution Modes:**

| Mode     | Use Case                         | Status             |
| -------- | -------------------------------- | ------------------ |
| Standard | Production with real Agent calls | ✅ Implemented     |
| DryRun   | Tests, demos, scheduling tests   | ✅ Implemented     |
| Sandbox  | Container-isolated execution     | ⬜ Not Implemented |

> **⚠️ Sandbox Mode:** Requires container-level isolation (Docker/gVisor/Firecracker)
> for true security. Current placeholder behaves like DryRun. Future feature.

- [x] `executor/types/types.go` - `Executor` interface, `PhaseExecutor` interface
- [x] `executor/types/helpers.go` - `BuildTriggerInput()` shared helper
- [x] `executor/executor.go` - Factory functions (`New`, `NewDryRun`, `NewWithMode`)
- [x] `executor/standard/executor.go` - Real execution with Job integration
- [x] `executor/standard/phases.go` - Phase implementations (P0-P5)
- [x] `executor/dryrun/executor.go` - Simulated execution with callbacks
- [x] `executor/sandbox/executor.go` - Placeholder (NOT IMPLEMENTED)
- [x] Manager integration - accepts `Executor` interface via config
- [x] Tests use DryRun mode for scheduling/concurrency tests

### 3.7 Integration Test (End-to-End Scheduling) ✅

- [x] Create test robot in `__yao.member` with clock config
- [x] Start manager
- [x] Wait for clock trigger
- [x] Verify:
  - [x] Robot loaded to cache
  - [x] Clock trigger matched
  - [x] Job submitted to pool
  - [x] Worker picked up job
  - [x] Executor stub called
  - [x] Job execution recorded
  - [x] Logs written
- [x] Test human intervention trigger
- [x] Test event trigger
- [x] Test concurrent executions (multiple robots)
- [x] Test quota enforcement (per-robot limit)
- [x] Test pause/resume/stop

**Test Files Created:**

- `manager/integration_test.go` - Core scheduling flow (Cache→Pool→Executor)
- `manager/integration_clock_test.go` - Clock trigger modes (times/interval/daemon)
- `manager/integration_human_test.go` - Human intervention trigger tests
- `manager/integration_event_test.go` - Event trigger tests
- `manager/integration_concurrent_test.go` - Concurrent execution & quota tests
- `manager/integration_control_test.go` - Pause/Resume/Stop tests

**Test Coverage:**

- 27 top-level test functions
- 80+ sub-tests covering all verification points
- 3x run stability verified

---

## Phase 4: Agent Call Infrastructure ✅

**Goal:** Implement unified Agent/Assistant calling mechanism. This is the foundation for all phase implementations (P0-P5).

**Architecture Note:**

- **Prompt construction is handled by Assistant layer** (`prompts.yml` in each assistant)
- **Executor only prepares input data** (ClockContext, InspirationReport, etc.) and calls Assistant
- **Assistant framework handles** prompt rendering, LLM API calls, streaming

**Implemented:**

1. A unified way to call assistants with streaming support
2. Input data formatting for each phase
3. Response parsing (markdown and structured data via `gou/text`)
4. Multi-turn conversation support

### 4.1 Agent Caller Implementation ✅

- [x] `executor/agent.go` - `AgentCaller` struct with `SkipOutput`, `SkipHistory`, `SkipSearch`, `ChatID`
- [x] `executor/agent.go` - `Call(ctx, assistantID, messages)` - basic call with full response
- [x] `executor/agent.go` - `CallWithMessages(ctx, assistantID, userContent)` - convenience method
- [x] `executor/agent.go` - `CallWithSystemAndUser(ctx, assistantID, systemContent, userContent)`
- [x] `executor/agent.go` - handle assistant not found error
- [x] `executor/agent.go` - handle LLM API errors gracefully
- [x] `executor/agent.go` - `CallResult.GetJSON()` / `GetJSONArray()` - parse JSON response using `gou/text`
- [x] `executor/agent.go` - `Conversation` struct for multi-turn dialogues
- [x] `executor/agent.go` - `Conversation.Turn()`, `RunUntil()`, `Reset()`, `WithSystemPrompt()`
- [x] `executor/agent.go` - Use `agentcontext.Noop()` logger to suppress debug output

### 4.2 Input Formatters ✅

- [x] `executor/input.go` - `FormatClockContext(clockCtx, robot)` - format clock context as message content
- [x] `executor/input.go` - `FormatInspirationReport(report)` - format P0 output for P1 input
- [x] `executor/input.go` - `FormatTriggerInput(input)` - format Human/Event trigger for P1 input
- [x] `executor/input.go` - `FormatGoals(goals, robot)` - format P1 output for P2 input
- [x] `executor/input.go` - `FormatTasks(tasks)` - format P2 output for P3 input
- [x] `executor/input.go` - `FormatTaskResults(results)` - format P3 output for P4/P5 input
- [x] `executor/input.go` - `FormatExecutionSummary(exec)` - format full execution for P5 input
- [x] `executor/input.go` - `BuildMessages()`, `BuildMessagesWithSystem()` - helper methods

### 4.3 Test Assistants ✅

- [x] `yao-dev-app/assistants/tests/robot-single/` - Single-turn test assistant
- [x] `yao-dev-app/assistants/tests/robot-conversation/` - Multi-turn conversation test assistant

### 4.4 Tests ✅

- [x] `executor/agent_test.go` - 22 test cases for AgentCaller and Conversation
- [x] `executor/input_test.go` - 20 test cases for InputFormatter
- [x] Verify: assistant can be called and returns response
- [x] Verify: multi-turn conversation maintains state
- [x] Verify: input data is well-formatted for assistant prompts
- [x] Verify: JSON/YAML extraction from LLM output works correctly

---

## Phase 5: Test Scenario & Assistants Setup ✅

**Goal:** Create realistic test scenarios with all required assistants.

**Architecture:**

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                      6 Generic Phase Agents (P0-P5)                          │
├─────────────────────────────────────────────────────────────────────────────┤
│  inspiration  │  goals  │  tasks  │  validation  │  delivery  │  learning   │
│     (P0)      │  (P1)   │  (P2)   │     (P3)     │    (P4)    │    (P5)     │
└───────────────┴─────────┴─────────┴──────────────┴────────────┴─────────────┘
                                    ↓ P2 assigns tasks to
┌─────────────────────────────────────────────────────────────────────────────┐
│                      Expert Agents (Task Executors)                          │
├─────────────────────────────────────────────────────────────────────────────┤
│  text-writer   │  web-reader  │  data-analyst  │  summarizer  │  ...        │
│  (Generate)    │  (Fetch URL) │  (Analyze)     │  (Summarize) │             │
└───────────────┴──────────────┴────────────────┴──────────────┴─────────────┘
```

**Test Strategy:**

- Phase Agents (P0-P5) are **generic** and reusable across all robot types
- Expert Agents are **specialized** for specific tasks (text, web, data, etc.)
- Each P0-P5 test uses **different expert combinations** to cover real scenarios
- Tests use `interval: 1s` or `TriggerManual()` for easy triggering (no time dependency)

### 5.1 Directory Structure

```
yao-dev-app/assistants/
├── robot/                    # Generic Phase Agents
│   ├── inspiration/          # P0: Analyze clock context, generate insights
│   │   ├── package.yao
│   │   └── prompts.yml
│   ├── goals/                # P1: Generate prioritized goals
│   │   ├── package.yao
│   │   └── prompts.yml
│   ├── tasks/                # P2: Split goals into executable tasks
│   │   ├── package.yao
│   │   └── prompts.yml
│   ├── validation/           # P3: Validate task results
│   │   ├── package.yao
│   │   └── prompts.yml
│   ├── delivery/             # P4: Format and deliver results
│   │   ├── package.yao
│   │   └── prompts.yml
│   └── learning/             # P5: Summarize execution, extract insights
│       ├── package.yao
│       └── prompts.yml
│
└── experts/                  # Expert Agents (Task Executors)
    ├── text-writer/          # Generate text content (reports, emails, summaries)
    │   ├── package.yao
    │   └── prompts.yml
    ├── web-reader/           # Fetch and parse web page content
    │   ├── package.yao
    │   └── prompts.yml
    ├── data-analyst/         # Analyze data, generate insights
    │   ├── package.yao
    │   └── prompts.yml
    └── summarizer/           # Summarize long text into key points
        ├── package.yao
        └── prompts.yml
```

### 5.2 Generic Phase Agents

#### 5.2.1 Inspiration Agent (P0)

- [x] `robot/inspiration/package.yao` - config with model, temperature
- [x] `robot/inspiration/prompts.yml` - system prompt:
  - Input: Clock context (time, day, markers), robot identity
  - Output: Markdown report with Summary, Highlights, Opportunities, Risks
  - Style: Analytical, context-aware

#### 5.2.2 Goals Agent (P1)

- [x] `robot/goals/package.yao` - config
- [x] `robot/goals/prompts.yml` - system prompt:
  - Input: Inspiration report OR trigger input (human/event)
  - Output: Prioritized goals in markdown (High/Normal/Low)
  - Style: Strategic, actionable

#### 5.2.3 Tasks Agent (P2)

- [x] `robot/tasks/package.yao` - config
- [x] `robot/tasks/prompts.yml` - system prompt:
  - Input: Goals, available expert agents list
  - Output: Structured task list (JSON) with executor assignments
  - Style: Detailed, executable

#### 5.2.4 Validation Agent (P3)

- [x] `robot/validation/package.yao` - config
- [x] `robot/validation/prompts.yml` - system prompt:
  - Input: Task result, expected outcome
  - Output: Validation result (pass/fail, issues, suggestions)
  - Style: Critical, thorough

#### 5.2.5 Delivery Agent (P4)

- [x] `robot/delivery/package.yao` - config
- [x] `robot/delivery/prompts.yml` - system prompt:
  - Input: Full execution context (P0-P3 results)
  - Output: Formatted delivery content
  - Style: Clear, professional

#### 5.2.6 Learning Agent (P5)

- [x] `robot/learning/package.yao` - config
- [x] `robot/learning/prompts.yml` - system prompt:
  - Input: Full execution summary
  - Output: Insights, patterns, improvement suggestions
  - Style: Reflective, insightful

### 5.3 Expert Agents (Task Executors)

#### 5.3.1 Text Writer

- [x] `experts/text-writer/package.yao` - config
- [x] `experts/text-writer/prompts.yml` - system prompt:
  - Input: Topic, key points, style (formal/casual), length
  - Output: Generated text content
  - Use cases: Weekly reports, email drafts, summaries

#### 5.3.2 Web Reader

- [x] `experts/web-reader/package.yao` - config with hooks
- [x] `experts/web-reader/prompts.yml` - system prompt:
  - Input: URL or topic to search
  - Output: Extracted content, key information
  - Use cases: News fetching, competitor monitoring, research
- [x] `experts/web-reader/src/fetch.ts` - HTTP fetching utilities
- [x] `experts/web-reader/src/fetch_test.ts` - 19 test cases (100% pass)
- [x] `experts/web-reader/src/index.ts` - Create/Next hooks

#### 5.3.3 Data Analyst

- [x] `experts/data-analyst/package.yao` - config
- [x] `experts/data-analyst/prompts.yml` - system prompt:
  - Input: Data description, analysis goal
  - Output: Analysis report, trends, insights
  - Use cases: Sales analysis, performance review

#### 5.3.4 Summarizer

- [x] `experts/summarizer/package.yao` - config
- [x] `experts/summarizer/prompts.yml` - system prompt:
  - Input: Long text content
  - Output: Concise summary with key points
  - Use cases: Document summarization, meeting notes

### 5.4 Test Scenarios

Each phase test uses different expert combinations:

| Test | Phase | Trigger          | Expert Agents Used       | Verification                  |
| ---- | ----- | ---------------- | ------------------------ | ----------------------------- |
| T1   | P0    | Clock (interval) | -                        | Clock → Inspiration report    |
| T2   | P1    | Clock            | -                        | Inspiration → Goals           |
| T3   | P1    | Human            | -                        | User input → Goals            |
| T4   | P2    | Clock            | text-writer, web-reader  | Goals → Tasks with executors  |
| T5   | P3    | Clock            | text-writer              | Task exec → Result validation |
| T6   | P3    | Human            | summarizer               | Task exec → Result validation |
| T7   | P4    | Clock            | -                        | Results → Delivery format     |
| T8   | P5    | Clock            | -                        | Full execution → Insights     |
| T9   | E2E   | Clock            | text-writer, summarizer  | Full P0→P5 flow               |
| T10  | E2E   | Human            | web-reader, data-analyst | Full P1→P5 flow               |

### 5.5 Verification

- [x] All 6 Phase Agents load correctly (`robot.inspiration`, `robot.goals`, etc.)
- [x] All 4 Expert Agents load correctly (`experts.text-writer`, `experts.web-reader`, etc.)
- [x] Web Reader `fetch.ts` utilities tested (19 tests, 100% pass)

---

## Phase 6: P0 Inspiration Implementation ✅

**Goal:** Implement P0 (Inspiration Agent). Clock trigger → P0 → stub P1-P5.

**Depends on:** Phase 4 (Agent Call Infrastructure), Phase 5 (Assistants Setup)

**Status:** COMPLETED

### 6.1 P0 Implementation

- [x] `executor/inspiration.go` - `RunInspiration(ctx, exec, data)` - real implementation
- [x] `executor/inspiration.go` - build prompt using `InputFormatter.FormatClockContext()`
- [x] `executor/inspiration.go` - call Inspiration Agent using `AgentCaller`
- [x] `executor/inspiration.go` - parse response to `InspirationReport` (markdown content)
- [x] `types/robot.go` - added `GetRobot()`/`SetRobot()` methods for Execution
- [x] `executor/executor.go` - set robot reference on execution creation

### 6.2 Tests

- [x] `executor/inspiration_test.go` - P0 with real LLM call (8 test cases)
- [x] Test: clock context correctly formatted in prompt
- [x] Test: robot identity included in prompt
- [x] Test: markdown report generated with expected sections
- [x] Test: handles LLM errors gracefully (robot nil, agent not found)
- [x] Test: uses clock from trigger input or creates new one
- [x] `InputFormatter.FormatClockContext()` unit tests (4 test cases)

### 6.3 Notes

- `executor_test.go` temporarily moved to `.bak` - will restore when all phases implemented
- P0 uses `robot.inspiration` test agent from `yao-dev-app/assistants/robot/inspiration/`

---

## Phase 7: P1 Goals Implementation ✅

**Goal:** Implement P1 (Goal Generation Agent). P0 → P1 → stub P2-P5.

**Depends on:** Phase 6 (P0 Inspiration)

**Status:** COMPLETED

### 7.1 P1 Implementation

- [x] `executor/goals.go` - `RunGoals(ctx, exec, data)` - real implementation
- [x] `executor/goals.go` - build prompt with inspiration report (Clock trigger)
- [x] `executor/goals.go` - build prompt with trigger input (Human/Event trigger)
- [x] `executor/goals.go` - call Goals Agent using `AgentCaller`
- [x] `executor/goals.go` - parse response to `Goals` struct (JSON with content + delivery)
- [x] `executor/goals.go` - handle Human/Event trigger (skip P0, use input directly)
- [x] `executor/goals.go` - include robot identity in prompt
- [x] `executor/goals.go` - include available resources in prompt
- [x] `executor/goals.go` - `ParseDelivery()` - parse delivery target from JSON
- [x] `executor/goals.go` - `IsValidDeliveryType()` - validate delivery types

### 7.2 Tests

- [x] `executor/goals_test.go` - P1 with real LLM call (14 test cases)
- [x] Test: inspiration report in prompt (Clock trigger)
- [x] Test: user input in prompt (Human trigger)
- [x] Test: event data in prompt (Event trigger)
- [x] Test: goals markdown generated with priorities
- [x] Test: delivery parsing from agent response
- [x] Test: error handling (robot nil, agent not found, empty input)
- [x] Test: fallback behavior (no inspiration → clock context)
- [x] `ParseDelivery()` unit tests (8 test cases covering edge cases)
- [x] `IsValidDeliveryType()` unit tests

### 7.3 Notes

- P1 uses `robot.goals` test agent from `yao-dev-app/assistants/robot/goals/`
- Goals Agent returns JSON: `{ "content": "...", "delivery": {...} }`
- Delivery is optional; if not present or invalid, `Goals.Delivery` is nil
- Available resources (agents, MCP, KB, DB) are passed to agent for achievable goal generation

---

## Phase 8: P2 Tasks Implementation ✅

**Goal:** Implement P2 (Task Planning Agent). P1 → P2 → stub P3-P5.

**Depends on:** Phase 7 (P1 Goals)

**Status:** COMPLETED

### 8.1 Validation Agent Setup (Prerequisite for P3) ✅

> **Note:** Validation Agent was already set up in Phase 5.

- [x] `robot/validation/package.yao` - Validation Agent config (DeepSeek V3, temperature 0.2)
- [x] `robot/validation/prompts.yml` - validation prompts
  - Input: Task result, expected outcome, validation rules
  - Output: Validation result (pass/fail, score, issues, suggestions)

### 8.2 P2 Implementation ✅

- [x] `executor/tasks.go` - `RunTasks(ctx, exec, data)` - real implementation
- [x] `executor/tasks.go` - build prompt with goals (using `FormatGoals`)
- [x] `executor/tasks.go` - include available tools/agents in prompt
- [x] `executor/tasks.go` - include delivery target in prompt (for task output format)
- [x] `executor/tasks.go` - call Tasks Agent using `AgentCaller`
- [x] `executor/tasks.go` - parse response to `[]Task` (structured JSON)
- [x] `executor/tasks.go` - validate task structure (executor type, ID, messages)
- [x] `executor/tasks.go` - `ParseTasks()`, `ParseTask()`, `ParseMessages()` helpers
- [x] `executor/tasks.go` - `SortTasksByOrder()` - ensure correct execution sequence
- [x] `executor/tasks.go` - `ValidateExecutorExists()` - optional executor existence check
- [x] `executor/tasks.go` - `ValidateTasksWithResources()` - validation with warnings
- [x] `executor/input.go` - `FormatGoals()` updated to include Delivery Target

### 8.3 Tests ✅

- [x] `executor/tasks_test.go` - P2 with real LLM call (7 integration tests)
- [x] Test: goals included in prompt
- [x] Test: available tools listed in prompt
- [x] Test: delivery target included in prompt
- [x] Test: structured tasks generated
- [x] Test: each task has valid executor type and ID
- [x] Test: each task has expected output and validation rules
- [x] `ParseTasks` unit tests (5 tests)
- [x] `ValidateTasks` unit tests (5 tests)
- [x] `SortTasksByOrder` unit tests (4 tests)
- [x] `ValidateExecutorExists` unit tests (7 tests)
- [x] `ValidateTasksWithResources` unit tests (3 tests)
- [x] `ParseExecutorType` unit tests (5 tests)
- [x] `IsValidExecutorType` unit tests (2 tests)
- [x] `FormatGoals` with delivery target tests (4 tests)

### 8.4 Notes

- Tasks Agent returns JSON: `{ "tasks": [...] }`
- Each task includes: id, executor_type, executor_id, messages, expected_output, validation_rules, order
- Tasks are sorted by `order` field after parsing
- Executor existence is optionally validated (warnings only, doesn't block)
- Delivery target from P1 is passed to P2 so tasks can produce appropriate output format

---

## Phase 9: P3 Run Implementation ✅

**Goal:** Implement P3 (Task Execution + Validation). P2 → P3 → stub P4-P5.

**Depends on:** Phase 8 (P2 Tasks + Validation Agent)

**Status:** Complete

### 9.1 Implementation ✅

- [x] `executor/run.go` - `RunExecution(ctx, exec, data)` - real implementation
  - [x] `RunConfig` - configuration (ContinueOnFailure, ValidationThreshold, MaxTurnsPerTask)
  - [x] Sequential task execution with progress tracking
  - [x] Task status updates (Running → Completed/Failed/Skipped)
  - [x] `ContinueOnFailure` option for graceful failure handling
  - [x] Previous task results passed as context to subsequent tasks
- [x] `executor/runner.go` - `Runner` struct for task execution
  - [x] `ExecuteWithRetry()` - multi-turn conversation flow for assistant tasks
  - [x] `executeNonAssistantTask()` - single-call execution for MCP/Process
  - [x] `executeAssistantWithMultiTurn()` - AI assistant with conversation support
  - [x] `ExecuteMCPTask()` - MCP tool execution (format: `clientID.toolName`)
  - [x] `ExecuteProcessTask()` - Yao process execution
  - [x] `BuildTaskContext()` - context with previous results
  - [x] `BuildAssistantMessages()` - build messages for assistant
  - [x] `FormatPreviousResultsAsContext()` - format previous results as context
  - [x] `extractOutput()` - extract output from CallResult
  - [x] `generateDefaultReply()` - fallback reply generation
- [x] `executor/validator.go` - Two-layer validation system
  - [x] Layer 1: Rule-based validation using `yao/assert`
  - [x] Layer 2: Semantic validation using Validation Agent
  - [x] `ValidateWithContext()` - validation with multi-turn support
  - [x] `isComplete()` - determine if expected result is obtained
  - [x] `checkNeedReply()` - determine if conversation should continue
  - [x] `generateFeedbackReply()` - generate validation feedback for next turn
  - [x] `detectNeedMoreInfo()` - detect if assistant needs clarification
  - [x] `convertStringRule()` - natural language rules to assertions
  - [x] `parseRules()` - JSON and string rule parsing
  - [x] `mergeResults()` - combine rule and semantic results

### 9.2 Assert Package ✅

Created new `yao/assert` package for universal assertion/validation:

- [x] `assert/types.go` - `Assertion`, `Result`, `AssertionOptions` types
- [x] `assert/asserter.go` - `Asserter` with 8 assertion types:
  - [x] `equals` - exact match
  - [x] `contains` - substring check
  - [x] `not_contains` - negative substring check
  - [x] `json_path` - JSON path extraction and comparison
  - [x] `regex` - regex pattern matching
  - [x] `type` - type checking (with optional path)
  - [x] `script` - custom script validation
  - [x] `agent` - AI agent validation
- [x] `assert/helpers.go` - `ValidateOutput()`, `ExtractPath()`, `ToString()`, `GetType()`
- [x] `assert/asserter_test.go` - 98.7% test coverage

### 9.3 Tests

**Completed:**
- [x] `assert/asserter_test.go` - 40+ test cases (98.7% coverage)
- [x] `types/robot_test.go` - Task structure tests with validation rules
- [x] `tasks_test.go` - ParseTasks with validation rules format
- [x] Validation rules format aligned with `prompts.yml` guidelines

**Completed Tests:**
- [x] `executor/standard/run_test.go` - P3 RunExecution tests ✅
  - [x] Test: tasks executed in order (`TestRunExecutionBasic`)
  - [x] Test: task status updates (`TestRunExecutionTaskStatus`)
  - [x] Test: remaining tasks marked as skipped on failure
  - [x] Test: error handling (robot nil, no tasks, non-existent assistant)
  - [x] Test: rule-based and semantic validation (`TestRunExecutionValidation`)
  - [x] Test: previous results passed as context to subsequent tasks
- [x] `executor/standard/runner_test.go` - Runner tests ✅
  - [x] Test: ExecuteWithRetry with multi-turn conversation flow
  - [x] Test: max turns limit enforcement
  - [x] Test: BuildTaskContext with previous results
  - [x] Test: FormatPreviousResultsAsContext formatting
  - [x] Test: BuildAssistantMessages with task content
  - [x] Test: FormatMessagesAsText (string, multipart, map)
  - [x] Test: MCP and Process tasks (skipped - requires runtime)
- [x] `executor/standard/validator_test.go` - Validator tests ✅
  - [x] Test: ValidateWithContext with multi-turn state
  - [x] Test: isComplete determination logic
  - [x] Test: checkNeedReply scenarios
  - [x] Test: convertStringRule for natural language rules
  - [x] Test: parseRules for JSON assertions (equals, regex, json_path, type)
  - [x] Test: validateSemantic with Validation Agent
  - [x] Test: mergeResults logic (rule + semantic)

**Completed:**
- [x] Test: ContinueOnFailure option (run_test.go) ✅
  - [x] `stops_on_first_failure_when_ContinueOnFailure_is_false`
  - [x] `continues_execution_when_ContinueOnFailure_is_true`
  - [x] `multiple_failures_with_ContinueOnFailure`

---

## Phase 10: P4 Delivery Implementation

**Goal:** Implement P4 (Delivery). P3 → P4 → stub P5.

**Depends on:** Phase 9 (P3 Run)

### 10.1 Execution Persistence (Prerequisite) ✅

> **Background:** Each Robot execution (P0-P5) needs persistent storage for UI history queries.

- [x] `yao/models/agent/execution.mod.yao` - Execution record model (`agent_execution` table)
  - [x] id, execution_id (unique)
  - [x] member_id (globally unique), team_id
  - [x] trigger_type (enum: clock, human, event)
  - [x] **Status tracking** (synced with runtime Execution):
    - [x] status (enum: pending, running, completed, failed, cancelled)
    - [x] phase (enum: inspiration, goals, tasks, run, delivery, learning)
    - [x] current (JSON) - current executing state (task_index, progress)
    - [x] error - error message if failed
  - [x] input (JSON) - trigger input
  - [x] **Phase outputs** (P0-P5):
    - [x] inspiration (JSON) - P0 output
    - [x] goals (JSON) - P1 output
    - [x] tasks (JSON) - P2 output
    - [x] results (JSON) - P3 output
    - [x] delivery (JSON) - P4 output
    - [x] learning (JSON) - P5 output
  - [x] **Timestamps**: start_time, end_time, created_at, updated_at
  - [x] Relations: member (hasOne __yao.member)
- [x] `agent/robot/store/execution.go` - Execution record storage
  - [x] `Save(ctx, record)` - create or update execution record
  - [x] `Get(ctx, execID)` - get execution by ID
  - [x] `List(ctx, opts)` - query execution history with filters
  - [x] `UpdatePhase(ctx, execID, phase, data)` - update current phase and data
  - [x] `UpdateStatus(ctx, execID, status, error)` - update execution status
  - [x] `UpdateCurrent(ctx, execID, current)` - update current executing state
  - [x] `Delete(ctx, execID)` - delete execution record
  - [x] `FromExecution(exec, robotID)` - convert runtime Execution to record
  - [x] `ToExecution()` - convert record to runtime Execution
- [x] Tests: `agent/robot/store/execution_test.go` (9 test groups, all passing)
- [x] Integrate into Executor - call `UpdatePhase()` after each phase completes
  - [x] Added `SkipPersistence` config option to `executor/types/Config`
  - [x] Added `ExecutionStore` to `executor/standard/Executor`
  - [x] Save execution record at start of `Execute()`
  - [x] Call `UpdatePhase()` after each phase completes in `runPhase()`
  - [x] Call `UpdateStatus()` on status changes (running, completed, failed)

### 10.2 Messenger Attachment Support ✅

> **Conclusion:** All email providers now support attachments.

**Implementation Status:**

| Provider | Attachment Support | Implementation |
|----------|-------------------|----------------|
| Twilio/SendGrid | ✅ Supported | `buildAttachments()` - base64 encoded |
| Mailgun | ✅ Supported | `sendEmailWithAttachments()` - multipart/form-data |
| SMTP (mailer) | ✅ Supported | `buildMessageWithAttachments()` - MIME multipart/mixed |

**Features Supported:**
- Regular attachments (Content-Disposition: attachment)
- Inline attachments (Content-Disposition: inline) with Content-ID for HTML embedding
- Multiple attachments per email
- Automatic content type detection
- Base64 encoding for SMTP (RFC 2045 compliant, 76-char line wrapping)

**Tests Added:**
- `messenger/providers/mailgun/mailgun_test.go`:
  - `TestSend_EmailWithAttachments_MockServer`
  - `TestSend_EmailWithInlineAttachment_MockServer`
  - `TestSend_EmailWithAttachments_RealAPI`
- `messenger/providers/mailer/mailer_test.go`:
  - `TestBuildMessage_WithAttachments` (single, multiple, inline, no attachments)
  - `TestSend_EmailWithAttachments_RealAPI`

```go
// messenger/types/types.go
type Attachment struct {
    Filename    string `json:"filename"`
    ContentType string `json:"content_type"`
    Content     []byte `json:"content"`
    Inline      bool   `json:"inline,omitempty"`
    CID         string `json:"cid,omitempty"`
}
```

Supported channels:
- [x] Email - Full attachment support
- [x] SMS - No attachment (text only)
- [x] WhatsApp - TBD

### 10.3 Type Updates (Prerequisite) ✅

- [x] Update `types/enums.go` - Update `DeliveryType` enum
  - [x] Remove `DeliveryFile`
  - [x] Add `DeliveryProcess`
- [x] Update `types/robot.go` - Delivery types for new architecture
  - [x] `DeliveryResult` - update to new structure (RequestID, Content, Results[])
  - [x] Add `DeliveryContent` struct
  - [x] Add `DeliveryAttachment` struct
  - [x] Add `DeliveryRequest` struct
  - [x] Add `DeliveryContext` struct
  - [x] Add `DeliveryPreferences` struct (with Email, Webhook, Process)
  - [x] Add `EmailPreference`, `EmailTarget` structs
  - [x] Add `WebhookPreference`, `WebhookTarget` structs
  - [x] Add `ProcessPreference`, `ProcessTarget` structs
  - [x] Add `ChannelResult` struct (with Target field)
- [x] Update `types/enums_test.go` - Update DeliveryType tests
- [x] Update `types/robot_test.go` - Update delivery result tests

### 10.4 Delivery Agent Setup

- [x] `robot/delivery/package.yao` - Delivery Agent config
- [x] `robot/delivery/prompts.yml` - delivery prompts
  - [x] Input: Full execution context (P0-P3 results)
  - [x] Output: DeliveryContent (Summary, Body, Attachments) - **only content, no channels**
  - [x] Agent focuses on content generation, NOT channel selection

### 10.5 Delivery Content Structure

```go
// DeliveryRequest - pushed to Delivery Center
// No Channels - Delivery Center decides based on preferences
type DeliveryRequest struct {
    Content *DeliveryContent `json:"content"` // Agent-generated content
    Context *DeliveryContext `json:"context"` // Tracking info
}

// DeliveryContent - Content generated by Delivery Agent (only content)
type DeliveryContent struct {
    Summary     string               `json:"summary"`               // Brief 1-2 sentence summary
    Body        string               `json:"body"`                  // Full markdown report
    Attachments []DeliveryAttachment `json:"attachments,omitempty"` // Output artifacts from P3
}

// DeliveryAttachment - Task output attachment with metadata
type DeliveryAttachment struct {
    Title       string `json:"title"`                 // Human-readable title
    Description string `json:"description,omitempty"` // What this artifact is
    TaskID      string `json:"task_id,omitempty"`     // Which task produced this
    File        string `json:"file"`                  // Wrapper: __<uploader>://<fileID>
}

// DeliveryContext - tracking info
type DeliveryContext struct {
    MemberID    string      `json:"member_id"`    // Robot member ID (globally unique)
    ExecutionID string      `json:"execution_id"`
    TriggerType TriggerType `json:"trigger_type"` // clock | human | event
    TeamID      string      `json:"team_id"`
}
```

**Key Design:**
- **Agent only generates content** (Summary, Body, Attachments)
- **Delivery Center decides channels** based on Robot/User preferences
- If webhook configured, every execution pushes automatically

**File Wrapper:**
- Format: `__<uploader>://<fileID>`
- Parse: `attachment.Parse(value)` → `(uploader, fileID, isWrapper)`
- Read: `attachment.Base64(ctx, value)` → base64 content

**Delivery Channels (each supports multiple targets):**
| Channel | Description | Multiple Targets |
|---------|-------------|------------------|
| `email` | Send via yao/messenger | ✅ Multiple recipients |
| `webhook` | POST to external URL | ✅ Multiple URLs |
| `process` | Yao Process call | ✅ Multiple processes |
| `notify` | In-app notification | Future (auto by subscriptions) |

### 10.6 Implementation

**P4 Entry (executor/delivery.go):**
- [x] `RunDelivery(ctx, exec, data)` - P4 entry point
  - [x] Call Delivery Agent to generate content (only content, no channels)
  - [x] Build DeliveryRequest (Content + Context)
  - [x] Push to Delivery Center
  - [x] Store DeliveryResult in exec.Delivery

**Delivery Center (executor/delivery_center.go):**
- [x] `DeliveryCenter.Deliver(ctx, request)` - main entry
  - [x] Read Robot/User delivery preferences
  - [x] Iterate through all enabled targets for each channel
  - [x] Aggregate ChannelResults into DeliveryResult

**Channel Handlers (each supports multiple targets):**
- [x] `sendEmail()` - uses yao/messenger
  - [x] Convert DeliveryAttachment to messenger.Attachment
  - [x] Support multiple EmailTarget
  - [x] Support custom subject_template per target
  - [x] Use `Robot.RobotEmail` as From address (if configured)
  - [x] Use global `DefaultEmailChannel()` for messenger channel selection
- [x] `postWebhook()` - POST JSON
  - [x] POST DeliveryContent as JSON payload
  - [x] Support multiple WebhookTarget
  - [x] Support custom headers per target
- [x] `callProcess()` - Yao Process call
  - [x] DeliveryContent as first arg
  - [x] Support multiple ProcessTarget
  - [x] Support additional args per target

### 10.7 Tests

- [x] `executor/delivery_test.go` - P4 delivery
- [x] Test: Delivery Agent generates content (only content)
- [x] Test: DeliveryCenter reads preferences
- [x] Test: Multiple email targets (TestDeliveryCenterEmail)
- [x] Test: Multiple webhook targets
- [x] Test: Multiple process targets (TestDeliveryCenterProcess)
- [x] Test: Mixed channels (email + webhook + process) (TestDeliveryCenterAllChannels)
- [x] Test: sendEmail with attachments (TestDeliveryCenterEmail)
- [x] Test: postWebhook with custom headers
- [x] Test: callProcess with args (TestDeliveryCenterProcess)
- [x] Test: Partial success (some targets fail)
- [x] Test: DeliveryResult aggregation

---

## Phase 11: API & Integration (MVP)

**Goal:** Complete Go API and end-to-end tests. Main flow: P0 → P1 → P2 → P3 → P4.

**Depends on:** Phase 10 (P4 Delivery)

> **Note:** Process handlers and JSAPI are optional wrappers, moved to Phase 12.
> Go API is sufficient for MVP integration.

### 11.1 Go API Implementation

- [x] `api/types.go` - API request/response types
- [x] `api/lifecycle.go` - manager lifecycle
  - [x] `Start()` / `Stop()` - manager lifecycle
  - [x] `StartWithConfig(config)` - start with custom config
  - [x] `IsRunning()` - check if system is running
- [x] `api/robot.go` - robot query functions
  - [x] `GetRobot(memberID)` - get robot by member ID
  - [x] `ListRobots(query)` - list robots with filtering
  - [x] `GetRobotStatus(memberID)` - get robot runtime status
- [x] `api/trigger.go` - trigger functions
  - [x] `Trigger(memberID, request)` - main trigger entry point
  - [x] `TriggerManual(memberID, triggerType, data)` - manual trigger for testing
  - [x] `Intervene(memberID, request)` - human intervention
  - [x] `HandleEvent(memberID, request)` - event trigger
- [x] `api/execution.go` - execution query and control
  - [x] `GetExecution(execID)` - get execution by ID
  - [x] `ListExecutions(memberID, query)` - list executions
  - [x] `GetExecutionStatus(execID)` - get execution with runtime status
  - [x] `PauseExecution(execID)` / `ResumeExecution(execID)` / `StopExecution(execID)`
- [x] `api/api.go` - package documentation
- [x] Tests: `api/*_test.go` (black-box tests, 16 test cases)

### 11.2 End-to-End Tests

- [x] Full clock trigger flow (P0 → P1 → P2 → P3 → P4) - `e2e_clock_test.go`
- [x] Human intervention flow (P1 → P2 → P3 → P4) - `e2e_human_test.go`
- [x] Event trigger flow (P1 → P2 → P3 → P4) - `e2e_event_test.go`
- [x] Concurrent execution test - `e2e_concurrent_test.go`
- [x] Pause/Resume/Stop test - `e2e_control_test.go`

---

## Phase 12: OpenAPI Integration

**Goal:** HTTP endpoints for Robot Agent management and triggers.

**Depends on:** Phase 11 (API & Integration), Frontend UI Design

> **Note:** This phase will be planned in detail after frontend UI design is complete.
> The API endpoints will be designed based on actual UI requirements.

### 12.1 Planned Features

- [ ] HTTP endpoints for robot management (CRUD)
- [ ] HTTP endpoints for human intervention triggers
- [ ] Webhook endpoints for external events
- [ ] WebSocket for real-time execution status updates
- [ ] Authentication and authorization integration

### 12.2 Design Dependencies

- Frontend dashboard design (robot list, status, controls)
- Execution history UI design
- Human intervention UI design
- Real-time notification requirements

---

## Phase 13: Advanced Features

**Goal:** P5 Learning, Process/JSAPI wrappers, dedup, plan queue.

> **Note:** These are optional features. Main flow works without them.

### 13.1 Process & JSAPI Wrappers

> **Note:** These are convenience wrappers around Go API for Yao ecosystem integration.

- [ ] `api/process.go` - implement Process handlers
  - [ ] `robot.Start` / `robot.Stop`
  - [ ] `robot.Trigger` / `robot.Intervene` / `robot.HandleEvent`
  - [ ] `robot.Pause` / `robot.Resume` / `robot.Stop`
  - [ ] `robot.Get` / `robot.List`
  - [ ] `robot.GetExecution` / `robot.ListExecutions`
- [ ] `api/jsapi.go` - implement JSAPI for JavaScript runtime
- [ ] Tests for Process and JSAPI

### 13.2 P5 Learning Implementation

> **Background:** P5 Learning is async, runs after P4 Delivery completes.
> User doesn't wait for it. Results stored in private KB for future reference.

#### 13.2.1 Learning Agent Setup

- [ ] `robot/learning/package.yao` - Learning Agent config
- [ ] `robot/learning/prompts.yml` - learning prompts

#### 13.2.2 Store Implementation

- [ ] `store/store.go` - Store interface and struct
- [ ] `store/kb.go` - KB operations (create, save, search)
- [ ] `store/learning.go` - save learning entries to private KB

#### 13.2.3 Implementation

- [ ] `executor/learning.go` - `RunLearning(ctx, exec, data)` - real implementation
- [ ] `executor/learning.go` - extract learnings from execution
- [ ] `executor/learning.go` - call Learning Agent
- [ ] `executor/learning.go` - save to private KB

#### 13.2.4 Tests

- [ ] `executor/learning_test.go` - P5 learning
- [ ] Test: learnings extracted from execution
- [ ] Test: learnings saved to KB
- [ ] Test: KB can be queried for past learnings

### 13.3 Fast Dedup (Time-Window)

> **Note:** Manager has `// TODO: dedup check` comment placeholder. Integrate after implementation.

- [ ] `dedup/dedup.go` - Dedup struct
- [ ] `dedup/fast.go` - fast in-memory time-window dedup
  - [ ] Key: `memberID:triggerType:window`
  - [ ] Check before submit
  - [ ] Mark after submit
- [ ] Integrate into Manager.Tick()
- [ ] Test: dedup check/mark, window expiry

### 13.4 Semantic Dedup

- [ ] `dedup/semantic.go` - call Dedup Agent for goal/task level dedup
- [ ] Dedup Agent setup (`assistants/robot/dedup/`)
- [ ] Test: semantic dedup with real LLM

### 13.5 Plan Queue

- [ ] `plan/plan.go` - plan queue implementation
  - [ ] Store planned tasks/goals
  - [ ] Execute at next cycle or specified time
- [ ] `plan/schedule.go` - schedule for later
- [ ] Test: plan queue operations

> **Note:** Monitoring is provided by Job system (Activity Monitor UI). No separate implementation needed.

---

## Test Assistants Structure

```
yao-dev-app/assistants/robot/
├── inspiration/           # P0: Inspiration Agent
│   ├── package.yao
│   └── prompts.yml
├── goals/                 # P1: Goal Generation Agent
│   ├── package.yao
│   └── prompts.yml
├── tasks/                 # P2: Task Planning Agent
│   ├── package.yao
│   └── prompts.yml
├── validation/            # P3: Validation Agent
│   ├── package.yao
│   └── prompts.yml
├── delivery/              # P4: Delivery Agent
│   ├── package.yao
│   └── prompts.yml
├── learning/              # P5: Learning Agent
│   ├── package.yao
│   └── prompts.yml
└── dedup/                 # Deduplication Agent
    ├── package.yao
    └── prompts.yml
```

---

## Notes

### Test Environment Setup

1. **Environment Variables:** Run `source yao/env.local.sh` before tests
2. **Test Preparation:** Use `testutils.Prepare(t)` to load config, KB, and agents

```go
package robot_test

import (
    "testing"
    "github.com/yaoapp/yao/agent/testutils"
)

func TestExample(t *testing.T) {
    // Load environment config (from YAO_TEST_APPLICATION)
    // This loads: config, connectors, KB, agents, models, etc.
    testutils.Prepare(t)
    defer testutils.Clean(t)

    // Your test code here
}
```

### Test Conventions

1. **Black-box Tests:** All tests in `*_test` package (external package)
2. **Real LLM Calls:** Use `gpt-4o` or `deepseek` connectors for agent tests
3. **Incremental:** Each phase builds on previous, all tests must pass before next phase
4. **No Skip:** Do NOT use `t.Skip()` except for `testing.Short()` (CI mode)
5. **Must Assert:** Every test MUST have result validation assertions

```go
func TestWithLLM(t *testing.T) {
    // Only allowed Skip: testing.Short() for CI
    if testing.Short() {
        t.Skip("Skipping integration test")
    }

    testutils.Prepare(t)
    defer testutils.Clean(t)

    // Your test code...
    result, err := SomeFunction()

    // MUST have assertions - no empty tests!
    assert.NoError(t, err)
    assert.NotNil(t, result)
    assert.Equal(t, expected, result.Field)
}
```

### Test Rules

| Rule              | Description                               |
| ----------------- | ----------------------------------------- |
| No arbitrary Skip | Only `testing.Short()` skip allowed       |
| Must assert       | Every test must validate results          |
| No empty tests    | Tests without assertions will fail review |
| Real calls        | LLM tests use real API calls, not mocks   |

### Key Environment Variables

| Variable               | Description                     |
| ---------------------- | ------------------------------- |
| `YAO_TEST_APPLICATION` | Test app path (`yao-dev-app`)   |
| `OPENAI_TEST_KEY`      | OpenAI API key                  |
| `DEEPSEEK_API_KEY`     | DeepSeek API key                |
| `YAO_DB_DRIVER`        | Database driver (mysql/sqlite3) |
| `YAO_DB_PRIMARY`       | Database connection string      |

---

## Progress Tracking

| Phase                 | Status | Description                                                                  |
| --------------------- | ------ | ---------------------------------------------------------------------------- |
| 1. Types & Interfaces | ✅     | All types, enums, interfaces                                                 |
| 2. Skeleton           | ✅     | Empty stubs, code compiles                                                   |
| 3. Scheduling System  | ✅     | Cache + Pool + Trigger + Job + Executor architecture                         |
| 4. Agent Infra        | ✅     | AgentCaller, InputFormatter, test assistants                                 |
| 5. Test Scenarios     | ✅     | Phase agents (P0-P5), expert agents                                          |
| 6. P0 Inspiration     | ✅     | Inspiration Agent integration                                                |
| 7. P1 Goals           | ✅     | Goal Generation Agent integration                                            |
| 8. P2 Tasks           | ✅     | Task Planning Agent integration                                              |
| 9. P3 Run             | ✅     | Task execution + validation + yao/assert + multi-turn conversation           |
| 10. P4 Delivery       | ✅     | Output delivery (email/webhook/process, notify future)                       |
| 11. API & Integration | ✅     | Go API, end-to-end tests (main flow: P0→P1→P2→P3→P4)                         |
| 12. OpenAPI           | ⬜     | HTTP endpoints (depends on frontend UI design)                               |
| 13. Advanced          | ⬜     | Process/JSAPI, P5 Learning, dedup, plan queue, Sandbox                       |

Legend: ⬜ Not started | 🟡 In progress | ✅ Complete

**Main Flow (MVP):** P0 Inspiration → P1 Goals → P2 Tasks → P3 Run → P4 Delivery ✅
**OpenAPI (Phase 12):** HTTP endpoints - planned after frontend UI design
**Advanced (Phase 13):** P5 Learning (async), Process/JSAPI, Dedup, Plan Queue, Sandbox

---

## Quick Commands

```bash
# Setup environment
source yao/env.local.sh

# Run all robot tests
go test -v ./agent/robot/...

# Run specific phase tests
go test -v ./agent/robot/types/...
go test -v ./agent/robot/cache/...
go test -v ./agent/robot/pool/...
go test -v ./agent/robot/executor/...

# Run with coverage
go test -cover ./agent/robot/...
```