opc-agent 0.4.0 → 0.5.0

package/README.md

@@ -42,6 +42,25 @@ opc run
 | `knowledge-base` | RAG with DeepBrain semantic search |
 | `code-reviewer` | Bug detection + style checking |
 
+## 🚀 Deploy to OpenClaw
+
+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
+
+# Or deploy AND auto-register in OpenClaw
+opc deploy --target openclaw --install
+
+# Then restart OpenClaw to pick it up
+openclaw gateway restart
+```
+
+This generates `IDENTITY.md`, `SOUL.md`, `AGENTS.md`, `USER.md`, and `MEMORY.md` — everything OpenClaw needs to run your agent.
+
+See [`examples/customer-service-demo/`](examples/customer-service-demo/) for a complete walkthrough.
+
 ## CLI Commands
 
 | Command | Description |
@@ -53,6 +72,7 @@ opc run
 | `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) |
 

package/dist/cli.js

@@ -52,6 +52,7 @@ const financial_advisor_1 = require("./templates/financial-advisor");
 const executive_assistant_1 = require("./templates/executive-assistant");
 const customer_service_2 = require("./templates/customer-service");
 const analytics_1 = require("./analytics");
+const openclaw_1 = require("./deploy/openclaw");
 const workflow_1 = require("./core/workflow");
 const versioning_1 = require("./core/versioning");
 const program = new commander_1.Command();
@@ -109,7 +110,7 @@ async function select(question, options) {
 program
     .name('opc')
     .description('OPC Agent - Open Agent Framework for business workstations')
-    .version('0.4.0');
+    .version('0.5.0');
 program
     .command('init')
     .description('Initialize a new OPC agent project (interactive)')
@@ -332,6 +333,53 @@ program
     console.log(`   Browse templates with: ${color.cyan('opc init --template <name>')}`);
     console.log(`\n   Available templates: ${Object.keys(TEMPLATES).map(t => color.cyan(t)).join(', ')}\n`);
 });
