opc-agent 0.1.0

package/templates/customer-service/README.md

@@ -0,0 +1,22 @@
+# Customer Service Agent Template
+
+A ready-to-use customer service agent with:
+- **FAQ Lookup** — Matches common questions to predefined answers
+- **Human Handoff** — Detects when a customer wants a real person
+- **Web Channel** — HTTP API for chat integration
+
+## Quick Start
+
+```bash
+opc init my-service --template customer-service
+cd my-service
+opc run
+```
+
+## Customization
+
+Edit `oad.yaml` to:
+- Change the system prompt
+- Add custom FAQ entries
+- Switch LLM provider
+- Adjust trust level

package/templates/customer-service/oad.yaml

@@ -0,0 +1,36 @@
+apiVersion: opc/v1
+kind: Agent
+metadata:
+  name: customer-service
+  version: 1.0.0
+  description: "A customer service agent with FAQ lookup and human handoff"
+  author: Deepleaper
+  license: Apache-2.0
+  marketplace:
+    certified: false
+    category: customer-service
+spec:
+  provider:
+    default: deepseek
+    allowed: [openai, deepseek, qwen]
+  model: deepseek-chat
+  systemPrompt: |
+    You are a friendly and professional customer service agent.
+    You help customers with their questions about products, orders, shipping, and returns.
+    Be concise, helpful, and empathetic.
+  skills:
+    - name: faq-lookup
+      description: "Look up FAQ answers"
+    - name: human-handoff
+      description: "Hand off to human agent when needed"
+  channels:
+    - type: web
+      port: 3000
+  memory:
+    shortTerm: true
+    longTerm: false
+  dtv:
+    trust:
+      level: sandbox
+    value:
+      metrics: [response_time, satisfaction_score]

package/tests/agent.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { BaseAgent } from '../src/core/agent';
+
+describe('BaseAgent', () => {
+  it('should start in init state', () => {
+    const agent = new BaseAgent({ name: 'test' });
+    expect(agent.state).toBe('init');
+    expect(agent.name).toBe('test');
+  });
+
+  it('should transition through lifecycle', async () => {
+    const agent = new BaseAgent({ name: 'test' });
+    const states: string[] = [];
+    agent.on('state:change', (_from, to) => states.push(to));
+
+    await agent.init();
+    expect(agent.state).toBe('ready');
+
+    await agent.start();
+    expect(agent.state).toBe('running');
+
+    await agent.stop();
+    expect(agent.state).toBe('stopped');
+
+    expect(states).toEqual(['ready', 'running', 'stopped']);
+  });
+
+  it('should not start if not ready', async () => {
+    const agent = new BaseAgent({ name: 'test' });
+    await expect(agent.start()).rejects.toThrow('Cannot start agent in state: init');
+  });
+
+  it('should handle messages with stub provider', async () => {
+    const agent = new BaseAgent({ name: 'test', systemPrompt: 'Be helpful' });
+    await agent.init();
+
+    const response = await agent.handleMessage({
+      id: 'msg_1',
+      role: 'user',
+      content: 'Hello',
+      timestamp: Date.now(),
+    });
+
+    expect(response.role).toBe('assistant');
+    expect(response.content).toContain('Hello');
+  });
+
+  it('should use skills before LLM fallback', async () => {
+    const agent = new BaseAgent({ name: 'test' });
+    await agent.init();
+
+    agent.registerSkill({
+      name: 'greeter',
+      description: 'Greets users',
+      execute: async (_ctx, msg) => {
+        if (msg.content.toLowerCase().includes('hello')) {
+          return { handled: true, response: 'Hi there!', confidence: 1.0 };
+        }
+        return { handled: false, confidence: 0 };
+      },
+    });
+
+    const response = await agent.handleMessage({
+      id: 'msg_1',
+      role: 'user',
+      content: 'Hello!',
+      timestamp: Date.now(),
+    });
+
+    expect(response.content).toBe('Hi there!');
+  });
+});

