opc-agent 0.9.0 → 1.1.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to OPC Agent will be documented in this file.
 
+## [1.1.0] - 2026-04-16
+
+### Added
+- **Feishu/Lark Channel**: Full Feishu bot integration with event subscription webhook, tenant access token caching, text & interactive card messaging, group + P2P support. Also works with Lark international via `apiBase` config. (`src/channels/feishu.ts`)
+- **Discord Channel**: Discord bot via Gateway WebSocket with auto-reconnect, heartbeat, message content intent, and 2000-char message splitting. (`src/channels/discord.ts`)
+- **ProcessWatcher**: Background process output monitoring with regex pattern matching — watch stdout/stderr for specific patterns (errors, "server ready", build completion) and get instant callbacks without polling. Supports `once` patterns, match history, and dynamic pattern add/remove. Inspired by Hermes Agent's `watch_patterns`. (`src/core/watch.ts`)
+
 ## [0.2.0] - 2026-04-15
 
 ### Added

package/README.md

@@ -1,188 +1,189 @@
-# OPC Agent
+<p align="center">
+  <h1 align="center">🤖 OPC Agent</h1>
+  <p align="center"><strong>Open Agent Framework — Build, test, and run AI Agents for business workstations</strong></p>
+  <p align="center">
+    <a href="https://www.npmjs.com/package/opc-agent"><img src="https://img.shields.io/npm/v/opc-agent?color=blue" alt="npm"></a>
+    <a href="https://github.com/anthropic-lab/opc-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="license"></a>
+    <a href="https://github.com/anthropic-lab/opc-agent/actions"><img src="https://img.shields.io/badge/tests-passing-brightgreen" alt="tests"></a>
+    <a href="https://www.npmjs.com/package/opc-agent"><img src="https://img.shields.io/npm/dm/opc-agent?color=orange" alt="downloads"></a>
+  </p>
+</p>
 
-**Open Agent Framework** — Build, test, and run AI Agents for business workstations.
+---
 
