apcore-js 0.4.0 → 0.6.0

package/src/middleware/manager.ts

@@ -1,105 +0,0 @@
-/**
- * MiddlewareManager -- onion model execution engine for the middleware pipeline.
- */
-
-import type { Context } from '../context.js';
-import { ModuleError } from '../errors.js';
-import { Middleware } from './base.js';
-
-export class MiddlewareChainError extends ModuleError {
-  readonly original: Error;
-  readonly executedMiddlewares: Middleware[];
-
-  constructor(original: Error, executedMiddlewares: Middleware[]) {
-    super('MIDDLEWARE_CHAIN_ERROR', String(original));
-    this.name = 'MiddlewareChainError';
-    this.original = original;
-    this.executedMiddlewares = executedMiddlewares;
-  }
-}
-
-export class MiddlewareManager {
-  private _middlewares: Middleware[] = [];
-
-  add(middleware: Middleware): void {
-    this._middlewares.push(middleware);
-  }
-
-  remove(middleware: Middleware): boolean {
-    for (let i = 0; i < this._middlewares.length; i++) {
-      if (this._middlewares[i] === middleware) {
-        this._middlewares.splice(i, 1);
-        return true;
-      }
-    }
-    return false;
-  }
-
-  snapshot(): Middleware[] {
-    return [...this._middlewares];
-  }
-
-  executeBefore(
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    context: Context,
-  ): [Record<string, unknown>, Middleware[]] {
-    let currentInputs = inputs;
-    const executedMiddlewares: Middleware[] = [];
-    const middlewares = this.snapshot();
-
-    for (const mw of middlewares) {
-      executedMiddlewares.push(mw);
-      try {
-        const result = mw.before(moduleId, currentInputs, context);
-        if (result !== null) {
-          currentInputs = result;
-        }
-      } catch (e) {
-        throw new MiddlewareChainError(e as Error, executedMiddlewares);
-      }
-    }
-
-    return [currentInputs, executedMiddlewares];
-  }
-
-  executeAfter(
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    output: Record<string, unknown>,
-    context: Context,
-  ): Record<string, unknown> {
-    let currentOutput = output;
-    const middlewares = this.snapshot();
-
-    for (let i = middlewares.length - 1; i >= 0; i--) {
-      const result = middlewares[i].after(moduleId, inputs, currentOutput, context);
-      if (result !== null) {
-        currentOutput = result;
-      }
-    }
-
-    return currentOutput;
-  }
-
-  executeOnError(
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    error: Error,
-    context: Context,
-    executedMiddlewares: Middleware[],
-  ): Record<string, unknown> | null {
-    for (let i = executedMiddlewares.length - 1; i >= 0; i--) {
-      try {
-        const result = executedMiddlewares[i].onError(moduleId, inputs, error, context);
-        if (result !== null) {
-          return result;
-        }
-      } catch (e) {
-        console.warn('[apcore:middleware] Error in onError handler, continuing:', e);
-        continue;
-      }
-    }
-    return null;
-  }
-}

package/src/module.ts

@@ -1,43 +0,0 @@
-/**
- * Module interface and related data types.
- */
-
-import type { TSchema } from '@sinclair/typebox';
-import type { Context } from './context.js';
-
-export interface ModuleAnnotations {
-  readonly readonly: boolean;
-  readonly destructive: boolean;
-  readonly idempotent: boolean;
-  readonly requiresApproval: boolean;
-  readonly openWorld: boolean;
-  readonly streaming: boolean;
-}
-
-export const DEFAULT_ANNOTATIONS: ModuleAnnotations = Object.freeze({
-  readonly: false,
-  destructive: false,
-  idempotent: false,
-  requiresApproval: false,
-  openWorld: true,
-  streaming: false,
-});
-
-export interface ModuleExample {
-  title: string;
-  inputs: Record<string, unknown>;
-  output: Record<string, unknown>;
-  description?: string;
-}
-
-export interface ValidationResult {
-  valid: boolean;
-  errors: Array<Record<string, string>>;
-}
-
-export interface Module {
-  inputSchema: TSchema;
-  outputSchema: TSchema;
-  description: string;
-  execute(inputs: Record<string, unknown>, context: Context): Promise<Record<string, unknown>> | Record<string, unknown>;
-}

package/src/observability/context-logger.ts

