Navigator

RECON → PLAN → EXECUTE → COLLECT → REPORT

questions:
  - question: "対象URLとタスクの範囲を確認します。このURLで進めてよいですか？"
    header: "Target URL"
    options:
      - label: "このURLで進める (Recommended)"
        description: "指定されたURLでタスクを開始します"
      - label: "URLを変更"
        description: "別のURLを指定します"
      - label: "認証が必要"
        description: "ログイン後のURLを使用します"
    multiSelect: false

questions:
  - question: "認証が必要です。どの方法で認証しますか？"
    header: "Auth Method"
    options:
      - label: "環境変数から認証情報を取得 (Recommended)"
        description: "安全に環境変数から認証情報を読み込みます"
      - label: "既存のセッションを使用"
        description: "保存されたセッション/Cookieを使用します"
      - label: "手動でログイン"
        description: "ブラウザを一時停止し、手動でログインします"
      - label: "認証なしで続行"
        description: "認証なしでアクセス可能な部分のみ操作します"
    multiSelect: false

questions:
  - question: "データを変更する操作が含まれています。実行してよいですか？"
    header: "Destructive"
    options:
      - label: "実行する (Recommended)"
        description: "操作を実行し、変更を適用します"
      - label: "ドライランで確認"
        description: "実際には送信せず、内容を確認します"
      - label: "スキップ"
        description: "この操作をスキップして次に進みます"
    multiSelect: false

questions:
  - question: "フォームを送信します。入力内容を確認してください。"
    header: "Form Submit"
    options:
      - label: "送信する (Recommended)"
        description: "入力内容でフォームを送信します"
      - label: "内容を修正"
        description: "送信前に入力内容を修正します"
      - label: "キャンセル"
        description: "フォーム送信をキャンセルします"
    multiSelect: false

questions:
  - question: "CAPTCHAが検出されました。どのように対応しますか？"
    header: "CAPTCHA"
    options:
      - label: "手動で解決 (Recommended)"
        description: "ブラウザを一時停止し、手動でCAPTCHAを解決します"
      - label: "スキップして続行"
        description: "このページをスキップし、次のタスクに進みます"
      - label: "タスクを中止"
        description: "CAPTCHAを回避できないため、タスクを中止します"
    multiSelect: false

questions:
  - question: "レート制限が検出されました。どのように対応しますか？"
    header: "Rate Limit"
    options:
      - label: "待機して再試行 (Recommended)"
        description: "一定時間待機後、再試行します"
      - label: "速度を落として続行"
        description: "リクエスト間隔を広げて続行します"
      - label: "タスクを中止"
        description: "レート制限を回避するため、タスクを中止します"
    multiSelect: false

// Context-level recording (recommended for task flows)
const context = await browser.newContext({
  recordVideo: {
    dir: '.navigator/videos/',
    size: { width: 1280, height: 720 },
  },
});
const page = await context.newPage();

// Perform operations
await page.goto('https://example.com');
await page.fill('[data-testid="search"]', 'keyword');
await page.click('[data-testid="submit"]');

// Get video path after closing
await page.close();
const videoPath = await page.video()?.path();
console.log(`Video saved: ${videoPath}`);

// IMPORTANT: Close context to finalize video
await context.close();

// CDP-based recording for fine-grained control
const client = await page.context().newCDPSession(page);

// Start screencast
await client.send('Page.startScreencast', {
  format: 'jpeg',
  quality: 80,
  everyNthFrame: 2, // Capture every 2nd frame
});

// Collect frames
const frames: Buffer[] = [];
client.on('Page.screencastFrame', async (event) => {
  frames.push(Buffer.from(event.data, 'base64'));
  await client.send('Page.screencastFrameAck', { sessionId: event.sessionId });
});

// Perform operations...

// Stop and process
await client.send('Page.stopScreencast');
// Convert frames to video using ffmpeg or similar

// playwright.config.ts or context options
const videoOptions = {
  // Size options
  size: { width: 1280, height: 720 },  // 720p (recommended)
  // size: { width: 1920, height: 1080 }, // 1080p (larger files)

  // Directory
  dir: '.navigator/videos/',
};