+// ── Deploy command ────────────────────────────────────────────
+program
+    .command('deploy')
+    .description('Deploy agent to a target runtime')
+    .option('-f, --file <file>', 'OAD file', 'oad.yaml')
+    .option('-t, --target <target>', 'Deploy target', 'openclaw')
+    .option('-o, --output <dir>', 'Output directory')
+    .option('--install', 'Also register in OpenClaw config')
+    .action(async (opts) => {
+    if (opts.target !== 'openclaw') {
+        console.error(`${icon.error} Unknown target: ${color.bold(opts.target)}. Supported: openclaw`);
+        process.exit(1);
+    }
+    try {
+        const runtime = new runtime_1.AgentRuntime();
+        const config = await runtime.loadConfig(opts.file);
+        const agentId = config.metadata.name.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+        const defaultOutput = path.join(homeDir, '.openclaw', 'agents', agentId, 'workspace');
+        const outputDir = path.resolve(opts.output ?? defaultOutput);
+        console.log(`\n${icon.rocket} ${color.bold('Deploy to OpenClaw')}\n`);
+        console.log(`  Agent:  ${color.cyan(config.metadata.name)} v${config.metadata.version}`);
+        console.log(`  Target: ${color.cyan('OpenClaw')}`);
+        console.log(`  Output: ${color.dim(outputDir)}`);
+        const result = (0, openclaw_1.deployToOpenClaw)({ oad: config, outputDir, install: opts.install });
+        console.log(`\n${icon.success} Generated ${result.files.length} files:`);
+        for (const f of result.files) {
+            console.log(`   ${icon.file} ${f}`);
+        }
+        if (result.installed) {
+            console.log(`\n${icon.success} Registered in OpenClaw config: ${color.dim(result.configPath)}`);
+            console.log(`\n${color.dim('Next:')} Restart OpenClaw gateway to pick up the new agent.`);
+            console.log(`   ${color.cyan('openclaw gateway restart')}\n`);
+        }
+        else if (opts.install) {
+            console.log(`\n${icon.warn} Could not auto-register. Add the agent manually to openclaw.json.`);
+        }
+        else {
+            console.log(`\n${color.dim('Next:')} Copy the output to your OpenClaw agents directory, or re-run with ${color.cyan('--install')}`);
+            console.log(`   ${color.cyan(`opc deploy --target openclaw --install`)}\n`);
+        }
+    }
+    catch (err) {
+        console.error(`${icon.error} Deploy failed:`, err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
 // ── Tool commands ────────────────────────────────────────────
 const toolCmd = program.command('tool').description('Manage MCP tools');
 toolCmd

package/dist/deploy/openclaw.d.ts

@@ -0,0 +1,14 @@
+import type { OADDocument } from '../schema/oad';
+export interface DeployOptions {
+    oad: OADDocument;
+    outputDir: string;
+    install?: boolean;
+}
+export interface DeployResult {
+    outputDir: string;
+    files: string[];
+    installed: boolean;
+    configPath?: string;
+}
+export declare function deployToOpenClaw(options: DeployOptions): DeployResult;
+//# sourceMappingURL=openclaw.d.ts.map

package/dist/deploy/openclaw.js

@@ -0,0 +1,208 @@
+"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.deployToOpenClaw = deployToOpenClaw;
+/**
+ * OpenClaw Deployer - Convert OAD → OpenClaw agent workspace
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function generateIdentityMd(oad) {
+    const m = oad.metadata;
+    return `# IDENTITY.md
+
+- **Name:** ${m.name}
+- **Version:** ${m.version}
+- **Description:** ${m.description ?? 'An AI agent'}
+- **Author:** ${m.author ?? 'Unknown'}
+- **License:** ${m.license}
+`;
+}
+function generateSoulMd(oad) {
+    const prompt = oad.spec.systemPrompt ?? 'You are a helpful AI assistant.';
+    return `# SOUL.md - ${oad.metadata.name}
+
+## System Prompt
+
+${prompt}
+
+## Model Configuration
+
+- **Model:** ${oad.spec.model}
+- **Provider:** ${oad.spec.provider?.default ?? 'deepseek'}
+`;
+}
+function generateAgentsMd(oad) {
+    const skills = oad.spec.skills;
+    const memory = oad.spec.memory;
+    const dtv = oad.spec.dtv;
+    let md = `# AGENTS.md - ${oad.metadata.name}\n\n`;
+    // Skills
+    md += `## Skills\n\n`;
+    if (skills.length === 0) {
+        md += `No skills configured.\n\n`;
+    }
+    else {
+        for (const sk of skills) {
+            md += `### ${sk.name}\n`;
+            if (sk.description)
+                md += `${sk.description}\n`;
+            if (sk.config)
+                md += `\nConfig:\n\`\`\`json\n${JSON.stringify(sk.config, null, 2)}\n\`\`\`\n`;
+            md += `\n`;
+        }
+    }
+    // Memory
+    md += `## Memory\n\n`;
+    if (memory) {
+        md += `- Short-term: ${memory.shortTerm ? 'enabled' : 'disabled'}\n`;
+        const lt = memory.longTerm;
+        if (typeof lt === 'object' && lt) {
+            md += `- Long-term: ${lt.provider} (collection: ${lt.collection ?? 'default'})\n`;
+        }
+        else {
+            md += `- Long-term: ${lt ? 'enabled' : 'disabled'}\n`;
+        }
+    }
+    else {
+        md += `Default memory settings.\n`;
+    }
+    md += `\n`;
+    // DTV
+    if (dtv) {
+        md += `## Trust & Value\n\n`;
+        md += `- Trust Level: ${dtv.trust?.level ?? 'sandbox'}\n`;
+        if (dtv.value?.metrics?.length) {
+            md += `- Metrics: ${dtv.value.metrics.join(', ')}\n`;
+        }
+        md += `\n`;
+    }
+    return md;
+}
+function generateUserMd(oad) {
+    return `# USER.md
+
+- **Name:** (your name)
+- **Role:** User
+- **Notes:** Configure this file with your preferences for ${oad.metadata.name}.
+`;
+}
+function generateMemoryMd(oad) {
+    return `# MEMORY.md - ${oad.metadata.name}
+
+## Persistent Knowledge
+
+(Agent will store learned information here)
+
+## User Preferences
+
+(Discovered user preferences will be noted here)
+`;
+}
+function generateOpenClawConfig(oad, agentDir) {
+    const channels = oad.spec.channels;
+    const channelConfig = {};
+    for (const ch of channels) {
+        if (ch.type === 'telegram') {
+            channelConfig.telegram = {
+                enabled: true,
+                note: 'Configure bot token in OpenClaw gateway settings',
+            };
+        }
+        else if (ch.type === 'web' || ch.type === 'websocket') {
+            channelConfig.web = { enabled: true, port: ch.port ?? 3000 };
+        }
+    }
+    return {
+        name: oad.metadata.name,
+        workspace: agentDir,
+        channels: channelConfig,
+    };
+}
+function deployToOpenClaw(options) {
+    const { oad, outputDir, install } = options;
+    const files = [];
+    // Create output directory
+    fs.mkdirSync(outputDir, { recursive: true });
+    // Generate all workspace files
+    const fileMap = {
+        'IDENTITY.md': generateIdentityMd(oad),
+        'SOUL.md': generateSoulMd(oad),
+        'AGENTS.md': generateAgentsMd(oad),
+        'USER.md': generateUserMd(oad),
+        'MEMORY.md': generateMemoryMd(oad),
+    };
+    for (const [name, content] of Object.entries(fileMap)) {
+        const filePath = path.join(outputDir, name);
+        fs.writeFileSync(filePath, content, 'utf-8');
+        files.push(name);
+    }
+    // Generate suggested channel config
+    const channelSuggestion = generateOpenClawConfig(oad, outputDir);
+    const configNote = path.join(outputDir, 'openclaw-config-suggestion.json');
+    fs.writeFileSync(configNote, JSON.stringify(channelSuggestion, null, 2), 'utf-8');
+    files.push('openclaw-config-suggestion.json');
+    const result = { outputDir, files, installed: false };
+    // Install mode: register in openclaw.json
+    if (install) {
+        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+        const configPath = path.join(homeDir, '.openclaw', 'openclaw.json');
+        if (fs.existsSync(configPath)) {
+            try {
+                const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+                if (!config.agents)
+                    config.agents = {};
+                const agentId = oad.metadata.name.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+                config.agents[agentId] = {
+                    workspace: outputDir,
+                    description: oad.metadata.description ?? '',
+                };
+                fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+                result.installed = true;
+                result.configPath = configPath;
+            }
+            catch (err) {
+                // Config exists but couldn't be updated - not fatal
+                console.error(`Warning: Could not update ${configPath}:`, err);
+            }
+        }
+        else {
+            console.error(`Warning: OpenClaw config not found at ${configPath}`);
+            console.error(`Run 'openclaw init' first, then re-run with --install`);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=openclaw.js.map

package/examples/customer-service-demo/README.md

@@ -0,0 +1,90 @@
+# ShopBot — Customer Service Demo
+
+A complete e-commerce customer service agent built with OPC Agent, deployable to OpenClaw.
+
+## What's Inside
+
+- `oad.yaml` — Full agent definition with product FAQ, order tracking, complaint handling
+- Rich system prompt with personality, escalation rules, and response templates
+- Telegram + Web channel configuration
+
+## Quick Start
+
+### 1. Install OPC Agent
+
+```bash
+npm install -g opc-agent
+```
+
+### 2. Validate the Agent
+
+```bash
+cd examples/customer-service-demo
+opc info
+opc build
+```
+
+### 3. Deploy to OpenClaw
+
+**Option A: Generate workspace files**
+```bash
+opc deploy --target openclaw --output ./shopbot-workspace
+```
+
+This creates a complete OpenClaw agent workspace with:
+- `IDENTITY.md` — Agent identity
+- `SOUL.md` — System prompt and model config
+- `AGENTS.md` — Skills, memory, and trust config
+- `USER.md` — User preferences template
+- `MEMORY.md` — Persistent memory template
+
+**Option B: Deploy and auto-register**
+```bash
+opc deploy --target openclaw --install
+```
+
+This generates the workspace AND registers the agent in `~/.openclaw/openclaw.json`.
+
+### 4. Restart OpenClaw
+
+```bash
+openclaw gateway restart
+```
+
+### 5. Test in Telegram
+
+Send a message to your OpenClaw Telegram bot. ShopBot will respond!
+
+Try these:
+- "What headphones do you sell?"
+- "Track my order TS-123456"
+- "I want to return my laptop stand"
+- "This is unacceptable, I want to speak to a manager"
+
+## Architecture
+
+```
+OPC Agent (Development)          OpenClaw (Runtime)
+┌─────────────────────┐         ┌──────────────────────┐
+│  oad.yaml           │         │  IDENTITY.md         │
+│  (agent definition) │──deploy─│  SOUL.md             │
+│                     │         │  AGENTS.md           │
+│  opc build/test     │         │  USER.md             │
+│  opc deploy         │         │  MEMORY.md           │
+└─────────────────────┘         │                      │
+                                │  ← Telegram/Web →    │
+                                └──────────────────────┘
+```
+
+OPC Agent is the **development framework**. OpenClaw is the **runtime**.
+
+## Customization
+
+Edit `oad.yaml` to:
+- Change the product catalog
+- Adjust escalation rules
+- Add new skills
+- Switch LLM provider/model
+- Modify the system prompt personality
+
+Then re-deploy: `opc deploy --target openclaw --install`

package/examples/customer-service-demo/oad.yaml

@@ -0,0 +1,107 @@
+apiVersion: opc/v1
+kind: Agent
+metadata:
+  name: ShopBot
+  version: "1.0.0"
+  description: "E-commerce customer service agent for TechStyle — handles product FAQs, order tracking, returns, and complaint escalation"
+  author: "TechStyle Inc."
+  license: Apache-2.0
+  marketplace:
+    category: customer-service
+    pricing: free
+    tags: [ecommerce, support, faq, orders]
+
+spec:
+  provider:
+    default: deepseek
+    allowed: [openai, deepseek, qwen]
+  model: deepseek-chat
+
+  systemPrompt: |
+    You are ShopBot, the friendly and professional customer service agent for TechStyle, 
+    an online electronics and lifestyle store.
+
+    ## Personality
+    - Warm, helpful, and patient
+    - Professional but not robotic — use a conversational tone
+    - Proactive: anticipate follow-up questions
+    - Empathetic: acknowledge customer frustration before solving problems
+
+    ## Core Capabilities
+    1. **Product FAQ**: Answer questions about products, specs, pricing, availability
+    2. **Order Tracking**: Look up order status by order ID (format: TS-XXXXXX)
+    3. **Returns & Refunds**: Guide customers through return process (30-day policy)
+    4. **Complaint Handling**: De-escalate issues, offer solutions, escalate when needed
+
+    ## Escalation Rules
+    - Escalate to human agent if:
+      - Customer asks 3+ times about the same unresolved issue
+      - Customer explicitly requests a human
+      - Issue involves billing disputes over $100
+      - Customer uses abusive language (remain calm, offer to transfer)
+    - Say: "Let me connect you with a specialist who can help further."
+
+    ## Response Guidelines
+    - Keep responses under 200 words unless detailed explanation is needed
+    - Always confirm understanding: "Just to make sure I understand..."
+    - End with a follow-up: "Is there anything else I can help with?"
+    - For order lookups, ask for order ID if not provided
+    - Never make up order status — if you can't find it, say so
+
+    ## Product Catalog (Quick Reference)
+    - TechStyle Pro Headphones — $149, wireless, ANC, 30hr battery
+    - TechStyle Slim Laptop Stand — $59, aluminum, adjustable
+    - TechStyle Power Bank 20K — $39, 20000mAh, USB-C PD
+    - TechStyle Smart Watch S3 — $199, health tracking, 5-day battery
+    - TechStyle Webcam 4K — $89, autofocus, built-in mic
+
+    ## Return Policy
+    - 30-day return window from delivery date
+    - Item must be in original packaging
+    - Free return shipping for defective items
+    - Refund processed within 5-7 business days
+    - Gift cards and sale items are final sale
+
+  skills:
+    - name: product-faq
+      description: "Answer product questions from the catalog knowledge base"
+      config:
+        source: catalog
+        fallback: "I don't have that info right now. Let me check with the team."
+
+    - name: order-lookup
+      description: "Look up order status by order ID"
+      config:
+        idPattern: "TS-\\d{6}"
+        notFoundMessage: "I couldn't find that order. Double-check the ID (format: TS-XXXXXX)."
+
+    - name: complaint-handler
+      description: "Handle complaints with empathy and escalation logic"
+      config:
+        maxAttempts: 3
+        escalationMessage: "Let me connect you with a specialist who can help further."
+
+  channels:
+    - type: telegram
+      config:
+        welcomeMessage: "Hi! 👋 I'm ShopBot from TechStyle. How can I help you today?"
+    - type: web
+      port: 3000
+
+  memory:
+    shortTerm: true
+    longTerm: false
+
+  dtv:
+    trust:
+      level: verified
+    value:
+      metrics:
+        - response_time
+        - resolution_rate
+        - customer_satisfaction
+
+  streaming:
+    enabled: true
+
+  locale: en

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opc-agent",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Open Agent Framework — Build, test, and run AI Agents for business workstations",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",