@@ -1,203 +0,0 @@
-/**
- * Structured logging: ContextLogger and ObsLoggingMiddleware.
- */
-
-import type { Context } from '../context.js';
-import { Middleware } from '../middleware/base.js';
-
-const LEVELS: Record<string, number> = {
-  trace: 0,
-  debug: 10,
-  info: 20,
-  warn: 30,
-  error: 40,
-  fatal: 50,
-};
-
-const REDACTED = '***REDACTED***';
-
-interface WritableOutput {
-  write(s: string): void;
-}
-
-export class ContextLogger {
-  private _name: string;
-  private _format: string;
-  private _level: string;
-  private _levelValue: number;
-  private _redactSensitive: boolean;
-  private _output: WritableOutput;
-  private _traceId: string | null = null;
-  private _moduleId: string | null = null;
-  private _callerId: string | null = null;
-
-  constructor(options?: {
-    name?: string;
-    format?: string;
-    level?: string;
-    redactSensitive?: boolean;
-    output?: WritableOutput;
-  }) {
-    this._name = options?.name ?? 'apcore';
-    this._format = options?.format ?? 'json';
-    this._level = options?.level ?? 'info';
-    this._levelValue = LEVELS[this._level] ?? 20;
-    this._redactSensitive = options?.redactSensitive ?? true;
-    this._output = options?.output ?? { write: (s: string) => process.stderr.write(s) };
-  }
-
-  static fromContext(context: Context, name: string, options?: {
-    format?: string;
-    level?: string;
-    redactSensitive?: boolean;
-    output?: WritableOutput;
-  }): ContextLogger {
-    const logger = new ContextLogger({ name, ...options });
-    logger._traceId = context.traceId;
-    logger._moduleId = context.callChain.length > 0 ? context.callChain[context.callChain.length - 1] : null;
-    logger._callerId = context.callerId;
-    return logger;
-  }
-
-  private _emit(levelName: string, message: string, extra?: Record<string, unknown> | null): void {
-    const levelValue = LEVELS[levelName] ?? 20;
-    if (levelValue < this._levelValue) return;
-
-    let redactedExtra = extra ?? null;
-    if (extra != null && this._redactSensitive) {
-      redactedExtra = {};
-      for (const [k, v] of Object.entries(extra)) {
-        (redactedExtra as Record<string, unknown>)[k] = k.startsWith('_secret_') ? REDACTED : v;
-      }
-    }
-
-    const now = new Date();
-    const entry: Record<string, unknown> = {
-      timestamp: now.toISOString(),
-      level: levelName,
-      message,
-      trace_id: this._traceId,
-      module_id: this._moduleId,
-      caller_id: this._callerId,
-      logger: this._name,
-      extra: redactedExtra,
-    };
-
-    if (this._format === 'json') {
-      this._output.write(JSON.stringify(entry) + '\n');
-    } else {
-      const ts = now.toISOString().replace('T', ' ').replace(/\.\d+Z$/, '');
-      const lvl = levelName.toUpperCase();
-      const trace = this._traceId ?? 'none';
-      const mod = this._moduleId ?? 'none';
-      let extrasStr = '';
-      if (redactedExtra) {
-        extrasStr = ' ' + Object.entries(redactedExtra).map(([k, v]) => `${k}=${v}`).join(' ');
-      }
-      this._output.write(`${ts} [${lvl}] [trace=${trace}] [module=${mod}] ${message}${extrasStr}\n`);
-    }
-  }
-
-  trace(message: string, extra?: Record<string, unknown>): void {
-    this._emit('trace', message, extra);
-  }
-
-  debug(message: string, extra?: Record<string, unknown>): void {
-    this._emit('debug', message, extra);
-  }
-
-  info(message: string, extra?: Record<string, unknown>): void {
-    this._emit('info', message, extra);
-  }
-
-  warn(message: string, extra?: Record<string, unknown>): void {
-    this._emit('warn', message, extra);
-  }
-
-  error(message: string, extra?: Record<string, unknown>): void {
-    this._emit('error', message, extra);
-  }
-
-  fatal(message: string, extra?: Record<string, unknown>): void {
-    this._emit('fatal', message, extra);
-  }
-}
-
-export class ObsLoggingMiddleware extends Middleware {
-  private _logger: ContextLogger;
-  private _logInputs: boolean;
-  private _logOutputs: boolean;
-
-  constructor(options?: {
-    logger?: ContextLogger;
-    logInputs?: boolean;
-    logOutputs?: boolean;
-  }) {
-    super();
-    this._logger = options?.logger ?? new ContextLogger({ name: 'apcore.obs_logging' });
-    this._logInputs = options?.logInputs ?? true;
-    this._logOutputs = options?.logOutputs ?? true;
-  }
-
-  override before(
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    context: Context,
-  ): null {
-    const starts = (context.data['_obs_logging_starts'] as number[]) ?? [];
-    starts.push(performance.now());
-    context.data['_obs_logging_starts'] = starts;
-
-    const extra: Record<string, unknown> = {
-      module_id: moduleId,
-      caller_id: context.callerId,
-    };
-    if (this._logInputs) {
-      extra['inputs'] = context.redactedInputs ?? inputs;
-    }
-    this._logger.info('Module call started', extra);
-    return null;
-  }
-
-  override after(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    output: Record<string, unknown>,
-    context: Context,
-  ): null {
-    const starts = context.data['_obs_logging_starts'] as number[] | undefined;
-    if (!starts || starts.length === 0) return null;
-    const startTime = starts.pop()!;
-    const durationMs = performance.now() - startTime;
-
-    const extra: Record<string, unknown> = {
-      module_id: moduleId,
-      duration_ms: durationMs,
-    };
-    if (this._logOutputs) {
-      extra['output'] = output;
-    }
-    this._logger.info('Module call completed', extra);
-    return null;
-  }
-
-  override onError(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    error: Error,
-    context: Context,
-  ): null {
-    const starts = context.data['_obs_logging_starts'] as number[] | undefined;
-    if (!starts || starts.length === 0) return null;
-    const startTime = starts.pop()!;
-    const durationMs = performance.now() - startTime;
-
-    this._logger.error('Module call failed', {
-      module_id: moduleId,
-      duration_ms: durationMs,
-      error_type: error.constructor.name,
-      error_message: String(error),
-    });
-    return null;
-  }
-}

