opc-agent 1.1.3 → 1.2.1

package/src/core/errors.ts

@@ -1,148 +1,148 @@
-/**
- * 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);
-}
+/**
+ * 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/hitl.ts

@@ -1,138 +1,138 @@
-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,
-    };
-  }
-}
+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/knowledge.ts

@@ -1,9 +1,11 @@
 /**
  * Knowledge Base / RAG - Local vector storage with semantic search
+ * Supports optional DeepBrain semantic search enhancement via OPC_DEEPBRAIN_ENABLED=true
  */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as crypto from 'crypto';
+import { spawnSync } from 'child_process';
 
 // Simple in-memory vector store (PGlite-compatible interface for future migration)
 interface VectorEntry {
@@ -180,11 +182,54 @@ export class KnowledgeBase {
   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`;
+    let context = '';
+    if (relevant.length > 0) {
+      context = `\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`;
+    }
+
+    // Enhance with DeepBrain semantic search if enabled
+    const deepBrainCtx = this.queryDeepBrain(query, topK);
+    return context + deepBrainCtx;
+  }
+
+  /**
+   * Query DeepBrain for semantic search enhancement.
+   * Activated when OPC_DEEPBRAIN_ENABLED=true and deepbrain CLI is globally installed.
+   */
+  private queryDeepBrain(query: string, topK: number): string {
+    if (process.env.OPC_DEEPBRAIN_ENABLED !== 'true') return '';
+
+    // Verify deepbrain is installed
+    const check = spawnSync('deepbrain', ['--version'], { encoding: 'utf-8', timeout: 3000 });
+    if (check.error || check.status !== 0) return '';
+
+    try {
+      const result = spawnSync(
+        'deepbrain',
+        ['query', query, '--top', String(topK), '--format', 'json'],
+        { encoding: 'utf-8', timeout: 5000 },
+      );
+      if (result.status !== 0 || !result.stdout?.trim()) return '';
+
+      type DeepBrainResult = { source?: string; score?: number; content?: string; text?: string };
+      const parsed: unknown = JSON.parse(result.stdout);
+      const items: DeepBrainResult[] = Array.isArray(parsed)
+        ? (parsed as DeepBrainResult[])
+        : ((parsed as { results?: DeepBrainResult[] }).results ?? []);
+
+      if (items.length === 0) return '';
+
+      return `\n\n--- DeepBrain Knowledge ---\n${items.map((r, i) => {
+        const relevance = r.score != null ? `${(r.score * 100).toFixed(0)}%` : 'n/a';
+        const text = r.content ?? r.text ?? '';
+        return `[${i + 1}] (source: ${r.source ?? 'deepbrain'}, relevance: ${relevance})\n${text}`;
+      }).join('\n\n')}\n--- End DeepBrain Knowledge ---\n`;
+    } catch {
+      return '';
+    }
   }
 
   getStats(): { totalEntries: number; sources: string[]; updatedAt: string } {