opc-agent 3.0.0 → 4.0.0

package/src/core/audio.ts

@@ -0,0 +1,98 @@
+/**
+ * Audio Processor - v1.0.0
+ * Audio transcription/synthesis wrappers with format detection, duration, split.
+ */
+
+export type AudioFormat = 'wav' | 'mp3' | 'ogg' | 'flac' | 'webm' | 'aac' | 'unknown';
+
+export interface TranscribeOptions {
+  language?: string;
+  model?: string;
+  provider?: string;
+}
+
+export interface SynthesizeOptions {
+  voice?: string;
+  speed?: number;
+  format?: AudioFormat;
+  provider?: string;
+}
+
+export interface TranscribeResult {
+  text: string;
+  language?: string;
+  duration?: number;
+  segments?: { start: number; end: number; text: string }[];
+}
+
+export interface SynthesizeResult {
+  audio: Buffer;
+  format: AudioFormat;
+  duration?: number;
+}
+
+export type TranscribeFunction = (audio: Buffer, options?: TranscribeOptions) => Promise<TranscribeResult>;
+export type SynthesizeFunction = (text: string, options?: SynthesizeOptions) => Promise<SynthesizeResult>;
+
+const FORMAT_SIGNATURES: [Buffer, AudioFormat][] = [
+  [Buffer.from('RIFF'), 'wav'],
+  [Buffer.from([0xff, 0xfb]), 'mp3'],
+  [Buffer.from([0xff, 0xf3]), 'mp3'],
+  [Buffer.from([0xff, 0xf2]), 'mp3'],
+  [Buffer.from([0x49, 0x44, 0x33]), 'mp3'], // ID3
+  [Buffer.from('OggS'), 'ogg'],
+  [Buffer.from('fLaC'), 'flac'],
+  [Buffer.from([0x1a, 0x45, 0xdf, 0xa3]), 'webm'],
+];
+
+export class AudioProcessor {
+  private transcribeFn?: TranscribeFunction;
+  private synthesizeFn?: SynthesizeFunction;
+
+  constructor(options?: { transcribe?: TranscribeFunction; synthesize?: SynthesizeFunction }) {
+    this.transcribeFn = options?.transcribe;
+    this.synthesizeFn = options?.synthesize;
+  }
+
+  /** Detect audio format from buffer header */
+  static detectFormat(audio: Buffer): AudioFormat {
+    for (const [sig, fmt] of FORMAT_SIGNATURES) {
+      if (audio.length >= sig.length && audio.subarray(0, sig.length).equals(sig)) return fmt;
+    }
+    return 'unknown';
+  }
+
+  /** Estimate duration in seconds for WAV files (for others returns undefined) */
+  static estimateDuration(audio: Buffer): number | undefined {
+    const fmt = AudioProcessor.detectFormat(audio);
+    if (fmt === 'wav' && audio.length >= 44) {
+      const sampleRate = audio.readUInt32LE(24);
+      const byteRate = audio.readUInt32LE(28);
+      if (byteRate > 0) {
+        const dataSize = audio.length - 44;
+        return dataSize / byteRate;
+      }
+    }
+    return undefined;
+  }
+
+  /** Split audio buffer into chunks of roughly `chunkBytes` size */
+  static split(audio: Buffer, chunkBytes: number): Buffer[] {
+    if (chunkBytes <= 0) throw new Error('chunkBytes must be positive');
+    const chunks: Buffer[] = [];
+    for (let i = 0; i < audio.length; i += chunkBytes) {
+      chunks.push(audio.subarray(i, Math.min(i + chunkBytes, audio.length)));
+    }
+    return chunks;
+  }
+
+  async transcribe(audio: Buffer, options?: TranscribeOptions): Promise<TranscribeResult> {
+    if (!this.transcribeFn) throw new Error('No transcribe provider configured');
+    return this.transcribeFn(audio, options);
+  }
+
+  async synthesize(text: string, options?: SynthesizeOptions): Promise<SynthesizeResult> {
+    if (!this.synthesizeFn) throw new Error('No synthesize provider configured');
+    return this.synthesizeFn(text, options);
+  }
+}