package/tests/channel.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { WebChannel } from '../src/channels/web';
+
+describe('WebChannel', () => {
+  let channel: WebChannel | null = null;
+
+  afterEach(async () => {
+    if (channel) {
+      await channel.stop();
+      channel = null;
+    }
+  });
+
+  it('should create with default port', () => {
+    channel = new WebChannel();
+    expect(channel.type).toBe('web');
+  });
+
+  it('should start and stop', async () => {
+    channel = new WebChannel(0); // random port
+    channel.onMessage(async (msg) => ({
+      id: 'resp_1',
+      role: 'assistant',
+      content: `Echo: ${msg.content}`,
+      timestamp: Date.now(),
+    }));
+    await channel.start();
+    await channel.stop();
+    channel = null;
+  });
+
+  it('should handle health check', async () => {
+    channel = new WebChannel(0);
+    await channel.start();
+    // Channel is running — health endpoint is available
+    await channel.stop();
+    channel = null;
+  });
+});

package/tests/oad.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import { OADSchema } from '../src/schema/oad';
+
+describe('OAD Schema', () => {
+  it('should parse a valid OAD document', () => {
+    const doc = OADSchema.parse({
+      apiVersion: 'opc/v1',
+      kind: 'Agent',
+      metadata: { name: 'test-agent' },
+      spec: {},
+    });
+    expect(doc.metadata.name).toBe('test-agent');
+    expect(doc.metadata.version).toBe('1.0.0');
+    expect(doc.spec.model).toBe('deepseek-chat');
+  });
+
+  it('should reject invalid apiVersion', () => {
+    expect(() =>
+      OADSchema.parse({
+        apiVersion: 'v2',
+        kind: 'Agent',
+        metadata: { name: 'test' },
+        spec: {},
+      })
+    ).toThrow();
+  });
+
+  it('should parse full document with all fields', () => {
+    const doc = OADSchema.parse({
+      apiVersion: 'opc/v1',
+      kind: 'Agent',
+      metadata: {
+        name: 'full-agent',
+        version: '2.0.0',
+        description: 'A full agent',
+        author: 'Test',
+        license: 'MIT',
+        marketplace: { certified: true, category: 'support' },
+      },
+      spec: {
+        provider: { default: 'openai', allowed: ['openai'] },
+        model: 'gpt-4',
+        systemPrompt: 'You are helpful.',
+        skills: [{ name: 'faq', description: 'FAQ skill' }],
+        channels: [{ type: 'web', port: 8080 }],
+        memory: { shortTerm: true, longTerm: true },
+        dtv: {
+          trust: { level: 'certified' },
+          value: { metrics: ['response_time'] },
+        },
+      },
+    });
+    expect(doc.metadata.version).toBe('2.0.0');
+    expect(doc.spec.channels[0].port).toBe(8080);
+    expect(doc.spec.dtv?.trust?.level).toBe('certified');
+  });
+
+  it('should reject missing metadata.name', () => {
+    expect(() =>
+      OADSchema.parse({
+        apiVersion: 'opc/v1',
+        kind: 'Agent',
+        metadata: {},
+        spec: {},
+      })
+    ).toThrow();
+  });
+});

package/tests/runtime.test.ts

@@ -0,0 +1,42 @@
+import { describe, it, expect } from 'vitest';
+import { AgentRuntime } from '../src/core/runtime';
+import { createCustomerServiceConfig } from '../src/templates/customer-service';
+
+describe('AgentRuntime', () => {
+  it('should initialize from config object', async () => {
+    const runtime = new AgentRuntime();
+    const config = createCustomerServiceConfig();
+    const agent = await runtime.initialize(config);
+    expect(agent.name).toBe('customer-service');
+    expect(agent.state).toBe('ready');
+  });
+
+  it('should throw if no config loaded', async () => {
+    const runtime = new AgentRuntime();
+    await expect(runtime.initialize()).rejects.toThrow('No config loaded');
+  });
+
+  it('should register skills after initialization', async () => {
+    const runtime = new AgentRuntime();
+    const config = createCustomerServiceConfig();
+    await runtime.initialize(config);
+
+    runtime.registerSkill({
+      name: 'test-skill',
+      description: 'Test',
+      execute: async () => ({ handled: false, confidence: 0 }),
+    });
+    // No throw = success
+  });
+
+  it('should throw registering skill before init', () => {
+    const runtime = new AgentRuntime();
+    expect(() =>
+      runtime.registerSkill({
+        name: 'test',
+        description: 'Test',
+        execute: async () => ({ handled: false, confidence: 0 }),
+      })
+    ).toThrow('Agent not initialized');
+  });
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+  },
+});