feat: Add OTLP tracing exporter and Module.preflight() method, and standardize audit and retry logging to warn level."

Author: tercel

CHANGELOG.md

@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.12.0] - 2026-03-10
+## [0.12.0] - 2026-03-11
 
 ### Added
 - **`Module.preflight()`** — Optional method for domain-specific pre-execution warnings (spec §5.6)
@@ -81,7 +81,7 @@ Built-in `system.*` modules that allow AI agents to query, monitor
 - **Optional methods** added to `Module` interface: `stream?()`, `validate?()`, `onLoad?()`, `onUnload?()`.
 
 #### Error Hierarchy
-- **`NotImplementedError`** — New error class for `GENERAL_NOT_IMPLEMENTED` code.
+- **`FeatureNotImplementedError`** — New error class for `GENERAL_NOT_IMPLEMENTED` code.
 - **`DependencyNotFoundError`** — New error class for `DEPENDENCY_NOT_FOUND` code.
 
 ### Changed
@@ -427,6 +427,7 @@ Built-in `system.*` modules that allow AI agents to query, monitor
 
 ---
 
+[0.12.0]: https://github.com/aipartnerup/apcore-typescript/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/aipartnerup/apcore-typescript/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/aipartnerup/apcore-typescript/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/aipartnerup/apcore-typescript/compare/v0.8.0...v0.9.0

README.md

@@ -128,7 +128,7 @@ src/
   cancel.ts             # Cancellation token support
   decorator.ts          # FunctionModule class and helpers
   bindings.ts           # YAML binding loader
-  errors.ts             # Error hierarchy (35 typed errors)
+  errors.ts             # Error hierarchy (36 typed errors)
   error-code-registry.ts # Custom error code registration with collision detection
   extensions.ts         # Extension manager
   module.ts             # Module types and annotations

src/events/subscribers.ts

@@ -45,19 +45,16 @@ export class WebhookSubscriber implements EventSubscriber {
     let lastError: unknown = null;
 
     for (let attempt = 0; attempt < attempts; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this._timeoutMs);
       try {
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), this._timeoutMs);
-
         const response = await fetch(this._url, {
           method: 'POST',
           headers: mergedHeaders,
           body: JSON.stringify(payload),
           signal: controller.signal,
         });
 
-        clearTimeout(timer);
-
         if (response.status < 500) {
           if (response.status >= 400) {
             console.warn(
@@ -81,6 +78,8 @@ export class WebhookSubscriber implements EventSubscriber {
           `Webhook ${this._url} failed (attempt ${attempt + 1}/${attempts}):`,
           err,
         );
+      } finally {
+        clearTimeout(timer);
       }
     }
 
@@ -145,19 +144,16 @@ export class A2ASubscriber implements EventSubscriber {
       }
     }
 
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this._timeoutMs);
     try {
-      const controller = new AbortController();
-      const timer = setTimeout(() => controller.abort(), this._timeoutMs);
-
       const response = await fetch(this._platformUrl, {
         method: 'POST',
         headers,
         body: JSON.stringify(payload),
         signal: controller.signal,
       });
 
-      clearTimeout(timer);
-
       if (response.status >= 400) {
         console.warn(
           '[apcore:events]',
@@ -170,6 +166,8 @@ export class A2ASubscriber implements EventSubscriber {
         `A2A delivery to ${this._platformUrl} failed for event ${event.eventType}:`,
         err,
       );
+    } finally {
+      clearTimeout(timer);
     }
   }
 }

src/executor.ts