package/src/core/context-discovery.ts

@@ -0,0 +1,85 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface ContextFile {
+  path: string;
+  type: 'agents' | 'soul' | 'user' | 'memory' | 'tools' | 'identity' | 'heartbeat' | 'bootstrap' | 'custom';
+  content: string;
+}
+
+const FILE_TYPE_MAP: Record<string, ContextFile['type']> = {
+  'AGENTS.md': 'agents',
+  'SOUL.md': 'soul',
+  'USER.md': 'user',
+  'MEMORY.md': 'memory',
+  'TOOLS.md': 'tools',
+  'IDENTITY.md': 'identity',
+  'HEARTBEAT.md': 'heartbeat',
+  'BOOTSTRAP.md': 'bootstrap',
+  '.opc.md': 'custom',
+  '.opc/config.md': 'custom',
+};
+
+export class ContextDiscovery {
+  static STANDARD_FILES = [
+    'AGENTS.md', 'SOUL.md', 'USER.md', 'MEMORY.md', 'TOOLS.md',
+    'IDENTITY.md', 'HEARTBEAT.md', 'BOOTSTRAP.md',
+    '.opc.md', '.opc/config.md',
+  ];
+
+  private customFiles: string[] = [];
+  private watchers: fs.FSWatcher[] = [];
+
+  discover(workDir?: string): ContextFile[] {
+    const dir = workDir || process.cwd();
+    const found: ContextFile[] = [];
+
+    for (const file of ContextDiscovery.STANDARD_FILES) {
+      const fullPath = path.join(dir, file);
+      if (fs.existsSync(fullPath)) {
+        found.push({
+          path: fullPath,
+          type: FILE_TYPE_MAP[file] || 'custom',
+          content: fs.readFileSync(fullPath, 'utf-8'),
+        });
+      }
+    }
+
+    for (const file of this.customFiles) {
+      const fullPath = path.isAbsolute(file) ? file : path.join(dir, file);
+      if (fs.existsSync(fullPath)) {
+        found.push({
+          path: fullPath,
+          type: 'custom',
+          content: fs.readFileSync(fullPath, 'utf-8'),
+        });
+      }
+    }
+
+    return found;
+  }
+
+  load(files: ContextFile[]): string {
+    return files.map(f => `# ${f.type.toUpperCase()}\n${f.content}`).join('\n\n');
+  }
+
+  watch(workDir: string, onChange: Function): void {
+    const watcher = fs.watch(workDir, { recursive: false }, (event, filename) => {
+      if (filename && ContextDiscovery.STANDARD_FILES.includes(filename)) {
+        onChange(filename, event);
+      }
+    });
+    this.watchers.push(watcher);
+  }
+
+  stopWatching(): void {
+    for (const w of this.watchers) w.close();
+    this.watchers = [];
+  }
+
+  addCustomFile(filePath: string): void {
+    if (!this.customFiles.includes(filePath)) {
+      this.customFiles.push(filePath);
+    }
+  }
+}

package/src/core/context-refs.ts

