@exellix/ai-tasks 8.1.16 → 8.2.0

package/dist/invocation/resolveProfileInvocationRouting.js

@@ -0,0 +1,118 @@
+import { AIProfilesError, resolveAIProfile } from "@x12i/ai-profiles";
+import { inferLlmRouteFromModel } from "../observability/llmRouteContext.js";
+import { formatResolvedProfileModelId, isResolvableModelAlias, normalizeXynthesisModelAlias, } from "../utils/aiProfileModelFormat.js";
+import { isConcreteModelId } from "../utils/concreteModelId.js";
+import { formatEngineLabel } from "./formatEngineLabel.js";
+import { parseProfileSlot } from "./parseProfileSlot.js";
+export const INVOCATION_RESOLVER_VERSION = "ai-tasks/8.1.16";
+/** Match `@exellix/xynthesis` `toOpenRouterModelId` wire shape for PRE/POST hops. */
+export function formatXynthesisWireModelId(provider, modelId) {
+    const p = provider.trim();
+    const m = modelId.trim();
+    if (!p || !m)
+        return m;
+    if (p === "custom" || p === "local")
+        return m;
+    return `${p}/${m}`;
+}
+function routingFromConcreteModelId(modelId) {
+    const route = inferLlmRouteFromModel(modelId);
+    return route.adapterHint === "openrouter" ? "openrouter" : "direct";
+}
+function directModelIdFromInvocation(resolved) {
+    const direct = resolved.invocation?.direct;
+    if (direct?.modelId) {
+        const provider = direct.provider ?? resolved.provider;
+        return formatResolvedProfileModelId(String(provider), direct.modelId);
+    }
+    return formatResolvedProfileModelId(resolved.provider, resolved.modelId);
+}
+function openrouterModelIdFromInvocation(resolved) {
+    const or = resolved.invocation?.openrouter;
+    if (or?.modelId) {
+        return or.modelId.includes("/") ? or.modelId : `openrouter/${or.modelId}`;
+    }
+    if (resolved.routing === "openrouter") {
+        return formatResolvedProfileModelId(resolved.provider, resolved.modelId);
+    }
+    return undefined;
+}
+function profileWarnings(resolved) {
+    return (resolved.warnings ?? [])
+        .map((w) => w.message)
+        .filter((m) => typeof m === "string" && m.trim().length > 0);
+}
+/**
+ * Shared profile-slot → routed provider/model resolver used by `resolveModelReference` and
+ * `resolveInvocationPlan`. Calls `@x12i/ai-profiles` `resolveAIProfile` with the same options
+ * `runTask` model resolution uses at execute time.
+ */
+export async function resolveProfileInvocationRouting(profileSlot, options) {
+    const trimmed = profileSlot.trim();
+    if (!trimmed) {
+        throw new Error("Profile slot must be a non-empty string.");
+    }
+    if (isConcreteModelId(trimmed)) {
+        const routing = routingFromConcreteModelId(trimmed);
+        const route = inferLlmRouteFromModel(trimmed);
+        const provider = route.providerPrefix ?? trimmed.split("/")[0] ?? "unknown";
+        return {
+            profileSlot: trimmed,
+            routing,
+            provider,
+            modelId: trimmed,
+            engineLabel: formatEngineLabel(routing, provider),
+            warnings: [],
+            ...(routing === "openrouter"
+                ? { openrouterModelId: trimmed }
+                : { directModelId: trimmed }),
+        };
+    }
+    if (!isResolvableModelAlias(trimmed) && !trimmed.includes("@")) {
+        const routing = routingFromConcreteModelId(trimmed);
+        const provider = trimmed.split("/")[0] ?? "unknown";
+        return {
+            profileSlot: trimmed,
+            routing,
+            provider,
+            modelId: trimmed,
+            engineLabel: formatEngineLabel(routing, provider),
+            warnings: [],
+        };
+    }
+    const { profileInput, choice } = parseProfileSlot(trimmed);
+    const normalizedInput = normalizeXynthesisModelAlias(profileInput);
+    let resolved;
+    try {
+        resolved = await resolveAIProfile(normalizedInput, {
+            choice,
+            source: options.source ?? "bundled",
+            useOpenRouter: options.useOpenRouter,
+        });
+    }
+    catch (err) {
+        if (err instanceof AIProfilesError && err.code === "UNKNOWN_PROFILE") {
+            throw new Error(`Unknown model profile alias "${trimmed}". Use a concrete provider model id or an @x12i/ai-profiles profile/shortcut (e.g. cheap, balanced, pro, default, cheapest).`);
+        }
+        if (err instanceof AIProfilesError && err.code === "UNKNOWN_CHOICE") {
+            throw new Error(`Unknown profile choice in slot "${trimmed}". Use profile@choice only when choice exists in the ai-profiles registry.`);
+        }
+        throw err;
+    }
+    const skillWireModelId = formatResolvedProfileModelId(resolved.provider, resolved.modelId);
+    const xynthesisWireModelId = formatXynthesisWireModelId(resolved.provider, resolved.modelId);
+    const modelId = options.phaseKind === "skill" ? skillWireModelId : xynthesisWireModelId;
+    return {
+        profileSlot: trimmed,
+        routing: resolved.routing,
+        provider: resolved.provider,
+        modelId,
+        engineLabel: formatEngineLabel(resolved.routing, resolved.provider),
+        invocation: resolved.invocation,
+        warnings: profileWarnings(resolved),
+        openrouterModelId: openrouterModelIdFromInvocation(resolved),
+        directModelId: directModelIdFromInvocation(resolved),
+        resolvedProfile: resolved,
+    };
+}
+//# sourceMappingURL=resolveProfileInvocationRouting.js.map

