apcore-mcp 0.13.0 → 0.15.0

package/dist/acl-builder.js

@@ -0,0 +1,115 @@
+/**
+ * Build an apcore `ACL` instance from a Config Bus `mcp.acl` section.
+ *
+ * Config Bus schema (YAML, shared across Python/TS/Rust bridges):
+ *
+ * ```yaml
+ * mcp:
+ *   acl:
+ *     default_effect: deny          # or "allow" — default "deny" (fail-secure)
+ *     rules:
+ *       - callers: ["role:admin"]
+ *         targets: ["sys.*"]
+ *         effect: allow
+ *         description: "Admins can reach system modules"
+ *       - callers: ["*"]
+ *         targets: ["sys.reload", "sys.toggle"]
+ *         effect: deny
+ *         conditions:
+ *           identity_types: ["human", "system"]
+ * ```
+ *
+ * Mirrors the Python `acl_builder.build_acl_from_config` contract. Invalid
+ * entries throw so misconfiguration fails loudly at startup.
+ */
+const ALLOWED_EFFECTS = new Set(["allow", "deny"]);
+const ALLOWED_RULE_KEYS = new Set([
+    "callers",
+    "targets",
+    "effect",
+    "description",
+    "conditions",
+]);
+/**
+ * Construct an apcore `ACL` from a Config Bus `mcp.acl` mapping.
+ *
+ * Returns `null` when `aclConfig` is falsy (no ACL section configured).
+ * Throws on malformed entries.
+ */
+export async function buildAclFromConfig(aclConfig) {
+    if (aclConfig === null || aclConfig === undefined)
+        return null;
+    if (typeof aclConfig !== "object" || Array.isArray(aclConfig)) {
+        throw new Error(`mcp.acl must be a mapping with 'rules' and optional 'default_effect', ` +
+            `got ${Array.isArray(aclConfig) ? "array" : typeof aclConfig}`);
+    }
+    const cfg = aclConfig;
+    const rulesRaw = cfg.rules;
+    // Validate rules type up-front — even for empty configs — to keep errors
+    // visible at startup rather than silently returning null.
+    if (rulesRaw !== undefined && !Array.isArray(rulesRaw)) {
+        throw new Error(`mcp.acl.rules must be a list, got ${typeof rulesRaw}`);
+    }
+    const hasRules = Array.isArray(rulesRaw) && rulesRaw.length > 0;
+    const hasDefault = cfg.default_effect !== undefined;
+    if (!hasRules && !hasDefault) {
+        return null; // Empty config section — treat as no ACL
+    }
+    let apcore;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        apcore = (await import("apcore-js"));
+    }
+    catch (err) {
+        throw new Error(`Config Bus 'mcp.acl' requires apcore-js>=0.18 with ACL support: ${err.message}`);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const ACL = (apcore.ACL ?? apcore.default?.ACL);
+    if (!ACL) {
+        throw new Error("apcore-js does not export ACL");
+    }
+    const defaultEffect = (cfg.default_effect ?? "deny");
+    if (!ALLOWED_EFFECTS.has(defaultEffect)) {
+        throw new Error(`mcp.acl.default_effect must be 'allow' or 'deny', got '${defaultEffect}'`);
+    }
+    const rawRules = (rulesRaw ?? []);
+    const rules = [];
+    for (let idx = 0; idx < rawRules.length; idx += 1) {
+        const entry = rawRules[idx];
+        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+            throw new Error(`mcp.acl.rules[${idx}] must be an object, got ${Array.isArray(entry) ? "array" : typeof entry}`);
+        }
+        const rec = entry;
+        const extra = Object.keys(rec).filter((k) => !ALLOWED_RULE_KEYS.has(k));
+        if (extra.length) {
+            throw new Error(`mcp.acl.rules[${idx}] got unexpected keys: ${extra.sort().join(", ")}`);
+        }
+        const callers = rec.callers;
+        const targets = rec.targets;
+        const effect = rec.effect;
+        if (!Array.isArray(callers) || callers.length === 0) {
+            throw new Error(`mcp.acl.rules[${idx}] 'callers' must be a non-empty list`);
+        }
+        if (!Array.isArray(targets) || targets.length === 0) {
+            throw new Error(`mcp.acl.rules[${idx}] 'targets' must be a non-empty list`);
+        }
+        if (typeof effect !== "string" || !ALLOWED_EFFECTS.has(effect)) {
+            throw new Error(`mcp.acl.rules[${idx}] 'effect' must be 'allow' or 'deny', got '${effect}'`);
+        }
+        const rule = {
+            callers: [...callers],
+            targets: [...targets],
+            effect: effect,
+            description: typeof rec.description === "string" ? rec.description : "",
+        };
+        if (rec.conditions !== undefined && rec.conditions !== null) {
+            if (typeof rec.conditions !== "object" || Array.isArray(rec.conditions)) {
+                throw new Error(`mcp.acl.rules[${idx}] 'conditions' must be an object or null`);
+            }
+            rule.conditions = rec.conditions;
+        }
+        rules.push(rule);
+    }
+    return new ACL(rules, defaultEffect);
+}
+//# sourceMappingURL=acl-builder.js.map

