opc-agent 0.1.0

package/src/core/agent.ts

@@ -0,0 +1,116 @@
+import { EventEmitter } from 'events';
+import type { AgentState, IAgent, IChannel, ISkill, Message, MemoryStore, AgentContext } from './types';
+import { InMemoryStore } from '../memory';
+import { createProvider, type LLMProvider } from '../providers';
+
+export class BaseAgent extends EventEmitter implements IAgent {
+  readonly name: string;
+  private _state: AgentState = 'init';
+  private skills: Map<string, ISkill> = new Map();
+  private channels: IChannel[] = [];
+  private memory: MemoryStore;
+  private provider: LLMProvider;
+  private systemPrompt: string;
+
+  constructor(options: {
+    name: string;
+    systemPrompt?: string;
+    provider?: string;
+    model?: string;
+    memory?: MemoryStore;
+  }) {
+    super();
+    this.name = options.name;
+    this.systemPrompt = options.systemPrompt ?? 'You are a helpful AI agent.';
+    this.memory = options.memory ?? new InMemoryStore();
+    this.provider = createProvider(options.provider ?? 'deepseek', options.model ?? 'deepseek-chat');
+  }
+
+  get state(): AgentState {
+    return this._state;
+  }
+
+  private transition(to: AgentState): void {
+    const from = this._state;
+    this._state = to;
+    this.emit('state:change', from, to);
+  }
+
+  async init(): Promise<void> {
+    this.transition('ready');
+  }
+
+  async start(): Promise<void> {
+    if (this._state !== 'ready') {
+      throw new Error(`Cannot start agent in state: ${this._state}`);
+    }
+    for (const channel of this.channels) {
+      channel.onMessage((msg) => this.handleMessage(msg));
+      await channel.start();
+    }
+    this.transition('running');
+  }
+
+  async stop(): Promise<void> {
+    for (const channel of this.channels) {
+      await channel.stop();
+    }
+    this.transition('stopped');
+  }
+
+  registerSkill(skill: ISkill): void {
+    this.skills.set(skill.name, skill);
+  }
+
+  bindChannel(channel: IChannel): void {
+    this.channels.push(channel);
+  }
+
+  async handleMessage(message: Message): Promise<Message> {
+    this.emit('message:in', message);
+
+    const sessionId = (message.metadata?.sessionId as string) ?? 'default';
+    await this.memory.addMessage(sessionId, message);
+
+    const context: AgentContext = {
+      agentName: this.name,
+      sessionId,
+      messages: await this.memory.getConversation(sessionId),
+      memory: this.memory,
+      metadata: {},
+    };
+
+    // Try skills first
+    for (const [name, skill] of this.skills) {
+      try {
+        const result = await skill.execute(context, message);
+        this.emit('skill:execute', name, result);
+        if (result.handled && result.response) {
+          const response = this.createResponse(result.response, message);
+          await this.memory.addMessage(sessionId, response);
+          this.emit('message:out', response);
+          return response;
+        }
+      } catch (err) {
+        this.emit('error', err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+
+    // Fall back to LLM
+    const llmResponse = await this.provider.chat(context.messages, this.systemPrompt);
+    const response = this.createResponse(llmResponse, message);
+    await this.memory.addMessage(sessionId, response);
+    this.emit('message:out', response);
+    return response;
+  }
+
+  private createResponse(content: string, inReplyTo: Message): Message {
+    return {
+      id: `msg_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      role: 'assistant',
+      content,
+      timestamp: Date.now(),
+      metadata: { inReplyTo: inReplyTo.id },
+    };
+  }
+}

package/src/core/config.ts

@@ -0,0 +1,14 @@
+import * as fs from 'fs';
+import * as yaml from 'js-yaml';
+import { OADSchema, type OADDocument } from '../schema/oad';
+
+export function loadOAD(filePath: string): OADDocument {
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const ext = filePath.split('.').pop()?.toLowerCase();
+  const data = (ext === 'yaml' || ext === 'yml') ? yaml.load(raw) : JSON.parse(raw);
+  return OADSchema.parse(data);
+}
+
+export function validateOAD(data: unknown): OADDocument {
+  return OADSchema.parse(data);
+}

package/src/core/runtime.ts

@@ -0,0 +1,57 @@
+import { BaseAgent } from './agent';
+import { loadOAD } from './config';
+import { WebChannel } from '../channels/web';
+import type { OADDocument } from '../schema/oad';
+import type { ISkill } from './types';
+
+export class AgentRuntime {
+  private agent: BaseAgent | null = null;
+  private config: OADDocument | null = null;
+
+  async loadConfig(filePath: string): Promise<OADDocument> {
+    this.config = loadOAD(filePath);
+    return this.config;
+  }
+
+  async initialize(config?: OADDocument): Promise<BaseAgent> {
+    const cfg = config ?? this.config;
+    if (!cfg) throw new Error('No config loaded. Call loadConfig() first.');
+
+    this.agent = new BaseAgent({
+      name: cfg.metadata.name,
+      systemPrompt: cfg.spec.systemPrompt,
+      provider: cfg.spec.provider?.default,
+      model: cfg.spec.model,
+    });
+
+    // Bind channels
+    for (const ch of cfg.spec.channels) {
+      if (ch.type === 'web') {
+        const port = ch.port ?? 3000;
+        this.agent.bindChannel(new WebChannel(port));
+      }
+    }
+
+    await this.agent.init();
+    return this.agent;
+  }
+
+  async start(): Promise<void> {
+    if (!this.agent) throw new Error('Agent not initialized.');
+    await this.agent.start();
+  }
+
+  async stop(): Promise<void> {
+    if (!this.agent) return;
+    await this.agent.stop();
+  }
+
+  registerSkill(skill: ISkill): void {
+    if (!this.agent) throw new Error('Agent not initialized.');
+    this.agent.registerSkill(skill);
+  }
+
+  getAgent(): BaseAgent | null {
+    return this.agent;
+  }
+}

package/src/core/types.ts

@@ -0,0 +1,68 @@
+import { EventEmitter } from 'events';
+
+// ─── Core Types ──────────────────────────────────────────────
+
+export type AgentState = 'init' | 'ready' | 'running' | 'stopped' | 'error';
+
+export interface Message {
+  id: string;
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  timestamp: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AgentContext {
+  agentName: string;
+  sessionId: string;
+  messages: Message[];
+  memory: MemoryStore;
+  metadata: Record<string, unknown>;
+}
+
+export interface SkillResult {
+  handled: boolean;
+  response?: string;
+  confidence: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ISkill {
+  name: string;
+  description: string;
+  execute(context: AgentContext, message: Message): Promise<SkillResult>;
+}
+
+export interface IChannel {
+  type: string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  onMessage(handler: (message: Message) => Promise<Message>): void;
+}
+
+export interface MemoryStore {
+  get(key: string): Promise<unknown>;
+  set(key: string, value: unknown): Promise<void>;
+  getConversation(sessionId: string): Promise<Message[]>;
+  addMessage(sessionId: string, message: Message): Promise<void>;
+  clear(sessionId?: string): Promise<void>;
+}
+
+export interface AgentEvents {
+  'state:change': (from: AgentState, to: AgentState) => void;
+  'message:in': (message: Message) => void;
+  'message:out': (message: Message) => void;
+  'skill:execute': (skill: string, result: SkillResult) => void;
+  'error': (error: Error) => void;
+}
+
+export interface IAgent extends EventEmitter {
+  readonly name: string;
+  readonly state: AgentState;
+  init(): Promise<void>;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  handleMessage(message: Message): Promise<Message>;
+  registerSkill(skill: ISkill): void;
+  bindChannel(channel: IChannel): void;
+}

package/src/dtv/data.ts

@@ -0,0 +1,29 @@
+export interface DataSource {
+  readonly name: string;
+  readonly type: string;
+  read(key: string): Promise<unknown>;
+}
+
+/**
+ * MRGConfig reader — read-only data layer for agents.
+ * Agents can read business data but cannot modify source systems.
+ */
+export class MRGConfigReader implements DataSource {
+  readonly name = 'mrg-config';
+  readonly type = 'config';
+  private data: Map<string, unknown>;
+
+  constructor(initial?: Record<string, unknown>) {
+    this.data = new Map(Object.entries(initial ?? {}));
+  }
+
+  async read(key: string): Promise<unknown> {
+    return this.data.get(key);
+  }
+
+  load(data: Record<string, unknown>): void {
+    for (const [k, v] of Object.entries(data)) {
+      this.data.set(k, v);
+    }
+  }
+}

package/src/dtv/trust.ts

@@ -0,0 +1,43 @@
+import type { TrustLevelType } from '../schema/oad';
+
+/**
+ * Trust levels: sandbox → verified → certified → listed
+ *
+ * - sandbox:   No network, no file system, limited capabilities
+ * - verified:  Identity verified, basic capabilities
+ * - certified: Passed security audit, full capabilities
+ * - listed:    Published in OPC marketplace
+ */
+export class TrustManager {
+  private level: TrustLevelType;
+
+  constructor(level: TrustLevelType = 'sandbox') {
+    this.level = level;
+  }
+
+  getLevel(): TrustLevelType {
+    return this.level;
+  }
+
+  canAccessNetwork(): boolean {
+    return this.level !== 'sandbox';
+  }
+
+  canAccessFileSystem(): boolean {
+    return this.level === 'certified' || this.level === 'listed';
+  }
+
+  canPublish(): boolean {
+    return this.level === 'listed';
+  }
+
+  upgrade(to: TrustLevelType): void {
+    const order: TrustLevelType[] = ['sandbox', 'verified', 'certified', 'listed'];
+    const currentIdx = order.indexOf(this.level);
+    const targetIdx = order.indexOf(to);
+    if (targetIdx <= currentIdx) {
+      throw new Error(`Cannot downgrade trust from ${this.level} to ${to}`);
+    }
+    this.level = to;
+  }
+}

package/src/dtv/value.ts

@@ -0,0 +1,47 @@
+/**
+ * Value tracking — metrics and ROI for agent operations.
+ */
+export interface ValueMetric {
+  name: string;
+  value: number;
+  unit: string;
+  timestamp: number;
+}
+
+export class ValueTracker {
+  private metrics: Map<string, ValueMetric[]> = new Map();
+  private trackedNames: Set<string>;
+
+  constructor(metricNames: string[] = []) {
+    this.trackedNames = new Set(metricNames);
+  }
+
+  record(name: string, value: number, unit: string = ''): void {
+    if (!this.metrics.has(name)) {
+      this.metrics.set(name, []);
+    }
+    this.metrics.get(name)!.push({ name, value, unit, timestamp: Date.now() });
+  }
+
+  getMetrics(name: string): ValueMetric[] {
+    return this.metrics.get(name) ?? [];
+  }
+
+  getAverage(name: string): number {
+    const m = this.getMetrics(name);
+    if (m.length === 0) return 0;
+    return m.reduce((sum, v) => sum + v.value, 0) / m.length;
+  }
+
+  getSummary(): Record<string, { count: number; average: number; last: number }> {
+    const result: Record<string, { count: number; average: number; last: number }> = {};
+    for (const [name, values] of this.metrics) {
+      result[name] = {
+        count: values.length,
+        average: this.getAverage(name),
+        last: values[values.length - 1]?.value ?? 0,
+      };
+    }
+    return result;
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+// OPC Agent — Open Agent Framework
+export { BaseAgent } from './core/agent';
+export { AgentRuntime } from './core/runtime';
+export { loadOAD, validateOAD } from './core/config';
+export { OADSchema } from './schema/oad';
+export type { OADDocument, Metadata, Spec, DTVConfig, TrustLevelType } from './schema/oad';
+export type { IAgent, IChannel, ISkill, Message, AgentContext, SkillResult, MemoryStore, AgentState } from './core/types';
+export { BaseChannel } from './channels';
+export { WebChannel } from './channels/web';
+export { BaseSkill } from './skills/base';
+export { SkillRegistry } from './skills';
+export { InMemoryStore } from './memory';
+export { TrustManager } from './dtv/trust';
+export { ValueTracker } from './dtv/value';
+export { MRGConfigReader } from './dtv/data';
+export { createProvider, SUPPORTED_PROVIDERS } from './providers';

package/src/memory/index.ts

@@ -0,0 +1,34 @@
+import type { Message, MemoryStore } from '../core/types';
+
+export class InMemoryStore implements MemoryStore {
+  private store: Map<string, unknown> = new Map();
+  private conversations: Map<string, Message[]> = new Map();
+
+  async get(key: string): Promise<unknown> {
+    return this.store.get(key);
+  }
+
+  async set(key: string, value: unknown): Promise<void> {
+    this.store.set(key, value);
+  }
+
+  async getConversation(sessionId: string): Promise<Message[]> {
+    return this.conversations.get(sessionId) ?? [];
+  }
+
+  async addMessage(sessionId: string, message: Message): Promise<void> {
+    if (!this.conversations.has(sessionId)) {
+      this.conversations.set(sessionId, []);
+    }
+    this.conversations.get(sessionId)!.push(message);
+  }
+
+  async clear(sessionId?: string): Promise<void> {
+    if (sessionId) {
+      this.conversations.delete(sessionId);
+    } else {
+      this.store.clear();
+      this.conversations.clear();
+    }
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,44 @@
+import type { Message } from '../core/types';
+
+/**
+ * LLM Provider interface — abstracts different LLM backends.
+ * Uses agentkits when available, falls back to stub.
+ */
+export interface LLMProvider {
+  name: string;
+  chat(messages: Message[], systemPrompt?: string): Promise<string>;
+}
+
+class StubProvider implements LLMProvider {
+  name: string;
+  private model: string;
+
+  constructor(name: string, model: string) {
+    this.name = name;
+    this.model = model;
+  }
+
+  async chat(messages: Message[], systemPrompt?: string): Promise<string> {
+    // Try agentkits dynamic import
+    try {
+      const ak = await import('agentkits');
+      const chat = ak.createChat({ provider: this.name as any, model: this.model });
+      const formatted = [
+        ...(systemPrompt ? [{ role: 'system' as const, content: systemPrompt }] : []),
+        ...messages.map((m) => ({ role: m.role, content: m.content })),
+      ];
+      const result = await (chat as any).send(formatted);
+      return typeof result === 'string' ? result : JSON.stringify(result);
+    } catch {
+      // Stub fallback when agentkits is not available
+      const lastMessage = messages[messages.length - 1];
+      return `[${this.name}/${this.model} stub] Received: "${lastMessage?.content ?? ''}"`;
+    }
+  }
+}
+
+export function createProvider(name: string = 'deepseek', model: string = 'deepseek-chat'): LLMProvider {
+  return new StubProvider(name, model);
+}
+
+export const SUPPORTED_PROVIDERS = ['openai', 'deepseek', 'qwen'] as const;

package/src/schema/oad.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+
+// ─── OAD Schema v1 ───────────────────────────────────────────
+
+export const SkillRefSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  config: z.record(z.unknown()).optional(),
+});
+
+export const ChannelSchema = z.object({
+  type: z.enum(['web', 'websocket', 'cli']),
+  port: z.number().optional(),
+  config: z.record(z.unknown()).optional(),
+});
+
+export const MemorySchema = z.object({
+  shortTerm: z.boolean().default(true),
+  longTerm: z.boolean().default(false),
+  provider: z.string().optional(),
+});
+
+export const TrustLevel = z.enum(['sandbox', 'verified', 'certified', 'listed']);
+
+export const DTVSchema = z.object({
+  trust: z.object({
+    level: TrustLevel.default('sandbox'),
+  }).optional(),
+  value: z.object({
+    metrics: z.array(z.string()).default([]),
+  }).optional(),
+});
+
+export const ProviderSchema = z.object({
+  default: z.string().default('deepseek'),
+  allowed: z.array(z.string()).default(['openai', 'deepseek', 'qwen']),
+});
+
+export const MarketplaceSchema = z.object({
+  certified: z.boolean().default(false),
+  category: z.string().optional(),
+});
+
+export const MetadataSchema = z.object({
+  name: z.string(),
+  version: z.string().default('1.0.0'),
+  description: z.string().optional(),
+  author: z.string().optional(),
+  license: z.string().default('Apache-2.0'),
+  marketplace: MarketplaceSchema.optional(),
+});
+
+export const SpecSchema = z.object({
+  provider: ProviderSchema.optional(),
+  model: z.string().default('deepseek-chat'),
+  systemPrompt: z.string().optional(),
+  skills: z.array(SkillRefSchema).default([]),
+  channels: z.array(ChannelSchema).default([]),
+  memory: MemorySchema.optional(),
+  dtv: DTVSchema.optional(),
+});
+
+export const OADSchema = z.object({
+  apiVersion: z.literal('opc/v1'),
+  kind: z.literal('Agent'),
+  metadata: MetadataSchema,
+  spec: SpecSchema,
+});
+
+export type OADDocument = z.infer<typeof OADSchema>;
+export type SkillRef = z.infer<typeof SkillRefSchema>;
+export type Channel = z.infer<typeof ChannelSchema>;
+export type Metadata = z.infer<typeof MetadataSchema>;
+export type Spec = z.infer<typeof SpecSchema>;
+export type DTVConfig = z.infer<typeof DTVSchema>;
+export type TrustLevelType = z.infer<typeof TrustLevel>;

package/src/skills/base.ts

@@ -0,0 +1,16 @@
+import type { ISkill, AgentContext, Message, SkillResult } from '../core/types';
+
+export abstract class BaseSkill implements ISkill {
+  abstract name: string;
+  abstract description: string;
+
+  abstract execute(context: AgentContext, message: Message): Promise<SkillResult>;
+
+  protected noMatch(): SkillResult {
+    return { handled: false, confidence: 0 };
+  }
+
+  protected match(response: string, confidence: number = 1.0): SkillResult {
+    return { handled: true, response, confidence };
+  }
+}

package/src/skills/index.ts

@@ -0,0 +1,27 @@
+import type { ISkill, AgentContext, Message, SkillResult } from '../core/types';
+
+export type { ISkill } from '../core/types';
+
+export class SkillRegistry {
+  private skills: Map<string, ISkill> = new Map();
+
+  register(skill: ISkill): void {
+    this.skills.set(skill.name, skill);
+  }
+
+  get(name: string): ISkill | undefined {
+    return this.skills.get(name);
+  }
+
+  list(): ISkill[] {
+    return Array.from(this.skills.values());
+  }
+
+  async executeAll(context: AgentContext, message: Message): Promise<SkillResult | null> {
+    for (const skill of this.skills.values()) {
+      const result = await skill.execute(context, message);
+      if (result.handled) return result;
+    }
+    return null;
+  }
+}

package/src/templates/customer-service.ts

@@ -0,0 +1,80 @@
+import { BaseSkill } from '../skills/base';
+import type { AgentContext, Message, SkillResult } from '../core/types';
+
+const DEFAULT_FAQ: Record<string, string> = {
+  'hours': 'Our business hours are Monday-Friday, 9am-6pm.',
+  'return': 'You can return items within 30 days of purchase.',
+  'shipping': 'Standard shipping takes 3-5 business days.',
+  'contact': 'You can reach us at support@example.com.',
+};
+
+export class FAQSkill extends BaseSkill {
+  name = 'faq-lookup';
+  description = 'Look up FAQ answers';
+  private faq: Record<string, string>;
+
+  constructor(faq?: Record<string, string>) {
+    super();
+    this.faq = faq ?? DEFAULT_FAQ;
+  }
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    for (const [key, answer] of Object.entries(this.faq)) {
+      if (lower.includes(key)) {
+        return this.match(answer, 0.9);
+      }
+    }
+    return this.noMatch();
+  }
+}
+
+export class HandoffSkill extends BaseSkill {
+  name = 'human-handoff';
+  description = 'Hand off to a human agent when confidence is low';
+  private keywords = ['speak to human', 'talk to agent', 'real person', 'human agent'];
+
+  async execute(_context: AgentContext, message: Message): Promise<SkillResult> {
+    const lower = message.content.toLowerCase();
+    if (this.keywords.some((kw) => lower.includes(kw))) {
+      return this.match(
+        'I understand you\'d like to speak with a human agent. Let me connect you now. Please hold.',
+        1.0
+      );
+    }
+    return this.noMatch();
+  }
+}
+
+export const CUSTOMER_SERVICE_SYSTEM_PROMPT = `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. If you're unsure, offer to connect them with a human agent.`;
+
+export function createCustomerServiceConfig() {
+  return {
+    apiVersion: 'opc/v1' as const,
+    kind: 'Agent' as const,
+    metadata: {
+      name: 'customer-service',
+      version: '1.0.0',
+      description: 'Customer service agent with FAQ and human handoff',
+      author: 'OPC Agent',
+      license: 'Apache-2.0',
+    },
+    spec: {
+      provider: { default: 'deepseek', allowed: ['openai', 'deepseek', 'qwen'] },
+      model: 'deepseek-chat',
+      systemPrompt: CUSTOMER_SERVICE_SYSTEM_PROMPT,
+      skills: [
+        { name: 'faq-lookup', description: 'Look up FAQ answers' },
+        { name: 'human-handoff', description: 'Hand off to human agent' },
+      ],
+      channels: [{ type: 'web' as const, port: 3000 }],
+      memory: { shortTerm: true, longTerm: false },
+      dtv: {
+        trust: { level: 'sandbox' as const },
+        value: { metrics: ['response_time', 'satisfaction_score'] },
+      },
+    },
+  };
+}