hono-apcore 0.1.0

package/dist/context/hono-context.factory.js

@@ -0,0 +1,117 @@
+import { Context as ApcoreContext, TraceContext, createIdentity } from 'apcore-js';
+function isHeaders(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof value.get === 'function' &&
+        typeof value.forEach === 'function');
+}
+/**
+ * Reduce any {@link HeaderSource} to a `Headers` instance.
+ *
+ * `Headers` already matches header names case-insensitively, so downstream
+ * lookups need no normalisation of their own.
+ */
+export function toHeaders(source) {
+    if (isHeaders(source))
+        return source;
+    if (source instanceof Request)
+        return source.headers;
+    const req = source.req;
+    if (req?.raw instanceof Request)
+        return req.raw.headers;
+    const raw = source.headers;
+    if (isHeaders(raw))
+        return raw;
+    const headers = new Headers();
+    if (raw !== null && typeof raw === 'object') {
+        for (const [key, value] of Object.entries(raw)) {
+            if (typeof value === 'string') {
+                headers.set(key, value);
+            }
+            else if (Array.isArray(value) && value.length > 0) {
+                headers.set(key, String(value[0]));
+            }
+        }
+    }
+    return headers;
+}
+/**
+ * Builds apcore `Context` objects from Hono requests.
+ *
+ * **Identity resolution**, in order:
+ *   1. `x-user-id` header
+ *   2. `Authorization: Bearer <token>` (identity id `"bearer"`)
+ *   3. `x-roles` alone — a demo shortcut for role-based ACL without auth
+ *   4. anonymous
+ *
+ * **W3C Trace Context** — a `traceparent` header supplies the trace id.
+ * Strict 32-hex validation and rejection of W3C-invalid ids happen inside
+ * `Context.create`, not here (PROTOCOL_SPEC §10.5).
+ *
+ * **Correlation id** — `x-correlation-id` (or `x-request-id`) is copied into
+ * `context.data["x-correlation-id"]` so existing log pipelines keep working.
+ *
+ * Pass a `resolveIdentity` override to plug in real authentication: whatever
+ * it returns wins over the header heuristics above.
+ */
+export class HonoContextFactory {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** Create an apcore `Context` from a Hono context, `Request`, or headers. */
+    createContext(source) {
+        const headers = toHeaders(source);
+        const identity = this.extractIdentity(headers);
+        const traceParent = this.extractTraceParent(headers);
+        const data = {
+            ...this.extractData(headers),
+            ...(this.options.data?.(headers) ?? {}),
+        };
+        return ApcoreContext.create(identity, traceParent, null, data);
+    }
+    extractTraceParent(headers) {
+        return TraceContext.extract(headers);
+    }
+    extractIdentity(headers) {
+        const custom = this.options.resolveIdentity?.(headers);
+        if (custom)
+            return custom;
+        const roles = this.extractRoles(headers);
+        const userId = headers.get('x-user-id');
+        if (userId) {
+            return createIdentity(userId, 'user', roles);
+        }
+        const auth = headers.get('authorization');
+        if (auth && auth.toLowerCase().startsWith('bearer ')) {
+            return createIdentity('bearer', 'api_key', roles);
+        }
+        // An `x-roles` header on its own still identifies a roled user — a demo
+        // shortcut for exercising role-based ACL without full authentication.
+        if (roles.length > 0) {
+            return createIdentity('u1', 'user', roles);
+        }
+        return createIdentity('anonymous', 'anonymous');
+    }
+    /** Parse the comma-separated `x-roles` header into a role list. */
+    extractRoles(headers) {
+        const raw = headers.get('x-roles');
+        if (!raw)
+            return [];
+        return raw
+            .split(',')
+            .map((role) => role.trim())
+            .filter((role) => role.length > 0);
+    }
+    extractData(headers) {
+        const data = {};
+        const correlationId = headers.get('x-correlation-id') ?? headers.get('x-request-id');
+        if (correlationId) {
+            data['x-correlation-id'] = correlationId;
+        }
+        return data;
+    }
+}
+/** Shared factory used by the default `apcore()` middleware. */
+export const defaultContextFactory = new HonoContextFactory();
+//# sourceMappingURL=hono-context.factory.js.map

package/dist/context/hono-context.factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono-context.factory.js","sourceRoot":"","sources":["../../src/context/hono-context.factory.ts"],"names":[],"mappings":"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"}