@@ -0,0 +1,140 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+
+export type RefType = 'file' | 'folder' | 'url' | 'git-diff' | 'git-log';
+
+export interface ContextRef {
+  type: RefType;
+  path: string;
+  content?: string;
+}
+
+export interface Message {
+  role: string;
+  content: string;
+  [key: string]: unknown;
+}
+
+const MAX_CONTENT_LENGTH = 5000;
+
+function truncate(text: string, max: number = MAX_CONTENT_LENGTH): string {
+  if (text.length <= max) return text;
+  return text.slice(0, max) + `\n...[truncated, ${text.length - max} chars omitted]`;
+}
+
+export class ContextRefResolver {
+  /**
+   * Parse @-references from text without resolving content.
+   */
+  parseRefs(text: string): ContextRef[] {
+    const refs: ContextRef[] = [];
+    const patterns: [RegExp, RefType, (m: RegExpMatchArray) => string][] = [
+      [/@file:(\S+)/g, 'file', (m) => m[1]],
+      [/@folder:(\S+)/g, 'folder', (m) => m[1]],
+      [/@url:(https?:\/\/\S+)/g, 'url', (m) => m[1]],
+      [/@git-diff\b/g, 'git-diff', () => 'git-diff'],
+      [/@git-log:(\d+)/g, 'git-log', (m) => m[1]],
+      [/@git-log\b(?!:)/g, 'git-log', () => '10'],
+    ];
+
+    for (const [regex, type, extract] of patterns) {
+      let match: RegExpExecArray | null;
+      while ((match = regex.exec(text)) !== null) {
+        refs.push({ type, path: extract(match) });
+      }
+    }
+    return refs;
+  }
+
+  /**
+   * Resolve content for each ref. Returns new array with content filled in.
+   */
+  async resolveRefs(refs: ContextRef[]): Promise<ContextRef[]> {
+    return Promise.all(refs.map(async (ref) => {
+      try {
+        const content = await this.resolveOne(ref);
+        return { ...ref, content: truncate(content) };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ...ref, content: `[Error resolving @${ref.type}:${ref.path}]: ${msg}` };
+      }
+    }));
+  }
+
+  private async resolveOne(ref: ContextRef): Promise<string> {
+    switch (ref.type) {
+      case 'file':
+        return fs.readFileSync(ref.path, 'utf-8');
+      case 'folder':
+        return this.listDir(ref.path);
+      case 'url':
+        return await this.fetchUrl(ref.path);
+      case 'git-diff':
+        return execSync('git diff', { encoding: 'utf-8', timeout: 10000 });
+      case 'git-log': {
+        const n = parseInt(ref.path) || 10;
+        return execSync(`git log --oneline -${n}`, { encoding: 'utf-8', timeout: 10000 });
+      }
+      default:
+        return `[Unknown ref type: ${ref.type}]`;
+    }
+  }
+
+  private listDir(dirPath: string, prefix: string = '', depth: number = 0): string {
+    if (depth > 5) return prefix + '...(max depth)\n';
+    if (!fs.existsSync(dirPath)) throw new Error(`Directory not found: ${dirPath}`);
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    let result = '';
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      result += `${prefix}${entry.isDirectory() ? '📁 ' : '📄 '}${entry.name}\n`;
+      if (entry.isDirectory()) {
+        result += this.listDir(path.join(dirPath, entry.name), prefix + '  ', depth + 1);
+      }
+    }
+    return result;
+  }
+
+  private async fetchUrl(url: string): Promise<string> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 10000);
+    try {
+      const res = await fetch(url, { signal: controller.signal });
+      const text = await res.text();
+      return text;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  /**
+   * Inject resolved refs as system messages before the user's last message.
+   */
+  injectRefs(messages: Message[], refs: ContextRef[]): Message[] {
+    if (refs.length === 0) return messages;
+
+    const resolvedRefs = refs.filter(r => r.content);
+    if (resolvedRefs.length === 0) return messages;
+
+    const contextMessages: Message[] = resolvedRefs.map(ref => ({
+      role: 'system',
+      content: `[Context from @${ref.type}:${ref.path}]\n\`\`\`\n${ref.content}\n\`\`\``,
+    }));
+
+    // Insert before the last user message
+    const result = [...messages];
+    let lastUserIdx = -1;
+    for (let i = result.length - 1; i >= 0; i--) {
+      if (result[i].role === 'user') { lastUserIdx = i; break; }
+    }
+
+    if (lastUserIdx >= 0) {
+      result.splice(lastUserIdx, 0, ...contextMessages);
+    } else {
+      result.push(...contextMessages);
+    }
+
+    return result;
+  }
+}

package/src/core/gateway.ts