package/dist/acl-builder.js.map

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

package/dist/adapters/annotations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/adapters/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAczE,qBAAa,gBAAgB;IAC3B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,kBAAkB;IAoB3E;;;;;;OAMG;IACH,mBAAmB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,MAAM;IAkElE;;;;OAIG;IACH,mBAAmB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO;CAOpE"}
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/adapters/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAkBzE,qBAAa,gBAAgB;IAC3B;;;;;;;;;OASG;IACH,gBAAgB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,kBAAkB;IAoB3E;;;;;;OAMG;IACH,mBAAmB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,MAAM;IAyFlE;;;;OAIG;IACH,mBAAmB,CAAC,WAAW,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO;CAOpE"}

package/dist/adapters/annotations.js

@@ -15,6 +15,10 @@ const DEFAULT_ANNOTATIONS = {
     streaming: false,
     cacheable: false,
     paginated: false,
+    // [AM-2] Numeric/string defaults for cache_ttl and pagination_style.
+    // Spec: default values omitted from suffix.
+    cacheTtl: 0,
+    paginationStyle: "cursor",
 };
 export class AnnotationMapper {
     /**
@@ -79,12 +83,29 @@ export class AnnotationMapper {
             parts.push(`streaming=${annotations.streaming}`);
         if ((annotations.cacheable ?? false) !== DEFAULT_ANNOTATIONS.cacheable)
             parts.push(`cacheable=${annotations.cacheable}`);
+        // [AM-2] Skip cache_ttl when equal to default (0). Spec: "Default
+        // values omitted from suffix". Pre-fix TS emitted any non-null
+        // value including the default, diverging from Python+Rust.
+        if (annotations.cacheTtl !== undefined &&
+            annotations.cacheTtl !== null &&
+            annotations.cacheTtl !== DEFAULT_ANNOTATIONS.cacheTtl)
+            parts.push(`cache_ttl=${annotations.cacheTtl}`);
+        if (annotations.cacheKeyFields !== undefined &&
+            annotations.cacheKeyFields !== null &&
+            annotations.cacheKeyFields.length > 0)
+            parts.push(`cache_key_fields=[${annotations.cacheKeyFields.join(",")}]`);
         if ((annotations.paginated ?? false) !== DEFAULT_ANNOTATIONS.paginated)
             parts.push(`paginated=${annotations.paginated}`);
-        // Append mcp_-prefixed extra fields
+        // [AM-2] Skip pagination_style when equal to default ("cursor").
+        if (annotations.paginationStyle !== undefined &&
+            annotations.paginationStyle !== null &&
+            annotations.paginationStyle !== DEFAULT_ANNOTATIONS.paginationStyle)
+            parts.push(`pagination_style=${annotations.paginationStyle}`);
+        // Append mcp_-prefixed extra fields (sorted alphabetically for deterministic output,
+        // matching Python+Rust sort behavior). [D11-022]
         const extraLines = [];
         if (annotations.extra && typeof annotations.extra === "object") {
-            for (const [key, value] of Object.entries(annotations.extra)) {
+            for (const [key, value] of Object.entries(annotations.extra).sort(([a], [b]) => a.localeCompare(b))) {
                 if (key.startsWith("mcp_") && typeof value === "string") {
                     const strippedKey = key.slice(4); // remove "mcp_" prefix
                     extraLines.push(`${strippedKey}: ${value}`);

package/dist/adapters/annotations.js.map

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

package/dist/adapters/errors.d.ts

@@ -4,8 +4,23 @@
  * Handles ModuleError instances with specific error codes, sanitizes
  * internal error details, formats schema validation errors with
  * field-level detail, and extracts AI guidance fields.
+ *
+ * Cross-language contract: apcore-js exposes concrete error classes
+ * (e.g. `TaskLimitExceededError`). We prefer `instanceof` dispatch when
+ * those classes are importable so structured fields flow through
+ * losslessly; we fall back to duck-typing (`error.code` inspection)
+ * when apcore-js is unavailable or the caller constructs a bare
+ * `ModuleError`.
  */
 import type { McpErrorResponse } from "../types.js";
+/**
+ * Canonical GENERAL_INTERNAL_ERROR envelope for non-ModuleError fallback.
+ *
+ * All three SDKs (Python, TypeScript, Rust) emit byte-identical envelopes so
+ * MCP clients can branch on `errorType === "GENERAL_INTERNAL_ERROR"` portably.
+ * See `apcore-mcp/docs/features/error-mapper.md` (EM-6).
+ */
+export declare function internalErrorResponse(): McpErrorResponse;
 export declare class ErrorMapper {
     /**
      * Convert an error to an MCP error response.
@@ -14,6 +29,28 @@ export declare class ErrorMapper {
      * Applies sanitization and formatting rules based on the error code.
      */
     toMcpError(error: unknown): McpErrorResponse;
+    /**
+     * Generic-error fallback for arbitrary inputs.
+     *
+     * Ports Rust's `to_mcp_error_any` downcast pattern: if the input is a
+     * `ModuleError` subclass, delegate to {@link toMcpError} so structured
+     * fields (code, details, AI guidance) survive. Otherwise — plain `Error`,
+     * unrelated subclass, or non-error object — return the canonical
+     * GENERAL_INTERNAL_ERROR envelope. The original class, message, stack,
+     * and details are deliberately discarded in that branch (security: avoid
+     * leaking server-side state). [D9-004]
+     */
+    toMcpErrorAny(error: unknown): McpErrorResponse;
+    /**
+     * Preferred `instanceof` dispatch for concrete apcore-js error classes.
+     *
+     * When the cache hasn't been populated yet (first call before the lazy
+     * load settles), returns null and the caller falls back to duck-typing.
+     * Once the cache is warm, subsequent calls produce identical output
+     * whether the error was thrown as a concrete class or a duck-typed
+     * plain object — the duck-typed branch below handles the latter.
+     */
+    private _matchApcoreErrorInstance;
     /**
      * Extract AI guidance fields from error and attach non-undefined values to result.
      */

package/dist/adapters/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/adapters/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAgBpD,qBAAa,WAAW;IACtB;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB;IAwK5C;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAazB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAQ7B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAetB;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;CA4B/B"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/adapters/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,IAAI,gBAAgB,CAOxD;AA0DD,qBAAa,WAAW;IACtB;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB;IA+O5C;;;;;;;;;;OAUG;IACH,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB;IAQ/C;;;;;;;;OAQG;IACH,OAAO,CAAC,yBAAyB;IAyDjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAazB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAQ7B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAetB;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;CA4B/B"}

package/dist/adapters/errors.js

@@ -4,8 +4,64 @@
  * Handles ModuleError instances with specific error codes, sanitizes
  * internal error details, formats schema validation errors with
  * field-level detail, and extracts AI guidance fields.
+ *
+ * Cross-language contract: apcore-js exposes concrete error classes
+ * (e.g. `TaskLimitExceededError`). We prefer `instanceof` dispatch when
+ * those classes are importable so structured fields flow through
+ * losslessly; we fall back to duck-typing (`error.code` inspection)
+ * when apcore-js is unavailable or the caller constructs a bare
+ * `ModuleError`.
  */
 import { ErrorCodes } from "../types.js";
+/**
+ * Canonical GENERAL_INTERNAL_ERROR envelope for non-ModuleError fallback.
+ *
+ * All three SDKs (Python, TypeScript, Rust) emit byte-identical envelopes so
+ * MCP clients can branch on `errorType === "GENERAL_INTERNAL_ERROR"` portably.
+ * See `apcore-mcp/docs/features/error-mapper.md` (EM-6).
+ */
+export function internalErrorResponse() {
+    return {
+        isError: true,
+        errorType: ErrorCodes.GENERAL_INTERNAL_ERROR,
+        message: "Internal error occurred",
+        details: null,
+    };
+}
+/**
+ * Lazy snapshot of apcore-js error classes used for `instanceof` dispatch.
+ * Populated on first use; falls back to duck-typing when apcore-js is
+ * unavailable. Cached across calls for perf.
+ *
+ * `ModuleError` is the documented base class for all structured apcore errors.
+ * `toMcpErrorAny` uses it as a downcast pivot, mirroring Rust's
+ * `to_mcp_error_any` which checks `err.downcast_ref::<ModuleError>()` before
+ * collapsing to the canonical envelope.
+ */
+let _apcoreErrorClasses = null;
+async function _loadApcoreErrorClasses() {
+    if (_apcoreErrorClasses)
+        return _apcoreErrorClasses;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const apcore = (await import("apcore-js"));
+        _apcoreErrorClasses = {
+            ModuleError: apcore.ModuleError,
+            TaskLimitExceededError: apcore.TaskLimitExceededError,
+            VersionConstraintError: apcore.VersionConstraintError,
+            DependencyNotFoundError: apcore.DependencyNotFoundError,
+            DependencyVersionMismatchError: apcore.DependencyVersionMismatchError,
+            loaded: true,
+        };
+    }
+    catch {
+        _apcoreErrorClasses = { loaded: true };
+    }
+    return _apcoreErrorClasses;
+}
+// Kick off the load eagerly but don't await; toMcpError is sync and will
+// observe the populated cache on subsequent invocations.
+void _loadApcoreErrorClasses();
 /** Internal error codes that should be sanitized to a generic message. */
 const INTERNAL_ERROR_CODES = new Set([
     ErrorCodes.CALL_DEPTH_EXCEEDED,
@@ -36,6 +92,13 @@ export class ErrorMapper {
                 retryable: true,
             };
         }
+        // Preferred: instanceof dispatch against apcore-js's concrete error
+        // classes so cross-language contracts stay tight. Falls back to the
+        // duck-typed code-based dispatch below when apcore-js was unavailable
+        // at load time.
+        const instanceMatch = this._matchApcoreErrorInstance(error);
+        if (instanceMatch)
+            return instanceMatch;
         // Duck-type check for ModuleError-like objects
         if (this._isModuleError(error)) {
             const code = error.code;
@@ -70,17 +133,15 @@ export class ErrorMapper {
                 this._attachAiGuidance(error, result);
                 return result;
             }
-            // Approval pending -> narrow details to approvalId only
-            // NOTE: apcore-js may use camelCase (approvalId) or snake_case (approval_id).
-            // Check both to stay compatible with either convention.
+            // Approval pending -> narrow details to approvalId only.
+            // [D10-003] Cross-language parity: upstream apcore SDKs emit
+            // snake_case (`approval_id`) exclusively, so the previous dual-key
+            // branch for camelCase `approvalId` was dormant and diverged from
+            // Python/Rust contracts (which accept snake_case only). Drop the
+            // camelCase source key; the output stays camelCase per MCP convention.
             if (code === ErrorCodes.APPROVAL_PENDING) {
-                const idKey = details && "approvalId" in details
-                    ? "approvalId"
-                    : details && "approval_id" in details
-                        ? "approval_id"
-                        : null;
-                const narrowed = idKey
-                    ? { approvalId: details[idKey] }
+                const narrowed = details && "approval_id" in details
+                    ? { approvalId: details["approval_id"] }
                     : null;
                 const result = {
                     isError: true,
@@ -161,6 +222,67 @@ export class ErrorMapper {
                 this._attachAiGuidance(error, result);
                 return result;
             }
+            // Dependency resolution errors (apcore 0.19) -> pass through with user-fixable hint
+            if (code === ErrorCodes.DEPENDENCY_NOT_FOUND ||
+                code === ErrorCodes.DEPENDENCY_VERSION_MISMATCH) {
+                const result = {
+                    isError: true,
+                    errorType: code,
+                    message: error.message,
+                    details,
+                    userFixable: true,
+                };
+                this._attachAiGuidance(error, result);
+                return result;
+            }
+            // Task limit exceeded -> retryable
+            if (code === ErrorCodes.TASK_LIMIT_EXCEEDED) {
+                const result = {
+                    isError: true,
+                    errorType: code,
+                    message: error.message,
+                    details,
+                    retryable: true,
+                };
+                this._attachAiGuidance(error, result);
+                return result;
+            }
+            // apcore 0.20.0 sync alignment A-001: CircuitBreakerOpenError ->
+            // retryable=true with the per-module recovery hint already attached
+            // by apcore-js's error class (mirrored via _attachAiGuidance).
+            if (code === ErrorCodes.CIRCUIT_BREAKER_OPEN) {
+                const result = {
+                    isError: true,
+                    errorType: code,
+                    message: error.message,
+                    details,
+                    retryable: true,
+                };
+                this._attachAiGuidance(error, result);
+                if (!result.aiGuidance) {
+                    result.aiGuidance =
+                        "Module's circuit breaker is OPEN — repeated failures have tripped " +
+                            "the breaker. Wait until the recovery window elapses, then retry; " +
+                            "the breaker will move to HALF_OPEN and accept a trial call.";
+                }
+                return result;
+            }
+            // Binding / version-constraint validation errors (apcore 0.19) -> pass through
+            if (code === ErrorCodes.VERSION_CONSTRAINT_INVALID ||
+                code === ErrorCodes.BINDING_SCHEMA_INFERENCE_FAILED ||
+                code === ErrorCodes.BINDING_SCHEMA_MODE_CONFLICT ||
+                code === ErrorCodes.BINDING_STRICT_SCHEMA_INCOMPATIBLE ||
+                code === ErrorCodes.BINDING_POLICY_VIOLATION) {
+                const result = {
+                    isError: true,
+                    errorType: code,
+                    message: error.message,
+                    details,
+                    userFixable: true,
+                };
+                this._attachAiGuidance(error, result);
+                return result;
+            }
             // Other known ModuleError codes -> pass through
             const result = {
                 isError: true,
@@ -171,13 +293,87 @@ export class ErrorMapper {
             this._attachAiGuidance(error, result);
             return result;
         }
-        // Unknown/unexpected exceptions -> generic error
-        return {
-            isError: true,
-            errorType: ErrorCodes.INTERNAL_ERROR,
-            message: "Internal error occurred",
-            details: null,
-        };
+        // Unknown/unexpected exceptions -> canonical GENERAL_INTERNAL_ERROR envelope (EM-6).
+        // Mirrors Python `internal_error_response()` and Rust `to_mcp_error_any()`.
+        return internalErrorResponse();
+    }
+    /**
+     * Generic-error fallback for arbitrary inputs.
+     *
+     * Ports Rust's `to_mcp_error_any` downcast pattern: if the input is a
+     * `ModuleError` subclass, delegate to {@link toMcpError} so structured
+     * fields (code, details, AI guidance) survive. Otherwise — plain `Error`,
+     * unrelated subclass, or non-error object — return the canonical
+     * GENERAL_INTERNAL_ERROR envelope. The original class, message, stack,
+     * and details are deliberately discarded in that branch (security: avoid
+     * leaking server-side state). [D9-004]
+     */
+    toMcpErrorAny(error) {
+        const ModuleError = _apcoreErrorClasses?.ModuleError;
+        if (ModuleError && error instanceof ModuleError) {
+            return this.toMcpError(error);
+        }
+        return internalErrorResponse();
+    }
+    /**
+     * Preferred `instanceof` dispatch for concrete apcore-js error classes.
+     *
+     * When the cache hasn't been populated yet (first call before the lazy
+     * load settles), returns null and the caller falls back to duck-typing.
+     * Once the cache is warm, subsequent calls produce identical output
+     * whether the error was thrown as a concrete class or a duck-typed
+     * plain object — the duck-typed branch below handles the latter.
+     */
+    _matchApcoreErrorInstance(error) {
+        if (!(error instanceof Error) || !_apcoreErrorClasses?.loaded)
+            return null;
+        const classes = _apcoreErrorClasses;
+        const asModErr = error;
+        if (classes.TaskLimitExceededError && error instanceof classes.TaskLimitExceededError) {
+            const result = {
+                isError: true,
+                errorType: ErrorCodes.TASK_LIMIT_EXCEEDED,
+                message: error.message,
+                details: asModErr.details ?? null,
+                retryable: true,
+            };
+            this._attachAiGuidance(error, result);
+            return result;
+        }
+        if (classes.DependencyNotFoundError && error instanceof classes.DependencyNotFoundError) {
+            const result = {
+                isError: true,
+                errorType: ErrorCodes.DEPENDENCY_NOT_FOUND,
+                message: error.message,
+                details: asModErr.details ?? null,
+                userFixable: true,
+            };
+            this._attachAiGuidance(error, result);
+            return result;
+        }
+        if (classes.DependencyVersionMismatchError && error instanceof classes.DependencyVersionMismatchError) {
+            const result = {
+                isError: true,
+                errorType: ErrorCodes.DEPENDENCY_VERSION_MISMATCH,
+                message: error.message,
+                details: asModErr.details ?? null,
+                userFixable: true,
+            };
+            this._attachAiGuidance(error, result);
+            return result;
+        }
+        if (classes.VersionConstraintError && error instanceof classes.VersionConstraintError) {
+            const result = {
+                isError: true,
+                errorType: ErrorCodes.VERSION_CONSTRAINT_INVALID,
+                message: error.message,
+                details: asModErr.details ?? null,
+                userFixable: true,
+            };
+            this._attachAiGuidance(error, result);
+            return result;
+        }
+        return null;
     }
     /**
      * Extract AI guidance fields from error and attach non-undefined values to result.

package/dist/adapters/errors.js.map

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

package/dist/adapters/id-normalizer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * ModuleIDNormalizer - Converts between apcore module IDs and OpenAI tool names.
+ *
+ * apcore uses dot-separated module IDs (e.g. "myorg.tools.search").
+ *
+ * [MID-6] MCP tool names accept dots and hyphens (and dot-notation is the
+ * apcore convention), so this normalizer is intended ONLY for the OpenAI
+ * function-calling format, which restricts function names to `[a-zA-Z0-9_-]`.
+ * Pre-fix doc here claimed "MCP tool names use hyphens" — that is incorrect
+ * and contradicts the spec at `docs/features/openai-converter.md`. This
+ * normalizer must NOT be applied on the MCP path.
+ */
+export declare class ModuleIDNormalizer {
+    /**
+     * Normalize an apcore module ID to an MCP-compatible tool name.
+     *
+     * Validates the module ID against MODULE_ID_PATTERN before converting.
+     * Replaces dots (`.`) with hyphens (`-`).
+     */
+    normalize(moduleId: string): string;
+    /**
+     * Denormalize an MCP tool name back to an apcore module ID.
+     *
+     * Replaces hyphens (`-`) with dots (`.`).
+     */
+    denormalize(toolName: string): string;
+    /**
+     * Bijection-guarded variant of denormalize. [MID-5]
+     *
+     * Returns the denormalized module ID if `toolName` is a valid pre-image of
+     * `normalize()` (i.e. the dash→dot replacement yields a string matching
+     * MODULE_ID_PATTERN). Returns `null` for inputs that could not have been
+     * produced by `normalize()`.
+     *
+     * Cross-language parity [D11-3]: validates the denormalized result against
+     * the shared MODULE_ID_PATTERN so underscores within segments (e.g.
+     * `"my_mod-v2"` → `"my_mod.v2"`) round-trip identically to Python/Rust.
+     */
+    tryDenormalize(toolName: string): string | null;
+}
+//# sourceMappingURL=id-normalizer.d.ts.map

package/dist/adapters/id-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-normalizer.d.ts","sourceRoot":"","sources":["../../src/adapters/id-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,qBAAa,kBAAkB;IAC7B;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IASnC;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIrC;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAMhD"}