package/dist/context/index.d.ts

@@ -0,0 +1,3 @@
+export { HonoContextFactory, defaultContextFactory, toHeaders } from './hono-context.factory.js';
+export type { HeaderSource } from './hono-context.factory.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACjG,YAAY,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/context/index.js

@@ -0,0 +1,2 @@
+export { HonoContextFactory, defaultContextFactory, toHeaders } from './hono-context.factory.js';
+//# sourceMappingURL=index.js.map

package/dist/context/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/core/apcore.d.ts

@@ -0,0 +1,135 @@
+import { ApcoreRegistry } from './registry.js';
+import { ApcoreExecutor } from './executor.js';
+import { ApcoreMcpService } from '../mcp/apcore-mcp.service.js';
+import { ApcoreCliService } from '../cli/apcore-cli.service.js';
+import { ApcoreA2aService } from '../a2a/apcore-a2a.service.js';
+import { HonoContextFactory } from '../context/hono-context.factory.js';
+import type { HonoAppLike } from '../scanners/hono-route-scanner.js';
+import type { TargetResolver } from '../bridge/binding-loader.js';
+import type { MountableApp } from '../mcp/mount.js';
+import type { McpApp } from '../mcp/apcore-mcp.service.js';
+import type { ApcoreSettings } from '../config.js';
+import type { ApToolDefinition, HonoApcoreOptions, MountMcpOptions, RegisterMethodOptions, RegisterObjectOptions, RouteScanOptions } from '../types.js';
+/**
+ * The single entry point for wiring apcore into a Hono app.
+ *
+ * Owns the apcore `Registry` and `Executor`, the tool/route registration
+ * surface, and the optional MCP, CLI, and A2A services. Everything else in
+ * this package hangs off an instance of this class.
+ *
+ * @example
+ * ```ts
+ * const ap = createApcore({
+ *   tools: [listTodos, addTodo],
+ *   mcp: { explorer: true, allowExecute: true },
+ * });
+ *
+ * app.use('*', apcore(ap));
+ * await ap.init(app);                 // register tools, scan routes
+ * await ap.mountMcp(app);             // serve MCP on the same port
+ * ```
+ */
+export declare class HonoApcore {
+    private readonly options;
+    /** Canonical `APCORE_*` settings, environment merged with `options.settings`. */
+    readonly settings: ApcoreSettings;
+    /** Registry wrapper — register and inspect modules. */
+    readonly registry: ApcoreRegistry;
+    /** Executor wrapper — `call()`, `stream()`, `validate()`. */
+    readonly executor: ApcoreExecutor;
+    /** Builds per-request apcore `Context` objects from Hono requests. */
+    readonly contextFactory: HonoContextFactory;
+    private readonly _mcp;
+    private readonly _cli;
+    private readonly _a2a;
+    private readonly scanner;
+    private initPromise;
+    constructor(options?: HonoApcoreOptions);
+    /**
+     * The route-scan options this instance would use: the `APCORE_*` settings
+     * with the constructor's `routes` block layered on top.
+     *
+     * The `hono-apcore` CLI reads this so `scan` against a configured entry
+     * produces the same module set the app itself registers.
+     */
+    get routeOptions(): RouteScanOptions;
+    /** The MCP service, or `null` when `options.mcp` was omitted. */
+    get mcp(): ApcoreMcpService | null;
+    /** The CLI service, or `null` when `options.cli` was omitted. */
+    get cli(): ApcoreCliService | null;
+    /** The A2A service, or `null` when `options.a2a` was omitted. */
+    get a2a(): ApcoreA2aService | null;
+    /** Register one tool definition. Returns its module ID. */
+    registerTool(tool: ApToolDefinition): Promise<string>;
+    /** Register several tool definitions. Returns their module IDs. */
+    registerTools(tools: ApToolDefinition[]): Promise<string[]>;
+    /** Register a single method of a service object as a module. */
+    registerMethod(options: RegisterMethodOptions): Promise<string>;
+    /** Register several — or all — methods of a service object. */
+    registerObject(options: RegisterObjectOptions): Promise<string[]>;
+    /**
+     * Scan a Hono app's route table and register every matching route as a
+     * module that replays the route in-process via `app.request()`.
+     *
+     * Options are merged over the `routes` block from the constructor and the
+     * `APCORE_INCLUDE_PATHS` / `APCORE_EXCLUDE_PATHS` / `APCORE_MODULE_PREFIX`
+     * settings.
+     *
+     * @returns The module IDs that were registered.
+     */
+    scanRoutes(app: HonoAppLike, options?: RouteScanOptions): Promise<string[]>;
+    /**
+     * Load a YAML bindings file and register its entries.
+     *
+     * @param filePath - Path to the YAML file. Defaults to `options.bindings`.
+     * @param resolveTarget - Resolves each entry's `target` to a live handler.
+     */
+    loadBindings(filePath?: string, resolveTarget?: TargetResolver): Promise<string[]>;
+    /**
+     * Discover extensions, register the configured tools and bindings, scan the
+     * app's routes, and start any surface configured to run standalone.
+     *
+     * Idempotent: repeat calls await the first one instead of registering twice.
+     * When `APCORE_ENABLED` is false, this resolves without doing anything.
+     *
+     * @param app - Hono app whose routes should be scanned. Omit to skip scanning.
+     * @param routeOptions - Route-scan overrides for this call.
+     */
+    init(app?: HonoAppLike, routeOptions?: RouteScanOptions): Promise<void>;
+    /**
+     * Await an in-flight {@link init}. Resolves immediately when init has not
+     * been called — the middleware uses it to avoid racing a slow startup.
+     */
+    ready(): Promise<void>;
+    /** Layer the `APCORE_*` settings, the constructor options, and a per-call override. */
+    private mergeRouteOptions;
+    private runInit;
+    /**
+     * Mount the MCP endpoint into the Hono app so one port serves both HTTP and
+     * MCP. Node runtime only — see {@link mountMcp}.
+     *
+     * @throws {Error} When the instance was created without `options.mcp`.
+     */
+    mountMcp(app: MountableApp, options?: MountMcpOptions): Promise<McpApp>;
+    /**
+     * Convert the registered modules to OpenAI-compatible tool definitions.
+     *
+     * @throws {Error} When the instance was created without `options.mcp`.
+     */
+    toOpenaiTools(options?: {
+        embedAnnotations?: boolean;
+        strict?: boolean;
+        tags?: string[];
+        prefix?: string;
+    }): Promise<unknown[]>;
+    /** Shut down the MCP and A2A surfaces. */
+    close(): Promise<void>;
+}
+/**
+ * Create a {@link HonoApcore} instance.
+ *
+ * Sugar for `new HonoApcore(options)`, matching the `createX()` style the
+ * Hono ecosystem uses.
+ */
+export declare function createApcore(options?: HonoApcoreOptions): HonoApcore;
+//# sourceMappingURL=apcore.d.ts.map