@@ -0,0 +1,106 @@
+import { EventEmitter } from 'events';
+import { randomUUID } from 'crypto';
+
+export interface AgentConfig {
+  id: string;
+  name: string;
+  model?: string;
+  skills?: string[];
+}
+
+export interface ChannelConfig {
+  id: string;
+  type: string;
+  config?: Record<string, unknown>;
+}
+
+export interface GatewayConfig {
+  port: number;
+  agents: AgentConfig[];
+  channels: ChannelConfig[];
+}
+
+interface GatewayMessage {
+  id: string;
+  content: string;
+  channel: string;
+  timestamp: number;
+}
+
+export class Gateway extends EventEmitter {
+  private config: GatewayConfig;
+  private agents = new Map<string, AgentConfig>();
+  private channels = new Map<string, ChannelConfig>();
+  private running = false;
+  private startTime = 0;
+  private messagesProcessed = 0;
+  private latencies: number[] = [];
+  private errors = 0;
+
+  constructor(config: GatewayConfig) {
+    super();
+    this.config = config;
+    for (const a of config.agents) this.agents.set(a.id, a);
+    for (const c of config.channels) this.channels.set(c.id, c);
+  }
+
+  async start(): Promise<void> {
+    if (this.running) throw new Error('Gateway already running');
+    this.running = true;
+    this.startTime = Date.now();
+    this.emit('started');
+  }
+
+  async stop(): Promise<void> {
+    if (!this.running) throw new Error('Gateway not running');
+    this.running = false;
+    this.emit('stopped');
+  }
+
+  async routeMessage(message: GatewayMessage, channel: string): Promise<string> {
+    if (!this.running) throw new Error('Gateway not running');
+    const start = Date.now();
+    this.messagesProcessed++;
+    // Simple round-robin routing
+    const agentIds = Array.from(this.agents.keys());
+    if (agentIds.length === 0) {
+      this.errors++;
+      throw new Error('No agents available');
+    }
+    const agentId = agentIds[this.messagesProcessed % agentIds.length];
+    this.latencies.push(Date.now() - start);
+    return agentId;
+  }
+
+  addAgent(config: AgentConfig): void {
+    this.agents.set(config.id, config);
+  }
+
+  removeAgent(id: string): void {
+    if (!this.agents.has(id)) throw new Error(`Agent ${id} not found`);
+    this.agents.delete(id);
+  }
+
+  addChannel(config: ChannelConfig): void {
+    this.channels.set(config.id, config);
+  }
+
+  getStatus(): { uptime: number; agents: number; channels: number; messagesProcessed: number } {
+    return {
+      uptime: this.running ? Date.now() - this.startTime : 0,
+      agents: this.agents.size,
+      channels: this.channels.size,
+      messagesProcessed: this.messagesProcessed,
+    };
+  }
+
+  getMetrics(): { messagesPerMinute: number; avgLatency: number; errorRate: number } {
+    const upMinutes = this.running ? (Date.now() - this.startTime) / 60000 : 1;
+    const avgLatency = this.latencies.length ? this.latencies.reduce((a, b) => a + b, 0) / this.latencies.length : 0;
+    return {
+      messagesPerMinute: this.messagesProcessed / Math.max(upMinutes, 0.001),
+      avgLatency,
+      errorRate: this.messagesProcessed ? this.errors / this.messagesProcessed : 0,
+    };
+  }
+}

package/src/core/heartbeat.ts