-[![npm version](https://img.shields.io/npm/v/opc-agent.svg)](https://www.npmjs.com/package/opc-agent)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+OPC Agent is a **TypeScript-first framework** for building production AI agents. Define your agent in a single YAML file (OAD — Open Agent Definition), connect any LLM provider, deploy to any channel.
 
-## Features
-
-- 🤖 **Agent Framework** — BaseAgent with lifecycle management, skills, and LLM integration
-- 📋 **OAD Schema** — Declarative agent definition (YAML/JSON) with validation
-- 🧠 **Memory System** — Short-term + long-term memory with DeepBrain integration
-- 🔌 **Multi-Channel** — Web, WebSocket, and Telegram channels
-- 🛡️ **DTV Framework** — Data, Trust, and Value tracking for agents
-- 🎯 **Skill System** — Pluggable skills with registry and priority execution
-- 📦 **Templates** — Customer service, sales assistant, knowledge base, code reviewer
-- 🚀 **CLI** — Interactive project creation, dev mode, build, test, run
-
-## Quick Start
+## ⚡ Quick Start (30 seconds)
 
 ```bash
-# Install globally
+# Install
 npm install -g opc-agent
 
-# Create a new agent project (interactive)
+# Create your first agent
 opc init my-agent
-
-# Or with a specific template
-opc init my-bot --template sales-assistant
-
-# Run the agent
 cd my-agent
+
+# Run it
 opc run
 ```
 
-## Templates
-
-| Template | Description |
-|----------|-------------|
-| `customer-service` | FAQ lookup + human handoff |
-| `sales-assistant` | Product Q&A + lead capture + appointment booking |
-| `knowledge-base` | RAG with DeepBrain semantic search |
-| `code-reviewer` | Bug detection + style checking |
+Your agent is now live at `http://localhost:3000` with a beautiful web chat UI.
 
-## 🚀 Deploy to OpenClaw
+## ✨ Features
 
-OPC Agent is a **development framework**. [OpenClaw](https://github.com/nicepkg/openclaw) is the **runtime**. Design your agent with OPC, deploy it to OpenClaw, and it runs on Telegram, Discord, or any channel OpenClaw supports.
-
-```bash
-# Generate OpenClaw workspace from your OAD
-opc deploy --target openclaw --output ./my-agent-workspace
+### 🔌 Multi-Provider LLM Support
+```yaml
+# oad.yaml
+spec:
+  provider:
+    default: deepseek
+    allowed: [openai, deepseek, qwen, anthropic, ollama]
+  model: deepseek-chat
+```
 
-# Or deploy AND auto-register in OpenClaw
-opc deploy --target openclaw --install
+Supports **OpenAI**, **DeepSeek**, **Anthropic**, **Qwen**, **Ollama** (local), and any OpenAI-compatible API.
 
-# Then restart OpenClaw to pick it up
-openclaw gateway restart
+### 📡 Multi-Channel Deployment
+```yaml
+spec:
+  channels:
+    - type: web        # Beautiful chat UI
+      port: 3000
+    - type: telegram   # Telegram bot
+    - type: websocket  # Real-time WebSocket
+    - type: slack       # Slack integration
+    - type: email       # Email channel
+    - type: wechat      # WeChat Official Account
+    - type: voice       # Voice (STT/TTS)
+    - type: webhook     # Incoming webhooks
 ```
 
-This generates `IDENTITY.md`, `SOUL.md`, `AGENTS.md`, `USER.md`, and `MEMORY.md` — everything OpenClaw needs to run your agent.
+### 🧠 Knowledge Base (RAG)
+```typescript
+import { KnowledgeBase } from 'opc-agent';
 
-See [`examples/customer-service-demo/`](examples/customer-service-demo/) for a complete walkthrough.
+const kb = new KnowledgeBase('./docs');
+await kb.addFile('product-manual.pdf');
+// Agent automatically uses KB for context
+```
 
-## CLI Commands
+### 🔧 Plugin System
+```yaml
+spec:
+  plugins:
+    - name: logging
+    - name: analytics
+    - name: rate-limit
+      config: { maxPerMinute: 60 }
+```
 
-| Command | Description |
-|---------|-------------|
-| `opc init [name]` | Create new project (interactive) |
-| `opc create <name>` | Create agent from template |
-| `opc info` | Show agent info from OAD |
-| `opc build` | Validate OAD |
-| `opc test` | Run in sandbox mode |
-| `opc run` | Start agent with channels |
-| `opc dev` | Hot-reload development mode |
-| `opc deploy` | **Deploy to OpenClaw runtime** |
-| `opc publish` | Validate and generate manifest |
-| `opc search <query>` | Search OPC Registry (coming soon) |
+Built-in plugins: `logging`, `analytics`, `rate-limit`. Custom plugins support lifecycle hooks: `onInit`, `onMessage`, `onResponse`, `onError`, `onShutdown`.
 
-## OAD Schema
+### 🔒 Security
+- Input sanitization (XSS, injection prevention)
+- API key rotation & management
+- CORS configuration
+- Helmet-style security headers
+- Content Security Policy
+- Auth middleware with session isolation
 
-OAD (Open Agent Definition) is a declarative schema for defining agents:
+### 🧪 Agent Testing
+```bash
+opc test              # Run test cases
+opc test --watch      # Watch mode
+```
 
 ```yaml
-apiVersion: opc/v1
-kind: Agent
-metadata:
-  name: my-agent
-  version: 1.0.0
-  description: "My AI agent"
-  marketplace:
-    category: support
-    pricing: free
-    tags: [ai, support]
-spec:
-  provider:
-    default: deepseek
-    allowed: [openai, deepseek, qwen]
-  model: deepseek-chat
-  systemPrompt: "You are a helpful assistant."
-  skills:
-    - name: faq-lookup
-      description: "Answer FAQs"
-  channels:
-    - type: web
-      port: 3000
-    - type: telegram
-      config:
-        token: "BOT_TOKEN"
-    - type: websocket
-      port: 3002
-  memory:
-    shortTerm: true
-    longTerm:
-      provider: deepbrain
-      collection: my-knowledge
-  dtv:
-    trust:
-      level: sandbox
-    value:
-      metrics: [response_time]
+# tests/greeting.yaml
+- input: "Hello"
+  expect:
+    contains: ["hello", "hi"]
+    maxLatencyMs: 5000
 ```
 
-## Memory Providers
+### 🎭 Multi-Agent Orchestration
+```typescript
+import { Orchestrator } from 'opc-agent';
 
-### In-Memory (default)
-Simple key-value store. Data lost on restart.
+const orchestrator = new Orchestrator({
+  agents: [triageAgent, salesAgent, supportAgent],
+  strategy: 'route-by-intent',
+});
+```
 
-### DeepBrain (optional)
-Semantic search over past conversations and knowledge. Install `deepbrain` package:
+### 📊 Built-in Analytics & Monitoring
+- `/api/health` — Health check
+- `/api/metrics` — Prometheus-compatible metrics
+- `/api/dashboard` — Real-time dashboard UI
+- Conversation export (JSON, Markdown, CSV)
 
-```bash
-npm install deepbrain
-```
+## 🏗️ Architecture
 
-Configure in OAD:
-```yaml
-memory:
-  longTerm:
-    provider: deepbrain
-    collection: my-collection
+```
+┌─────────────────────────────────────────────────┐
+│                   OAD (YAML)                     │
+│          Agent Definition & Config               │
+├─────────────────────────────────────────────────┤
+│                                                  │
+│  ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
+│  │ Channels │  │ Plugins  │  │   Security   │  │
+│  │ web,tg,  │  │ logging, │  │  sanitize,   │  │
+│  │ ws,slack │  │ analytics│  │  CORS, auth  │  │
+│  └────┬─────┘  └────┬─────┘  └──────┬───────┘  │
+│       │              │               │           │
+│  ┌────▼──────────────▼───────────────▼────────┐ │
+│  │              Agent Runtime                  │ │
+│  │   ┌─────────┐ ┌────────┐ ┌─────────────┐  │ │
+│  │   │ Memory  │ │ Skills │ │  Knowledge   │  │ │
+│  │   └─────────┘ └────────┘ └─────────────┘  │ │
+│  └────────────────────┬───────────────────────┘ │
+│                       │                          │
+│  ┌────────────────────▼───────────────────────┐ │
+│  │            LLM Providers                    │ │
+│  │  OpenAI · DeepSeek · Anthropic · Ollama    │ │
+│  └─────────────────────────────────────────────┘│
+└─────────────────────────────────────────────────┘
 ```
 
-Falls back to in-memory if deepbrain is not installed.
+## 📖 CLI Reference
 
-## Channels
+| Command | Description |
+|---------|-------------|
+| `opc init [name]` | Create a new agent project |
+| `opc run` | Start the agent |
+| `opc dev` | Start in development mode (auto-reload) |
+| `opc test` | Run agent test cases |
+| `opc validate` | Validate OAD configuration |
+| `opc deploy hermes` | Deploy to Hermes cloud |
+| `opc plugin list` | List available plugins |
+| `opc plugin add <name>` | Add a plugin to config |
+| `opc migrate` | Migrate OAD to latest schema |
+| `opc marketplace publish` | Publish to marketplace |
 
-- **Web** — Express HTTP server with `/chat` endpoint and SSE streaming
-- **WebSocket** — Real-time bidirectional communication with broadcast
-- **Telegram** — Webhook handler for Telegram Bot API
+## 🤝 Contributing
 
-## Programmatic Usage
+We welcome contributions! Here's how:
 
-```typescript
-import { BaseAgent, AgentRuntime } from 'opc-agent';
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Make your changes with tests
+4. Run tests: `npm test`
+5. Submit a pull request
 
-// Quick start
-const agent = new BaseAgent({
-  name: 'my-agent',
-  systemPrompt: 'You are helpful.',
-});
-await agent.init();
-
-// With skills
-agent.registerSkill({
-  name: 'greeter',
-  description: 'Greet users',
-  execute: async (ctx, msg) => {
-    if (msg.content.includes('hello')) {
-      return { handled: true, response: 'Hi!', confidence: 1.0 };
-    }
-    return { handled: false, confidence: 0 };
-  },
-});
+### Development Setup
 
-// From OAD config
-const runtime = new AgentRuntime();
-await runtime.loadConfig('oad.yaml');
-await runtime.initialize();
-await runtime.start();
+```bash
+git clone https://github.com/anthropic-lab/opc-agent.git
+cd opc-agent
+npm install
+npm run build
+npm test
 ```
 
-## Contributing
+## 📄 License
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+[Apache License 2.0](LICENSE) — Use it freely in commercial and open source projects.
 
-## License
+---
 
-Apache-2.0 — see [LICENSE](LICENSE).
+<p align="center">Built with ❤️ by the OPC team</p>

package/dist/channels/discord.d.ts

@@ -0,0 +1,44 @@
+import { BaseChannel } from './index';
+/**
+ * Discord Channel — v1.1.0
+ *
+ * Supports:
+ * - Discord Bot via Gateway (WebSocket) or HTTP interactions
+ * - Slash commands, message content intent
+ * - Thread-based conversations
+ * - Reactions, embeds
+ *
+ * Env vars:
+ *   DISCORD_BOT_TOKEN — bot token
+ *   DISCORD_APPLICATION_ID — application ID for slash commands
+ */
+export interface DiscordChannelConfig {
+    /** Bot token */
+    botToken?: string;
+    /** Application ID */
+    applicationId?: string;
+    /** Guild IDs to register slash commands (empty = global) */
+    guildIds?: string[];
+    /** Whether to use threads for conversations */
+    useThreads?: boolean;
+}
+export declare class DiscordChannel extends BaseChannel {
+    readonly type = "discord";
+    private config;
+    private ws;
+    private heartbeatInterval;
+    private sequenceNumber;
+    private sessionId;
+    private resumeUrl;
+    constructor(config?: DiscordChannelConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private identify;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private sendHeartbeat;
+    private handleMessage;
+    sendMessage(channelId: string, content: string): Promise<void>;
+    private splitMessage;
+}
+//# sourceMappingURL=discord.d.ts.map

package/dist/channels/discord.js

@@ -0,0 +1,189 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiscordChannel = void 0;
+const index_1 = require("./index");
+class DiscordChannel extends index_1.BaseChannel {
+    type = 'discord';
+    config;
+    ws = null;
+    heartbeatInterval = null;
+    sequenceNumber = null;
+    sessionId = null;
+    resumeUrl = null;
+    constructor(config = {}) {
+        super();
+        this.config = {
+            botToken: config.botToken ?? process.env.DISCORD_BOT_TOKEN ?? '',
+            applicationId: config.applicationId ?? process.env.DISCORD_APPLICATION_ID ?? '',
+            guildIds: config.guildIds ?? [],
+            useThreads: config.useThreads ?? true,
+        };
+    }
+    async start() {
+        if (!this.config.botToken) {
+            console.warn('[DiscordChannel] No bot token. Set DISCORD_BOT_TOKEN.');
+            return;
+        }
+        // Get gateway URL
+        const gatewayResp = await fetch('https://discord.com/api/v10/gateway/bot', {
+            headers: { Authorization: `Bot ${this.config.botToken}` },
+        });
+        const gatewayData = await gatewayResp.json();
+        const wsUrl = `${gatewayData.url}?v=10&encoding=json`;
+        const { WebSocket } = await Promise.resolve().then(() => __importStar(require('ws')));
+        this.ws = new WebSocket(wsUrl);
+        this.ws.on('message', async (data) => {
+            const payload = JSON.parse(data.toString());
+            this.sequenceNumber = payload.s ?? this.sequenceNumber;
+            switch (payload.op) {
+                case 10: // Hello
+                    this.startHeartbeat(payload.d.heartbeat_interval);
+                    this.identify();
+                    break;
+                case 11: // Heartbeat ACK
+                    break;
+                case 0: // Dispatch
+                    if (payload.t === 'READY') {
+                        this.sessionId = payload.d.session_id;
+                        this.resumeUrl = payload.d.resume_gateway_url;
+                        console.log(`[DiscordChannel] Connected as ${payload.d.user.username}`);
+                    }
+                    else if (payload.t === 'MESSAGE_CREATE') {
+                        await this.handleMessage(payload.d);
+                    }
+                    break;
+            }
+        });
+        this.ws.on('close', (code) => {
+            console.log(`[DiscordChannel] WebSocket closed: ${code}`);
+            this.stopHeartbeat();
+            // Auto-reconnect after 5s for resumable codes
+            if (code !== 4004 && code !== 4014) {
+                setTimeout(() => this.start(), 5000);
+            }
+        });
+        this.ws.on('error', (err) => {
+            console.error('[DiscordChannel] WebSocket error:', err.message);
+        });
+    }
+    async stop() {
+        this.stopHeartbeat();
+        if (this.ws) {
+            this.ws.close(1000);
+            this.ws = null;
+        }
+    }
+    identify() {
+        this.ws?.send(JSON.stringify({
+            op: 2,
+            d: {
+                token: this.config.botToken,
+                intents: (1 << 9) | (1 << 15), // GUILD_MESSAGES | MESSAGE_CONTENT
+                properties: {
+                    os: process.platform,
+                    browser: 'opc-agent',
+                    device: 'opc-agent',
+                },
+            },
+        }));
+    }
+    startHeartbeat(intervalMs) {
+        this.stopHeartbeat();
+        // Send first heartbeat with jitter
+        setTimeout(() => {
+            this.sendHeartbeat();
+            this.heartbeatInterval = setInterval(() => this.sendHeartbeat(), intervalMs);
+        }, intervalMs * Math.random());
+    }
+    stopHeartbeat() {
+        if (this.heartbeatInterval) {
+            clearInterval(this.heartbeatInterval);
+            this.heartbeatInterval = null;
+        }
+    }
+    sendHeartbeat() {
+        this.ws?.send(JSON.stringify({ op: 1, d: this.sequenceNumber }));
+    }
+    async handleMessage(d) {
+        // Ignore bot messages
+        const author = d.author;
+        if (author?.bot)
+            return;
+        if (!d.content || !this.handler)
+            return;
+        const msg = {
+            id: `discord_${d.id}`,
+            role: 'user',
+            content: d.content,
+            timestamp: new Date(d.timestamp).getTime(),
+            metadata: {
+                sessionId: `discord_${d.channel_id}`,
+                chatId: d.channel_id,
+                userId: author.id,
+                platform: 'discord',
+                guildId: d.guild_id,
+                threadId: d.thread?.toString(),
+            },
+        };
+        const response = await this.handler(msg);
+        await this.sendMessage(d.channel_id, response.content);
+    }
+    async sendMessage(channelId, content) {
+        // Discord max message length is 2000
+        const chunks = this.splitMessage(content, 2000);
+        for (const chunk of chunks) {
+            await fetch(`https://discord.com/api/v10/channels/${channelId}/messages`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bot ${this.config.botToken}`,
+                },
+                body: JSON.stringify({ content: chunk }),
+            });
+        }
+    }
+    splitMessage(text, maxLen) {
+        if (text.length <= maxLen)
+            return [text];
+        const parts = [];
+        for (let i = 0; i < text.length; i += maxLen) {
+            parts.push(text.slice(i, i + maxLen));
+        }
+        return parts;
+    }
+}
+exports.DiscordChannel = DiscordChannel;
+//# sourceMappingURL=discord.js.map