package/dist/invocation/resolveProfileInvocationRouting.js.map

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

package/dist/invocation/types.d.ts

@@ -0,0 +1,64 @@
+import type { ModelInvocation } from "@x12i/ai-profiles";
+/** Same routing enum as `@x12i/ai-profiles` {@link ResolvedAIProfile.routing}. */
+export type InvocationRouting = "openrouter" | "direct";
+export type InvocationPhase = "preAction" | "skill" | "postAction";
+export type InvocationPhasePlan = {
+    phase: InvocationPhase;
+    /** Stored ai-profile slot after graph-engine merge (name or profile@choice). */
+    profileSlot: string;
+    routing: InvocationRouting;
+    /** Logical provider key used by ai-tasks for this call. */
+    provider: string;
+    /** Model id passed to the gateway/client for this routing (OR id or vendor-native id). */
+    modelId: string;
+    /** Short UI label, e.g. "OpenRouter", "Anthropic". */
+    engineLabel: string;
+    /** Full invocation shapes from registry (optional but recommended for studio tooltips). */
+    invocation?: ModelInvocation;
+    warnings?: string[];
+};
+export type ResolveInvocationPlanInput = {
+    /** Required — ai-profile names per phase (already merged by caller). */
+    profiles: {
+        preActionModel: string;
+        skillModel: string;
+        postActionModel: string;
+    };
+    /**
+     * Policy snapshot — must match execute.
+     * Example: USE_OPENROUTER, API keys presence flags, studio Records-run defaults.
+     */
+    policy?: {
+        useOpenRouter?: boolean;
+        openrouterApiKeyPresent?: boolean;
+    };
+    /**
+     * Optional — when plan must reflect a specific node/strategy.
+     * If omitted, ai-tasks returns graph-default plan for the triple only.
+     */
+    runTaskContext?: {
+        skillKey?: string;
+        aiTaskStrategies?: Record<string, unknown>;
+        nodeId?: string;
+    };
+};
+export type ResolveInvocationPlanResult = {
+    phases: InvocationPhasePlan[];
+    /** Plan-level warnings (e.g. OR requested but key missing → fallback). */
+    warnings?: string[];
+    /** Version string for studio to log when debugging drift. */
+    resolverVersion?: string;
+};
+/** Post-run metadata on successful (or pre-provider) LLM-backed `runTask` results. */
+export type RunTaskResultMeta = {
+    provider?: string;
+    model?: string;
+    routing?: InvocationRouting;
+    engineLabel?: string;
+    /** When routing is openrouter, the OR model id actually invoked. */
+    openrouterModelId?: string;
+    /** When routing is direct, vendor-native id. */
+    directModelId?: string;
+    requestId?: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/invocation/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/invocation/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,QAAQ,CAAC;AAExD,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,OAAO,GAAG,YAAY,CAAC;AAEnE,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,eAAe,CAAC;IACvB,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,iBAAiB,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACvC,wEAAwE;IACxE,QAAQ,EAAE;QACR,cAAc,EAAE,MAAM,CAAC;QACvB,UAAU,EAAE,MAAM,CAAC;QACnB,eAAe,EAAE,MAAM,CAAC;KACzB,CAAC;IACF;;;OAGG;IACH,MAAM,CAAC,EAAE;QACP,aAAa,CAAC,EAAE,OAAO,CAAC;QACxB,uBAAuB,CAAC,EAAE,OAAO,CAAC;KACnC,CAAC;IACF;;;OAGG;IACH,cAAc,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,sFAAsF;AACtF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC"}

package/dist/invocation/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/invocation/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/invocation/types.ts"],"names":[],"mappings":""}

package/dist/logxer/aiTasksDiagnosticCodes.d.ts

@@ -7,6 +7,7 @@ export declare const AI_TASKS_DIAGNOSTIC_CODES: {
     readonly RUN_TASK_OBSERVABILITY_HINT: "RUN_TASK_OBSERVABILITY_HINT";
     readonly EXECUTION_STRATEGIES_MULTIPLE_OPTIMIZERS: "EXECUTION_STRATEGIES_MULTIPLE_OPTIMIZERS";
     readonly NARRIX_WEB_SCOPE_MISS: "NARRIX_WEB_SCOPE_MISS";
+    readonly RUN_TASK_EXECUTION_FAILED: "RUN_TASK_EXECUTION_FAILED";
 };
 export type AiTasksDiagnosticCode = (typeof AI_TASKS_DIAGNOSTIC_CODES)[keyof typeof AI_TASKS_DIAGNOSTIC_CODES];
 //# sourceMappingURL=aiTasksDiagnosticCodes.d.ts.map

package/dist/logxer/aiTasksDiagnosticCodes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aiTasksDiagnosticCodes.d.ts","sourceRoot":"","sources":["../../src/logxer/aiTasksDiagnosticCodes.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,eAAO,MAAM,yBAAyB;;;;;;;;CAQ5B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAC/B,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,OAAO,yBAAyB,CAAC,CAAC"}
+{"version":3,"file":"aiTasksDiagnosticCodes.d.ts","sourceRoot":"","sources":["../../src/logxer/aiTasksDiagnosticCodes.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,eAAO,MAAM,yBAAyB;;;;;;;;;CAS5B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAC/B,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,OAAO,yBAAyB,CAAC,CAAC"}

package/dist/logxer/aiTasksDiagnosticCodes.js

@@ -7,5 +7,6 @@ export const AI_TASKS_DIAGNOSTIC_CODES = {
     RUN_TASK_OBSERVABILITY_HINT: "RUN_TASK_OBSERVABILITY_HINT",
     EXECUTION_STRATEGIES_MULTIPLE_OPTIMIZERS: "EXECUTION_STRATEGIES_MULTIPLE_OPTIMIZERS",
     NARRIX_WEB_SCOPE_MISS: "NARRIX_WEB_SCOPE_MISS",
+    RUN_TASK_EXECUTION_FAILED: "RUN_TASK_EXECUTION_FAILED",
 };
 //# sourceMappingURL=aiTasksDiagnosticCodes.js.map

package/dist/logxer/aiTasksDiagnosticCodes.js.map

@@ -1 +1 @@
-{"version":3,"file":"aiTasksDiagnosticCodes.js","sourceRoot":"","sources":["../../src/logxer/aiTasksDiagnosticCodes.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,wCAAwC,EAAE,0CAA0C;IACpF,qCAAqC,EAAE,uCAAuC;IAC9E,kCAAkC,EAAE,oCAAoC;IACxE,mCAAmC,EAAE,qCAAqC;IAC1E,2BAA2B,EAAE,6BAA6B;IAC1D,wCAAwC,EAAE,0CAA0C;IACpF,qBAAqB,EAAE,uBAAuB;CACtC,CAAC"}
+{"version":3,"file":"aiTasksDiagnosticCodes.js","sourceRoot":"","sources":["../../src/logxer/aiTasksDiagnosticCodes.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,wCAAwC,EAAE,0CAA0C;IACpF,qCAAqC,EAAE,uCAAuC;IAC9E,kCAAkC,EAAE,oCAAoC;IACxE,mCAAmC,EAAE,qCAAqC;IAC1E,2BAA2B,EAAE,6BAA6B;IAC1D,wCAAwC,EAAE,0CAA0C;IACpF,qBAAqB,EAAE,uBAAuB;IAC9C,yBAAyB,EAAE,2BAA2B;CAC9C,CAAC"}

package/dist/observability/classifyRunTaskFailure.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Best-effort classification of runTask failures for operators and downstream hosts.
+ * Distinguishes likely root causes from wrapper/surface symptoms and names the event.
+ */
+export type FailureRole = "cause" | "symptom" | "unknown";
+/** Stable machine-readable failure event ids for filtering and dashboards. */
+export type FailureEvent = "graph_engine_task_run_wrapper" | "provider_auth" | "provider_quota_rate_limit" | "provider_routing" | "provider_invoke" | "content_registry_miss" | "prompt_template_empty" | "request_validation" | "task_configuration_compile" | "smart_input_validation" | "output_schema_validation" | "structured_output_parse" | "narrix_failure" | "synthesis_failure" | "missing_parsed_output" | "decision_output_missing" | "model_config" | "timeout" | "unknown";
+export type FailureClassification = {
+    /** Whether this message is likely the root cause or a downstream wrapper/surface signal. */
+    role: FailureRole;
+    /** Primary event this log line describes. */
+    event: FailureEvent;
+    /**
+     * When `role` is `symptom`, where to look next (event ids or free-text operator hint).
+     * Omitted when the line itself is the cause or classification is uncertain.
+     */
+    pointsTo?: FailureEvent[] | string;
+    /** Short operator-facing explanation of role + where to look. */
+    note: string;
+    confidence: "high" | "medium" | "low";
+};
+export type ClassifyRunTaskFailureInput = {
+    message: string;
+    code?: string;
+    name?: string;
+    phase?: string;
+    stage?: string;
+    durationMs?: number;
+};
+/** Classify a failure from message/code/name heuristics (no LLM invoke required). */
+export declare function classifyRunTaskFailure(input: ClassifyRunTaskFailureInput): FailureClassification;
+export declare function formatFailureClassificationHint(c: FailureClassification): string;
+//# sourceMappingURL=classifyRunTaskFailure.d.ts.map

package/dist/observability/classifyRunTaskFailure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifyRunTaskFailure.d.ts","sourceRoot":"","sources":["../../src/observability/classifyRunTaskFailure.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1D,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GACpB,+BAA+B,GAC/B,eAAe,GACf,2BAA2B,GAC3B,kBAAkB,GAClB,iBAAiB,GACjB,uBAAuB,GACvB,uBAAuB,GACvB,oBAAoB,GACpB,4BAA4B,GAC5B,wBAAwB,GACxB,0BAA0B,GAC1B,yBAAyB,GACzB,gBAAgB,GAChB,mBAAmB,GACnB,uBAAuB,GACvB,yBAAyB,GACzB,cAAc,GACd,SAAS,GACT,SAAS,CAAC;AAEd,MAAM,MAAM,qBAAqB,GAAG;IAClC,4FAA4F;IAC5F,IAAI,EAAE,WAAW,CAAC;IAClB,6CAA6C;IAC7C,KAAK,EAAE,YAAY,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC;IACnC,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAgCF,qFAAqF;AACrF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,qBAAqB,CAiLhG;AAED,wBAAgB,+BAA+B,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAahF"}

package/dist/observability/classifyRunTaskFailure.js

@@ -0,0 +1,111 @@
+/**
+ * Best-effort classification of runTask failures for operators and downstream hosts.
+ * Distinguishes likely root causes from wrapper/surface symptoms and names the event.
+ */
+function msgLower(input) {
+    return input.message.toLowerCase();
+}
+function symptom(event, pointsTo, note, confidence = "high") {
+    return { role: "symptom", event, pointsTo, note, confidence };
+}
+function cause(event, note, confidence = "high") {
+    return { role: "cause", event, note, confidence };
+}
+function unknown(note) {
+    return {
+        role: "unknown",
+        event: "unknown",
+        note,
+        confidence: "low",
+    };
+}
+/** Classify a failure from message/code/name heuristics (no LLM invoke required). */
+export function classifyRunTaskFailure(input) {
+    const m = msgLower(input);
+    const code = input.code?.toUpperCase() ?? "";
+    const name = input.name ?? "";
+    // Graph-engine / host wrappers — surface symptom only.
+    if (/^task_run_failed:/i.test(input.message.trim()) || code === "TASK_RUN_FAILED") {
+        return symptom("graph_engine_task_run_wrapper", [
+            "provider_auth",
+            "provider_quota_rate_limit",
+            "content_registry_miss",
+            "prompt_template_empty",
+            "provider_invoke",
+            "synthesis_failure",
+        ], "Graph-engine TASK_RUN_FAILED is a wrapper; inspect taskRunLog, res.error.message, ai-tasks RUN_TASK_EXECUTION_FAILED logs, or skill-execution records for the root cause.", "high");
+    }
+    if (name === "SmartInputValidationError" || code.startsWith("SMART_INPUT") || /smartinput/i.test(m)) {
+        return cause("smart_input_validation", "Invalid smartInput shape or unsupported xynthesized scope on the RunTaskRequest.", "high");
+    }
+    if (name === "TaskConfigurationCompileError" || /taskconfiguration/i.test(m)) {
+        return cause("task_configuration_compile", "taskConfiguration could not compile into a valid executionPipeline / request shape.", "high");
+    }
+    if (code === "PROMPT_RENDERED_EMPTY" ||
+        /prompt template.*rendered to empty string/i.test(m)) {
+        return cause("prompt_template_empty", "Prompt template resolved to empty text — check input bindings and template variables (e.g. input.question).", "high");
+    }
+    if (/content not found for key/i.test(m) ||
+        /failed to resolve instruction key/i.test(m) ||
+        /failed to resolve prompt key/i.test(m)) {
+        return cause("content_registry_miss", "Skill instructions/prompt could not be resolved from the content registry (.metadata / Catalox).", "high");
+    }
+    if (/agentid|jobtypeid|tasktypeid/i.test(m) &&
+        (/required|missing|non-empty|blank/i.test(m) || /must include/i.test(m))) {
+        return cause("request_validation", "Required RunTaskRequest correlation ids (agentId, jobTypeId, taskTypeId) are missing or blank.", "high");
+    }
+    if (/401|403|unauthorized|invalid api key|incorrect api key|authentication/i.test(m) ||
+        /api key.*(missing|not set|required)/i.test(m)) {
+        return cause("provider_auth", "Provider authentication failed — verify API keys for the resolved adapter (see adapterHint / likelyEnvKeys).", "high");
+    }
+    if (/rate limit|quota|429|too many requests/i.test(m)) {
+        return cause("provider_quota_rate_limit", "Provider quota or rate limit exceeded for the resolved model route.", "high");
+    }
+    if (/timeout|timed out|ETIMEDOUT|ESOCKETTIMEDOUT/i.test(m)) {
+        return cause("timeout", "Call exceeded timeoutMs — may be slow provider, network, or an oversized prompt/context.", "medium");
+    }
+    if (/unknown model profile alias|model_config|xynthesis_concrete_not_allowed/i.test(m)) {
+        return cause("model_config", "Model slot resolution failed — check modelConfig.skillModel / xynthesisModel aliases and graph-engine pre-resolution.", "high");
+    }
+    if (/narrix/i.test(m) && /fail|error|invalid|disabled/i.test(m)) {
+        return cause("narrix_failure", "Narrix preprocessor or handler returned an error — inspect narrixInput, seed archive, and USE_NARRIX_INGEST.", "high");
+    }
+    if (/synthesized-context|synthesis|xynthesis/i.test(m) &&
+        /fail|error|invoke/i.test(m)) {
+        return cause("synthesis_failure", "PRE/POST xynthesis call failed — check xynthesisModel, synthesis templates, and xynthesis provider env.", "medium");
+    }
+    if (/outputvalidation failed/i.test(m)) {
+        return symptom("output_schema_validation", "structured_output_parse", "Output failed JSON/schema validation after the model returned — inspect raw model output and outputValidation schema; root may be provider quality or schema mismatch.", "medium");
+    }
+    if (/did not return response\.parsed/i.test(m)) {
+        return symptom("decision_output_missing", "structured_output_parse", "Decision/routing task returned no parsed payload — inspect gateway parse mode and model structured-output compliance.", "high");
+    }
+    if (/no parsed output|parsed is empty|missing parsed/i.test(m)) {
+        return symptom("missing_parsed_output", ["provider_invoke", "structured_output_parse", "prompt_template_empty"], "No parsed skill output — often a symptom of an earlier provider/template failure or non-JSON model response.", "medium");
+    }
+    // Fast MAIN failures — only when no more specific cause matched above.
+    if (input.durationMs != null &&
+        input.durationMs < 2_000 &&
+        (input.stage === "main-skill" || input.phase === "main_skill")) {
+        return cause("provider_invoke", "Fast MAIN/provider failure — likely auth, routing, content resolution, or prompt build before a successful model round-trip.", "medium");
+    }
+    if (/provider|routing|gateway|invoke/i.test(m)) {
+        return cause("provider_invoke", "Provider or gateway invocation failed for the resolved model route.", "medium");
+    }
+    return unknown("Could not classify this failure automatically — use executionMode:trace, skill-execution records, and rootMessage/rootCode.");
+}
+export function formatFailureClassificationHint(c) {
+    if (c.role === "cause") {
+        return `[cause:${c.event}] ${c.note}`;
+    }
+    if (c.role === "symptom") {
+        const target = Array.isArray(c.pointsTo)
+            ? c.pointsTo.join(",")
+            : typeof c.pointsTo === "string"
+                ? c.pointsTo
+                : "upstream logs";
+        return `[symptom:${c.event}→check:${target}] ${c.note}`;
+    }
+    return `[unknown:${c.event}] ${c.note}`;
+}
+//# sourceMappingURL=classifyRunTaskFailure.js.map

package/dist/observability/classifyRunTaskFailure.js.map

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

package/dist/observability/llmRouteContext.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Infer intended provider adapter from a resolved model id on the ai-tasks wire.
+ * Gateway may still reroute internally; this is the best pre-invoke signal for logs.
+ */
+export type LlmAdapterHint = "openrouter" | "openai-direct" | "anthropic-direct" | "google-direct" | "groq-direct" | "unknown" | "unset";
+export type LlmRouteContext = {
+    /** Raw model string from modelConfig / llmCall (post alias resolution when applicable). */
+    rawModel?: string;
+    /** First path segment when model contains `/` (e.g. `openai`, `openrouter`, `x-ai`). */
+    providerPrefix?: string;
+    /** Remainder after provider prefix. */
+    modelId?: string;
+    /** Best-effort adapter the gateway stack is expected to use for this prefix. */
+    adapterHint: LlmAdapterHint;
+    /** Env vars commonly required for the inferred adapter (for operator hints). */
+    likelyEnvKeys: string[];
+    /** Short human-readable routing summary for log lines and error messages. */
+    routingNote: string;
+    /** When upstream returned routing diagnostics (trace mode / gateway echo). */
+    actualRouting?: Record<string, unknown>;
+};
+/** Parse a concrete or alias-like model id into log-friendly route context. */
+export declare function inferLlmRouteFromModel(rawModel: string | undefined | null): LlmRouteContext;
+/** Merge gateway routing echo (when present) into route context. */
+export declare function withActualRouting(base: LlmRouteContext, actualRouting: unknown): LlmRouteContext;
+//# sourceMappingURL=llmRouteContext.d.ts.map

package/dist/observability/llmRouteContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llmRouteContext.d.ts","sourceRoot":"","sources":["../../src/observability/llmRouteContext.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,YAAY,GACZ,eAAe,GACf,kBAAkB,GAClB,eAAe,GACf,aAAa,GACb,SAAS,GACT,OAAO,CAAC;AAEZ,MAAM,MAAM,eAAe,GAAG;IAC5B,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wFAAwF;IACxF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,WAAW,EAAE,cAAc,CAAC;IAC5B,gFAAgF;IAChF,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC,CAAC;AAyCF,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,eAAe,CA0C3F;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,eAAe,EACrB,aAAa,EAAE,OAAO,GACrB,eAAe,CAejB"}

package/dist/observability/llmRouteContext.js

@@ -0,0 +1,92 @@
+const ADAPTER_ENV = {
+    openrouter: ["OPEN_ROUTER_KEY", "OPENROUTER_API_KEY"],
+    "openai-direct": ["OPENAI_API_KEY"],
+    "anthropic-direct": ["ANTHROPIC_API_KEY"],
+    "google-direct": ["GOOGLE_API_KEY", "GEMINI_API_KEY"],
+    "groq-direct": ["GROQ_API_KEY"],
+    unknown: [],
+    unset: [],
+};
+function adapterForPrefix(prefix) {
+    const p = prefix.toLowerCase();
+    if (p === "openrouter")
+        return "openrouter";
+    if (p === "openai")
+        return "openai-direct";
+    if (p === "anthropic")
+        return "anthropic-direct";
+    if (p === "google")
+        return "google-direct";
+    if (p === "groq")
+        return "groq-direct";
+    return "unknown";
+}
+function formatRoutingNote(args) {
+    if (!args.rawModel?.trim()) {
+        return "no model configured on this call (gateway/provider defaults may apply)";
+    }
+    const target = args.providerPrefix && args.modelId
+        ? `${args.providerPrefix}/${args.modelId}`
+        : args.rawModel;
+    const env = args.likelyEnvKeys.length > 0 ? `; check env: ${args.likelyEnvKeys.join(" or ")}` : "";
+    return `intended adapter=${args.adapterHint} model=${target}${env}`;
+}
+/** Parse a concrete or alias-like model id into log-friendly route context. */
+export function inferLlmRouteFromModel(rawModel) {
+    const raw = typeof rawModel === "string" ? rawModel.trim() : "";
+    if (!raw) {
+        return {
+            adapterHint: "unset",
+            likelyEnvKeys: [],
+            routingNote: formatRoutingNote({ adapterHint: "unset", likelyEnvKeys: [] }),
+        };
+    }
+    const slash = raw.indexOf("/");
+    if (slash > 0) {
+        const providerPrefix = raw.slice(0, slash);
+        const modelId = raw.slice(slash + 1);
+        const adapterHint = adapterForPrefix(providerPrefix);
+        const likelyEnvKeys = ADAPTER_ENV[adapterHint];
+        return {
+            rawModel: raw,
+            providerPrefix,
+            modelId,
+            adapterHint,
+            likelyEnvKeys,
+            routingNote: formatRoutingNote({
+                rawModel: raw,
+                adapterHint,
+                providerPrefix,
+                modelId,
+                likelyEnvKeys,
+            }),
+        };
+    }
+    return {
+        rawModel: raw,
+        adapterHint: "unknown",
+        likelyEnvKeys: [],
+        routingNote: formatRoutingNote({
+            rawModel: raw,
+            adapterHint: "unknown",
+            likelyEnvKeys: [],
+        }),
+    };
+}
+/** Merge gateway routing echo (when present) into route context. */
+export function withActualRouting(base, actualRouting) {
+    if (actualRouting == null || typeof actualRouting !== "object" || Array.isArray(actualRouting)) {
+        return base;
+    }
+    const r = actualRouting;
+    const provider = typeof r.provider === "string" && r.provider.trim() ? r.provider.trim() : undefined;
+    const note = provider
+        ? `${base.routingNote}; gateway routing.provider=${provider}`
+        : base.routingNote;
+    return {
+        ...base,
+        actualRouting: r,
+        routingNote: note,
+    };
+}
+//# sourceMappingURL=llmRouteContext.js.map

package/dist/observability/llmRouteContext.js.map

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

package/dist/observability/logRunTaskFailure.d.ts

@@ -0,0 +1,10 @@
+import { type EnrichRunTaskErrorContext } from "../errors/runTaskExecutionError.js";
+export type LogRunTaskFailureArgs = EnrichRunTaskErrorContext & {
+    cause: unknown;
+};
+/**
+ * Emit a structured diagnostic log for a failed `runTask` and return an enriched error
+ * suitable for graph-engine / RealTasksClient to surface as `error.message`.
+ */
+export declare function logAndEnrichRunTaskFailure(args: LogRunTaskFailureArgs): Error;
+//# sourceMappingURL=logRunTaskFailure.d.ts.map

package/dist/observability/logRunTaskFailure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logRunTaskFailure.d.ts","sourceRoot":"","sources":["../../src/observability/logRunTaskFailure.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,oCAAoC,CAAC;AAO5C,MAAM,MAAM,qBAAqB,GAAG,yBAAyB,GAAG;IAC9D,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAaF;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,qBAAqB,GAAG,KAAK,CA8E7E"}

package/dist/observability/logRunTaskFailure.js

@@ -0,0 +1,87 @@
+import { DebugLogAbstract, fieldEvidence } from "@x12i/logxer";
+import { classifyRunTaskFailure, formatFailureClassificationHint, } from "./classifyRunTaskFailure.js";
+import { enrichRunTaskError, isRunTaskExecutionError, } from "../errors/runTaskExecutionError.js";
+import { isSmartInputValidationError } from "../errors/smartInputValidationError.js";
+import { isTaskConfigurationCompileError } from "../errors/taskConfigurationCompileError.js";
+import { AI_TASKS_DIAGNOSTIC_CODES } from "../logxer/aiTasksDiagnosticCodes.js";
+import { getAiTasksLogxer } from "../logxer/packageLogxers.js";
+import { inferLlmRouteFromModel } from "./llmRouteContext.js";
+function rootMessageFromError(error) {
+    return {
+        message: error.message,
+        name: error.name,
+        code: typeof error.code === "string"
+            ? error.code
+            : undefined,
+    };
+}
+/**
+ * Emit a structured diagnostic log for a failed `runTask` and return an enriched error
+ * suitable for graph-engine / RealTasksClient to surface as `error.message`.
+ */
+export function logAndEnrichRunTaskFailure(args) {
+    const enriched = enrichRunTaskError(args.cause, args);
+    const details = isRunTaskExecutionError(enriched) ? enriched.details : undefined;
+    const root = details?.rootError ??
+        (args.cause instanceof Error ? rootMessageFromError(args.cause) : { name: "Error", message: String(args.cause) });
+    const route = details?.llmRoute ??
+        inferLlmRouteFromModel(details?.modelConfig?.skillModel ??
+            args.modelConfig?.skillModel);
+    const failureClassification = details?.failureClassification ??
+        classifyRunTaskFailure({
+            message: root.message,
+            code: root.code,
+            name: root.name,
+            phase: details?.phase ?? args.phase,
+            stage: details?.stage ?? args.stage,
+            durationMs: args.durationMs ?? details?.durationMs,
+        });
+    const evidence = [
+        fieldEvidence("skillKey", args.skillKey),
+        fieldEvidence("phase", details?.phase ?? args.phase ?? "unknown"),
+        fieldEvidence("failureRole", failureClassification.role),
+        fieldEvidence("failureEvent", failureClassification.event),
+        fieldEvidence("failureConfidence", failureClassification.confidence),
+        ...(failureClassification.pointsTo
+            ? [
+                fieldEvidence("failurePointsTo", Array.isArray(failureClassification.pointsTo)
+                    ? failureClassification.pointsTo.join(",")
+                    : failureClassification.pointsTo),
+            ]
+            : []),
+        fieldEvidence("failureNote", failureClassification.note),
+        ...(args.stage || details?.stage
+            ? [fieldEvidence("stage", details?.stage ?? args.stage)]
+            : []),
+        ...(args.nodeId ? [fieldEvidence("nodeId", args.nodeId)] : []),
+        ...(args.graphId ? [fieldEvidence("graphId", args.graphId)] : []),
+        ...(args.jobId ? [fieldEvidence("jobId", args.jobId)] : []),
+        ...(args.taskId ? [fieldEvidence("taskId", args.taskId)] : []),
+        ...(route.rawModel ? [fieldEvidence("model", route.rawModel)] : []),
+        ...(route.adapterHint !== "unset"
+            ? [fieldEvidence("adapterHint", route.adapterHint)]
+            : []),
+        ...(route.routingNote ? [fieldEvidence("routingNote", route.routingNote)] : []),
+        ...(route.likelyEnvKeys.length
+            ? [fieldEvidence("likelyEnvKeys", route.likelyEnvKeys.join(", "))]
+            : []),
+        ...(root.message ? [fieldEvidence("rootMessage", root.message)] : []),
+        ...(root.code ? [fieldEvidence("rootCode", root.code)] : []),
+        ...(root.name ? [fieldEvidence("rootErrorName", root.name)] : []),
+        ...(args.durationMs != null ? [fieldEvidence("durationMs", args.durationMs)] : []),
+    ];
+    const summary = isRunTaskExecutionError(enriched)
+        ? enriched.message
+        : `${root.message} ${formatFailureClassificationHint(failureClassification)}`.trim();
+    getAiTasksLogxer().errorCode(AI_TASKS_DIAGNOSTIC_CODES.RUN_TASK_EXECUTION_FAILED, {
+        source: "@exellix/ai-tasks",
+        debugKind: DebugLogAbstract.TRACE,
+        diagnostics: { summary },
+        evidence,
+    });
+    if (isSmartInputValidationError(enriched) || isTaskConfigurationCompileError(enriched)) {
+        return enriched;
+    }
+    return enriched;
+}
+//# sourceMappingURL=logRunTaskFailure.js.map