@@ -27,7 +27,7 @@ import {
 import { AfterMiddleware, BeforeMiddleware, Middleware } from './middleware/index.js';
 import { MiddlewareChainError, MiddlewareManager } from './middleware/manager.js';
 import { guardCallChain } from './utils/call-chain.js';
-import type { ModuleAnnotations, PreflightCheckResult, PreflightResult } from './module.js';
+import type { Module, ModuleAnnotations, PreflightCheckResult, PreflightResult } from './module.js';
 import { DEFAULT_ANNOTATIONS, createPreflightResult } from './module.js';
 import { MODULE_ID_PATTERN } from './registry/registry.js';
 import type { Registry } from './registry/registry.js';
@@ -554,9 +554,10 @@ export class Executor {
     }
 
     // Check 7: module-level preflight (optional)
-    if (typeof (mod as any).preflight === 'function') {
+    const modWithPreflight = mod as { preflight?: Module['preflight'] };
+    if (typeof modWithPreflight.preflight === 'function') {
       try {
-        const preflightWarnings = (mod as any).preflight(effectiveInputs, ctx);
+        const preflightWarnings = modWithPreflight.preflight(effectiveInputs, ctx);
         if (Array.isArray(preflightWarnings) && preflightWarnings.length > 0) {
           checks.push({ check: 'module_preflight', passed: true, warnings: preflightWarnings });
         } else {
@@ -642,7 +643,7 @@ export class Executor {
 
   /** Emit an audit event for the approval decision (logging + span event). */
   private _emitApprovalEvent(result: ApprovalResult, moduleId: string, ctx: Context): void {
-    console.info(
+    console.warn(
       `[apcore:executor] Approval decision: module=${moduleId} status=${result.status} approved_by=${result.approvedBy} reason=${result.reason}`,
     );
 

src/middleware/retry.ts

@@ -65,7 +65,7 @@ export class RetryMiddleware extends Middleware {
     const delayMs = this._calculateDelay(retryCount);
     context.data[retryKey] = retryCount + 1;
 
-    console.info(
+    console.warn(
       `[apcore:retry] Retrying module '${moduleId}' (attempt ${retryCount + 1}/${this._config.maxRetries}) after ${Math.round(delayMs)}ms`,
     );
 

src/observability/index.ts

@@ -1,4 +1,4 @@
-export { TracingMiddleware, StdoutExporter, InMemoryExporter, createSpan } from './tracing.js';
+export { TracingMiddleware, StdoutExporter, InMemoryExporter, OTLPExporter, createSpan } from './tracing.js';
 export type { Span, SpanExporter } from './tracing.js';
 export { MetricsCollector, MetricsMiddleware } from './metrics.js';
 export { ContextLogger, ObsLoggingMiddleware } from './context-logger.js';

src/observability/tracing.ts

@@ -125,8 +125,8 @@ export class OTLPExporter implements SpanExporter {
         ...this._headers,
       },
       body: JSON.stringify(payload),
-    }).catch(() => {
-      // Silently ignore network errors
+    }).catch((err: unknown) => {
+      console.warn('[apcore:tracing] OTLP export failed:', err);
     });
   }
 }

src/registry/schema-export.ts

@@ -2,7 +2,6 @@
  * Schema query and export functions for the registry system.
  */
 
-import type { TSchema } from '@sinclair/typebox';
 import yaml from 'js-yaml';
 import type { ModuleAnnotations, ModuleExample } from '../module.js';
 import { InvalidInputError, ModuleNotFoundError } from '../errors.js';

tests/test-approval-executor.test.ts

@@ -431,7 +431,7 @@ describe('ApprovalAuditEvents', () => {
   it('emits audit log on approved', async () => {
     const registry = createTestRegistry();
     const executor = new Executor({ registry, approvalHandler: new AutoApproveHandler() });
-    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => {});
+    const infoSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
     try {
       await executor.call('test.approval_required');
       const approvalLogs = infoSpy.mock.calls.filter(
@@ -448,7 +448,7 @@ describe('ApprovalAuditEvents', () => {
   it('emits audit log on denied', async () => {
     const registry = createTestRegistry();
     const executor = new Executor({ registry, approvalHandler: new AlwaysDenyHandler() });
-    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => {});
+    const infoSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
     try {
       await expect(executor.call('test.approval_required')).rejects.toThrow(ApprovalDeniedError);
       const approvalLogs = infoSpy.mock.calls.filter(
@@ -467,7 +467,7 @@ describe('ApprovalAuditEvents', () => {
       createApprovalResult({ status: 'pending', approvalId: 'tok-123' }),
     );
     const executor = new Executor({ registry, approvalHandler: handler });
-    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => {});
+    const infoSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
     try {
       await expect(executor.call('test.approval_required')).rejects.toThrow(ApprovalPendingError);
       const approvalLogs = infoSpy.mock.calls.filter(
@@ -483,7 +483,7 @@ describe('ApprovalAuditEvents', () => {
   it('does not emit audit log when gate is skipped', async () => {
     const registry = createTestRegistry();
     const executor = new Executor({ registry });
-    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => {});
+    const infoSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
     try {
       await executor.call('test.approval_required');
       const approvalLogs = infoSpy.mock.calls.filter(
@@ -504,7 +504,7 @@ describe('ApprovalAuditEvents', () => {
       createApprovalResult({ status: 'approved', approvedBy: 'test-user', reason: 'looks good' }),
     );
     const executor = new Executor({ registry, approvalHandler: handler });
-    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => {});
+    const infoSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
 
     try {
       const ctx = Context.create(executor);
@@ -529,7 +529,7 @@ describe('ApprovalAuditEvents', () => {
     const mockSpan = { events: mockSpanEvents };
 
     const executor = new Executor({ registry, approvalHandler: new AlwaysDenyHandler() });
-    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => {});
+    const infoSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
 
     try {
       const ctx = Context.create(executor);
@@ -547,7 +547,7 @@ describe('ApprovalAuditEvents', () => {
   it('works without tracing spans', async () => {
     const registry = createTestRegistry();
     const executor = new Executor({ registry, approvalHandler: new AutoApproveHandler() });
-    const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => {});
+    const infoSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
     try {
       const result = await executor.call('test.approval_required');
       expect(result['status']).toBe('executed');