opc-agent 4.1.1 → 4.1.3

package/src/core/context-refs.ts

@@ -1,140 +0,0 @@
-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/errors.ts

@@ -1,148 +0,0 @@
-/**
- * OPC Agent Error Hierarchy - v1.0.0
- * Custom error classes with user-friendly messages and recovery hints.
- */
-
-export class OPCError extends Error {
-  public readonly code: string;
-  public readonly hint?: string;
-  public readonly context?: Record<string, unknown>;
-  public readonly timestamp = Date.now();
-
-  constructor(message: string, opts?: { code?: string; hint?: string; context?: Record<string, unknown>; cause?: Error }) {
-    super(message);
-    this.name = 'OPCError';
-    this.code = opts?.code ?? 'OPC_UNKNOWN';
-    this.hint = opts?.hint;
-    this.context = opts?.context;
-    if (opts?.cause) this.cause = opts.cause;
-  }
-
-  toJSON(): Record<string, unknown> {
-    return { name: this.name, code: this.code, message: this.message, hint: this.hint, context: this.context, timestamp: this.timestamp };
-  }
-
-  toUserMessage(): string {
-    return this.hint ? `${this.message}\n💡 ${this.hint}` : this.message;
-  }
-}
-
-export class ProviderError extends OPCError {
-  public readonly provider: string;
-  public readonly statusCode?: number;
-
-  constructor(provider: string, message: string, opts?: { statusCode?: number; hint?: string; cause?: Error }) {
-    super(message, {
-      code: 'OPC_PROVIDER_ERROR',
-      hint: opts?.hint ?? `Check your API key and network connection for ${provider}.`,
-      context: { provider, statusCode: opts?.statusCode },
-      cause: opts?.cause,
-    });
-    this.name = 'ProviderError';
-    this.provider = provider;
-    this.statusCode = opts?.statusCode;
-  }
-}
-
-export class ValidationError extends OPCError {
-  public readonly field?: string;
-  public readonly errors: string[];
-
-  constructor(message: string, errors: string[] = [], field?: string) {
-    super(message, {
-      code: 'OPC_VALIDATION_ERROR',
-      hint: 'Check your OAD configuration file for missing or invalid fields.',
-      context: { field, errors },
-    });
-    this.name = 'ValidationError';
-    this.field = field;
-    this.errors = errors;
-  }
-}
-
-export class ConfigError extends OPCError {
-  constructor(message: string, hint?: string) {
-    super(message, { code: 'OPC_CONFIG_ERROR', hint: hint ?? 'Check your oad.yaml and .env files.' });
-    this.name = 'ConfigError';
-  }
-}
-
-export class ChannelError extends OPCError {
-  public readonly channelType: string;
-
-  constructor(channelType: string, message: string, opts?: { hint?: string; cause?: Error }) {
-    super(message, {
-      code: 'OPC_CHANNEL_ERROR',
-      hint: opts?.hint ?? `Check configuration for the ${channelType} channel.`,
-      context: { channelType },
-      cause: opts?.cause,
-    });
-    this.name = 'ChannelError';
-    this.channelType = channelType;
-  }
-}
-
-export class PluginError extends OPCError {
-  public readonly pluginName: string;
-
-  constructor(pluginName: string, message: string, opts?: { hint?: string; cause?: Error }) {
-    super(message, {
-      code: 'OPC_PLUGIN_ERROR',
-      hint: opts?.hint ?? `Check plugin "${pluginName}" configuration.`,
-      context: { pluginName },
-      cause: opts?.cause,
-    });
-    this.name = 'PluginError';
-    this.pluginName = pluginName;
-  }
-}
-
-export class RateLimitError extends OPCError {
-  public readonly retryAfterMs?: number;
-
-  constructor(message?: string, retryAfterMs?: number) {
-    super(message ?? 'Rate limit exceeded. Please slow down.', {
-      code: 'OPC_RATE_LIMIT',
-      hint: retryAfterMs ? `Try again in ${Math.ceil(retryAfterMs / 1000)} seconds.` : 'Please wait before sending more messages.',
-      context: { retryAfterMs },
-    });
-    this.name = 'RateLimitError';
-    this.retryAfterMs = retryAfterMs;
-  }
-}
-
-export class SecurityError extends OPCError {
-  constructor(message: string, hint?: string) {
-    super(message, { code: 'OPC_SECURITY_ERROR', hint: hint ?? 'This request was blocked for security reasons.' });
-    this.name = 'SecurityError';
-  }
-}
-
-export class TimeoutError extends OPCError {
-  constructor(operation: string, timeoutMs: number) {
-    super(`Operation "${operation}" timed out after ${timeoutMs}ms`, {
-      code: 'OPC_TIMEOUT',
-      hint: 'The operation took too long. Try again or increase the timeout.',
-      context: { operation, timeoutMs },
-    });
-    this.name = 'TimeoutError';
-  }
-}
-
-/**
- * Wrap an unknown thrown value into an OPCError.
- */
-export function wrapError(err: unknown, fallbackMessage = 'An unexpected error occurred'): OPCError {
-  if (err instanceof OPCError) return err;
-  if (err instanceof Error) return new OPCError(err.message, { cause: err });
-  return new OPCError(typeof err === 'string' ? err : fallbackMessage);
-}
-
-/**
- * Format error for user display (no stack traces).
- */
-export function formatErrorForUser(err: unknown): string {
-  if (err instanceof OPCError) return err.toUserMessage();
-  if (err instanceof Error) return err.message;
-  return String(err);
-}