package/src/observability/metrics.ts

@@ -1,214 +0,0 @@
-/**
- * In-memory metrics collection with Prometheus export.
- */
-
-import type { Context } from '../context.js';
-import { ModuleError } from '../errors.js';
-import { Middleware } from '../middleware/base.js';
-
-const DESCRIPTIONS: Record<string, string> = {
-  apcore_module_calls_total: 'Total module calls',
-  apcore_module_errors_total: 'Total module errors',
-  apcore_module_duration_seconds: 'Module execution duration',
-};
-
-function labelsKey(labels: Record<string, string>): string {
-  return Object.entries(labels).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}=${v}`).join(',');
-}
-
-export class MetricsCollector {
-  static readonly DEFAULT_BUCKETS: number[] = [
-    0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0, 60.0,
-  ];
-
-  private _buckets: number[];
-  private _counters: Map<string, number> = new Map();
-  private _histogramSums: Map<string, number> = new Map();
-  private _histogramCounts: Map<string, number> = new Map();
-  private _histogramBuckets: Map<string, number> = new Map();
-
-  constructor(buckets?: number[]) {
-    this._buckets = buckets ? [...buckets].sort((a, b) => a - b) : [...MetricsCollector.DEFAULT_BUCKETS];
-  }
-
-  increment(name: string, labels: Record<string, string>, amount: number = 1): void {
-    const key = `${name}|${labelsKey(labels)}`;
-    this._counters.set(key, (this._counters.get(key) ?? 0) + amount);
-  }
-
-  observe(name: string, labels: Record<string, string>, value: number): void {
-    const lk = labelsKey(labels);
-    const key = `${name}|${lk}`;
-
-    this._histogramSums.set(key, (this._histogramSums.get(key) ?? 0) + value);
-    this._histogramCounts.set(key, (this._histogramCounts.get(key) ?? 0) + 1);
-
-    for (const b of this._buckets) {
-      if (value <= b) {
-        const bkey = `${name}|${lk}|${b}`;
-        this._histogramBuckets.set(bkey, (this._histogramBuckets.get(bkey) ?? 0) + 1);
-      }
-    }
-    // +Inf bucket
-    const infKey = `${name}|${lk}|Inf`;
-    this._histogramBuckets.set(infKey, (this._histogramBuckets.get(infKey) ?? 0) + 1);
-  }
-
-  snapshot(): Record<string, unknown> {
-    return {
-      counters: Object.fromEntries(this._counters),
-      histograms: {
-        sums: Object.fromEntries(this._histogramSums),
-        counts: Object.fromEntries(this._histogramCounts),
-        buckets: Object.fromEntries(this._histogramBuckets),
-      },
-    };
-  }
-
-  reset(): void {
-    this._counters.clear();
-    this._histogramSums.clear();
-    this._histogramCounts.clear();
-    this._histogramBuckets.clear();
-  }
-
-  exportPrometheus(): string {
-    const lines: string[] = [];
-    const counterNames = new Set<string>();
-    const histNames = new Set<string>();
-
-    // Counters
-    for (const [compositeKey, value] of [...this._counters.entries()].sort()) {
-      const [name, lk] = compositeKey.split('|', 2);
-      if (!counterNames.has(name)) {
-        const desc = DESCRIPTIONS[name] ?? name;
-        lines.push(`# HELP ${name} ${desc}`);
-        lines.push(`# TYPE ${name} counter`);
-        counterNames.add(name);
-      }
-      const labelsStr = formatLabels(parseLabels(lk));
-      lines.push(`${name}${labelsStr} ${value}`);
-    }
-
-    // Histograms
-    const histKeys = [...this._histogramSums.keys()].sort();
-    for (const compositeKey of histKeys) {
-      const [name, lk] = compositeKey.split('|', 2);
-      if (!histNames.has(name)) {
-        const desc = DESCRIPTIONS[name] ?? name;
-        lines.push(`# HELP ${name} ${desc}`);
-        lines.push(`# TYPE ${name} histogram`);
-        histNames.add(name);
-      }
-
-      const labelsDict = parseLabels(lk);
-      const labelsStr = formatLabels(labelsDict);
-
-      for (const b of this._buckets) {
-        const bkey = `${name}|${lk}|${b}`;
-        const count = this._histogramBuckets.get(bkey) ?? 0;
-        const leStr = String(b);
-        const leLabels = { ...labelsDict, le: leStr };
-        lines.push(`${name}_bucket${formatLabels(leLabels)} ${count}`);
-      }
-
-      const infKey = `${name}|${lk}|Inf`;
-      const infCount = this._histogramBuckets.get(infKey) ?? 0;
-      const infLabels = { ...labelsDict, le: '+Inf' };
-      lines.push(`${name}_bucket${formatLabels(infLabels)} ${infCount}`);
-
-      const sumVal = this._histogramSums.get(compositeKey) ?? 0;
-      const countVal = this._histogramCounts.get(compositeKey) ?? 0;
-      lines.push(`${name}_sum${labelsStr} ${sumVal}`);
-      lines.push(`${name}_count${labelsStr} ${countVal}`);
-    }
-
-    return lines.length > 0 ? lines.join('\n') + '\n' : '';
-  }
-
-  incrementCalls(moduleId: string, status: string): void {
-    this.increment('apcore_module_calls_total', { module_id: moduleId, status });
-  }
-
-  incrementErrors(moduleId: string, errorCode: string): void {
-    this.increment('apcore_module_errors_total', { module_id: moduleId, error_code: errorCode });
-  }
-
-  observeDuration(moduleId: string, durationSeconds: number): void {
-    this.observe('apcore_module_duration_seconds', { module_id: moduleId }, durationSeconds);
-  }
-}
-
-function parseLabels(lk: string): Record<string, string> {
-  if (!lk) return {};
-  const result: Record<string, string> = {};
-  for (const pair of lk.split(',')) {
-    const [k, v] = pair.split('=', 2);
-    if (k) result[k] = v ?? '';
-  }
-  return result;
-}
-
-function formatLabels(labels: Record<string, string>): string {
-  const entries = Object.entries(labels);
-  if (entries.length === 0) return '';
-  const sorted = entries.sort(([a], [b]) => {
-    if (a === 'le') return 1;
-    if (b === 'le') return -1;
-    return a.localeCompare(b);
-  });
-  const pairs = sorted.map(([k, v]) => `${k}="${v}"`).join(',');
-  return `{${pairs}}`;
-}
-
-export class MetricsMiddleware extends Middleware {
-  private _collector: MetricsCollector;
-
-  constructor(collector: MetricsCollector) {
-    super();
-    this._collector = collector;
-  }
-
-  override before(
-    _moduleId: string,
-    _inputs: Record<string, unknown>,
-    context: Context,
-  ): null {
-    const starts = (context.data['_metrics_starts'] as number[]) ?? [];
-    starts.push(performance.now());
-    context.data['_metrics_starts'] = starts;
-    return null;
-  }
-
-  override after(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    _output: Record<string, unknown>,
-    context: Context,
-  ): null {
-    const starts = context.data['_metrics_starts'] as number[] | undefined;
-    if (!starts || starts.length === 0) return null;
-    const startTime = starts.pop()!;
-    const durationS = (performance.now() - startTime) / 1000;
-    this._collector.incrementCalls(moduleId, 'success');
-    this._collector.observeDuration(moduleId, durationS);
-    return null;
-  }
-
-  override onError(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    error: Error,
-    context: Context,
-  ): null {
-    const starts = context.data['_metrics_starts'] as number[] | undefined;
-    if (!starts || starts.length === 0) return null;
-    const startTime = starts.pop()!;
-    const durationS = (performance.now() - startTime) / 1000;
-    const errorCode = error instanceof ModuleError ? error.code : error.constructor.name;
-    this._collector.incrementCalls(moduleId, 'error');
-    this._collector.incrementErrors(moduleId, errorCode);
-    this._collector.observeDuration(moduleId, durationS);
-    return null;
-  }
-}