opc-agent 0.5.1 → 0.7.0

package/src/core/knowledge.ts

@@ -0,0 +1,210 @@
+/**
+ * Knowledge Base / RAG - Local vector storage with semantic search
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+
+// Simple in-memory vector store (PGlite-compatible interface for future migration)
+interface VectorEntry {
+  id: string;
+  content: string;
+  embedding: number[];
+  metadata: Record<string, unknown>;
+}
+
+interface KnowledgeStore {
+  entries: VectorEntry[];
+  version: number;
+  updatedAt: string;
+}
+
+const CHUNK_SIZE = 500; // chars per chunk
+const CHUNK_OVERLAP = 50;
+const STORE_FILE = '.opc-knowledge.json';
+
+function splitText(text: string, chunkSize = CHUNK_SIZE, overlap = CHUNK_OVERLAP): string[] {
+  const chunks: string[] = [];
+  // Split by paragraphs first, then by size
+  const paragraphs = text.split(/\n\s*\n/).filter(p => p.trim());
+  let current = '';
+
+  for (const para of paragraphs) {
+    if (current.length + para.length > chunkSize && current.length > 0) {
+      chunks.push(current.trim());
+      // Keep overlap from end of current
+      current = current.slice(-overlap) + '\n\n' + para;
+    } else {
+      current += (current ? '\n\n' : '') + para;
+    }
+  }
+  if (current.trim()) chunks.push(current.trim());
+
+  // If any chunk is still too large, split by sentences
+  const result: string[] = [];
+  for (const chunk of chunks) {
+    if (chunk.length <= chunkSize * 1.5) {
+      result.push(chunk);
+    } else {
+      const sentences = chunk.split(/(?<=[.!?])\s+/);
+      let buf = '';
+      for (const s of sentences) {
+        if (buf.length + s.length > chunkSize && buf) {
+          result.push(buf.trim());
+          buf = buf.slice(-overlap) + ' ' + s;
+        } else {
+          buf += (buf ? ' ' : '') + s;
+        }
+      }
+      if (buf.trim()) result.push(buf.trim());
+    }
+  }
+  return result;
+}
+
+// Simple TF-IDF-like embedding (no external dependencies)
+// For production, replace with real embedding API
+function simpleEmbed(text: string): number[] {
+  const words = text.toLowerCase().replace(/[^a-z0-9\s]/g, '').split(/\s+/).filter(Boolean);
+  const dim = 128;
+  const vec = new Array(dim).fill(0);
+
+  for (const word of words) {
+    const hash = crypto.createHash('md5').update(word).digest();
+    for (let i = 0; i < dim; i++) {
+      vec[i] += (hash[i % hash.length] - 128) / 128;
+    }
+  }
+
+  // Normalize
+  const mag = Math.sqrt(vec.reduce((s, v) => s + v * v, 0)) || 1;
+  return vec.map(v => v / mag);
+}
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  let dot = 0, magA = 0, magB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    magA += a[i] * a[i];
+    magB += b[i] * b[i];
+  }
+  return dot / (Math.sqrt(magA) * Math.sqrt(magB) || 1);
+}
+
+export class KnowledgeBase {
+  private store: KnowledgeStore;
+  private storePath: string;
+
+  constructor(baseDir: string = '.') {
+    this.storePath = path.join(baseDir, STORE_FILE);
+    this.store = this.load();
+  }
+
+  private load(): KnowledgeStore {
+    try {
+      if (fs.existsSync(this.storePath)) {
+        return JSON.parse(fs.readFileSync(this.storePath, 'utf-8'));
+      }
+    } catch { /* ignore */ }
+    return { entries: [], version: 1, updatedAt: new Date().toISOString() };
+  }
+
+  private save(): void {
+    this.store.updatedAt = new Date().toISOString();
+    fs.writeFileSync(this.storePath, JSON.stringify(this.store), 'utf-8');
+  }
+
+  async addFile(filePath: string): Promise<{ chunks: number }> {
+    const absPath = path.resolve(filePath);
+    if (!fs.existsSync(absPath)) {
+      throw new Error(`File not found: ${absPath}`);
+    }
+
+    const content = fs.readFileSync(absPath, 'utf-8');
+    const filename = path.basename(absPath);
+
+    // Remove existing entries for this file
+    this.store.entries = this.store.entries.filter(
+      e => e.metadata.source !== filename
+    );
+
+    const chunks = splitText(content);
+    for (let i = 0; i < chunks.length; i++) {
+      const chunk = chunks[i];
+      this.store.entries.push({
+        id: `${filename}_${i}_${Date.now()}`,
+        content: chunk,
+        embedding: simpleEmbed(chunk),
+        metadata: {
+          source: filename,
+          chunkIndex: i,
+          totalChunks: chunks.length,
+          addedAt: new Date().toISOString(),
+        },
+      });
+    }
+
+    this.save();
+    return { chunks: chunks.length };
+  }
+
+  async addText(text: string, source: string = 'manual'): Promise<{ chunks: number }> {
+    const chunks = splitText(text);
+    for (let i = 0; i < chunks.length; i++) {
+      this.store.entries.push({
+        id: `${source}_${i}_${Date.now()}`,
+        content: chunks[i],
+        embedding: simpleEmbed(chunks[i]),
+        metadata: { source, chunkIndex: i, totalChunks: chunks.length, addedAt: new Date().toISOString() },
+      });
+    }
+    this.save();
+    return { chunks: chunks.length };
+  }
+
+  async search(query: string, topK: number = 5): Promise<Array<{ content: string; score: number; source: string }>> {
+    if (this.store.entries.length === 0) return [];
+
+    const queryEmb = simpleEmbed(query);
+    const scored = this.store.entries.map(entry => ({
+      content: entry.content,
+      score: cosineSimilarity(queryEmb, entry.embedding),
+      source: String(entry.metadata.source ?? 'unknown'),
+    }));
+
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, topK);
+  }
+
+  /** Build context string for injection into LLM calls */
+  async getContext(query: string, topK: number = 3, minScore: number = 0.1): Promise<string> {
+    const results = await this.search(query, topK);
+    const relevant = results.filter(r => r.score >= minScore);
+    if (relevant.length === 0) return '';
+
+    return `\n\n--- Relevant Knowledge ---\n${relevant.map((r, i) =>
+      `[${i + 1}] (source: ${r.source}, relevance: ${(r.score * 100).toFixed(0)}%)\n${r.content}`
+    ).join('\n\n')}\n--- End Knowledge ---\n`;
+  }
+
+  getStats(): { totalEntries: number; sources: string[]; updatedAt: string } {
+    const sources = [...new Set(this.store.entries.map(e => String(e.metadata.source)))];
+    return {
+      totalEntries: this.store.entries.length,
+      sources,
+      updatedAt: this.store.updatedAt,
+    };
+  }
+
+  clear(): void {
+    this.store.entries = [];
+    this.save();
+  }
+
+  removeSource(source: string): number {
+    const before = this.store.entries.length;
+    this.store.entries = this.store.entries.filter(e => e.metadata.source !== source);
+    this.save();
+    return before - this.store.entries.length;
+  }
+}

