apcore-js 0.5.0 → 0.6.0

package/src/extensions.ts

@@ -1,265 +0,0 @@
-/**
- * Extension point framework for apcore.
- *
- * Provides a centralized mechanism to register, query, and wire custom
- * extensions (discoverers, middleware, ACL providers, span exporters, and
- * module validators) into the apcore runtime.
- */
-
-import type { ACL } from './acl.js';
-import type { Executor } from './executor.js';
-import { Middleware } from './middleware/index.js';
-import { TracingMiddleware } from './observability/tracing.js';
-import type { Span, SpanExporter } from './observability/tracing.js';
-import type { Discoverer, ModuleValidator, Registry } from './registry/registry.js';
-
-/**
- * Delegates span export to multiple underlying exporters.
- */
-class CompositeExporter implements SpanExporter {
-  private _exporters: SpanExporter[];
-
-  constructor(exporters: SpanExporter[]) {
-    this._exporters = exporters;
-  }
-
-  export(span: Span): void {
-    for (const exp of this._exporters) {
-      try {
-        exp.export(span);
-      } catch (e) {
-        console.warn('[apcore:extensions] Span exporter failed:', e);
-      }
-    }
-  }
-}
-
-/**
- * Describes a named slot where extensions can be registered.
- */
-export interface ExtensionPoint {
-  readonly name: string;
-  readonly description: string;
-  readonly multiple: boolean;
-}
-
-/** Type guard: checks if value has a `discover` method. */
-function isDiscoverer(value: unknown): value is Discoverer {
-  return typeof value === 'object' && value !== null && typeof (value as Record<string, unknown>)['discover'] === 'function';
-}
-
-/** Type guard: checks if value has a `validate` method. */
-function isModuleValidator(value: unknown): value is ModuleValidator {
-  return typeof value === 'object' && value !== null && typeof (value as Record<string, unknown>)['validate'] === 'function';
-}
-
-/** Type guard: checks if value has at least one middleware method (before, after, onError). */
-function isMiddleware(value: unknown): value is Middleware {
-  if (typeof value !== 'object' || value === null) return false;
-  const obj = value as Record<string, unknown>;
-  return typeof obj['before'] === 'function' || typeof obj['after'] === 'function' || typeof obj['onError'] === 'function';
-}
-
-/** Type guard: checks if value has a `check` method (ACL). */
-function isACL(value: unknown): value is ACL {
-  return typeof value === 'object' && value !== null && typeof (value as Record<string, unknown>)['check'] === 'function';
-}
-
-/** Type guard: checks if value has an `export` method (SpanExporter). */
-function isSpanExporter(value: unknown): value is SpanExporter {
-  return typeof value === 'object' && value !== null && typeof (value as Record<string, unknown>)['export'] === 'function';
-}
-
-type TypeChecker = (value: unknown) => boolean;
-
-interface InternalExtensionPoint extends ExtensionPoint {
-  readonly typeCheck: TypeChecker;
-  readonly typeName: string;
-}
-
-function builtInPoints(): Map<string, InternalExtensionPoint> {
-  return new Map<string, InternalExtensionPoint>([
-    ['discoverer', {
-      name: 'discoverer',
-      description: 'Custom module discovery strategy',
-      multiple: false,
-      typeCheck: isDiscoverer,
-      typeName: 'Discoverer',
-    }],
-    ['middleware', {
-      name: 'middleware',
-      description: 'Execution middleware',
-      multiple: true,
-      typeCheck: isMiddleware,
-      typeName: 'Middleware',
-    }],
-    ['acl', {
-      name: 'acl',
-      description: 'Access control provider',
-      multiple: false,
-      typeCheck: isACL,
-      typeName: 'ACL',
-    }],
-    ['span_exporter', {
-      name: 'span_exporter',
-      description: 'Tracing span exporter',
-      multiple: true,
-      typeCheck: isSpanExporter,
-      typeName: 'SpanExporter',
-    }],
-    ['module_validator', {
-      name: 'module_validator',
-      description: 'Custom module validation',
-      multiple: false,
-      typeCheck: isModuleValidator,
-      typeName: 'ModuleValidator',
-    }],
-  ]);
-}
-
-/**
- * Manages extension points and their registered implementations.
- *
- * Pre-registers five built-in extension points: discoverer, middleware,
- * acl, span_exporter, and module_validator.
- */
-export class ExtensionManager {
-  private _points: Map<string, InternalExtensionPoint>;
-  private _extensions: Map<string, unknown[]>;
-
-  constructor() {
-    this._points = builtInPoints();
-    this._extensions = new Map<string, unknown[]>();
-    for (const name of this._points.keys()) {
-      this._extensions.set(name, []);
-    }
-  }
-
-  /**
-   * Register an extension for the given extension point.
-   *
-   * @throws Error if point_name is unknown.
-   * @throws Error if extension does not satisfy the type constraint.
-   */
-  register(pointName: string, extension: unknown): void {
-    const point = this._points.get(pointName);
-    if (point === undefined) {
-      throw new Error(
-        `Unknown extension point: '${pointName}'. Available: ${[...this._points.keys()].sort().join(', ')}`,
-      );
-    }
-
-    if (!point.typeCheck(extension)) {
-      throw new TypeError(
-        `Extension for '${pointName}' must satisfy the ${point.typeName} interface`,
-      );
-    }
-
-    if (point.multiple) {
-      this._extensions.get(pointName)!.push(extension);
-    } else {
-      this._extensions.set(pointName, [extension]);
-    }
-  }
-
-  /**
-   * Return the single extension for a non-multiple point, or null.
-   */
-  get(pointName: string): unknown | null {
-    if (!this._points.has(pointName)) {
-      throw new Error(`Unknown extension point: '${pointName}'`);
-    }
-    const exts = this._extensions.get(pointName)!;
-    return exts.length > 0 ? exts[0] : null;
-  }
-
-  /**
-   * Return all extensions for a multiple-type point.
-   */
-  getAll(pointName: string): unknown[] {
-    if (!this._points.has(pointName)) {
-      throw new Error(`Unknown extension point: '${pointName}'`);
-    }
-    return [...this._extensions.get(pointName)!];
-  }
-
-  /**
-   * Remove a specific extension from an extension point.
-   * Returns true if found and removed, false otherwise.
-   */
-  unregister(pointName: string, extension: unknown): boolean {
-    if (!this._points.has(pointName)) {
-      throw new Error(`Unknown extension point: '${pointName}'`);
-    }
-    const exts = this._extensions.get(pointName)!;
-    const idx = exts.indexOf(extension);
-    if (idx === -1) return false;
-    exts.splice(idx, 1);
-    return true;
-  }
-
-  /**
-   * Return all registered extension points.
-   */
-  listPoints(): ExtensionPoint[] {
-    return [...this._points.values()].map(({ name, description, multiple }) => ({
-      name,
-      description,
-      multiple,
-    }));
-  }
-
-  /**
-   * Wire all registered extensions into the given registry and executor.
-   */
-  apply(registry: Registry, executor: Executor): void {
-    // Discoverer
-    const discoverer = this.get('discoverer') as Discoverer | null;
-    if (discoverer !== null) {
-      registry.setDiscoverer(discoverer);
-    }
-
-    // Module validator
-    const validator = this.get('module_validator') as ModuleValidator | null;
-    if (validator !== null) {
-      registry.setValidator(validator);
-    }
-
-    // ACL
-    const acl = this.get('acl') as ACL | null;
-    if (acl !== null) {
-      executor.setAcl(acl);
-    }
-
-    // Middleware
-    for (const mw of this.getAll('middleware')) {
-      executor.use(mw as Middleware);
-    }
-
-    // Span exporters: find existing TracingMiddleware and set exporter(s)
-    const exporters = this.getAll('span_exporter') as SpanExporter[];
-    if (exporters.length > 0) {
-      const tracingMw = this._findTracingMiddleware(executor);
-      if (tracingMw !== null) {
-        if (exporters.length === 1) {
-          tracingMw.setExporter(exporters[0]);
-        } else {
-          tracingMw.setExporter(new CompositeExporter(exporters));
-        }
-      } else {
-        console.warn(
-          '[apcore:extensions] span_exporter extensions registered but no TracingMiddleware found in executor middleware chain',
-        );
-      }
-    }
-  }
-
-  private _findTracingMiddleware(executor: Executor): TracingMiddleware | null {
-    for (const mw of executor.middlewares) {
-      if (mw instanceof TracingMiddleware) {
-        return mw;
-      }
-    }
-    return null;
-  }
-}

