opc-agent 0.9.0 → 1.1.0

package/src/channels/feishu.ts

@@ -0,0 +1,236 @@
+import { BaseChannel } from './index';
+import type { Message } from '../core/types';
+
+/**
+ * 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;
+}
+
+interface FeishuTokenCache {
+  token: string;
+  expiresAt: number;
+}
+
+export class FeishuChannel extends BaseChannel {
+  readonly type = 'feishu';
+  private config: Required<Pick<FeishuChannelConfig, 'port' | 'apiBase'>> & FeishuChannelConfig;
+  private server: import('http').Server | null = null;
+  private tokenCache: FeishuTokenCache | null = null;
+  private processedEvents = new Set<string>();
+
+  constructor(config: FeishuChannelConfig = {}) {
+    super();
+    this.config = {
+      appId: config.appId ?? process.env.FEISHU_APP_ID ?? '',
+      appSecret: config.appSecret ?? process.env.FEISHU_APP_SECRET ?? '',
+      verificationToken: config.verificationToken ?? process.env.FEISHU_VERIFICATION_TOKEN ?? '',
+      encryptKey: config.encryptKey ?? process.env.FEISHU_ENCRYPT_KEY,
+      port: config.port ?? 3002,
+      apiBase: config.apiBase ?? 'https://open.feishu.cn',
+    };
+  }
+
+  async start(): Promise<void> {
+    if (!this.config.appId || !this.config.appSecret) {
+      console.warn('[FeishuChannel] Missing appId/appSecret. Set FEISHU_APP_ID and FEISHU_APP_SECRET.');
+      return;
+    }
+
+    const express = (await import('express')).default;
+    const app = express();
+    app.use(express.json());
+
+    // Event subscription endpoint
+    app.post('/feishu/event', async (req, res) => {
+      try {
+        const body = req.body;
+
+        // URL verification challenge
+        if (body.type === 'url_verification') {
+          res.json({ challenge: body.challenge });
+          return;
+        }
+
+        // Deduplicate events
+        const eventId = body.header?.event_id;
+        if (eventId && this.processedEvents.has(eventId)) {
+          res.json({ ok: true });
+          return;
+        }
+        if (eventId) {
+          this.processedEvents.add(eventId);
+          // Prune old events (keep last 1000)
+          if (this.processedEvents.size > 1000) {
+            const arr = [...this.processedEvents];
+            this.processedEvents = new Set(arr.slice(-500));
+          }
+        }
+
+        // Verify token
+        if (this.config.verificationToken && body.header?.token !== this.config.verificationToken) {
+          res.status(403).json({ error: 'Invalid verification token' });
+          return;
+        }
+
+        // Handle im.message.receive_v1
+        const event = body.event;
+        if (body.header?.event_type === 'im.message.receive_v1' && this.handler) {
+          const msgBody = event?.message;
+          if (!msgBody) { res.json({ ok: true }); return; }
+
+          // Only handle text messages for now
+          const msgType = msgBody.message_type;
+          let content = '';
+          if (msgType === 'text') {
+            try {
+              const parsed = JSON.parse(msgBody.content);
+              content = parsed.text ?? '';
+            } catch {
+              content = msgBody.content ?? '';
+            }
+          } else {
+            // Acknowledge non-text silently
+            res.json({ ok: true });
+            return;
+          }
+
+          // Strip @bot mentions
+          content = content.replace(/@_user_\d+/g, '').trim();
+          if (!content) { res.json({ ok: true }); return; }
+
+          const chatId = msgBody.chat_id;
+          const senderId = event.sender?.sender_id?.open_id ?? 'unknown';
+
+          const msg: Message = {
+            id: `feishu_${msgBody.message_id}`,
+            role: 'user',
+            content,
+            timestamp: parseInt(msgBody.create_time, 10) || Date.now(),
+            metadata: {
+              sessionId: `feishu_${chatId}`,
+              chatId,
+              userId: senderId,
+              platform: 'feishu',
+              messageId: msgBody.message_id,
+              chatType: msgBody.chat_type, // 'p2p' or 'group'
+            },
+          };
+
+          const response = await this.handler(msg);
+          await this.sendTextMessage(chatId, response.content);
+        }
+
+        res.json({ ok: true });
+      } catch (err) {
+        console.error('[FeishuChannel] Error handling event:', err);
+        res.status(500).json({ error: 'Internal error' });
+      }
+    });
+
+    app.get('/health', (_req, res) => {
+      res.json({ status: 'ok', channel: 'feishu' });
+    });
+
+    this.server = app.listen(this.config.port, () => {
+      console.log(`[FeishuChannel] Listening on port ${this.config.port}`);
+    });
+  }
+
+  async stop(): Promise<void> {
+    if (this.server) {
+      this.server.close();
+      this.server = null;
+    }
+  }
+
+  /** Get tenant access token (cached) */
+  private async getAccessToken(): Promise<string> {
+    if (this.tokenCache && Date.now() < this.tokenCache.expiresAt) {
+      return this.tokenCache.token;
+    }
+
+    const resp = await fetch(`${this.config.apiBase}/open-apis/auth/v3/tenant_access_token/internal`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        app_id: this.config.appId,
+        app_secret: this.config.appSecret,
+      }),
+    });
+
+    const data = await resp.json() as { tenant_access_token: string; expire: number; code: number };
+    if (data.code !== 0) {
+      throw new Error(`[FeishuChannel] Failed to get access token: ${JSON.stringify(data)}`);
+    }
+
+    this.tokenCache = {
+      token: data.tenant_access_token,
+      expiresAt: Date.now() + (data.expire - 60) * 1000, // refresh 60s early
+    };
+    return this.tokenCache.token;
+  }
+
+  /** Send a text message to a chat */
+  async sendTextMessage(chatId: string, text: string): Promise<void> {
+    const token = await this.getAccessToken();
+    const resp = await fetch(`${this.config.apiBase}/open-apis/im/v1/messages?receive_id_type=chat_id`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`,
+      },
+      body: JSON.stringify({
+        receive_id: chatId,
+        msg_type: 'text',
+        content: JSON.stringify({ text }),
+      }),
+    });
+
+    if (!resp.ok) {
+      console.error('[FeishuChannel] Failed to send message:', await resp.text());
+    }
+  }
+
+  /** Send an interactive card message */
+  async sendCardMessage(chatId: string, card: Record<string, unknown>): Promise<void> {
+    const token = await this.getAccessToken();
+    await fetch(`${this.config.apiBase}/open-apis/im/v1/messages?receive_id_type=chat_id`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${token}`,
+      },
+      body: JSON.stringify({
+        receive_id: chatId,
+        msg_type: 'interactive',
+        content: JSON.stringify(card),
+      }),
+    });
+  }
+}