package/src/core/gateway.ts

@@ -1,106 +0,0 @@
-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

@@ -1,51 +0,0 @@
-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/hitl.ts

@@ -1,138 +0,0 @@
-import { EventEmitter } from 'events';
-import { Logger } from './logger';
-
-// ── HITL Types ──────────────────────────────────────────────
-
-export interface ApprovalRequest {
-  id: string;
-  action: string;
-  description: string;
-  context?: Record<string, unknown>;
-  timeoutMs: number;
-  defaultAction: 'approve' | 'deny';
-  createdAt: number;
-}
-
-export interface ApprovalResponse {
-  requestId: string;
-  decision: 'approve' | 'deny';
-  respondedBy?: string;
-  respondedAt: number;
-  timedOut: boolean;
-}
-
-export type ApprovalHandler = (request: ApprovalRequest) => Promise<ApprovalResponse>;
-
-export interface HITLConfig {
-  /** Actions that always require approval */
-  requireApproval: string[];
-  /** Default timeout in ms */
-  defaultTimeoutMs: number;
-  /** Default action on timeout */
-  defaultAction: 'approve' | 'deny';
-}
-
-// ── HITL Manager ────────────────────────────────────────────
-
-export class HITLManager extends EventEmitter {
-  private config: HITLConfig;
-  private handler: ApprovalHandler | null = null;
-  private pending: Map<string, { request: ApprovalRequest; resolve: (r: ApprovalResponse) => void }> = new Map();
-  private logger = new Logger('hitl');
-
-  constructor(config?: Partial<HITLConfig>) {
-    super();
-    this.config = {
-      requireApproval: config?.requireApproval ?? [],
-      defaultTimeoutMs: config?.defaultTimeoutMs ?? 60000,
-      defaultAction: config?.defaultAction ?? 'deny',
-    };
-  }
-
-  setHandler(handler: ApprovalHandler): void {
-    this.handler = handler;
-  }
-
-  needsApproval(action: string): boolean {
-    if (this.config.requireApproval.includes('*')) return true;
-    return this.config.requireApproval.includes(action);
-  }
-
-  async requestApproval(action: string, description: string, context?: Record<string, unknown>): Promise<ApprovalResponse> {
-    const request: ApprovalRequest = {
-      id: `hitl_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
-      action,
-      description,
-      context,
-      timeoutMs: this.config.defaultTimeoutMs,
-      defaultAction: this.config.defaultAction,
-      createdAt: Date.now(),
-    };
-
-    this.emit('approval:requested', request);
-    this.logger.info('Approval requested', { id: request.id, action });
-
-    if (this.handler) {
-      try {
-        const response = await Promise.race([
-          this.handler(request),
-          this.createTimeout(request),
-        ]);
-        this.emit('approval:responded', response);
-        return response;
-      } catch {
-        return this.timeoutResponse(request);
-      }
-    }
-
-    // No handler: wait for manual response via respond()
-    return new Promise<ApprovalResponse>((resolve) => {
-      this.pending.set(request.id, { request, resolve });
-
-      setTimeout(() => {
-        if (this.pending.has(request.id)) {
-          this.pending.delete(request.id);
-          const response = this.timeoutResponse(request);
-          this.emit('approval:timeout', response);
-          resolve(response);
-        }
-      }, request.timeoutMs);
-    });
-  }
-
-  respond(requestId: string, decision: 'approve' | 'deny', respondedBy?: string): boolean {
-    const entry = this.pending.get(requestId);
-    if (!entry) return false;
-
-    this.pending.delete(requestId);
-    const response: ApprovalResponse = {
-      requestId,
-      decision,
-      respondedBy,
-      respondedAt: Date.now(),
-      timedOut: false,
-    };
-    entry.resolve(response);
-    this.emit('approval:responded', response);
-    return true;
-  }
-
-  getPending(): ApprovalRequest[] {
-    return Array.from(this.pending.values()).map(e => e.request);
-  }
-
-  private createTimeout(request: ApprovalRequest): Promise<ApprovalResponse> {
-    return new Promise((resolve) => {
-      setTimeout(() => resolve(this.timeoutResponse(request)), request.timeoutMs);
-    });
-  }
-
-  private timeoutResponse(request: ApprovalRequest): ApprovalResponse {
-    return {
-      requestId: request.id,
-      decision: request.defaultAction,
-      respondedAt: Date.now(),
-      timedOut: true,
-    };
-  }
-}

package/src/core/hooks.ts

@@ -1,105 +0,0 @@
-/**
- * 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;
-  }
-}