package/dist/core/apcore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apcore.d.ts","sourceRoot":"","sources":["../../src/core/apcore.ts"],"names":[],"mappings":"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"}

package/dist/core/apcore.js

@@ -0,0 +1,257 @@
+import { Executor, Registry } from 'apcore-js';
+import { ApcoreRegistry } from './registry.js';
+import { ApcoreExecutor } from './executor.js';
+import { ApcoreMcpService } from '../mcp/apcore-mcp.service.js';
+import { ApcoreCliService } from '../cli/apcore-cli.service.js';
+import { ApcoreA2aService } from '../a2a/apcore-a2a.service.js';
+import { HonoContextFactory } from '../context/hono-context.factory.js';
+import { HonoRouteScanner } from '../scanners/hono-route-scanner.js';
+import { ApBindingLoader } from '../bridge/binding-loader.js';
+import { mountMcp as mountMcpEndpoint } from '../mcp/mount.js';
+import { loadSettings, toMcpTransport } from '../config.js';
+/**
+ * The single entry point for wiring apcore into a Hono app.
+ *
+ * Owns the apcore `Registry` and `Executor`, the tool/route registration
+ * surface, and the optional MCP, CLI, and A2A services. Everything else in
+ * this package hangs off an instance of this class.
+ *
+ * @example
+ * ```ts
+ * const ap = createApcore({
+ *   tools: [listTodos, addTodo],
+ *   mcp: { explorer: true, allowExecute: true },
+ * });
+ *
+ * app.use('*', apcore(ap));
+ * await ap.init(app);                 // register tools, scan routes
+ * await ap.mountMcp(app);             // serve MCP on the same port
+ * ```
+ */
+export class HonoApcore {
+    options;
+    /** Canonical `APCORE_*` settings, environment merged with `options.settings`. */
+    settings;
+    /** Registry wrapper — register and inspect modules. */
+    registry;
+    /** Executor wrapper — `call()`, `stream()`, `validate()`. */
+    executor;
+    /** Builds per-request apcore `Context` objects from Hono requests. */
+    contextFactory;
+    _mcp;
+    _cli;
+    _a2a;
+    scanner = new HonoRouteScanner();
+    initPromise = null;
+    constructor(options = {}) {
+        this.options = options;
+        this.settings = loadSettings(undefined, options.settings);
+        const registry = new Registry({ extensionsDir: options.extensionsDir ?? null });
+        const executor = new Executor({
+            registry,
+            acl: options.acl ?? null,
+            middlewares: options.middleware ?? null,
+        });
+        this.registry = new ApcoreRegistry(registry);
+        this.executor = new ApcoreExecutor(executor);
+        this.contextFactory = new HonoContextFactory();
+        this._mcp = options.mcp
+            ? new ApcoreMcpService(this.registry, this.executor, {
+                ...options.mcp,
+                // The APCORE_* settings supply the defaults; explicit config wins.
+                transport: options.mcp.transport ?? toMcpTransport(this.settings.transport),
+                host: options.mcp.host ?? this.settings.host,
+                port: options.mcp.port ?? this.settings.port,
+            })
+            : null;
+        this._cli = options.cli ? new ApcoreCliService(this.registry, options.cli) : null;
+        this._a2a = options.a2a
+            ? new ApcoreA2aService(this.registry, this.executor, options.a2a)
+            : null;
+    }
+    // -------------------------------------------------------------------------
+    // Surfaces
+    // -------------------------------------------------------------------------
+    /**
+     * The route-scan options this instance would use: the `APCORE_*` settings
+     * with the constructor's `routes` block layered on top.
+     *
+     * The `hono-apcore` CLI reads this so `scan` against a configured entry
+     * produces the same module set the app itself registers.
+     */
+    get routeOptions() {
+        return this.mergeRouteOptions();
+    }
+    /** The MCP service, or `null` when `options.mcp` was omitted. */
+    get mcp() {
+        return this._mcp;
+    }
+    /** The CLI service, or `null` when `options.cli` was omitted. */
+    get cli() {
+        return this._cli;
+    }
+    /** The A2A service, or `null` when `options.a2a` was omitted. */
+    get a2a() {
+        return this._a2a;
+    }
+    // -------------------------------------------------------------------------
+    // Registration
+    // -------------------------------------------------------------------------
+    /** Register one tool definition. Returns its module ID. */
+    registerTool(tool) {
+        return this.registry.registerTool(tool, { modulePrefix: this.settings.modulePrefix });
+    }
+    /** Register several tool definitions. Returns their module IDs. */
+    registerTools(tools) {
+        return this.registry.registerTools(tools, { modulePrefix: this.settings.modulePrefix });
+    }
+    /** Register a single method of a service object as a module. */
+    registerMethod(options) {
+        return this.registry.registerMethod(options);
+    }
+    /** Register several — or all — methods of a service object. */
+    registerObject(options) {
+        return this.registry.registerObject(options);
+    }
+    /**
+     * Scan a Hono app's route table and register every matching route as a
+     * module that replays the route in-process via `app.request()`.
+     *
+     * Options are merged over the `routes` block from the constructor and the
+     * `APCORE_INCLUDE_PATHS` / `APCORE_EXCLUDE_PATHS` / `APCORE_MODULE_PREFIX`
+     * settings.
+     *
+     * @returns The module IDs that were registered.
+     */
+    async scanRoutes(app, options = {}) {
+        const merged = this.mergeRouteOptions(options);
+        const ids = [];
+        for (const { module, execute } of this.scanner.scanWithExecutors(app, merged)) {
+            try {
+                ids.push(await this.registry.registerScanned(module, execute));
+            }
+            catch (err) {
+                // A path segment can collide with a reserved namespace ("internal",
+                // "system", ...) or otherwise fail §2.7 validation. Name the route so
+                // the fix is obvious instead of surfacing a bare module-ID error.
+                const reason = err instanceof Error ? err.message : String(err);
+                throw new Error(`Cannot register route ${module.target} as module "${module.moduleId}": ${reason}. ` +
+                    'Give it an explicit id via routes.overrides, or drop it with routes.excludePaths.', { cause: err });
+            }
+        }
+        return ids;
+    }
+    /**
+     * Load a YAML bindings file and register its entries.
+     *
+     * @param filePath - Path to the YAML file. Defaults to `options.bindings`.
+     * @param resolveTarget - Resolves each entry's `target` to a live handler.
+     */
+    async loadBindings(filePath, resolveTarget) {
+        const path = filePath ?? this.options.bindings;
+        if (!path)
+            return [];
+        return new ApBindingLoader(this.registry, resolveTarget).loadFromFile(path);
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Discover extensions, register the configured tools and bindings, scan the
+     * app's routes, and start any surface configured to run standalone.
+     *
+     * Idempotent: repeat calls await the first one instead of registering twice.
+     * When `APCORE_ENABLED` is false, this resolves without doing anything.
+     *
+     * @param app - Hono app whose routes should be scanned. Omit to skip scanning.
+     * @param routeOptions - Route-scan overrides for this call.
+     */
+    init(app, routeOptions) {
+        this.initPromise ??= this.runInit(app, routeOptions);
+        return this.initPromise;
+    }
+    /**
+     * Await an in-flight {@link init}. Resolves immediately when init has not
+     * been called — the middleware uses it to avoid racing a slow startup.
+     */
+    async ready() {
+        await this.initPromise;
+    }
+    /** Layer the `APCORE_*` settings, the constructor options, and a per-call override. */
+    mergeRouteOptions(options = {}) {
+        return {
+            modulePrefix: this.settings.modulePrefix || undefined,
+            includePaths: this.settings.includePaths,
+            excludePaths: this.settings.excludePaths,
+            ...this.options.routes,
+            ...options,
+        };
+    }
+    async runInit(app, routeOptions) {
+        if (!this.settings.enabled)
+            return;
+        if (this.options.extensionsDir) {
+            await this.registry.discover();
+        }
+        if (this.options.tools?.length) {
+            await this.registerTools(this.options.tools);
+        }
+        if (this.options.bindings) {
+            await this.loadBindings();
+        }
+        if (app) {
+            await this.scanRoutes(app, routeOptions);
+        }
+        // Surfaces start last, so every module is registered before a client can
+        // list the tools.
+        if (this._a2a && this.options.a2a?.port !== undefined) {
+            await this._a2a.start();
+        }
+        if (this._mcp && this.options.mcp?.transport) {
+            await this._mcp.start();
+        }
+    }
+    /**
+     * Mount the MCP endpoint into the Hono app so one port serves both HTTP and
+     * MCP. Node runtime only — see {@link mountMcp}.
+     *
+     * @throws {Error} When the instance was created without `options.mcp`.
+     */
+    async mountMcp(app, options = {}) {
+        if (!this._mcp) {
+            throw new Error('mountMcp() requires the MCP surface. Pass an `mcp` block to createApcore().');
+        }
+        return mountMcpEndpoint(app, this._mcp, {
+            explorer: this.options.mcp?.explorer,
+            explorerPrefix: this.options.mcp?.explorerPrefix,
+            allowExecute: this.options.mcp?.allowExecute,
+            ...options,
+        });
+    }
+    /**
+     * Convert the registered modules to OpenAI-compatible tool definitions.
+     *
+     * @throws {Error} When the instance was created without `options.mcp`.
+     */
+    async toOpenaiTools(options) {
+        if (!this._mcp) {
+            throw new Error('toOpenaiTools() requires the MCP surface. Pass an `mcp` block to createApcore().');
+        }
+        return this._mcp.toOpenaiTools(options);
+    }
+    /** Shut down the MCP and A2A surfaces. */
+    async close() {
+        await this._mcp?.stop();
+        this._a2a?.stop();
+    }
+}
+/**
+ * Create a {@link HonoApcore} instance.
+ *
+ * Sugar for `new HonoApcore(options)`, matching the `createX()` style the
+ * Hono ecosystem uses.
+ */
+export function createApcore(options = {}) {
+    return new HonoApcore(options);
+}
+//# sourceMappingURL=apcore.js.map

package/dist/core/apcore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apcore.js","sourceRoot":"","sources":["../../src/core/apcore.ts"],"names":[],"mappings":"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"}

package/dist/core/executor.d.ts

@@ -0,0 +1,32 @@
+import type { Context, Executor, PreflightResult } from 'apcore-js';
+/**
+ * Thin wrapper around the upstream apcore-js `Executor`.
+ *
+ * Every delegation normalises `null` / `undefined` inputs to `{}` so callers
+ * never have to think about nullability at the call site.
+ */
+export declare class ApcoreExecutor {
+    private readonly executor;
+    constructor(executor: Executor);
+    /** The underlying apcore-js `Executor`. */
+    get raw(): Executor;
+    /**
+     * Execute a module by ID.
+     *
+     * @param moduleId - Fully-qualified module identifier (e.g. `"todo.list"`).
+     * @param inputs   - Key/value inputs; `null` / `undefined` become `{}`.
+     * @param context  - Optional execution context (identity, trace, data).
+     */
+    call(moduleId: string, inputs?: Record<string, unknown> | null, context?: Context | null): Promise<Record<string, unknown>>;
+    /**
+     * Stream execution results from a module, yielding each chunk produced by
+     * the upstream generator.
+     */
+    stream(moduleId: string, inputs?: Record<string, unknown> | null, context?: Context | null): AsyncGenerator<Record<string, unknown>>;
+    /**
+     * Run preflight checks — schema, ACL, approval, call-chain — without
+     * executing the module.
+     */
+    validate(moduleId: string, inputs?: Record<string, unknown> | null, context?: Context | null): Promise<PreflightResult>;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/core/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/core/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEpE;;;;;GAKG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,QAAQ;IAE/C,2CAA2C;IAC3C,IAAI,GAAG,IAAI,QAAQ,CAElB;IAED;;;;;;OAMG;IACG,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACvC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GACvB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAInC;;;OAGG;IACI,MAAM,CACX,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACvC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GACvB,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAI1C;;;OAGG;IACH,QAAQ,CACN,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,EACvC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GACvB,OAAO,CAAC,eAAe,CAAC;CAG5B"}

package/dist/core/executor.js

@@ -0,0 +1,41 @@
+/**
+ * Thin wrapper around the upstream apcore-js `Executor`.
+ *
+ * Every delegation normalises `null` / `undefined` inputs to `{}` so callers
+ * never have to think about nullability at the call site.
+ */
+export class ApcoreExecutor {
+    executor;
+    constructor(executor) {
+        this.executor = executor;
+    }
+    /** The underlying apcore-js `Executor`. */
+    get raw() {
+        return this.executor;
+    }
+    /**
+     * Execute a module by ID.
+     *
+     * @param moduleId - Fully-qualified module identifier (e.g. `"todo.list"`).
+     * @param inputs   - Key/value inputs; `null` / `undefined` become `{}`.
+     * @param context  - Optional execution context (identity, trace, data).
+     */
+    async call(moduleId, inputs, context) {
+        return this.executor.call(moduleId, inputs ?? {}, context);
+    }
+    /**
+     * Stream execution results from a module, yielding each chunk produced by
+     * the upstream generator.
+     */
+    async *stream(moduleId, inputs, context) {
+        yield* this.executor.stream(moduleId, inputs ?? {}, context);
+    }
+    /**
+     * Run preflight checks — schema, ACL, approval, call-chain — without
+     * executing the module.
+     */
+    validate(moduleId, inputs, context) {
+        return this.executor.validate(moduleId, inputs ?? {}, context);
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/core/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/core/executor.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,cAAc;IACI;IAA7B,YAA6B,QAAkB;QAAlB,aAAQ,GAAR,QAAQ,CAAU;IAAG,CAAC;IAEnD,2CAA2C;IAC3C,IAAI,GAAG;QACL,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,CACR,QAAgB,EAChB,MAAuC,EACvC,OAAwB;QAExB,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;IAC7D,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,CAAC,MAAM,CACX,QAAgB,EAChB,MAAuC,EACvC,OAAwB;QAExB,KAAK,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;IAC/D,CAAC;IAED;;;OAGG;IACH,QAAQ,CACN,QAAgB,EAChB,MAAuC,EACvC,OAAwB;QAExB,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;IACjE,CAAC;CACF"}