@@ -0,0 +1,51 @@
+export interface HeartbeatConfig {
+  interval: number;
+  checkFn: () => Promise<string>;
+}
+
+export class HeartbeatManager {
+  private config: HeartbeatConfig;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private callbacks: ((status: string) => void)[] = [];
+  private lastBeat: { timestamp: number; status: string } | null = null;
+
+  constructor(config: HeartbeatConfig) {
+    if (!config.interval || config.interval < 100) {
+      throw new Error('HeartbeatManager requires interval >= 100ms');
+    }
+    if (typeof config.checkFn !== 'function') {
+      throw new Error('HeartbeatManager requires checkFn');
+    }
+    this.config = config;
+  }
+
+  start(): void {
+    if (this.timer) return;
+    this.timer = setInterval(async () => {
+      try {
+        const status = await this.config.checkFn();
+        this.lastBeat = { timestamp: Date.now(), status };
+        for (const cb of this.callbacks) cb(status);
+      } catch (err: any) {
+        const status = `error: ${err.message}`;
+        this.lastBeat = { timestamp: Date.now(), status };
+        for (const cb of this.callbacks) cb(status);
+      }
+    }, this.config.interval);
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+
+  onBeat(callback: (status: string) => void): void {
+    this.callbacks.push(callback);
+  }
+
+  getLastBeat(): { timestamp: number; status: string } | null {
+    return this.lastBeat;
+  }
+}

package/src/core/hooks.ts

@@ -0,0 +1,105 @@
+/**
+ * Hooks Module - v1.0.0
+ * Event hook system with priority ordering and context modification.
+ */
+
+export type HookEvent =
+  | 'before:message' | 'after:message'
+  | 'before:tool' | 'after:tool'
+  | 'before:llm' | 'after:llm'
+  | 'before:send' | 'after:send'
+  | 'before:learn' | 'after:learn'
+  | 'before:recall' | 'after:recall'
+  | 'on:error' | 'on:start' | 'on:stop';
+
+export const ALL_HOOK_EVENTS: HookEvent[] = [
+  'before:message', 'after:message',
+  'before:tool', 'after:tool',
+  'before:llm', 'after:llm',
+  'before:send', 'after:send',
+  'before:learn', 'after:learn',
+  'before:recall', 'after:recall',
+  'on:error', 'on:start', 'on:stop',
+];
+
+export interface HookContext {
+  [key: string]: unknown;
+}
+
+export type HookHandler = (ctx: HookContext) => HookContext | void | Promise<HookContext | void>;
+
+interface RegisteredHook {
+  id: string;
+  event: HookEvent;
+  handler: HookHandler;
+  priority: number;
+  name?: string;
+}
+
+let hookIdCounter = 0;
+
+export class HookManager {
+  private hooks: Map<HookEvent, RegisteredHook[]> = new Map();
+
+  register(event: HookEvent, handler: HookHandler, options?: { priority?: number; name?: string }): string {
+    const id = `hook_${++hookIdCounter}`;
+    const entry: RegisteredHook = {
+      id,
+      event,
+      handler,
+      priority: options?.priority ?? 100,
+      name: options?.name,
+    };
+    if (!this.hooks.has(event)) this.hooks.set(event, []);
+    const list = this.hooks.get(event)!;
+    list.push(entry);
+    list.sort((a, b) => a.priority - b.priority);
+    return id;
+  }
+
+  unregister(id: string): boolean {
+    for (const [event, list] of this.hooks) {
+      const idx = list.findIndex(h => h.id === id);
+      if (idx !== -1) {
+        list.splice(idx, 1);
+        return true;
+      }
+    }
+    return false;
+  }
+
+  async run(event: HookEvent, ctx: HookContext = {}): Promise<HookContext> {
+    const list = this.hooks.get(event);
+    if (!list || list.length === 0) return ctx;
+    let current = { ...ctx };
+    for (const hook of list) {
+      const result = await hook.handler(current);
+      if (result) current = { ...current, ...result };
+    }
+    return current;
+  }
+
+  getRegistered(event?: HookEvent): { id: string; event: HookEvent; priority: number; name?: string }[] {
+    const results: { id: string; event: HookEvent; priority: number; name?: string }[] = [];
+    const events = event ? [event] : ALL_HOOK_EVENTS;
+    for (const e of events) {
+      const list = this.hooks.get(e) ?? [];
+      for (const h of list) {
+        results.push({ id: h.id, event: h.event, priority: h.priority, name: h.name });
+      }
+    }
+    return results;
+  }
+
+  clear(event?: HookEvent): void {
+    if (event) {
+      this.hooks.delete(event);
+    } else {
+      this.hooks.clear();
+    }
+  }
+
+  hasHooks(event: HookEvent): boolean {
+    return (this.hooks.get(event)?.length ?? 0) > 0;
+  }
+}