package/src/channels/web.ts

@@ -62,52 +62,127 @@ const CHAT_HTML = `<!DOCTYPE html>
 <html lang="en">
 <head>
 <meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
 <title>OPC Agent</title>
 <style>
+:root{--bg:#0a0a0f;--surface:#12121a;--border:#1e1e2e;--text:#e0e0e0;--text-dim:#888;--accent:#818cf8;--accent-hover:#6366f1;--user-bg:#2563eb;--user-hover:#1d4ed8;--error-bg:#7f1d1d;--error-text:#fca5a5;--success:#22c55e;--radius:12px}
 *{margin:0;padding:0;box-sizing:border-box}
-body{background:#0a0a0f;color:#e0e0e0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;height:100vh;display:flex;flex-direction:column}
-header{background:#12121a;padding:16px 24px;border-bottom:1px solid #1e1e2e;display:flex;align-items:center;gap:12px}
-header h1{font-size:18px;font-weight:600;color:#fff}
-header .dot{width:8px;height:8px;border-radius:50%;background:#22c55e;animation:pulse 2s infinite}
-@keyframes pulse{0%,100%{opacity:1}50%{opacity:.4}}
-#messages{flex:1;overflow-y:auto;padding:24px;display:flex;flex-direction:column;gap:16px}
-.msg{max-width:720px;padding:12px 16px;border-radius:12px;line-height:1.6;font-size:14px;white-space:pre-wrap;word-break:break-word}
-.msg.user{align-self:flex-end;background:#2563eb;color:#fff;border-bottom-right-radius:4px}
-.msg.assistant{align-self:flex-start;background:#1e1e2e;color:#d4d4d8;border-bottom-left-radius:4px}
-.msg.assistant .cursor{display:inline-block;width:2px;height:14px;background:#818cf8;animation:blink .6s infinite;vertical-align:text-bottom;margin-left:2px}
+body{background:var(--bg);color:var(--text);font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',sans-serif;height:100vh;height:100dvh;display:flex;flex-direction:column;overflow:hidden}
+header{background:var(--surface);padding:14px 20px;border-bottom:1px solid var(--border);display:flex;align-items:center;gap:12px;flex-shrink:0;backdrop-filter:blur(12px)}
+header .avatar{width:36px;height:36px;border-radius:50%;background:linear-gradient(135deg,var(--accent),#6366f1);display:flex;align-items:center;justify-content:center;font-size:16px;flex-shrink:0}
+header .info{flex:1;min-width:0}
+header h1{font-size:16px;font-weight:600;color:#fff;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+header .status{font-size:12px;color:var(--success);display:flex;align-items:center;gap:4px}
+header .status .dot{width:6px;height:6px;border-radius:50%;background:var(--success);animation:pulse 2s infinite}
+nav.header-nav{display:flex;gap:4px}
+nav.header-nav a{color:var(--text-dim);text-decoration:none;font-size:12px;padding:4px 10px;border-radius:6px;transition:all .2s}
+nav.header-nav a:hover{color:#fff;background:rgba(255,255,255,.06)}
+@keyframes pulse{0%,100%{opacity:1}50%{opacity:.3}}
+@keyframes fadeIn{from{opacity:0;transform:translateY(8px)}to{opacity:1;transform:translateY(0)}}
+@keyframes slideIn{from{opacity:0;transform:scale(.96)}to{opacity:1;transform:scale(1)}}
+#messages{flex:1;overflow-y:auto;padding:20px;display:flex;flex-direction:column;gap:12px;scroll-behavior:smooth}
+#messages::-webkit-scrollbar{width:4px}
+#messages::-webkit-scrollbar-track{background:transparent}
+#messages::-webkit-scrollbar-thumb{background:var(--border);border-radius:4px}
+.msg-wrap{display:flex;flex-direction:column;animation:fadeIn .3s ease-out}
+.msg-wrap.user{align-items:flex-end}
+.msg-wrap.assistant{align-items:flex-start}
+.msg{max-width:min(720px,85%);padding:10px 14px;border-radius:var(--radius);line-height:1.7;font-size:14px;word-break:break-word;position:relative;transition:all .2s}
+.msg.user{background:var(--user-bg);color:#fff;border-bottom-right-radius:4px}
+.msg.assistant{background:var(--surface);color:var(--text);border:1px solid var(--border);border-bottom-left-radius:4px}
+.msg.error{background:var(--error-bg);color:var(--error-text);border:1px solid rgba(239,68,68,.3)}
+.msg pre{background:rgba(0,0,0,.4);padding:12px;border-radius:8px;overflow-x:auto;margin:8px 0;font-size:13px;font-family:'JetBrains Mono','Fira Code','Cascadia Code',monospace;line-height:1.5}
+.msg code{font-family:'JetBrains Mono','Fira Code','Cascadia Code',monospace;font-size:13px;background:rgba(0,0,0,.3);padding:1px 5px;border-radius:4px}
+.msg pre code{background:none;padding:0}
+.msg .cursor{display:inline-block;width:2px;height:14px;background:var(--accent);animation:blink .6s infinite;vertical-align:text-bottom;margin-left:2px}
 @keyframes blink{0%,100%{opacity:1}50%{opacity:0}}
-.msg.error{background:#7f1d1d;color:#fca5a5}
-#input-area{background:#12121a;padding:16px 24px;border-top:1px solid #1e1e2e;display:flex;gap:12px}
-#input{flex:1;background:#1e1e2e;border:1px solid #2e2e3e;border-radius:10px;padding:12px 16px;color:#fff;font-size:14px;outline:none;resize:none;max-height:120px;font-family:inherit}
-#input:focus{border-color:#818cf8}
-#send{background:#2563eb;color:#fff;border:none;border-radius:10px;padding:12px 20px;font-size:14px;cursor:pointer;font-weight:500;transition:background .2s}
-#send:hover{background:#1d4ed8}
-#send:disabled{background:#334155;cursor:not-allowed}
+.typing{display:flex;gap:4px;padding:12px 16px;align-items:center}
+.typing span{width:6px;height:6px;border-radius:50%;background:var(--text-dim);animation:typingDot 1.4s infinite}
+.typing span:nth-child(2){animation-delay:.2s}
+.typing span:nth-child(3){animation-delay:.4s}
+@keyframes typingDot{0%,60%,100%{opacity:.3;transform:scale(.8)}30%{opacity:1;transform:scale(1)}}
+.reactions{display:flex;gap:4px;margin-top:4px}
+.reactions button{background:rgba(255,255,255,.06);border:1px solid transparent;border-radius:16px;padding:2px 8px;font-size:13px;cursor:pointer;transition:all .15s;color:var(--text-dim)}
+.reactions button:hover{background:rgba(255,255,255,.12);border-color:var(--border)}
+.reactions button.active{background:rgba(99,102,241,.2);border-color:var(--accent);color:var(--accent)}
+.msg-time{font-size:11px;color:var(--text-dim);margin-top:2px;opacity:0;transition:opacity .2s}
+.msg-wrap:hover .msg-time{opacity:1}
+.attachment{display:flex;align-items:center;gap:8px;background:rgba(0,0,0,.3);padding:8px 12px;border-radius:8px;margin-top:6px;font-size:13px}
+.attachment .icon{font-size:18px}
+#input-area{background:var(--surface);padding:12px 20px 16px;border-top:1px solid var(--border);display:flex;gap:10px;align-items:flex-end;flex-shrink:0}
+#input{flex:1;background:var(--bg);border:1px solid var(--border);border-radius:var(--radius);padding:10px 14px;color:#fff;font-size:14px;outline:none;resize:none;max-height:150px;min-height:42px;font-family:inherit;line-height:1.5;transition:border-color .2s}
+#input:focus{border-color:var(--accent)}
+#input::placeholder{color:var(--text-dim)}
+#send{background:var(--user-bg);color:#fff;border:none;border-radius:var(--radius);width:42px;height:42px;font-size:18px;cursor:pointer;transition:all .2s;display:flex;align-items:center;justify-content:center;flex-shrink:0}
+#send:hover{background:var(--user-hover);transform:scale(1.05)}
+#send:disabled{background:#334155;cursor:not-allowed;transform:none}
+.empty-state{flex:1;display:flex;flex-direction:column;align-items:center;justify-content:center;color:var(--text-dim);gap:12px;padding:40px;text-align:center}
+.empty-state .logo{font-size:48px;opacity:.6}
+.empty-state h2{color:var(--text);font-size:20px;font-weight:500}
+.empty-state p{font-size:14px;max-width:400px;line-height:1.6}
+@media(max-width:640px){
+  header{padding:10px 14px}
+  #messages{padding:12px}
+  #input-area{padding:10px 14px 14px}
+  .msg{max-width:90%;font-size:14px}
+  nav.header-nav{display:none}
+}
 </style>
 </head>
 <body>
-<header><div class="dot"></div><h1 id="title">OPC Agent</h1></header>
-<div id="messages"></div>
+<header>
+<div class="avatar" id="avatar">🤖</div>
+<div class="info"><h1 id="title">OPC Agent</h1><div class="status"><span class="dot"></span>Online</div></div>
+<nav class="header-nav"><a href="/dashboard">Dashboard</a><a href="/templates">Templates</a></nav>
+</header>
+<div id="messages">
+<div class="empty-state" id="empty"><div class="logo">💬</div><h2>Start a conversation</h2><p>Type a message below to chat with your AI agent.</p></div>
+</div>
 <div id="input-area">
-<textarea id="input" rows="1" placeholder="Type a message..." autocomplete="off"></textarea>
-<button id="send">Send</button>
+<textarea id="input" rows="1" placeholder="Type a message…" autocomplete="off"></textarea>
+<button id="send" aria-label="Send">↑</button>
 </div>
 <script>
-const msgs=document.getElementById('messages'),input=document.getElementById('input'),btn=document.getElementById('send');
+const msgs=document.getElementById('messages'),input=document.getElementById('input'),btn=document.getElementById('send'),empty=document.getElementById('empty');
 let sessionId=crypto.randomUUID(),sending=false;
 
-function addMsg(role,text){
+function esc(s){const d=document.createElement('div');d.textContent=s;return d.innerHTML}
+function fmtTime(){return new Date().toLocaleTimeString([],{hour:'2-digit',minute:'2-digit'})}
+function renderMd(text){
+  let h=esc(text);
+  h=h.replace(/\`\`\`(\\w*)\\n([\\s\\S]*?)\`\`\`/g,'<pre><code>$2</code></pre>');
+  h=h.replace(/\`([^\`]+)\`/g,'<code>$1</code>');
+  h=h.replace(/\\*\\*(.+?)\\*\\*/g,'<strong>$1</strong>');
+  h=h.replace(/\\n/g,'<br>');
+  return h;
+}
+
+function addMsg(role,text,opts){
+  if(empty)empty.remove();
+  const wrap=document.createElement('div');
+  wrap.className='msg-wrap '+role;
   const d=document.createElement('div');
   d.className='msg '+role;
-  d.textContent=text;
-  msgs.appendChild(d);
+  if(opts?.html)d.innerHTML=text;else if(role==='assistant'&&text)d.innerHTML=renderMd(text);else d.textContent=text;
+  wrap.appendChild(d);
+  const time=document.createElement('div');
+  time.className='msg-time';
+  time.textContent=fmtTime();
+  wrap.appendChild(time);
+  if(role==='assistant'&&text){
+    const rx=document.createElement('div');rx.className='reactions';
+    rx.innerHTML='<button data-r="👍" onclick="react(this)">👍</button><button data-r="👎" onclick="react(this)">👎</button>';
+    wrap.appendChild(rx);
+  }
+  msgs.appendChild(wrap);
   msgs.scrollTop=msgs.scrollHeight;
   return d;
 }
 
+window.react=function(el){el.classList.toggle('active')};
+
 input.addEventListener('keydown',e=>{if(e.key==='Enter'&&!e.shiftKey){e.preventDefault();send()}});
-input.addEventListener('input',()=>{input.style.height='auto';input.style.height=Math.min(input.scrollHeight,120)+'px'});
+input.addEventListener('input',()=>{input.style.height='auto';input.style.height=Math.min(input.scrollHeight,150)+'px'});
 btn.addEventListener('click',send);
 
 async function send(){
@@ -116,8 +191,13 @@ async function send(){
   sending=true;btn.disabled=true;
   input.value='';input.style.height='auto';
   addMsg('user',text);
-  const el=addMsg('assistant','');
-  el.innerHTML='<span class="cursor"></span>';
+  const wrap=document.createElement('div');wrap.className='msg-wrap assistant';
+  const d=document.createElement('div');d.className='msg assistant';
+  d.innerHTML='<div class="typing"><span></span><span></span><span></span></div>';
+  wrap.appendChild(d);
+  const time=document.createElement('div');time.className='msg-time';time.textContent=fmtTime();
+  wrap.appendChild(time);
+  msgs.appendChild(wrap);msgs.scrollTop=msgs.scrollHeight;
   try{
     const res=await fetch('/api/chat',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({message:text,sessionId})});
     if(!res.ok)throw new Error('HTTP '+res.status);
@@ -130,21 +210,20 @@ async function send(){
       const lines=chunk.split('\\n');
       for(const line of lines){
         if(!line.startsWith('data: '))continue;
-        const d=line.slice(6);
-        if(d==='[DONE]')continue;
-        try{const j=JSON.parse(d);if(j.content)full+=j.content;if(j.error)full='Error: '+j.error;}catch{}
+        const dd=line.slice(6);if(dd==='[DONE]')continue;
+        try{const j=JSON.parse(dd);if(j.content)full+=j.content;if(j.error)full='Error: '+j.error;}catch{}
       }
-      el.textContent=full;
+      d.innerHTML=renderMd(full)+'<span class="cursor"></span>';
       msgs.scrollTop=msgs.scrollHeight;
     }
-    if(!full)el.textContent='(empty response)';
-  }catch(e){
-    el.className='msg error';el.textContent='Error: '+e.message;
-  }
+    if(!full){d.textContent='(empty response)';}else{d.innerHTML=renderMd(full);}
+    const rx=document.createElement('div');rx.className='reactions';
+    rx.innerHTML='<button data-r="👍" onclick="react(this)">👍</button><button data-r="👎" onclick="react(this)">👎</button>';
+    wrap.appendChild(rx);
+  }catch(e){d.className='msg error';d.textContent='Error: '+e.message;}
   sending=false;btn.disabled=false;input.focus();
 }
 
-// Fetch agent info
 fetch('/api/info').then(r=>r.json()).then(d=>{if(d.name)document.getElementById('title').textContent=d.name}).catch(()=>{});
 </script>
 </body>
@@ -379,7 +458,7 @@ export class WebChannel extends BaseChannel {
         timestamp: Date.now(),
         uptime: uptimeMs,
         uptimeHuman: `${Math.floor(uptimeMs / 3600000)}h ${Math.floor((uptimeMs % 3600000) / 60000)}m`,
-        version: '0.7.0',
+        version: '1.0.0',
         agent: this.agentName,
         stats: {
           sessions: this.stats.sessions,

package/src/cli.ts

@@ -29,6 +29,8 @@ import { createProvider } from './providers';
 import { KnowledgeBase } from './core/knowledge';
 import { publishAgent, installAgent } from './marketplace';
 
+import { PluginManager, createLoggingPlugin, createAnalyticsPlugin, createRateLimitPlugin } from './plugins';
+
 const program = new Command();
 
 const color = {
@@ -92,7 +94,7 @@ async function select(question: string, options: { value: string; label: string
 program
   .name('opc')
   .description('OPC Agent - Open Agent Framework for business workstations')
-  .version('0.9.0');
+  .version('1.0.0');
 
 // ── Init command ─────────────────────────────────────────────
 
@@ -800,4 +802,109 @@ program
     }
   });
 
+// 🔌 Plugin commands ────────────────────────────────────────
+
+const pluginCmd = program.command('plugin').description('Manage plugins');
+pluginCmd.command('list')
+  .description('List available built-in plugins')
+  .action(() => {
+    const builtIn = [
+      { name: 'logging', description: 'Logs all messages and responses' },
+      { name: 'analytics', description: 'Tracks message counts and error rates' },
+      { name: 'rate-limit', description: 'Per-user rate limiting' },
+    ];
+    console.log(`\n${icon.gear} ${color.bold('Available Plugins')}\n`);
+    for (const p of builtIn) {
+      console.log(`  ${color.cyan(p.name.padEnd(16))} ${p.description}`);
+    }
+    console.log(`\n  Add to oad.yaml: ${color.dim('plugins: [{ name: "logging" }]')}\n`);
+  });
+
+pluginCmd.command('add')
+  .argument('<name>', 'Plugin name')
+  .option('-f, --file <file>', 'OAD file', 'oad.yaml')
+  .description('Add a plugin to your agent configuration')
+  .action((name: string, opts: { file: string }) => {
+    const validPlugins = ['logging', 'analytics', 'rate-limit'];
+    if (!validPlugins.includes(name)) {
+      console.error(`${icon.error} Unknown plugin: ${color.bold(name)}. Available: ${validPlugins.join(', ')}`);
+      process.exit(1);
+    }
+    try {
+      const raw = fs.readFileSync(opts.file, 'utf-8');
+      const config = yaml.load(raw) as any;
+      if (!config.spec.plugins) config.spec.plugins = [];
+      if (config.spec.plugins.some((p: any) => p.name === name)) {
+        console.log(`${icon.info} Plugin "${name}" already in config.`);
+        return;
+      }
+      config.spec.plugins.push({ name });
+      fs.writeFileSync(opts.file, yaml.dump(config, { lineWidth: 120 }));
+      console.log(`${icon.success} Added plugin "${color.cyan(name)}" to ${opts.file}`);
+    } catch (err) {
+      console.error(`${icon.error} Failed:`, err instanceof Error ? err.message : err);
+      process.exit(1);
+    }
+  });
+
+// 🔄 Migrate command ────────────────────────────────────────
+
+program
+  .command('migrate')
+  .description('Migrate OAD to latest schema version')
+  .option('-f, --file <file>', 'OAD file', 'oad.yaml')
+  .option('--dry-run', 'Show changes without writing')
+  .action(async (opts: { file: string; dryRun?: boolean }) => {
+    try {
+      const raw = fs.readFileSync(opts.file, 'utf-8');
+      const config = yaml.load(raw) as any;
+      let changed = false;
+
+      // Migration: add apiVersion if missing
+      if (!config.apiVersion) { config.apiVersion = 'opc/v1'; changed = true; }
+      // Migration: add kind if missing
+      if (!config.kind) { config.kind = 'Agent'; changed = true; }
+      // Migration: ensure metadata.version
+      if (!config.metadata?.version) {
+        if (!config.metadata) config.metadata = {};
+        config.metadata.version = '1.0.0';
+        changed = true;
+      }
+      // Migration: ensure spec.channels is array
+      if (config.spec?.channels && !Array.isArray(config.spec.channels)) {
+        config.spec.channels = [config.spec.channels];
+        changed = true;
+      }
+      // Migration: ensure spec.skills is array
+      if (config.spec?.skills && !Array.isArray(config.spec.skills)) {
+        config.spec.skills = [config.spec.skills];
+        changed = true;
+      }
+      // Migration: old model format
+      if (config.spec?.llm?.model && !config.spec?.model) {
+        config.spec.model = config.spec.llm.model;
+        delete config.spec.llm;
+        changed = true;
+      }
+
+      if (!changed) {
+        console.log(`${icon.success} OAD is already up to date.`);
+        return;
+      }
+
+      if (opts.dryRun) {
+        console.log(`\n${icon.info} Would migrate:\n`);
+        console.log(yaml.dump(config, { lineWidth: 120 }));
+      } else {
+        // Backup
+        fs.writeFileSync(opts.file + '.bak', raw);
+        fs.writeFileSync(opts.file, yaml.dump(config, { lineWidth: 120 }));
+        console.log(`${icon.success} Migrated ${color.bold(opts.file)} (backup: ${opts.file}.bak)`);
+      }
+    } catch (err) {
+      console.error(`${icon.error} Migration failed:`, err instanceof Error ? err.message : err);
+      process.exit(1);
+    }
+  });
+
 program.parse();