@online5880/opensession 0.1.1 → 0.1.3

package/README.ko.md

@@ -0,0 +1,133 @@
+# 🌐 OpenSession
+
+**[English](README.md) | [한국어](README.ko.md)**
+
+> **AI 에이전트 운영을 위한 실행 연속성 계층 (Execution Continuity Layer)**
+
+[![npm version](https://img.shields.io/npm/v/@online5880/opensession.svg?style=flat-square)](https://www.npmjs.com/package/@online5880/opensession)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](#)
+[![Built with Supabase](https://img.shields.io/badge/Backend-Supabase-green.svg?style=flat-square)](https://supabase.com)
+
+**OpenSession**은 AI 에이전트가 다양한 도구, 환경, 네트워크 상태 사이에서 작업의 맥락(Context)과 연속성(Continuity)을 잃지 않도록 돕는 **실행 연속성 OS**입니다. 한 번 시작하면 어디서든 재개할 수 있습니다.
+
+---
+
+## 🚀 왜 OpenSession 인가요?
+
+AI 에이전트와 협업할 때 가장 큰 문제는 **"맥락의 단절(Context Fragmentation)"**입니다.
+- 로컬에서 작업하던 에이전트를 서버로 옮기면?
+- 네트워크 오류로 세션이 끊기면?
+- 여러 도구가 각자의 로그를 남겨서 전체 흐름을 파악하기 힘들다면?
+
+**OpenSession은 이 모든 문제를 해결합니다.** 단일 세션 ID로 모든 활동을 Supabase에 영속화하고, CLI/Web/TUI를 통해 끊김 없이 실시간으로 모니터링할 수 있습니다.
+
+---
+
+## ✨ 핵심 기능
+
+### 1. 영속적 세션 모델 (Stable Session Model)
+- 어떤 환경에서도 동일한 `session_id`를 사용하여 작업을 이어갑니다.
+- `start` -> `pause` -> `resume` 워크플로우를 완벽하게 지원합니다.
+
+### 2. 강력한 이벤트 타임라인 (Durable Event Timeline)
+- **의도 (Intent)**: 무엇을 하려고 하는가?
+- **액션 (Action)**: 실제 어떤 명령을 실행했는가?
+- **결과물 (Artifact)**: 무엇을 만들어냈는가?
+- 위 세 가지 핵심 요소를 구조화된 JSON으로 기록하여 심층 분석이 가능합니다.
+
+### 3. 다중 모니터링 인터페이스 (Multi-Surface Monitoring)
+- **CLI**: 직관적인 터미널 기반 제어.
+- **WebUI (Viewer)**: 브라우저에서 확인하는 고해상도 타임라인 대시보드.
+- **TUI (Terminal UI)**: 터미널 안에서 키보드로 조작하는 대화형 대시보드.
+
+### 4. 엔터프라이즈급 신뢰성 (Enterprise-Grade Reliability)
+- **멱등성(Idempotency)** 보장: 동일한 이벤트가 중복 기록되는 것을 방지합니다.
+- **지수 백오프(Exponential Backoff)**: 불안정한 네트워크 환경에서도 자동으로 재시도합니다.
+
+---
+
+## 🗺️ 로드맵: 3단계 인터페이스
+
+| 단계 (Phase) | 인터페이스 | 상태 | 기능 설명 |
+| :--- | :--- | :--- | :--- |
+| **Phase 1** | **CLI 코어** | ✅ 안정됨 | 세션 제어, 기본 로깅, 설정 관리 |
+| **Phase 2** | **WebUI 뷰어** | ✅ 안정됨 | 다크 테마, 통계(KPI) 리포트, JSON 페이로드 뷰어 |
+| **Phase 3** | **인터랙티브 TUI** | ✅ 활성화 | 대화형 세션 선택, 실시간 이벤트 스트리밍 자동 갱신 |
+
+---
+
+## 🛠️ 시작하기
+
+### 설치 및 단축어 설정 (Alias)
+
+빠른 실행을 위해 쉘 프로필에 단축어를 추가하세요:
+
+**macOS / Linux (Bash/Zsh):**
+```bash
+alias opss='npx -y @online5880/opensession'
+```
+
+**Windows (PowerShell):**
+```powershell
+function opss { npx -y @online5880/opensession @args }
+```
+
+### 1분 퀵 스타트
+
+1. **초기화**: Supabase URL과 API 키를 설정합니다.
+   ```bash
+   opss init
+   ```
+
+2. **세션 시작**: 새로운 프로젝트 세션을 시작합니다.
+   ```bash
+   opss start --project-key my-ai-lab --actor mane
+   ```
+
+3. **이벤트 기록**: 에이전트의 활동을 기록합니다.
+   ```bash
+   opss log --limit 10
+   ```
+
+4. **대시보드 실행**: 원하는 뷰어를 선택해 모니터링하세요.
+   ```bash
+   opss tui      # 터미널 대시보드 (추천)
+   opss viewer   # 웹 브라우저 뷰어
+   ```
+
+---
+
+## 📖 명령어 가이드
+
+| 명령어 | 단축어 | 설명 |
+| :--- | :--- | :--- |
+| `init` | `setup` | Supabase 서버 연결 및 로컬 설정을 초기화합니다. |
+| `start` | `st` | 새로운 세션을 생성하고 타임라인을 시작합니다. |
+| `resume` | `rs` | 멱등성 보호를 통해 기존 세션을 재개합니다. |
+| `tui` | - | **(New)** 인터랙티브 터미널 대시보드(TUI)를 실행합니다. |
+| `viewer` | `vw` | 로컬 웹 뷰어 서버를 실행합니다 (기본 8787 포트). |
+| `status` | `ps` | CLI 버전 정보 및 활성 세션 상태를 확인합니다. |
+| `report` | - | 28일간의 KPI 통계 및 주간 트렌드 분석 리포트를 생성합니다. |
+
+---
+
+## 🏗️ 아키텍처
+
+OpenSession은 에이전트 런타임과 영구 스토리지 사이의 **신뢰성 높은 연결 계층**으로 작동합니다.
+
+```mermaid
+graph TD
+    Agent[AI Agent / Developer] -->|Log/Control| CLI[OpenSession CLI]
+    CLI -->|Persist| DB[(Supabase Cloud)]
+    DB -->|Stream| TUI[TUI Dashboard]
+    DB -->|Render| Web[Web Viewer]
+```
+
+---
+
+## 🤝 기여하기 (Contributing)
+
+기여는 언제나 환영합니다! 버그 제보 및 기능 제안은 [GitHub Issues](https://github.com/online5880/opensession/issues)를 이용해 주세요.
+
+MIT © [online5880](https://github.com/online5880)

package/README.md

@@ -1,32 +1,137 @@
-# @online5880/opensession
-
-MVP CLI for session continuity with Supabase.
-
-## Commands
-
-- `init [--project-key] [--actor]` (프롬프트로 URL/ANON KEY 입력)
-- `login --actor`
-- `start --project-key [--project-name] [--actor]`
-- `resume --session-id [--actor]`
-- `status [--project-key]`
-- `sync --project <name>`
-- `log [--session-id] [--limit]`
-
-## Quick start
-
-```bash
-npm install
-node src/cli.js init --project-key demo --actor mane
-node src/cli.js sync --project demo
-node src/cli.js start --project-key demo
-node src/cli.js status
-node src/cli.js log
-```
-
-Apply `sql/schema.sql` in Supabase SQL editor before using the CLI.
-
-## npx 실행
-
-```bash
-npx @online5880/opensession init
-```
+# 🌐 OpenSession
+
+**[English](README.md) | [한국어](README.ko.md)**
+
+> **The Execution Continuity Layer for AI Agent Operations**
+
+[![npm version](https://img.shields.io/npm/v/@online5880/opensession.svg?style=flat-square)](https://www.npmjs.com/package/@online5880/opensession)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](#)
+[![Built with Supabase](https://img.shields.io/badge/Backend-Supabase-green.svg?style=flat-square)](https://supabase.com)
+
+**OpenSession** is an execution continuity layer designed to help AI agents maintain context and workflow stability across different tools, environments, and network conditions.
+
+---
+
+## 🚀 Why OpenSession?
+
+The biggest challenge in collaborating with AI agents is **"Context Fragmentation."**
+- What happens if you move an agent from local to a remote server?
+- What if the session drops due to network issues?
+- How do you track the flow across multiple tools with disparate logs?
+
+**OpenSession solves this.** By using a single session ID, all activities are persisted to Supabase, allowing you to monitor and resume work seamlessly via CLI, Web, or TUI.
+
+---
+
+## ✨ Key Capabilities
+
+### 1. Stable Session Model
+- Resume work anywhere using the same `session_id`.
+- Native support for `start` -> `pause` -> `resume` workflows.
+
+### 2. Durable Event Timeline
+- **Intent**: What is the goal?
+- **Action**: What command was executed?
+- **Artifact**: What was produced?
+- All elements are recorded in structured JSON for deep analysis.
+
+### 3. Multi-Surface Monitoring
+- **CLI**: Intuitive terminal-based control.
+- **WebUI (Viewer)**: High-resolution timeline dashboard in your browser.
+- **TUI (Terminal UI)**: Keyboard-driven interactive dashboard inside your terminal.
+
+### 4. Enterprise-Grade Reliability
+- **Idempotency**: Prevents duplicate event recording.
+- **Exponential Backoff**: Automatic retries for unstable network scenarios.
+
+---
+
+## 🗺️ Roadmap: The 3-Layer Interface
+
+| Phase | Surface | Status | Features |
+| :--- | :--- | :--- | :--- |
+| **Phase 1** | **CLI Core** | ✅ Stable | Session control, basic logging, config management |
+| **Phase 2** | **WebUI Viewer** | ✅ Stable | Dark theme, KPI reports, JSON payload viewer |
+| **Phase 3** | **Interactive TUI** | ✅ Active | Real-time session switching, live event streaming |
+
+### Installation & Setup
+
+#### 1. Alias / Function Setup
+To use the `opss` shorthand, add the following to your shell profile:
+
+**macOS / Linux (Bash/Zsh):**
+```bash
+alias opss='npx -y @online5880/opensession'
+```
+
+**Windows (PowerShell):**
+```powershell
+function opss { npx -y @online5880/opensession @args }
+```
+
+#### 2. Global Install (Optional)
+```bash
+npm install -g @online5880/opensession
+```
+
+---
+
+## 🚀 1-Minute Quickstart
+
+1. **Initialize**: Set up your Supabase URL and API Key.
+   ```bash
+   opss init
+   ```
+
+2. **Start Session**: Begin a new project session.
+   ```bash
+   opss start --project-key my-ai-lab --actor mane
+   ```
+
+3. **Log Events**: Record agent activities.
+   ```bash
+   opss log --limit 10
+   ```
+
+4. **Launch Dashboard**: Choose your preferred view.
+   ```bash
+   opss tui      # Terminal dashboard (Recommended)
+   opss viewer   # Web browser viewer
+   ```
+
+---
+
+## 📖 Command Reference
+
+| Command | Alias | Description |
+| :--- | :--- | :--- |
+| `init` | `setup` | Initialize Supabase connection and local config. |
+| `start` | `st` | Create a new session and start the timeline. |
+| `resume` | `rs` | Resume an existing session with idempotency protection. |
+| `tui` | - | **(New)** Launch the interactive Terminal UI dashboard. |
+| `viewer` | `vw` | Run a local read-only web viewer server. |
+| `status` | `ps` | Check CLI version and active session status. |
+| `report` | - | Generate 28-day KPI stats and weekly trend analysis. |
+
+---
+
+## 🏗️ Architecture
+
+OpenSession acts as a high-reliability bridge between agent runtimes and persistent storage.
+
+```mermaid
+graph TD
+    Agent[AI Agent / Developer] -->|Log/Control| CLI[OpenSession CLI]
+    CLI -->|Persist| DB[(Supabase Cloud)]
+    DB -->|Stream| TUI[TUI Dashboard]
+    DB -->|Render| Web[Web Viewer]
+```
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please use [GitHub Issues](https://github.com/online5880/opensession/issues) for bug reports and feature requests.
+
+MIT © [online5880](https://github.com/online5880)

package/package.json

@@ -1,20 +1,23 @@
-{
-  "name": "@online5880/opensession",
-  "version": "0.1.1",
-  "description": "Session continuity bridge CLI with Supabase backend",
-  "type": "module",
-  "bin": {
-    "opensession": "src/cli.js"
-  },
-  "scripts": {
-    "start": "node src/cli.js",
-    "lint": "sh -c 'for f in src/*.js; do node --check \"$f\"; done'"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "dependencies": {
-    "@supabase/supabase-js": "^2.52.1",
-    "commander": "^14.0.1"
-  }
-}
+{
+  "name": "@online5880/opensession",
+  "version": "0.1.3",
+  "description": "Session continuity bridge CLI with Supabase backend",
+  "type": "module",
+  "bin": {
+    "opensession": "src/cli.js",
+    "opss": "src/cli.js"
+  },
+  "scripts": {
+    "start": "node src/cli.js",
+    "lint": "sh -c 'for f in src/*.js; do node --check \"$f\"; done'",
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@supabase/supabase-js": "^2.52.1",
+    "blessed": "^0.1.81",
+    "commander": "^14.0.1"
+  }
+}

package/site/index.html

@@ -0,0 +1,35 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>OpenSession — Agent Execution Continuity OS</title>
+  <meta name="description" content="Start once, resume anywhere. OpenSession is the execution continuity layer for AI agent operations." />
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;600&display=swap" rel="stylesheet">
+  <style>
+    :root {--bg:#080b12;--bg-soft:#0f1420;--panel:#121a28;--panel-2:#182234;--text:#e9f1ff;--muted:#99abc9;--line:#22314a;--brand:#64d6ff;--brand-2:#8c7bff;--ok:#37d67a;}
+    *{box-sizing:border-box} body{margin:0;font-family:Inter,system-ui,-apple-system,sans-serif;color:var(--text);background:radial-gradient(1200px 700px at 85% -10%,rgba(140,123,255,.22),transparent 60%),radial-gradient(1000px 600px at 10% -10%,rgba(100,214,255,.18),transparent 58%),var(--bg)}
+    .container{width:min(1120px,92vw);margin:0 auto}.topbar{display:flex;justify-content:space-between;align-items:center;padding:18px 0;border-bottom:1px solid rgba(255,255,255,.06);position:sticky;top:0;backdrop-filter:blur(10px);background:rgba(8,11,18,.75)}
+    .brand{font-weight:800}.brand span{color:var(--brand)}.nav a{color:var(--muted);text-decoration:none;margin-left:18px;font-size:.95rem}.hero{padding:74px 0 34px;text-align:center}
+    .eyebrow{color:var(--brand);font-weight:600;letter-spacing:.12em;text-transform:uppercase;font-size:.78rem}h1{margin:14px auto;max-width:900px;font-size:clamp(2rem,5vw,3.8rem);line-height:1.08}.sub{margin:0 auto;max-width:760px;color:var(--muted);font-size:1.08rem}
+    .cta{margin-top:28px;display:flex;gap:12px;justify-content:center;flex-wrap:wrap}.btn{padding:12px 18px;border-radius:12px;text-decoration:none;font-weight:600}.btn.primary{color:#06121a;background:linear-gradient(90deg,var(--brand),#7de6ff)}.btn.secondary{color:var(--text);border:1px solid #2a3c59;background:rgba(255,255,255,.02)}
+    .metrics{margin-top:28px;display:grid;grid-template-columns:repeat(4,1fr);gap:10px;background:rgba(255,255,255,.02);border:1px solid var(--line);border-radius:14px;padding:10px}.metric{background:linear-gradient(180deg,var(--panel),var(--panel-2));border-radius:10px;padding:14px}.metric .n{font-size:1.1rem;font-weight:800}.metric .l{color:var(--muted);font-size:.85rem;margin-top:4px}
+    section{padding:36px 0}h2{margin:0 0 14px;font-size:1.45rem}.cards{display:grid;grid-template-columns:repeat(3,1fr);gap:12px}.card{border:1px solid var(--line);background:linear-gradient(180deg,var(--panel),#111827);border-radius:14px;padding:16px}.card h3{margin:0 0 8px}.card p{margin:0;color:var(--muted);font-size:.93rem}
+    .arch{border:1px solid var(--line);border-radius:14px;padding:16px;background:linear-gradient(180deg,#101827,#0d1421)}.layers{display:grid;grid-template-columns:repeat(4,1fr);gap:10px;margin-top:12px}.layer{border:1px solid #2a3e60;border-radius:10px;padding:12px;background:#0c1320}
+    .timeline{border-left:2px solid #2a3b5a;margin-left:6px;padding-left:16px}.event{margin:0 0 14px}.event span{color:var(--muted);display:block;margin-top:4px}
+    .code{border:1px solid #2a3f60;border-radius:12px;background:#08111d;overflow:auto;font-family:"JetBrains Mono",monospace;font-size:.9rem;line-height:1.6;padding:14px}.code .ok{color:var(--ok)}.code .cmd{color:#8fd0ff}
+    footer{padding:30px 0 42px;color:var(--muted);font-size:.9rem;border-top:1px solid rgba(255,255,255,.06);margin-top:22px}
+    @media (max-width:900px){.cards{grid-template-columns:1fr}.layers{grid-template-columns:1fr 1fr}.metrics{grid-template-columns:1fr 1fr}}
+  </style>
+</head>
+<body><div class="container"><div class="topbar"><div class="brand">Open<span>Session</span></div><div class="nav"><a href="#features">Features</a><a href="#docs">Docs</a><a href="#updates">What's New</a></div></div>
+<section class="hero"><div class="eyebrow">Agent Execution Continuity OS</div><h1>Start once, resume anywhere.<br/>Keep every agent run connected.</h1><p class="sub">OpenSession keeps intent, actions, and artifacts connected so teams can hand off work without losing context.</p><div class="cta"><a class="btn primary" href="#docs">Quickstart</a><a class="btn secondary" href="https://github.com/online5880/opensession" target="_blank" rel="noreferrer">GitHub</a></div>
+<div class="metrics"><div class="metric"><div class="n">Resume Anywhere</div><div class="l">single session id across environments</div></div><div class="metric"><div class="n">Intent → Action → Artifact</div><div class="l">structured execution chain</div></div><div class="metric"><div class="n">Handoff Packet</div><div class="l">3-minute transfer context</div></div><div class="metric"><div class="n">Guardrails</div><div class="l">risk-level automation control</div></div></div></section>
+<section id="features"><h2>Core capabilities</h2><div class="cards"><article class="card"><h3>Resume Anywhere ID</h3><p>Continue the same session from CLI, automation, or another machine using one stable session id.</p></article><article class="card"><h3>Automation Guardrails</h3><p>Classify risky automation paths and enforce approval policies before external side effects.</p></article><article class="card"><h3>Session Health Score</h3><p>Detect likely breakage early with health indicators for interruptions and loops.</p></article></div></section>
+<section><h2>Architecture</h2><div class="arch">OpenSession runs as an execution continuity layer above your agent/runtime stack.<div class="layers"><div class="layer"><b>Surface</b>CLI / WebUI / TUI</div><div class="layer"><b>Core</b>Sessions / Events / Handoff</div><div class="layer"><b>Policy</b>Guardrails / Approvals</div><div class="layer"><b>Storage</b>Supabase + Artifact links</div></div></div></section>
+<section id="updates"><h2>What’s New</h2><div class="timeline"><div class="event"><b>v0.1.x — continuity baseline</b><span>init/sync/start/resume/status/log stabilized with Supabase-backed runtime flow.</span></div><div class="event"><b>Viewer/TUI surfaces</b><span>read-only viewer and operational terminal flow added for daily ops visibility.</span></div><div class="event"><b>Reliability hardening</b><span>retry/idempotency and runbook-oriented operations added for unstable runtime scenarios.</span></div></div></section>
+<section id="docs"><h2>Docs · One-command start</h2><div class="code"><div><span class="cmd">alias opss='npx -y @online5880/opensession'</span></div><div><span class="cmd">opss init</span> <span class="ok"># set Supabase URL/key</span></div><div><span class="cmd">opss sync --project demo</span></div><div><span class="cmd">opss start --project-key demo --actor mane</span></div><div><span class="cmd">opss status --project demo</span></div><div><span class="cmd">opss log --limit 50</span></div></div></section>
+<footer>OpenSession · Execution continuity for AI agent operations · <a href="https://github.com/online5880/opensession" target="_blank" rel="noreferrer" style="color:#9fd6ff">GitHub</a></footer></div></body>
+</html>

package/sql/schema.sql

@@ -1,27 +1,38 @@
-create table if not exists projects (
-  id uuid primary key default gen_random_uuid(),
-  project_key text unique not null,
-  name text not null,
-  created_at timestamptz not null default now()
-);
-
-create table if not exists sessions (
-  id uuid primary key default gen_random_uuid(),
-  project_id uuid not null references projects(id) on delete cascade,
-  actor text not null,
-  status text not null default 'active',
-  started_at timestamptz not null default now(),
-  ended_at timestamptz
-);
-
-create index if not exists sessions_project_status_idx on sessions(project_id, status);
-
-create table if not exists session_events (
-  id uuid primary key default gen_random_uuid(),
-  session_id uuid not null references sessions(id) on delete cascade,
-  type text not null,
-  payload jsonb not null default '{}'::jsonb,
-  created_at timestamptz not null default now()
-);
-
-create index if not exists session_events_session_created_idx on session_events(session_id, created_at);
+create table if not exists projects (
+  id uuid primary key default gen_random_uuid(),
+  project_key text unique not null,
+  name text not null,
+  created_at timestamptz not null default now()
+);
+
+create table if not exists sessions (
+  id uuid primary key default gen_random_uuid(),
+  project_id uuid not null references projects(id) on delete cascade,
+  actor text not null,
+  status text not null default 'active',
+  started_at timestamptz not null default now(),
+  ended_at timestamptz
+);
+
+create index if not exists sessions_project_status_idx on sessions(project_id, status);
+
+create table if not exists session_events (
+  id uuid primary key default gen_random_uuid(),
+  session_id uuid not null references sessions(id) on delete cascade,
+  type text not null,
+  idempotency_key text,
+  payload jsonb not null default '{}'::jsonb,
+  created_at timestamptz not null default now()
+);
+
+update session_events
+set idempotency_key = payload->>'idempotencyKey'
+where idempotency_key is null
+  and payload ? 'idempotencyKey'
+  and nullif(payload->>'idempotencyKey', '') is not null;
+
+create index if not exists session_events_session_created_idx on session_events(session_id, created_at);
+create index if not exists session_events_idempotency_idx on session_events(session_id, type, idempotency_key);
+create unique index if not exists session_events_session_type_idempotency_key_uidx
+  on session_events(session_id, type, idempotency_key)
+  where idempotency_key is not null;

package/src/automation.js

@@ -0,0 +1,197 @@
+const DEFAULT_TIMEOUT_MS = 5000;
+
+function withTimeout(ms) {
+  return AbortSignal.timeout(Number.isInteger(ms) && ms > 0 ? ms : DEFAULT_TIMEOUT_MS);
+}
+
+function normalizeArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value;
+}
+
+function normalizeHeaders(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+
+  const output = {};
+  for (const [key, headerValue] of Object.entries(value)) {
+    if (typeof headerValue === 'string' && headerValue.trim().length > 0) {
+      output[key] = headerValue;
+    }
+  }
+  return output;
+}
+
+function normalizeWebhookTarget(target) {
+  if (!target || typeof target !== 'object') {
+    return null;
+  }
+
+  const url = typeof target.url === 'string' ? target.url.trim() : '';
+  if (!url) {
+    return null;
+  }
+
+  const eventTypes = normalizeArray(target.eventTypes).filter((item) => typeof item === 'string' && item.trim().length > 0);
+  const source = typeof target.source === 'string' && target.source.trim().length > 0 ? target.source.trim() : null;
+
+  return {
+    type: 'webhook',
+    url,
+    eventTypes,
+    source,
+    headers: normalizeHeaders(target.headers),
+    timeoutMs: Number.isInteger(target.timeoutMs) && target.timeoutMs > 0 ? target.timeoutMs : DEFAULT_TIMEOUT_MS
+  };
+}
+
+function normalizeRule(rule) {
+  if (!rule || typeof rule !== 'object') {
+    return null;
+  }
+
+  const name = typeof rule.name === 'string' && rule.name.trim().length > 0 ? rule.name.trim() : 'unnamed-rule';
+  const when = rule.when && typeof rule.when === 'object' && !Array.isArray(rule.when) ? rule.when : {};
+  const actions = normalizeArray(rule.actions)
+    .map((action) => normalizeWebhookTarget(action))
+    .filter(Boolean);
+
+  if (actions.length === 0) {
+    return null;
+  }
+
+  return {
+    name,
+    when: {
+      eventType: typeof when.eventType === 'string' ? when.eventType.trim() : null,
+      source: typeof when.source === 'string' ? when.source.trim() : null,
+      projectKey: typeof when.projectKey === 'string' ? when.projectKey.trim() : null
+    },
+    actions
+  };
+}
+
+function shouldApplyTarget(target, envelope) {
+  if (!target) {
+    return false;
+  }
+
+  if (target.source && target.source !== envelope.source) {
+    return false;
+  }
+
+  if (target.eventTypes.length > 0 && !target.eventTypes.includes(envelope.eventType)) {
+    return false;
+  }
+
+  return true;
+}
+
+function ruleMatches(rule, envelope) {
+  const { when } = rule;
+
+  if (when.eventType && when.eventType !== envelope.eventType) {
+    return false;
+  }
+
+  if (when.source && when.source !== envelope.source) {
+    return false;
+  }
+
+  if (when.projectKey && when.projectKey !== envelope.projectKey) {
+    return false;
+  }
+
+  return true;
+}
+
+async function postJson(url, body, options = {}) {
+  const headers = {
+    'Content-Type': 'application/json',
+    ...(options.headers ?? {})
+  };
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+    signal: withTimeout(options.timeoutMs)
+  });
+
+  const text = await response.text();
+  return {
+    ok: response.ok,
+    status: response.status,
+    body: text.slice(0, 400)
+  };
+}
+
+export async function dispatchAutomation(envelope, automationConfig = {}) {
+  const rules = normalizeArray(automationConfig.rules)
+    .map((rule) => normalizeRule(rule))
+    .filter(Boolean);
+  const directTargets = normalizeArray(automationConfig.webhooks)
+    .map((target) => normalizeWebhookTarget(target))
+    .filter(Boolean)
+    .filter((target) => shouldApplyTarget(target, envelope));
+
+  const results = [];
+
+  for (const target of directTargets) {
+    try {
+      const response = await postJson(target.url, envelope, target);
+      results.push({
+        channel: 'webhook',
+        mode: 'direct',
+        destination: target.url,
+        ...response
+      });
+    } catch (error) {
+      results.push({
+        channel: 'webhook',
+        mode: 'direct',
+        destination: target.url,
+        ok: false,
+        status: 0,
+        body: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  for (const rule of rules) {
+    if (!ruleMatches(rule, envelope)) {
+      continue;
+    }
+
+    for (const action of rule.actions) {
+      try {
+        const response = await postJson(action.url, {
+          rule: rule.name,
+          event: envelope
+        }, action);
+        results.push({
+          channel: 'webhook',
+          mode: 'rule',
+          rule: rule.name,
+          destination: action.url,
+          ...response
+        });
+      } catch (error) {
+        results.push({
+          channel: 'webhook',
+          mode: 'rule',
+          rule: rule.name,
+          destination: action.url,
+          ok: false,
+          status: 0,
+          body: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+  }
+
+  return results;
+}