package/dist/channels/feishu.d.ts

@@ -0,0 +1,47 @@
+import { BaseChannel } from './index';
+/**
+ * Feishu / Lark Channel — v1.1.0
+ *
+ * Supports:
+ * - Event Subscription (webhook) mode for receiving messages
+ * - Bot send via Feishu Open API
+ * - URL verification challenge
+ * - Message card (interactive) responses
+ * - Group chat & P2P messaging
+ *
+ * Env vars:
+ *   FEISHU_APP_ID, FEISHU_APP_SECRET — app credentials
+ *   FEISHU_VERIFICATION_TOKEN — event subscription verification
+ *   FEISHU_ENCRYPT_KEY — (optional) event encryption key
+ */
+export interface FeishuChannelConfig {
+    /** Feishu App ID */
+    appId?: string;
+    /** Feishu App Secret */
+    appSecret?: string;
+    /** Verification token for event subscription */
+    verificationToken?: string;
+    /** Encrypt key (optional, for encrypted events) */
+    encryptKey?: string;
+    /** Webhook server port (default: 3002) */
+    port?: number;
+    /** API base URL (use 'https://open.larksuite.com' for Lark international) */
+    apiBase?: string;
+}
+export declare class FeishuChannel extends BaseChannel {
+    readonly type = "feishu";
+    private config;
+    private server;
+    private tokenCache;
+    private processedEvents;
+    constructor(config?: FeishuChannelConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Get tenant access token (cached) */
+    private getAccessToken;
+    /** Send a text message to a chat */
+    sendTextMessage(chatId: string, text: string): Promise<void>;
+    /** Send an interactive card message */
+    sendCardMessage(chatId: string, card: Record<string, unknown>): Promise<void>;
+}
+//# sourceMappingURL=feishu.d.ts.map