opc-agent 0.3.0 → 0.5.0

package/src/core/workflow.ts

@@ -0,0 +1,235 @@
+import { EventEmitter } from 'events';
+import type { Message, AgentContext, ISkill, IAgent } from './types';
+import { Logger } from './logger';
+
+// ── Workflow Types ──────────────────────────────────────────
+
+export type StepType = 'skill' | 'tool' | 'agent' | 'condition' | 'parallel';
+
+export interface WorkflowStep {
+  id: string;
+  type: StepType;
+  name: string;
+  config?: Record<string, unknown>;
+  /** For condition steps */
+  condition?: string;
+  branches?: { if: WorkflowStep[]; else?: WorkflowStep[] };
+  /** For parallel steps */
+  parallel?: WorkflowStep[];
+  /** Timeout in ms */
+  timeout?: number;
+  /** Retry count */
+  retries?: number;
+}
+
+export interface WorkflowDefinition {
+  name: string;
+  description?: string;
+  version?: string;
+  steps: WorkflowStep[];
+  onError?: 'stop' | 'skip' | 'retry';
+}
+
+export interface StepResult {
+  stepId: string;
+  status: 'success' | 'skipped' | 'error';
+  output?: string;
+  error?: string;
+  durationMs: number;
+}
+
+export interface WorkflowResult {
+  workflow: string;
+  status: 'completed' | 'failed' | 'partial';
+  steps: StepResult[];
+  totalDurationMs: number;
+}
+
+// ── Workflow Engine ─────────────────────────────────────────
+
+export class WorkflowEngine extends EventEmitter {
+  private workflows: Map<string, WorkflowDefinition> = new Map();
+  private skills: Map<string, ISkill> = new Map();
+  private agents: Map<string, IAgent> = new Map();
+  private logger = new Logger('workflow');
+
+  registerWorkflow(workflow: WorkflowDefinition): void {
+    this.workflows.set(workflow.name, workflow);
+    this.logger.info('Workflow registered', { name: workflow.name, steps: workflow.steps.length });
+  }
+
+  unregisterWorkflow(name: string): void {
+    this.workflows.delete(name);
+  }
+
+  getWorkflow(name: string): WorkflowDefinition | undefined {
+    return this.workflows.get(name);
+  }
+
+  listWorkflows(): WorkflowDefinition[] {
+    return Array.from(this.workflows.values());
+  }
+
+  registerSkill(skill: ISkill): void {
+    this.skills.set(skill.name, skill);
+  }
+
+  registerAgent(agent: IAgent): void {
+    this.agents.set(agent.name, agent);
+  }
+
+  async run(name: string, context: AgentContext, input?: string): Promise<WorkflowResult> {
+    const workflow = this.workflows.get(name);
+    if (!workflow) throw new Error(`Workflow "${name}" not found`);
+
+    const startTime = Date.now();
+    const results: StepResult[] = [];
+    let failed = false;
+
+    this.emit('workflow:start', { name, input });
+
+    try {
+      await this.executeSteps(workflow.steps, context, input ?? '', results, workflow.onError ?? 'stop');
+    } catch (err) {
+      failed = true;
+      this.logger.error('Workflow failed', { name, error: (err as Error).message });
+    }
+
+    const result: WorkflowResult = {
+      workflow: name,
+      status: failed ? 'failed' : results.some(r => r.status === 'error') ? 'partial' : 'completed',
+      steps: results,
+      totalDurationMs: Date.now() - startTime,
+    };
+
+    this.emit('workflow:end', result);
+    return result;
+  }
+
+  private async executeSteps(
+    steps: WorkflowStep[],
+    context: AgentContext,
+    input: string,
+    results: StepResult[],
+    onError: string,
+  ): Promise<string> {
+    let currentInput = input;
+
+    for (const step of steps) {
+      const stepStart = Date.now();
+
+      try {
+        if (step.type === 'parallel' && step.parallel) {
+          const parallelResults = await Promise.all(
+            step.parallel.map(s => this.executeSingleStep(s, context, currentInput)),
+          );
+          const combined = parallelResults.map(r => r.output ?? '').join('\n');
+          for (const r of parallelResults) results.push(r);
+          currentInput = combined;
+        } else if (step.type === 'condition' && step.branches) {
+          const conditionMet = this.evaluateCondition(step.condition ?? '', currentInput, context);
+          const branch = conditionMet ? step.branches.if : (step.branches.else ?? []);
+          results.push({
+            stepId: step.id,
+            status: 'success',
+            output: `condition=${conditionMet}`,
+            durationMs: Date.now() - stepStart,
+          });
+          currentInput = await this.executeSteps(branch, context, currentInput, results, onError);
+        } else {
+          const result = await this.executeSingleStep(step, context, currentInput);
+          results.push(result);
+          if (result.status === 'success' && result.output) {
+            currentInput = result.output;
+          }
+          if (result.status === 'error' && onError === 'stop') {
+            throw new Error(`Step "${step.id}" failed: ${result.error}`);
+          }
+        }
+      } catch (err) {
+        if (onError === 'stop') throw err;
+        // skip: continue
+      }
+    }
+
+    return currentInput;
+  }
+
+  private async executeSingleStep(
+    step: WorkflowStep,
+    context: AgentContext,
+    input: string,
+  ): Promise<StepResult> {
+    const startTime = Date.now();
+    let retries = step.retries ?? 0;
+
+    while (true) {
+      try {
+        const output = await this.executeStepAction(step, context, input);
+        return {
+          stepId: step.id,
+          status: 'success',
+          output,
+          durationMs: Date.now() - startTime,
+        };
+      } catch (err) {
+        if (retries > 0) {
+          retries--;
+          continue;
+        }
+        return {
+          stepId: step.id,
+          status: 'error',
+          error: (err as Error).message,
+          durationMs: Date.now() - startTime,
+        };
+      }
+    }
+  }
+
+  private async executeStepAction(step: WorkflowStep, context: AgentContext, input: string): Promise<string> {
+    const message: Message = {
+      id: `wf_${step.id}_${Date.now()}`,
+      role: 'user',
+      content: input,
+      timestamp: Date.now(),
+      metadata: { workflowStep: step.id },
+    };
+
+    switch (step.type) {
+      case 'skill': {
+        const skill = this.skills.get(step.name);
+        if (!skill) throw new Error(`Skill "${step.name}" not found`);
+        const result = await skill.execute(context, message);
+        return result.response ?? '';
+      }
+      case 'agent': {
+        const agent = this.agents.get(step.name);
+        if (!agent) throw new Error(`Agent "${step.name}" not found`);
+        const response = await agent.handleMessage(message);
+        return response.content;
+      }
+      case 'tool': {
+        // Tools are executed via config callback
+        const toolFn = step.config?.handler as ((input: string) => Promise<string>) | undefined;
+        if (toolFn) return await toolFn(input);
+        return `[tool:${step.name}] executed`;
+      }
+      default:
+        return input;
+    }
+  }
+
+  private evaluateCondition(condition: string, input: string, _context: AgentContext): boolean {
+    // Simple condition evaluator: supports "contains:keyword", "length>N", "true", "false"
+    if (condition === 'true') return true;
+    if (condition === 'false') return false;
+    if (condition.startsWith('contains:')) {
+      return input.toLowerCase().includes(condition.slice(9).toLowerCase());
+    }
+    if (condition.startsWith('length>')) {
+      return input.length > parseInt(condition.slice(7), 10);
+    }
+    return !!condition;
+  }
+}