package/src/deploy/hermes.ts

@@ -0,0 +1,156 @@
+/**
+ * Hermes Agent Adapter - Convert OAD → Hermes Agent config
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import type { OADDocument } from '../schema/oad';
+
+export interface HermesDeployOptions {
+  oad: OADDocument;
+  outputDir: string;
+}
+
+export interface HermesDeployResult {
+  outputDir: string;
+  files: string[];
+}
+
+interface HermesCharacter {
+  name: string;
+  description: string;
+  personality: string;
+  system: string;
+  bio: string[];
+  lore: string[];
+  messageExamples: Array<Array<{ user: string; content: { text: string } }>>;
+  postExamples: string[];
+  topics: string[];
+  adjectives: string[];
+  style: {
+    all: string[];
+    chat: string[];
+    post: string[];
+  };
+  plugins: string[];
+  settings: {
+    model: string;
+    voice: { model: string };
+    secrets: Record<string, string>;
+  };
+}
+
+function oadToHermesCharacter(oad: OADDocument): HermesCharacter {
+  const m = oad.metadata;
+  const s = oad.spec;
+  const prompt = s.systemPrompt ?? 'You are a helpful AI agent.';
+
+  // Extract personality traits from system prompt
+  const lines = prompt.split('\n').filter(l => l.trim());
+  const bio = lines.slice(0, 3).map(l => l.replace(/^[-*#]\s*/, '').trim());
+
+  return {
+    name: m.name,
+    description: m.description ?? `${m.name} - AI Agent`,
+    personality: prompt.slice(0, 500),
+    system: prompt,
+    bio: bio.length > 0 ? bio : [`${m.name} is an AI agent built with OPC Agent framework.`],
+    lore: [`Created with OPC Agent v${m.version}`, `Licensed under ${m.license}`],
+    messageExamples: [
+      [
+        { user: '{{user1}}', content: { text: 'Hello!' } },
+        { user: m.name, content: { text: 'Hi there! How can I help you today?' } },
+      ],
+    ],
+    postExamples: [],
+    topics: s.skills.map(sk => sk.name),
+    adjectives: ['helpful', 'knowledgeable', 'professional'],
+    style: {
+      all: ['Be helpful and professional', 'Use clear language'],
+      chat: ['Respond conversationally', 'Be concise but thorough'],
+      post: ['Share useful insights', 'Be informative'],
+    },
+    plugins: s.skills.map(sk => sk.name),
+    settings: {
+      model: s.model,
+      voice: { model: 'en_US-neutral' },
+      secrets: {},
+    },
+  };
+}
+
+function generateHermesSettings(oad: OADDocument): Record<string, any> {
+  return {
+    name: oad.metadata.name,
+    version: oad.metadata.version,
+    runtime: {
+      provider: oad.spec.provider?.default ?? 'openai',
+      model: oad.spec.model,
+      temperature: 0.7,
+      maxTokens: 2048,
+    },
+    channels: oad.spec.channels.map(ch => ({
+      type: ch.type,
+      enabled: true,
+      config: ch.config ?? {},
+    })),
+    memory: {
+      enabled: !!oad.spec.memory,
+      provider: typeof oad.spec.memory?.longTerm === 'object'
+        ? oad.spec.memory.longTerm.provider
+        : 'in-memory',
+    },
+  };
+}
+
+export function deployToHermes(options: HermesDeployOptions): HermesDeployResult {
+  const { oad, outputDir } = options;
+  const files: string[] = [];
+
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  // character.json
+  const character = oadToHermesCharacter(oad);
+  const charPath = path.join(outputDir, 'character.json');
+  fs.writeFileSync(charPath, JSON.stringify(character, null, 2), 'utf-8');
+  files.push('character.json');
+
+  // settings.json
+  const settings = generateHermesSettings(oad);
+  const settingsPath = path.join(outputDir, 'settings.json');
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf-8');
+  files.push('settings.json');
+
+  // .env template
+  const envContent = `# Hermes Agent Environment
+HERMES_CHARACTER=${oad.metadata.name}
+HERMES_MODEL=${oad.spec.model}
+HERMES_PROVIDER=${oad.spec.provider?.default ?? 'openai'}
+# Add your API keys below:
+# OPENAI_API_KEY=
+# DEEPSEEK_API_KEY=
+`;
+  fs.writeFileSync(path.join(outputDir, '.env.hermes'), envContent, 'utf-8');
+  files.push('.env.hermes');
+
+  // README
+  const readme = `# ${oad.metadata.name} - Hermes Agent
+
+Converted from OAD format using \`opc deploy --target hermes\`.
+
+## Usage
+
+1. Copy \`character.json\` to your Hermes agents directory
+2. Configure \`.env.hermes\` with your API keys
+3. Start Hermes with this character
+
+## Files
+
+- \`character.json\` - Agent character definition
+- \`settings.json\` - Runtime settings
+- \`.env.hermes\` - Environment template
+`;
+  fs.writeFileSync(path.join(outputDir, 'README.md'), readme, 'utf-8');
+  files.push('README.md');
+
+  return { outputDir, files };
+}

