apcore-js 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.3.0] - 2026-02-20
+
+### Changed
+- Use shallow merge for `stream()` accumulation instead of last-chunk.
+
+### Added
+- Add `Executor.stream()` async generator and `ModuleAnnotations.streaming` for streaming support in the core execution pipeline.
+
+### Co-Authors
+- Claude Opus 4.6 <noreply@anthropic.com>
+
+### Added
+
+- **Error classes and constants**
+  - `ModuleExecuteError` — New error class for module execution failures
+  - `InternalError` — New error class for general internal errors
+  - `ErrorCodes` — Frozen object with all 26 error code strings for consistent error code usage
+  - `ErrorCode` — Type definition for all error codes
+- **Registry constants**
+  - `REGISTRY_EVENTS` — Frozen object with standard event names (`register`, `unregister`)
+  - `MODULE_ID_PATTERN` — Regex pattern enforcing lowercase/digits/underscores/dots for module IDs (no hyphens allowed to ensure bijective MCP tool name normalization)
+- **Executor methods**
+  - `Executor.callAsync()` — Alias for `call()` for compatibility with MCP bridge packages
+
+### Changed
+
+- **Module ID validation** — Registry now validates module IDs against `MODULE_ID_PATTERN` on registration, rejecting IDs with hyphens or invalid characters
+- **Event handling** — Registry event validation now uses `REGISTRY_EVENTS` constants instead of hardcoded strings
+- **Test updates** — Updated tests to use underscore-separated module IDs instead of hyphens (e.g., `math.add_ten` instead of `math.addTen`, `ctx_test` instead of `ctx-test`)
+
+### Fixed
+
+- **String literals in Registry** — Replaced hardcoded `'register'` and `'unregister'` strings with `REGISTRY_EVENTS.REGISTER` and `REGISTRY_EVENTS.UNREGISTER` constants in event triggers for consistency
+
 ## [0.2.0] - 2026-02-20
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apcore-js",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "AI-Perceivable Core — schema-driven module development framework",
   "type": "module",
   "main": "./dist/index.js",

package/src/executor.ts

@@ -180,6 +180,96 @@ export class Executor {
     return this.call(moduleId, inputs, context);
   }
 