package/src/deploy/openclaw.ts

@@ -0,0 +1,200 @@
+/**
+ * OpenClaw Deployer - Convert OAD → OpenClaw agent workspace
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import type { OADDocument } from '../schema/oad';
+
+export interface DeployOptions {
+  oad: OADDocument;
+  outputDir: string;
+  install?: boolean; // also register in openclaw.json
+}
+
+export interface DeployResult {
+  outputDir: string;
+  files: string[];
+  installed: boolean;
+  configPath?: string;
+}
+
+function generateIdentityMd(oad: OADDocument): string {
+  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: OADDocument): string {
+  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: OADDocument): string {
+  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: OADDocument): string {
+  return `# USER.md
+
+- **Name:** (your name)
+- **Role:** User
+- **Notes:** Configure this file with your preferences for ${oad.metadata.name}.
+`;
+}
+
+function generateMemoryMd(oad: OADDocument): string {
+  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: OADDocument, agentDir: string): Record<string, any> {
+  const channels = oad.spec.channels;
+  const channelConfig: Record<string, any> = {};
+
+  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,
+  };
+}
+
+export function deployToOpenClaw(options: DeployOptions): DeployResult {
+  const { oad, outputDir, install } = options;
+  const files: string[] = [];
+
+  // Create output directory
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  // Generate all workspace files
+  const fileMap: Record<string, string> = {
+    '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: DeployResult = { 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;
+}

package/src/index.ts

@@ -29,6 +29,21 @@ export type { IPlugin, PluginHooks } from './plugins';
 export { Sandbox } from './core/sandbox';
 export type { SandboxConfig, SandboxRestrictions } from './core/sandbox';
 export { Analytics } from './analytics';
+
+// v0.4.0 modules
+export { WorkflowEngine } from './core/workflow';
+export type { WorkflowDefinition, WorkflowStep, WorkflowResult, StepResult } from './core/workflow';
+export { AgentRegistry } from './core/a2a';
+export type { A2ARequest, A2AResponse, AgentCapability, AgentRegistration } from './core/a2a';
+export { HITLManager } from './core/hitl';
+export type { ApprovalRequest, ApprovalResponse, HITLConfig } from './core/hitl';
+export { VoiceChannel } from './channels/voice';
+export type { VoiceChannelConfig, STTProvider, TTSProvider } from './channels/voice';
+export { WebhookChannel } from './channels/webhook';
+export type { WebhookConfig, WebhookPayload } from './channels/webhook';
+export { VersionManager } from './core/versioning';
+export type { VersionEntry, Migration } from './core/versioning';
+export { ConnectionPool, RequestBatcher, LazyLoader } from './core/performance';
 export type { AnalyticsSnapshot } from './analytics';
 export { t, setLocale, getLocale, detectLocale, addMessages } from './i18n';
 export type { Locale } from './i18n';

package/src/schema/oad.ts

@@ -8,8 +8,48 @@ export const SkillRefSchema = z.object({
   config: z.record(z.unknown()).optional(),
 });
 
+export const WorkflowStepSchema: z.ZodType<any> = z.lazy(() => z.object({
+  id: z.string(),
+  type: z.enum(['skill', 'tool', 'agent', 'condition', 'parallel']),
+  name: z.string(),
+  config: z.record(z.unknown()).optional(),
+  condition: z.string().optional(),
+  branches: z.object({ if: z.array(WorkflowStepSchema), else: z.array(WorkflowStepSchema).optional() }).optional(),
+  parallel: z.array(WorkflowStepSchema).optional(),
+  timeout: z.number().optional(),
+  retries: z.number().optional(),
+}));
+
+export const WorkflowSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  version: z.string().optional(),
+  steps: z.array(WorkflowStepSchema).default([]),
+  onError: z.enum(['stop', 'skip', 'retry']).optional(),
+});
+
+export const VoiceSchema = z.object({
+  enabled: z.boolean().default(false),
+  sttProvider: z.string().optional(),
+  ttsProvider: z.string().optional(),
+  language: z.string().optional(),
+});
+
+export const WebhookSchema = z.object({
+  path: z.string().optional(),
+  secret: z.string().optional(),
+  retryAttempts: z.number().optional(),
+});
+
+export const HITLSchema = z.object({
+  enabled: z.boolean().default(false),
+  requireApproval: z.array(z.string()).default([]),
+  defaultTimeoutMs: z.number().default(60000),
+  defaultAction: z.enum(['approve', 'deny']).default('deny'),
+});
+
 export const ChannelSchema = z.object({
-  type: z.enum(['web', 'websocket', 'telegram', 'cli']),
+  type: z.enum(['web', 'websocket', 'telegram', 'cli', 'voice', 'webhook']),
   port: z.number().optional(),
   config: z.record(z.unknown()).optional(),
 });
@@ -80,6 +120,10 @@ export const SpecSchema = z.object({
   room: RoomSchema.optional(),
   streaming: z.union([z.boolean(), StreamingSchema]).default(false),
   locale: z.enum(['en', 'zh-CN']).optional(),
+  workflows: z.array(WorkflowSchema).optional(),
+  voice: VoiceSchema.optional(),
+  webhook: WebhookSchema.optional(),
+  hitl: HITLSchema.optional(),
 });
 
 export const OADSchema = z.object({

package/src/templates/executive-assistant.ts

@@ -0,0 +1,71 @@
+import { BaseSkill } from '../skills/base';
+import type { AgentContext, Message, SkillResult } from '../core/types';
+import type { OADDocument } from '../schema/oad';
+
+export class CalendarSkill extends BaseSkill {
+  name = 'calendar-management';
+  description = 'Manage calendar and scheduling';
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    if (lower.includes('schedule') || lower.includes('meeting') || lower.includes('calendar')) {
+      return this.match('I can help manage your calendar. I can schedule meetings, check availability, send invites, and set reminders. What would you like to do?', 0.8);
+    }
+    if (lower.includes('remind') || lower.includes('reminder')) {
+      return this.match('I\'ll set a reminder for you. Please provide the date, time, and what you\'d like to be reminded about.', 0.75);
+    }
+    return this.noMatch();
+  }
+}
+
+export class EmailDraftSkill extends BaseSkill {
+  name = 'email-drafting';
+  description = 'Draft professional emails';
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    if (lower.includes('email') || lower.includes('draft') || lower.includes('write')) {
+      return this.match('I can draft emails for you. Please provide: the recipient, subject, key points to cover, and desired tone (formal/casual/friendly).', 0.8);
+    }
+    return this.noMatch();
+  }
+}
+
+export class MeetingPrepSkill extends BaseSkill {
+  name = 'meeting-prep';
+  description = 'Prepare for meetings with agendas and notes';
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    if (lower.includes('agenda') || lower.includes('prep') || lower.includes('prepare')) {
+      return this.match('I can prepare meeting materials including: agenda creation, attendee briefings, talking points, action item tracking, and follow-up summaries.', 0.8);
+    }
+    return this.noMatch();
+  }
+}
+
+export function createExecutiveAssistantConfig(): OADDocument {
+  return {
+    apiVersion: 'opc/v1',
+    kind: 'Agent',
+    metadata: {
+      name: 'executive-assistant',
+      version: '1.0.0',
+      description: 'AI Executive Assistant - calendar management, email drafting, meeting prep',
+      author: 'OPC',
+      license: 'Apache-2.0',
+    },
+    spec: {
+      model: 'deepseek-chat',
+      systemPrompt: 'You are an executive assistant AI. Help users manage their calendar, draft emails, and prepare for meetings. Be professional, concise, and proactive.',
+      skills: [
+        { name: 'calendar-management', description: 'Manage calendar and scheduling' },
+        { name: 'email-drafting', description: 'Draft professional emails' },
+        { name: 'meeting-prep', description: 'Prepare meeting materials' },
+      ],
+      channels: [{ type: 'web', port: 3000 }],
+      memory: { shortTerm: true, longTerm: false },
+      streaming: false,
+    },
+  };
+}

package/src/templates/financial-advisor.ts

@@ -0,0 +1,60 @@
+import { BaseSkill } from '../skills/base';
+import type { AgentContext, Message, SkillResult } from '../core/types';
+import type { OADDocument } from '../schema/oad';
+
+export class BudgetAnalysisSkill extends BaseSkill {
+  name = 'budget-analysis';
+  description = 'Analyze budgets and expenses';
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    if (lower.includes('budget') || lower.includes('expense') || lower.includes('cost')) {
+      return this.match('I can help analyze your budget. Please share your income and expense categories, and I\'ll provide insights on spending patterns and savings opportunities.', 0.8);
+    }
+    if (lower.includes('save') || lower.includes('saving')) {
+      return this.match('Common savings strategies: 50/30/20 rule (needs/wants/savings), automate transfers, review subscriptions, negotiate bills, and track daily spending.', 0.75);
+    }
+    return this.noMatch();
+  }
+}
+
+export class FinancialPlanningSkill extends BaseSkill {
+  name = 'financial-planning';
+  description = 'Help with financial planning and advice';
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    if (lower.includes('invest') || lower.includes('portfolio')) {
+      return this.match('For investment planning, consider: risk tolerance, time horizon, diversification, asset allocation, and regular rebalancing. This is general guidance — consult a certified financial advisor for personalized advice.', 0.8);
+    }
+    if (lower.includes('retire') || lower.includes('pension')) {
+      return this.match('Retirement planning essentials: estimate target savings (25x annual expenses), maximize employer matching, consider tax-advantaged accounts, and start early for compound growth.', 0.8);
+    }
+    return this.noMatch();
+  }
+}
+
+export function createFinancialAdvisorConfig(): OADDocument {
+  return {
+    apiVersion: 'opc/v1',
+    kind: 'Agent',
+    metadata: {
+      name: 'financial-advisor',
+      version: '1.0.0',
+      description: 'AI Financial Advisor - budget analysis, expense tracking, financial planning',
+      author: 'OPC',
+      license: 'Apache-2.0',
+    },
+    spec: {
+      model: 'deepseek-chat',
+      systemPrompt: 'You are a financial advisor AI. Help users with budget analysis, expense tracking, and financial planning. Always recommend consulting a certified financial advisor for binding decisions.',
+      skills: [
+        { name: 'budget-analysis', description: 'Analyze budgets and expenses' },
+        { name: 'financial-planning', description: 'Financial planning advice' },
+      ],
+      channels: [{ type: 'web', port: 3000 }],
+      memory: { shortTerm: true, longTerm: false },
+      streaming: false,
+    },
+  };
+}