package/src/middleware/adapters.ts

@@ -1,54 +0,0 @@
-/**
- * Function adapter classes for the middleware system.
- */
-
-import type { Context } from '../context.js';
-import { Middleware } from './base.js';
-
-export type BeforeCallback = (
-  moduleId: string,
-  inputs: Record<string, unknown>,
-  context: Context,
-) => Record<string, unknown> | null;
-
-export type AfterCallback = (
-  moduleId: string,
-  inputs: Record<string, unknown>,
-  output: Record<string, unknown>,
-  context: Context,
-) => Record<string, unknown> | null;
-
-export class BeforeMiddleware extends Middleware {
-  private _callback: BeforeCallback;
-
-  constructor(callback: BeforeCallback) {
-    super();
-    this._callback = callback;
-  }
-
-  override before(
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    context: Context,
-  ): Record<string, unknown> | null {
-    return this._callback(moduleId, inputs, context);
-  }
-}
-
-export class AfterMiddleware extends Middleware {
-  private _callback: AfterCallback;
-
-  constructor(callback: AfterCallback) {
-    super();
-    this._callback = callback;
-  }
-
-  override after(
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    output: Record<string, unknown>,
-    context: Context,
-  ): Record<string, unknown> | null {
-    return this._callback(moduleId, inputs, output, context);
-  }
-}