+  /**
+   * Streaming execution pipeline. If the module exposes a stream() async generator,
+   * yields each chunk. Otherwise falls back to call() and yields a single chunk.
+   *
+   * Pipeline: context -> safety -> lookup -> ACL -> validate inputs -> before-middleware
+   *   -> stream (or fallback to execute) -> validate accumulated output -> after-middleware
+   */
+  async *stream(
+    moduleId: string,
+    inputs?: Record<string, unknown> | null,
+    context?: Context | null,
+  ): AsyncGenerator<Record<string, unknown>> {
+    let effectiveInputs = inputs ?? {};
+    const ctx = this._createContext(moduleId, context);
+    this._checkSafety(moduleId, ctx);
+
+    const mod = this._lookupModule(moduleId);
+    this._checkAcl(moduleId, ctx);
+
+    effectiveInputs = this._validateInputs(mod, effectiveInputs, ctx);
+
+    yield* this._streamWithMiddleware(mod, moduleId, effectiveInputs, ctx);
+  }
+
+  private async *_streamWithMiddleware(
+    mod: Record<string, unknown>,
+    moduleId: string,
+    inputs: Record<string, unknown>,
+    ctx: Context,
+  ): AsyncGenerator<Record<string, unknown>> {
+    let effectiveInputs = inputs;
+    let executedMiddlewares: Middleware[] = [];
+
+    try {
+      try {
+        [effectiveInputs, executedMiddlewares] = this._middlewareManager.executeBefore(moduleId, effectiveInputs, ctx);
+      } catch (e) {
+        if (e instanceof MiddlewareChainError) {
+          executedMiddlewares = e.executedMiddlewares;
+          const recovery = this._middlewareManager.executeOnError(
+            moduleId, effectiveInputs, e.original, ctx, executedMiddlewares,
+          );
+          if (recovery !== null) {
+            yield recovery;
+            return;
+          }
+          executedMiddlewares = [];
+          throw e.original;
+        }
+        throw e;
+      }
+
+      const streamFn = mod['stream'] as
+        | ((inputs: Record<string, unknown>, context: Context) => AsyncGenerator<Record<string, unknown>>)
+        | undefined;
+
+      if (typeof streamFn === 'function') {
+        // Module has a stream() method: iterate and yield each chunk
+        let accumulated: Record<string, unknown> = {};
+        for await (const chunk of streamFn.call(mod, effectiveInputs, ctx)) {
+          accumulated = { ...accumulated, ...chunk };
+          yield chunk;
+        }
+
+        // Validate accumulated output against output schema
+        this._validateOutput(mod, accumulated);
+
+        // Run after-middleware on the accumulated result
+        this._middlewareManager.executeAfter(moduleId, effectiveInputs, accumulated, ctx);
+      } else {
+        // Fallback: execute normally and yield single chunk
+        let output = await this._executeWithTimeout(mod, moduleId, effectiveInputs, ctx);
+        this._validateOutput(mod, output);
+        output = this._middlewareManager.executeAfter(moduleId, effectiveInputs, output, ctx);
+        yield output;
+      }
+    } catch (exc) {
+      if (executedMiddlewares.length > 0) {
+        const recovery = this._middlewareManager.executeOnError(
+          moduleId, effectiveInputs, exc as Error, ctx, executedMiddlewares,
+        );
+        if (recovery !== null) {
+          yield recovery;
+          return;
+        }
+      }
+      throw exc;
+    }
+  }
+
   private _createContext(moduleId: string, context?: Context | null): Context {
     if (context == null) {
       return Context.create(this).child(moduleId);
@@ -265,10 +355,7 @@ export class Executor {
 
       let output = await this._executeWithTimeout(mod, moduleId, effectiveInputs, ctx);
 
-      const outputSchema = mod['outputSchema'] as TSchema | undefined;
-      if (outputSchema != null) {
-        this._validateSchema(outputSchema, output, 'Output');
-      }
+      this._validateOutput(mod, output);
 
       output = this._middlewareManager.executeAfter(moduleId, effectiveInputs, output, ctx);
       return output;
@@ -283,6 +370,13 @@ export class Executor {
     }
   }
 
+  private _validateOutput(mod: Record<string, unknown>, output: Record<string, unknown>): void {
+    const outputSchema = mod['outputSchema'] as TSchema | undefined;
+    if (outputSchema != null) {
+      this._validateSchema(outputSchema, output, 'Output');
+    }
+  }
+
   validate(moduleId: string, inputs: Record<string, unknown>): ValidationResult {
     const module = this._registry.get(moduleId);
     if (module === null) {

package/src/module.ts

@@ -11,6 +11,7 @@ export interface ModuleAnnotations {
   readonly idempotent: boolean;
   readonly requiresApproval: boolean;
   readonly openWorld: boolean;
+  readonly streaming: boolean;
 }
 
 export const DEFAULT_ANNOTATIONS: ModuleAnnotations = Object.freeze({
@@ -19,6 +20,7 @@ export const DEFAULT_ANNOTATIONS: ModuleAnnotations = Object.freeze({
   idempotent: false,
   requiresApproval: false,
   openWorld: true,
+  streaming: false,
 });
 
 export interface ModuleExample {

package/src/schema/annotations.ts

@@ -11,6 +11,7 @@ const ANNOTATION_FIELDS: ReadonlyArray<keyof ModuleAnnotations> = [
   'idempotent',
   'requiresApproval',
   'openWorld',
+  'streaming',
 ];
 
 export function mergeAnnotations(

package/tests/registry/test-schema-export.test.ts

@@ -37,6 +37,7 @@ function createModule(
       idempotent: true,
       requiresApproval: false,
       openWorld: false,
+      streaming: false,
     },
     examples: [
       {

package/tests/schema/test-annotations.test.ts

@@ -25,6 +25,7 @@ describe('mergeAnnotations', () => {
       idempotent: true,
       requiresApproval: false,
       openWorld: false,
+      streaming: false,
     };
     const result = mergeAnnotations(null, codeAnnotations);
     expect(result.readonly).toBe(true);
@@ -39,6 +40,7 @@ describe('mergeAnnotations', () => {
       idempotent: false,
       requiresApproval: false,
       openWorld: true,
+      streaming: false,
     };
     const yamlAnnotations = { readonly: false, destructive: true };
     const result = mergeAnnotations(yamlAnnotations, codeAnnotations);

package/tests/schema/test-exporter.test.ts

@@ -55,6 +55,7 @@ describe('SchemaExporter', () => {
         idempotent: true,
         requiresApproval: false,
         openWorld: false,
+        streaming: false,
       };
       const result = exporter.exportMcp(sd, annotations, 'MyTool');
       expect(result['name']).toBe('MyTool');

package/tests/test-executor-stream.test.ts

@@ -0,0 +1,208 @@
+import { describe, it, expect } from 'vitest';
+import { Type } from '@sinclair/typebox';
+import { Executor } from '../src/executor.js';
+import { FunctionModule } from '../src/decorator.js';
+import { Registry } from '../src/registry/registry.js';
+import { Middleware } from '../src/middleware/base.js';
+import { ModuleNotFoundError } from '../src/errors.js';
+
+function createSimpleModule(id: string): FunctionModule {
+  return new FunctionModule({
+    execute: (inputs) => ({ greeting: `Hello, ${inputs['name'] ?? 'world'}!` }),
+    moduleId: id,
+    inputSchema: Type.Object({ name: Type.Optional(Type.String()) }),
+    outputSchema: Type.Object({ greeting: Type.String() }),
+    description: 'Greet module',
+  });
+}
+
+/**
+ * Creates a module with a stream() async generator that yields chunks.
+ */
+function createStreamingModule(id: string): FunctionModule & { stream: (inputs: Record<string, unknown>) => AsyncGenerator<Record<string, unknown>> } {
+  const mod = new FunctionModule({
+    execute: (inputs) => ({ greeting: `Hello, ${inputs['name'] ?? 'world'}!` }),
+    moduleId: id,
+    inputSchema: Type.Object({ name: Type.Optional(Type.String()) }),
+    outputSchema: Type.Object({ greeting: Type.String() }),
+    description: 'Streaming greet module',
+  });
+
+  // Attach a stream method to the module
+  const streamingMod = mod as FunctionModule & { stream: (inputs: Record<string, unknown>) => AsyncGenerator<Record<string, unknown>> };
+  streamingMod.stream = async function* (inputs: Record<string, unknown>): AsyncGenerator<Record<string, unknown>> {
+    const name = (inputs['name'] as string) ?? 'world';
+    yield { greeting: `Hello, ` };
+    yield { greeting: `${name}` };
+    yield { greeting: `!` };
+  };
+
+  return streamingMod;
+}
+
+async function collectChunks(gen: AsyncGenerator<Record<string, unknown>>): Promise<Record<string, unknown>[]> {
+  const chunks: Record<string, unknown>[] = [];
+  for await (const chunk of gen) {
+    chunks.push(chunk);
+  }
+  return chunks;
+}
+
+describe('Executor.stream()', () => {
+  it('falls back to single chunk when module has no stream()', async () => {
+    const registry = new Registry();
+    const mod = createSimpleModule('greet');
+    registry.register('greet', mod);
+
+    const executor = new Executor({ registry });
+    const chunks = await collectChunks(executor.stream('greet', { name: 'Alice' }));
+
+    expect(chunks).toHaveLength(1);
+    expect(chunks[0]['greeting']).toBe('Hello, Alice!');
+  });
+
+  it('yields multiple chunks from streaming module', async () => {
+    const registry = new Registry();
+    const mod = createStreamingModule('greet');
+    registry.register('greet', mod);
+
+    const executor = new Executor({ registry });
+    const chunks = await collectChunks(executor.stream('greet', { name: 'Bob' }));
+
+    expect(chunks.length).toBeGreaterThan(1);
+    expect(chunks[0]['greeting']).toBe('Hello, ');
+    expect(chunks[1]['greeting']).toBe('Bob');
+    expect(chunks[2]['greeting']).toBe('!');
+  });
+
+  it('throws ModuleNotFoundError for unknown module', async () => {
+    const registry = new Registry();
+    const executor = new Executor({ registry });
+
+    const chunks: Record<string, unknown>[] = [];
+    await expect(async () => {
+      for await (const chunk of executor.stream('nonexistent')) {
+        chunks.push(chunk);
+      }
+    }).rejects.toThrow(ModuleNotFoundError);
+  });
+
+  it('runs before-middleware before streaming and after-middleware on accumulated result', async () => {
+    const registry = new Registry();
+    const mod = createStreamingModule('echo');
+    registry.register('echo', mod);
+
+    const calls: string[] = [];
+    class TrackingMiddleware extends Middleware {
+      override before() { calls.push('before'); return null; }
+      override after() { calls.push('after'); return null; }
+    }
+
+    const executor = new Executor({ registry, middlewares: [new TrackingMiddleware()] });
+    const chunks = await collectChunks(executor.stream('echo', { name: 'Test' }));
+
+    expect(chunks.length).toBeGreaterThan(0);
+    expect(calls).toContain('before');
+    expect(calls).toContain('after');
+    // before must come first
+    expect(calls.indexOf('before')).toBeLessThan(calls.indexOf('after'));
+  });
+
+  it('runs before-middleware before fallback and after-middleware on result', async () => {
+    const registry = new Registry();
+    const mod = createSimpleModule('echo');
+    registry.register('echo', mod);
+
+    const calls: string[] = [];
+    class TrackingMiddleware extends Middleware {
+      override before() { calls.push('before'); return null; }
+      override after() { calls.push('after'); return null; }
+    }
+
+    const executor = new Executor({ registry, middlewares: [new TrackingMiddleware()] });
+    const chunks = await collectChunks(executor.stream('echo', { name: 'Test' }));
+
+    expect(chunks).toHaveLength(1);
+    expect(calls).toEqual(['before', 'after']);
+  });
+
+  it('handles middleware error recovery in streaming mode', async () => {
+    const registry = new Registry();
+    const failMod = new FunctionModule({
+      execute: () => { throw new Error('stream-boom'); },
+      moduleId: 'fail',
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({}),
+      description: 'Failing module',
+    });
+    registry.register('fail', failMod);
+
+    class RecoveryMiddleware extends Middleware {
+      override onError() { return { recovered: true }; }
+    }
+
+    const executor = new Executor({ registry, middlewares: [new RecoveryMiddleware()] });
+    // Non-streaming module fallback with error should recover
+    const chunks = await collectChunks(executor.stream('fail'));
+    expect(chunks).toHaveLength(1);
+    expect(chunks[0]['recovered']).toBe(true);
+  });
+
+  it('accumulates chunks via shallow merge for after-middleware', async () => {
+    const registry = new Registry();
+    const mod = {
+      description: 'multi-key streaming module',
+      inputSchema: Type.Object({ prefix: Type.String() }),
+      outputSchema: Type.Object({ a: Type.Optional(Type.String()), b: Type.Optional(Type.String()) }),
+      execute: async (inputs: Record<string, unknown>) => ({ a: `${inputs['prefix']}_a`, b: `${inputs['prefix']}_b` }),
+      async *stream(inputs: Record<string, unknown>) {
+        yield { a: `${inputs['prefix']}_a` };
+        yield { b: `${inputs['prefix']}_b` };
+      },
+    };
+    registry.register('multi', mod);
+
+    let afterOutput: Record<string, unknown> | null = null;
+    const executor = new Executor({ registry });
+    executor.useAfter((_mid, _inputs, output) => {
+      afterOutput = { ...output };
+      return null;
+    });
+
+    const chunks: Record<string, unknown>[] = [];
+    for await (const chunk of executor.stream('multi', { prefix: 'test' })) {
+      chunks.push(chunk);
+    }
+
+    expect(chunks).toHaveLength(2);
+    expect(chunks[0]).toEqual({ a: 'test_a' });
+    expect(chunks[1]).toEqual({ b: 'test_b' });
+    // After-middleware should receive the MERGED result
+    expect(afterOutput).toEqual({ a: 'test_a', b: 'test_b' });
+  });
+
+  it('validates output schema on accumulated streaming result', async () => {
+    const registry = new Registry();
+    const mod = new FunctionModule({
+      execute: () => ({ greeting: 'fallback' }),
+      moduleId: 'validated',
+      inputSchema: Type.Object({}),
+      outputSchema: Type.Object({ greeting: Type.String() }),
+      description: 'Validated module',
+    });
+
+    // Attach a stream that produces valid accumulated output
+    const streamingMod = mod as FunctionModule & { stream: (inputs: Record<string, unknown>) => AsyncGenerator<Record<string, unknown>> };
+    streamingMod.stream = async function* (): AsyncGenerator<Record<string, unknown>> {
+      yield { greeting: 'chunk1' };
+      yield { greeting: 'chunk2' };
+    };
+
+    registry.register('validated', streamingMod);
+
+    const executor = new Executor({ registry });
+    // The last chunk is used as the accumulated output for validation
+    const chunks = await collectChunks(executor.stream('validated'));
+    expect(chunks).toHaveLength(2);
+  });
+});