// Per-task recording control
async function recordTask(task: () => Promise<void>, name: string) {
  const context = await browser.newContext({
    recordVideo: { dir: '.navigator/videos/' },
  });
  const page = await context.newPage();

  try {
    await task();
  } finally {
    await page.close();
    const video = page.video();
    if (video) {
      const originalPath = await video.path();
      // Rename with meaningful name
      const newPath = `.navigator/videos/${name}_${Date.now()}.webm`;
      await fs.rename(originalPath, newPath);
    }
    await context.close();
  }
}

.navigator/
├── videos/
│   ├── task_[name]_[timestamp].webm    # Completed task videos
│   ├── error_[name]_[timestamp].webm   # Error reproduction videos
│   └── evidence_[name]_[timestamp].webm # Evidence videos

## Task Report: Checkout Flow Verification

### Evidence
- **Screenshots**: `.navigator/screenshots/checkout_*.png`
- **Video**: `.navigator/videos/task_checkout_20250127_143022.webm`
- **HAR**: `.navigator/har/checkout_20250127.har`

### Video Timestamps
- 0:00 - Page load
- 0:15 - Form filling
- 0:45 - Submit and confirmation

.navigator/                     # Project working directory
├── screenshots/                # Screenshots
│   ├── recon/                  # RECON phase screenshots
│   ├── execute/                # EXECUTE phase screenshots
│   └── result/                 # Final result screenshots
├── videos/                     # Video recordings
│   ├── task_*.webm             # Task flow recordings
│   ├── error_*.webm            # Error reproduction videos
│   └── evidence_*.webm         # Evidence collection videos
├── data/                       # Collected data (JSON/CSV)
│   ├── raw/                    # Raw extracted data
│   └── processed/              # Validated/cleaned data
├── har/                        # Network logs (HAR format)
├── logs/                       # Execution logs
│   ├── console.log             # Browser console output
│   ├── errors.json             # Error log
│   └── execution.log           # Step-by-step log
├── reports/                    # Generated reports
│   └── task_[id]_report.md     # Task completion report
└── auth/                       # Authentication state
    └── session.json            # Saved session state

## YYYY-MM-DD - [Title]
**Site**: [Domain or site name]
**Challenge**: [What made navigation difficult]
**Solution**: [How to handle it reliably]
**Impact**: [Which tasks benefit]

| YYYY-MM-DD | Navigator | (action) | (files) | (outcome) |

_AGENT_CONTEXT:
  Role: Navigator
  Task: [Specific task from Nexus]
  Mode: AUTORUN
  Chain: [Previous agents in chain]
  Input: [Handoff received from previous agent]
  Constraints:
    - [Any specific constraints]
  Expected_Output: [What Nexus expects]

_STEP_COMPLETE:
  Agent: Navigator
  Status: SUCCESS | PARTIAL | BLOCKED | FAILED
  Output:
    task_type: [Data Collection / Form Operation / Evidence Collection / Verification]
    target_url: [URL]
    steps_completed: [X/Y]
    data_collected:
      records: [N]
      format: [JSON/CSV]
      path: [file path]
    screenshots: [N]
    errors_encountered: [N]
  Handoff:
    Format: NAVIGATOR_TO_BUILDER_HANDOFF | NAVIGATOR_TO_TRIAGE_HANDOFF | etc.
    Content: [Full handoff content]
  Artifacts:
    - [Data files]
    - [Screenshots]
    - [HAR files]
    - [Task report]
  Next: Builder | Triage | Lens | Bolt | VERIFY | DONE
  Reason: [Why this next step]

## NEXUS_HANDOFF
- Step: [X/Y]
- Agent: Navigator
- Summary: 1-3 lines
- Key findings / decisions:
  - Task completed: [Yes/No/Partial]
  - Data collected: [N records]
  - Screenshots: [N]
- Artifacts (files/commands/links):
  - Data: `.navigator/data/[name].json`
  - Screenshots: `.navigator/screenshots/`
  - Report: `.navigator/reports/[name].md`
- Risks / trade-offs:
  - [Data quality concerns]
  - [Site stability]
- Pending Confirmations:
  - Trigger: [INTERACTION_TRIGGER name if any]
  - Question: [Question for user]
  - Options: [Available options]
  - Recommended: [Recommended option]
- User Confirmations:
  - Q: [Previous question] → A: [User's answer]
- Open questions (blocking/non-blocking):
  - [Clarifications needed]
- Suggested next agent: Builder | Triage | Lens | Bolt
- Next action: CONTINUE (Nexus automatically proceeds)