package/src/middleware/base.ts

@@ -1,33 +0,0 @@
-/**
- * Middleware base class for apcore.
- */
-
-import type { Context } from '../context.js';
-
-export class Middleware {
-  before(
-    _moduleId: string,
-    _inputs: Record<string, unknown>,
-    _context: Context,
-  ): Record<string, unknown> | null {
-    return null;
-  }
-
-  after(
-    _moduleId: string,
-    _inputs: Record<string, unknown>,
-    _output: Record<string, unknown>,
-    _context: Context,
-  ): Record<string, unknown> | null {
-    return null;
-  }
-
-  onError(
-    _moduleId: string,
-    _inputs: Record<string, unknown>,
-    _error: Error,
-    _context: Context,
-  ): Record<string, unknown> | null {
-    return null;
-  }
-}

package/src/middleware/logging.ts

@@ -1,103 +0,0 @@
-/**
- * LoggingMiddleware for structured module call logging.
- */
-
-import type { Context } from '../context.js';
-import { Middleware } from './base.js';
-
-export interface Logger {
-  info(message: string, extra?: Record<string, unknown>): void;
-  error(message: string, extra?: Record<string, unknown>): void;
-}
-
-const defaultLogger: Logger = {
-  info(message: string, extra?: Record<string, unknown>) {
-    console.info(message, extra ?? '');
-  },
-  error(message: string, extra?: Record<string, unknown>) {
-    console.error(message, extra ?? '');
-  },
-};
-
-export class LoggingMiddleware extends Middleware {
-  private _logger: Logger;
-  private _logInputs: boolean;
-  private _logOutputs: boolean;
-  private _logErrors: boolean;
-
-  constructor(options?: {
-    logger?: Logger;
-    logInputs?: boolean;
-    logOutputs?: boolean;
-    logErrors?: boolean;
-  }) {
-    super();
-    this._logger = options?.logger ?? defaultLogger;
-    this._logInputs = options?.logInputs ?? true;
-    this._logOutputs = options?.logOutputs ?? true;
-    this._logErrors = options?.logErrors ?? true;
-  }
-
-  override before(
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    context: Context,
-  ): null {
-    context.data['_logging_mw_start'] = performance.now();
-
-    if (this._logInputs) {
-      const redacted = context.redactedInputs ?? inputs;
-      this._logger.info(`[${context.traceId}] START ${moduleId}`, {
-        traceId: context.traceId,
-        moduleId,
-        callerId: context.callerId,
-        inputs: redacted,
-      });
-    }
-
-    return null;
-  }
-
-  override after(
-    moduleId: string,
-    _inputs: Record<string, unknown>,
-    output: Record<string, unknown>,
-    context: Context,
-  ): null {
-    const startTime = (context.data['_logging_mw_start'] as number) ?? performance.now();
-    const durationMs = performance.now() - startTime;
-
-    if (this._logOutputs) {
-      this._logger.info(
-        `[${context.traceId}] END ${moduleId} (${durationMs.toFixed(2)}ms)`,
-        {
-          traceId: context.traceId,
-          moduleId,
-          durationMs,
-          output,
-        },
-      );
-    }
-
-    return null;
-  }
-
-  override onError(
-    moduleId: string,
-    inputs: Record<string, unknown>,
-    error: Error,
-    context: Context,
-  ): null {
-    if (this._logErrors) {
-      const redacted = context.redactedInputs ?? inputs;
-      this._logger.error(`[${context.traceId}] ERROR ${moduleId}: ${error}`, {
-        traceId: context.traceId,
-        moduleId,
-        error: String(error),
-        inputs: redacted,
-      });
-    }
-
-    return null;
-  }
-}

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), undefined, 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>;
-}