package/src/index.ts

@@ -47,3 +47,21 @@ 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';
+
+// v0.5.0+ modules
+export { KnowledgeBase } from './core/knowledge';
+export { deployToHermes } from './deploy/hermes';
+export type { HermesDeployOptions, HermesDeployResult } from './deploy/hermes';
+export { publishAgent, installAgent } from './marketplace';
+export type { AgentManifest, PublishOptions, InstallOptions } from './marketplace';
+
+// v0.7.0 modules
+export { createAuthMiddleware, getActiveSessions } from './core/auth';
+export type { AuthConfig, AuthSession } from './core/auth';
+export { HttpSkill } from './skills/http';
+export { WebhookTriggerSkill } from './skills/webhook-trigger';
+export type { WebhookTarget } from './skills/webhook-trigger';
+export { SchedulerSkill } from './skills/scheduler';
+export type { ScheduledTask } from './skills/scheduler';
+export { DocumentSkill } from './skills/document';
+export type { DocumentChunk } from './skills/document';

package/src/marketplace/index.ts

@@ -0,0 +1,223 @@
+/**
+ * Agent Marketplace - Package, publish, and install agents
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { execSync } from 'child_process';
+
+export interface AgentManifest {
+  name: string;
+  version: string;
+  description: string;
+  author: string;
+  license: string;
+  oadVersion: string;
+  channels: string[];
+  skills: string[];
+  files: string[];
+  checksum: string;
+  publishedAt: string;
+  homepage?: string;
+  repository?: string;
+  tags?: string[];
+}
+
+export interface PublishOptions {
+  oadPath: string;
+  outputDir?: string;
+  includeKnowledge?: boolean;
+}
+
+export interface InstallOptions {
+  source: string; // local path or URL
+  targetDir?: string;
+}
+
+function computeChecksum(filePath: string): string {
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+export async function publishAgent(options: PublishOptions): Promise<{ archivePath: string; manifest: AgentManifest }> {
+  const { oadPath, outputDir = '.', includeKnowledge = false } = options;
+  const absOad = path.resolve(oadPath);
+  const baseDir = path.dirname(absOad);
+
+  if (!fs.existsSync(absOad)) {
+    throw new Error(`OAD file not found: ${absOad}`);
+  }
+
+  // Dynamic import yaml
+  const yaml = await import('js-yaml');
+  const oadContent = fs.readFileSync(absOad, 'utf-8');
+  const oad = yaml.load(oadContent) as any;
+
+  const name = oad.metadata?.name ?? 'unnamed-agent';
+  const version = oad.metadata?.version ?? '0.0.0';
+  const safeName = name.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+
+  // Collect files to package
+  const filesToPack: { rel: string; abs: string }[] = [
+    { rel: path.basename(absOad), abs: absOad },
+  ];
+
+  // Include common files
+  const extras = ['.env.example', 'README.md', 'package.json'];
+  for (const f of extras) {
+    const fp = path.join(baseDir, f);
+    if (fs.existsSync(fp)) {
+      filesToPack.push({ rel: f, abs: fp });
+    }
+  }
+
+  // Include knowledge base if requested
+  if (includeKnowledge) {
+    const kbFile = path.join(baseDir, '.opc-knowledge.json');
+    if (fs.existsSync(kbFile)) {
+      filesToPack.push({ rel: '.opc-knowledge.json', abs: kbFile });
+    }
+  }
+
+  // Include prompts directory if exists
+  const promptsDir = path.join(baseDir, 'prompts');
+  if (fs.existsSync(promptsDir) && fs.statSync(promptsDir).isDirectory()) {
+    const promptFiles = fs.readdirSync(promptsDir);
+    for (const pf of promptFiles) {
+      filesToPack.push({ rel: `prompts/${pf}`, abs: path.join(promptsDir, pf) });
+    }
+  }
+
+  // Build manifest
+  const manifest: AgentManifest = {
+    name: safeName,
+    version,
+    description: oad.metadata?.description ?? '',
+    author: oad.metadata?.author ?? '',
+    license: oad.metadata?.license ?? 'Apache-2.0',
+    oadVersion: 'opc/v1',
+    channels: (oad.spec?.channels ?? []).map((c: any) => c.type),
+    skills: (oad.spec?.skills ?? []).map((s: any) => s.name),
+    files: filesToPack.map(f => f.rel),
+    checksum: '',
+    publishedAt: new Date().toISOString(),
+    tags: oad.metadata?.marketplace?.tags,
+  };
+
+  // Create staging directory
+  const stageDir = path.join(outputDir, `.opc-stage-${safeName}`);
+  fs.mkdirSync(stageDir, { recursive: true });
+
+  for (const f of filesToPack) {
+    const dest = path.join(stageDir, f.rel);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(f.abs, dest);
+  }
+
+  // Write manifest
+  fs.writeFileSync(path.join(stageDir, 'opc-manifest.json'), JSON.stringify(manifest, null, 2));
+
+  // Create tar.gz
+  const archiveName = `${safeName}-${version}.tar.gz`;
+  const archivePath = path.join(outputDir, archiveName);
+
+  try {
+    execSync(`tar -czf "${archivePath}" -C "${stageDir}" .`, { stdio: 'pipe' });
+  } catch {
+    // Fallback: just zip the directory content list
+    // On Windows without tar, create a simple zip-like package
+    const packageData = {
+      manifest,
+      files: filesToPack.map(f => ({
+        path: f.rel,
+        content: fs.readFileSync(f.abs, 'utf-8'),
+      })),
+    };
+    fs.writeFileSync(
+      archivePath.replace('.tar.gz', '.opc.json'),
+      JSON.stringify(packageData, null, 2),
+    );
+  }
+
+  // Compute checksum
+  if (fs.existsSync(archivePath)) {
+    manifest.checksum = computeChecksum(archivePath);
+  }
+
+  // Cleanup staging
+  fs.rmSync(stageDir, { recursive: true, force: true });
+
+  // Write final manifest
+  fs.writeFileSync(
+    path.join(outputDir, 'opc-manifest.json'),
+    JSON.stringify(manifest, null, 2),
+  );
+
+  return { archivePath: fs.existsSync(archivePath) ? archivePath : archivePath.replace('.tar.gz', '.opc.json'), manifest };
+}
+
+export async function installAgent(options: InstallOptions): Promise<{ dir: string; manifest: AgentManifest }> {
+  const { source, targetDir } = options;
+  const absSource = path.resolve(source);
+
+  if (!fs.existsSync(absSource)) {
+    throw new Error(`Package not found: ${absSource}`);
+  }
+
+  let manifest: AgentManifest;
+  let installDir: string;
+
+  if (absSource.endsWith('.opc.json')) {
+    // JSON package format
+    const pkg = JSON.parse(fs.readFileSync(absSource, 'utf-8'));
+    manifest = pkg.manifest;
+    installDir = targetDir ?? path.join('.', manifest.name);
+    fs.mkdirSync(installDir, { recursive: true });
+
+    for (const f of pkg.files) {
+      const dest = path.join(installDir, f.path);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, f.content, 'utf-8');
+    }
+    fs.writeFileSync(path.join(installDir, 'opc-manifest.json'), JSON.stringify(manifest, null, 2));
+  } else {
+    // tar.gz format
+    const tmpDir = path.join(path.dirname(absSource), '.opc-extract-tmp');
+    fs.mkdirSync(tmpDir, { recursive: true });
+
+    try {
+      execSync(`tar -xzf "${absSource}" -C "${tmpDir}"`, { stdio: 'pipe' });
+    } catch {
+      throw new Error('Failed to extract package. Ensure tar is available.');
+    }
+
+    const manifestPath = path.join(tmpDir, 'opc-manifest.json');
+    if (!fs.existsSync(manifestPath)) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+      throw new Error('Invalid package: missing opc-manifest.json');
+    }
+
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    installDir = targetDir ?? path.join('.', manifest.name);
+
+    // Move files
+    fs.mkdirSync(installDir, { recursive: true });
+    const copyRecursive = (src: string, dest: string) => {
+      const entries = fs.readdirSync(src, { withFileTypes: true });
+      for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+          fs.mkdirSync(destPath, { recursive: true });
+          copyRecursive(srcPath, destPath);
+        } else {
+          fs.copyFileSync(srcPath, destPath);
+        }
+      }
+    };
+    copyRecursive(tmpDir, installDir);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+
+  return { dir: installDir, manifest };
+}

package/src/schema/oad.ts

@@ -48,6 +48,12 @@ export const HITLSchema = z.object({
   defaultAction: z.enum(['approve', 'deny']).default('deny'),
 });
 
+export const AuthSchema = z.object({
+  enabled: z.boolean().default(false),
+  apiKeys: z.array(z.string()).default([]),
+  sessionIsolation: z.boolean().default(true),
+});
+
 export const ChannelSchema = z.object({
   type: z.enum(['web', 'websocket', 'telegram', 'cli', 'voice', 'webhook']),
   port: z.number().optional(),
@@ -124,6 +130,7 @@ export const SpecSchema = z.object({
   voice: VoiceSchema.optional(),
   webhook: WebhookSchema.optional(),
   hitl: HITLSchema.optional(),
+  auth: AuthSchema.optional(),
 });
 
 export const OADSchema = z.object({