opc-agent 1.4.0 → 1.4.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/fast-mode.ts

@@ -0,0 +1,75 @@
+// ─── Fast Mode Router ────────────────────────────────────────
+// Higher-level fast mode abstraction on top of PriorityRouter.
+// Routes requests through priority queues for lower latency on supported models.
+
+export interface FastModeConfig {
+  enabled: boolean;
+  supportedModels: string[];
+  priorityTier: 'standard' | 'fast' | 'turbo';
+}
+
+export interface FastModeStats {
+  requestsRouted: number;
+  avgLatencySavingMs: number;
+}
+
+export class FastModeRouter {
+  private config: FastModeConfig;
+  private requestsRouted: number = 0;
+  private totalLatencySavingMs: number = 0;
+
+  constructor(config: FastModeConfig) {
+    this.config = { ...config };
+  }
+
+  /** Check if a model supports fast mode */
+  isSupported(model: string): boolean {
+    return this.config.supportedModels.some((pattern) => {
+      if (pattern.endsWith('*')) {
+        return model.startsWith(pattern.slice(0, -1));
+      }
+      return model === pattern;
+    });
+  }
+
+  /**
+   * Get the fast-mode endpoint for a model.
+   * Appends /fast suffix or priority query param based on tier.
+   */
+  getEndpoint(model: string, baseEndpoint: string): string {
+    if (!this.config.enabled || !this.isSupported(model)) {
+      return baseEndpoint;
+    }
+
+    this.requestsRouted++;
+    // Estimate ~120ms saving for fast, ~200ms for turbo
+    this.totalLatencySavingMs += this.config.priorityTier === 'turbo' ? 200 : 120;
+
+    const separator = baseEndpoint.includes('?') ? '&' : '?';
+
+    if (this.config.priorityTier === 'turbo') {
+      // Turbo uses a dedicated /fast path
+      const url = baseEndpoint.replace(/\/$/, '');
+      return `${url}/fast`;
+    }
+
+    // Fast tier uses query param
+    return `${baseEndpoint}${separator}priority=${this.config.priorityTier}`;
+  }
+
+  /** Toggle enabled state, return new state */
+  toggle(): boolean {
+    this.config.enabled = !this.config.enabled;
+    return this.config.enabled;
+  }
+
+  /** Get routing stats */
+  getStats(): FastModeStats {
+    return {
+      requestsRouted: this.requestsRouted,
+      avgLatencySavingMs: this.requestsRouted > 0
+        ? Math.round(this.totalLatencySavingMs / this.requestsRouted)
+        : 0,
+    };
+  }
+}

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,
+    };
+  }
+}